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

package/dist/index.mjs

@@ -7,11 +7,11 @@ 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 chalk from "chalk";
 import prompts from "prompts";
 import ora from "ora";
-import { execFileSync, spawn } from "node:child_process";
-import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region ../../platform/api-client-core/src/api-error-shape.ts
 /**
@@ -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;
@@ -1487,6 +1509,15 @@ var ThemeAssetManifest = class {
 	entries() {
 		return Object.entries(this.assets).map(([key, link]) => [key, copyLink(link)]);
 	}
+	/**
+	* Stable digest of the URL references represented by this manifest.
+	* Pull baselines exclude pending entries because those belong only to an
+	* existing dev target and are deliberately absent from the pulled source.
+	*/
+	fingerprint(opts = {}) {
+		const entries = this.entries().filter(([, link]) => !opts.excludePending || !link.pending).toSorted(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+		return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+	}
 	has(key) {
 		return this.assets[key] !== void 0;
 	}
@@ -1525,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}`);
@@ -1569,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
@@ -1610,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) {
@@ -1626,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()`
@@ -1635,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) {
@@ -1681,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);
@@ -1695,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;
@@ -1761,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);
@@ -1916,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}`);
@@ -2117,7 +2180,7 @@ var Syncer = class {
 			const response = await deleteThemeResource(this.api, this.themeId, body);
 			if (response.content_version_sha) this.lastKnownRemoteSha = response.content_version_sha;
 		} catch (e) {
-			throw this.rethrowIfConflict(e);
+			if (!isNotFoundError(e)) throw this.rethrowIfConflict(e);
 		}
 		this.removeRemoteResource(relativePath);
 	}
@@ -2126,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) {
@@ -2260,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,
@@ -2279,8 +2344,9 @@ var Syncer = class {
 				return result;
 			}
 		}
-		await this.fetchChecksums();
-		await this.preflightPush(opts.baseSha);
+		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) {
 			result.linked = await this.linkManagedAssets(opts.linkManagedAssets);
@@ -2305,7 +2371,7 @@ var Syncer = class {
 		if (opts.delete) {
 			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) => !localPaths.has(key) && !this.themeRoot.ignore.ignore(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;
@@ -2383,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;
 }
@@ -2418,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"]);
@@ -2440,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) {
@@ -2455,7 +2541,7 @@ 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
@@ -2642,17 +2728,58 @@ function timestamp() {
 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 pendingUpdates = /* @__PURE__ */ new Set();
 	console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
-	const syncResult = await syncer.uploadTheme({
+	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: (done, total) => {
-			process.stdout.write(`\r  Uploading ${done}/${total} files…`);
-		}
+		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) {
@@ -2660,17 +2787,28 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 		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 () => {
-			askOwed = !await syncer.requestSync();
+			const accepted = await syncer.requestSync();
+			askOwed = !accepted;
+			if (accepted) recordRemoteState();
 		});
 	};
 	const flushSyncNow = () => {
@@ -2698,7 +2836,15 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 			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;
+		}
 		const changed = [...modified, ...added];
+		let wroteRemote = false;
 		for (const file of changed) {
 			if (opts.validate && file.isLiquid) {
 				const diagnostics = file.validateSchema();
@@ -2709,23 +2855,39 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 			}
 			pendingUpdates.add(file.relativePath);
 			try {
-				const uploadedContent = await syncer.uploadFile(file, void 0, { pendingAsset: true });
+				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);
+				await syncer.deleteRemoteFile(file.relativePath, syncer.remoteSha());
+				wroteRemote = true;
 				console.log(`  ✓ removed ${file.relativePath}`);
-			} catch {}
+			} 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();
@@ -2773,302 +2935,155 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 	};
 }
 //#endregion
-//#region src/theme-picker.ts
-const PAGE_SIZE = 50;
-const LOAD_MORE_VALUE = -1;
-function themeLabel(t) {
-	const active = t.status === "active" ? ` ${chalk.green("[active]")}` : "";
-	return `${t.name} (#${t.id})${active}`;
-}
-function themeChoices(themeList, hasMore) {
-	const choices = themeList.map((t) => ({
-		title: themeLabel(t),
-		value: t.id
-	}));
-	if (hasMore) choices.push({
-		title: chalk.dim(`── Load more themes ──`),
-		value: LOAD_MORE_VALUE
-	});
-	return choices;
+//#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;
+	}
 }
-async function fetchThemesPage(api, page, searchQuery) {
-	const body = await listApplicationThemes(api, {
-		per_page: PAGE_SIZE,
-		page,
-		...searchQuery ? { search_query: searchQuery } : {}
-	});
-	return {
-		themes: body.application_themes ?? [],
-		hasMore: page < (body.meta?.total_pages ?? 1)
+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
+		});
+		renameSync(tempPath, path);
+	} catch (error) {
+		rmSync(tempPath, { force: true });
+		throw error;
+	}
 }
-async function selectTheme(api, message) {
-	const allThemes = [];
-	let page = 1;
-	let hasMore = true;
-	let initialIndex = 0;
-	let searchQuery = "";
-	let searchResults = [];
-	while (true) {
-		if (hasMore && allThemes.length < page * PAGE_SIZE) {
-			const result = await fetchThemesPage(api, page);
-			allThemes.push(...result.themes);
-			hasMore = result.hasMore;
-		}
-		if (!allThemes.length) {
-			console.error("No themes found.");
-			process.exit(1);
-		}
-		const choices = themeChoices(allThemes, hasMore);
-		const { id } = await prompts({
-			type: "autocomplete",
-			name: "id",
-			message,
-			initial: initialIndex,
-			choices,
-			suggest: async (input, choices) => {
-				if (!input) {
-					searchQuery = "";
-					searchResults = [];
-					return choices;
-				}
-				if (input !== searchQuery) {
-					searchQuery = input;
-					try {
-						searchResults = (await fetchThemesPage(api, 1, input)).themes;
-					} catch {
-						searchResults = [];
-					}
-				}
-				return searchResults.map((t) => ({
-					title: themeLabel(t),
-					value: t.id
-				}));
+function removeDevRemoteBaseline(themeRoot) {
+	rmSync(join(themeRoot, BASELINE_FILE), { force: true });
+}
+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;
 			}
-		}, { onCancel: () => process.exit(130) });
-		if (id === LOAD_MORE_VALUE) {
-			initialIndex = allThemes.length;
-			page++;
-			continue;
-		}
-		if (!id) {
-			console.error("No theme selected.");
-			process.exit(1);
+			if (content.equals(Buffer.from("fluid-managed-asset\n"))) return null;
+			resources.push({
+				key,
+				checksum: createHash("sha256").update(content).digest("hex"),
+				contentPresent: true
+			});
 		}
-		const found = allThemes.find((t) => t.id === id) ?? searchResults.find((t) => t.id === id);
-		if (found) return found;
-		return (await getApplicationTheme(api, id)).application_theme;
+		return {
+			themeId,
+			remoteSha,
+			assetManifestSha: assetManifest.fingerprint(),
+			resources
+		};
+	} catch {
+		return null;
 	}
 }
-async function findTheme(api, identifier) {
-	const idNum = Number(identifier);
-	if (Number.isInteger(idNum) && idNum > 0) try {
-		const body = await getApplicationTheme(api, idNum);
-		if (body.application_theme) return body.application_theme;
-	} catch {}
-	let page = 1;
-	let hasMore = true;
-	while (hasMore) {
-		const result = await fetchThemesPage(api, page, identifier);
-		const found = result.themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
-		if (found) return found;
-		hasMore = result.hasMore;
-		page++;
-	}
-	console.error(`No theme found with identifier: ${identifier}`);
-	process.exit(1);
+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
+	};
 }
-//#endregion
-//#region src/workspace.ts
-const WORKSPACE_FILE = ".fluid-workspace.json";
-/**
-* Walk up from `startDir` looking for `.fluid-workspace.json`.
-* Returns the workspace info if found, or `null` if not in a workspace.
-*/
-function findWorkspace(startDir) {
-	let dir = resolve(startDir ?? process.cwd());
-	while (true) {
-		const candidate = join(dir, WORKSPACE_FILE);
-		if (existsSync(candidate)) try {
-			const raw = readFileSync(candidate, "utf-8");
-			const config = JSON.parse(raw);
-			return {
-				root: dir,
-				config
-			};
-		} catch {
-			return null;
-		}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return null;
+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
+	};
 }
-/**
-* If cwd is already inside `{workspace}/local/{company}/...`, return that
-* theme root directory. Otherwise return null.
-*
-* Examples (workspace root = /code/fluid-theme-dev):
-*   cwd = /code/fluid-theme-dev/local/acme-co           → /code/fluid-theme-dev/local/acme-co
-*   cwd = /code/fluid-theme-dev/local/acme-co/templates  → /code/fluid-theme-dev/local/acme-co
-*   cwd = /code/fluid-theme-dev                          → null
-*   cwd = /code/fluid-theme-dev/local                    → null
-*/
-function resolveThemeRootFromCwd(workspace) {
-	const cwd = resolve(process.cwd());
-	const localDir = join(workspace.root, "local");
-	const rel = relative(localDir, cwd);
-	if (rel.startsWith("..") || rel === ".") return null;
-	const firstSegment = rel.split(sep)[0];
-	if (!firstSegment) return null;
-	return join(localDir, firstSegment);
+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/commands/dev.ts
+//#region src/theme/shadow-repo.ts
 /**
-* Create the isolated theme used by `theme dev`.
+* 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.
 *
-* A checkout from `theme pull` has a source theme id. New servers clone that
-* source by reference, preserving its DAM/ImageKit assets without moving
-* bytes. A 404/405 keeps older deployments compatible with the established
-* empty-theme flow; other failures must remain visible to the developer.
+* 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.
 */
-async function createDevelopmentTheme(api, sourceThemeId, name) {
-	if (sourceThemeId !== void 0) try {
-		return (await cloneApplicationThemeForDevelopment(api, sourceThemeId, { application_theme: { name } })).application_theme;
-	} 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;
-}
-async function ensureDevTheme(api, projectKey, identifier, sourceThemeId) {
-	if (identifier) {
-		const theme = await findTheme(api, identifier);
-		setLastDevThemeId(theme.id);
-		return theme;
-	}
-	const stored = getDevTheme(projectKey);
-	if (stored && stored.sourceThemeId === sourceThemeId) {
-		try {
-			const existing = (await getApplicationTheme(api, stored.id)).application_theme;
-			if (existing && existing.status === "development") {
-				console.log(`Using existing dev theme #${existing.id}`);
-				setDevTheme(projectKey, {
-					id: existing.id,
-					name: existing.name,
-					...sourceThemeId === void 0 ? {} : { sourceThemeId }
-				});
-				return existing;
-			}
-		} 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));
-	setDevTheme(projectKey, {
-		id: theme.id,
-		name: theme.name,
-		...sourceThemeId === void 0 ? {} : { sourceThemeId }
-	});
-	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
-	return theme;
-}
-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) => {
-		requireToken();
-		let rootPath = opts.root;
-		if (rootPath === ".") {
-			const workspace = findWorkspace();
-			if (workspace) rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
-		}
-		const themeRoot = new ThemeRoot(rootPath);
-		if (!themeRoot.isValid()) {
-			console.error(`'${rootPath}' does not look like a theme directory.`);
-			process.exit(1);
-		}
-		const port = Number(opts.port);
-		if (!Number.isInteger(port) || port < 1 || port > 65535) {
-			console.error(`Invalid port: '${opts.port}'. Must be an integer between 1 and 65535.`);
-			process.exit(1);
-		}
-		try {
-			await checkPortAvailable(opts.host, port);
-		} catch (e) {
-			if (e instanceof PortInUseError) console.error(e.message);
-			else console.error(`Failed to check port availability: ${e}`);
-			process.exit(1);
-		}
-		const reloadMode = opts.liveReload === "off" ? "off" : "full-page";
-		const api = createApiClient();
-		const config = readThemeConfig(themeRoot.root);
-		let company;
-		if (config?.company) company = config.company;
-		else {
-			company = (await api.get("/api/company/v1/companies/me")).data?.company?.subdomain ?? "";
-			if (!company) {
-				console.error("Could not determine company subdomain. Make sure your token is valid.");
-				process.exit(1);
-			}
-		}
-		const projectKey = devThemeKey(company, themeRoot.root);
-		const theme = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey, void 0, config?.themeId);
-		const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
-		let stop;
-		const cleanup = () => {
-			stop?.();
-			process.exit(0);
-		};
-		process.on("SIGINT", cleanup);
-		process.on("SIGTERM", cleanup);
-		stop = await startDevServer(api, {
-			id: theme.id,
-			name: theme.name,
-			company,
-			editorUrl
-		}, themeRoot, {
-			host: opts.host,
-			port,
-			reloadMode,
-			validate: !opts.force
-		}, (address) => {
-			console.log(`\n  Dev server: ${address}`);
-			console.log(`  Web editor: ${editorUrl}`);
-			console.log("\n  Watching for file changes…\n");
-			if (opts.navigate) import("open").then((m) => m.default(`${address}/home`));
-		});
-		await new Promise(() => {});
-	});
-}
-//#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;
+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.
@@ -3404,6 +3419,311 @@ async function ensureRootGitignoreHidesShadow(themeRoot) {
 	writeFileSync(gitignorePath, `${existing}${separator}.fluid-theme/\n`, "utf-8");
 }
 //#endregion
+//#region src/theme-picker.ts
+const PAGE_SIZE = 50;
+const LOAD_MORE_VALUE = -1;
+function themeLabel(t) {
+	const active = t.status === "active" ? ` ${chalk.green("[active]")}` : "";
+	return `${t.name} (#${t.id})${active}`;
+}
+function themeChoices(themeList, hasMore) {
+	const choices = themeList.map((t) => ({
+		title: themeLabel(t),
+		value: t.id
+	}));
+	if (hasMore) choices.push({
+		title: chalk.dim(`── Load more themes ──`),
+		value: LOAD_MORE_VALUE
+	});
+	return choices;
+}
+async function fetchThemesPage(api, page, searchQuery) {
+	const body = await listApplicationThemes(api, {
+		per_page: PAGE_SIZE,
+		page,
+		...searchQuery ? { search_query: searchQuery } : {}
+	});
+	return {
+		themes: body.application_themes ?? [],
+		hasMore: page < (body.meta?.total_pages ?? 1)
+	};
+}
+async function selectTheme(api, message) {
+	const allThemes = [];
+	let page = 1;
+	let hasMore = true;
+	let initialIndex = 0;
+	let searchQuery = "";
+	let searchResults = [];
+	while (true) {
+		if (hasMore && allThemes.length < page * PAGE_SIZE) {
+			const result = await fetchThemesPage(api, page);
+			allThemes.push(...result.themes);
+			hasMore = result.hasMore;
+		}
+		if (!allThemes.length) {
+			console.error("No themes found.");
+			process.exit(1);
+		}
+		const choices = themeChoices(allThemes, hasMore);
+		const { id } = await prompts({
+			type: "autocomplete",
+			name: "id",
+			message,
+			initial: initialIndex,
+			choices,
+			suggest: async (input, choices) => {
+				if (!input) {
+					searchQuery = "";
+					searchResults = [];
+					return choices;
+				}
+				if (input !== searchQuery) {
+					searchQuery = input;
+					try {
+						searchResults = (await fetchThemesPage(api, 1, input)).themes;
+					} catch {
+						searchResults = [];
+					}
+				}
+				return searchResults.map((t) => ({
+					title: themeLabel(t),
+					value: t.id
+				}));
+			}
+		}, { onCancel: () => process.exit(130) });
+		if (id === LOAD_MORE_VALUE) {
+			initialIndex = allThemes.length;
+			page++;
+			continue;
+		}
+		if (!id) {
+			console.error("No theme selected.");
+			process.exit(1);
+		}
+		const found = allThemes.find((t) => t.id === id) ?? searchResults.find((t) => t.id === id);
+		if (found) return found;
+		return (await getApplicationTheme(api, id)).application_theme;
+	}
+}
+async function findTheme(api, identifier) {
+	const idNum = Number(identifier);
+	if (Number.isInteger(idNum) && idNum > 0) try {
+		const body = await getApplicationTheme(api, idNum);
+		if (body.application_theme) return body.application_theme;
+	} catch {}
+	let page = 1;
+	let hasMore = true;
+	while (hasMore) {
+		const result = await fetchThemesPage(api, page, identifier);
+		const found = result.themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
+		if (found) return found;
+		hasMore = result.hasMore;
+		page++;
+	}
+	console.error(`No theme found with identifier: ${identifier}`);
+	process.exit(1);
+}
+//#endregion
+//#region src/workspace.ts
+const WORKSPACE_FILE = ".fluid-workspace.json";
+/**
+* Walk up from `startDir` looking for `.fluid-workspace.json`.
+* Returns the workspace info if found, or `null` if not in a workspace.
+*/
+function findWorkspace(startDir) {
+	let dir = resolve(startDir ?? process.cwd());
+	while (true) {
+		const candidate = join(dir, WORKSPACE_FILE);
+		if (existsSync(candidate)) try {
+			const raw = readFileSync(candidate, "utf-8");
+			const config = JSON.parse(raw);
+			return {
+				root: dir,
+				config
+			};
+		} catch {
+			return null;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* If cwd is already inside `{workspace}/local/{company}/...`, return that
+* theme root directory. Otherwise return null.
+*
+* Examples (workspace root = /code/fluid-theme-dev):
+*   cwd = /code/fluid-theme-dev/local/acme-co           → /code/fluid-theme-dev/local/acme-co
+*   cwd = /code/fluid-theme-dev/local/acme-co/templates  → /code/fluid-theme-dev/local/acme-co
+*   cwd = /code/fluid-theme-dev                          → null
+*   cwd = /code/fluid-theme-dev/local                    → null
+*/
+function resolveThemeRootFromCwd(workspace) {
+	const cwd = resolve(process.cwd());
+	const localDir = join(workspace.root, "local");
+	const rel = relative(localDir, cwd);
+	if (rel.startsWith("..") || rel === ".") return null;
+	const firstSegment = rel.split(sep)[0];
+	if (!firstSegment) return null;
+	return join(localDir, firstSegment);
+}
+//#endregion
+//#region src/commands/dev.ts
+/** 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`.
+*
+* A checkout from `theme pull` has a source theme id. New servers clone that
+* source by reference, preserving its DAM/ImageKit assets without moving
+* bytes. A 404/405 keeps older deployments compatible with the established
+* empty-theme flow; other failures must remain visible to the developer.
+*/
+async function createDevelopmentTheme(api, sourceThemeId, name) {
+	if (sourceThemeId !== void 0) try {
+		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 {
+		theme: (await createApplicationTheme(api, { application_theme: {
+			name,
+			status: "development"
+		} })).application_theme,
+		referenceCloned: false
+	};
+}
+async function ensureDevTheme(api, projectKey, identifier, sourceThemeId) {
+	if (identifier) {
+		const theme = await findTheme(api, identifier);
+		setLastDevThemeId(theme.id);
+		return {
+			theme,
+			referenceCloned: false
+		};
+	}
+	const stored = getDevTheme(projectKey);
+	if (stored && stored.sourceThemeId === sourceThemeId) {
+		try {
+			const existing = (await getApplicationTheme(api, stored.id)).application_theme;
+			if (existing && existing.status === "development") {
+				console.log(`Using existing dev theme #${existing.id}`);
+				setDevTheme(projectKey, {
+					...stored,
+					id: existing.id,
+					name: existing.name,
+					...sourceThemeId === void 0 ? {} : { sourceThemeId }
+				});
+				return {
+					theme: existing,
+					referenceCloned: false
+				};
+			}
+		} catch {}
+		clearDevTheme(projectKey);
+	}
+	const { hostname } = await import("node:os");
+	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 }
+	});
+	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
+	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) => {
+		requireToken();
+		let rootPath = opts.root;
+		if (rootPath === ".") {
+			const workspace = findWorkspace();
+			if (workspace) rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
+		}
+		const themeRoot = new ThemeRoot(rootPath);
+		if (!themeRoot.isValid()) {
+			console.error(`'${rootPath}' does not look like a theme directory.`);
+			process.exit(1);
+		}
+		const port = Number(opts.port);
+		if (!Number.isInteger(port) || port < 1 || port > 65535) {
+			console.error(`Invalid port: '${opts.port}'. Must be an integer between 1 and 65535.`);
+			process.exit(1);
+		}
+		try {
+			await checkPortAvailable(opts.host, port);
+		} catch (e) {
+			if (e instanceof PortInUseError) console.error(e.message);
+			else console.error(`Failed to check port availability: ${e}`);
+			process.exit(1);
+		}
+		const reloadMode = opts.liveReload === "off" ? "off" : "full-page";
+		const api = createApiClient();
+		const config = readThemeConfig(themeRoot.root);
+		let company;
+		if (config?.company) company = config.company;
+		else {
+			company = (await api.get("/api/company/v1/companies/me")).data?.company?.subdomain ?? "";
+			if (!company) {
+				console.error("Could not determine company subdomain. Make sure your token is valid.");
+				process.exit(1);
+			}
+		}
+		const projectKey = devThemeKey(company, themeRoot.root);
+		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 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;
+		const cleanup = () => {
+			stop?.();
+			process.exit(0);
+		};
+		process.on("SIGINT", cleanup);
+		process.on("SIGTERM", cleanup);
+		stop = await startDevServer(api, {
+			id: theme.id,
+			name: theme.name,
+			company,
+			editorUrl
+		}, themeRoot, {
+			host: opts.host,
+			port,
+			reloadMode,
+			validate: !opts.force,
+			...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}`);
+			console.log("\n  Watching for file changes…\n");
+			if (opts.navigate) import("open").then((m) => m.default(`${address}/home`));
+		});
+		await new Promise(() => {});
+	});
+}
+//#endregion
 //#region src/theme/merge-push.ts
 /**
 * Compute what changed locally since the last time the shadow repo
@@ -3420,15 +3740,24 @@ async function diffAgainstShadow(themeRoot, shadow) {
 	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);
 	}
-	if (await shadow.hasHead()) for (const key of await listHeadPaths(shadow)) {
+	for (const key of headPaths) {
 		if (localByKey.has(key)) continue;
 		if (themeRoot.ignore.ignore(key)) continue;
 		if (assetManifest.has(key)) continue;
@@ -3441,15 +3770,6 @@ async function diffAgainstShadow(themeRoot, shadow) {
 	};
 }
 /**
-* 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
@@ -3917,7 +4237,8 @@ function createPushCommand() {
 					themeId: theme.id,
 					themeName: theme.name,
 					company: config.company,
-					baseSha: baseSha ?? void 0
+					baseSha: baseSha ?? void 0,
+					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint({ excludePending: true })
 				});
 				return;
 			}
@@ -3929,7 +4250,8 @@ function createPushCommand() {
 					themeId: theme.id,
 					themeName: theme.name,
 					company: subdomain,
-					baseSha: baseSha ?? void 0
+					baseSha: baseSha ?? void 0,
+					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint({ excludePending: true })
 				});
 			} catch {}
 		}
@@ -4210,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,
@@ -4252,7 +4578,8 @@ function createPullCommand() {
 			themeId: theme.id,
 			themeName: theme.name,
 			company: subdomain,
-			baseSha: remoteSha ?? existingConfig?.baseSha
+			baseSha: remoteSha ?? existingConfig?.baseSha,
+			assetManifestSha: new ThemeAssetManifest(absoluteRoot).fingerprint({ excludePending: true })
 		});
 		if (result.conflicts.length > 0) process.exit(1);
 	});