@fluid-app/fluid-cli-theme-dev 0.1.48 → 0.1.49

package/dist/index.mjs

@@ -6,9 +6,9 @@ import { createHash, randomBytes } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import chokidar from "chokidar";
+import net from "node:net";
 import { execFileSync, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
-import net from "node:net";
 import chalk from "chalk";
 import prompts from "prompts";
 import ora from "ora";
@@ -1455,6 +1455,28 @@ function watchTheme(root, handler) {
 	return () => watcher.close();
 }
 //#endregion
+//#region src/theme/case-collisions.ts
+var CaseCollisionError = class extends Error {
+	constructor(collisions) {
+		super(`Theme contains paths that differ only by letter case and cannot be synchronized safely:\n${collisions.map((paths) => `  ${paths.join(", ")}`).join("\n")}`);
+		this.collisions = collisions;
+		this.name = "CaseCollisionError";
+	}
+};
+/** Refuse paths a case-insensitive checkout cannot represent independently. */
+function assertNoCaseCollisions(paths) {
+	const pathsByFoldedKey = /* @__PURE__ */ new Map();
+	for (const rawPath of paths) {
+		const path = normalizeThemeResourceKey(rawPath);
+		const foldedKey = path.toLowerCase();
+		const matchingPaths = pathsByFoldedKey.get(foldedKey) ?? /* @__PURE__ */ new Set();
+		matchingPaths.add(path);
+		pathsByFoldedKey.set(foldedKey, matchingPaths);
+	}
+	const collisions = [...pathsByFoldedKey.values()].filter((matchingPaths) => matchingPaths.size > 1).map((matchingPaths) => [...matchingPaths].sort()).sort(([left = ""], [right = ""]) => left.localeCompare(right));
+	if (collisions.length > 0) throw new CaseCollisionError(collisions);
+}
+//#endregion
 //#region src/theme/asset-manifest.ts
 const MANIFEST_FILE = ".fluid-assets.json";
 const MANIFEST_VERSION = 1;
@@ -1534,16 +1556,16 @@ var ThemeAssetManifest = class {
 function readDocument(path) {
 	if (!existsSync(path)) return emptyDocument();
 	try {
-		return parseDocument(JSON.parse(readFileSync(path, "utf-8")));
+		return parseDocument$1(JSON.parse(readFileSync(path, "utf-8")));
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Could not read ${MANIFEST_FILE}: ${message}`);
 	}
 }
-function parseDocument(value) {
-	if (!isRecord$1(value) || value["version"] !== MANIFEST_VERSION) throw new Error(`expected version ${MANIFEST_VERSION}`);
+function parseDocument$1(value) {
+	if (!isRecord$2(value) || value["version"] !== MANIFEST_VERSION) throw new Error(`expected version ${MANIFEST_VERSION}`);
 	const rawAssets = value["assets"];
-	if (!isRecord$1(rawAssets)) throw new Error("expected an assets object");
+	if (!isRecord$2(rawAssets)) throw new Error("expected an assets object");
 	const assets = {};
 	for (const [key, rawLink] of Object.entries(rawAssets)) {
 		if (!isThemeAssetKey(key) || !isThemeAssetLink(rawLink)) throw new Error(`invalid asset entry for ${key}`);
@@ -1578,14 +1600,14 @@ function copyLink(link) {
 	};
 }
 function isThemeAssetLink(value) {
-	return isRecord$1(value) && typeof value["sourceThemeId"] === "number" && Number.isInteger(value["sourceThemeId"]) && value["sourceThemeId"] > 0 && (value["checksum"] === void 0 || typeof value["checksum"] === "string" && value["checksum"].length > 0) && (value["url"] === void 0 || typeof value["url"] === "string" && value["url"].length > 0) && (value["contentType"] === void 0 || typeof value["contentType"] === "string" && value["contentType"].length > 0) && (value["contentSize"] === void 0 || typeof value["contentSize"] === "number" && Number.isInteger(value["contentSize"]) && value["contentSize"] > 0) && (value["previewImageUrl"] === void 0 || typeof value["previewImageUrl"] === "string" && value["previewImageUrl"].length > 0) && (value["altText"] === void 0 || typeof value["altText"] === "string") && (value["handle"] === void 0 || typeof value["handle"] === "string" && value["handle"].length > 0) && (value["pending"] === void 0 || typeof value["pending"] === "boolean") && (value["damAssetCode"] === void 0 || typeof value["damAssetCode"] === "string" && value["damAssetCode"].length > 0);
+	return isRecord$2(value) && typeof value["sourceThemeId"] === "number" && Number.isInteger(value["sourceThemeId"]) && value["sourceThemeId"] > 0 && (value["checksum"] === void 0 || typeof value["checksum"] === "string" && value["checksum"].length > 0) && (value["url"] === void 0 || typeof value["url"] === "string" && value["url"].length > 0) && (value["contentType"] === void 0 || typeof value["contentType"] === "string" && value["contentType"].length > 0) && (value["contentSize"] === void 0 || typeof value["contentSize"] === "number" && Number.isInteger(value["contentSize"]) && value["contentSize"] > 0) && (value["previewImageUrl"] === void 0 || typeof value["previewImageUrl"] === "string" && value["previewImageUrl"].length > 0) && (value["altText"] === void 0 || typeof value["altText"] === "string") && (value["handle"] === void 0 || typeof value["handle"] === "string" && value["handle"].length > 0) && (value["pending"] === void 0 || typeof value["pending"] === "boolean") && (value["damAssetCode"] === void 0 || typeof value["damAssetCode"] === "string" && value["damAssetCode"].length > 0);
 }
 function isThemeAssetKey(key) {
 	if (key.includes("\\") || key.includes("\0")) return false;
 	const segments = key.split("/");
 	return segments[0] === "assets" && segments.length === 2 && segments[1] !== void 0 && segments[1].length > 0 && segments[1] !== "." && segments[1] !== "..";
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
@@ -1619,6 +1641,7 @@ var Syncer = class {
 	remoteResourceGroups = /* @__PURE__ */ new Map();
 	remoteResourceIndex = /* @__PURE__ */ new Map();
 	remoteIndexesDirty = false;
+	remoteResourcesLoaded = false;
 	lastKnownRemoteSha = null;
 	assetManifestInstance;
 	constructor(api, themeId, themeRoot, assetManifest) {
@@ -1635,6 +1658,7 @@ var Syncer = class {
 		const body = await listThemeResources(this.api, this.themeId);
 		this.updateChecksums(body.application_theme_resources ?? []);
 		this.lastKnownRemoteSha = body.content_version_sha ?? null;
+		this.remoteResourcesLoaded = true;
 	}
 	/**
 	* Server's `content_version_sha` captured on the last `fetchChecksums()`
@@ -1644,6 +1668,7 @@ var Syncer = class {
 		return this.lastKnownRemoteSha;
 	}
 	updateChecksums(resources) {
+		assertNoCaseCollisions(resources.flatMap((resource) => resource.key ? [resource.key] : []));
 		this.rawRemoteResources.clear();
 		this.remoteResourceGroups.clear();
 		for (const resource of resources) {
@@ -1690,6 +1715,11 @@ var Syncer = class {
 	remoteKeys() {
 		return [...this.remoteResources.keys()];
 	}
+	/** A null-content resource has no possible working-tree counterpart. */
+	canDeleteRemoteResource(key) {
+		const resource = this.remoteResources.get(key);
+		return resource?.content != null || isManagedAssetResource(resource);
+	}
 	/** Snapshot of remote checksums (key → sha256). Available after fetchChecksums() or downloadAll(). */
 	remoteChecksums() {
 		return Object.fromEntries(this.checksums);
@@ -1704,13 +1734,32 @@ var Syncer = class {
 		}
 		return urls;
 	}
+	/** Compact, complete resource state paired with its acknowledged dev SHA. */
+	devRemoteState(assetManifestSha) {
+		if (!this.remoteResourcesLoaded || !this.lastKnownRemoteSha) return null;
+		return {
+			themeId: this.themeId,
+			remoteSha: this.lastKnownRemoteSha,
+			assetManifestSha,
+			resources: [...this.remoteResourceGroups.values()].flat().map(remoteResourceState)
+		};
+	}
+	useDevRemoteState(state) {
+		if (state.themeId !== this.themeId) throw new Error(`Dev remote state belongs to theme #${state.themeId}, not #${this.themeId}`);
+		this.updateChecksums(state.resources.map(remoteResourceFromState));
+		this.lastKnownRemoteSha = state.remoteSha;
+		this.remoteResourcesLoaded = true;
+	}
+	async ensureRemoteResourcesLoaded() {
+		if (!this.remoteResourcesLoaded) await this.fetchChecksums();
+	}
 	/**
 	* Adds URL-backed FileResources for manifest assets without transferring
 	* their bytes. The target stores the source asset's ImageKit URL.
 	*/
 	async linkManagedAssets(opts = {}) {
 		this.assetManifest.reload();
-		await this.fetchChecksums();
+		await this.ensureRemoteResourcesLoaded();
 		const plans = [];
 		for (const [key, link] of this.assetManifest.entries()) {
 			if (this.themeRoot.ignore.ignore(key)) continue;
@@ -1770,7 +1819,7 @@ var Syncer = class {
 	}
 	async fetchThemeAssetMetadata(sourceThemeId) {
 		const body = await getThemeAssets(this.api, sourceThemeId);
-		if (!isRecord(body) || !Array.isArray(body["file_resources"])) throw new Error("Theme assets response did not include file_resources");
+		if (!isRecord$1(body) || !Array.isArray(body["file_resources"])) throw new Error("Theme assets response did not include file_resources");
 		const assets = /* @__PURE__ */ new Map();
 		for (const value of body["file_resources"]) {
 			const asset = parseThemeAssetMetadata(value);
@@ -1925,7 +1974,12 @@ var Syncer = class {
 				key: file.relativePath,
 				content
 			}, baseSha);
-			this.setRemoteResource(resource);
+			this.setRemoteResource({
+				...resource,
+				key: file.relativePath,
+				content,
+				checksum: resource.checksum ?? file.checksum()
+			});
 			return content;
 		}
 		if (isNestedBinaryThemeAsset(file)) throw new Error(`Binary assets must be directly inside assets/: ${file.relativePath}`);
@@ -2135,6 +2189,7 @@ var Syncer = class {
 		const resources = body.application_theme_resources ?? [];
 		this.updateChecksums(resources);
 		this.lastKnownRemoteSha = body.content_version_sha ?? null;
+		this.remoteResourcesLoaded = true;
 		return resources;
 	}
 	async downloadBinaryAsset(url) {
@@ -2269,6 +2324,7 @@ var Syncer = class {
 	}
 	async uploadTheme(opts = {}) {
 		const localFiles = this.themeRoot.files();
+		assertNoCaseCollisions(localFiles.map((file) => file.relativePath));
 		const result = {
 			uploaded: 0,
 			deleted: 0,
@@ -2288,7 +2344,8 @@ var Syncer = class {
 				return result;
 			}
 		}
-		if (!opts.diff) await this.fetchChecksums();
+		if (opts.remoteState) this.useDevRemoteState(opts.remoteState);
+		else await this.fetchChecksums();
 		if (!opts.skipPreflight) await this.preflightPush(opts.baseSha);
 		let baseSha = opts.baseSha ?? null;
 		if (opts.linkManagedAssets) {
@@ -2298,7 +2355,7 @@ var Syncer = class {
 			this.assetManifest.reload();
 			this.ensureManagedAssetsAreResolved();
 		}
-		const toUpload = opts.diff?.changed ?? localFiles.filter((f) => f.exists && this.hasChanged(f));
+		const toUpload = localFiles.filter((f) => f.exists && this.hasChanged(f));
 		let done = 0;
 		for (const file of toUpload) {
 			try {
@@ -2312,11 +2369,9 @@ var Syncer = class {
 			opts.onProgress?.(++done, toUpload.length);
 		}
 		if (opts.delete) {
-			const toDelete = opts.diff?.deleted ?? (() => {
-				const localPaths = new Set(localFiles.map((f) => f.relativePath));
-				for (const key of this.assetManifest.keys()) localPaths.add(key);
-				return this.remoteKeys().filter((key) => !localPaths.has(key) && !this.themeRoot.ignore.ignore(key));
-			})();
+			const localPaths = new Set(localFiles.map((f) => f.relativePath));
+			for (const key of this.assetManifest.keys()) localPaths.add(key);
+			const toDelete = this.remoteKeys().filter((key) => this.canDeleteRemoteResource(key) && !localPaths.has(key) && !this.themeRoot.ignore.ignore(key));
 			for (const key of toDelete) try {
 				await this.deleteRemoteFile(key, baseSha);
 				baseSha = this.lastKnownRemoteSha;
@@ -2394,6 +2449,26 @@ function isNestedBinaryThemeAsset(file) {
 function isManagedAssetResource(resource) {
 	return resource?.resource_type === "FileResource" && typeof resource.url === "string" && resource.url.length > 0;
 }
+function remoteResourceFromState(state) {
+	return {
+		key: state.key,
+		checksum: state.checksum,
+		content: state.contentPresent ? "" : null,
+		resource_type: state.resourceType,
+		resource_id: state.resourceId,
+		url: state.url
+	};
+}
+function remoteResourceState(resource) {
+	return {
+		key: resource.key,
+		checksum: resource.checksum,
+		contentPresent: resource.content != null,
+		resourceType: resource.resource_type,
+		resourceId: resource.resource_id,
+		url: resource.url
+	};
+}
 function isNotFoundError(error) {
 	return isApiError(error) && error.status === 404;
 }
@@ -2429,7 +2504,7 @@ function uploadedAssetMetadata(file, resource) {
 	};
 }
 function parseThemeAssetMetadata(value) {
-	if (!isRecord(value)) return void 0;
+	if (!isRecord$1(value)) return void 0;
 	const filename = nonEmptyString(value["filename"]);
 	const url = nonEmptyString(value["url"]);
 	const contentType = nonEmptyString(value["content_type"]);
@@ -2451,7 +2526,7 @@ function parseThemeAssetMetadata(value) {
 	};
 }
 function createdFileResourceId(value) {
-	if (!isRecord(value) || !isRecord(value["file_resource"])) return;
+	if (!isRecord$1(value) || !isRecord$1(value["file_resource"])) return;
 	return positiveInteger(value["file_resource"]["id"]);
 }
 function positiveInteger(value) {
@@ -2466,840 +2541,882 @@ function nonEmptyString(value) {
 function optionalString(value) {
 	return typeof value === "string" ? value : void 0;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region src/theme/shadow-repo.ts
+//#region src/theme/liquid-delimiters.ts
 /**
-* A bare git repo hidden under `.fluid-theme/repo` that stands in for
-* git's index+HEAD when talking to the Fluid server. Every pull commits
-* the incoming remote state onto a single branch (`refs/heads/main`);
-* every successful push commits the outgoing local state onto the same
-* branch. HEAD therefore represents "the last state the CLI and server
-* agreed on", and its tree is the natural three-way-merge base for the
-* next pull.
+* Heuristic-only check for obviously unbalanced liquid delimiters
+* (`{% %}` and `{{ }}`). This is NOT a liquid parser — it only tracks
+* opening delimiters until they are closed. It exists to give watch-mode users a signal
+* when a save is liquid-syntax-broken: the server accepts
+* syntax-broken liquid silently on upload, and the storefront
+* renderer then serves stale content for that section with no error
+* anywhere else in the pipeline.
 *
-* We stay in git's plumbing layer — no working tree, no index file
-* next to the theme content — so the shadow repo cannot interfere
-* with the user's own git repo (if they have one) around the theme
-* dir. All state lives inside `.fluid-theme/`.
+* Closing-looking tokens without a preceding Liquid opener are intentionally
+* ignored. Liquid files commonly contain CSS such as `width:100%}` or adjacent
+* block braces (`}}`), so treating every close token as Liquid creates noisy
+* false warnings on valid theme files.
 *
-* The class only wraps the small handful of plumbing commands we
-* actually need: hash-object, cat-file, write-tree (via a temp index),
-* commit-tree, update-ref, and merge-file. Everything else stays out.
+* Known false positive: delimiters written literally inside a
+* `{% raw %}...{% endraw %}` block are still counted and can trip
+* this check even though the liquid is valid. Acceptable for a
+* warn-only heuristic — a real fix requires parsing liquid, which is
+* out of scope here (see the server-side validation note in the PR).
 */
-var ShadowRepo = class ShadowRepo {
-	headExists = void 0;
-	constructor(themeRoot, gitDir) {
-		this.themeRoot = themeRoot;
-		this.gitDir = gitDir;
+function hasUnbalancedLiquidDelimiters(content) {
+	let unclosedTags = 0;
+	let unclosedOutputs = 0;
+	for (const token of content.matchAll(/\{%|%\}|\{\{|\}\}/g)) switch (token[0]) {
+		case "{%":
+			unclosedTags += 1;
+			break;
+		case "%}":
+			if (unclosedTags > 0) unclosedTags -= 1;
+			break;
+		case "{{":
+			unclosedOutputs += 1;
+			break;
+		case "}}":
+			if (unclosedOutputs > 0) unclosedOutputs -= 1;
+			break;
 	}
-	/**
-	* Return a ShadowRepo bound to `themeId` for the given theme root.
-	* The shadow is initialized on first use and re-initialized when
-	* the caller passes a themeId different from the one previously
-	* recorded — the merge base is only meaningful for the theme it
-	* was captured against, so a cross-theme operation (pull A → push
-	* B, or two pulls of different themes into one dir) starts from a
-	* clean slate rather than pretending B's state matches A's HEAD.
-	*/
-	static async open(themeRoot, themeId) {
-		const shadowDir = join(themeRoot, ".fluid-theme");
-		const gitDir = join(shadowDir, "repo");
-		const themeIdFile = join(shadowDir, "theme-id");
-		if (existsSync(gitDir)) {
-			if (readStoredThemeId(themeIdFile) !== themeId) rmSync(gitDir, {
-				recursive: true,
-				force: true
+	return unclosedTags > 0 || unclosedOutputs > 0;
+}
+const BLOCK_TAGS = new Map([
+	["capture", "endcapture"],
+	["case", "endcase"],
+	["comment", "endcomment"],
+	["for", "endfor"],
+	["form", "endform"],
+	["if", "endif"],
+	["ifchanged", "endifchanged"],
+	["javascript", "endjavascript"],
+	["paginate", "endpaginate"],
+	["raw", "endraw"],
+	["schema", "endschema"],
+	["style", "endstyle"],
+	["stylesheet", "endstylesheet"],
+	["tablerow", "endtablerow"],
+	["unless", "endunless"]
+]);
+const CLOSING_TAGS = new Set(BLOCK_TAGS.values());
+const OPAQUE_BLOCK_TAGS = new Set([
+	"comment",
+	"javascript",
+	"raw",
+	"schema",
+	"style",
+	"stylesheet"
+]);
+/**
+* Find structurally unbalanced Liquid block tags such as an `{% if %}` with
+* no `{% endif %}`. This intentionally recognizes only established paired
+* tags; custom and inline tags are ignored rather than guessed at.
+*
+* Content inside raw/comment/schema/style/javascript blocks is opaque to
+* Liquid and therefore skipped until that block's matching close tag. This
+* prevents CSS, JSON, and examples containing Liquid-looking text from
+* producing false errors.
+*/
+function findLiquidBlockTagDiagnostics(content) {
+	const stack = [];
+	const diagnostics = [];
+	let line = 1;
+	let previousTagIndex = 0;
+	const processTag = (name, tagLine) => {
+		const open = stack.at(-1);
+		if (open && OPAQUE_BLOCK_TAGS.has(open.name)) {
+			if (name === open.expectedClose) stack.pop();
+			return;
+		}
+		const expectedClose = BLOCK_TAGS.get(name);
+		if (expectedClose) {
+			stack.push({
+				name,
+				expectedClose,
+				line: tagLine
 			});
+			return;
 		}
-		const repo = new ShadowRepo(themeRoot, gitDir);
-		if (!existsSync(gitDir)) {
-			mkdirSync(shadowDir, { recursive: true });
-			await repo.git([
-				"init",
-				"--bare",
-				"-b",
-				"main",
-				gitDir
-			], { cwd: themeRoot });
+		if (!CLOSING_TAGS.has(name)) return;
+		if (!open) {
+			diagnostics.push({
+				severity: "error",
+				message: `Unexpected Liquid tag '{% ${name} %}' on line ${tagLine}; there is no open block to close.`
+			});
+			return;
 		}
-		writeFileSync(themeIdFile, `${themeId}\n`, "utf-8");
-		const shadowIgnore = join(shadowDir, ".gitignore");
-		if (!existsSync(shadowIgnore)) writeFileSync(shadowIgnore, "# Fluid CLI shadow repo — internal state, not for version control.\n*\n");
-		await ensureRootGitignoreHidesShadow(themeRoot);
-		return repo;
-	}
-	/** True when the repo has at least one commit on `refs/heads/main`. */
-	async hasHead() {
-		if (this.headExists !== void 0) return this.headExists;
-		try {
-			await this.git([
-				"rev-parse",
-				"--verify",
-				"HEAD"
-			]);
-			this.headExists = true;
-		} catch {
-			this.headExists = false;
+		if (name !== open.expectedClose) {
+			diagnostics.push({
+				severity: "error",
+				message: `Mismatched Liquid tag '{% ${name} %}' on line ${tagLine}; '{% ${open.name} %}' from line ${open.line} must close with '{% ${open.expectedClose} %}'.`
+			});
+			return;
 		}
-		return this.headExists;
+		stack.pop();
+	};
+	for (const match of content.matchAll(/\{%-?\s*([a-zA-Z_][\w-]*)\b(?:(?!\{%)[\s\S])*?-?%\}/g)) {
+		const name = match[1]?.toLowerCase();
+		if (!name) continue;
+		const index = match.index ?? 0;
+		for (let cursor = previousTagIndex; cursor < index; cursor++) if (content.charCodeAt(cursor) === 10) line += 1;
+		previousTagIndex = index;
+		const open = stack.at(-1);
+		if (name === "liquid" && !(open && OPAQUE_BLOCK_TAGS.has(open.name))) {
+			const statements = match[0].replace(/^\{%-?\s*liquid\b/i, "").replace(/-?%\}$/, "").split("\n");
+			for (const [offset, statement] of statements.entries()) {
+				const statementName = /^\s*([a-zA-Z_][\w-]*)\b/.exec(statement)?.[1];
+				if (!statementName) continue;
+				processTag(statementName.toLowerCase(), line + offset);
+			}
+		} else processTag(name, line);
 	}
-	/**
-	* Every path recorded under HEAD's tree, recursively. Callers use
-	* this to detect local deletions (paths in HEAD, absent from the
-	* working tree). Returns [] when HEAD has never been committed.
-	*/
-	async headPaths() {
-		if (!await this.hasHead()) return [];
-		const { stdout } = await this.git([
-			"ls-tree",
-			"-r",
-			"-z",
-			"HEAD",
-			"--name-only"
-		]);
-		return stdout.toString("utf8").split("\0").filter((line) => line.length > 0);
+	for (const open of stack.reverse()) diagnostics.push({
+		severity: "error",
+		message: `Unclosed Liquid tag '{% ${open.name} %}' on line ${open.line}; expected '{% ${open.expectedClose} %}'.`
+	});
+	return diagnostics;
+}
+//#endregion
+//#region src/theme/dev-server/port-preflight.ts
+/**
+* The dev command does real work before it ever binds a port: it resolves
+* (or creates) a server-side dev theme and runs a full initial sync, which
+* can take minutes on a large theme. If the requested port is already taken
+* — most commonly by another `fluid theme dev` or the Mist Desktop preview,
+* which both default to 9292 — all of that work is wasted and the process
+* used to die with a raw `EADDRINUSE` stack trace. Call this before any of
+* that work starts so we fail fast with a clear message instead.
+*/
+var PortInUseError = class extends Error {
+	constructor(host, port) {
+		super(formatPortConflictMessage(host, port));
+		this.host = host;
+		this.port = port;
+		this.name = "PortInUseError";
 	}
-	/**
-	* The content of `path` in HEAD's tree, or null when the path does
-	* not exist there. Callers use this as the merge base for pull
-	* conflict resolution.
-	*/
-	async blobAtHead(path) {
-		if (!await this.hasHead()) return null;
-		try {
-			const { stdout } = await this.git([
-				"cat-file",
-				"-p",
-				`HEAD:${path}`
-			]);
-			return stdout;
-		} catch {
-			return null;
-		}
-	}
-	/**
-	* Write `content` as a blob in the shadow repo and return its sha.
-	* Used by `commitState` to stage each file's content before the
-	* `write-tree` call.
-	*/
-	async writeBlob(content) {
-		const buf = typeof content === "string" ? Buffer.from(content) : content;
-		const { stdout } = await this.git([
-			"hash-object",
-			"-w",
-			"--stdin"
-		], { input: buf });
-		return stdout.toString("utf8").trim();
-	}
-	/**
-	* Commit `files` as HEAD's new tree, threaded onto the current HEAD
-	* as the parent. Uses a per-call temp index so a partial run can't
-	* corrupt anything reachable from HEAD; the previous commit stays
-	* intact until `update-ref` at the end.
-	*
-	* Returns the new commit sha.
-	*/
-	async commitState(files, message) {
-		const indexPath = mkdtempSync(join(tmpdir(), "fluid-shadow-")) + "/index";
-		try {
-			const indexArgs = ["update-index", "--add"];
-			for (const { path, sha } of files) indexArgs.push("--cacheinfo", `100644,${sha},${path}`);
-			if (files.length > 0) await this.git(indexArgs, { env: { GIT_INDEX_FILE: indexPath } });
-			const treeSha = (await this.git(["write-tree"], { env: { GIT_INDEX_FILE: indexPath } })).stdout.toString("utf8").trim();
-			const parent = await this.hasHead() ? (await this.git(["rev-parse", "HEAD"])).stdout.toString("utf8").trim() : null;
-			const commitArgs = [
-				"commit-tree",
-				treeSha,
-				"-m",
-				message
-			];
-			if (parent) commitArgs.push("-p", parent);
-			const commitSha = (await this.git(commitArgs, { env: {
-				GIT_AUTHOR_NAME: "Fluid CLI",
-				GIT_AUTHOR_EMAIL: "cli@fluid.app",
-				GIT_COMMITTER_NAME: "Fluid CLI",
-				GIT_COMMITTER_EMAIL: "cli@fluid.app"
-			} })).stdout.toString("utf8").trim();
-			await this.git([
-				"update-ref",
-				"refs/heads/main",
-				commitSha
-			]);
-			this.headExists = true;
-			return commitSha;
-		} finally {
-			try {
-				rmSync(indexPath, { force: true });
-				rmSync(indexPath.substring(0, indexPath.length - 6), {
-					recursive: true,
-					force: true
-				});
-			} catch {}
-		}
-	}
-	/**
-	* Three-way merge of `local` against `remote` with `base` as the
-	* common ancestor. Returns the merged bytes and a flag when
-	* `git merge-file` reported unresolved conflicts (i.e. the output
-	* contains `<<<<<<<` markers for the reader to resolve).
-	*
-	* `base` is null when HEAD has never seen this path; we merge
-	* against an empty base, which is what git itself does for a new
-	* file added on both sides.
-	*
-	* `favor` maps to `git merge-file`'s `--ours` / `--theirs`: instead
-	* of emitting `<<<<<<<` markers, conflicting hunks are resolved to
-	* the local (`"local"` → `--ours`, local is file1) or remote
-	* (`"remote"` → `--theirs`) side. The output then never contains
-	* markers, so the result is reported conflict-free even when
-	* merge-file's exit code still counts the auto-resolved hunks.
-	*/
-	async merge3(base, local, remote, favor) {
-		const dir = mkdtempSync(join(tmpdir(), "fluid-merge-"));
-		const localPath = join(dir, "local");
-		const basePath = join(dir, "base");
-		const remotePath = join(dir, "remote");
-		try {
-			writeFileSync(localPath, local);
-			writeFileSync(basePath, base ?? Buffer.alloc(0));
-			writeFileSync(remotePath, remote);
-			try {
-				const { stdout } = await this.git([
-					"merge-file",
-					"-p",
-					...favor === "local" ? ["--ours"] : favor === "remote" ? ["--theirs"] : [],
-					"-L",
-					"local",
-					"-L",
-					"base",
-					"-L",
-					"remote",
-					localPath,
-					basePath,
-					remotePath
-				]);
-				return {
-					merged: stdout,
-					hasConflicts: false
-				};
-			} catch (err) {
-				const e = err;
-				const merged = e.stdout instanceof Buffer ? e.stdout : e.stdout != null ? Buffer.from(e.stdout) : Buffer.alloc(0);
-				const inConflictRange = typeof e.code === "number" && e.code >= 1 && e.code <= 127;
-				if (inConflictRange && favor) return {
-					merged,
-					hasConflicts: false
-				};
-				if (inConflictRange && merged.length > 0) return {
-					merged,
-					hasConflicts: true
-				};
-				throw err;
-			}
-		} finally {
-			try {
-				rmSync(dir, {
-					recursive: true,
-					force: true
-				});
-			} catch {}
-		}
-	}
-	/**
-	* Snapshot the working-tree copy of `paths` into HEAD as a single
-	* commit. Intended for the migration path: on the first pull with
-	* the new CLI (no shadow repo yet, but a `.fluid-theme.json` with
-	* checksums exists) we seed HEAD with whatever is on disk before
-	* running the merge, so unmodified files fast-forward cleanly and
-	* modified files show a diff.
-	*/
-	async seedFromWorkingTree(files, message) {
-		const entries = [];
-		for (const { path, content } of files) entries.push({
-			path,
-			sha: await this.writeBlob(content)
-		});
-		await this.commitState(entries, message);
-	}
-	async git(args, opts = {}) {
-		const child = spawn("git", args[0] === "init" ? args : [
-			"--git-dir",
-			this.gitDir,
-			...args
-		], {
-			cwd: opts.cwd ?? this.themeRoot,
-			env: {
-				...process.env,
-				...opts.env
-			},
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		});
-		if (opts.input) child.stdin.write(opts.input);
-		child.stdin.end();
-		return new Promise((resolve, reject) => {
-			const stdout = [];
-			const stderr = [];
-			child.stdout.on("data", (chunk) => stdout.push(chunk));
-			child.stderr.on("data", (chunk) => stderr.push(chunk));
-			child.on("error", reject);
-			child.on("close", (code) => {
-				const out = Buffer.concat(stdout);
-				const err = Buffer.concat(stderr);
-				if (code === 0) resolve({
-					stdout: out,
-					stderr: err
-				});
-				else {
-					const e = /* @__PURE__ */ new Error(`git ${args.join(" ")} exited with ${code}: ${err.toString("utf8")}`);
-					e.code = code ?? -1;
-					e.stdout = out;
-					e.stderr = err;
-					reject(e);
-				}
-			});
-		});
-	}
-};
-/**
-* Content-type check the pull command uses to decide whether a file
-* is safe to run through `merge3` (line-based) or must fall back to
-* whole-file "either/or" resolution (binary).
-*/
-function looksBinary(content) {
-	return content.subarray(0, Math.min(content.length, 8e3)).includes(0);
-}
-/** Best-effort readFile that returns null when the file does not exist. */
-function readIfExists(path) {
-	try {
-		return readFileSync(path);
-	} catch {
-		return null;
-	}
-}
-/**
-* Parse the numeric theme id from `.fluid-theme/theme-id`. Returns
-* null when the file is missing or the contents don't parse cleanly;
-* `open` treats that as "unknown theme" and rebuilds the shadow.
-*/
-function readStoredThemeId(themeIdFile) {
-	try {
-		const stored = parseInt(readFileSync(themeIdFile, "utf-8").trim(), 10);
-		return Number.isFinite(stored) ? stored : null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Append `.fluid-theme/` to the theme root's `.gitignore` when the
-* theme dir sits inside a git working tree and the entry isn't
-* already there. Skipped when the user isn't in a git repo — no
-* point manufacturing a `.gitignore` for someone who doesn't use
-* git. Idempotent — a second call is a no-op.
-*/
-async function ensureRootGitignoreHidesShadow(themeRoot) {
-	if (!await new Promise((resolve) => {
-		const child = spawn("git", ["rev-parse", "--is-inside-work-tree"], {
-			cwd: themeRoot,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			]
-		});
-		child.on("close", (code) => resolve(code === 0));
-		child.on("error", () => resolve(false));
-	})) return;
-	const gitignorePath = join(themeRoot, ".gitignore");
-	let existing = "";
-	try {
-		existing = readFileSync(gitignorePath, "utf-8");
-	} catch {
-		existing = "";
-	}
-	const lines = existing.split("\n").map((line) => line.trim());
-	if (lines.includes(".fluid-theme/") || lines.includes(".fluid-theme")) return;
-	const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
-	writeFileSync(gitignorePath, `${existing}${separator}.fluid-theme/\n`, "utf-8");
-}
-//#endregion
-//#region src/theme/merge-push.ts
-/**
-* Compute what changed locally since the last time the shadow repo
-* committed a state. Replaces the sha256 `checksums` map: shadow HEAD
-* is the source of truth for "what the CLI last saw the server have".
-*
-* Files whose local bytes are byte-identical to their HEAD blob are
-* skipped; anything else — new, modified, or a locally-deleted path
-* that HEAD still has — is included.
-*/
-async function diffAgainstShadow(themeRoot, shadow) {
-	const changed = [];
-	const deleted = [];
-	const localFiles = themeRoot.files();
-	const localByKey = /* @__PURE__ */ new Map();
-	const assetManifest = new ThemeAssetManifest(themeRoot.root);
-	for (const file of localFiles) {
-		if (!file.exists) continue;
-		localByKey.set(file.relativePath, file);
-		const headBlob = await shadow.blobAtHead(file.relativePath);
-		const localBuf = file.isText ? Buffer.from(file.read()) : file.readBinary();
-		if (headBlob && headBlob.equals(localBuf)) continue;
-		changed.push(file);
-	}
-	if (await shadow.hasHead()) for (const key of await listHeadPaths(shadow)) {
-		if (localByKey.has(key)) continue;
-		if (themeRoot.ignore.ignore(key)) continue;
-		if (assetManifest.has(key)) continue;
-		if (isStylesheetKey(key)) continue;
-		deleted.push(key);
-	}
-	return {
-		changed,
-		deleted
-	};
-}
-/**
-* Read every path recorded under HEAD's tree. Used to detect local
-* deletions (paths in HEAD, absent from the working tree). Implemented
-* with `git ls-tree -r HEAD --name-only` piped through the shadow
-* repo's plumbing.
-*/
-async function listHeadPaths(shadow) {
-	return shadow.headPaths();
-}
-/**
-* Refuse a push when any working file still contains a conflict marker
-* from a previous pull. Mirrors git's "you have unresolved conflicts;
-* fix them and re-run" behavior — the whole point of writing markers
-* on pull was to hand resolution to the user, so we can't send them
-* upstream.
-*/
-function findUnresolvedConflicts(files) {
-	const flagged = [];
-	for (const file of files) {
-		if (!file.isText) continue;
-		const buf = readIfExists(file.absolutePath);
-		if (!buf) continue;
-		if (containsConflictMarker(buf)) flagged.push(file.relativePath);
-	}
-	return flagged;
-}
-/**
-* Stable, machine-readable one-liner for non-interactive callers
-* (Mist Desktop's publish flow parses push output). Uploading marker-
-* bearing files to a live theme is never acceptable, so `--auto-
-* baseline` pushes still refuse — but they emit this line so the
-* desktop can surface WHICH files block the publish instead of a
-* dead-end wall of prose. Format:
-*
-*   FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=a.liquid,b.json
-*/
-function conflictMarkerBlockLine(files) {
-	return `FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=${files.join(",")}`;
-}
-const CONFLICT_START = Buffer.from("<<<<<<<");
-const CONFLICT_MID = Buffer.from("=======");
-const CONFLICT_END = Buffer.from(">>>>>>>");
-/**
-* A file counts as unresolved when it contains all three marker
-* shapes: `<<<<<<<`, `=======`, and `>>>>>>>`. Requiring all three
-* avoids false positives — a line of equals signs alone (e.g. inside
-* an ASCII table in a template comment) doesn't trip the guard.
-*/
-function containsConflictMarker(buf) {
-	return buf.includes(CONFLICT_START) && buf.includes(CONFLICT_MID) && buf.includes(CONFLICT_END);
+};
+function formatPortConflictMessage(host, port) {
+	return `Port ${port} on ${host} is already in use — likely another \`fluid theme dev\` or the Mist Desktop preview. Stop the other server or pass --port <number>.`;
 }
 /**
-* Commit the current working-tree state to shadow HEAD after a
-* successful push. Ensures the next pull's merge base is the state
-* we know the server just accepted.
+* Attempt to bind `host:port`, then immediately release it. Resolves if the
+* port is free; rejects with `PortInUseError` on `EADDRINUSE`/`EACCES`, or
+* the raw error for anything else unexpected.
 */
-async function commitPushedState(themeRoot, shadow, message) {
-	const entries = [];
-	const assetManifest = new ThemeAssetManifest(themeRoot.root);
-	const localKeys = /* @__PURE__ */ new Set();
-	for (const file of themeRoot.files()) {
-		if (!file.exists) continue;
-		localKeys.add(file.relativePath);
-		const buf = file.isText ? Buffer.from(file.read()) : file.readBinary();
-		entries.push({
-			path: file.relativePath,
-			sha: await shadow.writeBlob(buf)
+function checkPortAvailable(host, port) {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer();
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE" || err.code === "EACCES") reject(new PortInUseError(host, port));
+			else reject(err);
 		});
-	}
-	let managedAssetSentinelSha;
-	for (const key of assetManifest.keys()) {
-		if (localKeys.has(key)) continue;
-		managedAssetSentinelSha ??= await shadow.writeBlob(MANAGED_ASSET_SHADOW_SENTINEL);
-		entries.push({
-			path: key,
-			sha: managedAssetSentinelSha
+		server.once("listening", () => {
+			server.close(() => resolve());
 		});
-	}
-	if (entries.length > 0 || await shadow.hasHead()) await shadow.commitState(entries, message);
-}
-/**
-* A target can already have every URL-backed FileResource (for example from a
-* reference clone), while this checkout's manifest still names its old source
-* theme. Adopt the target and clear any legacy binary from shadow even though
-* no remote write was necessary.
-*/
-async function finalizeManifestOnlyPush(syncer, themeRoot, shadow) {
-	syncer.repointManagedAssetsToCurrentTheme();
-	await commitPushedState(themeRoot, shadow, `push @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+		server.listen(port, host);
+	});
 }
 //#endregion
-//#region src/theme/liquid-delimiters.ts
-/**
-* Heuristic-only check for obviously unbalanced liquid delimiters
-* (`{% %}` and `{{ }}`). This is NOT a liquid parser — it only tracks
-* opening delimiters until they are closed. It exists to give watch-mode users a signal
-* when a save is liquid-syntax-broken: the server accepts
-* syntax-broken liquid silently on upload, and the storefront
-* renderer then serves stale content for that section with no error
-* anywhere else in the pipeline.
-*
-* Closing-looking tokens without a preceding Liquid opener are intentionally
-* ignored. Liquid files commonly contain CSS such as `width:100%}` or adjacent
-* block braces (`}}`), so treating every close token as Liquid creates noisy
-* false warnings on valid theme files.
-*
-* Known false positive: delimiters written literally inside a
-* `{% raw %}...{% endraw %}` block are still counted and can trip
-* this check even though the liquid is valid. Acceptable for a
-* warn-only heuristic — a real fix requires parsing liquid, which is
-* out of scope here (see the server-side validation note in the PR).
-*/
-function hasUnbalancedLiquidDelimiters(content) {
-	let unclosedTags = 0;
-	let unclosedOutputs = 0;
-	for (const token of content.matchAll(/\{%|%\}|\{\{|\}\}/g)) switch (token[0]) {
-		case "{%":
-			unclosedTags += 1;
-			break;
-		case "%}":
-			if (unclosedTags > 0) unclosedTags -= 1;
-			break;
-		case "{{":
-			unclosedOutputs += 1;
-			break;
-		case "}}":
-			if (unclosedOutputs > 0) unclosedOutputs -= 1;
-			break;
-	}
-	return unclosedTags > 0 || unclosedOutputs > 0;
+//#region src/theme/dev-server/index.ts
+function timestamp() {
+	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
 }
-const BLOCK_TAGS = new Map([
-	["capture", "endcapture"],
-	["case", "endcase"],
-	["comment", "endcomment"],
-	["for", "endfor"],
-	["form", "endform"],
-	["if", "endif"],
-	["ifchanged", "endifchanged"],
-	["javascript", "endjavascript"],
-	["paginate", "endpaginate"],
-	["raw", "endraw"],
-	["schema", "endschema"],
-	["style", "endstyle"],
-	["stylesheet", "endstylesheet"],
-	["tablerow", "endtablerow"],
-	["unless", "endunless"]
-]);
-const CLOSING_TAGS = new Set(BLOCK_TAGS.values());
-const OPAQUE_BLOCK_TAGS = new Set([
-	"comment",
-	"javascript",
-	"raw",
-	"schema",
-	"style",
-	"stylesheet"
-]);
-/**
-* Find structurally unbalanced Liquid block tags such as an `{% if %}` with
-* no `{% endif %}`. This intentionally recognizes only established paired
-* tags; custom and inline tags are ignored rather than guessed at.
-*
-* Content inside raw/comment/schema/style/javascript blocks is opaque to
-* Liquid and therefore skipped until that block's matching close tag. This
-* prevents CSS, JSON, and examples containing Liquid-looking text from
-* producing false errors.
-*/
-function findLiquidBlockTagDiagnostics(content) {
-	const stack = [];
-	const diagnostics = [];
-	let line = 1;
-	let previousTagIndex = 0;
-	const processTag = (name, tagLine) => {
-		const open = stack.at(-1);
-		if (open && OPAQUE_BLOCK_TAGS.has(open.name)) {
-			if (name === open.expectedClose) stack.pop();
-			return;
+async function startDevServer(api, theme, themeRoot, opts, onReady) {
+	const sse = new SSEStream();
+	const syncer = new Syncer(api, theme.id, themeRoot);
+	let remoteStateSafe = true;
+	const invalidateRemoteState = () => {
+		if (!remoteStateSafe) return;
+		remoteStateSafe = false;
+		try {
+			opts.onRemoteStateInvalidated?.();
+		} catch {}
+	};
+	const recordRemoteState = () => {
+		if (!remoteStateSafe) return;
+		if (opts.onRemoteState) {
+			const state = syncer.devRemoteState(new ThemeAssetManifest(themeRoot.root).fingerprint());
+			if (state) try {
+				opts.onRemoteState(state);
+			} catch {
+				invalidateRemoteState();
+			}
 		}
-		const expectedClose = BLOCK_TAGS.get(name);
-		if (expectedClose) {
-			stack.push({
-				name,
-				expectedClose,
-				line: tagLine
-			});
+	};
+	const pendingUpdates = /* @__PURE__ */ new Set();
+	console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
+	const progress = (done, total) => {
+		process.stdout.write(`\r  Uploading ${done}/${total} files…`);
+	};
+	const uploadFromRemoteIndex = () => syncer.uploadTheme({
+		delete: true,
+		validate: opts.validate,
+		linkManagedAssets: { replace: true },
+		pendingBinaryAssets: true,
+		onProgress: progress
+	});
+	let syncResult;
+	if (opts.initialSync) {
+		let remoteStateIsTrusted = false;
+		try {
+			syncer.useDevRemoteState(opts.initialSync);
+			await syncer.preflightPush(opts.initialSync.remoteSha);
+			remoteStateIsTrusted = true;
+		} catch (error) {
+			if (!(error instanceof PushConflictError)) throw error;
+		}
+		syncResult = remoteStateIsTrusted ? await syncer.uploadTheme({
+			delete: true,
+			validate: opts.validate,
+			linkManagedAssets: { replace: true },
+			pendingBinaryAssets: true,
+			baseSha: syncer.remoteSha(),
+			remoteState: opts.initialSync,
+			skipPreflight: true,
+			onProgress: progress
+		}) : await uploadFromRemoteIndex();
+	} else syncResult = await uploadFromRemoteIndex();
+	process.stdout.write("\n");
+	if (syncResult.linked > 0) console.log(`  Saved ${syncResult.linked} remote asset reference(s).`);
+	if (syncResult.validationFailed) {
+		console.error(`\nSchema validation failed (${syncResult.errors.length} error(s)). Use --force to skip.\n`);
+		for (const e of syncResult.errors) console.error(`  ${e}`);
+		process.exit(1);
+	} else if (syncResult.errors.length > 0) {
+		invalidateRemoteState();
+		for (const e of syncResult.errors) console.error(`  ${e}`);
+		if (syncResult.uploaded + syncResult.deleted === 0) process.exit(1);
+	}
+	if (syncResult.errors.length === 0) recordRemoteState();
+	const SYNC_IDLE_MS = 2e3;
+	let lastArrivedAt = 0;
+	let pendingSync = null;
+	let syncInFlight = Promise.resolve();
+	let askOwed = false;
+	let remoteWritesBlocked = false;
+	const blockRemoteWrites = (error) => {
+		if (remoteWritesBlocked) return;
+		remoteWritesBlocked = true;
+		invalidateRemoteState();
+		console.error(`\n[Watcher] Remote theme changed outside this dev session (${error.message}). Restart theme dev to compare the current remote state before writing again.`);
+	};
+	const sendSync = () => {
+		syncInFlight = syncInFlight.then(async () => {
+			const accepted = await syncer.requestSync();
+			askOwed = !accepted;
+			if (accepted) recordRemoteState();
+		});
+	};
+	const flushSyncNow = () => {
+		if (!pendingSync) return;
+		clearTimeout(pendingSync);
+		pendingSync = null;
+		sendSync();
+	};
+	const scheduleSync = () => {
+		if (pendingSync) clearTimeout(pendingSync);
+		pendingSync = setTimeout(() => {
+			pendingSync = null;
+			sendSync();
+		}, SYNC_IDLE_MS);
+	};
+	const stopWatcher = watchTheme(themeRoot, async (modified, added, removed, arrivedAt) => {
+		if (arrivedAt - lastArrivedAt > SYNC_IDLE_MS) flushSyncNow();
+		else if (pendingSync) {
+			clearTimeout(pendingSync);
+			pendingSync = null;
+		}
+		lastArrivedAt = arrivedAt;
+		await syncInFlight;
+		if (askOwed) {
+			sendSync();
+			await syncInFlight;
+		}
+		if (remoteWritesBlocked) return;
+		try {
+			assertNoCaseCollisions(themeRoot.files().map((file) => file.relativePath));
+		} catch (error) {
+			console.error(`\n[Watcher] Sync blocked: ${String(error)}`);
 			return;
 		}
-		if (!CLOSING_TAGS.has(name)) return;
-		if (!open) {
-			diagnostics.push({
-				severity: "error",
-				message: `Unexpected Liquid tag '{% ${name} %}' on line ${tagLine}; there is no open block to close.`
-			});
+		const changed = [...modified, ...added];
+		let wroteRemote = false;
+		for (const file of changed) {
+			if (opts.validate && file.isLiquid) {
+				const diagnostics = file.validateSchema();
+				for (const d of diagnostics) {
+					const prefix = d.severity === "error" ? "Schema error" : "Schema warning";
+					console.warn(`\n[${prefix}] ${file.relativePath}: ${d.message}`);
+				}
+			}
+			pendingUpdates.add(file.relativePath);
+			try {
+				const uploadedContent = await syncer.uploadFile(file, syncer.remoteSha(), { pendingAsset: true });
+				wroteRemote = true;
+				console.log(`  ✓ synced ${file.relativePath} (${timestamp()})`);
+				if (file.isLiquid && uploadedContent !== null && hasUnbalancedLiquidDelimiters(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: unbalanced liquid delimiters — the storefront may silently serve stale content for this section`);
+				if (file.isLiquid && uploadedContent !== null) for (const diagnostic of findLiquidBlockTagDiagnostics(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: ${diagnostic.message}`);
+			} catch (e) {
+				if (e instanceof PushConflictError) {
+					blockRemoteWrites(e);
+					break;
+				}
+				invalidateRemoteState();
+				console.error(`\n[Watcher] Upload failed: ${file.relativePath}: ${e}`);
+			} finally {
+				pendingUpdates.delete(file.relativePath);
+			}
+		}
+		if (remoteWritesBlocked) return;
+		for (const file of removed) {
+			if (themeRoot.ignore.ignore(file.relativePath)) continue;
+			try {
+				await syncer.deleteRemoteFile(file.relativePath, syncer.remoteSha());
+				wroteRemote = true;
+				console.log(`  ✓ removed ${file.relativePath}`);
+			} catch (error) {
+				if (error instanceof PushConflictError) {
+					blockRemoteWrites(error);
+					break;
+				}
+				invalidateRemoteState();
+			}
+		}
+		if (remoteWritesBlocked) return;
+		if (wroteRemote) recordRemoteState();
+		if (removed.length > 0) sse.broadcast(JSON.stringify({ reload_page: true }));
+		else if (changed.length > 0) sse.broadcast(JSON.stringify({ modified: changed.map((f) => f.relativePath) }));
+		scheduleSync();
+	});
+	const server = http.createServer(async (req, res) => {
+		if (req.url === "/hot-reload") {
+			sse.add(res);
 			return;
 		}
-		if (name !== open.expectedClose) {
-			diagnostics.push({
-				severity: "error",
-				message: `Mismatched Liquid tag '{% ${name} %}' on line ${tagLine}; '{% ${open.name} %}' from line ${open.line} must close with '{% ${open.expectedClose} %}'.`
+		try {
+			await proxyRequest(req, res, {
+				company: theme.company,
+				themeId: theme.id,
+				reloadMode: opts.reloadMode,
+				pendingFiles: () => [...pendingUpdates].map((p) => themeRoot.file(p)).filter((f) => f.isText).map((f) => ({
+					relativePath: f.relativePath,
+					read: () => f.read()
+				}))
 			});
-			return;
+		} catch (e) {
+			console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
+			if (!res.headersSent) {
+				const message = e instanceof Error ? e.message : String(e);
+				res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+				res.end(`Bad Gateway — the local preview could not reach ${theme.company}.fluid.app: ${message}\nThis is the dev machine's network path to Fluid, not the theme. Common causes: TLS-inspecting security software (its root CA is in the OS keychain, which Node does not read — set NODE_EXTRA_CA_CERTS to its certificate), DNS, or a proxy. The same error is logged by the theme dev server process.`);
+			}
 		}
-		stack.pop();
-	};
-	for (const match of content.matchAll(/\{%-?\s*([a-zA-Z_][\w-]*)\b(?:(?!\{%)[\s\S])*?-?%\}/g)) {
-		const name = match[1]?.toLowerCase();
-		if (!name) continue;
-		const index = match.index ?? 0;
-		for (let cursor = previousTagIndex; cursor < index; cursor++) if (content.charCodeAt(cursor) === 10) line += 1;
-		previousTagIndex = index;
-		const open = stack.at(-1);
-		if (name === "liquid" && !(open && OPAQUE_BLOCK_TAGS.has(open.name))) {
-			const statements = match[0].replace(/^\{%-?\s*liquid\b/i, "").replace(/-?%\}$/, "").split("\n");
-			for (const [offset, statement] of statements.entries()) {
-				const statementName = /^\s*([a-zA-Z_][\w-]*)\b/.exec(statement)?.[1];
-				if (!statementName) continue;
-				processTag(statementName.toLowerCase(), line + offset);
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+				console.error(formatPortConflictMessage(opts.host, opts.port));
+				process.exit(1);
 			}
-		} else processTag(name, line);
-	}
-	for (const open of stack.reverse()) diagnostics.push({
-		severity: "error",
-		message: `Unclosed Liquid tag '{% ${open.name} %}' on line ${open.line}; expected '{% ${open.expectedClose} %}'.`
+			reject(err);
+		});
+		server.listen(opts.port, opts.host, () => resolve());
 	});
-	return diagnostics;
+	const address = `http://${opts.host}:${opts.port}`;
+	onReady?.(address);
+	return function stop() {
+		sse.close();
+		stopWatcher();
+		server.close();
+	};
 }
 //#endregion
-//#region src/theme/dev-server/port-preflight.ts
-/**
-* The dev command does real work before it ever binds a port: it resolves
-* (or creates) a server-side dev theme and runs a full initial sync, which
-* can take minutes on a large theme. If the requested port is already taken
-* — most commonly by another `fluid theme dev` or the Mist Desktop preview,
-* which both default to 9292 — all of that work is wasted and the process
-* used to die with a raw `EADDRINUSE` stack trace. Call this before any of
-* that work starts so we fail fast with a clear message instead.
-*/
-var PortInUseError = class extends Error {
-	constructor(host, port) {
-		super(formatPortConflictMessage(host, port));
-		this.host = host;
-		this.port = port;
-		this.name = "PortInUseError";
+//#region src/theme/dev-remote-baseline.ts
+const BASELINE_VERSION = 1;
+const BASELINE_FILE = join(".fluid-theme", "dev-baseline.json");
+function readDevRemoteBaseline(themeRoot, themeId, assetManifestSha) {
+	try {
+		const state = parseDocument(JSON.parse(readFileSync(join(themeRoot, BASELINE_FILE), "utf-8")));
+		if (state.themeId !== themeId) return null;
+		if (state.assetManifestSha !== assetManifestSha) return null;
+		return state;
+	} catch {
+		return null;
 	}
-};
-function formatPortConflictMessage(host, port) {
-	return `Port ${port} on ${host} is already in use — likely another \`fluid theme dev\` or the Mist Desktop preview. Stop the other server or pass --port <number>.`;
 }
-/**
-* Attempt to bind `host:port`, then immediately release it. Resolves if the
-* port is free; rejects with `PortInUseError` on `EADDRINUSE`/`EACCES`, or
-* the raw error for anything else unexpected.
-*/
-function checkPortAvailable(host, port) {
-	return new Promise((resolve, reject) => {
-		const server = net.createServer();
-		server.once("error", (err) => {
-			if (err.code === "EADDRINUSE" || err.code === "EACCES") reject(new PortInUseError(host, port));
-			else reject(err);
-		});
-		server.once("listening", () => {
-			server.close(() => resolve());
+function writeDevRemoteBaseline(themeRoot, state) {
+	const document = {
+		version: BASELINE_VERSION,
+		...state
+	};
+	parseDocument(document);
+	const path = join(themeRoot, BASELINE_FILE);
+	const tempPath = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(tempPath, `${JSON.stringify(document)}\n`, {
+			encoding: "utf-8",
+			mode: 384
 		});
-		server.listen(port, host);
-	});
+		renameSync(tempPath, path);
+	} catch (error) {
+		rmSync(tempPath, { force: true });
+		throw error;
+	}
 }
-//#endregion
-//#region src/theme/dev-server/index.ts
-function timestamp() {
-	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+function removeDevRemoteBaseline(themeRoot) {
+	rmSync(join(themeRoot, BASELINE_FILE), { force: true });
 }
-async function startDevServer(api, theme, themeRoot, opts, onReady) {
-	const sse = new SSEStream();
-	const syncer = new Syncer(api, theme.id, themeRoot);
-	const recordRemoteSha = () => {
-		const remoteSha = syncer.remoteSha();
-		if (remoteSha) opts.onRemoteSha?.(remoteSha);
+async function devRemoteStateFromSourceShadow(themeRoot, shadow, themeId, remoteSha) {
+	try {
+		if (!await shadow.hasHead()) return null;
+		const assetManifest = new ThemeAssetManifest(themeRoot.root);
+		const resources = [];
+		for (const key of await shadow.headPaths()) {
+			const content = await shadow.blobAtHead(key);
+			if (!content) return null;
+			const asset = assetManifest.get(key);
+			if (asset) {
+				if (asset.pending || !asset.url || !content.equals(Buffer.from("fluid-managed-asset\n"))) return null;
+				resources.push({
+					key,
+					checksum: asset.checksum ?? null,
+					contentPresent: false,
+					resourceType: "FileResource",
+					url: asset.url
+				});
+				continue;
+			}
+			if (content.equals(Buffer.from("fluid-managed-asset\n"))) return null;
+			resources.push({
+				key,
+				checksum: createHash("sha256").update(content).digest("hex"),
+				contentPresent: true
+			});
+		}
+		return {
+			themeId,
+			remoteSha,
+			assetManifestSha: assetManifest.fingerprint(),
+			resources
+		};
+	} catch {
+		return null;
+	}
+}
+function parseDocument(document) {
+	if (!isRecord(document) || document["version"] !== BASELINE_VERSION) throw new Error(`expected version ${BASELINE_VERSION}`);
+	const themeId = document["themeId"];
+	const remoteSha = document["remoteSha"];
+	const assetManifestSha = document["assetManifestSha"];
+	const rawResources = document["resources"];
+	if (!isPositiveInteger(themeId)) throw new Error("invalid theme id");
+	if (!isNonEmptyString(remoteSha)) throw new Error("invalid remote sha");
+	if (!isNonEmptyString(assetManifestSha)) throw new Error("invalid asset manifest sha");
+	if (!Array.isArray(rawResources)) throw new Error("invalid resources");
+	const resources = rawResources.map(parseResource);
+	assertNoCaseCollisions(resources.map((resource) => resource.key));
+	return {
+		themeId,
+		remoteSha,
+		assetManifestSha,
+		resources
 	};
-	const pendingUpdates = /* @__PURE__ */ new Set();
-	console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
-	const progress = (done, total) => {
-		process.stdout.write(`\r  Uploading ${done}/${total} files…`);
+}
+function parseResource(resource) {
+	if (!isRecord(resource)) throw new Error("invalid resource");
+	const key = resource["key"];
+	const checksum = resource["checksum"];
+	const contentPresent = resource["contentPresent"];
+	const resourceType = resource["resourceType"];
+	const resourceId = resource["resourceId"];
+	const url = resource["url"];
+	if (!isNonEmptyString(key) || key.includes("\0")) throw new Error("invalid resource key");
+	if (checksum !== null && !isNonEmptyString(checksum)) throw new Error("invalid resource checksum");
+	if (typeof contentPresent !== "boolean") throw new Error("invalid resource content marker");
+	if (resourceType !== void 0 && resourceType !== null && !isNonEmptyString(resourceType)) throw new Error("invalid resource type");
+	if (resourceId !== void 0 && resourceId !== null && !isPositiveInteger(resourceId)) throw new Error("invalid resource id");
+	if (url !== void 0 && url !== null && !isNonEmptyString(url)) throw new Error("invalid resource url");
+	return {
+		key,
+		checksum,
+		contentPresent,
+		resourceType,
+		resourceId,
+		url
 	};
-	const uploadFromRemoteIndex = () => syncer.uploadTheme({
-		delete: true,
-		validate: opts.validate,
-		linkManagedAssets: { replace: true },
-		pendingBinaryAssets: true,
-		onProgress: progress
-	});
-	let syncResult;
-	if (opts.initialSync) {
-		let shadowIsTrusted = false;
+}
+function isRecord(candidate) {
+	return typeof candidate === "object" && candidate !== null;
+}
+function isNonEmptyString(candidate) {
+	return typeof candidate === "string" && candidate.length > 0;
+}
+function isPositiveInteger(candidate) {
+	return typeof candidate === "number" && Number.isInteger(candidate) && candidate > 0;
+}
+//#endregion
+//#region src/theme/shadow-repo.ts
+/**
+* A bare git repo hidden under `.fluid-theme/repo` that stands in for
+* git's index+HEAD when talking to the Fluid server. Every pull commits
+* the incoming remote state onto a single branch (`refs/heads/main`);
+* every successful push commits the outgoing local state onto the same
+* branch. HEAD therefore represents "the last state the CLI and server
+* agreed on", and its tree is the natural three-way-merge base for the
+* next pull.
+*
+* We stay in git's plumbing layer — no working tree, no index file
+* next to the theme content — so the shadow repo cannot interfere
+* with the user's own git repo (if they have one) around the theme
+* dir. All state lives inside `.fluid-theme/`.
+*
+* The class only wraps the small handful of plumbing commands we
+* actually need: hash-object, cat-file, write-tree (via a temp index),
+* commit-tree, update-ref, and merge-file. Everything else stays out.
+*/
+var ShadowRepo = class ShadowRepo {
+	headExists = void 0;
+	constructor(themeRoot, gitDir) {
+		this.themeRoot = themeRoot;
+		this.gitDir = gitDir;
+	}
+	/**
+	* Return a ShadowRepo bound to `themeId` for the given theme root.
+	* The shadow is initialized on first use and re-initialized when
+	* the caller passes a themeId different from the one previously
+	* recorded — the merge base is only meaningful for the theme it
+	* was captured against, so a cross-theme operation (pull A → push
+	* B, or two pulls of different themes into one dir) starts from a
+	* clean slate rather than pretending B's state matches A's HEAD.
+	*/
+	static async open(themeRoot, themeId) {
+		const shadowDir = join(themeRoot, ".fluid-theme");
+		const gitDir = join(shadowDir, "repo");
+		const themeIdFile = join(shadowDir, "theme-id");
+		if (existsSync(gitDir)) {
+			if (readStoredThemeId(themeIdFile) !== themeId) rmSync(gitDir, {
+				recursive: true,
+				force: true
+			});
+		}
+		const repo = new ShadowRepo(themeRoot, gitDir);
+		if (!existsSync(gitDir)) {
+			mkdirSync(shadowDir, { recursive: true });
+			await repo.git([
+				"init",
+				"--bare",
+				"-b",
+				"main",
+				gitDir
+			], { cwd: themeRoot });
+		}
+		writeFileSync(themeIdFile, `${themeId}\n`, "utf-8");
+		const shadowIgnore = join(shadowDir, ".gitignore");
+		if (!existsSync(shadowIgnore)) writeFileSync(shadowIgnore, "# Fluid CLI shadow repo — internal state, not for version control.\n*\n");
+		await ensureRootGitignoreHidesShadow(themeRoot);
+		return repo;
+	}
+	/** True when the repo has at least one commit on `refs/heads/main`. */
+	async hasHead() {
+		if (this.headExists !== void 0) return this.headExists;
+		try {
+			await this.git([
+				"rev-parse",
+				"--verify",
+				"HEAD"
+			]);
+			this.headExists = true;
+		} catch {
+			this.headExists = false;
+		}
+		return this.headExists;
+	}
+	/**
+	* Every path recorded under HEAD's tree, recursively. Callers use
+	* this to detect local deletions (paths in HEAD, absent from the
+	* working tree). Returns [] when HEAD has never been committed.
+	*/
+	async headPaths() {
+		if (!await this.hasHead()) return [];
+		const { stdout } = await this.git([
+			"ls-tree",
+			"-r",
+			"-z",
+			"HEAD",
+			"--name-only"
+		]);
+		return stdout.toString("utf8").split("\0").filter((line) => line.length > 0);
+	}
+	/**
+	* The content of `path` in HEAD's tree, or null when the path does
+	* not exist there. Callers use this as the merge base for pull
+	* conflict resolution.
+	*/
+	async blobAtHead(path) {
+		if (!await this.hasHead()) return null;
 		try {
-			await syncer.preflightPush(opts.initialSync.remoteSha);
-			shadowIsTrusted = true;
-		} catch (error) {
-			if (!(error instanceof PushConflictError)) throw error;
+			const { stdout } = await this.git([
+				"cat-file",
+				"-p",
+				`HEAD:${path}`
+			]);
+			return stdout;
+		} catch {
+			return null;
 		}
-		if (shadowIsTrusted) {
-			const diff = await diffAgainstShadow(themeRoot, opts.initialSync.shadow);
-			syncResult = await syncer.uploadTheme({
-				delete: true,
-				validate: opts.validate,
-				pendingBinaryAssets: true,
-				baseSha: syncer.remoteSha(),
-				diff,
-				skipPreflight: true,
-				onProgress: progress
-			});
-		} else syncResult = await uploadFromRemoteIndex();
-	} else syncResult = await uploadFromRemoteIndex();
-	process.stdout.write("\n");
-	if (syncResult.linked > 0) console.log(`  Saved ${syncResult.linked} remote asset reference(s).`);
-	if (syncResult.validationFailed) {
-		console.error(`\nSchema validation failed (${syncResult.errors.length} error(s)). Use --force to skip.\n`);
-		for (const e of syncResult.errors) console.error(`  ${e}`);
-		process.exit(1);
-	} else if (syncResult.errors.length > 0) {
-		for (const e of syncResult.errors) console.error(`  ${e}`);
-		if (syncResult.uploaded + syncResult.deleted === 0) process.exit(1);
 	}
-	if (syncResult.errors.length === 0) recordRemoteSha();
-	const SYNC_IDLE_MS = 2e3;
-	let lastArrivedAt = 0;
-	let pendingSync = null;
-	let syncInFlight = Promise.resolve();
-	let askOwed = false;
-	const sendSync = () => {
-		syncInFlight = syncInFlight.then(async () => {
-			askOwed = !await syncer.requestSync();
-		});
-	};
-	const flushSyncNow = () => {
-		if (!pendingSync) return;
-		clearTimeout(pendingSync);
-		pendingSync = null;
-		sendSync();
-	};
-	const scheduleSync = () => {
-		if (pendingSync) clearTimeout(pendingSync);
-		pendingSync = setTimeout(() => {
-			pendingSync = null;
-			sendSync();
-		}, SYNC_IDLE_MS);
-	};
-	const stopWatcher = watchTheme(themeRoot, async (modified, added, removed, arrivedAt) => {
-		if (arrivedAt - lastArrivedAt > SYNC_IDLE_MS) flushSyncNow();
-		else if (pendingSync) {
-			clearTimeout(pendingSync);
-			pendingSync = null;
-		}
-		lastArrivedAt = arrivedAt;
-		await syncInFlight;
-		if (askOwed) {
-			sendSync();
-			await syncInFlight;
+	/**
+	* Write `content` as a blob in the shadow repo and return its sha.
+	* Used by `commitState` to stage each file's content before the
+	* `write-tree` call.
+	*/
+	async writeBlob(content) {
+		const buf = typeof content === "string" ? Buffer.from(content) : content;
+		const { stdout } = await this.git([
+			"hash-object",
+			"-w",
+			"--stdin"
+		], { input: buf });
+		return stdout.toString("utf8").trim();
+	}
+	/**
+	* Commit `files` as HEAD's new tree, threaded onto the current HEAD
+	* as the parent. Uses a per-call temp index so a partial run can't
+	* corrupt anything reachable from HEAD; the previous commit stays
+	* intact until `update-ref` at the end.
+	*
+	* Returns the new commit sha.
+	*/
+	async commitState(files, message) {
+		const indexPath = mkdtempSync(join(tmpdir(), "fluid-shadow-")) + "/index";
+		try {
+			const indexArgs = ["update-index", "--add"];
+			for (const { path, sha } of files) indexArgs.push("--cacheinfo", `100644,${sha},${path}`);
+			if (files.length > 0) await this.git(indexArgs, { env: { GIT_INDEX_FILE: indexPath } });
+			const treeSha = (await this.git(["write-tree"], { env: { GIT_INDEX_FILE: indexPath } })).stdout.toString("utf8").trim();
+			const parent = await this.hasHead() ? (await this.git(["rev-parse", "HEAD"])).stdout.toString("utf8").trim() : null;
+			const commitArgs = [
+				"commit-tree",
+				treeSha,
+				"-m",
+				message
+			];
+			if (parent) commitArgs.push("-p", parent);
+			const commitSha = (await this.git(commitArgs, { env: {
+				GIT_AUTHOR_NAME: "Fluid CLI",
+				GIT_AUTHOR_EMAIL: "cli@fluid.app",
+				GIT_COMMITTER_NAME: "Fluid CLI",
+				GIT_COMMITTER_EMAIL: "cli@fluid.app"
+			} })).stdout.toString("utf8").trim();
+			await this.git([
+				"update-ref",
+				"refs/heads/main",
+				commitSha
+			]);
+			this.headExists = true;
+			return commitSha;
+		} finally {
+			try {
+				rmSync(indexPath, { force: true });
+				rmSync(indexPath.substring(0, indexPath.length - 6), {
+					recursive: true,
+					force: true
+				});
+			} catch {}
 		}
-		const changed = [...modified, ...added];
-		let wroteRemote = false;
-		for (const file of changed) {
-			if (opts.validate && file.isLiquid) {
-				const diagnostics = file.validateSchema();
-				for (const d of diagnostics) {
-					const prefix = d.severity === "error" ? "Schema error" : "Schema warning";
-					console.warn(`\n[${prefix}] ${file.relativePath}: ${d.message}`);
-				}
-			}
-			pendingUpdates.add(file.relativePath);
+	}
+	/**
+	* Three-way merge of `local` against `remote` with `base` as the
+	* common ancestor. Returns the merged bytes and a flag when
+	* `git merge-file` reported unresolved conflicts (i.e. the output
+	* contains `<<<<<<<` markers for the reader to resolve).
+	*
+	* `base` is null when HEAD has never seen this path; we merge
+	* against an empty base, which is what git itself does for a new
+	* file added on both sides.
+	*
+	* `favor` maps to `git merge-file`'s `--ours` / `--theirs`: instead
+	* of emitting `<<<<<<<` markers, conflicting hunks are resolved to
+	* the local (`"local"` → `--ours`, local is file1) or remote
+	* (`"remote"` → `--theirs`) side. The output then never contains
+	* markers, so the result is reported conflict-free even when
+	* merge-file's exit code still counts the auto-resolved hunks.
+	*/
+	async merge3(base, local, remote, favor) {
+		const dir = mkdtempSync(join(tmpdir(), "fluid-merge-"));
+		const localPath = join(dir, "local");
+		const basePath = join(dir, "base");
+		const remotePath = join(dir, "remote");
+		try {
+			writeFileSync(localPath, local);
+			writeFileSync(basePath, base ?? Buffer.alloc(0));
+			writeFileSync(remotePath, remote);
 			try {
-				const uploadedContent = await syncer.uploadFile(file, void 0, { pendingAsset: true });
-				wroteRemote = true;
-				console.log(`  ✓ synced ${file.relativePath} (${timestamp()})`);
-				if (file.isLiquid && uploadedContent !== null && hasUnbalancedLiquidDelimiters(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: unbalanced liquid delimiters — the storefront may silently serve stale content for this section`);
-				if (file.isLiquid && uploadedContent !== null) for (const diagnostic of findLiquidBlockTagDiagnostics(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: ${diagnostic.message}`);
-			} catch (e) {
-				console.error(`\n[Watcher] Upload failed: ${file.relativePath}: ${e}`);
-			} finally {
-				pendingUpdates.delete(file.relativePath);
+				const { stdout } = await this.git([
+					"merge-file",
+					"-p",
+					...favor === "local" ? ["--ours"] : favor === "remote" ? ["--theirs"] : [],
+					"-L",
+					"local",
+					"-L",
+					"base",
+					"-L",
+					"remote",
+					localPath,
+					basePath,
+					remotePath
+				]);
+				return {
+					merged: stdout,
+					hasConflicts: false
+				};
+			} catch (err) {
+				const e = err;
+				const merged = e.stdout instanceof Buffer ? e.stdout : e.stdout != null ? Buffer.from(e.stdout) : Buffer.alloc(0);
+				const inConflictRange = typeof e.code === "number" && e.code >= 1 && e.code <= 127;
+				if (inConflictRange && favor) return {
+					merged,
+					hasConflicts: false
+				};
+				if (inConflictRange && merged.length > 0) return {
+					merged,
+					hasConflicts: true
+				};
+				throw err;
 			}
-		}
-		for (const file of removed) {
-			if (themeRoot.ignore.ignore(file.relativePath)) continue;
+		} finally {
 			try {
-				await syncer.deleteRemoteFile(file.relativePath);
-				wroteRemote = true;
-				console.log(`  ✓ removed ${file.relativePath}`);
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
 			} catch {}
 		}
-		if (wroteRemote) recordRemoteSha();
-		if (removed.length > 0) sse.broadcast(JSON.stringify({ reload_page: true }));
-		else if (changed.length > 0) sse.broadcast(JSON.stringify({ modified: changed.map((f) => f.relativePath) }));
-		scheduleSync();
-	});
-	const server = http.createServer(async (req, res) => {
-		if (req.url === "/hot-reload") {
-			sse.add(res);
-			return;
-		}
-		try {
-			await proxyRequest(req, res, {
-				company: theme.company,
-				themeId: theme.id,
-				reloadMode: opts.reloadMode,
-				pendingFiles: () => [...pendingUpdates].map((p) => themeRoot.file(p)).filter((f) => f.isText).map((f) => ({
-					relativePath: f.relativePath,
-					read: () => f.read()
-				}))
+	}
+	/**
+	* Snapshot the working-tree copy of `paths` into HEAD as a single
+	* commit. Intended for the migration path: on the first pull with
+	* the new CLI (no shadow repo yet, but a `.fluid-theme.json` with
+	* checksums exists) we seed HEAD with whatever is on disk before
+	* running the merge, so unmodified files fast-forward cleanly and
+	* modified files show a diff.
+	*/
+	async seedFromWorkingTree(files, message) {
+		const entries = [];
+		for (const { path, content } of files) entries.push({
+			path,
+			sha: await this.writeBlob(content)
+		});
+		await this.commitState(entries, message);
+	}
+	async git(args, opts = {}) {
+		const child = spawn("git", args[0] === "init" ? args : [
+			"--git-dir",
+			this.gitDir,
+			...args
+		], {
+			cwd: opts.cwd ?? this.themeRoot,
+			env: {
+				...process.env,
+				...opts.env
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		if (opts.input) child.stdin.write(opts.input);
+		child.stdin.end();
+		return new Promise((resolve, reject) => {
+			const stdout = [];
+			const stderr = [];
+			child.stdout.on("data", (chunk) => stdout.push(chunk));
+			child.stderr.on("data", (chunk) => stderr.push(chunk));
+			child.on("error", reject);
+			child.on("close", (code) => {
+				const out = Buffer.concat(stdout);
+				const err = Buffer.concat(stderr);
+				if (code === 0) resolve({
+					stdout: out,
+					stderr: err
+				});
+				else {
+					const e = /* @__PURE__ */ new Error(`git ${args.join(" ")} exited with ${code}: ${err.toString("utf8")}`);
+					e.code = code ?? -1;
+					e.stdout = out;
+					e.stderr = err;
+					reject(e);
+				}
 			});
-		} catch (e) {
-			console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
-			if (!res.headersSent) {
-				const message = e instanceof Error ? e.message : String(e);
-				res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
-				res.end(`Bad Gateway — the local preview could not reach ${theme.company}.fluid.app: ${message}\nThis is the dev machine's network path to Fluid, not the theme. Common causes: TLS-inspecting security software (its root CA is in the OS keychain, which Node does not read — set NODE_EXTRA_CA_CERTS to its certificate), DNS, or a proxy. The same error is logged by the theme dev server process.`);
-			}
-		}
-	});
-	await new Promise((resolve, reject) => {
-		server.once("error", (err) => {
-			if (err.code === "EADDRINUSE" || err.code === "EACCES") {
-				console.error(formatPortConflictMessage(opts.host, opts.port));
-				process.exit(1);
-			}
-			reject(err);
 		});
-		server.listen(opts.port, opts.host, () => resolve());
-	});
-	const address = `http://${opts.host}:${opts.port}`;
-	onReady?.(address);
-	return function stop() {
-		sse.close();
-		stopWatcher();
-		server.close();
-	};
+	}
+};
+/**
+* Content-type check the pull command uses to decide whether a file
+* is safe to run through `merge3` (line-based) or must fall back to
+* whole-file "either/or" resolution (binary).
+*/
+function looksBinary(content) {
+	return content.subarray(0, Math.min(content.length, 8e3)).includes(0);
+}
+/** Best-effort readFile that returns null when the file does not exist. */
+function readIfExists(path) {
+	try {
+		return readFileSync(path);
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse the numeric theme id from `.fluid-theme/theme-id`. Returns
+* null when the file is missing or the contents don't parse cleanly;
+* `open` treats that as "unknown theme" and rebuilds the shadow.
+*/
+function readStoredThemeId(themeIdFile) {
+	try {
+		const stored = parseInt(readFileSync(themeIdFile, "utf-8").trim(), 10);
+		return Number.isFinite(stored) ? stored : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Append `.fluid-theme/` to the theme root's `.gitignore` when the
+* theme dir sits inside a git working tree and the entry isn't
+* already there. Skipped when the user isn't in a git repo — no
+* point manufacturing a `.gitignore` for someone who doesn't use
+* git. Idempotent — a second call is a no-op.
+*/
+async function ensureRootGitignoreHidesShadow(themeRoot) {
+	if (!await new Promise((resolve) => {
+		const child = spawn("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd: themeRoot,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		child.on("close", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	})) return;
+	const gitignorePath = join(themeRoot, ".gitignore");
+	let existing = "";
+	try {
+		existing = readFileSync(gitignorePath, "utf-8");
+	} catch {
+		existing = "";
+	}
+	const lines = existing.split("\n").map((line) => line.trim());
+	if (lines.includes(".fluid-theme/") || lines.includes(".fluid-theme")) return;
+	const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+	writeFileSync(gitignorePath, `${existing}${separator}.fluid-theme/\n`, "utf-8");
 }
 //#endregion
 //#region src/theme-picker.ts
@@ -3455,22 +3572,9 @@ function resolveThemeRootFromCwd(workspace) {
 }
 //#endregion
 //#region src/commands/dev.ts
-/**
-* Return the state needed to trust the source shadow for a dev sync.
-*
-* All three values must still describe the same world: the checkout has not
-* pulled a newer source, the dev theme has not changed outside this CLI, and
-* managed ImageKit references have not changed outside the shadow's file tree.
-*/
-function devShadowTrust(config, devTheme, assetManifestSha) {
-	if (!config?.baseSha || !devTheme?.remoteSha || !devTheme.sourceBaseSha || !devTheme.assetManifestSha) return null;
-	if (devTheme.sourceThemeId !== config.themeId) return null;
-	if (devTheme.sourceBaseSha !== config.baseSha) return null;
-	if (devTheme.assetManifestSha !== assetManifestSha) return null;
-	return {
-		sourceThemeId: config.themeId,
-		remoteSha: devTheme.remoteSha
-	};
+/** Whether this invocation may read and persist the dev remote baseline. */
+function devRemoteBaselineEnabled(explicitTheme) {
+	return !explicitTheme && process.env["FLUID_THEME_DEV_DISABLE_SHADOW_SYNC"] !== "1";
 }
 /**
 * Create the isolated theme used by `theme dev`.
@@ -3482,21 +3586,30 @@ function devShadowTrust(config, devTheme, assetManifestSha) {
 */
 async function createDevelopmentTheme(api, sourceThemeId, name) {
 	if (sourceThemeId !== void 0) try {
-		return (await cloneApplicationThemeForDevelopment(api, sourceThemeId, { application_theme: { name } })).application_theme;
+		return {
+			theme: (await cloneApplicationThemeForDevelopment(api, sourceThemeId, { application_theme: { name } })).application_theme,
+			referenceCloned: true
+		};
 	} catch (error) {
 		if (!isApiError(error) || error.status !== 404 && error.status !== 405) throw error;
 		console.warn("Server-side theme cloning is unavailable; falling back to an empty development theme. The first sync may take longer.");
 	}
-	return (await createApplicationTheme(api, { application_theme: {
-		name,
-		status: "development"
-	} })).application_theme;
+	return {
+		theme: (await createApplicationTheme(api, { application_theme: {
+			name,
+			status: "development"
+		} })).application_theme,
+		referenceCloned: false
+	};
 }
-async function ensureDevTheme(api, projectKey, identifier, sourceThemeId, sourceBaseSha, sourceAssetManifestSha) {
+async function ensureDevTheme(api, projectKey, identifier, sourceThemeId) {
 	if (identifier) {
 		const theme = await findTheme(api, identifier);
 		setLastDevThemeId(theme.id);
-		return theme;
+		return {
+			theme,
+			referenceCloned: false
+		};
 	}
 	const stored = getDevTheme(projectKey);
 	if (stored && stored.sourceThemeId === sourceThemeId) {
@@ -3510,25 +3623,24 @@ async function ensureDevTheme(api, projectKey, identifier, sourceThemeId, source
 					name: existing.name,
 					...sourceThemeId === void 0 ? {} : { sourceThemeId }
 				});
-				return existing;
+				return {
+					theme: existing,
+					referenceCloned: false
+				};
 			}
 		} catch {}
 		clearDevTheme(projectKey);
 	}
 	const { hostname } = await import("node:os");
-	const theme = await createDevelopmentTheme(api, sourceThemeId, `Development (${hostname().split(".")[0] ?? "dev"}-${Math.random().toString(36).slice(2, 8)})`.slice(0, 50));
+	const creation = await createDevelopmentTheme(api, sourceThemeId, `Development (${hostname().split(".")[0] ?? "dev"}-${Math.random().toString(36).slice(2, 8)})`.slice(0, 50));
+	const { theme } = creation;
 	setDevTheme(projectKey, {
 		id: theme.id,
 		name: theme.name,
-		...sourceThemeId === void 0 ? {} : { sourceThemeId },
-		...sourceThemeId !== void 0 && sourceBaseSha ? {
-			sourceBaseSha,
-			remoteSha: sourceBaseSha
-		} : {},
-		...sourceAssetManifestSha ? { assetManifestSha: sourceAssetManifestSha } : {}
+		...sourceThemeId === void 0 ? {} : { sourceThemeId }
 	});
 	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
-	return theme;
+	return creation;
 }
 function createDevCommand() {
 	return new Command("dev").description("Start the theme dev server with hot reload").option("--host <host>", "Local server host", "127.0.0.1").option("--port <port>", "Local server port", "9292").option("-t, --theme <name-or-id>", "Use an existing theme instead of dev theme").option("-f, --force", "Skip schema validation on upload").option("--live-reload <mode>", "Reload mode: full-page | off", "full-page").option("--navigate", "Open browser navigator after server starts").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
@@ -3568,31 +3680,16 @@ function createDevCommand() {
 			}
 		}
 		const projectKey = devThemeKey(company, themeRoot.root);
-		const theme = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey, void 0, config?.themeId, config?.baseSha, config?.assetManifestSha);
-		const devTheme = opts.theme ? void 0 : getDevTheme(projectKey);
+		const devTarget = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey, void 0, config?.themeId);
+		const { theme } = devTarget;
 		const assetManifest = new ThemeAssetManifest(themeRoot.root);
-		const trust = opts.theme ? null : devShadowTrust(config, devTheme, assetManifest.fingerprint());
-		let initialSync;
-		if (trust) {
-			const shadow = await ShadowRepo.open(themeRoot.root, trust.sourceThemeId);
-			if (await shadow.hasHead()) initialSync = {
-				shadow,
-				remoteSha: trust.remoteSha
-			};
-		}
-		let rememberRemoteSha;
-		if (!opts.theme && config?.baseSha && devTheme) {
-			const sourceBaseSha = config.baseSha;
-			let rememberedDevTheme = devTheme;
-			rememberRemoteSha = (remoteSha) => {
-				rememberedDevTheme = {
-					...rememberedDevTheme,
-					sourceBaseSha,
-					remoteSha,
-					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint()
-				};
-				setDevTheme(projectKey, rememberedDevTheme);
-			};
+		const baselineEnabled = devRemoteBaselineEnabled(Boolean(opts.theme));
+		let initialRemoteState = baselineEnabled ? readDevRemoteBaseline(themeRoot.root, theme.id, assetManifest.fingerprint()) : null;
+		if (!initialRemoteState && baselineEnabled && devTarget.referenceCloned && config?.themeId && config.baseSha) try {
+			initialRemoteState = await devRemoteStateFromSourceShadow(themeRoot, await ShadowRepo.open(themeRoot.root, config.themeId), theme.id, config.baseSha);
+			if (initialRemoteState) writeDevRemoteBaseline(themeRoot.root, initialRemoteState);
+		} catch {
+			initialRemoteState = null;
 		}
 		const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
 		let stop;
@@ -3612,8 +3709,11 @@ function createDevCommand() {
 			port,
 			reloadMode,
 			validate: !opts.force,
-			...initialSync ? { initialSync } : {},
-			...rememberRemoteSha ? { onRemoteSha: rememberRemoteSha } : {}
+			...initialRemoteState ? { initialSync: initialRemoteState } : {},
+			...baselineEnabled ? {
+				onRemoteState: (state) => writeDevRemoteBaseline(themeRoot.root, state),
+				onRemoteStateInvalidated: () => removeDevRemoteBaseline(themeRoot.root)
+			} : {}
 		}, (address) => {
 			console.log(`\n  Dev server: ${address}`);
 			console.log(`  Web editor: ${editorUrl}`);
@@ -3624,6 +3724,133 @@ function createDevCommand() {
 	});
 }
 //#endregion
+//#region src/theme/merge-push.ts
+/**
+* Compute what changed locally since the last time the shadow repo
+* committed a state. Replaces the sha256 `checksums` map: shadow HEAD
+* is the source of truth for "what the CLI last saw the server have".
+*
+* Files whose local bytes are byte-identical to their HEAD blob are
+* skipped; anything else — new, modified, or a locally-deleted path
+* that HEAD still has — is included.
+*/
+async function diffAgainstShadow(themeRoot, shadow) {
+	const changed = [];
+	const deleted = [];
+	const localFiles = themeRoot.files();
+	const localByKey = /* @__PURE__ */ new Map();
+	const assetManifest = new ThemeAssetManifest(themeRoot.root);
+	let headPaths;
+	try {
+		headPaths = await shadow.headPaths();
+	} catch (error) {
+		throw new Error("Could not read the local theme shadow", { cause: error });
+	}
+	assertNoCaseCollisions([...localFiles.map((file) => file.relativePath), ...headPaths]);
+	const headPathSet = new Set(headPaths);
+	for (const file of localFiles) {
+		if (!file.exists) continue;
+		localByKey.set(file.relativePath, file);
+		const headBlob = await shadow.blobAtHead(file.relativePath);
+		if (!headBlob && headPathSet.has(file.relativePath)) throw new Error(`Could not read the local theme shadow: ${file.relativePath}`);
+		const localBuf = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		if (headBlob && headBlob.equals(localBuf)) continue;
+		changed.push(file);
+	}
+	for (const key of headPaths) {
+		if (localByKey.has(key)) continue;
+		if (themeRoot.ignore.ignore(key)) continue;
+		if (assetManifest.has(key)) continue;
+		if (isStylesheetKey(key)) continue;
+		deleted.push(key);
+	}
+	return {
+		changed,
+		deleted
+	};
+}
+/**
+* Refuse a push when any working file still contains a conflict marker
+* from a previous pull. Mirrors git's "you have unresolved conflicts;
+* fix them and re-run" behavior — the whole point of writing markers
+* on pull was to hand resolution to the user, so we can't send them
+* upstream.
+*/
+function findUnresolvedConflicts(files) {
+	const flagged = [];
+	for (const file of files) {
+		if (!file.isText) continue;
+		const buf = readIfExists(file.absolutePath);
+		if (!buf) continue;
+		if (containsConflictMarker(buf)) flagged.push(file.relativePath);
+	}
+	return flagged;
+}
+/**
+* Stable, machine-readable one-liner for non-interactive callers
+* (Mist Desktop's publish flow parses push output). Uploading marker-
+* bearing files to a live theme is never acceptable, so `--auto-
+* baseline` pushes still refuse — but they emit this line so the
+* desktop can surface WHICH files block the publish instead of a
+* dead-end wall of prose. Format:
+*
+*   FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=a.liquid,b.json
+*/
+function conflictMarkerBlockLine(files) {
+	return `FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=${files.join(",")}`;
+}
+const CONFLICT_START = Buffer.from("<<<<<<<");
+const CONFLICT_MID = Buffer.from("=======");
+const CONFLICT_END = Buffer.from(">>>>>>>");
+/**
+* A file counts as unresolved when it contains all three marker
+* shapes: `<<<<<<<`, `=======`, and `>>>>>>>`. Requiring all three
+* avoids false positives — a line of equals signs alone (e.g. inside
+* an ASCII table in a template comment) doesn't trip the guard.
+*/
+function containsConflictMarker(buf) {
+	return buf.includes(CONFLICT_START) && buf.includes(CONFLICT_MID) && buf.includes(CONFLICT_END);
+}
+/**
+* Commit the current working-tree state to shadow HEAD after a
+* successful push. Ensures the next pull's merge base is the state
+* we know the server just accepted.
+*/
+async function commitPushedState(themeRoot, shadow, message) {
+	const entries = [];
+	const assetManifest = new ThemeAssetManifest(themeRoot.root);
+	const localKeys = /* @__PURE__ */ new Set();
+	for (const file of themeRoot.files()) {
+		if (!file.exists) continue;
+		localKeys.add(file.relativePath);
+		const buf = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		entries.push({
+			path: file.relativePath,
+			sha: await shadow.writeBlob(buf)
+		});
+	}
+	let managedAssetSentinelSha;
+	for (const key of assetManifest.keys()) {
+		if (localKeys.has(key)) continue;
+		managedAssetSentinelSha ??= await shadow.writeBlob(MANAGED_ASSET_SHADOW_SENTINEL);
+		entries.push({
+			path: key,
+			sha: managedAssetSentinelSha
+		});
+	}
+	if (entries.length > 0 || await shadow.hasHead()) await shadow.commitState(entries, message);
+}
+/**
+* A target can already have every URL-backed FileResource (for example from a
+* reference clone), while this checkout's manifest still names its old source
+* theme. Adopt the target and clear any legacy binary from shadow even though
+* no remote write was necessary.
+*/
+async function finalizeManifestOnlyPush(syncer, themeRoot, shadow) {
+	syncer.repointManagedAssetsToCurrentTheme();
+	await commitPushedState(themeRoot, shadow, `push @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+}
+//#endregion
 //#region src/theme/auto-baseline.ts
 /**
 * `fluid theme push --auto-baseline`: when a theme directory has no
@@ -4305,7 +4532,11 @@ function createPullCommand() {
 		const syncer = new Syncer(api, theme.id, themeRoot);
 		const actorPromise = fetchSyncActor(api);
 		const spinner = ora(`Pulling ${theme.name} (#${theme.id})…`).start();
-		const resources = await syncer.downloadAll();
+		const resources = await syncer.downloadAll().catch((error) => {
+			if (!(error instanceof CaseCollisionError)) throw error;
+			spinner.fail(error.message);
+			process.exit(1);
+		});
 		const externalizedAssets = await syncer.externalizePulledAssets(resources, { delete: !opts.nodelete });
 		const result = await mergePull({
 			themeRoot,