@fluid-app/fluid-cli-theme-dev 0.1.38 → 0.1.39

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { getAuthToken, readConfig, updateConfig } from "@fluid-app/fluid-cli";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import chokidar from "chokidar";
@@ -13,19 +13,50 @@ 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
+/**
+* Narrows a parsed JSON error payload to the envelope contract. Arrays and
+* primitives are not envelopes, so they resolve to `null` — their content is
+* still reachable through `ApiError.data`.
+*/
+function toApiErrorBody(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+/**
+* The single unwrap rule, shared by every producer of `ApiError`.
+*
+* `??` rather than `||` so an explicitly empty `errors` (`""`, `0`, `false`)
+* is preserved instead of silently falling back to the whole envelope.
+*/
+function toApiErrorData(body) {
+	if (!body) return null;
+	return body.errors ?? body;
+}
+//#endregion
 //#region ../../platform/api-client-core/src/fetch-client.ts
 /**
 * API Error class compatible with fluid-admin's ApiError
 */
 var ApiError = class ApiError extends Error {
 	status;
+	/**
+	* The unwrapped field-error bag. See `ApiErrorData`; the contract is
+	* documented in `docs/api-error-data-contract.md`.
+	*/
 	data;
+	/**
+	* The full error response envelope. Read `error_message`, `error`, `status`
+	* and nested `errors` from here — `data` has already unwrapped one level.
+	*/
+	body;
 	requestId;
-	constructor(message, status, data, requestId) {
+	constructor(message, status, data, requestId, body) {
 		super(message);
 		this.name = "ApiError";
 		this.status = status;
-		this.data = data;
+		this.data = data ?? null;
+		this.body = body ?? null;
 		this.requestId = requestId;
 		if ("captureStackTrace" in Error) Error.captureStackTrace(this, ApiError);
 	}
@@ -35,6 +66,7 @@ var ApiError = class ApiError extends Error {
 			message: this.message,
 			status: this.status,
 			data: this.data,
+			body: this.body,
 			requestId: this.requestId
 		};
 	}
@@ -121,14 +153,20 @@ function createFetchClient(config) {
 		if (!response.ok) {
 			const errorText = await response.text().catch(() => "");
 			if (response.headers.get("content-type")?.includes("application/json")) {
-				let data;
+				let parsed;
 				try {
-					data = JSON.parse(errorText);
+					parsed = JSON.parse(errorText);
 				} catch {
 					throw new ApiError(errorText.slice(0, 200) || `${method} request failed with status ${response.status}`, response.status, null, headerRequestId);
 				}
-				const nestedError = typeof data.error === "object" && data.error !== null ? data.error.message : void 0;
-				throw new ApiError(data.message || data.error_message || (typeof nestedError === "string" ? nestedError : void 0) || `${method} request failed`, response.status, data.errors || data, headerRequestId ?? getRequestIdFromJsonBody(data));
+				const body = toApiErrorBody(parsed);
+				throw new ApiError((body ? (() => {
+					const nestedError = typeof body.error === "object" && body.error !== null ? body.error.message : void 0;
+					const directError = typeof body.error === "string" ? body.error : void 0;
+					const message = typeof body.message === "string" ? body.message : void 0;
+					const errorMessage = typeof body.error_message === "string" ? body.error_message : void 0;
+					return message || errorMessage || directError || (typeof nestedError === "string" ? nestedError : void 0);
+				})() : void 0) || `${method} request failed with status ${response.status}`, response.status, body ? toApiErrorData(body) : parsed, headerRequestId ?? getRequestIdFromJsonBody(parsed), body);
 			} else throw new ApiError(`${method} request failed with status ${response.status}`, response.status, null, headerRequestId);
 		}
 		if (response.status === 204 || response.headers.get("content-length") === "0") return null;
@@ -264,6 +302,16 @@ function requireToken() {
 //#endregion
 //#region src/theme-config.ts
 const CONFIG_FILE = ".fluid-theme.json";
+/**
+* `company` must be the bare subdomain slug — the dev server builds
+* `<company>.fluid.app` from it, so a full domain here produces an
+* unreachable `<slug>.fluid.app.fluid.app` host. Some external tooling
+* writes the full domain (or a URL); accept those and reduce them to
+* the subdomain.
+*/
+function normalizeCompany(company) {
+	return company.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/[/?#].*$/, "").replace(/\.fluid\.app$/i, "");
+}
 function configPath(themeRoot) {
 	return join(themeRoot, CONFIG_FILE);
 }
@@ -273,7 +321,9 @@ function readThemeConfig(themeRoot) {
 	if (!existsSync(path)) return null;
 	try {
 		const raw = readFileSync(path, "utf-8");
-		return JSON.parse(raw);
+		const config = JSON.parse(raw);
+		if (typeof config.company === "string") config.company = normalizeCompany(config.company);
+		return config;
 	} catch {
 		return null;
 	}
@@ -473,6 +523,40 @@ function mimeTypeFor(ext) {
 	};
 }
 //#endregion
+//#region src/theme/resource-key.ts
+const THEME_LEVEL_RESOURCE_KEYS = new Set([
+	"global_styles.css",
+	"styles.css",
+	"variables.json"
+]);
+const COMPOSITE_RESOURCE_FILE_NAMES = new Set([
+	"index.liquid",
+	"styles.css",
+	"variables.json"
+]);
+function hasSafeSegments(key) {
+	return key.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+function normalizeThemeResourceKey(value) {
+	return value.replaceAll("\\", "/");
+}
+/**
+* Whether a relative file path is a resource key accepted by the Fluid themes
+* resource API. Local project files (package manifests, QA evidence, scripts,
+* source baselines, and similar agent artifacts) must never be uploaded.
+*/
+function isThemeResourceKey(relativePath) {
+	const key = normalizeThemeResourceKey(relativePath);
+	if (!hasSafeSegments(key)) return false;
+	if (THEME_LEVEL_RESOURCE_KEYS.has(key)) return true;
+	const segments = key.split("/");
+	const prefix = segments[0];
+	const fileName = segments.at(-1);
+	if (!prefix || !fileName || segments.length < 2) return false;
+	if (prefix === "assets" || prefix === "config" || prefix === "locales" || prefix === "layouts") return true;
+	return segments.length >= 3 && COMPOSITE_RESOURCE_FILE_NAMES.has(fileName);
+}
+//#endregion
 //#region ../../platform/theme-schema/src/types.ts
 const VALID_SETTING_TYPES = Object.values({
 	"input": [
@@ -853,7 +937,7 @@ var ThemeFile = class {
 	mime;
 	constructor(absolutePath, root) {
 		this.absolutePath = absolutePath;
-		this.relativePath = relative(root, absolutePath);
+		this.relativePath = normalizeThemeResourceKey(relative(root, absolutePath));
 		this.mime = mimeTypeFor(extname(absolutePath).toLowerCase());
 	}
 	get name() {
@@ -941,6 +1025,7 @@ const THEME_MARKERS = [
 	"assets",
 	"config"
 ];
+const THEME_ASSET_MANIFEST = ".fluid-assets.json";
 var ThemeRoot = class {
 	root;
 	ignore;
@@ -949,7 +1034,7 @@ var ThemeRoot = class {
 		this.ignore = new FluidIgnore(this.root);
 	}
 	isValid() {
-		return THEME_MARKERS.some((m) => {
+		return existsSync(join(this.root, THEME_ASSET_MANIFEST)) || THEME_MARKERS.some((m) => {
 			try {
 				return statSync(join(this.root, m)).isDirectory();
 			} catch {
@@ -958,7 +1043,10 @@ var ThemeRoot = class {
 		});
 	}
 	files() {
-		return this.glob(this.root).filter((f) => !this.ignore.ignore(f.relativePath));
+		return this.glob(this.root).filter((f) => isThemeResourceKey(f.relativePath) && !this.ignore.ignore(f.relativePath));
+	}
+	isResourcePath(pathOrFile) {
+		return isThemeResourceKey(this.file(pathOrFile).relativePath);
 	}
 	file(pathOrFile) {
 		if (pathOrFile instanceof ThemeFile) return pathOrFile;
@@ -969,8 +1057,10 @@ var ThemeRoot = class {
 		for (const entry of readdirSync(dir, { withFileTypes: true })) {
 			if (entry.name.startsWith(".")) continue;
 			const full = join(dir, entry.name);
-			if (entry.isDirectory()) results.push(...this.glob(full));
-			else if (entry.isFile()) results.push(new ThemeFile(full, this.root));
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules") continue;
+				results.push(...this.glob(full));
+			} else if (entry.isFile()) results.push(new ThemeFile(full, this.root));
 		}
 		return results;
 	}
@@ -1200,6 +1290,17 @@ async function getApplicationThemeAvailableThemeables(client, id, params) {
 	return client.get(`/api/application_themes/${id}/available_themeables`, params);
 }
 /**
+* Create a development reference clone of an application theme
+* Creates an isolated development theme while preserving existing DAM and ImageKit references without transferring asset bytes.
+*
+* @param client - Fetch client instance
+* @param id - id
+* @param body - body
+*/
+async function cloneApplicationThemeForDevelopment(client, id, body) {
+	return client.post(`/api/application_themes/${id}/clone_for_development`, body);
+}
+/**
 * Publishes the theme
 *
 *
@@ -1210,6 +1311,16 @@ async function publishApplicationTheme(client, id) {
 	return client.post(`/api/application_themes/${id}/publish`);
 }
 /**
+* Get theme assets
+*
+*
+* @param client - Fetch client instance
+* @param id - id
+*/
+async function getThemeAssets(client, id) {
+	return client.get(`/api/application_themes/${id}/theme_assets`);
+}
+/**
 * Lists all theme resources
 *
 *
@@ -1241,6 +1352,26 @@ async function updateThemeResource(client, application_theme_id, body) {
 async function deleteThemeResource(client, application_theme_id, body) {
 	return client.delete(`/api/application_themes/${application_theme_id}/resources`, { body });
 }
+/**
+* Creates a file resource
+*
+*
+* @param client - Fetch client instance
+* @param body - body
+*/
+async function createFileResource(client, body) {
+	return client.post(`/api/file_resources`, body);
+}
+/**
+* Deletes a file resource
+*
+*
+* @param client - Fetch client instance
+* @param id - id
+*/
+async function destroyFileResource(client, id) {
+	return client.delete(`/api/file_resources/${id}`);
+}
 //#endregion
 //#region src/theme/format-error.ts
 const STYLESHEET_MIGRATION_SKILL = "template-stylesheet-to-asset-migration";
@@ -1276,13 +1407,16 @@ function formatError(e) {
 }
 //#endregion
 //#region src/theme/dev-server/watcher.ts
+function relativeThemePath(root, filePath) {
+	return relative(root.root, filePath).split(sep).join("/");
+}
 function watchTheme(root, handler) {
 	const watcher = chokidar.watch(root.root, {
 		ignoreInitial: true,
 		ignored: (filePath) => {
 			if (filePath.includes("node_modules")) return true;
 			try {
-				const rel = relative(root.root, filePath);
+				const rel = relativeThemePath(root, filePath);
 				return (rel.split(/[\\/]/).pop() ?? "").startsWith(".") || root.ignore.ignore(rel);
 			} catch {
 				return false;
@@ -1301,21 +1435,151 @@ function watchTheme(root, handler) {
 		});
 	};
 	watcher.on("change", (filePath) => {
-		const rel = relative(root.root, filePath);
-		if (root.ignore.ignore(rel)) return;
-		enqueue(() => handler([root.file(filePath)], [], []));
+		const rel = relativeThemePath(root, filePath);
+		if (!root.isResourcePath(filePath) || root.ignore.ignore(rel)) return;
+		const arrivedAt = Date.now();
+		enqueue(() => handler([root.file(filePath)], [], [], arrivedAt));
 	});
 	watcher.on("add", (filePath) => {
-		const rel = relative(root.root, filePath);
-		if (root.ignore.ignore(rel)) return;
-		enqueue(() => handler([], [root.file(filePath)], []));
+		const rel = relativeThemePath(root, filePath);
+		if (!root.isResourcePath(filePath) || root.ignore.ignore(rel)) return;
+		const arrivedAt = Date.now();
+		enqueue(() => handler([], [root.file(filePath)], [], arrivedAt));
 	});
 	watcher.on("unlink", (filePath) => {
-		enqueue(() => handler([], [], [root.file(filePath)]));
+		const rel = relativeThemePath(root, filePath);
+		if (!root.isResourcePath(filePath) || root.ignore.ignore(rel)) return;
+		const arrivedAt = Date.now();
+		enqueue(() => handler([], [], [root.file(filePath)], arrivedAt));
 	});
 	return () => watcher.close();
 }
 //#endregion
+//#region src/theme/asset-manifest.ts
+const MANIFEST_FILE = ".fluid-assets.json";
+const MANIFEST_VERSION = 1;
+/**
+* A tiny shadow-repo placeholder for a manifest-backed asset. It preserves
+* the path as a deletion baseline without retaining the asset bytes locally.
+*/
+const MANAGED_ASSET_SHADOW_SENTINEL = "fluid-managed-asset\n";
+/**
+* Tracks binary theme assets that deliberately live only on the server.
+*
+* The manifest is a dotfile so it is excluded from theme uploads and file
+* watching. It is written before the corresponding local file is removed,
+* which prevents `delete: true` from mistaking the removed byte source for a
+* request to delete its remote FileResource.
+*/
+var ThemeAssetManifest = class {
+	assets;
+	path;
+	constructor(themeRoot) {
+		this.path = join(themeRoot, MANIFEST_FILE);
+		this.assets = readDocument(this.path).assets;
+	}
+	reload() {
+		this.assets = readDocument(this.path).assets;
+	}
+	keys() {
+		return Object.keys(this.assets);
+	}
+	entries() {
+		return Object.entries(this.assets).map(([key, link]) => [key, copyLink(link)]);
+	}
+	has(key) {
+		return this.assets[key] !== void 0;
+	}
+	get(key) {
+		const link = this.assets[key];
+		return link ? copyLink(link) : void 0;
+	}
+	set(key, link) {
+		if (!isThemeAssetKey(key) || !isThemeAssetLink(link)) throw new Error(`invalid asset entry for ${key}`);
+		this.assets[key] = copyLink(link);
+	}
+	delete(key) {
+		delete this.assets[key];
+	}
+	write() {
+		const document = {
+			version: MANIFEST_VERSION,
+			assets: copyAssets(this.assets)
+		};
+		const tempPath = `${this.path}.${randomBytes(6).toString("hex")}.tmp`;
+		try {
+			mkdirSync(dirname(this.path), { recursive: true });
+			writeFileSync(tempPath, JSON.stringify(document, null, 2) + "\n", {
+				encoding: "utf-8",
+				mode: 384
+			});
+			renameSync(tempPath, this.path);
+		} catch (error) {
+			try {
+				unlinkSync(tempPath);
+			} catch {}
+			throw error;
+		}
+	}
+};
+function readDocument(path) {
+	if (!existsSync(path)) return emptyDocument();
+	try {
+		return parseDocument(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}`);
+	const rawAssets = value["assets"];
+	if (!isRecord$1(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}`);
+		assets[key] = copyLink(rawLink);
+	}
+	return {
+		version: MANIFEST_VERSION,
+		assets
+	};
+}
+function emptyDocument() {
+	return {
+		version: MANIFEST_VERSION,
+		assets: {}
+	};
+}
+function copyAssets(assets) {
+	return Object.fromEntries(Object.entries(assets).map(([key, link]) => [key, copyLink(link)]));
+}
+function copyLink(link) {
+	return {
+		sourceThemeId: link.sourceThemeId,
+		...typeof link.checksum === "string" ? { checksum: link.checksum } : {},
+		...typeof link.url === "string" ? { url: link.url } : {},
+		...typeof link.contentType === "string" ? { contentType: link.contentType } : {},
+		...typeof link.contentSize === "number" ? { contentSize: link.contentSize } : {},
+		...typeof link.previewImageUrl === "string" ? { previewImageUrl: link.previewImageUrl } : {},
+		...typeof link.altText === "string" ? { altText: link.altText } : {},
+		...typeof link.handle === "string" ? { handle: link.handle } : {},
+		...link.pending === true ? { pending: true } : {},
+		...typeof link.damAssetCode === "string" ? { damAssetCode: link.damAssetCode } : {}
+	};
+}
+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);
+}
+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) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/theme/stylesheet-keys.ts
 const STYLESHEET_KEY_PATTERN = /^(styles\.css|global_styles\.css|[^/]+\/[^/]+\/styles\.css)$/;
 function isStylesheetKey(key) {
@@ -1323,6 +1587,7 @@ function isStylesheetKey(key) {
 }
 //#endregion
 //#region src/theme/syncer.ts
+const ASSET_REFERENCE_CONCURRENCY = 6;
 /**
 * Server rejected the push because the CLI's `base_sha` no longer
 * matches the theme's current `content_version_sha` (someone else
@@ -1340,12 +1605,22 @@ var PushConflictError = class extends Error {
 	}
 };
 var Syncer = class {
-	checksums = /* @__PURE__ */ new Map();
+	checksumIndex = /* @__PURE__ */ new Map();
+	rawRemoteResources = /* @__PURE__ */ new Map();
+	remoteResourceGroups = /* @__PURE__ */ new Map();
+	remoteResourceIndex = /* @__PURE__ */ new Map();
+	remoteIndexesDirty = false;
 	lastKnownRemoteSha = null;
-	constructor(api, themeId, themeRoot) {
+	assetManifestInstance;
+	constructor(api, themeId, themeRoot, assetManifest) {
 		this.api = api;
 		this.themeId = themeId;
 		this.themeRoot = themeRoot;
+		this.assetManifestInstance = assetManifest;
+	}
+	get assetManifest() {
+		this.assetManifestInstance ??= new ThemeAssetManifest(this.themeRoot.root);
+		return this.assetManifestInstance;
 	}
 	async fetchChecksums() {
 		const body = await listThemeResources(this.api, this.themeId);
@@ -1360,35 +1635,294 @@ var Syncer = class {
 		return this.lastKnownRemoteSha;
 	}
 	updateChecksums(resources) {
-		for (const r of resources) if (r.key && r.checksum) this.checksums.set(r.key, r.checksum);
-		for (const key of this.checksums.keys()) if (this.checksums.has(`${key}.liquid`)) this.checksums.delete(key);
+		this.rawRemoteResources.clear();
+		this.remoteResourceGroups.clear();
+		for (const resource of resources) {
+			if (!resource.key) continue;
+			this.rawRemoteResources.set(resource.key, resource);
+			const group = this.remoteResourceGroups.get(resource.key) ?? [];
+			group.push(resource);
+			this.remoteResourceGroups.set(resource.key, group);
+		}
+		this.remoteIndexesDirty = true;
+	}
+	setRemoteResource(resource) {
+		if (!resource.key) return;
+		this.rawRemoteResources.set(resource.key, resource);
+		this.remoteResourceGroups.set(resource.key, [resource]);
+		this.remoteIndexesDirty = true;
+	}
+	removeRemoteResource(relativePath) {
+		this.rawRemoteResources.delete(relativePath);
+		this.remoteResourceGroups.delete(relativePath);
+		this.remoteIndexesDirty = true;
+	}
+	get checksums() {
+		if (this.remoteIndexesDirty) this.rebuildRemoteIndexes();
+		return this.checksumIndex;
+	}
+	get remoteResources() {
+		if (this.remoteIndexesDirty) this.rebuildRemoteIndexes();
+		return this.remoteResourceIndex;
+	}
+	rebuildRemoteIndexes() {
+		this.remoteIndexesDirty = false;
+		this.checksumIndex.clear();
+		this.remoteResourceIndex.clear();
+		for (const [key, resource] of this.rawRemoteResources) {
+			if (this.rawRemoteResources.has(`${key}.liquid`)) continue;
+			this.remoteResourceIndex.set(key, resource);
+			if (resource.checksum) this.checksumIndex.set(key, resource.checksum);
+		}
 	}
 	hasChanged(file) {
 		return file.checksum() !== this.checksums.get(file.relativePath);
 	}
 	remoteKeys() {
-		return [...this.checksums.keys()];
+		return [...this.remoteResources.keys()];
 	}
 	/** Snapshot of remote checksums (key → sha256). Available after fetchChecksums() or downloadAll(). */
 	remoteChecksums() {
 		return Object.fromEntries(this.checksums);
 	}
+	/** URL-backed assets keyed by their exact theme resource path. */
+	remoteAssetUrls() {
+		const urls = {};
+		for (const [key, resource] of this.remoteResources) {
+			if (!isManagedAssetResource(resource)) continue;
+			const url = resource.url;
+			if (typeof url === "string" && url.length > 0) urls[key] = url;
+		}
+		return urls;
+	}
+	/**
+	* 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();
+		const plans = [];
+		for (const [key, link] of this.assetManifest.entries()) {
+			if (this.themeRoot.ignore.ignore(key)) continue;
+			if (this.themeRoot.file(key).exists) continue;
+			const targetResource = this.managedAssetResourceForLink(key, link) ?? this.remoteResources.get(key);
+			if (targetResource && !this.managedAssetNeedsRefresh(targetResource, link)) continue;
+			if (targetResource && !opts.replace) continue;
+			const metadata = assetMetadataFromLink(link);
+			plans.push({
+				key,
+				link,
+				...targetResource ? { targetResource } : {},
+				...metadata ? { metadata } : {}
+			});
+		}
+		if (plans.length > 0) {
+			await this.resolveAssetMetadata(plans);
+			await this.createAssetReferences(plans);
+			await this.fetchChecksums();
+		}
+		if (opts.replace && await this.pruneDuplicateManagedAssetReferences()) await this.fetchChecksums();
+		this.ensureManagedAssetsAreResolved();
+		return plans.length;
+	}
+	async resolveAssetMetadata(plans) {
+		const bySourceTheme = /* @__PURE__ */ new Map();
+		for (const plan of plans) {
+			if (plan.metadata) continue;
+			const sourcePlans = bySourceTheme.get(plan.link.sourceThemeId) ?? [];
+			sourcePlans.push(plan);
+			bySourceTheme.set(plan.link.sourceThemeId, sourcePlans);
+		}
+		let manifestChanged = false;
+		for (const [sourceThemeId, sourcePlans] of bySourceTheme) {
+			let sourceAssets;
+			try {
+				sourceAssets = await this.fetchThemeAssetMetadata(sourceThemeId);
+			} catch (error) {
+				throw new Error(`Could not read asset metadata from theme #${sourceThemeId}: ${formatError(error)}`);
+			}
+			for (const plan of sourcePlans) {
+				const sourceMetadata = sourceAssets.get(assetFilename(plan.key));
+				if (!sourceMetadata) throw new Error(`Could not find usable metadata for ${plan.key} in theme #${sourceThemeId}`);
+				const metadata = {
+					...sourceMetadata,
+					...typeof plan.link.url === "string" ? { url: plan.link.url } : {}
+				};
+				plan.metadata = metadata;
+				this.assetManifest.set(plan.key, {
+					...plan.link,
+					...metadata
+				});
+				manifestChanged = true;
+			}
+		}
+		if (manifestChanged) this.assetManifest.write();
+	}
+	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");
+		const assets = /* @__PURE__ */ new Map();
+		for (const value of body["file_resources"]) {
+			const asset = parseThemeAssetMetadata(value);
+			if (asset) assets.set(asset.filename, asset.metadata);
+		}
+		return assets;
+	}
+	async createAssetReferences(plans) {
+		const errors = [];
+		let nextPlan = 0;
+		const worker = async () => {
+			while (nextPlan < plans.length) {
+				const plan = plans[nextPlan];
+				nextPlan += 1;
+				if (!plan || !plan.metadata) continue;
+				try {
+					await this.createAssetReference(plan);
+				} catch (error) {
+					errors.push(`${plan.key}: ${formatError(error)}`);
+				}
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(ASSET_REFERENCE_CONCURRENCY, plans.length) }, worker));
+		if (errors.length > 0) throw new Error(`Could not save ${errors.length} ImageKit URL reference(s) (this requires File Resources update access): ${errors.join("; ")}`);
+	}
+	async createAssetReference(plan) {
+		const metadata = plan.metadata;
+		if (!metadata) throw new Error("asset metadata was not resolved");
+		const targetResourceId = plan.targetResource?.resource_id;
+		if (plan.targetResource && typeof targetResourceId !== "number") throw new Error("existing target asset has no resource ID");
+		const createdResourceId = createdFileResourceId(await createFileResource(this.api, { file_resource: {
+			url: metadata.url,
+			filename: assetFilename(plan.key),
+			content_type: metadata.contentType,
+			content_size: metadata.contentSize,
+			...metadata.previewImageUrl ? { preview_image_url: metadata.previewImageUrl } : {},
+			...metadata.altText !== void 0 ? { alt_text: metadata.altText } : {},
+			...metadata.handle ? { handle: metadata.handle } : {},
+			relateable_id: this.themeId,
+			relateable_type: "ApplicationTheme"
+		} }));
+		if (!createdResourceId) throw new Error("create response did not include a FileResource ID");
+		if (typeof targetResourceId !== "number") return;
+		try {
+			await destroyFileResource(this.api, targetResourceId);
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			try {
+				await destroyFileResource(this.api, createdResourceId);
+			} catch {}
+			throw error;
+		}
+	}
 	/**
-	* Uploads one file. Resolves with the exact text content that was
-	* sent to the server (null for binary files) so callers can run
-	* diagnostics against the same bytes instead of re-reading a file
-	* that may have changed on disk while the request was in flight.
+	* Returns every resource for an exact logical key. A legacy `foo` resource
+	* is hidden when `foo.liquid` exists, matching the normal remote index.
 	*/
-	async uploadFile(file, baseSha) {
+	resourcesForLogicalKey(key) {
+		if (this.rawRemoteResources.has(`${key}.liquid`)) return [];
+		return this.remoteResourceGroups.get(key) ?? [];
+	}
+	managedAssetResourceForLink(key, link) {
+		return this.resourcesForLogicalKey(key).find((resource) => isManagedAssetResource(resource) && !this.managedAssetNeedsRefresh(resource, link));
+	}
+	/** Make interrupted reference replacement converge to one FileResource. */
+	async pruneDuplicateManagedAssetReferences() {
+		const resourcesToDelete = [];
+		for (const [key, link] of this.assetManifest.entries()) {
+			if (this.themeRoot.ignore.ignore(key) || !link.url) continue;
+			const resources = this.resourcesForLogicalKey(key).filter(isManagedAssetResource);
+			if (resources.length < 2) continue;
+			const matchingResources = resources.filter((resource) => resource.url === link.url);
+			if (matchingResources.length === 0) continue;
+			const keeper = this.lowestResourceId(matchingResources, key);
+			const keeperId = this.resourceIdForAssetReference(keeper, key);
+			for (const resource of resources) {
+				const resourceId = this.resourceIdForAssetReference(resource, key);
+				if (resourceId !== keeperId) resourcesToDelete.push({
+					key,
+					resourceId
+				});
+			}
+		}
+		if (resourcesToDelete.length === 0) return false;
+		const errors = [];
+		let nextResource = 0;
+		const worker = async () => {
+			while (nextResource < resourcesToDelete.length) {
+				const resource = resourcesToDelete[nextResource];
+				nextResource += 1;
+				if (!resource) continue;
+				try {
+					await destroyFileResource(this.api, resource.resourceId);
+				} catch (error) {
+					if (!isNotFoundError(error)) errors.push(`${resource.key}: ${formatError(error)}`);
+				}
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(ASSET_REFERENCE_CONCURRENCY, resourcesToDelete.length) }, worker));
+		if (errors.length > 0) throw new Error(`Could not remove ${errors.length} duplicate ImageKit URL reference(s): ${errors.join("; ")}`);
+		return true;
+	}
+	lowestResourceId(resources, key) {
+		let lowest = resources[0];
+		if (!lowest) throw new Error(`No asset resources found for ${key}`);
+		let lowestId = this.resourceIdForAssetReference(lowest, key);
+		for (const resource of resources.slice(1)) {
+			const resourceId = this.resourceIdForAssetReference(resource, key);
+			if (resourceId < lowestId) {
+				lowest = resource;
+				lowestId = resourceId;
+			}
+		}
+		return lowest;
+	}
+	resourceIdForAssetReference(resource, key) {
+		const resourceId = positiveInteger(resource.resource_id);
+		if (!resourceId) throw new Error(`Existing target asset has no resource ID: ${key}`);
+		return resourceId;
+	}
+	/** Makes this target the provenance source for assets it now resolves. */
+	repointManagedAssetsToCurrentTheme() {
+		this.assetManifest.reload();
+		let changed = false;
+		for (const [key, link] of this.assetManifest.entries()) {
+			if (this.themeRoot.ignore.ignore(key)) continue;
+			if (this.themeRoot.file(key).exists) continue;
+			const resource = this.remoteResources.get(key);
+			if (!isManagedAssetResource(resource)) throw new Error(`Managed asset is missing from target theme: ${key}`);
+			const nextLink = {
+				...link,
+				sourceThemeId: this.themeId
+			};
+			delete nextLink.pending;
+			delete nextLink.checksum;
+			Object.assign(nextLink, resourceLink(resource));
+			this.assetManifest.set(key, nextLink);
+			changed = true;
+		}
+		if (changed) this.assetManifest.write();
+	}
+	/**
+	* Uploads one file. Resolves with the exact text content that was sent to
+	* the server (null for binary files) so callers can run diagnostics against
+	* the same bytes instead of re-reading a file that may have changed on disk
+	* while the request was in flight.
+	*/
+	async uploadFile(file, baseSha, opts = {}) {
 		if (file.isText) {
 			const content = file.read();
-			await this.putResource({
+			const resource = await this.putResource({
 				key: file.relativePath,
 				content
 			}, baseSha);
+			this.setRemoteResource(resource);
 			return content;
 		}
-		await this.uploadBinaryFile(file, baseSha);
+		if (isNestedBinaryThemeAsset(file)) throw new Error(`Binary assets must be directly inside assets/: ${file.relativePath}`);
+		const resource = await this.uploadBinaryFile(file, baseSha);
+		this.setRemoteResource(resource);
+		if (isThemeAssetKey(file.relativePath)) this.externalizeBinaryFile(file, resource, opts.pendingAsset);
 		return null;
 	}
 	/**
@@ -1419,6 +1953,10 @@ var Syncer = class {
 		try {
 			const response = await updateThemeResource(this.api, this.themeId, body);
 			if (response.content_version_sha) this.lastKnownRemoteSha = response.content_version_sha;
+			return response.application_theme_resource ?? {
+				key: typeof resource["key"] === "string" ? resource["key"] : "",
+				checksum: null
+			};
 		} catch (e) {
 			throw this.rethrowIfConflict(e);
 		}
@@ -1434,6 +1972,41 @@ var Syncer = class {
 	* (no stored `baseSha` in `.fluid-theme.json`) and `--force` pushes
 	* short-circuit past the check.
 	*/
+	/**
+	* Tell Fluid the push is finished, so it commits the theme's current state
+	* as one version.
+	*
+	* The other half of `preflightPush`. That one runs once before the file
+	* loop to reject a stale base; this runs once after it, and is the only
+	* thing that turns a push into a commit — the per-file writes just mark the
+	* theme changed.
+	*
+	* It exists because the server cannot see where an operation ends. A push
+	* arrives as a hundred-odd independent requests, and every way of inferring
+	* "these belong together" either merges two publishes that happened to land
+	* close together or splits one push across several commits. The client
+	* knows; this says so.
+	*
+	* Best-effort in that it never throws: the files are already on the server
+	* by the time this runs, and Fluid sweeps anything left unsynced, so a
+	* failure delays the commit rather than losing it and must not fail the
+	* push.
+	*
+	* Returns whether Fluid took the request, because a caller tracking edit
+	* boundaries needs to know. A failed ask leaves the previous edit
+	* uncommitted, and uploading the next one over it merges the two into
+	* whichever commit eventually lands.
+	*/
+	async requestSync() {
+		try {
+			const response = await this.api.post(`/api/application_themes/${this.themeId}/resources/sync`, {});
+			if (response.content_version_sha) this.lastKnownRemoteSha = response.content_version_sha;
+			return true;
+		} catch (e) {
+			console.warn(`  ⚠ couldn't ask Fluid to commit this push (${formatError(e)}). It will be picked up automatically.`);
+			return false;
+		}
+	}
 	async preflightPush(baseSha) {
 		if (!baseSha) return;
 		try {
@@ -1483,7 +2056,7 @@ var Syncer = class {
 		if (ikBody.height) backfillPayload["asset"]["height"] = ikBody.height;
 		if (ikBody.width) backfillPayload["asset"]["width"] = ikBody.width;
 		const backfillBody = await this.api.post("/api/dam/assets/backfill_imagekit", backfillPayload);
-		await this.putResource({
+		const update = await this.putResource({
 			key: file.relativePath,
 			dam_asset: {
 				dam_asset_code: backfillBody.asset.code,
@@ -1495,6 +2068,32 @@ var Syncer = class {
 				preview_image_url: ikBody.thumbnailUrl
 			}
 		}, baseSha);
+		return {
+			...update,
+			key: update.key || file.relativePath,
+			url: update.url ?? backfillBody.asset.default_variant_url,
+			damAssetCode: backfillBody.asset.code,
+			assetMetadata: {
+				url: backfillBody.asset.default_variant_url,
+				contentType: file.mime.name,
+				contentSize: ikBody.size,
+				previewImageUrl: ikBody.thumbnailUrl,
+				altText: file.name,
+				handle: backfillBody.asset.code
+			}
+		};
+	}
+	externalizeBinaryFile(file, resource, pending) {
+		this.assetManifest.reload();
+		this.assetManifest.set(file.relativePath, {
+			sourceThemeId: this.themeId,
+			...resourceLink(resource),
+			...uploadedAssetMetadata(file, resource),
+			...pending ? { pending: true } : {},
+			...typeof resource.damAssetCode === "string" ? { damAssetCode: resource.damAssetCode } : {}
+		});
+		this.assetManifest.write();
+		unlinkSync(file.absolutePath);
 	}
 	canonicalPathToImageKitFolder(canonicalPath) {
 		const parts = canonicalPath.split(".");
@@ -1510,6 +2109,8 @@ var Syncer = class {
 		}[category] ?? "files"}/${assetCode}`;
 	}
 	async deleteRemoteFile(relativePath, baseSha) {
+		this.assetManifest.reload();
+		if (this.assetManifest.has(relativePath)) return;
 		const body = { application_theme_resource: { key: relativePath } };
 		if (baseSha) body["base_sha"] = baseSha;
 		try {
@@ -1518,7 +2119,7 @@ var Syncer = class {
 		} catch (e) {
 			throw this.rethrowIfConflict(e);
 		}
-		this.checksums.delete(relativePath);
+		this.removeRemoteResource(relativePath);
 	}
 	async downloadAll() {
 		const body = await listThemeResources(this.api, this.themeId);
@@ -1532,15 +2133,138 @@ var Syncer = class {
 		if (!resp.ok) throw new Error(`Failed to download asset: ${resp.status}`);
 		return Buffer.from(await resp.arrayBuffer());
 	}
+	/**
+	* Move directly-addressable binary `assets/*` resources into the local
+	* manifest before merge-pull sees them. This prevents a byte download and
+	* keeps those paths out of the shadow repository; their canonical state is
+	* the ImageKit URL, not a local file.
+	*/
+	async externalizePulledAssets(resources, opts) {
+		this.assetManifest.reload();
+		const managedKeys = /* @__PURE__ */ new Set();
+		const changedManifestKeys = /* @__PURE__ */ new Set();
+		const remoteManagedKeys = /* @__PURE__ */ new Set();
+		const preservedManifestKeys = /* @__PURE__ */ new Set();
+		const filesToRemove = /* @__PURE__ */ new Map();
+		const errors = [];
+		let manifestChanged = false;
+		const resourcesNeedingMetadata = resources.filter((resource) => {
+			const key = resource.key;
+			if (!key) return false;
+			const file = this.themeRoot.file(key);
+			if (!this.isSafeThemeFile(key, file)) return false;
+			if (!isLinkableBinaryResource(resource, key, file)) return false;
+			const existing = this.assetManifest.get(key);
+			if (this.themeRoot.ignore.ignore(key) || existing?.pending) return false;
+			return !existing || existing.url !== resource.url || !assetMetadataFromLink(existing);
+		});
+		let assetMetadata = /* @__PURE__ */ new Map();
+		const unresolvedMetadataKeys = /* @__PURE__ */ new Set();
+		if (resourcesNeedingMetadata.length > 0) {
+			try {
+				assetMetadata = await this.fetchThemeAssetMetadata(this.themeId);
+			} catch (error) {
+				errors.push(`Read remote asset metadata: ${formatError(error)}`);
+				for (const resource of resourcesNeedingMetadata) if (resource.key) unresolvedMetadataKeys.add(resource.key);
+			}
+			if (unresolvedMetadataKeys.size === 0) for (const resource of resourcesNeedingMetadata) {
+				const key = resource.key;
+				if (!key || assetMetadata.has(assetFilename(key))) continue;
+				unresolvedMetadataKeys.add(key);
+				errors.push(`Could not find usable metadata for ${key} in theme #${this.themeId}`);
+			}
+		}
+		for (const resource of resources) {
+			const key = resource.key;
+			if (!key) continue;
+			const file = this.themeRoot.file(key);
+			if (!this.isSafeThemeFile(key, file)) continue;
+			if (!isLinkableBinaryResource(resource, key, file)) continue;
+			remoteManagedKeys.add(key);
+			if (this.themeRoot.ignore.ignore(key)) {
+				if (this.assetManifest.has(key)) preservedManifestKeys.add(key);
+				managedKeys.add(key);
+				continue;
+			}
+			if (this.assetManifest.get(key)?.pending) {
+				preservedManifestKeys.add(key);
+				managedKeys.add(key);
+				continue;
+			}
+			if (unresolvedMetadataKeys.has(key)) {
+				const stale = this.assetManifest.get(key);
+				if (stale && stale.url !== resource.url) {
+					this.assetManifest.delete(key);
+					manifestChanged = true;
+				}
+				continue;
+			}
+			try {
+				const existing = this.assetManifest.get(key);
+				const metadata = assetMetadata.get(assetFilename(key));
+				this.assetManifest.set(key, {
+					...existing,
+					sourceThemeId: this.themeId,
+					...metadata,
+					...resourceLink(resource)
+				});
+				manifestChanged = true;
+				changedManifestKeys.add(key);
+				managedKeys.add(key);
+				filesToRemove.set(key, file);
+			} catch (error) {
+				errors.push(`Externalize ${key}: ${formatError(error)}`);
+			}
+		}
+		if (opts.delete) for (const [key, link] of this.assetManifest.entries()) {
+			if (remoteManagedKeys.has(key) || preservedManifestKeys.has(key) || this.themeRoot.ignore.ignore(key) || link.pending) continue;
+			this.assetManifest.delete(key);
+			manifestChanged = true;
+		}
+		if (manifestChanged) try {
+			this.assetManifest.write();
+		} catch (error) {
+			errors.push(`Persist remote asset manifest: ${formatError(error)}`);
+			for (const key of changedManifestKeys) managedKeys.delete(key);
+			return {
+				managedKeys,
+				linked: 0,
+				errors
+			};
+		}
+		let linked = 0;
+		for (const [key, file] of filesToRemove) try {
+			if (file.exists) unlinkSync(file.absolutePath);
+			linked++;
+		} catch (error) {
+			errors.push(`Externalize ${key}: ${formatError(error)}`);
+		}
+		return {
+			managedKeys,
+			linked,
+			errors
+		};
+	}
+	isSafeThemeFile(key, file) {
+		return !key.includes("\0") && !key.split(/[\\/]/).includes("..") && (file.absolutePath === this.themeRoot.root || file.absolutePath.startsWith(this.themeRoot.root + sep));
+	}
+	managedAssetNeedsRefresh(resource, link) {
+		if (!isManagedAssetResource(resource)) return true;
+		if (link.url !== void 0) return resource.url !== link.url;
+		if (link.checksum !== void 0) return resource.checksum !== link.checksum;
+		return true;
+	}
+	ensureManagedAssetsAreResolved() {
+		const unresolved = this.assetManifest.entries().filter(([key]) => !this.themeRoot.ignore.ignore(key) && !this.themeRoot.file(key).exists).map(([key]) => key).filter((key) => !isManagedAssetResource(this.remoteResources.get(key)));
+		if (unresolved.length > 0) throw new Error(`Managed asset(s) could not be linked: ${unresolved.join(", ")}`);
+	}
 	async uploadTheme(opts = {}) {
-		await this.fetchChecksums();
-		await this.preflightPush(opts.baseSha);
-		let baseSha = opts.baseSha ?? null;
 		const localFiles = this.themeRoot.files();
 		const result = {
 			uploaded: 0,
 			deleted: 0,
 			downloaded: 0,
+			linked: 0,
 			errors: [],
 			validationFailed: false
 		};
@@ -1555,11 +2279,21 @@ var Syncer = class {
 				return result;
 			}
 		}
+		await this.fetchChecksums();
+		await this.preflightPush(opts.baseSha);
+		let baseSha = opts.baseSha ?? null;
+		if (opts.linkManagedAssets) {
+			result.linked = await this.linkManagedAssets(opts.linkManagedAssets);
+			baseSha = this.lastKnownRemoteSha ?? baseSha;
+		} else if (this.assetManifestInstance) {
+			this.assetManifest.reload();
+			this.ensureManagedAssetsAreResolved();
+		}
 		const toUpload = localFiles.filter((f) => f.exists && this.hasChanged(f));
 		let done = 0;
 		for (const file of toUpload) {
 			try {
-				await this.uploadFile(file, baseSha);
+				await this.uploadFile(file, baseSha, { pendingAsset: opts.pendingBinaryAssets });
 				baseSha = this.lastKnownRemoteSha;
 				result.uploaded++;
 			} catch (e) {
@@ -1570,7 +2304,8 @@ var Syncer = class {
 		}
 		if (opts.delete) {
 			const localPaths = new Set(localFiles.map((f) => f.relativePath));
-			const toDelete = this.remoteKeys().filter((k) => !localPaths.has(k));
+			for (const key of this.assetManifest.keys()) localPaths.add(key);
+			const toDelete = this.remoteKeys().filter((key) => !localPaths.has(key) && !this.themeRoot.ignore.ignore(key));
 			for (const key of toDelete) try {
 				await this.deleteRemoteFile(key, baseSha);
 				baseSha = this.lastKnownRemoteSha;
@@ -1584,23 +2319,29 @@ var Syncer = class {
 	}
 	async downloadTheme(opts = {}) {
 		const resources = await this.downloadAll();
+		const externalizedAssets = await this.externalizePulledAssets(resources, { delete: opts.delete ?? false });
 		const result = {
 			uploaded: 0,
 			deleted: 0,
 			downloaded: 0,
+			linked: externalizedAssets.linked,
 			skipped: 0,
-			errors: [],
+			errors: [...externalizedAssets.errors],
 			validationFailed: false
 		};
 		let done = 0;
 		for (const resource of resources) {
+			if (externalizedAssets.managedKeys.has(resource.key)) {
+				opts.onProgress?.(++done, resources.length);
+				continue;
+			}
 			if (opts.skip?.has(resource.key)) {
 				result.skipped++;
 				opts.onProgress?.(++done, resources.length);
 				continue;
 			}
 			const file = this.themeRoot.file(resource.key);
-			if (!file.absolutePath.startsWith(this.themeRoot.root + sep)) {
+			if (!this.isSafeThemeFile(resource.key, file)) {
 				result.errors.push(`Download ${resource.key}: path traversal detected`);
 				opts.onProgress?.(++done, resources.length);
 				continue;
@@ -1625,7 +2366,6 @@ var Syncer = class {
 				if (remoteKeys.has(file.relativePath)) continue;
 				if (isStylesheetKey(file.relativePath)) continue;
 				try {
-					const { unlinkSync } = await import("node:fs");
 					unlinkSync(file.absolutePath);
 					result.deleted++;
 				} catch {}
@@ -1634,17 +2374,106 @@ var Syncer = class {
 		return result;
 	}
 };
+function isLinkableBinaryResource(resource, key, file) {
+	return isThemeAssetKey(key) && isManagedAssetResource(resource) && !file.isText;
+}
+function isNestedBinaryThemeAsset(file) {
+	return !file.isText && file.relativePath.startsWith("assets/") && !isThemeAssetKey(file.relativePath);
+}
+function isManagedAssetResource(resource) {
+	return resource?.resource_type === "FileResource" && typeof resource.url === "string" && resource.url.length > 0;
+}
+function isNotFoundError(error) {
+	return isApiError(error) && error.status === 404;
+}
+function resourceLink(resource) {
+	return {
+		...typeof resource.checksum === "string" && resource.checksum.length > 0 ? { checksum: resource.checksum } : {},
+		...typeof resource.url === "string" && resource.url.length > 0 ? { url: resource.url } : {}
+	};
+}
+function assetFilename(key) {
+	return key.slice(7);
+}
+function assetMetadataFromLink(link) {
+	if (typeof link.url !== "string" || link.url.length === 0 || typeof link.contentType !== "string" || link.contentType.length === 0 || typeof link.contentSize !== "number" || !Number.isInteger(link.contentSize) || link.contentSize <= 0) return;
+	return {
+		url: link.url,
+		contentType: link.contentType,
+		contentSize: link.contentSize,
+		...typeof link.previewImageUrl === "string" ? { previewImageUrl: link.previewImageUrl } : {},
+		...typeof link.altText === "string" ? { altText: link.altText } : {},
+		...typeof link.handle === "string" ? { handle: link.handle } : {}
+	};
+}
+function uploadedAssetMetadata(file, resource) {
+	if (resource.assetMetadata) return resource.assetMetadata;
+	if (!resource.url) throw new Error(`Uploaded asset has no URL: ${file.relativePath}`);
+	return {
+		url: resource.url,
+		contentType: file.mime.name,
+		contentSize: file.size(),
+		altText: file.name,
+		...typeof resource.damAssetCode === "string" ? { handle: resource.damAssetCode } : {}
+	};
+}
+function parseThemeAssetMetadata(value) {
+	if (!isRecord(value)) return void 0;
+	const filename = nonEmptyString(value["filename"]);
+	const url = nonEmptyString(value["url"]);
+	const contentType = nonEmptyString(value["content_type"]);
+	const contentSize = positiveInteger(value["content_size"]);
+	if (!filename || !url || !contentType || !contentSize) return void 0;
+	const previewImageUrl = nonEmptyString(value["preview_image_url"]);
+	const altText = optionalString(value["alt_text"]);
+	const handle = nonEmptyString(value["handle"]);
+	return {
+		filename,
+		metadata: {
+			url,
+			contentType,
+			contentSize,
+			...previewImageUrl ? { previewImageUrl } : {},
+			...altText !== void 0 ? { altText } : {},
+			...handle ? { handle } : {}
+		}
+	};
+}
+function createdFileResourceId(value) {
+	if (!isRecord(value) || !isRecord(value["file_resource"])) return;
+	return positiveInteger(value["file_resource"]["id"]);
+}
+function positiveInteger(value) {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) return void 0;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function optionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 //#endregion
 //#region src/theme/liquid-delimiters.ts
 /**
 * Heuristic-only check for obviously unbalanced liquid delimiters
-* (`{% %}` and `{{ }}`). This is NOT a liquid parser — it just counts
-* delimiter occurrences. It exists to give watch-mode users a signal
+* (`{% %}` 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
@@ -1652,11 +2481,118 @@ var Syncer = class {
 * out of scope here (see the server-side validation note in the PR).
 */
 function hasUnbalancedLiquidDelimiters(content) {
-	const tagOpens = content.match(/\{%/g)?.length ?? 0;
-	const tagCloses = content.match(/%\}/g)?.length ?? 0;
-	const outputOpens = content.match(/\{\{/g)?.length ?? 0;
-	const outputCloses = content.match(/\}\}/g)?.length ?? 0;
-	return tagOpens !== tagCloses || outputOpens !== outputCloses;
+	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;
+}
+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;
+		}
+		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;
+		}
+		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;
+		}
+		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);
+	}
+	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
@@ -1711,17 +2647,57 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 	const syncResult = await syncer.uploadTheme({
 		delete: true,
 		validate: opts.validate,
+		linkManagedAssets: { replace: true },
+		pendingBinaryAssets: true,
 		onProgress: (done, total) => {
 			process.stdout.write(`\r  Uploading ${done}/${total} files…`);
 		}
 	});
 	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}`);
-	const stopWatcher = watchTheme(themeRoot, async (modified, added, removed) => {
+	} else if (syncResult.errors.length > 0) {
+		for (const e of syncResult.errors) console.error(`  ${e}`);
+		if (syncResult.uploaded + syncResult.deleted === 0) process.exit(1);
+	}
+	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;
+		}
 		const changed = [...modified, ...added];
 		for (const file of changed) {
 			if (opts.validate && file.isLiquid) {
@@ -1733,21 +2709,26 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 			}
 			pendingUpdates.add(file.relativePath);
 			try {
-				const uploadedContent = await syncer.uploadFile(file);
+				const uploadedContent = await syncer.uploadFile(file, void 0, { pendingAsset: 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);
 			}
 		}
-		for (const file of removed) try {
-			await syncer.deleteRemoteFile(file.relativePath);
-			console.log(`  ✓ removed ${file.relativePath}`);
-		} catch {}
+		for (const file of removed) {
+			if (themeRoot.ignore.ignore(file.relativePath)) continue;
+			try {
+				await syncer.deleteRemoteFile(file.relativePath);
+				console.log(`  ✓ removed ${file.relativePath}`);
+			} catch {}
+		}
 		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") {
@@ -1767,8 +2748,9 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 		} catch (e) {
 			console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
 			if (!res.headersSent) {
-				res.writeHead(502);
-				res.end("Bad Gateway");
+				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.`);
 			}
 		}
 	});
@@ -1944,21 +2926,42 @@ function resolveThemeRootFromCwd(workspace) {
 }
 //#endregion
 //#region src/commands/dev.ts
-async function ensureDevTheme(api, projectKey, identifier) {
+/**
+* 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 (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) {
+	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
+					name: existing.name,
+					...sourceThemeId === void 0 ? {} : { sourceThemeId }
 				});
 				return existing;
 			}
@@ -1966,13 +2969,11 @@ async function ensureDevTheme(api, projectKey, identifier) {
 		clearDevTheme(projectKey);
 	}
 	const { hostname } = await import("node:os");
-	const theme = (await createApplicationTheme(api, { application_theme: {
-		name: `Development (${hostname().split(".")[0] ?? "dev"}-${Math.random().toString(36).slice(2, 8)})`.slice(0, 50),
-		status: "development"
-	} })).application_theme;
+	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
+		name: theme.name,
+		...sourceThemeId === void 0 ? {} : { sourceThemeId }
 	});
 	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
 	return theme;
@@ -2015,7 +3016,7 @@ function createDevCommand() {
 			}
 		}
 		const projectKey = devThemeKey(company, themeRoot.root);
-		const theme = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey);
+		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 = () => {
@@ -2130,10 +3131,11 @@ var ShadowRepo = class ShadowRepo {
 		const { stdout } = await this.git([
 			"ls-tree",
 			"-r",
+			"-z",
 			"HEAD",
 			"--name-only"
 		]);
-		return stdout.toString("utf8").split("\n").filter((line) => line.length > 0);
+		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
@@ -2178,12 +3180,9 @@ var ShadowRepo = class ShadowRepo {
 	async commitState(files, message) {
 		const indexPath = mkdtempSync(join(tmpdir(), "fluid-shadow-")) + "/index";
 		try {
-			for (const { path, sha } of files) await this.git([
-				"update-index",
-				"--add",
-				"--cacheinfo",
-				`100644,${sha},${path}`
-			], { env: { GIT_INDEX_FILE: indexPath } });
+			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 = [
@@ -2420,6 +3419,7 @@ async function diffAgainstShadow(themeRoot, shadow) {
 	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);
@@ -2430,6 +3430,8 @@ async function diffAgainstShadow(themeRoot, shadow) {
 	}
 	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);
 	}
@@ -2496,15 +3498,37 @@ function containsConflictMarker(buf) {
 */
 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)
 		});
 	}
-	if (entries.length > 0) await shadow.commitState(entries, message);
+	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
@@ -2685,7 +3709,7 @@ async function fetchSyncActor(api, timeoutMs = 5e3) {
 //#endregion
 //#region src/commands/push.ts
 function createPushCommand() {
-	return new Command("push").description("Push local theme files to a remote theme").option("-t, --theme <name-or-id>", "Theme name or ID to push to").option("-n, --nodelete", "Do not delete remote files missing locally").option("-f, --force", "Skip schema validation and the server-side merge check").option("-p, --publish", "Publish the theme after pushing").option("-u, --unpublished", "Create a new unpublished theme and push to it").option("--auto-baseline", "When no local baseline exists, record the server's current state as the baseline and push only what differs locally (never modifies local files, never deletes server-only files)").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
+	return new Command("push").description("Push local theme files to a remote theme").option("-t, --theme <name-or-id>", "Theme name or ID to push to").option("-n, --nodelete", "Do not delete remote files missing locally").option("-f, --force", "Skip local Liquid validation and the server-side merge check").option("-p, --publish", "Publish the theme after pushing").option("-u, --unpublished", "Create a new unpublished theme and push to it").option("--auto-baseline", "When no local baseline exists, record the server's current state as the baseline and push only what differs locally (never modifies local files, never deletes server-only files)").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
 		requireToken();
 		let rootPath = opts.root;
 		if (rootPath === ".") {
@@ -2782,12 +3806,26 @@ function createPushCommand() {
 			}
 		}
 		const { changed, deleted } = await diffAgainstShadow(themeRoot, shadow);
-		if (changed.length === 0 && deleted.length === 0) {
+		const managedAssetCount = new ThemeAssetManifest(themeRoot.root).keys().length;
+		if (changed.length === 0 && deleted.length === 0 && managedAssetCount === 0) {
 			console.log("Nothing to push — local matches the last synced state.");
 			await persistConfig();
 			return;
 		}
 		const spinner = ora(`Pushing to ${theme.name} (#${theme.id})…`).start();
+		if (!opts.force) {
+			const validationErrors = [];
+			for (const file of changed) {
+				if (!file.isLiquid) continue;
+				for (const diagnostic of file.validateSchema()) if (diagnostic.severity === "error") validationErrors.push(`${file.relativePath}: ${diagnostic.message}`);
+				for (const diagnostic of findLiquidBlockTagDiagnostics(file.read())) validationErrors.push(`${file.relativePath}: ${diagnostic.message}`);
+			}
+			if (validationErrors.length > 0) {
+				spinner.fail(`Liquid validation failed (${validationErrors.length} error(s)). Use --force to skip.`);
+				for (const error of validationErrors) console.error(`  ${error}`);
+				process.exit(1);
+			}
+		}
 		try {
 			await syncer.preflightPush(baseSha);
 			baseSha = syncer.remoteSha() ?? baseSha;
@@ -2798,17 +3836,24 @@ function createPushCommand() {
 			}
 			throw e;
 		}
-		if (!opts.force) {
-			const errors = [];
-			for (const file of changed) {
-				if (!file.isLiquid) continue;
-				for (const d of file.validateSchema()) if (d.severity === "error") errors.push(`${file.relativePath}: ${d.message}`);
-			}
-			if (errors.length > 0) {
-				spinner.fail(`Schema validation failed (${errors.length} error(s)). Use --force to skip.`);
-				for (const err of errors) console.error(`  ${err}`);
+		let linked = 0;
+		try {
+			linked = await syncer.linkManagedAssets({ replace: true });
+			baseSha = syncer.remoteSha() ?? baseSha;
+		} catch (error) {
+			spinner.fail(`Could not save remote asset references: ${formatError(error)}`);
+			process.exit(1);
+		}
+		if (changed.length === 0 && deleted.length === 0 && linked === 0) {
+			try {
+				await finalizeManifestOnlyPush(syncer, themeRoot, shadow);
+			} catch (error) {
+				spinner.fail(`Could not finalize remote asset references: ${formatError(error)}`);
 				process.exit(1);
 			}
+			spinner.succeed("Nothing to push — local matches the remote theme.");
+			await persistConfig();
+			return;
 		}
 		let uploaded = 0;
 		let deletedCount = 0;
@@ -2845,10 +3890,17 @@ function createPushCommand() {
 			}
 			spinner.text = `Pushing ${++progress}/${total} files…`;
 		}
+		if (errors.length === 0) try {
+			syncer.repointManagedAssetsToCurrentTheme();
+		} catch (error) {
+			errors.push(`Save asset provenance: ${formatError(error)}`);
+		}
+		if (uploaded > 0 || deletedCount > 0 || linked > 0) await syncer.requestSync();
 		if (errors.length) {
 			spinner.warn(`Pushed with ${errors.length} error(s).`);
 			for (const err of errors) console.error(`  ${err}`);
-		} else spinner.succeed(`Pushed ${uploaded} file(s)` + (deletedCount > 0 ? `, deleted ${deletedCount} remote file(s).` : "."));
+			process.exitCode = 1;
+		} else spinner.succeed(`Pushed ${uploaded} file(s), saved ${linked} remote asset reference(s)` + (deletedCount > 0 ? `, deleted ${deletedCount} remote file(s).` : "."));
 		if (errors.length === 0) await commitPushedState(themeRoot, shadow, syncCommitSubject("Push", await getActor()));
 		await persistConfig();
 		/**
@@ -2888,6 +3940,7 @@ function createPushCommand() {
 				pubSpinner.succeed("Theme published.");
 			} catch (e) {
 				pubSpinner.fail(`Publish failed: ${e}`);
+				process.exitCode = 1;
 			}
 		}
 	});
@@ -2901,6 +3954,16 @@ function renderPullFirst(spinner) {
 }
 //#endregion
 //#region src/theme/merge-pull.ts
+/** `write(..., RESOLVES_CONFLICT)`: this write is the chosen side of a conflict. */
+const RESOLVES_CONFLICT = true;
+/**
+* Appended to every per-file write failure. Resource keys are verbatim
+* relative paths, so a template named `Sale 11/14/2025, 12:30 PM` asks
+* the filesystem for directories that Windows (and any path already
+* occupied by a file) refuses. Renaming the template in the admin is
+* the only fix the user owns.
+*/
+const RENAME_REMEDY = "Rename the template in the admin visual builder to remove / \\ : * ? \" < > | from its name, then pull again.";
 /**
 * Reconcile the just-downloaded remote tree against the working tree,
 * using the shadow repo's HEAD as the merge base. Text files that
@@ -2928,18 +3991,46 @@ async function mergePull(input) {
 		errors: []
 	};
 	const pendingWrites = [];
-	const write = (file, content) => {
-		if (input.resolve) pendingWrites.push({
-			file,
-			content
-		});
-		else file.write(content);
+	const unwrittenKeys = /* @__PURE__ */ new Set();
+	const tryWrite = (key, file, content) => {
+		try {
+			file.write(content);
+			return true;
+		} catch (e) {
+			unwrittenKeys.add(key);
+			result.errors.push(`Reconcile ${key}: ${errMsg(e)}. ${RENAME_REMEDY}`);
+			return false;
+		}
+	};
+	/**
+	* Write `content`, then apply `record` — the bookkeeping that says
+	* which bucket of the summary this file counted as. The two travel
+	* together, including into the deferred flush: bookkeeping applied
+	* when the write was merely QUEUED would report a file the flush
+	* never managed to write as both written and errored.
+	*/
+	const write = (key, file, content, record, resolvesConflict = false) => {
+		if (input.resolve) {
+			pendingWrites.push({
+				key,
+				file,
+				content,
+				record,
+				resolvesConflict
+			});
+			return;
+		}
+		if (tryWrite(key, file, content)) record();
 	};
 	const remoteContent = /* @__PURE__ */ new Map();
 	const remoteKeys = /* @__PURE__ */ new Set();
 	let done = 0;
 	for (const resource of remote) {
 		remoteKeys.add(resource.key);
+		if (input.skipRemoteKeys?.has(resource.key)) {
+			onProgress?.(++done, remote.length);
+			continue;
+		}
 		try {
 			const buf = await materialize(resource, fetchBinary);
 			if (buf) remoteContent.set(resource.key, buf);
@@ -2952,18 +4043,17 @@ async function mergePull(input) {
 		const file = themeRoot.file(key);
 		if (!file.absolutePath.startsWith(themeRoot.root + sep)) {
 			result.errors.push(`Reconcile ${key}: path traversal detected`);
+			unwrittenKeys.add(key);
 			continue;
 		}
 		if (input.force) {
-			write(file, remoteBuf);
-			result.written++;
+			write(key, file, remoteBuf, () => result.written++);
 			continue;
 		}
 		const localBuf = readIfExists(file.absolutePath);
 		const baseBuf = await shadow.blobAtHead(key);
 		if (localBuf == null) {
-			write(file, remoteBuf);
-			result.written++;
+			write(key, file, remoteBuf, () => result.written++);
 			continue;
 		}
 		if (localBuf.equals(remoteBuf)) {
@@ -2971,11 +4061,14 @@ async function mergePull(input) {
 			continue;
 		}
 		if (baseBuf && localBuf.equals(baseBuf)) {
-			write(file, remoteBuf);
-			result.written++;
+			write(key, file, remoteBuf, () => result.written++);
 			continue;
 		}
 		if (baseBuf && remoteBuf.equals(baseBuf)) {
+			if (input.resolve === "remote" && !looksBinary(localBuf) && hasGeneratedConflictMarkers(localBuf)) {
+				write(key, file, remoteBuf, () => result.autoResolved.push(`${key} (cleared conflict markers)`), RESOLVES_CONFLICT);
+				continue;
+			}
 			result.skipped++;
 			continue;
 		}
@@ -2984,24 +4077,25 @@ async function mergePull(input) {
 				result.autoResolved.push(`${key} (binary — kept local)`);
 				continue;
 			}
-			write(file, remoteBuf);
-			if (input.resolve === "remote") result.autoResolved.push(`${key} (binary — kept remote)`);
-			else result.conflicts.push(`${key} (binary — kept remote)`);
+			write(key, file, remoteBuf, () => {
+				if (input.resolve === "remote") result.autoResolved.push(`${key} (binary — kept remote)`);
+				else result.conflicts.push(`${key} (binary — kept remote)`);
+			}, input.resolve === "remote");
 			continue;
 		}
 		const { merged, hasConflicts } = await shadow.merge3(baseBuf, localBuf, remoteBuf);
 		if (hasConflicts && input.resolve) {
-			write(file, (await shadow.merge3(baseBuf, localBuf, remoteBuf, input.resolve)).merged);
-			result.autoResolved.push(key);
+			write(key, file, (await shadow.merge3(baseBuf, localBuf, remoteBuf, input.resolve)).merged, () => result.autoResolved.push(key), RESOLVES_CONFLICT);
 			continue;
 		}
-		write(file, merged);
-		if (hasConflicts) result.conflicts.push(key);
-		else result.merged++;
+		write(key, file, merged, () => {
+			if (hasConflicts) result.conflicts.push(key);
+			else result.merged++;
+		});
 	}
 	if (input.resolve) {
-		if (result.autoResolved.length > 0) await commitPushedState(themeRoot, shadow, syncCommitSubject("Snapshot before pull", input.actor ?? null));
-		for (const { file, content } of pendingWrites) file.write(content);
+		if (pendingWrites.some((w) => w.resolvesConflict)) await commitPushedState(themeRoot, shadow, syncCommitSubject("Snapshot before pull", input.actor ?? null));
+		for (const { key, file, content, record } of pendingWrites) if (tryWrite(key, file, content)) record();
 	}
 	if (doDelete && await shadow.hasHead()) for (const file of themeRoot.files()) {
 		if (remoteKeys.has(file.relativePath)) continue;
@@ -3017,12 +4111,16 @@ async function mergePull(input) {
 		} catch {}
 	}
 	const commitEntries = [];
-	for (const [key, buf] of remoteContent) commitEntries.push({
-		path: key,
-		sha: await shadow.writeBlob(buf)
-	});
+	for (const [key, buf] of remoteContent) {
+		if (unwrittenKeys.has(key)) continue;
+		commitEntries.push({
+			path: key,
+			sha: await shadow.writeBlob(buf)
+		});
+	}
 	for (const key of remoteKeys) {
-		if (remoteContent.has(key)) continue;
+		if (input.skipRemoteKeys?.has(key)) continue;
+		if (remoteContent.has(key) && !unwrittenKeys.has(key)) continue;
 		const prevBlob = await shadow.blobAtHead(key);
 		if (prevBlob == null) continue;
 		commitEntries.push({
@@ -3030,9 +4128,23 @@ async function mergePull(input) {
 			sha: await shadow.writeBlob(prevBlob)
 		});
 	}
-	if (commitEntries.length > 0) await shadow.commitState(commitEntries, syncCommitSubject("Pull", input.actor ?? null));
+	const assetManifest = new ThemeAssetManifest(themeRoot.root);
+	let managedAssetSentinelSha;
+	for (const key of input.skipRemoteKeys ?? []) {
+		if (!remoteKeys.has(key) || !assetManifest.has(key)) continue;
+		managedAssetSentinelSha ??= await shadow.writeBlob(MANAGED_ASSET_SHADOW_SENTINEL);
+		commitEntries.push({
+			path: key,
+			sha: managedAssetSentinelSha
+		});
+	}
+	if (commitEntries.length > 0 || remoteKeys.size === 0 && await shadow.hasHead()) await shadow.commitState(commitEntries, syncCommitSubject("Pull", input.actor ?? null));
 	return result;
 }
+function hasGeneratedConflictMarkers(content) {
+	const text = content.toString("utf8");
+	return /^<<<<<<< local\r?$/m.test(text) && /^=======\r?$/m.test(text) && /^>>>>>>> remote\r?$/m.test(text);
+}
 async function materialize(resource, fetchBinary) {
 	if (resource.resource_type === "FileResource" && resource.url) return fetchBinary(resource.url);
 	if (resource.content == null) return null;
@@ -3098,28 +4210,34 @@ 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 externalizedAssets = await syncer.externalizePulledAssets(resources, { delete: !opts.nodelete });
 		const result = await mergePull({
 			themeRoot,
 			shadow,
-			remote: await syncer.downloadAll(),
+			remote: resources,
 			fetchBinary: (url) => syncer.downloadBinaryAsset(url),
 			delete: !opts.nodelete,
 			force: opts.force ?? false,
+			skipRemoteKeys: externalizedAssets.managedKeys,
 			resolve: resolveSide,
 			actor: await actorPromise,
 			onProgress: (done, total) => {
 				spinner.text = `Downloading ${done}/${total} files…`;
 			}
 		});
+		result.errors.push(...externalizedAssets.errors);
 		const parts = [];
 		if (result.written > 0) parts.push(`wrote ${result.written} file(s)`);
 		if (result.merged > 0) parts.push(`merged ${result.merged} file(s) cleanly`);
+		if (externalizedAssets.linked > 0) parts.push(`kept ${externalizedAssets.linked} binary asset(s) remote`);
 		if (result.autoResolved.length > 0) parts.push(`auto-resolved ${result.autoResolved.length} conflict(s) (kept ${resolveSide})`);
 		if (result.deleted > 0) parts.push(`deleted ${result.deleted} local file(s)`);
 		if (result.skipped > 0) parts.push(`${result.skipped} already in sync`);
 		if (result.errors.length) {
 			spinner.warn(`Pulled with ${result.errors.length} error(s): ${parts.join(", ")}.`);
 			for (const e of result.errors) console.error(`  ${e}`);
+			process.exitCode = 1;
 		} else if (result.conflicts.length > 0) {
 			spinner.warn(`${result.conflicts.length} conflict(s) — resolve markers before pushing: ${parts.join(", ")}.`);
 			console.log();
@@ -3176,6 +4294,7 @@ function createLintCommand() {
 		for (const { file, content } of liquidFiles) {
 			const blocksSchemaType = file.isTemplate ? "object" : "array";
 			for (const diagnostic of validateSchemaText(content, { blocksSchemaType })) record(file.relativePath, diagnostic);
+			for (const diagnostic of findLiquidBlockTagDiagnostics(content)) record(file.relativePath, diagnostic);
 		}
 		const existingSectionNames = /* @__PURE__ */ new Set();
 		for (const { file } of liquidFiles) {