@aippy/vite-plugins 0.4.0-dev.2 → 0.4.0-dev.4

package/README.md

@@ -102,10 +102,12 @@ const projectRoot = findProjectRoot(); // '/path/to/project'
 
 UNLICENSED - Aippy Team
 
-## Asset manifest v1
+## Asset files
 
-Version 0.4.0-dev.1 reads both legacy flat URL inventories and `schemaVersion: 1` manifests. Assets Agent writes resource plans; development builds preserve their metadata and supplement resources discovered by the existing scanner. Invalid v1 inventories and manifest/wrapper write failures stop the build.
+`src/config/assets.json` is a flat URL dictionary. The plugin writes only that file. The project-root `assets-plan.json` is read-only input for reserved names and `implementation.path` exclusions. The plugin does not validate the plan; aippy-chat does. A missing or unreadable plan does not stop the build. Invalid dictionary JSON, a single-file v1 plan stored in the dictionary, or a failed dictionary/wrapper write stops the build without overwriting the file. A source file the plugin cannot parse or rewrite only logs a warning.
 
-Import the generated flat URL map from `@/config/assets`. Only entries with usable URLs appear in that map; the existing `window.getReplacedAssets` hook still mutates it in place. Source-code assets and generated fallbacks with an exact `implementation.path` retain their original source references. Preload reads resource URLs rather than generation prompts or error text. The JSON schema is exported as `@aippy/vite-plugins/assets.schema.json`; parser checks also enforce byte, reference and semantic constraints.
+Import the generated map from `@/config/assets`. It exports the dictionary's string values. `window.getReplacedAssets` still mutates that object in place. Preload reads those string values and URLs in other source files, not prompts inside the plan.
 
-Pending the next dev release, wrappers retain only historical flat placeholder keys listed in `legacyPlaceholderKeys` as empty strings; other unavailable media remain absent. Concrete code assets continue to use their source references. These changes are not included in the published 0.4.0-dev.1 package.
+Source written as `aippy-asset:` + `encodeURIComponent(key)` + `:` + url rewrites to that dictionary key. The url may be any reference aippy-chat accepts (`ValidReference`): http(s), root-relative, or relative. A token the rewrite cannot reach (template literal, CSS, HTML, unknown key) is reduced to its plain url, on disk in `devMode` and in every build's `transform`, so a token never reaches the browser.
+
+Version 0.4.0-dev.3 is published. The `dev` dist-tag points at it. `latest` remains `0.3.0`.

package/dist/aippy-preload/html-utils.d.ts

@@ -1,11 +1,6 @@
 /**
  * HTML processing utilities for aippy preload plugin
  */
-/**
- * Generate meta tags for asset preloading
- * @param assets - Array of asset URLs
- * @returns HTML meta tags string
- */
 export declare function generateMetaTags(assets: string[]): string;
 /**
  * Inject meta tags into HTML content

package/dist/aippy-preload/index.js

@@ -1,2 +1,2 @@
-import { t as e } from "../aippy-preload-Dhhw3O6d.js";
+import { t as e } from "../aippy-preload-BjhVTEKH.js";
 export { e as aippyPreloadPlugin, e as default };

package/dist/aippy-preload-BjhVTEKH.js

@@ -0,0 +1,175 @@
+import { extractAssetsFromContent as e, isValidAsset as t } from "./utils/index.js";
+import { l as n, m as r, s as i } from "./generator-utils-VznlFF00.js";
+import { promises as a } from "fs";
+import o from "path";
+//#region src/aippy-preload/scanner-utils.ts
+async function s(t) {
+	let n = [], r = [o.join(process.cwd(), "index.html")];
+	for (let o of r) try {
+		let r = i(await a.readFile(o, "utf-8")), s = e(r, "html", t);
+		n.push(...s);
+	} catch {
+		console.warn("⚠️  No index.html found in project root");
+	}
+	return n;
+}
+async function c(t, s) {
+	let c = [], l = o.resolve(t, "config/assets.json"), u = /* @__PURE__ */ new Set();
+	try {
+		let e = JSON.parse(await a.readFile(l, "utf8"));
+		e && typeof e == "object" && !Array.isArray(e) && (u = new Set(Object.keys(e)));
+	} catch {}
+	let d = await r(t, [
+		".ts",
+		".tsx",
+		".js",
+		".jsx"
+	]);
+	for (let r of d) try {
+		let o = i(await a.readFile(r, "utf-8")), d = e(o, "js", s);
+		d.some((e) => u.has(e)) && (d = e(n(o, r, t, l), "js", s)), c.push(...d);
+	} catch (e) {
+		console.warn(`⚠️  Failed to read JS file: ${r}`, e);
+	}
+	return c;
+}
+async function l(t, n) {
+	let o = [], s = await r(t, [
+		".css",
+		".scss",
+		".sass",
+		".less"
+	]);
+	for (let t of s) try {
+		let r = i(await a.readFile(t, "utf-8")), s = e(r, "css", n);
+		o.push(...s);
+	} catch (e) {
+		console.warn(`⚠️  Failed to read CSS file: ${t}`, e);
+	}
+	return o;
+}
+function u(e, n) {
+	if (!t(e) || /["'<>\s`]/.test(e)) return !1;
+	let r = e.split(/[?#]/, 1)[0].toLowerCase();
+	return n.some((e) => r.endsWith(e.toLowerCase()));
+}
+async function d(t, n) {
+	let s = [], c = await r(t, [".json"]);
+	for (let r of c) try {
+		let c = i(await a.readFile(r, "utf-8"));
+		if (o.basename(r) === "assets-plan.json") continue;
+		if (o.resolve(r) === o.resolve(t, "config/assets.json")) {
+			let e = JSON.parse(c);
+			if (e && typeof e == "object" && !Array.isArray(e)) {
+				for (let t of Object.values(e)) typeof t == "string" && u(t, n) && s.push(t);
+				continue;
+			}
+		}
+		let l = e(c, "js", n);
+		s.push(...l);
+	} catch (e) {
+		console.warn(`⚠️  Failed to read JSON file: ${r}`, e);
+	}
+	return s;
+}
+async function f(e, t, n) {
+	console.log("🔍 Scanning source files for static assets...");
+	let r = [];
+	if (n) {
+		console.log("🔍 Deep scanning source file contents...");
+		let [n, i, a, o] = await Promise.all([
+			s(t),
+			c(e, t),
+			l(e, t),
+			d(e, t)
+		]);
+		r.push(...n, ...i, ...a, ...o);
+	}
+	return [...new Set(r)];
+}
+//#endregion
+//#region src/aippy-preload/html-utils.ts
+var p = "<head>", m = 6;
+function h(e) {
+	return e.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function g(e) {
+	return e.map((e) => `    <meta content="${h(e)}" name="aippy:preload">`).join("\n");
+}
+function _(e, t) {
+	let n = e.indexOf(p);
+	if (n === -1) throw Error("Could not find <head> tag in HTML");
+	let r = n + m;
+	return e.slice(0, r) + "\n" + t + "\n" + e.slice(r);
+}
+function v(e) {
+	let t = e.length;
+	if (console.log(`📁 Found ${t} static ${t === 1 ? "asset" : "assets"} in source files`), t === 0) {
+		console.log("⚠️  No static assets found in source files.");
+		return;
+	}
+	console.log(`📋 ${t === 1 ? "Asset" : "Assets"} found:`), e.forEach((e) => console.log(`   - ${e}`));
+}
+function y(e) {
+	console.log(`✅ Injected ${e} preload meta ${e === 1 ? "tag" : "tags"} into index.html`);
+}
+//#endregion
+//#region src/aippy-preload/index.ts
+var b = 3, x = 1e3;
+function S(e) {
+	return new Promise((t) => setTimeout(t, e));
+}
+async function C(e, t = b, n = x) {
+	for (let r = 1; r <= t; r++) try {
+		return await a.readFile(e, "utf-8");
+	} catch (e) {
+		if (e.code === "ENOENT") {
+			if (r < t) {
+				console.log(`⏳ index.html not found, waiting ${n}ms before retry (attempt ${r}/${t})...`), await S(n);
+				continue;
+			}
+			return console.log(`⚠️ index.html not found after ${t} attempts, skipping preload injection.`), null;
+		}
+		return console.error("❌ Error reading index.html:", e), null;
+	}
+	return null;
+}
+function w(e = {}) {
+	let t = {
+		extensions: [
+			".png",
+			".jpg",
+			".jpeg",
+			".gif",
+			".svg",
+			".mp4",
+			".mp3",
+			".wav",
+			".ogg",
+			".webm"
+		],
+		srcDir: "src",
+		outDir: "dist",
+		deepScan: !0,
+		...e
+	};
+	return {
+		name: "vite-plugin-aippy-preload",
+		apply: "build",
+		enforce: "post",
+		async writeBundle() {
+			try {
+				let e = await f(t.srcDir, t.extensions, t.deepScan);
+				if (v(e), e.length === 0) return;
+				let n = o.join(t.outDir, "index.html"), r = await C(n);
+				if (r === null) return;
+				let i = _(r, g(e));
+				await a.writeFile(n, i, "utf-8"), y(e.length);
+			} catch (e) {
+				console.error("❌ Error in aippy preload plugin:", e);
+			}
+		}
+	};
+}
+//#endregion
+export { w as t };

package/dist/asset-constants/generator-utils.d.ts

@@ -1,12 +1,38 @@
 import { AssetInfo } from './types';
-import { AssetDocument } from './manifest';
+/** A flat dictionary is a v1 plan only when schemaVersion is a number and assets is an object. */
+export declare function isSingleFilePlan(value: unknown): boolean;
+export declare const ASSET_TOKEN_PREFIX = "aippy-asset:";
 /**
- * Generate assets.json file content from asset info
- * @param assets - Map of assets
- * @param existingAssets - Map of existing assets from previous runs
- * @returns JSON string
+ * Mirrors aippy-chat `assetmanifest.ValidReference`: every value the server
+ * puts in the inventory as a usable url must be accepted here, including
+ * root-relative and relative paths.
  */
-export declare function generateAssetsFileContent(assets: Map<string, AssetInfo>, existingAssets: Map<string, string>, document?: AssetDocument): string;
+export declare function isDictionaryResourceURL(value: string): boolean;
+/** Keys that own each usable dictionary URL. A shared URL lists every key. */
+export declare function dictionaryResourceOwners(flat: Record<string, unknown>): Map<string, string[]>;
+/** Percent-encode a dictionary key so `:` and `$` cannot be read as separators. */
+export declare function encodeAssetKey(key: string): string;
+/**
+ * `aippy-asset:<encodeURIComponent(key)>:<url>`.
+ * The key ends at the first raw colon. `hero:mobile` must be `hero%3Amobile`;
+ * splitting that unencoded form would name `hero` and is rejected because the
+ * remainder `mobile:https://...` is not a resource reference.
+ */
+export declare function parseAssetToken(value: string): {
+    key: string;
+    url: string;
+} | undefined;
+/**
+ * Drop the `aippy-asset:<key>:` prefix from any token the key rewrite did not
+ * reach (template literals, CSS, HTML, unknown keys), leaving the url itself.
+ * A literal token is never a loadable resource.
+ */
+export declare function stripAssetTokens(code: string): string;
+/**
+ * Write the flat dictionary. Existing keys and non-string values stay; scanned
+ * resources only add a key when that URL is not already present.
+ */
+export declare function generateAssetsFileContent(assets: Map<string, AssetInfo>, existingAssets: Map<string, string>, flat?: Record<string, unknown>): string;
 /**
  * Parse existing assets.json file
  * @param content - File content

package/dist/asset-constants/index.js

@@ -1,2 +1,391 @@
-import { t as e } from "../asset-constants-BUK7zWRd.js";
-export { e as assetConstantsPlugin, e as default };
+import { extractAssetsFromContent as e, generateConstantName as t, processAssetURL as n } from "../utils/index.js";
+import { a as r, c as i, d as a, f as o, g as s, h as c, i as l, l as u, m as d, n as f, o as p, p as m, r as h, s as g, t as _, u as v } from "../generator-utils-VznlFF00.js";
+import { promises as y } from "fs";
+import b from "path";
+import { parse as x } from "@babel/parser";
+import S from "@babel/traverse";
+import * as C from "@babel/types";
+import w from "@babel/generator";
+//#region src/asset-constants/index.ts
+var T = typeof S == "function" ? S : S.default, E = typeof w == "function" ? w : w.default, D = class extends Error {}, O = class {
+	constructor(e = {}) {
+		s(this, "options", void 0), s(this, "assets", /* @__PURE__ */ new Map()), s(this, "existingAssets", /* @__PURE__ */ new Map()), s(this, "flat", {}), s(this, "fileCache", new o()), s(this, "planKeys", void 0), s(this, "implementationPaths", /* @__PURE__ */ new Set()), s(this, "keyRefFiles", /* @__PURE__ */ new Set()), this.options = {
+			extensions: [
+				".png",
+				".jpg",
+				".jpeg",
+				".gif",
+				".svg",
+				".mp4",
+				".mp3",
+				".wav",
+				".ogg",
+				".webm"
+			],
+			srcDir: "src",
+			outputFile: "src/config/assets.json",
+			devMode: !1,
+			...e
+		};
+	}
+	clearCache() {
+		this.fileCache.clear();
+	}
+	generateConstantName(e) {
+		let n = /* @__PURE__ */ new Set([
+			...Array.from(this.assets.values()).map((e) => e.constantName),
+			...Array.from(this.existingAssets.values()),
+			...this.planKeys ?? []
+		]);
+		return t(e, n);
+	}
+	async scanTsFile(t) {
+		try {
+			let n = await this.fileCache.read(t), r = [], i = e(n, "js", this.options.extensions), a = /* @__PURE__ */ new Set([...Object.keys(this.flat), ...this.planKeys ?? []]);
+			if (i.some((e) => a.has(e))) {
+				let r = u(n, t, this.options.srcDir, this.options.outputFile);
+				i = e(r, "js", this.options.extensions);
+			}
+			let o = n.split("\n"), s = _(this.flat);
+			i = i.filter((e) => {
+				if (e.startsWith("aippy-asset:") || !n.includes(`"${e}"`) && !n.includes(`'${e}'`)) return !1;
+				let t = s.get(e);
+				return !t || t.length === 1;
+			}), i.forEach((e) => {
+				if (this.isImplementationReference(t, e)) return;
+				let n = this.generateConstantName(e), i = o.findIndex((t) => t.includes(e)) + 1;
+				r.push({
+					originalUri: e,
+					constantName: n,
+					filePath: t,
+					line: i,
+					column: 1
+				});
+			}), n.includes("aippy-asset:") && this.keyRefFiles.add(t);
+			let c = new Set(r.map((e) => e.originalUri));
+			for (let [e, i] of s) i.length !== 1 || c.has(e) || !n.includes(`"${e}"`) && !n.includes(`'${e}'`) || r.push({
+				originalUri: e,
+				constantName: i[0],
+				filePath: t,
+				line: 1,
+				column: 1
+			});
+			return r;
+		} catch (e) {
+			return console.warn(`Warning: Failed to scan ${t}:`, e), [];
+		}
+	}
+	async scanAllTsFiles() {
+		let e = this.options.srcDir;
+		try {
+			let t = await d(e, [".ts", ".tsx"]);
+			for (let e of t) {
+				if (e.endsWith("assets.json") || e.endsWith("assets.ts")) continue;
+				let t = await this.scanTsFile(e), n = _(this.flat);
+				t.forEach((e) => {
+					let t = n.get(e.originalUri);
+					if (t && t.length > 1) return;
+					t && t.length === 1 ? e.constantName = t[0] : this.existingAssets.has(e.originalUri) && (e.constantName = this.existingAssets.get(e.originalUri));
+					let r = e.originalUri;
+					this.assets.has(r) || this.assets.set(r, e);
+				});
+			}
+		} catch (e) {
+			console.error("Error scanning TypeScript files:", e);
+		}
+	}
+	async readExistingAssetsFile() {
+		try {
+			return await y.readFile(this.options.outputFile, "utf-8");
+		} catch (e) {
+			if (e.code === "ENOENT") return "";
+			throw new D("Unable to read assets.json: " + String(e));
+		}
+	}
+	sidecarPath() {
+		return b.resolve(this.options.srcDir, "..", "assets-plan.json");
+	}
+	async parseExistingAssets() {
+		let e = await this.readExistingAssetsFile();
+		if (e.trim()) {
+			let t;
+			try {
+				t = JSON.parse(e);
+			} catch {
+				throw new D("assets: invalid JSON syntax");
+			}
+			if (h(t)) throw new D("assets: single-file asset plan is not supported");
+			if (!t || typeof t != "object" || Array.isArray(t)) throw new D("assets: URL dictionary object required");
+			this.flat = { ...t };
+		}
+		try {
+			this.existingAssets = p(e);
+		} catch (e) {
+			throw new D(e instanceof Error ? e.message : "assets: invalid JSON syntax");
+		}
+		await this.readSidecar();
+	}
+	async readSidecar() {
+		let e = "";
+		try {
+			e = await y.readFile(this.sidecarPath(), "utf-8");
+		} catch (e) {
+			e.code !== "ENOENT" && console.warn("assets: unable to read assets-plan.json; continuing with the dictionary only");
+			return;
+		}
+		if (!e.trim()) return;
+		let t;
+		try {
+			t = JSON.parse(e);
+		} catch {
+			console.warn("assets: assets-plan.json is not valid JSON; continuing with the dictionary only");
+			return;
+		}
+		if (!h(t)) {
+			console.warn("assets: assets-plan.json is not a plan; continuing with the dictionary only");
+			return;
+		}
+		let n = t.assets;
+		this.planKeys = Object.keys(n);
+		let r = b.resolve(this.options.srcDir, "..");
+		for (let e of Object.values(n)) {
+			let t = e?.implementation?.path;
+			typeof t == "string" && t && this.implementationPaths.add(b.resolve(r, t));
+		}
+	}
+	isImplementationReference(e, t) {
+		if (!this.implementationPaths.size || /^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//")) return !1;
+		let n = t.split(/[?#]/)[0], r = n.startsWith("@/") ? b.resolve(this.options.srcDir, n.slice(2)) : b.resolve(b.dirname(e), n);
+		return this.implementationPaths.has(r);
+	}
+	async generateAssetsFile() {
+		await this.parseExistingAssets(), await this.scanAllTsFiles();
+		let e = f(this.assets, this.existingAssets, this.flat);
+		try {
+			let t = b.dirname(this.options.outputFile);
+			await y.mkdir(t, { recursive: !0 }), await y.writeFile(this.options.outputFile, e, "utf-8"), await this.generateAssetsWrapper();
+		} catch (e) {
+			throw new D("Unable to write the asset dictionary or wrapper: " + String(e));
+		}
+		l(this.assets.size, this.existingAssets, this.assets, this.options.outputFile);
+	}
+	async generateAssetsWrapper() {
+		let e = this.options.outputFile.replace(/\.json$/, ".ts"), t = `// 🍎 Auto-generated wrapper for assets.json
+// This file handles iOS image replacement via asset-interceptor.js
+import assetsData from "./${b.basename(this.options.outputFile)}";
+
+// Batch process all asset URLs for potential replacements
+// sessionStorage may contain __aippy_asset_overrides__ with multiple image mappings
+(window as any).getReplacedAssets?.(assetsData);
+
+export default assetsData;
+`;
+		await y.writeFile(e, t, "utf-8"), console.log(`  ✓ Generated assets wrapper: ${b.relative(process.cwd(), e)}`);
+	}
+	getAssets() {
+		return Array.from(this.assets.values());
+	}
+	isReplacementCandidate(e, t) {
+		let i = r(e);
+		return i && Object.hasOwn(this.flat, i.key) ? !0 : t.has(n(e));
+	}
+	replaceLiteral(e, t, n) {
+		let r = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(n), i = C.memberExpression(C.identifier(t), r ? C.identifier(n) : C.stringLiteral(n), !r);
+		if ((C.isObjectProperty(e.parent) || C.isObjectMethod(e.parent) || C.isClassProperty(e.parent) || C.isClassMethod(e.parent)) && e.key === "key" && (e.parent.computed = !0), e.parent && C.isJSXAttribute(e.parent)) return e.replaceWith(C.jsxExpressionContainer(i)), !0;
+		try {
+			C.validate(e.parent, e.key, i);
+		} catch {
+			return !1;
+		}
+		return e.replaceWith(i), !0;
+	}
+	async replaceUrisInFile(e, t) {
+		try {
+			let o = await this.fileCache.read(e), s = x(o, {
+				sourceType: "module",
+				plugins: [
+					"typescript",
+					"jsx",
+					"decorators-legacy"
+				]
+			}), c = !1, l = this.options.outputFile.replace(/\.json$/, ".ts"), u = m(l, this.options.srcDir), d = v(e, this.options.srcDir, this.options.outputFile), f = a(s, d), p = "assetsData", h = !1, g, _ = /* @__PURE__ */ new Set();
+			T(s, {
+				Identifier: (e) => {
+					_.add(e.node.name);
+				},
+				ImportDeclaration: (e) => {
+					if (!(!d.has(e.node.source.value) || e.node.importKind === "type")) for (let t of e.node.specifiers) {
+						if (t.importKind === "type") continue;
+						let n = e.scope.getBinding(t.local.name);
+						i(t) && (p = t.local.name, h = !0, g = n);
+					}
+				}
+			});
+			let S = !1;
+			if (h && T(s, { StringLiteral: (n) => {
+				!C.isImportDeclaration(n.parent) && !f(n) && !this.isImplementationReference(e, n.node.value) && this.isReplacementCandidate(n.node.value, t) && n.scope.getBinding(p) !== g && (S = !0);
+			} }), !h && _.has(p) || S) {
+				let e = "aippyAssetsData";
+				for (let t = 2; _.has(e); t++) e = `aippyAssetsData${t}`;
+				S && g.scope.rename(p, e), p = e;
+			}
+			if (T(s, { StringLiteral: (i) => {
+				let a = i.node.value;
+				if (this.isImplementationReference(e, a) || f(i) || C.isImportDeclaration(i.parent) || C.isExportNamedDeclaration(i.parent) || C.isExportAllDeclaration(i.parent) || i.findParent((e) => C.isTSType(e.node) || C.isTSInterfaceBody(e.node))) return;
+				let o = r(a);
+				if (o && Object.hasOwn(this.flat, o.key)) {
+					this.replaceLiteral(i, p, o.key) && (i.skip(), c = !0);
+					return;
+				}
+				let s = n(a);
+				if (t.has(s)) {
+					let e = t.get(s);
+					this.replaceLiteral(i, p, e) && (i.skip(), c = !0);
+				}
+			} }), !c) return;
+			if (!h) {
+				let e = C.importDeclaration([C.importDefaultSpecifier(C.identifier(p))], C.stringLiteral(u));
+				s.program.body.unshift(e);
+			}
+			let w = E(s, {
+				retainLines: !1,
+				comments: !0,
+				compact: !1
+			}, o);
+			await y.writeFile(e, w.code, "utf-8"), this.fileCache.invalidate(e), console.log(`  ✓ Replaced URIs in ${b.relative(process.cwd(), e)}`);
+		} catch (t) {
+			console.warn(`Warning: Failed to replace URIs in ${e}:`, t);
+		}
+	}
+	async replaceAllUris() {
+		let e = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Set();
+		for (let n of this.assets.values()) e.set(n.originalUri, n.constantName), t.add(n.filePath);
+		for (let e of this.keyRefFiles) t.add(e);
+		for (let n of t) await this.replaceUrisInFile(n, e);
+	}
+	needsRewrite() {
+		return this.assets.size > 0 || this.keyRefFiles.size > 0;
+	}
+	async cleanupUnusedConstants() {
+		if (!this.planKeys) try {
+			let e = await this.readExistingAssetsFile();
+			if (!e.trim()) return;
+			let t = /* @__PURE__ */ new Map();
+			try {
+				let n = JSON.parse(e);
+				for (let [e, r] of Object.entries(n)) typeof r == "string" && t.set(e, r);
+			} catch (e) {
+				console.warn("Warning: Failed to parse assets.json:", e);
+				return;
+			}
+			if (t.size === 0) return;
+			let n = /* @__PURE__ */ new Set(), r = await d(this.options.srcDir, [".ts", ".tsx"]);
+			for (let e of r) if (!(e.endsWith("assets.json") || e.endsWith("assets.ts"))) try {
+				let r = await this.fileCache.read(e);
+				for (let e of t.keys()) r.includes(e) && n.add(e);
+			} catch (t) {
+				console.warn(`Warning: Failed to read ${e}:`, t);
+			}
+			let i = [];
+			for (let e of t.keys()) n.has(e) || i.push(e);
+			if (i.length > 0) {
+				console.log(`🧹 Removing ${i.length} unused constant(s):`), i.forEach((e) => {
+					console.log(`  - ${e}`);
+				});
+				let e = [];
+				for (let n of i) {
+					let r = t.get(n);
+					r && e.push(r);
+				}
+				for (let t of e) this.assets.delete(t);
+			} else console.log("✅ All constants are in use");
+		} catch (e) {
+			console.warn("Warning: Failed to cleanup unused constants:", e);
+		}
+	}
+	async upgradeJsonImportsToTs() {
+		let e = this.options.outputFile.replace(/\.json$/, ".ts"), t = m(e, this.options.srcDir), n = await d(this.options.srcDir, [".ts", ".tsx"]), r = 0;
+		for (let i of n) if (!(i.endsWith("assets.ts") || i.endsWith("assets.json"))) try {
+			let n = await this.fileCache.read(i), a = c(i, this.options.outputFile) + ".json", o = c(i, e), s = m(this.options.outputFile, this.options.srcDir) + ".json";
+			if (!n.includes(a) && !n.includes(o) && !n.includes(s)) continue;
+			let l = x(n, {
+				sourceType: "module",
+				plugins: [
+					"typescript",
+					"jsx",
+					"decorators-legacy"
+				]
+			}), u = !1;
+			if (T(l, { ImportDeclaration: (e) => {
+				let n = e.node.source.value;
+				(n === a || n === o || n === s) && (e.node.source.value = t, u = !0);
+			} }), u) {
+				let e = E(l, {
+					retainLines: !1,
+					comments: !0,
+					compact: !1
+				}, n);
+				await y.writeFile(i, e.code, "utf-8"), this.fileCache.invalidate(i), console.log(`  ✓ Upgraded import in ${b.relative(process.cwd(), i)} → ${t}`), r++;
+			}
+		} catch (e) {
+			console.warn(`Warning: Failed to upgrade imports in ${i}:`, e);
+		}
+		r > 0 && console.log(`✅ Upgraded ${r} file(s) to use ${t}`);
+	}
+	async stripUnresolvedTokens() {
+		let e = await d(this.options.srcDir, [...k]);
+		e.push(b.resolve(this.options.srcDir, "..", "index.html"));
+		let t = b.resolve(this.options.outputFile);
+		for (let n of e) if (b.resolve(n) !== t) try {
+			let e = await y.readFile(n, "utf-8"), t = g(e);
+			if (t === e) continue;
+			await y.writeFile(n, t, "utf-8"), this.fileCache.invalidate(n), console.log(`  ✓ Kept plain asset urls in ${b.relative(process.cwd(), n)}`);
+		} catch (e) {
+			if (e.code === "ENOENT") continue;
+			console.warn(`Warning: Failed to clean asset tokens in ${n}:`, e);
+		}
+	}
+}, k = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".css",
+	".scss",
+	".sass",
+	".less",
+	".html",
+	".json"
+];
+function A(e = {}) {
+	return {
+		name: "vite-plugin-asset-constants",
+		apply: "build",
+		enforce: "pre",
+		async buildStart() {
+			if (!e.devMode) return;
+			let t = new O(e);
+			try {
+				await t.generateAssetsFile();
+				let e = t.getAssets();
+				t.needsRewrite() && (console.log(`📦 Found ${e.length} asset references:`), e.forEach((e) => {
+					console.log(`  ${e.constantName} = '${e.originalUri}' (${b.relative(process.cwd(), e.filePath)}:${e.line})`);
+				}), console.log("\n🔄 Replacing URIs with constants..."), await t.replaceAllUris(), console.log("✅ URI replacement completed!")), console.log("\n🧹 Checking for unused constants..."), await t.cleanupUnusedConstants(), await t.generateAssetsFile(), console.log("\n🔄 Upgrading assets.json imports to assets.ts..."), await t.upgradeJsonImportsToTs(), await t.stripUnresolvedTokens(), console.log("✅ Asset constants finalized!\n"), t.clearCache();
+			} catch (e) {
+				console.error("❌ Error in asset constants plugin:", e), e instanceof D && this.error(e.message);
+			}
+		},
+		transform(e, t) {
+			return t.includes("/node_modules/") || !e.includes("aippy-asset:") ? null : {
+				code: g(e),
+				map: null
+			};
+		},
+		transformIndexHtml(e) {
+			return g(e);
+		}
+	};
+}
+//#endregion
+export { A as assetConstantsPlugin, A as default };

package/dist/asset-constants/wrapper-keys.d.ts

@@ -1,5 +1,6 @@
 import * as t from '@babel/types';
 export declare function isDefaultImport(item: t.ImportDeclaration['specifiers'][number]): boolean;
+/** A string literal used as `assets['key']` on the wrapper's default import. */
 export declare function wrapperKeyGuard(ast: t.File, importSources: Set<string>): (p: any) => boolean;
 export declare function wrapperImportSources(filePath: string, srcDir: string, outputFile: string): Set<string>;
 export declare function withoutWrapperKeys(content: string, filePath: string, srcDir: string, outputFile: string): string;