@lovrozagar/flare 0.8.0 → 0.9.1

package/README.md

@@ -766,6 +766,26 @@ import { styles, cn } from "@lovrozagar/flare/styles";
 
 `tw=` on `styles()` or as a JSX attribute is **dropped**. Put utilities in `class=`. `css=` compiles through the same plugin (not a `data-c` hash).
 
+### Which class strings compile
+
+Only string literals inside a `class=` expression get CSS: plain literals, arrays, ternary branches, the right side of `&&`, call arguments (`cn("a", on() && "b")`) and template literals. Literals elsewhere get none: module constants and lookups (`variants[props.v]`, so cva-style config objects), `class={(state) => "…"}` functions, and props not named `class`. Write variants as `&&` arms inside `cn(...)`.
+
+### Theme
+
+`sx.twCssPath` is the app's Tailwind entry stylesheet. Relative and package `@import`s resolve from the importing file, and `@plugin` loads relative or installed plugins.
+
+- **Merging follows the theme.** `cn` (and the compile-time static merge) uses tables compiled from that theme, so custom scale names merge: with `--radius-control`, `cn("rounded-control", "rounded-lg")` is `rounded-lg`, and a custom `--text-body` size no longer conflicts with a `text-muted` color. Without `twCssPath`, `cn` uses the default Tailwind tables. In dev, editing the theme rebuilds the CSS and the tables.
+- **Theme values are inlined by default** (`sx.themeVars: "inline"`): `.bg-canvas { background-color: light-dark(#f9f9fb, #18191b) }`. `"reference"` keeps `var(--background-color-canvas)` and ships the referenced theme vars in `@layer theme`, so a page can change them at runtime (a live theme editor).
+- **Tailwind's own stacks stay live.** Element-local `--tw-*` vars (shadow, ring, transform and filter stacks) are never inlined, and their `@property` rules ship, so `shadow-sm ring-1` composes on one element.
+
+### Strict classes
+
+`sx.strict` fails the module (a build error; the dev overlay in dev) when an app-layer class literal compiles to no CSS, for example a reset palette color or a typo. `{ allow: ["prose"] }` lets non-Tailwind class names through; `group` and `peer` markers always pass. `{ deny: [/^-?m[lr]-/] }` rejects utilities even when they compile. Library-layer modules (`/node_modules/`) are not checked.
+
+```ts
+flare({ sx: { tw: true, twCssPath: "./src/theme.css", strict: { allow: ["prose"], deny: [/^text-(left|right)$/] } } });
+```
+
 ## Fonts and images
 
 ```tsx
@@ -1088,6 +1108,9 @@ export default defineConfig({
 | `purge`                                | off                                         | Dead CSS / `data-testid` strip                               |
 | `serviceWorker`                        | off                                         | `sw.js`                                                      |
 | `sx.tw`                                | compile `class=` Tailwind                   |                                                              |
+| `sx.twCssPath`                         | `@import "tailwindcss"`                     | Theme entry stylesheet; `cn` merges with its scales          |
+| `sx.themeVars`                         | `"inline"`                                  | `"reference"` keeps theme `var()`s for runtime theming       |
+| `sx.strict`                            | off                                         | Unknown or denied class literals fail the build              |
 | `image.quality` / `widths` / `exclude` | image pipeline                              |                                                              |
 | `assetsBase`                           | `"/assets"`                                 | Must start with `/`, no trailing `/` (`"/"` = root-relative) |
 | `entry.client` / `entry.server`        | `src/client`, `src/server`                  |                                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",

package/src/plugins/cn-theme.ts

@@ -0,0 +1,36 @@
+import { compileToSource, compileToTables, mergeConfigs } from "../styles/cn-vendor/compiler.ts";
+import { getDefaultCnConfig } from "../styles/cn-vendor/default-config.generated.ts";
+import { createEngine, wrapClsx } from "../styles/cn-vendor/engine.ts";
+import { themeFromCss } from "../styles/cn-vendor/theme-css.ts";
+import { resolveStylesheetPath } from "./tw-compile.ts";
+
+export interface ThemeCn {
+	/** `cn` merging with the app theme's scales (custom radius, spacing, font size, shadow names). */
+	cn: (...inputs: Parameters<ReturnType<typeof wrapClsx>>) => string;
+	/** Same merge for one space-separated string — what the compile-time static merge runs. */
+	mergeString: (input: string) => string;
+	/** Every stylesheet read, so dev can rebuild when one changes. */
+	files: string[];
+	/** An ES module whose default export is the compiled tables, in the shape of `cn-vendor/tables.generated.ts`. */
+	source: string;
+}
+
+/**
+ * Compile `cn` merge tables from a Tailwind v4 entry stylesheet: the default tailwind-merge config
+ * extended (or overridden, for `--<ns>-*: initial`) by the `@theme` names it and its relative and
+ * package imports declare.
+ */
+export function createThemeCn(cssPath: string): ThemeCn {
+	const { extension, files } = themeFromCss([cssPath], (specifier, fromDir) =>
+		resolveStylesheetPath(specifier, fromDir),
+	);
+	const config = mergeConfigs(getDefaultCnConfig(), extension);
+	const { tables, validatorImpls, prefix } = compileToTables(config);
+	const engine = createEngine(tables, validatorImpls, { prefix });
+	return {
+		cn: wrapClsx(engine.mergeString, engine),
+		files,
+		mergeString: engine.mergeString,
+		source: compileToSource(config, { banner: `// GENERATED by @lovrozagar/flare from ${cssPath}. Do not edit.` }),
+	};
+}

package/src/plugins/sx-ast/index.ts

@@ -1,12 +1,37 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import type { Plugin } from "vite";
-import { extractDeclarations, extractPrefaceCss, initTailwindCompiler } from "../tw-compile.ts";
+import { join, resolve } from "node:path";
+import type { Plugin, ViteDevServer } from "vite";
+import { createThemeCn } from "../cn-theme.ts";
+import type { ThemeCn } from "../cn-theme.ts";
+import {
+	extractDeclarations,
+	extractPrefaceCss,
+	extractPropertyRules,
+	initTailwindCompiler,
+	themeVarsBlock,
+} from "../tw-compile.ts";
 import type { TailwindCompiler } from "../tw-compile.ts";
 import { rewriteModule } from "./rewrite.ts";
 
+export interface SxStrictOptions {
+	/** Tokens that may compile to no CSS (non-Tailwind classes such as `prose`). Markers (`group`, `peer`) are always allowed. */
+	allow?: string[];
+	/** Tokens rejected even when they compile (e.g. physical-direction utilities). */
+	deny?: RegExp[];
+}
+
 export interface SxAstOptions {
-	strict?: boolean;
+	/**
+	 * Fail the module (build error, dev overlay) when an app-layer class literal compiles to no CSS
+	 * or matches a `deny` pattern. Library-layer modules are not checked. Requires Tailwind (`tw`/`twCssPath`).
+	 */
+	strict?: boolean | SxStrictOptions;
+	/**
+	 * How utilities reference theme values. `"inline"` (default) resolves them to their values at
+	 * build time. `"reference"` keeps `var(--…)` and emits the referenced theme vars, so a page can
+	 * change the theme at runtime (live theme editors).
+	 */
+	themeVars?: "inline" | "reference";
 	/** Absolute path prefixes that map to the "sx" layer (lib code). Default: ["/node_modules/"]. */
 	libPaths?: string[];
 	/** Override layer detection per module id. Return null to fall back to libPaths heuristic. */
@@ -53,6 +78,10 @@ interface PluginState {
 	 * Emitted verbatim before atomic utility rules so browser defaults are normalized.
 	 */
 	twPrefaceCss: string;
+	/** `@property` rules for the Tailwind locals the emitted utilities use, by variable name. */
+	properties: Map<string, string>;
+	/** themeVars "reference": theme vars the emitted utilities reference. */
+	referencedVars: Set<string>;
 }
 
 interface LibManifestShape {
@@ -132,11 +161,25 @@ function resolveLayer(
 }
 
 /** Compose the final CSS text from the class pool, wrapped in @layer blocks. */
+/* Tailwind's fallback for browsers without @property: the same initial values, set directly. */
+const PROPERTIES_SUPPORTS =
+	"((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b))))";
+
+function propertiesFallback(properties: Map<string, string>): string {
+	const decls = [...properties].map(([name, rule]) => {
+		const initial = /initial-value:\s*([^;]+);/.exec(rule);
+		return `${name}: ${initial ? initial[1].trim() : "initial"};`;
+	});
+	return `@layer properties { @supports ${PROPERTIES_SUPPORTS} { *, ::before, ::after, ::backdrop { ${decls.join(" ")} } } }`;
+}
+
 function composeCss(
 	classPool: Map<string, string>,
 	layerByClass: Map<string, "sx" | "app">,
 	skip: Set<string>,
 	twPrefaceCss: string,
+	properties: Map<string, string> = new Map(),
+	themeBlock = "",
 ): string {
 	const sxRules: string[] = [];
 	const appRules: string[] = [];
@@ -159,19 +202,38 @@ function composeCss(
 	appRules.sort(atLast);
 
 	const parts: string[] = [];
+	/* First statement, so the fallback layer ranks below every other layer. */
+	if (properties.size > 0) parts.push("@layer properties;");
 	if (twPrefaceCss) parts.push(twPrefaceCss);
+	if (themeBlock) parts.push(themeBlock);
 	parts.push(LAYER_PRELUDE);
 	if (sxRules.length > 0) parts.push(`@layer sx { ${sxRules.join(" ")} }`);
 	if (appRules.length > 0) parts.push(`@layer app { ${appRules.join(" ")} }`);
+	if (properties.size > 0) {
+		parts.push(...properties.values());
+		parts.push(propertiesFallback(properties));
+	}
 
 	return parts.join("\n");
 }
 
+/* Flare's own `cn` tables module. With a twCssPath, the plugin serves tables compiled from that
+   theme in its place, so `cn` merges the app's custom scale names (`rounded-control`). */
+const CN_TABLES_RE = /[\\/]styles[\\/]cn-vendor[\\/]tables\.generated\.ts(?:\?.*)?$/;
+
+function lineOf(code: string, token: string): number {
+	const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const m = new RegExp(`(?<![\\w:/-])${escaped}(?![\\w-])`).exec(code);
+	return m ? code.slice(0, m.index).split("\n").length : 1;
+}
+
 const DEV_CSS_VIRTUAL_ID = "virtual:flare-sx-dev-css";
 const DEV_CSS_RESOLVED_ID = "\0virtual:flare-sx-dev-css";
 
 export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string = "/assets"): Plugin {
 	const libPaths = opts.libPaths ?? ["/node_modules/"];
+	const strict: SxStrictOptions | null = opts.strict ? (opts.strict === true ? {} : opts.strict) : null;
+	const strictAllow = new Set(strict?.allow ?? []);
 	/* On-disk dir mirrors URL prefix — emit must land where bundleHref points. */
 	const assetsDir = assetsBase === "" ? "assets" : assetsBase.slice(1);
 	const state: PluginState = {
@@ -181,10 +243,35 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 		providedByLibs: new Set(),
 		twCompiler: null,
 		twPrefaceCss: "",
+		properties: new Map(),
+		referencedVars: new Set(),
 	};
+	const referenceVars = opts.themeVars === "reference";
+	const themeBlockOf = (): string =>
+		referenceVars && state.twCompiler
+			? themeVarsBlock(state.referencedVars, state.twCompiler.themeVars, state.twPrefaceCss)
+			: "";
 
 	let mode: "dev" | "prod" = "dev";
 	let root = process.cwd();
+	let themeCn: ThemeCn | null = null;
+	let devServer: ViteDevServer | null = null;
+	const themeCnFor = (): ThemeCn | null => {
+		if (!opts.twCssPath) return null;
+		if (!themeCn) {
+			themeCn = createThemeCn(resolve(opts.twCssPath));
+			devServer?.watcher.add(themeCn.files);
+		}
+		return themeCn;
+	};
+	/* Throws on failure: a broken Tailwind entry fails the build (non-zero exit) instead of
+	   shipping class= tokens with no CSS behind them. */
+	const loadTw = async (): Promise<void> => {
+		const compiler = await initTailwindCompiler(opts.twCssPath);
+		/* Zero-class build captures theme vars + preflight (base layer) verbatim. */
+		state.twPrefaceCss = extractPrefaceCss(compiler.build([]));
+		state.twCompiler = compiler;
+	};
 
 	return {
 		async buildStart(this: { environment?: { config?: { root?: string } } }) {
@@ -192,16 +279,31 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 			if (opts.pruneFromLibManifests) {
 				state.providedByLibs = scanLibManifests(root);
 			}
-			if ((opts.tw || opts.twCssPath) && state.twCompiler === null) {
+			if ((opts.tw || opts.twCssPath) && state.twCompiler === null) await loadTw();
+		},
+
+		configureServer(server) {
+			devServer = server;
+			if (themeCn) server.watcher.add(themeCn.files);
+			/* A theme edit changes both the CSS every utility compiles to and the cn merge tables:
+			   drop both, forget emitted rules, and re-transform every module from scratch. */
+			server.watcher.on("change", async (file) => {
+				if (!themeCn?.files.includes(resolve(file))) return;
 				try {
-					state.twCompiler = await initTailwindCompiler(opts.twCssPath);
-					/* Zero-class build captures theme vars + preflight (base layer) verbatim. */
-					state.twPrefaceCss = extractPrefaceCss(state.twCompiler.build([]));
+					await loadTw();
 				} catch (e) {
-					/* Warn but don't fail the build — class= tokens pass through without CSS emit. */
-					console.warn(`[flare:sx-ast] Tailwind compiler init failed: ${e instanceof Error ? e.message : String(e)}`);
+					server.config.logger.error(`[flare:sx-ast] ${e instanceof Error ? e.message : String(e)}`);
+					return;
 				}
-			}
+				themeCn = null;
+				state.classPool.clear();
+				state.layerByClass.clear();
+				state.moduleManifest.clear();
+				state.properties.clear();
+				state.referencedVars.clear();
+				server.moduleGraph.invalidateAll();
+				server.ws.send({ type: "full-reload" });
+			});
 		},
 
 		configResolved(config) {
@@ -217,9 +319,20 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 		},
 
 		load(id: string): { code: string; moduleType: string } | null {
+			if (CN_TABLES_RE.test(id)) {
+				const theme = themeCnFor();
+				return theme ? { code: theme.source, moduleType: "js" } : null;
+			}
 			if (id !== DEV_CSS_RESOLVED_ID) return null;
 			/* Each import() re-runs load — no caching — so SSR always gets latest state. */
-			const css = composeCss(state.classPool, state.layerByClass, state.providedByLibs, state.twPrefaceCss);
+			const css = composeCss(
+				state.classPool,
+				state.layerByClass,
+				state.providedByLibs,
+				state.twPrefaceCss,
+				state.properties,
+				themeBlockOf(),
+			);
 			const classNames = [...state.classPool.keys()];
 			return {
 				code: `export function getDevSxCss() { return ${JSON.stringify(css)} }\nexport function getDevSxClasses() { return ${JSON.stringify(classNames)} }`,
@@ -229,7 +342,14 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 
 		generateBundle() {
 			const self = this as unknown as { emitFile: (f: { type: string; fileName: string; source: string }) => void };
-			const css = composeCss(state.classPool, state.layerByClass, state.providedByLibs, state.twPrefaceCss);
+			const css = composeCss(
+				state.classPool,
+				state.layerByClass,
+				state.providedByLibs,
+				state.twPrefaceCss,
+				state.properties,
+				themeBlockOf(),
+			);
 			self.emitFile({ fileName: `${assetsDir}/flare-global.css`, source: css, type: "asset" });
 
 			if (opts.manifest) {
@@ -276,6 +396,7 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 			const moduleRules: Array<{ cls: string; rule: string }> = [];
 
 			const tw = state.twCompiler;
+			const violations: string[] = [];
 			const result = rewriteModule(code, {
 				cssEmit: (rule) => {
 					/*
@@ -293,16 +414,38 @@ export function createSxAstPlugin(opts: SxAstOptions = {}, assetsBase: string =
 					moduleRules.push({ cls, rule });
 				},
 				layer,
+				mergeClassList: themeCnFor()?.mergeString,
+				onClassToken:
+					strict && layer === "app"
+						? (token, compiled) => {
+								if (!compiled && !strictAllow.has(token)) {
+									violations.push(`${id}:${lineOf(code, token)} "${token}" compiles to no CSS`);
+								}
+								const denied = strict.deny?.find((re) => re.test(token));
+								if (denied) violations.push(`${id}:${lineOf(code, token)} "${token}" matches deny ${denied}`);
+							}
+						: undefined,
 				mode,
 				sourcePath: id,
 				twCompile: tw
 					? (token: string) => {
 							const output = tw.build([token]);
-							return extractDeclarations(output, [token], tw.themeVars) || null;
+							for (const [name, rule] of extractPropertyRules(output)) state.properties.set(name, rule);
+							const decls = extractDeclarations(output, [token], referenceVars ? undefined : tw.themeVars);
+							if (referenceVars) {
+								for (const m of decls.matchAll(/var\((--[\w-]+)/g)) state.referencedVars.add(m[1]);
+							}
+							return decls || null;
 						}
 					: undefined,
 			});
 
+			if (violations.length > 0) {
+				throw new Error(
+					`[flare:sx-ast] sx.strict rejected ${violations.length} class token(s):\n  ${violations.join("\n  ")}`,
+				);
+			}
+
 			/* Track which classes this module emitted; layer already set in cssEmit above */
 			if (result !== null) {
 				for (const cls of result.emittedClasses) {

package/src/plugins/sx-ast/rewrite.ts

@@ -15,6 +15,13 @@ export interface RewriteCtx {
 	 * null for unknown tokens. Omit to disable Tailwind compilation entirely.
 	 */
 	twCompile?: (token: string) => string | null;
+	/**
+	 * Compile-time merge for a static class string. Defaults to the built-in tables; the sx plugin
+	 * passes the app theme's merge so custom scale names (`rounded-control`) collapse correctly.
+	 */
+	mergeClassList?: (input: string) => string;
+	/** Called for every literal class token compiled through Tailwind (markers excluded); `compiled` is false when it produced no CSS. */
+	onClassToken?: (token: string, compiled: boolean) => void;
 }
 
 export interface RewriteResult {
@@ -183,6 +190,7 @@ function compileTwFromExpr(expr: unknown, ctx: RewriteCtx): void {
 		for (const token of raw.split(/\s+/).filter(Boolean)) {
 			if (MARKER_TOKEN_RE.test(token)) continue;
 			const body = ctx.twCompile(token);
+			ctx.onClassToken?.(token, Boolean(body));
 			if (!body) continue;
 			ctx.cssEmit(buildTwRule(token, body));
 		}
@@ -197,6 +205,7 @@ function compileTwFromString(value: string, ctx: RewriteCtx): void {
 	for (const token of value.split(/\s+/).filter(Boolean)) {
 		if (MARKER_TOKEN_RE.test(token)) continue;
 		const body = ctx.twCompile(token);
+		ctx.onClassToken?.(token, Boolean(body));
 		if (!body) continue;
 		ctx.cssEmit(buildTwRule(token, body));
 	}
@@ -488,7 +497,7 @@ export function rewriteModule(source: string, ctx: RewriteCtx): RewriteResult |
 		if (classAttr) {
 			const resolved = resolveClassAttr(source, classAttr);
 			if (resolved.kind === "literal") {
-				const merged = mergeClassList(resolved.value);
+				const merged = (ctx.mergeClassList ?? mergeClassList)(resolved.value);
 				classLiteral = merged;
 				if (resolved.rewrite || merged !== resolved.value) classNeedsRewrite = true;
 				if (resolved.rewrite) foldedStaticCn = true;
@@ -707,7 +716,7 @@ export function rewriteModule(source: string, ctx: RewriteCtx): RewriteResult |
 		} else if (classAttr) {
 			const existing = resolveClassAttr(source, classAttr);
 			if (existing.kind === "literal") {
-				const merged = mergeClassList(existing.value);
+				const merged = (ctx.mergeClassList ?? mergeClassList)(existing.value);
 				if (merged) {
 					replace(classAttr.start, classAttr.end, `class={cn("${merged}", ${compileCssCall})}`);
 					neededImports.add("cn");

package/src/plugins/tw-compile.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 export interface TailwindCompiler {
 	build: (classes: string[]) => string;
@@ -36,18 +37,18 @@ function cssEscapeClass(cls: string): string {
 	return cls.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
 }
 
-function selectorMatchesAny(selector: string, prefixes: Set<string>): boolean {
+/**
+ * What follows a requested utility's own class in `selector`: "" for the bare class, the variant
+ * suffix (`[aria-pressed="true"]`, `:focus-visible:disabled`, `:where(...)`, ` .child`) otherwise,
+ * or null when the selector is not that utility (`.p-40` is not `.p-4`).
+ */
+function suffixAfterUtility(selector: string, prefixes: Set<string>): string | null {
 	for (const prefix of prefixes) {
-		if (
-			selector === prefix ||
-			selector.startsWith(`${prefix}:`) ||
-			selector.startsWith(`${prefix} `) ||
-			selector.startsWith(`${prefix},`)
-		) {
-			return true;
-		}
+		if (!selector.startsWith(prefix)) continue;
+		const suffix = selector.slice(prefix.length);
+		if (suffix === "" || /^[:[ ,]/.test(suffix)) return suffix;
 	}
-	return false;
+	return null;
 }
 
 function extractLayerContent(css: string, atStart: number): string {
@@ -107,13 +108,15 @@ function extractDeclsInner(css: string, selectorSet?: Set<string>): string {
 			}
 		}
 		const body = remaining.slice(braceStart + 1, i).trim();
-		const matchesFilter = !selectorSet || selectorMatchesAny(selector, selectorSet);
-		if (matchesFilter && body.length > 0) {
-			const pseudo = extractPseudo(selector);
-			if (pseudo) {
-				result.push(`&${pseudo} { ${body} }`);
+		if (body.length > 0) {
+			if (selectorSet) {
+				/* Keep the whole variant suffix: flattened attribute variants and chained pseudos. */
+				const suffix = suffixAfterUtility(selector, selectorSet);
+				if (suffix === "" || suffix?.startsWith(",")) result.push(body);
+				else if (suffix !== null) result.push(`&${suffix} { ${body} }`);
 			} else {
-				result.push(body);
+				const pseudo = extractPseudo(selector);
+				result.push(pseudo ? `&${pseudo} { ${body} }` : body);
 			}
 		}
 		remaining = remaining.slice(i + 1).trim();
@@ -121,11 +124,56 @@ function extractDeclsInner(css: string, selectorSet?: Set<string>): string {
 	return result.join(";");
 }
 
+/** Tailwind's element-local stacks (`--tw-shadow`, `--tw-scale-x`, …): never theme values. */
+function isLocalVar(name: string): boolean {
+	return name.startsWith("--tw-");
+}
+
+/**
+ * The `@property` rules in a build output, keyed by variable name, whitespace-normalized
+ * (`@property --tw-shadow { syntax: "*"; inherits: false; initial-value: 0 0 #0000; }`).
+ * Utilities reference these locals with `var()`; without the registration (and its initial
+ * value) a stack like `box-shadow: var(--tw-inset-shadow), …, var(--tw-shadow)` is invalid.
+ */
+export function extractPropertyRules(cssOutput: string): Map<string, string> {
+	const rules = new Map<string, string>();
+	for (const m of cssOutput.matchAll(/@property\s+(--[\w-]+)\s*\{([^}]*)\}/g)) {
+		const decls = m[2]
+			.split(";")
+			.map((d) => d.trim().replace(/\s+/g, " "))
+			.filter(Boolean);
+		rules.set(m[1], `@property ${m[1]} { ${decls.map((d) => `${d};`).join(" ")} }`);
+	}
+	return rules;
+}
+
+/**
+ * `@layer theme { :root, :host { … } }` defining the theme vars `referenced` needs: each one and,
+ * transitively, the vars its value references. Locals (`--tw-*`), vars the preface already defines,
+ * and names Tailwind never emitted are skipped. Empty string when nothing is needed.
+ */
+export function themeVarsBlock(referenced: Set<string>, themeVars: Map<string, string>, preface: string): string {
+	const decls: string[] = [];
+	const seen = new Set<string>();
+	const queue = [...referenced];
+	while (queue.length > 0) {
+		const name = queue.shift() as string;
+		if (seen.has(name) || isLocalVar(name)) continue;
+		seen.add(name);
+		if (new RegExp(`${name.replace(/[-]/g, "\\-")}\\s*:`).test(preface)) continue;
+		const value = themeVars.get(name);
+		if (value === undefined) continue;
+		decls.push(`${name}: ${value};`);
+		for (const m of value.matchAll(/var\((--[\w-]+)/g)) queue.push(m[1]);
+	}
+	return decls.length > 0 ? `@layer theme { :root, :host { ${decls.join(" ")} } }` : "";
+}
+
 function resolveThemeVars(css: string, themeVars: Map<string, string>): string {
 	let result = css;
 	for (let i = 0; i < 5; i++) {
 		const next = result.replace(/var\((--[\w-]+)\)/g, (full, name: string) => {
-			return themeVars.get(name) ?? full;
+			return isLocalVar(name) ? full : (themeVars.get(name) ?? full);
 		});
 		if (next === result) break;
 		result = next;
@@ -179,8 +227,80 @@ export function extractDeclarations(
 
 const TAILWIND_MODULE: string = "tailwindcss";
 
-/** Initialize a Tailwind v4 compiler from an optional CSS entry file. */
+/** `@scope/name/sub/path` → `["@scope/name", "sub/path"]`; `name` → `["name", ""]`. */
+function splitBareSpecifier(id: string): [string, string] {
+	const parts = id.split("/");
+	const nameParts = id.startsWith("@") ? 2 : 1;
+	return [parts.slice(0, nameParts).join("/"), parts.slice(nameParts).join("/")];
+}
+
+/**
+ * A bare CSS specifier from `fromDir`: a package root resolves to its `style` entry
+ * (`exports["."].style`, then `style`); a subpath goes through the package's exports.
+ */
+function resolveBareStylesheet(id: string, fromDir: string): string {
+	const req = createRequire(join(fromDir, "noop.css"));
+	const [name, subpath] = splitBareSpecifier(id);
+	if (subpath) return req.resolve(id);
+	const pkgPath = req.resolve(`${name}/package.json`);
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+		exports?: Record<string, { style?: string } | string> | string;
+		style?: string;
+	};
+	const rootExport = typeof pkg.exports === "object" ? pkg.exports["."] : undefined;
+	const style = (typeof rootExport === "object" ? rootExport.style : undefined) ?? pkg.style;
+	if (!style) throw new Error(`package "${name}" has no "style" entry to import as CSS`);
+	return join(dirname(pkgPath), style);
+}
+
+/**
+ * Where an `@import` points. Relative and absolute ids resolve against the importing
+ * stylesheet's directory (`base`). Bare ids resolve from `base` like Node would, then from
+ * Flare's own install (the optional `tailwindcss` peer usually sits beside Flare).
+ */
+export function resolveStylesheetPath(id: string, base: string): string {
+	if (id.startsWith(".") || isAbsolute(id)) return resolve(base, id);
+	try {
+		return resolveBareStylesheet(id, base);
+	} catch (fromBase) {
+		try {
+			return resolveBareStylesheet(id, dirname(fileURLToPath(import.meta.url)));
+		} catch {
+			throw new Error(
+				`cannot resolve @import "${id}" from ${base}: ${fromBase instanceof Error ? fromBase.message : String(fromBase)}`,
+				{ cause: fromBase },
+			);
+		}
+	}
+}
+
+/**
+ * Where an `@plugin` / `@config` module points: relative and absolute ids from the referencing
+ * stylesheet's directory, bare ids through Node resolution from there, then from Flare's install.
+ */
+export function resolveModulePath(id: string, base: string): string {
+	if (id.startsWith(".") || isAbsolute(id)) return resolve(base, id);
+	try {
+		return createRequire(join(base, "noop.js")).resolve(id);
+	} catch (fromBase) {
+		try {
+			return createRequire(import.meta.url).resolve(id);
+		} catch {
+			throw new Error(
+				`cannot resolve @plugin "${id}" from ${base}: ${fromBase instanceof Error ? fromBase.message : String(fromBase)}`,
+				{ cause: fromBase },
+			);
+		}
+	}
+}
+
+/**
+ * Initialize a Tailwind v4 compiler from an optional CSS entry file. The entry's imports
+ * resolve from its own directory (no entry: the process cwd). Throws on any failure —
+ * callers fail the build, never fall back to pass-through.
+ */
 export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCompiler> {
+	const entry = cssPath ? resolve(cssPath) : undefined;
 	try {
 		/* Optional peer: a non-literal specifier keeps consumers without tailwindcss typechecking. */
 		const tw = (await import(/* @vite-ignore */ TAILWIND_MODULE)) as { compile?: unknown; default?: unknown };
@@ -191,12 +311,7 @@ export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCo
 			);
 		}
 
-		let cssContent: string;
-		if (cssPath) {
-			cssContent = readFileSync(resolve(cssPath), "utf-8");
-		} else {
-			cssContent = '@import "tailwindcss";';
-		}
+		const cssContent = entry ? readFileSync(entry, "utf-8") : '@import "tailwindcss";';
 
 		const compiler = await (
 			compileFn as (
@@ -206,18 +321,17 @@ export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCo
 				build: (classes: string[]) => string;
 			}>
 		)(cssContent, {
+			/* Without `base`, Tailwind resolves the entry's own @imports against "" — the process cwd. */
+			base: entry ? dirname(entry) : process.cwd(),
 			loadStylesheet: (id: string, base: string) => {
-				if (id === "tailwindcss") {
-					const esmRequire = createRequire(import.meta.url);
-					const pkgPath = esmRequire.resolve("tailwindcss/package.json");
-					const pkgDir = dirname(pkgPath);
-					const cssPath2 = join(pkgDir, "index.css");
-					const content = readFileSync(cssPath2, "utf-8");
-					return { base: pkgDir, content, path: cssPath2 };
-				}
-				const resolved = resolve(base, id);
-				const content = readFileSync(resolved, "utf-8");
-				return { base: dirname(resolved), content, path: resolved };
+				const path = resolveStylesheetPath(id, base);
+				return { base: dirname(path), content: readFileSync(path, "utf-8"), path };
+			},
+			/* `@plugin` and `@config`: a plugin's default export (function or plugin object). */
+			loadModule: async (id: string, base: string) => {
+				const path = resolveModulePath(id, base);
+				const mod = (await import(/* @vite-ignore */ pathToFileURL(path).href)) as { default?: unknown };
+				return { base: dirname(path), module: mod.default ?? mod, path };
 			},
 		});
 
@@ -226,7 +340,7 @@ export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCo
 		const trackingBuild = (classes: string[]): string => {
 			const output = originalBuild(classes);
 			for (const m of output.matchAll(/(--[\w-]+)\s*:\s*([^;]+)/g)) {
-				if (!themeVars.has(m[1])) {
+				if (!isLocalVar(m[1]) && !themeVars.has(m[1])) {
 					themeVars.set(m[1], m[2].trim());
 				}
 			}
@@ -236,7 +350,7 @@ export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCo
 		return { build: trackingBuild, themeVars };
 	} catch (e: unknown) {
 		throw new Error(
-			`tailwindcss init failed: ${e instanceof Error ? e.message : String(e)}. Check tailwind.config.ts for syntax errors.`,
+			`Tailwind init failed for ${entry ?? 'the default @import "tailwindcss" entry'}: ${e instanceof Error ? e.message : String(e)}`,
 			{ cause: e },
 		);
 	}