@bamboocss/generator 1.53.0 → 1.54.0

package/dist/index.cjs

@@ -2450,41 +2450,162 @@ const OS_DARK_QUERY = "@media (prefers-color-scheme: dark)";
 /** Compare a condition against a known query without tripping over spacing. */
 const normalize = (condition) => typeof condition === "string" ? condition.replace(/\s+/g, " ").trim() : void 0;
 /**
-* Does this value carry a comma at the top level?
+* Split a value on its top-level `separator`, ignoring one nested inside a function or a
+* string.
 *
-* `light-dark()` takes exactly two arguments, and CSS offers no way to group a
-* comma-separated value into one of them — there is no parenthesized form of a shadow list.
-* So a token whose light or dark arm is itself a list cannot be folded: the arms splat into
-* three or more arguments, the function is invalid, and the browser drops the whole
-* declaration. That failure is silent and total — a `--shadows-sm` carrying two shadows
-* emitted `light-dark(a, b, c)` and every element referencing it rendered with no shadow at
-* all, while the class naming it looked perfectly correct.
-*
-* Multi-part `box-shadow` is the shape that bites, since a realistic elevation token is
-* almost always two shadows; `transition` and `background` lists are the same story.
-*
-* Depth-aware, so `rgb(16, 19, 26)` still folds — its commas are the function's own.
-* Quote-aware, so a font stack's `"Foo, Bar"` is not mistaken for a separator.
+* Depth-aware, so `rgb(16, 19, 26)` is one part rather than three — its commas are the
+* function's own. Quote-aware, so a font stack's `"Foo, Bar"` is not mistaken for a
+* separator. Splitting on `' '` collapses runs of whitespace, which is what makes
+* `0  1px 2px red` and `0 1px 2px red` compare component for component.
 */
-const hasTopLevelComma = (value) => {
+function splitTopLevel(value, separator) {
+	const parts = [];
+	let current = "";
 	let depth = 0;
 	let quote;
+	const isSeparator = (char) => separator === "," ? char === "," : char === " " || char === "	" || char === "\n" || char === "\r";
 	for (let index = 0; index < value.length; index++) {
 		const char = value[index];
 		if (quote) {
-			if (char === "\\") index++;
-			else if (char === quote) quote = void 0;
+			current += char;
+			if (char === "\\") {
+				current += value[index + 1] ?? "";
+				index++;
+			} else if (char === quote) quote = void 0;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			current += char;
 			continue;
 		}
-		if (char === "\"" || char === "'") quote = char;
-		else if (char === "(") depth++;
+		if (char === "(") depth++;
 		else if (char === ")") depth--;
-		else if (char === "," && depth === 0) return true;
+		else if (depth === 0 && isSeparator(char)) {
+			if (separator === "," || current.trim()) parts.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
 	}
-	return false;
-};
+	if (separator === "," || current.trim()) parts.push(current.trim());
+	return parts;
+}
+/** Functions whose result is a `<color>`. */
+const COLOR_FUNCTIONS = new Set([
+	"color",
+	"color-mix",
+	"device-cmyk",
+	"hsl",
+	"hsla",
+	"hwb",
+	"lab",
+	"lch",
+	"light-dark",
+	"oklab",
+	"oklch",
+	"rgb",
+	"rgba"
+]);
+/** Keywords that are a `<color>`: the named set, the system set, and the two specials. */
+const COLOR_KEYWORDS = new Set(`transparent currentcolor
+   aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue
+   blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk
+   crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki
+   darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen
+   darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue
+   dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite
+   gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki
+   lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan
+   lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen
+   lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen
+   magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen
+   mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream
+   mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid
+   palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum
+   powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown
+   seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen
+   steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow
+   yellowgreen
+   accentcolor accentcolortext activetext buttonborder buttonface buttontext canvas canvastext
+   field fieldtext graytext highlight highlighttext linktext mark marktext selecteditem
+   selecteditemtext visitedtext`.trim().split(/\s+/));
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** One value, rather than a list or a space-separated shorthand. */
+const isSingleComponent = (value) => splitTopLevel(value, ",").length === 1 && splitTopLevel(value, " ").length === 1;
+/**
+* Is this single component provably a `<color>`?
+*
+* Provably, not plausibly. A false negative costs a fold; a false positive emits CSS the
+* browser drops on the floor without a word, which is the failure this whole file is written
+* around. So anything unrecognised is not a color.
+*
+* A `var()` is only a color when it names a token bamboo emitted from the `colors` category —
+* the reference itself says nothing about its type, and guessing wrong is exactly the
+* silent-drop case.
+*/
+function isColorValue(value, colorVars) {
+	if (value.startsWith("#")) return HEX_COLOR.test(value);
+	const open = value.indexOf("(");
+	if (open === -1) return COLOR_KEYWORDS.has(value.toLowerCase());
+	if (!value.endsWith(")")) return false;
+	const fn = value.slice(0, open).toLowerCase();
+	if (fn !== "var") return COLOR_FUNCTIONS.has(fn);
+	const [name] = splitTopLevel(value.slice(open + 1, -1), ",");
+	return name !== void 0 && colorVars.has(name);
+}
+/**
+* Merge a token's light and dark values into one, folding only the parts that differ.
+*
+* `light-dark()` is a `<color>` function — `light-dark() = light-dark(<color>, <color>)` in
+* CSS Color 5 — and that is the whole constraint here. It cannot carry a shadow, a border
+* shorthand or a length, and a browser handed one drops the declaration outright: verified in
+* Chrome, `--t: light-dark(0 1px 2px red, 0 1px 2px black)` computes `box-shadow: none`,
+* `light-dark(4px, 8px)` computes `padding-top: 0px`. Nothing warns. The token is still in the
+* sheet and the class naming it still looks correct.
+*
+* So a value is folded component by component rather than whole. `0 1px 2px red` against
+* `0 1px 2px black` differs in one place, that place is a color, and the result keeps the
+* geometry outside the function where it parses:
+*
+*     0 1px 2px light-dark(red, black)
+*
+* That is also what makes a list foldable, which folding whole never could: `light-dark()`
+* takes exactly two arguments and CSS offers no way to group a comma-separated value into one
+* of them, so a two-shadow token splatted into `light-dark(a, b, c)` and was dropped. Per-item
+* folding sidesteps the arity problem entirely, because the commas stay in the value where
+* they belong. A list of whole `light-dark()` calls does *not* work and was measured not to —
+* the arms have to be colors either way.
+*
+* Bails to `undefined` — keep the `@media` block, which expresses anything — whenever the two
+* arms do not line up part for part, or a differing part is not provably a color.
+*/
+function foldValue(light, dark, colorVars) {
+	const lightItems = splitTopLevel(light, ",");
+	const darkItems = splitTopLevel(dark, ",");
+	if (lightItems.length !== darkItems.length) return;
+	const items = [];
+	for (let index = 0; index < lightItems.length; index++) {
+		const lightParts = splitTopLevel(lightItems[index], " ");
+		const darkParts = splitTopLevel(darkItems[index], " ");
+		if (lightParts.length !== darkParts.length) return;
+		const merged = [];
+		for (let part = 0; part < lightParts.length; part++) {
+			const lightPart = lightParts[part];
+			const darkPart = darkParts[part];
+			if (lightPart === darkPart) {
+				merged.push(lightPart);
+				continue;
+			}
+			if (!isColorValue(lightPart, colorVars) || !isColorValue(darkPart, colorVars)) return;
+			merged.push(`light-dark(${lightPart}, ${darkPart})`);
+		}
+		items.push(merged.join(" "));
+	}
+	return items.join(", ");
+}
 /**
-* Collapse a token's `base`/`_osDark` pair into a single `light-dark()` declaration.
+* Collapse a token's `base`/`_osDark` pair into a single declaration.
 *
 * Two declarations and a whole `@media (prefers-color-scheme: dark)` block become one line,
 * which for a design system carrying a few hundred `_osDark` semantic tokens is the largest
@@ -2494,7 +2615,9 @@ const hasTopLevelComma = (value) => {
 * `[data-theme=dark]` selector is not, so the two are independent mechanisms that resolve
 * against each other by source order. `light-dark()` reads `color-scheme`, which is an
 * ordinary inherited property — so a toggle is `color-scheme: dark` on a subtree rather than
-* a second copy of every token.
+* a second copy of every token. That argument is why the fold has to reach past colors: a
+* sheet that folds its colors and leaves its shadows on the media query gives a subtree
+* toggle half a theme, with the shadows still following the OS.
 *
 * A var carrying `_osLight` as well is left alone. Folding it would put the light arm of
 * `light-dark()` and an `@media (prefers-color-scheme: light)` block in play for the same
@@ -2503,7 +2626,7 @@ const hasTopLevelComma = (value) => {
 *
 * `view.vars` is shared with the JS theme artifacts, so this copies rather than mutates.
 */
-function foldLightDark(vars, conditions) {
+function foldLightDark(vars, conditions, colorVars) {
 	const base = vars.get(BASE);
 	const osDark = vars.get(OS_DARK);
 	if (!base || !osDark) return {
@@ -2520,8 +2643,9 @@ function foldLightDark(vars, conditions) {
 	for (const [name, darkValue] of osDark) {
 		const lightValue = base.get(name);
 		if (lightValue === void 0 || osLight?.has(name)) continue;
-		if (hasTopLevelComma(lightValue) || hasTopLevelComma(darkValue)) continue;
-		nextBase.set(name, `light-dark(${lightValue}, ${darkValue})`);
+		const folded = colorVars.has(name) && isSingleComponent(lightValue) && isSingleComponent(darkValue) ? `light-dark(${lightValue}, ${darkValue})` : foldValue(lightValue, darkValue, colorVars);
+		if (folded === void 0) continue;
+		nextBase.set(name, folded);
 		nextDark.delete(name);
 	}
 	if (nextDark.size === osDark.size) return {
@@ -2537,12 +2661,18 @@ function foldLightDark(vars, conditions) {
 		folded: true
 	};
 }
+/** The custom properties bamboo emitted for `colors` tokens, by var name. */
+function getColorVars(tokens) {
+	const names = /* @__PURE__ */ new Set();
+	for (const token of tokens.view.categoryMap.get("colors")?.values() ?? []) names.add(token.extensions.var);
+	return names;
+}
 function generateTokenCss(ctx, sheet) {
 	const { config, conditions, tokens } = ctx;
 	const { cssVarRoot, staticCss } = config;
 	const root = cssVarRoot;
 	const results = [];
-	const { vars: tokenVars, folded } = foldLightDark(tokens.view.vars, conditions);
+	const { vars: tokenVars, folded } = foldLightDark(tokens.view.vars, conditions, getColorVars(tokens));
 	/**
 	* `light-dark()` returns the light value unless `color-scheme` names both, and a stylesheet
 	* that never sets it looks exactly like one where dark mode is broken. This rides with the
@@ -3943,14 +4073,32 @@ var Generator = class extends _bamboocss_core.Context {
 	getParserCss = (decoder) => {
 		return generateParserCss(this, decoder);
 	};
+	/**
+	* Each atom's first call site, by the class name the sheet writes it under.
+	*
+	* Only what the encoder recorded — see `StyleEncoder.recordOrigins` — so empty unless an
+	* integration asked for origins. Several hashes can decode to one class; the first wins.
+	*/
+	getAtomOrigins = () => {
+		const byHash = this.encoder.atomOrigins();
+		const origins = /* @__PURE__ */ new Map();
+		if (!byHash.size) return origins;
+		for (const atom of this.decoder.collect(this.encoder).atomic) {
+			const origin = byHash.get(atom.hash);
+			if (origin && !origins.has(atom.className)) origins.set(atom.className, origin);
+		}
+		return origins;
+	};
 	getCss = (stylesheet) => {
-		let css = (stylesheet ?? this.createSheet()).toCss({ minify: this.config.minify });
+		const sheet = stylesheet ?? this.createSheet();
+		let css = sheet.toCss({ minify: this.config.minify });
 		if (this.hooks["cssgen:done"]) css = this.hooks["cssgen:done"]({
 			artifact: "styles.css",
 			content: css
 		}) ?? css;
 		this.assertNoUnresolvedTokens();
 		this.reportRawValues();
+		this.reportInvalidDeclarations(sheet);
 		return css;
 	};
 	/**
@@ -4057,6 +4205,63 @@ var Generator = class extends _bamboocss_core.Context {
 		throw new _bamboocss_shared.BambooError("UNRESOLVED_TOKEN", `${found.size} style value(s) name a token that does not exist:\n\n${detail}\n\nEach is emitted as written, which parses — so the stylesheet is valid and nothing downstream objects. The browser drops the declaration at compute time and the style is simply absent from the element, which surfaces as "this never applied" a long way from the typo that caused it. Write \`[value]\` to mark one as a literal, or set \`unresolvedToken: 'warn'\` to report these without failing.`);
 	};
 	/**
+	* The findings `warn` has already printed, keyed `property:value`.
+	*
+	* A dev server emits the sheet on every edit, and extraction is additive within a watch, so
+	* a finding that warned on every rebuild would bury the edit that introduced the next one.
+	* Per process, like the sheet it describes.
+	*/
+	reportedInvalidDeclarations = /* @__PURE__ */ new Set();
+	/**
+	* Report every declaration in the sheet just emitted that its property's grammar rejects.
+	*
+	* The other side of `assertNoUnresolvedTokens`. That one reads the *values* the source asked
+	* for; this reads what the sheet *contains*, after every utility transform, mixin and recipe
+	* has had its say — which is the only place a transform that handed a value through
+	* unchanged, or a `[…]` literal that was never valid CSS, can be seen at all. Collected by
+	* `Stylesheet.toCss`, where the finished tree exists; graded here, where the sheet is
+	* emitted.
+	*
+	* A finding the unresolved-token pass owns is left to it, whatever that pass is set to, so
+	* one mistake is one report and `unresolvedToken: 'off'` means silence rather than the same
+	* value reported in this check's voice: `display: 'flexx'` is that pass's grammar half, and
+	* would otherwise be rejected again here as the declaration it became. Keyed on the
+	* property the utility *emits*, because that is how the sheet spells it.
+	*
+	* `warn` reports each distinct declaration once per process. `error` lists everything the
+	* sheet holds each time, because each time the build is failing on it.
+	*/
+	reportInvalidDeclarations = (sheet) => {
+		const severity = this.utility.invalidDeclaration;
+		if (severity === "off") return;
+		const owned = /* @__PURE__ */ new Set();
+		for (const ref of this.utility.unresolvedTokens.values()) owned.add(`${this.utility.cssPropertyOf(ref.prop)}:${ref.value}`);
+		const id = (finding) => `${finding.prop}:${finding.value}`;
+		const findings = sheet.invalidDeclarations.filter((finding) => !owned.has(id(finding)));
+		if (!findings.length) return;
+		const describe = ({ prop, value, selector, layer, count }) => {
+			return `- \`${prop}: ${value}\`${selector ? ` in \`${selector}\`` : ""}${layer ? `, \`@layer ${layer}\`` : ""}${count > 1 ? ` (${count} rules)` : ""}`;
+		};
+		const dropped = "Each parses, so the stylesheet is valid and nothing downstream objects. The browser drops the declaration at compute time and the style is simply absent from the element.";
+		if (severity === "error") {
+			const detail = (0, _bamboocss_shared.truncateList)(findings.map(describe), {
+				limit: 25,
+				unit: "declaration",
+				separator: "\n"
+			});
+			throw new _bamboocss_shared.BambooError("INVALID_DECLARATION", `${findings.length} declaration(s) in the stylesheet are not valid CSS for their property:\n\n${detail}\n\n${dropped} Fix the value, or set \`invalidDeclaration: 'warn'\` to report these without failing.`);
+		}
+		const fresh = findings.filter((finding) => !this.reportedInvalidDeclarations.has(id(finding)));
+		if (!fresh.length) return;
+		for (const finding of fresh) this.reportedInvalidDeclarations.add(id(finding));
+		const detail = (0, _bamboocss_shared.truncateList)(fresh.map(describe), {
+			limit: 25,
+			unit: "declaration",
+			separator: "\n"
+		});
+		_bamboocss_logger.logger.warn("sheet", `${fresh.length} declaration(s) in the stylesheet are not valid CSS for their property:\n\n${detail}\n\n${dropped} Set \`invalidDeclaration: 'error'\` to fail the build on these, or \`'off'\` to stop reporting them.`);
+	};
+	/**
 	* Get CSS for a specific layer from the stylesheet
 	*/
 	getLayerCss = (sheet, layer) => {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Context, StyleDecoder, Stylesheet } from "@bamboocss/core";
+import { AtomOrigin, Context, StyleDecoder, Stylesheet } from "@bamboocss/core";
 import { ArtifactId, CssArtifactType, LoadConfigResult, SpecFile, SpecType, SpecTypeMap } from "@bamboocss/types";
 
 //#region src/generator.d.ts
@@ -131,6 +131,13 @@ declare class Generator extends Context {
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;
+  /**
+   * Each atom's first call site, by the class name the sheet writes it under.
+   *
+   * Only what the encoder recorded — see `StyleEncoder.recordOrigins` — so empty unless an
+   * integration asked for origins. Several hashes can decode to one class; the first wins.
+   */
+  getAtomOrigins: () => Map<string, AtomOrigin>;
   getCss: (stylesheet?: Stylesheet) => string;
   /**
    * Fail on a style value shaped like a token path that names no token.
@@ -192,6 +199,34 @@ declare class Generator extends Context {
    */
   reportRawValues: () => void;
   assertNoUnresolvedTokens: () => void;
+  /**
+   * The findings `warn` has already printed, keyed `property:value`.
+   *
+   * A dev server emits the sheet on every edit, and extraction is additive within a watch, so
+   * a finding that warned on every rebuild would bury the edit that introduced the next one.
+   * Per process, like the sheet it describes.
+   */
+  private reportedInvalidDeclarations;
+  /**
+   * Report every declaration in the sheet just emitted that its property's grammar rejects.
+   *
+   * The other side of `assertNoUnresolvedTokens`. That one reads the *values* the source asked
+   * for; this reads what the sheet *contains*, after every utility transform, mixin and recipe
+   * has had its say — which is the only place a transform that handed a value through
+   * unchanged, or a `[…]` literal that was never valid CSS, can be seen at all. Collected by
+   * `Stylesheet.toCss`, where the finished tree exists; graded here, where the sheet is
+   * emitted.
+   *
+   * A finding the unresolved-token pass owns is left to it, whatever that pass is set to, so
+   * one mistake is one report and `unresolvedToken: 'off'` means silence rather than the same
+   * value reported in this check's voice: `display: 'flexx'` is that pass's grammar half, and
+   * would otherwise be rejected again here as the declaration it became. Keyed on the
+   * property the utility *emits*, because that is how the sheet spells it.
+   *
+   * `warn` reports each distinct declaration once per process. `error` lists everything the
+   * sheet holds each time, because each time the build is failing on it.
+   */
+  reportInvalidDeclarations: (sheet: Stylesheet) => void;
   /**
    * Get CSS for a specific layer from the stylesheet
    */

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Context, StyleDecoder, Stylesheet } from "@bamboocss/core";
+import { AtomOrigin, Context, StyleDecoder, Stylesheet } from "@bamboocss/core";
 import { ArtifactId, CssArtifactType, LoadConfigResult, SpecFile, SpecType, SpecTypeMap } from "@bamboocss/types";
 
 //#region src/generator.d.ts
@@ -131,6 +131,13 @@ declare class Generator extends Context {
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;
+  /**
+   * Each atom's first call site, by the class name the sheet writes it under.
+   *
+   * Only what the encoder recorded — see `StyleEncoder.recordOrigins` — so empty unless an
+   * integration asked for origins. Several hashes can decode to one class; the first wins.
+   */
+  getAtomOrigins: () => Map<string, AtomOrigin>;
   getCss: (stylesheet?: Stylesheet) => string;
   /**
    * Fail on a style value shaped like a token path that names no token.
@@ -192,6 +199,34 @@ declare class Generator extends Context {
    */
   reportRawValues: () => void;
   assertNoUnresolvedTokens: () => void;
+  /**
+   * The findings `warn` has already printed, keyed `property:value`.
+   *
+   * A dev server emits the sheet on every edit, and extraction is additive within a watch, so
+   * a finding that warned on every rebuild would bury the edit that introduced the next one.
+   * Per process, like the sheet it describes.
+   */
+  private reportedInvalidDeclarations;
+  /**
+   * Report every declaration in the sheet just emitted that its property's grammar rejects.
+   *
+   * The other side of `assertNoUnresolvedTokens`. That one reads the *values* the source asked
+   * for; this reads what the sheet *contains*, after every utility transform, mixin and recipe
+   * has had its say — which is the only place a transform that handed a value through
+   * unchanged, or a `[…]` literal that was never valid CSS, can be seen at all. Collected by
+   * `Stylesheet.toCss`, where the finished tree exists; graded here, where the sheet is
+   * emitted.
+   *
+   * A finding the unresolved-token pass owns is left to it, whatever that pass is set to, so
+   * one mistake is one report and `unresolvedToken: 'off'` means silence rather than the same
+   * value reported in this check's voice: `display: 'flexx'` is that pass's grammar half, and
+   * would otherwise be rejected again here as the declaration it became. Keyed on the
+   * property the utility *emits*, because that is how the sheet spells it.
+   *
+   * `warn` reports each distinct declaration once per process. `error` lists everything the
+   * sheet holds each time, because each time the build is failing on it.
+   */
+  reportInvalidDeclarations: (sheet: Stylesheet) => void;
   /**
    * Get CSS for a specific layer from the stylesheet
    */

package/dist/index.mjs

@@ -2424,41 +2424,162 @@ const OS_DARK_QUERY = "@media (prefers-color-scheme: dark)";
 /** Compare a condition against a known query without tripping over spacing. */
 const normalize = (condition) => typeof condition === "string" ? condition.replace(/\s+/g, " ").trim() : void 0;
 /**
-* Does this value carry a comma at the top level?
+* Split a value on its top-level `separator`, ignoring one nested inside a function or a
+* string.
 *
-* `light-dark()` takes exactly two arguments, and CSS offers no way to group a
-* comma-separated value into one of them — there is no parenthesized form of a shadow list.
-* So a token whose light or dark arm is itself a list cannot be folded: the arms splat into
-* three or more arguments, the function is invalid, and the browser drops the whole
-* declaration. That failure is silent and total — a `--shadows-sm` carrying two shadows
-* emitted `light-dark(a, b, c)` and every element referencing it rendered with no shadow at
-* all, while the class naming it looked perfectly correct.
-*
-* Multi-part `box-shadow` is the shape that bites, since a realistic elevation token is
-* almost always two shadows; `transition` and `background` lists are the same story.
-*
-* Depth-aware, so `rgb(16, 19, 26)` still folds — its commas are the function's own.
-* Quote-aware, so a font stack's `"Foo, Bar"` is not mistaken for a separator.
+* Depth-aware, so `rgb(16, 19, 26)` is one part rather than three — its commas are the
+* function's own. Quote-aware, so a font stack's `"Foo, Bar"` is not mistaken for a
+* separator. Splitting on `' '` collapses runs of whitespace, which is what makes
+* `0  1px 2px red` and `0 1px 2px red` compare component for component.
 */
-const hasTopLevelComma = (value) => {
+function splitTopLevel(value, separator) {
+	const parts = [];
+	let current = "";
 	let depth = 0;
 	let quote;
+	const isSeparator = (char) => separator === "," ? char === "," : char === " " || char === "	" || char === "\n" || char === "\r";
 	for (let index = 0; index < value.length; index++) {
 		const char = value[index];
 		if (quote) {
-			if (char === "\\") index++;
-			else if (char === quote) quote = void 0;
+			current += char;
+			if (char === "\\") {
+				current += value[index + 1] ?? "";
+				index++;
+			} else if (char === quote) quote = void 0;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			current += char;
 			continue;
 		}
-		if (char === "\"" || char === "'") quote = char;
-		else if (char === "(") depth++;
+		if (char === "(") depth++;
 		else if (char === ")") depth--;
-		else if (char === "," && depth === 0) return true;
+		else if (depth === 0 && isSeparator(char)) {
+			if (separator === "," || current.trim()) parts.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
 	}
-	return false;
-};
+	if (separator === "," || current.trim()) parts.push(current.trim());
+	return parts;
+}
+/** Functions whose result is a `<color>`. */
+const COLOR_FUNCTIONS = new Set([
+	"color",
+	"color-mix",
+	"device-cmyk",
+	"hsl",
+	"hsla",
+	"hwb",
+	"lab",
+	"lch",
+	"light-dark",
+	"oklab",
+	"oklch",
+	"rgb",
+	"rgba"
+]);
+/** Keywords that are a `<color>`: the named set, the system set, and the two specials. */
+const COLOR_KEYWORDS = new Set(`transparent currentcolor
+   aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue
+   blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk
+   crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki
+   darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen
+   darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue
+   dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite
+   gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki
+   lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan
+   lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen
+   lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen
+   magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen
+   mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream
+   mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid
+   palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum
+   powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown
+   seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen
+   steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow
+   yellowgreen
+   accentcolor accentcolortext activetext buttonborder buttonface buttontext canvas canvastext
+   field fieldtext graytext highlight highlighttext linktext mark marktext selecteditem
+   selecteditemtext visitedtext`.trim().split(/\s+/));
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** One value, rather than a list or a space-separated shorthand. */
+const isSingleComponent = (value) => splitTopLevel(value, ",").length === 1 && splitTopLevel(value, " ").length === 1;
+/**
+* Is this single component provably a `<color>`?
+*
+* Provably, not plausibly. A false negative costs a fold; a false positive emits CSS the
+* browser drops on the floor without a word, which is the failure this whole file is written
+* around. So anything unrecognised is not a color.
+*
+* A `var()` is only a color when it names a token bamboo emitted from the `colors` category —
+* the reference itself says nothing about its type, and guessing wrong is exactly the
+* silent-drop case.
+*/
+function isColorValue(value, colorVars) {
+	if (value.startsWith("#")) return HEX_COLOR.test(value);
+	const open = value.indexOf("(");
+	if (open === -1) return COLOR_KEYWORDS.has(value.toLowerCase());
+	if (!value.endsWith(")")) return false;
+	const fn = value.slice(0, open).toLowerCase();
+	if (fn !== "var") return COLOR_FUNCTIONS.has(fn);
+	const [name] = splitTopLevel(value.slice(open + 1, -1), ",");
+	return name !== void 0 && colorVars.has(name);
+}
+/**
+* Merge a token's light and dark values into one, folding only the parts that differ.
+*
+* `light-dark()` is a `<color>` function — `light-dark() = light-dark(<color>, <color>)` in
+* CSS Color 5 — and that is the whole constraint here. It cannot carry a shadow, a border
+* shorthand or a length, and a browser handed one drops the declaration outright: verified in
+* Chrome, `--t: light-dark(0 1px 2px red, 0 1px 2px black)` computes `box-shadow: none`,
+* `light-dark(4px, 8px)` computes `padding-top: 0px`. Nothing warns. The token is still in the
+* sheet and the class naming it still looks correct.
+*
+* So a value is folded component by component rather than whole. `0 1px 2px red` against
+* `0 1px 2px black` differs in one place, that place is a color, and the result keeps the
+* geometry outside the function where it parses:
+*
+*     0 1px 2px light-dark(red, black)
+*
+* That is also what makes a list foldable, which folding whole never could: `light-dark()`
+* takes exactly two arguments and CSS offers no way to group a comma-separated value into one
+* of them, so a two-shadow token splatted into `light-dark(a, b, c)` and was dropped. Per-item
+* folding sidesteps the arity problem entirely, because the commas stay in the value where
+* they belong. A list of whole `light-dark()` calls does *not* work and was measured not to —
+* the arms have to be colors either way.
+*
+* Bails to `undefined` — keep the `@media` block, which expresses anything — whenever the two
+* arms do not line up part for part, or a differing part is not provably a color.
+*/
+function foldValue(light, dark, colorVars) {
+	const lightItems = splitTopLevel(light, ",");
+	const darkItems = splitTopLevel(dark, ",");
+	if (lightItems.length !== darkItems.length) return;
+	const items = [];
+	for (let index = 0; index < lightItems.length; index++) {
+		const lightParts = splitTopLevel(lightItems[index], " ");
+		const darkParts = splitTopLevel(darkItems[index], " ");
+		if (lightParts.length !== darkParts.length) return;
+		const merged = [];
+		for (let part = 0; part < lightParts.length; part++) {
+			const lightPart = lightParts[part];
+			const darkPart = darkParts[part];
+			if (lightPart === darkPart) {
+				merged.push(lightPart);
+				continue;
+			}
+			if (!isColorValue(lightPart, colorVars) || !isColorValue(darkPart, colorVars)) return;
+			merged.push(`light-dark(${lightPart}, ${darkPart})`);
+		}
+		items.push(merged.join(" "));
+	}
+	return items.join(", ");
+}
 /**
-* Collapse a token's `base`/`_osDark` pair into a single `light-dark()` declaration.
+* Collapse a token's `base`/`_osDark` pair into a single declaration.
 *
 * Two declarations and a whole `@media (prefers-color-scheme: dark)` block become one line,
 * which for a design system carrying a few hundred `_osDark` semantic tokens is the largest
@@ -2468,7 +2589,9 @@ const hasTopLevelComma = (value) => {
 * `[data-theme=dark]` selector is not, so the two are independent mechanisms that resolve
 * against each other by source order. `light-dark()` reads `color-scheme`, which is an
 * ordinary inherited property — so a toggle is `color-scheme: dark` on a subtree rather than
-* a second copy of every token.
+* a second copy of every token. That argument is why the fold has to reach past colors: a
+* sheet that folds its colors and leaves its shadows on the media query gives a subtree
+* toggle half a theme, with the shadows still following the OS.
 *
 * A var carrying `_osLight` as well is left alone. Folding it would put the light arm of
 * `light-dark()` and an `@media (prefers-color-scheme: light)` block in play for the same
@@ -2477,7 +2600,7 @@ const hasTopLevelComma = (value) => {
 *
 * `view.vars` is shared with the JS theme artifacts, so this copies rather than mutates.
 */
-function foldLightDark(vars, conditions) {
+function foldLightDark(vars, conditions, colorVars) {
 	const base = vars.get(BASE);
 	const osDark = vars.get(OS_DARK);
 	if (!base || !osDark) return {
@@ -2494,8 +2617,9 @@ function foldLightDark(vars, conditions) {
 	for (const [name, darkValue] of osDark) {
 		const lightValue = base.get(name);
 		if (lightValue === void 0 || osLight?.has(name)) continue;
-		if (hasTopLevelComma(lightValue) || hasTopLevelComma(darkValue)) continue;
-		nextBase.set(name, `light-dark(${lightValue}, ${darkValue})`);
+		const folded = colorVars.has(name) && isSingleComponent(lightValue) && isSingleComponent(darkValue) ? `light-dark(${lightValue}, ${darkValue})` : foldValue(lightValue, darkValue, colorVars);
+		if (folded === void 0) continue;
+		nextBase.set(name, folded);
 		nextDark.delete(name);
 	}
 	if (nextDark.size === osDark.size) return {
@@ -2511,12 +2635,18 @@ function foldLightDark(vars, conditions) {
 		folded: true
 	};
 }
+/** The custom properties bamboo emitted for `colors` tokens, by var name. */
+function getColorVars(tokens) {
+	const names = /* @__PURE__ */ new Set();
+	for (const token of tokens.view.categoryMap.get("colors")?.values() ?? []) names.add(token.extensions.var);
+	return names;
+}
 function generateTokenCss(ctx, sheet) {
 	const { config, conditions, tokens } = ctx;
 	const { cssVarRoot, staticCss } = config;
 	const root = cssVarRoot;
 	const results = [];
-	const { vars: tokenVars, folded } = foldLightDark(tokens.view.vars, conditions);
+	const { vars: tokenVars, folded } = foldLightDark(tokens.view.vars, conditions, getColorVars(tokens));
 	/**
 	* `light-dark()` returns the light value unless `color-scheme` names both, and a stylesheet
 	* that never sets it looks exactly like one where dark mode is broken. This rides with the
@@ -3917,14 +4047,32 @@ var Generator = class extends Context {
 	getParserCss = (decoder) => {
 		return generateParserCss(this, decoder);
 	};
+	/**
+	* Each atom's first call site, by the class name the sheet writes it under.
+	*
+	* Only what the encoder recorded — see `StyleEncoder.recordOrigins` — so empty unless an
+	* integration asked for origins. Several hashes can decode to one class; the first wins.
+	*/
+	getAtomOrigins = () => {
+		const byHash = this.encoder.atomOrigins();
+		const origins = /* @__PURE__ */ new Map();
+		if (!byHash.size) return origins;
+		for (const atom of this.decoder.collect(this.encoder).atomic) {
+			const origin = byHash.get(atom.hash);
+			if (origin && !origins.has(atom.className)) origins.set(atom.className, origin);
+		}
+		return origins;
+	};
 	getCss = (stylesheet) => {
-		let css = (stylesheet ?? this.createSheet()).toCss({ minify: this.config.minify });
+		const sheet = stylesheet ?? this.createSheet();
+		let css = sheet.toCss({ minify: this.config.minify });
 		if (this.hooks["cssgen:done"]) css = this.hooks["cssgen:done"]({
 			artifact: "styles.css",
 			content: css
 		}) ?? css;
 		this.assertNoUnresolvedTokens();
 		this.reportRawValues();
+		this.reportInvalidDeclarations(sheet);
 		return css;
 	};
 	/**
@@ -4031,6 +4179,63 @@ var Generator = class extends Context {
 		throw new BambooError("UNRESOLVED_TOKEN", `${found.size} style value(s) name a token that does not exist:\n\n${detail}\n\nEach is emitted as written, which parses — so the stylesheet is valid and nothing downstream objects. The browser drops the declaration at compute time and the style is simply absent from the element, which surfaces as "this never applied" a long way from the typo that caused it. Write \`[value]\` to mark one as a literal, or set \`unresolvedToken: 'warn'\` to report these without failing.`);
 	};
 	/**
+	* The findings `warn` has already printed, keyed `property:value`.
+	*
+	* A dev server emits the sheet on every edit, and extraction is additive within a watch, so
+	* a finding that warned on every rebuild would bury the edit that introduced the next one.
+	* Per process, like the sheet it describes.
+	*/
+	reportedInvalidDeclarations = /* @__PURE__ */ new Set();
+	/**
+	* Report every declaration in the sheet just emitted that its property's grammar rejects.
+	*
+	* The other side of `assertNoUnresolvedTokens`. That one reads the *values* the source asked
+	* for; this reads what the sheet *contains*, after every utility transform, mixin and recipe
+	* has had its say — which is the only place a transform that handed a value through
+	* unchanged, or a `[…]` literal that was never valid CSS, can be seen at all. Collected by
+	* `Stylesheet.toCss`, where the finished tree exists; graded here, where the sheet is
+	* emitted.
+	*
+	* A finding the unresolved-token pass owns is left to it, whatever that pass is set to, so
+	* one mistake is one report and `unresolvedToken: 'off'` means silence rather than the same
+	* value reported in this check's voice: `display: 'flexx'` is that pass's grammar half, and
+	* would otherwise be rejected again here as the declaration it became. Keyed on the
+	* property the utility *emits*, because that is how the sheet spells it.
+	*
+	* `warn` reports each distinct declaration once per process. `error` lists everything the
+	* sheet holds each time, because each time the build is failing on it.
+	*/
+	reportInvalidDeclarations = (sheet) => {
+		const severity = this.utility.invalidDeclaration;
+		if (severity === "off") return;
+		const owned = /* @__PURE__ */ new Set();
+		for (const ref of this.utility.unresolvedTokens.values()) owned.add(`${this.utility.cssPropertyOf(ref.prop)}:${ref.value}`);
+		const id = (finding) => `${finding.prop}:${finding.value}`;
+		const findings = sheet.invalidDeclarations.filter((finding) => !owned.has(id(finding)));
+		if (!findings.length) return;
+		const describe = ({ prop, value, selector, layer, count }) => {
+			return `- \`${prop}: ${value}\`${selector ? ` in \`${selector}\`` : ""}${layer ? `, \`@layer ${layer}\`` : ""}${count > 1 ? ` (${count} rules)` : ""}`;
+		};
+		const dropped = "Each parses, so the stylesheet is valid and nothing downstream objects. The browser drops the declaration at compute time and the style is simply absent from the element.";
+		if (severity === "error") {
+			const detail = truncateList(findings.map(describe), {
+				limit: 25,
+				unit: "declaration",
+				separator: "\n"
+			});
+			throw new BambooError("INVALID_DECLARATION", `${findings.length} declaration(s) in the stylesheet are not valid CSS for their property:\n\n${detail}\n\n${dropped} Fix the value, or set \`invalidDeclaration: 'warn'\` to report these without failing.`);
+		}
+		const fresh = findings.filter((finding) => !this.reportedInvalidDeclarations.has(id(finding)));
+		if (!fresh.length) return;
+		for (const finding of fresh) this.reportedInvalidDeclarations.add(id(finding));
+		const detail = truncateList(fresh.map(describe), {
+			limit: 25,
+			unit: "declaration",
+			separator: "\n"
+		});
+		logger.warn("sheet", `${fresh.length} declaration(s) in the stylesheet are not valid CSS for their property:\n\n${detail}\n\n${dropped} Set \`invalidDeclaration: 'error'\` to fail the build on these, or \`'off'\` to stop reporting them.`);
+	};
+	/**
 	* Get CSS for a specific layer from the stylesheet
 	*/
 	getLayerCss = (sheet, layer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/generator",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "The css generator for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -38,12 +38,12 @@
     "pluralize": "8.0.0",
     "postcss": "8.5.26",
     "ts-pattern": "5.9.0",
-    "@bamboocss/core": "1.53.0",
-    "@bamboocss/is-valid-prop": "^1.53.0",
-    "@bamboocss/logger": "1.53.0",
-    "@bamboocss/shared": "1.53.0",
-    "@bamboocss/token-dictionary": "1.53.0",
-    "@bamboocss/types": "1.53.0"
+    "@bamboocss/core": "1.54.0",
+    "@bamboocss/is-valid-prop": "^1.54.0",
+    "@bamboocss/logger": "1.54.0",
+    "@bamboocss/shared": "1.54.0",
+    "@bamboocss/token-dictionary": "1.54.0",
+    "@bamboocss/types": "1.54.0"
   },
   "devDependencies": {
     "@types/pluralize": "0.0.33"