@bamboocss/vite 1.35.1 → 1.35.3

package/dist/index.cjs

@@ -176,7 +176,8 @@ const replaceAssetReferences = (bundle, previous, next, sourcemap) => {
 * would therefore leave two different reachable subsets under one CDN key. The extra final
 * hash is not cosmetic: it makes late graph reachability cache-safe.
 */
-const optimizeStaticCssAssets = (bundle, session) => {
+const optimizeStaticCssAssets = (bundle, session, options = {}) => {
+	const { rename = true } = options;
 	for (const [bundleName, output] of Object.entries(bundle)) {
 		if (output.type !== "asset") continue;
 		const source = typeof output.source === "string" ? output.source : Buffer.from(output.source).toString();
@@ -184,6 +185,7 @@ const optimizeStaticCssAssets = (bundle, session) => {
 		const optimized = pruneStaticCss(source, session);
 		output.source = optimized;
 		if (optimized === source) continue;
+		if (!rename) continue;
 		const nextName = output.fileName.replace(/\.css$/, `.b-${(0, _bamboocss_shared.toHash)(optimized)}.css`);
 		if (nextName === output.fileName) continue;
 		if (bundle[nextName] && bundle[nextName] !== output) throw new Error(`bamboocss: final CSS asset name collision at ${JSON.stringify(nextName)}.`);
@@ -208,7 +210,7 @@ const optimizeStaticCssAssets = (bundle, session) => {
 * process just wrote, which is a race on any watch rebuild.
 */
 const bamboocssCss = (options) => {
-	const { configPath, cwd, session } = options;
+	const { configPath, cwd, session, renameCssAsset = true } = options;
 	const builder = new _bamboocss_node.Builder();
 	let server;
 	let command = "build";
@@ -292,7 +294,13 @@ const bamboocssCss = (options) => {
 		generateBundle: {
 			order: "post",
 			handler(_, bundle) {
-				optimizeStaticCssAssets(bundle, session);
+				const rolldown = Boolean(this.meta?.rolldownVersion);
+				optimizeStaticCssAssets(bundle, session, { rename: renameCssAsset && !rolldown });
+				if (!session.transformedFiles.size) return;
+				if (!Object.values(bundle).some((output) => {
+					if (output.type !== "asset") return false;
+					return (typeof output.source === "string" ? output.source : Buffer.from(output.source).toString()).includes("--made-with-bamboo");
+				})) throw new Error(`bamboocss: ${session.transformedFiles.size} module(s) were compiled to Bamboo class values, but no emitted asset carries the generated stylesheet. The build would ship unstyled.\n\nThis happens when another plugin, or the bundler itself, drops or replaces the CSS asset after it is emitted. If you are on Rolldown, report this — the rename that used to cause it is already disabled there. Otherwise look for a plugin running in \`generateBundle\` that rewrites CSS assets.`);
 			}
 		}
 	};
@@ -709,9 +717,10 @@ const propertyKey = (nameNode) => {
 * there is nothing to match — the host here is any import of the generated css module, which
 * a file defining a recipe necessarily has, since `cva` came from it.
 */
-const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGeneratedCssModule, isShadowed, newImportModule) => {
+const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGeneratedCssModule, isShadowed, newImportModule, helperModuleFromSubpath) => {
 	const sourceFile = call.getSourceFile();
 	let host;
+	let subpathModule;
 	for (const declaration of sourceFile.getImportDeclarations()) {
 		const mod = declaration.getModuleSpecifierValue();
 		if (declaration.isTypeOnly()) continue;
@@ -724,8 +733,10 @@ const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGenerated
 			}
 		}
 		if (!host && isGeneratedCssModule(mod) && declaration.getNamedImports().length > 0) host = declaration;
+		if (!subpathModule) subpathModule = helperModuleFromSubpath?.(mod);
 	}
-	if (!host && !newImportModule) return void 0;
+	const fallbackModule = newImportModule ?? subpathModule;
+	if (!host && !fallbackModule) return void 0;
 	if (declaredAtModuleScope(sourceFile).has(imported)) return void 0;
 	if (isShadowed(call, imported)) return void 0;
 	if (!host) {
@@ -736,7 +747,7 @@ const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGenerated
 			insert: {
 				pos: anchor.getEnd(),
 				names: [imported],
-				module: newImportModule
+				module: fallbackModule
 			}
 		};
 	}
@@ -1512,6 +1523,32 @@ const foldSource = (options) => {
 	const isBambooCssModule = (mod) => matchesModule(mod, cssModules);
 	const isGeneratedCssModule = (mod) => matchesModule(mod, [generatedCssModule]);
 	/**
+	* Where the compiler's helpers can be imported from, for a file that imports the generated
+	* css module by *subpath* rather than through its barrel.
+	*
+	* `styled-system/css/cva.js` is a real spelling, and it cannot host the helper: that module
+	* exports `cva`, not `cvaMap`. Matching only the barrel meant no host was found and every
+	* runtime recipe selection in the file declined — a failure whose reported reason said
+	* nothing about import spelling, and whose suggested remedies all pointed elsewhere.
+	*
+	* The sibling `cx` module is what actually exports them. The prefix is verified against the
+	* configured output before anything is derived, so an unrelated `foo/css/bar.js` is left
+	* alone, and the caller's extension is preserved rather than guessed at.
+	*/
+	const helperModuleFromSubpath = (mod) => {
+		const normalized = mod.replaceAll("\\", "/");
+		const at = normalized.lastIndexOf("/css/");
+		if (at < 0) return void 0;
+		const prefix = normalized.slice(0, at + 5 - 1);
+		if (!isGeneratedCssModule(prefix)) return void 0;
+		const rest = normalized.slice(at + 5);
+		if (!rest || rest.includes("/")) return void 0;
+		const dot = rest.lastIndexOf(".");
+		const extension = dot > 0 ? rest.slice(dot) : "";
+		if (rest === `cx${extension}`) return void 0;
+		return `${prefix}/cx${extension}`;
+	};
+	/**
 	* The generated css entry as spelled beside an imported config recipe.
 	*
 	* A decision table needs only `cvaMap`, but a module importing a config recipe often has
@@ -1822,7 +1859,7 @@ const foldSource = (options) => {
 					}
 					const lowered = lowerRecipeCall(call, entry, styleCompiler, isInertExpression, resolvedSelection, inlineSlot, maxRecipeStates);
 					if (lowered.kind === "dynamic-style") {
-						const helper = ensureRecipeHelperImport(RECIPE_MAP_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name));
+						const helper = ensureRecipeHelperImport(RECIPE_MAP_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name), helperModuleFromSubpath);
 						if (helper) {
 							candidates.push({
 								item,
@@ -1849,7 +1886,7 @@ const foldSource = (options) => {
 						continue;
 					}
 					if (lowered.kind === "slots") {
-						const helper = lowered.helper ? ensureRecipeHelperImport(lowered.helper, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name)) : void 0;
+						const helper = lowered.helper ? ensureRecipeHelperImport(lowered.helper, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name), helperModuleFromSubpath) : void 0;
 						if (!lowered.helper || helper) {
 							const replacement = lowered.helper && helper && helper.name !== lowered.helper ? lowered.expression.replaceAll(`${lowered.helper}(`, `${helper.name}(`) : lowered.expression;
 							candidates.push({
@@ -2302,7 +2339,7 @@ const foldSource = (options) => {
 		const end = call.getEnd();
 		if (code.slice(start, end) !== call.getText()) continue;
 		if (collides([[start, end]])) continue;
-		const helper = ensureRecipeHelperImport(SPLIT_PROPS_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(target.getText()));
+		const helper = ensureRecipeHelperImport(SPLIT_PROPS_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(target.getText()), helperModuleFromSubpath);
 		if (!helper) continue;
 		const keys = Object.keys(entry.config.variants ?? {});
 		magic.overwrite(start, end, `${helper.name}(${args[0].getText()}, ${JSON.stringify(keys)})`);
@@ -2348,11 +2385,17 @@ const foldSource = (options) => {
 			if (skipped.filter((item) => SURVIVES_TO_RUNTIME.has(item.reason) && item.end > item.start).some((item) => nameNode.findReferencesAsNodes().some((ref) => ref.getStart() >= item.start && ref.getStart() < item.end))) continue;
 			const survivor = nameNode.findReferencesAsNodes().find((ref) => !applied.some(([from, to]) => ref.getStart() >= from && ref.getStart() < to));
 			if (!survivor) continue;
+			const survivorFile = survivor.getSourceFile();
+			const foreign = survivorFile !== sourceFile;
 			skipped.push({
 				name: binding,
 				reason: "runtime-binding",
-				start: survivor.getStart(),
-				end: survivor.getEnd()
+				start: foreign ? nameNode.getStart() : survivor.getStart(),
+				end: foreign ? nameNode.getEnd() : survivor.getEnd(),
+				...foreign ? { origin: {
+					filePath: survivorFile.getFilePath(),
+					line: survivor.getStartLineNumber()
+				} } : {}
 			});
 		}
 		const bambooModules = [
@@ -2653,7 +2696,7 @@ const formatSkipped = (id, skipped) => {
 * with no matching rule.
 */
 const bamboocss = (options = {}) => {
-	const { configPath, cwd, reportSkipped = false, reportSummary = true, denseClassNames = true, maxRecipeStates } = options;
+	const { configPath, cwd, reportSkipped = false, reportSummary = true, denseClassNames = true, maxRecipeStates, renameCssAsset = true } = options;
 	if (maxRecipeStates !== void 0 && (!Number.isSafeInteger(maxRecipeStates) || maxRecipeStates < 1)) throw new Error("bamboocss: `maxRecipeStates` must be a positive safe integer.");
 	/** Totals across the build, for the summary. */
 	const totals = {
@@ -2689,7 +2732,7 @@ const bamboocss = (options = {}) => {
 			separator: "\n"
 		});
 		const threw = entries.some((entry) => entry.reason === "compile-failed");
-		return /* @__PURE__ */ new Error(`bamboocss: ${entries.length} call(s) could not be compiled.\n\n${detail}\n\n` + (threw ? "`compile-failed` is a module the compiler threw on — see the error logged for it above. Nothing was established about its calls either way.\n\n" : "") + "Bamboo emits no runtime styling fallback or recipe layer. Make the values finite and statically analyzable, move variation into declared recipe variants, or safelist intentional dynamic classes with `staticCss`.");
+		return /* @__PURE__ */ new Error(`bamboocss: ${entries.length} call(s) could not be compiled.\n\n${detail}\n\n` + (threw ? "`compile-failed` is a module the compiler threw on — see the error logged for it above. Nothing was established about its calls either way.\n\n" : "") + (entries.some((entry) => entry.reason === "runtime-binding") ? "`runtime-binding` is a Bamboo value read outside a call the compiler rewrote — most often an inline `cva`/`sva` imported by another module. Its declaration is erased where it is declared, so the import receives `undefined`; a recipe used in more than one file has to be a config recipe under `theme.extend.recipes`. The location given is the reference to change, not the declaration.\n\n" : "") + "Bamboo emits no runtime styling fallback or recipe layer. Make the values finite and statically analyzable, move variation into declared recipe variants, or safelist intentional dynamic classes with `staticCss`.\n\nSet `BAMBOO_DIAGNOSTIC_LIMIT=all` to list every finding rather than the first few.");
 	};
 	/**
 	* Recipe configs read out of modules other than the one being transformed.
@@ -2718,7 +2761,8 @@ const bamboocss = (options = {}) => {
 	return [bamboocssCss({
 		configPath,
 		cwd,
-		session: staticSession
+		session: staticSession,
+		renameCssAsset
 	}), {
 		name: "bamboocss:compiler",
 		enforce: "pre",
@@ -2815,7 +2859,12 @@ const bamboocss = (options = {}) => {
 			for (const entry of result.skipped) {
 				if (entry.reason === "not-imported" || entry.reason === "overlapping") continue;
 				if (entry.name === "cx" && entry.reason === "dynamic") continue;
-				addSurvivor({
+				addSurvivor(entry.origin ? {
+					file: entry.origin.filePath,
+					line: entry.origin.line,
+					name: entry.name,
+					reason: entry.reason
+				} : {
 					file: filePath,
 					line: lineAt(code, entry.start),
 					name: entry.name,
@@ -2835,7 +2884,7 @@ const bamboocss = (options = {}) => {
 		buildEnd() {
 			if (survivors.length) throw createSurvivorError(survivors);
 			if (typeof this.getModuleInfo === "function") {
-				if (!staticSession.cssLoaded) throw new Error(`bamboocss: compiled class values were produced, but ${JSON.stringify(VIRTUAL_CSS_ID)} was not imported. Import it once from the application entry so the compiled rules are emitted.`);
+				if (!staticSession.cssLoaded) throw new Error(`bamboocss: compiled class values were produced, but ${JSON.stringify(VIRTUAL_CSS_ID)} was not imported. Add \`import ${JSON.stringify(VIRTUAL_CSS_ID)}\` once, from a JavaScript or TypeScript module in the application entry graph.\n\nIt has to be a JS import. \`@import\` from a stylesheet does not reach it: the id names a virtual module resolved by this plugin, and Vite resolves CSS \`@import\` before plugin resolution, so it fails as an unresolvable path. A project that ships one preloaded stylesheet imports this from its entry module instead, and lets Vite emit the CSS asset.`);
 				const outsideExtraction = [...staticSession.transformedFiles].filter((file) => !staticSession.extractedFiles.has(file));
 				if (outsideExtraction.length) throw new Error(`bamboocss: ${outsideExtraction.length} statically compiled module(s) are outside the CSS extraction graph:\n\n${(0, _bamboocss_shared.truncateList)(outsideExtraction.map((file) => `  ${file}`), {
 					unit: "file",

package/dist/index.d.cts

@@ -45,6 +45,24 @@ interface BambooVitePluginOptions {
    * build time and memory for the exact compound-variant decision table. @default 65536
    */
   maxRecipeStates?: number;
+  /**
+   * Give the pruned stylesheet a final name derived from its own bytes.
+   *
+   * Rollup expands `[hash]` before `generateBundle`, so pruning after it can leave two
+   * different reachable subsets under one CDN key. Renaming closes that, at the cost of
+   * replacing an entry in the output bundle — which not every consumer of the bundle
+   * tolerates. Rolldown drops the asset outright (detected automatically, no flag needed),
+   * and a framework that relocates assets itself, such as react-router's SSR build, can
+   * lose track of the new name.
+   *
+   * Turning it off keeps the pruned bytes and Vite's own content hash. That hash is computed
+   * before pruning, so it stops describing the file exactly; in practice it still changes
+   * whenever the extracted CSS does, and only a change that alters *reachability alone*
+   * can now reuse a key. Prefer that over an asset your framework cannot find.
+   *
+   * @default true
+   */
+  renameCssAsset?: boolean;
 }
 /**
  * Vite integration for Bamboo CSS.

package/dist/index.d.mts

@@ -45,6 +45,24 @@ interface BambooVitePluginOptions {
    * build time and memory for the exact compound-variant decision table. @default 65536
    */
   maxRecipeStates?: number;
+  /**
+   * Give the pruned stylesheet a final name derived from its own bytes.
+   *
+   * Rollup expands `[hash]` before `generateBundle`, so pruning after it can leave two
+   * different reachable subsets under one CDN key. Renaming closes that, at the cost of
+   * replacing an entry in the output bundle — which not every consumer of the bundle
+   * tolerates. Rolldown drops the asset outright (detected automatically, no flag needed),
+   * and a framework that relocates assets itself, such as react-router's SSR build, can
+   * lose track of the new name.
+   *
+   * Turning it off keeps the pruned bytes and Vite's own content hash. That hash is computed
+   * before pruning, so it stops describing the file exactly; in practice it still changes
+   * whenever the extracted CSS does, and only a change that alters *reachability alone*
+   * can now reuse a key. Prefer that over an asset your framework cannot find.
+   *
+   * @default true
+   */
+  renameCssAsset?: boolean;
 }
 /**
  * Vite integration for Bamboo CSS.

package/dist/index.mjs

@@ -146,7 +146,8 @@ const replaceAssetReferences = (bundle, previous, next, sourcemap) => {
 * would therefore leave two different reachable subsets under one CDN key. The extra final
 * hash is not cosmetic: it makes late graph reachability cache-safe.
 */
-const optimizeStaticCssAssets = (bundle, session) => {
+const optimizeStaticCssAssets = (bundle, session, options = {}) => {
+	const { rename = true } = options;
 	for (const [bundleName, output] of Object.entries(bundle)) {
 		if (output.type !== "asset") continue;
 		const source = typeof output.source === "string" ? output.source : Buffer.from(output.source).toString();
@@ -154,6 +155,7 @@ const optimizeStaticCssAssets = (bundle, session) => {
 		const optimized = pruneStaticCss(source, session);
 		output.source = optimized;
 		if (optimized === source) continue;
+		if (!rename) continue;
 		const nextName = output.fileName.replace(/\.css$/, `.b-${toHash(optimized)}.css`);
 		if (nextName === output.fileName) continue;
 		if (bundle[nextName] && bundle[nextName] !== output) throw new Error(`bamboocss: final CSS asset name collision at ${JSON.stringify(nextName)}.`);
@@ -178,7 +180,7 @@ const optimizeStaticCssAssets = (bundle, session) => {
 * process just wrote, which is a race on any watch rebuild.
 */
 const bamboocssCss = (options) => {
-	const { configPath, cwd, session } = options;
+	const { configPath, cwd, session, renameCssAsset = true } = options;
 	const builder = new Builder();
 	let server;
 	let command = "build";
@@ -262,7 +264,13 @@ const bamboocssCss = (options) => {
 		generateBundle: {
 			order: "post",
 			handler(_, bundle) {
-				optimizeStaticCssAssets(bundle, session);
+				const rolldown = Boolean(this.meta?.rolldownVersion);
+				optimizeStaticCssAssets(bundle, session, { rename: renameCssAsset && !rolldown });
+				if (!session.transformedFiles.size) return;
+				if (!Object.values(bundle).some((output) => {
+					if (output.type !== "asset") return false;
+					return (typeof output.source === "string" ? output.source : Buffer.from(output.source).toString()).includes("--made-with-bamboo");
+				})) throw new Error(`bamboocss: ${session.transformedFiles.size} module(s) were compiled to Bamboo class values, but no emitted asset carries the generated stylesheet. The build would ship unstyled.\n\nThis happens when another plugin, or the bundler itself, drops or replaces the CSS asset after it is emitted. If you are on Rolldown, report this — the rename that used to cause it is already disabled there. Otherwise look for a plugin running in \`generateBundle\` that rewrites CSS assets.`);
 			}
 		}
 	};
@@ -679,9 +687,10 @@ const propertyKey = (nameNode) => {
 * there is nothing to match — the host here is any import of the generated css module, which
 * a file defining a recipe necessarily has, since `cva` came from it.
 */
-const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGeneratedCssModule, isShadowed, newImportModule) => {
+const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGeneratedCssModule, isShadowed, newImportModule, helperModuleFromSubpath) => {
 	const sourceFile = call.getSourceFile();
 	let host;
+	let subpathModule;
 	for (const declaration of sourceFile.getImportDeclarations()) {
 		const mod = declaration.getModuleSpecifierValue();
 		if (declaration.isTypeOnly()) continue;
@@ -694,8 +703,10 @@ const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGenerated
 			}
 		}
 		if (!host && isGeneratedCssModule(mod) && declaration.getNamedImports().length > 0) host = declaration;
+		if (!subpathModule) subpathModule = helperModuleFromSubpath?.(mod);
 	}
-	if (!host && !newImportModule) return void 0;
+	const fallbackModule = newImportModule ?? subpathModule;
+	if (!host && !fallbackModule) return void 0;
 	if (declaredAtModuleScope(sourceFile).has(imported)) return void 0;
 	if (isShadowed(call, imported)) return void 0;
 	if (!host) {
@@ -706,7 +717,7 @@ const ensureRecipeHelperImport = (imported, call, isBambooCssModule, isGenerated
 			insert: {
 				pos: anchor.getEnd(),
 				names: [imported],
-				module: newImportModule
+				module: fallbackModule
 			}
 		};
 	}
@@ -1482,6 +1493,32 @@ const foldSource = (options) => {
 	const isBambooCssModule = (mod) => matchesModule(mod, cssModules);
 	const isGeneratedCssModule = (mod) => matchesModule(mod, [generatedCssModule]);
 	/**
+	* Where the compiler's helpers can be imported from, for a file that imports the generated
+	* css module by *subpath* rather than through its barrel.
+	*
+	* `styled-system/css/cva.js` is a real spelling, and it cannot host the helper: that module
+	* exports `cva`, not `cvaMap`. Matching only the barrel meant no host was found and every
+	* runtime recipe selection in the file declined — a failure whose reported reason said
+	* nothing about import spelling, and whose suggested remedies all pointed elsewhere.
+	*
+	* The sibling `cx` module is what actually exports them. The prefix is verified against the
+	* configured output before anything is derived, so an unrelated `foo/css/bar.js` is left
+	* alone, and the caller's extension is preserved rather than guessed at.
+	*/
+	const helperModuleFromSubpath = (mod) => {
+		const normalized = mod.replaceAll("\\", "/");
+		const at = normalized.lastIndexOf("/css/");
+		if (at < 0) return void 0;
+		const prefix = normalized.slice(0, at + 5 - 1);
+		if (!isGeneratedCssModule(prefix)) return void 0;
+		const rest = normalized.slice(at + 5);
+		if (!rest || rest.includes("/")) return void 0;
+		const dot = rest.lastIndexOf(".");
+		const extension = dot > 0 ? rest.slice(dot) : "";
+		if (rest === `cx${extension}`) return void 0;
+		return `${prefix}/cx${extension}`;
+	};
+	/**
 	* The generated css entry as spelled beside an imported config recipe.
 	*
 	* A decision table needs only `cvaMap`, but a module importing a config recipe often has
@@ -1792,7 +1829,7 @@ const foldSource = (options) => {
 					}
 					const lowered = lowerRecipeCall(call, entry, styleCompiler, isInertExpression, resolvedSelection, inlineSlot, maxRecipeStates);
 					if (lowered.kind === "dynamic-style") {
-						const helper = ensureRecipeHelperImport(RECIPE_MAP_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name));
+						const helper = ensureRecipeHelperImport(RECIPE_MAP_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name), helperModuleFromSubpath);
 						if (helper) {
 							candidates.push({
 								item,
@@ -1819,7 +1856,7 @@ const foldSource = (options) => {
 						continue;
 					}
 					if (lowered.kind === "slots") {
-						const helper = lowered.helper ? ensureRecipeHelperImport(lowered.helper, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name)) : void 0;
+						const helper = lowered.helper ? ensureRecipeHelperImport(lowered.helper, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(name), helperModuleFromSubpath) : void 0;
 						if (!lowered.helper || helper) {
 							const replacement = lowered.helper && helper && helper.name !== lowered.helper ? lowered.expression.replaceAll(`${lowered.helper}(`, `${helper.name}(`) : lowered.expression;
 							candidates.push({
@@ -2272,7 +2309,7 @@ const foldSource = (options) => {
 		const end = call.getEnd();
 		if (code.slice(start, end) !== call.getText()) continue;
 		if (collides([[start, end]])) continue;
-		const helper = ensureRecipeHelperImport(SPLIT_PROPS_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(target.getText()));
+		const helper = ensureRecipeHelperImport(SPLIT_PROPS_HELPER, call, isBambooCssModule, isGeneratedCssModule, isShadowed, helperModules.get(target.getText()), helperModuleFromSubpath);
 		if (!helper) continue;
 		const keys = Object.keys(entry.config.variants ?? {});
 		magic.overwrite(start, end, `${helper.name}(${args[0].getText()}, ${JSON.stringify(keys)})`);
@@ -2318,11 +2355,17 @@ const foldSource = (options) => {
 			if (skipped.filter((item) => SURVIVES_TO_RUNTIME.has(item.reason) && item.end > item.start).some((item) => nameNode.findReferencesAsNodes().some((ref) => ref.getStart() >= item.start && ref.getStart() < item.end))) continue;
 			const survivor = nameNode.findReferencesAsNodes().find((ref) => !applied.some(([from, to]) => ref.getStart() >= from && ref.getStart() < to));
 			if (!survivor) continue;
+			const survivorFile = survivor.getSourceFile();
+			const foreign = survivorFile !== sourceFile;
 			skipped.push({
 				name: binding,
 				reason: "runtime-binding",
-				start: survivor.getStart(),
-				end: survivor.getEnd()
+				start: foreign ? nameNode.getStart() : survivor.getStart(),
+				end: foreign ? nameNode.getEnd() : survivor.getEnd(),
+				...foreign ? { origin: {
+					filePath: survivorFile.getFilePath(),
+					line: survivor.getStartLineNumber()
+				} } : {}
 			});
 		}
 		const bambooModules = [
@@ -2623,7 +2666,7 @@ const formatSkipped = (id, skipped) => {
 * with no matching rule.
 */
 const bamboocss = (options = {}) => {
-	const { configPath, cwd, reportSkipped = false, reportSummary = true, denseClassNames = true, maxRecipeStates } = options;
+	const { configPath, cwd, reportSkipped = false, reportSummary = true, denseClassNames = true, maxRecipeStates, renameCssAsset = true } = options;
 	if (maxRecipeStates !== void 0 && (!Number.isSafeInteger(maxRecipeStates) || maxRecipeStates < 1)) throw new Error("bamboocss: `maxRecipeStates` must be a positive safe integer.");
 	/** Totals across the build, for the summary. */
 	const totals = {
@@ -2659,7 +2702,7 @@ const bamboocss = (options = {}) => {
 			separator: "\n"
 		});
 		const threw = entries.some((entry) => entry.reason === "compile-failed");
-		return /* @__PURE__ */ new Error(`bamboocss: ${entries.length} call(s) could not be compiled.\n\n${detail}\n\n` + (threw ? "`compile-failed` is a module the compiler threw on — see the error logged for it above. Nothing was established about its calls either way.\n\n" : "") + "Bamboo emits no runtime styling fallback or recipe layer. Make the values finite and statically analyzable, move variation into declared recipe variants, or safelist intentional dynamic classes with `staticCss`.");
+		return /* @__PURE__ */ new Error(`bamboocss: ${entries.length} call(s) could not be compiled.\n\n${detail}\n\n` + (threw ? "`compile-failed` is a module the compiler threw on — see the error logged for it above. Nothing was established about its calls either way.\n\n" : "") + (entries.some((entry) => entry.reason === "runtime-binding") ? "`runtime-binding` is a Bamboo value read outside a call the compiler rewrote — most often an inline `cva`/`sva` imported by another module. Its declaration is erased where it is declared, so the import receives `undefined`; a recipe used in more than one file has to be a config recipe under `theme.extend.recipes`. The location given is the reference to change, not the declaration.\n\n" : "") + "Bamboo emits no runtime styling fallback or recipe layer. Make the values finite and statically analyzable, move variation into declared recipe variants, or safelist intentional dynamic classes with `staticCss`.\n\nSet `BAMBOO_DIAGNOSTIC_LIMIT=all` to list every finding rather than the first few.");
 	};
 	/**
 	* Recipe configs read out of modules other than the one being transformed.
@@ -2688,7 +2731,8 @@ const bamboocss = (options = {}) => {
 	return [bamboocssCss({
 		configPath,
 		cwd,
-		session: staticSession
+		session: staticSession,
+		renameCssAsset
 	}), {
 		name: "bamboocss:compiler",
 		enforce: "pre",
@@ -2785,7 +2829,12 @@ const bamboocss = (options = {}) => {
 			for (const entry of result.skipped) {
 				if (entry.reason === "not-imported" || entry.reason === "overlapping") continue;
 				if (entry.name === "cx" && entry.reason === "dynamic") continue;
-				addSurvivor({
+				addSurvivor(entry.origin ? {
+					file: entry.origin.filePath,
+					line: entry.origin.line,
+					name: entry.name,
+					reason: entry.reason
+				} : {
 					file: filePath,
 					line: lineAt(code, entry.start),
 					name: entry.name,
@@ -2805,7 +2854,7 @@ const bamboocss = (options = {}) => {
 		buildEnd() {
 			if (survivors.length) throw createSurvivorError(survivors);
 			if (typeof this.getModuleInfo === "function") {
-				if (!staticSession.cssLoaded) throw new Error(`bamboocss: compiled class values were produced, but ${JSON.stringify(VIRTUAL_CSS_ID)} was not imported. Import it once from the application entry so the compiled rules are emitted.`);
+				if (!staticSession.cssLoaded) throw new Error(`bamboocss: compiled class values were produced, but ${JSON.stringify(VIRTUAL_CSS_ID)} was not imported. Add \`import ${JSON.stringify(VIRTUAL_CSS_ID)}\` once, from a JavaScript or TypeScript module in the application entry graph.\n\nIt has to be a JS import. \`@import\` from a stylesheet does not reach it: the id names a virtual module resolved by this plugin, and Vite resolves CSS \`@import\` before plugin resolution, so it fails as an unresolvable path. A project that ships one preloaded stylesheet imports this from its entry module instead, and lets Vite emit the CSS asset.`);
 				const outsideExtraction = [...staticSession.transformedFiles].filter((file) => !staticSession.extractedFiles.has(file));
 				if (outsideExtraction.length) throw new Error(`bamboocss: ${outsideExtraction.length} statically compiled module(s) are outside the CSS extraction graph:\n\n${truncateList(outsideExtraction.map((file) => `  ${file}`), {
 					unit: "file",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/vite",
-  "version": "1.35.1",
+  "version": "1.35.3",
   "description": "Vite integration for Bamboo CSS",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -40,18 +40,18 @@
     "postcss": "8.5.26",
     "postcss-selector-parser": "7.1.5",
     "ts-morph": "28.0.0",
-    "@bamboocss/config": "1.35.1",
-    "@bamboocss/core": "1.35.1",
-    "@bamboocss/extractor": "1.35.1",
-    "@bamboocss/node": "1.35.1",
-    "@bamboocss/logger": "1.35.1",
-    "@bamboocss/shared": "1.35.1",
-    "@bamboocss/types": "1.35.1"
+    "@bamboocss/config": "1.35.3",
+    "@bamboocss/extractor": "1.35.3",
+    "@bamboocss/logger": "1.35.3",
+    "@bamboocss/node": "1.35.3",
+    "@bamboocss/core": "1.35.3",
+    "@bamboocss/shared": "1.35.3",
+    "@bamboocss/types": "1.35.3"
   },
   "devDependencies": {
     "@jridgewell/trace-mapping": "^0.3.31",
     "vite": "7.2.6",
-    "@bamboocss/fixture": "1.35.1"
+    "@bamboocss/fixture": "1.35.3"
   },
   "peerDependencies": {
     "vite": ">=5"