@bamboocss/vite 1.20.4 → 1.22.0

package/client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ambient declaration for the virtual stylesheet, so `import 'virtual:bamboo.css'`
+ * typechecks.
+ *
+ * Reference it once, next to the `vite/client` reference a vite project already has:
+ *
+ *     /// <reference types="@bamboocss/vite/client" />
+ *
+ * Shipped as a separate entry rather than folded into the package's own types, because a
+ * `declare module` in the main entry would apply to every consumer of the exported API —
+ * including builds that do not use the plugin.
+ */
+declare module 'virtual:bamboo.css' {}

package/dist/index.cjs

@@ -24,6 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+let _bamboocss_node = require("@bamboocss/node");
+let _bamboocss_logger = require("@bamboocss/logger");
 let _bamboocss_config_ts_path = require("@bamboocss/config/ts-path");
 let _bamboocss_extractor = require("@bamboocss/extractor");
 let magic_string = require("magic-string");
@@ -32,8 +34,90 @@ let ts_morph = require("ts-morph");
 let _bamboocss_core = require("@bamboocss/core");
 let _bamboocss_shared = require("@bamboocss/shared");
 let node_path = require("node:path");
-let _bamboocss_logger = require("@bamboocss/logger");
-let _bamboocss_node = require("@bamboocss/node");
+//#region src/css.ts
+/**
+* What a project imports to get the stylesheet.
+*
+* Spelled with a `.css` extension because that is how vite decides what a module is: the
+* id is all it has for a module with no file behind it, so `virtual:bamboo` would be
+* bundled as javascript and injected as a script.
+*/
+const VIRTUAL_CSS_ID = "virtual:bamboo.css";
+/**
+* Rollup's convention for a module with no file: a leading NUL tells every other plugin
+* not to try reading it off disk.
+*/
+const RESOLVED_ID = `\0${VIRTUAL_CSS_ID}`;
+/**
+* Serve bamboo's stylesheet as a virtual module, in dev and in build.
+*
+* This is the integration itself, not an optimisation: without it nothing emits css and
+* the generated `styled-system` runtime names classes no rule exists for.
+*
+* A virtual module rather than a file written to disk, because vite already owns the two
+* things a file would have to reimplement. In dev it injects css over the websocket and
+* replaces it in place, so an edit repaints without reloading; in build it hashes the
+* content into the asset graph and lets the bundler decide where it lands. Writing
+* `styles.css` and asking the project to import it means the build reads a file the same
+* process just wrote, which is a race on any watch rebuild.
+*/
+const bamboocssCss = (options = {}) => {
+	const { configPath, cwd } = options;
+	const builder = new _bamboocss_node.Builder();
+	let server;
+	/**
+	* Serialised, because both `load` and the watcher can reach it and `Builder` keeps one
+	* context. Two overlapping passes would extract into the same encoder and emit the
+	* stylesheet twice over.
+	*/
+	let pending;
+	const build = async () => {
+		await builder.setup({
+			configPath,
+			cwd
+		});
+		await builder.emit();
+		builder.extract();
+		return builder.toCss({ layerParams: true });
+	};
+	const generate = () => {
+		pending = Promise.resolve(pending).catch(() => void 0).then(build);
+		return pending;
+	};
+	return {
+		name: "bamboocss:css",
+		resolveId(id) {
+			if (id === "virtual:bamboo.css") return RESOLVED_ID;
+			return null;
+		},
+		async load(id) {
+			if (id !== RESOLVED_ID) return null;
+			const css = await generate();
+			if (this.addWatchFile) for (const file of builder.context?.getFiles() ?? []) this.addWatchFile(builder.context.runtime.path.abs(builder.context.config.cwd, file));
+			return css;
+		},
+		configureServer(devServer) {
+			server = devServer;
+			const invalidate = (file) => {
+				const ctx = builder.context;
+				if (!ctx) return;
+				if (!ctx.getFiles().some((f) => ctx.runtime.path.abs(ctx.config.cwd, f) === file)) return;
+				const mod = server?.moduleGraph.getModuleById(RESOLVED_ID);
+				if (!mod) return;
+				server?.moduleGraph.invalidateModule(mod);
+				server?.ws.send({
+					type: "update",
+					updates: []
+				});
+				_bamboocss_logger.logger.debug("vite", `styles invalidated by ${file}`);
+			};
+			devServer.watcher.on("change", invalidate);
+			devServer.watcher.on("add", invalidate);
+			devServer.watcher.on("unlink", invalidate);
+		}
+	};
+};
+//#endregion
 //#region src/fold-partial.ts
 /**
 * Statically resolvable means: every box in the tree carries a known value.
@@ -480,9 +564,6 @@ const planPartialFold = (argument, boxNode, styles, deps) => {
 	if (!partition) return void 0;
 	const className = deps.runtimeCss(partition.staticStyles);
 	if (!className && !partition.finite.length) return void 0;
-	if (deps.ctx.config.cssMode === "grouped") {
-		if ((className ? 1 : 0) + partition.finite.length + (partition.dynamicText.length ? 1 : 0) > 1) return void 0;
-	}
 	return {
 		className,
 		dynamicText: partition.dynamicText.length ? `{ ${partition.dynamicText.join(", ")} }` : void 0,
@@ -676,7 +757,6 @@ const ensureCxImport = (call, calleeRoot, isBambooCssModule, isGeneratedCssModul
 //#region src/runtime-css.ts
 /** The shape `createCss` and `createMergeCss` both take, derived from a resolved context. */
 const createCssContext = (ctx) => ({
-	grouped: ctx.config.cssMode === "grouped",
 	hash: Boolean(ctx.hash.className),
 	conditions: {
 		shift: ctx.conditions.shift,
@@ -1502,6 +1582,23 @@ const isGeneratedOutput = (filePath, ctx) => {
 	const file = slashed(filePath);
 	return file === root || file.startsWith(`${root}/`);
 };
+/**
+* The skip reasons that leave a `css()`-family call in the output.
+*
+* `overlapping` is handled by the enclosing fold, and `not-imported` is somebody else's
+* function of the same name — neither leaves a call of ours. `not-foldable` is a `cva`/`sva`
+* definition, which keeps the recipe runtime rather than the css engine; see `strict`.
+*/
+const SURVIVES_TO_RUNTIME = new Set([
+	"dynamic",
+	"raw-call",
+	"unsupported-kind",
+	"no-call-expression",
+	"empty",
+	"unresolved-token"
+]);
+/** 1-indexed line of a source offset, for an error a user can navigate to. */
+const lineAt = (code, offset) => code.slice(0, offset).split("\n").length;
 const formatSkipped = (id, skipped) => {
 	const counts = /* @__PURE__ */ new Map();
 	for (const entry of skipped) counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
@@ -1510,16 +1607,17 @@ const formatSkipped = (id, skipped) => {
 /**
 * Vite integration for Bamboo CSS.
 *
-* This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
-* job is the optional build-time fold.
+* Two plugins, because they do unrelated jobs on different schedules. The first emits the
+* stylesheet as a virtual module and runs in dev and build alike — that is the integration,
+* and nothing styles without it. The second is the optional build-time fold.
 *
-* It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+* The fold runs with `enforce: 'pre'` so it sees module source as close as possible to what
 * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
 * sees them would otherwise make the two disagree, and a folded class could end up
 * with no matching rule.
 */
 const bamboocss = (options = {}) => {
-	const { transform = false, partial, configPath, cwd, reportSkipped = false, reportSummary = true } = options;
+	const { transform = true, partial, configPath, cwd, reportSkipped = false, reportSummary = true, strict = false } = options;
 	/** Totals across the build, for the summary. */
 	const totals = {
 		folded: 0,
@@ -1527,6 +1625,8 @@ const bamboocss = (options = {}) => {
 		filesWithFolds: 0,
 		skipped: /* @__PURE__ */ new Map()
 	};
+	/** Under `strict`, every call that would still reach the runtime. */
+	const survivors = [];
 	let ctx;
 	let runtimeCss;
 	let setup;
@@ -1540,8 +1640,11 @@ const bamboocss = (options = {}) => {
 		});
 		await setup;
 	};
-	return {
-		name: "bamboocss",
+	return [bamboocssCss({
+		configPath,
+		cwd
+	}), {
+		name: "bamboocss:fold",
 		enforce: "pre",
 		apply: "build",
 		async buildStart() {
@@ -1550,6 +1653,7 @@ const bamboocss = (options = {}) => {
 			totals.files = 0;
 			totals.filesWithFolds = 0;
 			totals.skipped.clear();
+			survivors.length = 0;
 			await ensureContext();
 		},
 		/**
@@ -1611,6 +1715,23 @@ const bamboocss = (options = {}) => {
 			totals.folded += result.folded.length;
 			if (result.folded.length) totals.filesWithFolds++;
 			for (const entry of result.skipped) totals.skipped.set(entry.reason, (totals.skipped.get(entry.reason) ?? 0) + 1);
+			if (strict) {
+				for (const entry of result.skipped) {
+					if (!SURVIVES_TO_RUNTIME.has(entry.reason)) continue;
+					survivors.push({
+						file: filePath,
+						line: lineAt(code, entry.start),
+						name: entry.name,
+						reason: entry.reason
+					});
+				}
+				if (result.code.includes("cssLeaf(")) survivors.push({
+					file: filePath,
+					line: lineAt(result.code, result.code.indexOf("cssLeaf(")),
+					name: "cssLeaf",
+					reason: "lowered-leaf"
+				});
+			}
 			if (reportSkipped && result.skipped.length) _bamboocss_logger.logger.info("vite:transform", formatSkipped(filePath, result.skipped));
 			for (const dependency of result.dependencies) this.addWatchFile?.(dependency);
 			if (!result.folded.length) return null;
@@ -1621,6 +1742,16 @@ const bamboocss = (options = {}) => {
 			};
 		},
 		buildEnd() {
+			if (strict && survivors.length) {
+				const byFile = /* @__PURE__ */ new Map();
+				for (const entry of survivors) {
+					const list = byFile.get(entry.file) ?? [];
+					list.push(entry);
+					byFile.set(entry.file, list);
+				}
+				const detail = Array.from(byFile.entries()).map(([file, entries]) => [`  ${file}`, ...entries.map((e) => `    ${e.line}: ${e.name}() — ${e.reason}`)].join("\n")).join("\n");
+				throw new Error(`bamboocss: ${survivors.length} call(s) could not be folded, and \`strict\` is on.\n\n${detail}\n\nEach one keeps \`styled-system/css\` in the bundle, so the engine cannot be dropped however many other calls folded. Make the values static, move the variation into a \`cva\` variant, or generate them with \`staticCss\` — or set \`strict: false\` to accept the runtime.`);
+			}
 			if (!transform || !reportSummary) return;
 			const declined = Array.from(totals.skipped.values()).reduce((sum, count) => sum + count, 0);
 			const total = totals.folded + declined;
@@ -1629,10 +1760,12 @@ const bamboocss = (options = {}) => {
 			const reasons = Array.from(totals.skipped.entries()).sort((a, b) => b[1] - a[1]).map(([reason, count]) => `${reason}=${count}`).join(" ");
 			_bamboocss_logger.logger.info("vite:transform", `Folded ${totals.folded}/${total} (${share}%) across ${totals.filesWithFolds}/${totals.files} files` + (reasons ? ` — declined: ${reasons}` : ""));
 		}
-	};
+	}];
 };
 //#endregion
+exports.VIRTUAL_CSS_ID = VIRTUAL_CSS_ID;
 exports.bamboocss = bamboocss;
+exports.bamboocssCss = bamboocssCss;
 exports.createRuntimeCss = createRuntimeCss;
 exports.default = bamboocss;
 exports.foldSource = foldSource;

package/dist/index.d.cts

@@ -1,8 +1,36 @@
+import { Plugin } from "vite";
 import { Context } from "@bamboocss/core";
 import { Dict, ParserResultInterface } from "@bamboocss/types";
 import MagicString from "magic-string";
-import { Plugin } from "vite";
 
+//#region src/css.d.ts
+/**
+ * What a project imports to get the stylesheet.
+ *
+ * Spelled with a `.css` extension because that is how vite decides what a module is: the
+ * id is all it has for a module with no file behind it, so `virtual:bamboo` would be
+ * bundled as javascript and injected as a script.
+ */
+declare const VIRTUAL_CSS_ID = "virtual:bamboo.css";
+interface BambooCssPluginOptions {
+  configPath?: string;
+  cwd?: string;
+}
+/**
+ * Serve bamboo's stylesheet as a virtual module, in dev and in build.
+ *
+ * This is the integration itself, not an optimisation: without it nothing emits css and
+ * the generated `styled-system` runtime names classes no rule exists for.
+ *
+ * A virtual module rather than a file written to disk, because vite already owns the two
+ * things a file would have to reimplement. In dev it injects css over the websocket and
+ * replaces it in place, so an edit repaints without reloading; in build it hashes the
+ * content into the asset graph and lets the bundler decide where it lands. Writing
+ * `styles.css` and asking the project to import it means the build reads a file the same
+ * process just wrote, which is a race on any watch rebuild.
+ */
+declare const bamboocssCss: (options?: BambooCssPluginOptions) => Plugin;
+//#endregion
 //#region src/runtime-css.d.ts
 /**
  * The generated runtime's `css`, rebuilt in-process from a resolved context.
@@ -101,9 +129,18 @@ interface BambooVitePluginOptions {
    * Rewrite statically-resolvable `css()` and pattern calls into literal class
    * strings, so they cost nothing at runtime.
    *
-   * Off by default, and build-only — see the "Source transformation" guide for why.
+   * On by default, and build-only — it never runs in `vite dev`, where the parse would land
+   * on every hot update and a dev bundle gains nothing from pre-resolved calls.
    *
-   * @default false
+   * What it buys is per-call CPU, not bytes: the runtime still ships, because dropping it
+   * needs *every* call site in the graph to fold. Bundle size moves slightly against you —
+   * measured at -0.8% raw and +1.0% gzipped on `sandbox/runtime-perf`, since distinct class
+   * literals compress worse than the repeated `css({ … })` calls they replace. Set it to
+   * `false` if that trade is the wrong way round for you, or to keep builds faster: folding
+   * re-parses each module with `ts-morph`, roughly 0.3ms for a small component and 3ms for a
+   * 147-line file with 24 call sites.
+   *
+   * @default true
    */
   transform?: boolean;
   /**
@@ -135,18 +172,35 @@ interface BambooVitePluginOptions {
    * @default true
    */
   reportSummary?: boolean;
+  /**
+   * Fail the build when a `css()` or pattern call is left for the runtime.
+   *
+   * The fold's value is not the per-call CPU it saves — it is that a bundle where *every*
+   * such call folded no longer imports `styled-system/css` at all, and the engine behind it
+   * drops out. One survivor keeps the whole thing, so a coverage percentage cannot tell you
+   * whether you got the prize. This can.
+   *
+   * Deliberately silent about `cva`/`sva`. A `cva(...)` definition returns a function and can
+   * never collapse to a class string, so failing on it would make this unusable for anyone
+   * writing recipes — and recipes keep their own much smaller runtime by design. What this
+   * guarantees is narrower and checkable: nothing still calls `css()`.
+   *
+   * @default false
+   */
+  strict?: boolean;
 }
 /**
  * Vite integration for Bamboo CSS.
  *
- * This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
- * job is the optional build-time fold.
+ * Two plugins, because they do unrelated jobs on different schedules. The first emits the
+ * stylesheet as a virtual module and runs in dev and build alike — that is the integration,
+ * and nothing styles without it. The second is the optional build-time fold.
  *
- * It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+ * The fold runs with `enforce: 'pre'` so it sees module source as close as possible to what
  * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
  * sees them would otherwise make the two disagree, and a folded class could end up
  * with no matching rule.
  */
-declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin;
+declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin[];
 //#endregion
-export { type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, bamboocss, bamboocss as default, createRuntimeCss, foldSource };
+export { type BambooCssPluginOptions, type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, VIRTUAL_CSS_ID, bamboocss, bamboocss as default, bamboocssCss, createRuntimeCss, foldSource };

package/dist/index.d.mts

@@ -1,8 +1,36 @@
 import MagicString from "magic-string";
 import { Context } from "@bamboocss/core";
-import { Dict, ParserResultInterface } from "@bamboocss/types";
 import { Plugin } from "vite";
+import { Dict, ParserResultInterface } from "@bamboocss/types";
 
+//#region src/css.d.ts
+/**
+ * What a project imports to get the stylesheet.
+ *
+ * Spelled with a `.css` extension because that is how vite decides what a module is: the
+ * id is all it has for a module with no file behind it, so `virtual:bamboo` would be
+ * bundled as javascript and injected as a script.
+ */
+declare const VIRTUAL_CSS_ID = "virtual:bamboo.css";
+interface BambooCssPluginOptions {
+  configPath?: string;
+  cwd?: string;
+}
+/**
+ * Serve bamboo's stylesheet as a virtual module, in dev and in build.
+ *
+ * This is the integration itself, not an optimisation: without it nothing emits css and
+ * the generated `styled-system` runtime names classes no rule exists for.
+ *
+ * A virtual module rather than a file written to disk, because vite already owns the two
+ * things a file would have to reimplement. In dev it injects css over the websocket and
+ * replaces it in place, so an edit repaints without reloading; in build it hashes the
+ * content into the asset graph and lets the bundler decide where it lands. Writing
+ * `styles.css` and asking the project to import it means the build reads a file the same
+ * process just wrote, which is a race on any watch rebuild.
+ */
+declare const bamboocssCss: (options?: BambooCssPluginOptions) => Plugin;
+//#endregion
 //#region src/runtime-css.d.ts
 /**
  * The generated runtime's `css`, rebuilt in-process from a resolved context.
@@ -101,9 +129,18 @@ interface BambooVitePluginOptions {
    * Rewrite statically-resolvable `css()` and pattern calls into literal class
    * strings, so they cost nothing at runtime.
    *
-   * Off by default, and build-only — see the "Source transformation" guide for why.
+   * On by default, and build-only — it never runs in `vite dev`, where the parse would land
+   * on every hot update and a dev bundle gains nothing from pre-resolved calls.
    *
-   * @default false
+   * What it buys is per-call CPU, not bytes: the runtime still ships, because dropping it
+   * needs *every* call site in the graph to fold. Bundle size moves slightly against you —
+   * measured at -0.8% raw and +1.0% gzipped on `sandbox/runtime-perf`, since distinct class
+   * literals compress worse than the repeated `css({ … })` calls they replace. Set it to
+   * `false` if that trade is the wrong way round for you, or to keep builds faster: folding
+   * re-parses each module with `ts-morph`, roughly 0.3ms for a small component and 3ms for a
+   * 147-line file with 24 call sites.
+   *
+   * @default true
    */
   transform?: boolean;
   /**
@@ -135,18 +172,35 @@ interface BambooVitePluginOptions {
    * @default true
    */
   reportSummary?: boolean;
+  /**
+   * Fail the build when a `css()` or pattern call is left for the runtime.
+   *
+   * The fold's value is not the per-call CPU it saves — it is that a bundle where *every*
+   * such call folded no longer imports `styled-system/css` at all, and the engine behind it
+   * drops out. One survivor keeps the whole thing, so a coverage percentage cannot tell you
+   * whether you got the prize. This can.
+   *
+   * Deliberately silent about `cva`/`sva`. A `cva(...)` definition returns a function and can
+   * never collapse to a class string, so failing on it would make this unusable for anyone
+   * writing recipes — and recipes keep their own much smaller runtime by design. What this
+   * guarantees is narrower and checkable: nothing still calls `css()`.
+   *
+   * @default false
+   */
+  strict?: boolean;
 }
 /**
  * Vite integration for Bamboo CSS.
  *
- * This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
- * job is the optional build-time fold.
+ * Two plugins, because they do unrelated jobs on different schedules. The first emits the
+ * stylesheet as a virtual module and runs in dev and build alike — that is the integration,
+ * and nothing styles without it. The second is the optional build-time fold.
  *
- * It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+ * The fold runs with `enforce: 'pre'` so it sees module source as close as possible to what
  * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
  * sees them would otherwise make the two disagree, and a folded class could end up
  * with no matching rule.
  */
-declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin;
+declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin[];
 //#endregion
-export { type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, bamboocss, bamboocss as default, createRuntimeCss, foldSource };
+export { type BambooCssPluginOptions, type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, VIRTUAL_CSS_ID, bamboocss, bamboocss as default, bamboocssCss, createRuntimeCss, foldSource };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { Builder, loadConfigAndCreateContext } from "@bamboocss/node";
+import { logger } from "@bamboocss/logger";
 import { resolveTsPathPattern } from "@bamboocss/config/ts-path";
 import { box, maybeBoxNode, unbox } from "@bamboocss/extractor";
 import MagicString from "magic-string";
@@ -5,8 +7,90 @@ import { Node, SyntaxKind, VariableDeclarationKind } from "ts-morph";
 import { Recipes } from "@bamboocss/core";
 import { compact, createCssUncached, createMergeCss, getSlotCompoundVariant, memo, withoutSpace } from "@bamboocss/shared";
 import { resolve } from "node:path";
-import { logger } from "@bamboocss/logger";
-import { loadConfigAndCreateContext } from "@bamboocss/node";
+//#region src/css.ts
+/**
+* What a project imports to get the stylesheet.
+*
+* Spelled with a `.css` extension because that is how vite decides what a module is: the
+* id is all it has for a module with no file behind it, so `virtual:bamboo` would be
+* bundled as javascript and injected as a script.
+*/
+const VIRTUAL_CSS_ID = "virtual:bamboo.css";
+/**
+* Rollup's convention for a module with no file: a leading NUL tells every other plugin
+* not to try reading it off disk.
+*/
+const RESOLVED_ID = `\0${VIRTUAL_CSS_ID}`;
+/**
+* Serve bamboo's stylesheet as a virtual module, in dev and in build.
+*
+* This is the integration itself, not an optimisation: without it nothing emits css and
+* the generated `styled-system` runtime names classes no rule exists for.
+*
+* A virtual module rather than a file written to disk, because vite already owns the two
+* things a file would have to reimplement. In dev it injects css over the websocket and
+* replaces it in place, so an edit repaints without reloading; in build it hashes the
+* content into the asset graph and lets the bundler decide where it lands. Writing
+* `styles.css` and asking the project to import it means the build reads a file the same
+* process just wrote, which is a race on any watch rebuild.
+*/
+const bamboocssCss = (options = {}) => {
+	const { configPath, cwd } = options;
+	const builder = new Builder();
+	let server;
+	/**
+	* Serialised, because both `load` and the watcher can reach it and `Builder` keeps one
+	* context. Two overlapping passes would extract into the same encoder and emit the
+	* stylesheet twice over.
+	*/
+	let pending;
+	const build = async () => {
+		await builder.setup({
+			configPath,
+			cwd
+		});
+		await builder.emit();
+		builder.extract();
+		return builder.toCss({ layerParams: true });
+	};
+	const generate = () => {
+		pending = Promise.resolve(pending).catch(() => void 0).then(build);
+		return pending;
+	};
+	return {
+		name: "bamboocss:css",
+		resolveId(id) {
+			if (id === "virtual:bamboo.css") return RESOLVED_ID;
+			return null;
+		},
+		async load(id) {
+			if (id !== RESOLVED_ID) return null;
+			const css = await generate();
+			if (this.addWatchFile) for (const file of builder.context?.getFiles() ?? []) this.addWatchFile(builder.context.runtime.path.abs(builder.context.config.cwd, file));
+			return css;
+		},
+		configureServer(devServer) {
+			server = devServer;
+			const invalidate = (file) => {
+				const ctx = builder.context;
+				if (!ctx) return;
+				if (!ctx.getFiles().some((f) => ctx.runtime.path.abs(ctx.config.cwd, f) === file)) return;
+				const mod = server?.moduleGraph.getModuleById(RESOLVED_ID);
+				if (!mod) return;
+				server?.moduleGraph.invalidateModule(mod);
+				server?.ws.send({
+					type: "update",
+					updates: []
+				});
+				logger.debug("vite", `styles invalidated by ${file}`);
+			};
+			devServer.watcher.on("change", invalidate);
+			devServer.watcher.on("add", invalidate);
+			devServer.watcher.on("unlink", invalidate);
+		}
+	};
+};
+//#endregion
 //#region src/fold-partial.ts
 /**
 * Statically resolvable means: every box in the tree carries a known value.
@@ -453,9 +537,6 @@ const planPartialFold = (argument, boxNode, styles, deps) => {
 	if (!partition) return void 0;
 	const className = deps.runtimeCss(partition.staticStyles);
 	if (!className && !partition.finite.length) return void 0;
-	if (deps.ctx.config.cssMode === "grouped") {
-		if ((className ? 1 : 0) + partition.finite.length + (partition.dynamicText.length ? 1 : 0) > 1) return void 0;
-	}
 	return {
 		className,
 		dynamicText: partition.dynamicText.length ? `{ ${partition.dynamicText.join(", ")} }` : void 0,
@@ -649,7 +730,6 @@ const ensureCxImport = (call, calleeRoot, isBambooCssModule, isGeneratedCssModul
 //#region src/runtime-css.ts
 /** The shape `createCss` and `createMergeCss` both take, derived from a resolved context. */
 const createCssContext = (ctx) => ({
-	grouped: ctx.config.cssMode === "grouped",
 	hash: Boolean(ctx.hash.className),
 	conditions: {
 		shift: ctx.conditions.shift,
@@ -1475,6 +1555,23 @@ const isGeneratedOutput = (filePath, ctx) => {
 	const file = slashed(filePath);
 	return file === root || file.startsWith(`${root}/`);
 };
+/**
+* The skip reasons that leave a `css()`-family call in the output.
+*
+* `overlapping` is handled by the enclosing fold, and `not-imported` is somebody else's
+* function of the same name — neither leaves a call of ours. `not-foldable` is a `cva`/`sva`
+* definition, which keeps the recipe runtime rather than the css engine; see `strict`.
+*/
+const SURVIVES_TO_RUNTIME = new Set([
+	"dynamic",
+	"raw-call",
+	"unsupported-kind",
+	"no-call-expression",
+	"empty",
+	"unresolved-token"
+]);
+/** 1-indexed line of a source offset, for an error a user can navigate to. */
+const lineAt = (code, offset) => code.slice(0, offset).split("\n").length;
 const formatSkipped = (id, skipped) => {
 	const counts = /* @__PURE__ */ new Map();
 	for (const entry of skipped) counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
@@ -1483,16 +1580,17 @@ const formatSkipped = (id, skipped) => {
 /**
 * Vite integration for Bamboo CSS.
 *
-* This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
-* job is the optional build-time fold.
+* Two plugins, because they do unrelated jobs on different schedules. The first emits the
+* stylesheet as a virtual module and runs in dev and build alike — that is the integration,
+* and nothing styles without it. The second is the optional build-time fold.
 *
-* It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+* The fold runs with `enforce: 'pre'` so it sees module source as close as possible to what
 * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
 * sees them would otherwise make the two disagree, and a folded class could end up
 * with no matching rule.
 */
 const bamboocss = (options = {}) => {
-	const { transform = false, partial, configPath, cwd, reportSkipped = false, reportSummary = true } = options;
+	const { transform = true, partial, configPath, cwd, reportSkipped = false, reportSummary = true, strict = false } = options;
 	/** Totals across the build, for the summary. */
 	const totals = {
 		folded: 0,
@@ -1500,6 +1598,8 @@ const bamboocss = (options = {}) => {
 		filesWithFolds: 0,
 		skipped: /* @__PURE__ */ new Map()
 	};
+	/** Under `strict`, every call that would still reach the runtime. */
+	const survivors = [];
 	let ctx;
 	let runtimeCss;
 	let setup;
@@ -1513,8 +1613,11 @@ const bamboocss = (options = {}) => {
 		});
 		await setup;
 	};
-	return {
-		name: "bamboocss",
+	return [bamboocssCss({
+		configPath,
+		cwd
+	}), {
+		name: "bamboocss:fold",
 		enforce: "pre",
 		apply: "build",
 		async buildStart() {
@@ -1523,6 +1626,7 @@ const bamboocss = (options = {}) => {
 			totals.files = 0;
 			totals.filesWithFolds = 0;
 			totals.skipped.clear();
+			survivors.length = 0;
 			await ensureContext();
 		},
 		/**
@@ -1584,6 +1688,23 @@ const bamboocss = (options = {}) => {
 			totals.folded += result.folded.length;
 			if (result.folded.length) totals.filesWithFolds++;
 			for (const entry of result.skipped) totals.skipped.set(entry.reason, (totals.skipped.get(entry.reason) ?? 0) + 1);
+			if (strict) {
+				for (const entry of result.skipped) {
+					if (!SURVIVES_TO_RUNTIME.has(entry.reason)) continue;
+					survivors.push({
+						file: filePath,
+						line: lineAt(code, entry.start),
+						name: entry.name,
+						reason: entry.reason
+					});
+				}
+				if (result.code.includes("cssLeaf(")) survivors.push({
+					file: filePath,
+					line: lineAt(result.code, result.code.indexOf("cssLeaf(")),
+					name: "cssLeaf",
+					reason: "lowered-leaf"
+				});
+			}
 			if (reportSkipped && result.skipped.length) logger.info("vite:transform", formatSkipped(filePath, result.skipped));
 			for (const dependency of result.dependencies) this.addWatchFile?.(dependency);
 			if (!result.folded.length) return null;
@@ -1594,6 +1715,16 @@ const bamboocss = (options = {}) => {
 			};
 		},
 		buildEnd() {
+			if (strict && survivors.length) {
+				const byFile = /* @__PURE__ */ new Map();
+				for (const entry of survivors) {
+					const list = byFile.get(entry.file) ?? [];
+					list.push(entry);
+					byFile.set(entry.file, list);
+				}
+				const detail = Array.from(byFile.entries()).map(([file, entries]) => [`  ${file}`, ...entries.map((e) => `    ${e.line}: ${e.name}() — ${e.reason}`)].join("\n")).join("\n");
+				throw new Error(`bamboocss: ${survivors.length} call(s) could not be folded, and \`strict\` is on.\n\n${detail}\n\nEach one keeps \`styled-system/css\` in the bundle, so the engine cannot be dropped however many other calls folded. Make the values static, move the variation into a \`cva\` variant, or generate them with \`staticCss\` — or set \`strict: false\` to accept the runtime.`);
+			}
 			if (!transform || !reportSummary) return;
 			const declined = Array.from(totals.skipped.values()).reduce((sum, count) => sum + count, 0);
 			const total = totals.folded + declined;
@@ -1602,7 +1733,7 @@ const bamboocss = (options = {}) => {
 			const reasons = Array.from(totals.skipped.entries()).sort((a, b) => b[1] - a[1]).map(([reason, count]) => `${reason}=${count}`).join(" ");
 			logger.info("vite:transform", `Folded ${totals.folded}/${total} (${share}%) across ${totals.filesWithFolds}/${totals.files} files` + (reasons ? ` — declined: ${reasons}` : ""));
 		}
-	};
+	}];
 };
 //#endregion
-export { bamboocss, bamboocss as default, createRuntimeCss, foldSource };
+export { VIRTUAL_CSS_ID, bamboocss, bamboocss as default, bamboocssCss, createRuntimeCss, foldSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/vite",
-  "version": "1.20.4",
+  "version": "1.22.0",
   "description": "Vite integration for Bamboo CSS",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "directory": "packages/vite"
   },
   "files": [
+    "client.d.ts",
     "dist"
   ],
   "sideEffects": false,
@@ -27,7 +28,8 @@
         "default": "./dist/index.mjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./client": "./client.d.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -35,18 +37,18 @@
   "dependencies": {
     "magic-string": "0.30.21",
     "ts-morph": "28.0.0",
-    "@bamboocss/extractor": "1.20.4",
-    "@bamboocss/logger": "1.20.4",
-    "@bamboocss/core": "1.20.4",
-    "@bamboocss/config": "1.20.4",
-    "@bamboocss/node": "1.20.4",
-    "@bamboocss/shared": "1.20.4",
-    "@bamboocss/types": "1.20.4"
+    "@bamboocss/config": "1.22.0",
+    "@bamboocss/core": "1.22.0",
+    "@bamboocss/logger": "1.22.0",
+    "@bamboocss/extractor": "1.22.0",
+    "@bamboocss/node": "1.22.0",
+    "@bamboocss/shared": "1.22.0",
+    "@bamboocss/types": "1.22.0"
   },
   "devDependencies": {
     "@jridgewell/trace-mapping": "^0.3.31",
     "vite": "7.2.6",
-    "@bamboocss/fixture": "1.20.4"
+    "@bamboocss/fixture": "1.22.0"
   },
   "peerDependencies": {
     "vite": ">=5"