tailwindcss-patch 9.1.0 → 9.2.1

package/dist/cli.js

@@ -1,6 +1,6 @@
 const require_chunk = require("./chunk-8l464Juk.js");
-const require_validate = require("./validate-BuhhSYBe.js");
-const require_index_bundle = require("./index.bundle-C4Y53Ygf.js");
+const require_validate = require("./validate-Bo-Ua7Kg.js");
+const require_index_bundle = require("./index.bundle-BkqJb7rw.js");
 let node_process = require("node:process");
 node_process = require_chunk.__toESM(node_process);
 //#region src/cli.bundle.ts

package/dist/cli.mjs

@@ -1,5 +1,5 @@
-import { k as logger, r as ValidateCommandError } from "./validate-4FCU-Ql3.mjs";
-import { t as createTailwindcssPatchCli } from "./index.bundle-0Fe7Jx8V.mjs";
+import { k as logger, r as ValidateCommandError } from "./validate-CceFRP7h.mjs";
+import { t as createTailwindcssPatchCli } from "./index.bundle-Dnh0a6WS.mjs";
 import process from "node:process";
 //#region src/cli.bundle.ts
 async function main() {

package/dist/commands/cli-runtime.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-8l464Juk.js");
-const require_validate = require("../validate-BuhhSYBe.js");
+const require_validate = require("../validate-Bo-Ua7Kg.js");
 let node_process = require("node:process");
 node_process = require_chunk.__toESM(node_process);
 let fs_extra = require("fs-extra");

package/dist/commands/cli-runtime.mjs

@@ -1,4 +1,4 @@
-import { E as loadWorkspaceConfigModule, T as loadPatchOptionsForWorkspace, a as tailwindcssPatchCommands, b as groupTokensByFile, i as classifyValidateError, k as logger, n as VALIDATE_FAILURE_REASONS, o as migrateConfigFiles, r as ValidateCommandError, s as restoreConfigFiles, t as VALIDATE_EXIT_CODES, u as TailwindcssPatcher } from "../validate-4FCU-Ql3.mjs";
+import { E as loadWorkspaceConfigModule, T as loadPatchOptionsForWorkspace, a as tailwindcssPatchCommands, b as groupTokensByFile, i as classifyValidateError, k as logger, n as VALIDATE_FAILURE_REASONS, o as migrateConfigFiles, r as ValidateCommandError, s as restoreConfigFiles, t as VALIDATE_EXIT_CODES, u as TailwindcssPatcher } from "../validate-CceFRP7h.mjs";
 import process from "node:process";
 import fs from "fs-extra";
 import path from "pathe";

package/dist/{index.bundle-C4Y53Ygf.js → index.bundle-BkqJb7rw.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-8l464Juk.js");
-const require_validate = require("./validate-BuhhSYBe.js");
+const require_validate = require("./validate-Bo-Ua7Kg.js");
 let node_module = require("node:module");
 let node_process = require("node:process");
 node_process = require_chunk.__toESM(node_process);
@@ -7,13 +7,20 @@ let pathe = require("pathe");
 pathe = require_chunk.__toESM(pathe);
 let node_fs = require("node:fs");
 //#region src/v4/engine.ts
-async function collectRawCandidates(source, options) {
+function resolveScanSources(options, compiledSources) {
+	if (Array.isArray(options?.scanSources)) return options.scanSources;
+	if (options?.scanSources === true) return compiledSources;
+	return [];
+}
+async function collectRawCandidates(source, options, compiledSources = []) {
 	const rawCandidates = /* @__PURE__ */ new Set();
 	for (const candidate of options?.candidates ?? []) rawCandidates.add(candidate);
 	for (const candidateSource of options?.sources ?? []) {
 		const candidates = await require_validate.extractRawCandidatesWithPositions(candidateSource.content, candidateSource.extension);
 		for (const candidate of candidates) rawCandidates.add(candidate.rawCandidate);
 	}
+	const filesystemSources = resolveScanSources(options, compiledSources);
+	if (filesystemSources.length > 0) for (const candidate of await require_validate.extractRawCandidates(filesystemSources)) rawCandidates.add(candidate);
 	const inlineSources = require_validate.extractTailwindV4InlineSourceCandidates(source.css);
 	for (const candidate of inlineSources.included) rawCandidates.add(candidate);
 	for (const candidate of inlineSources.excluded) rawCandidates.delete(candidate);
@@ -29,11 +36,11 @@ function createTailwindV4Engine(source) {
 			return require_validate.resolveValidTailwindV4Candidates(await require_validate.loadTailwindV4DesignSystem(source), candidates);
 		},
 		async generate(options) {
-			const rawCandidates = await collectRawCandidates(source, options);
+			const { compiled, dependencies } = await require_validate.compileTailwindV4Source(source);
+			const rawCandidates = await collectRawCandidates(source, options, compiled.sources);
 			const classSet = require_validate.resolveValidTailwindV4Candidates(await require_validate.loadTailwindV4DesignSystem(source), rawCandidates);
 			const inlineSources = require_validate.extractTailwindV4InlineSourceCandidates(source.css);
 			for (const candidate of inlineSources.excluded) classSet.delete(candidate);
-			const { compiled, dependencies } = await require_validate.compileTailwindV4Source(source);
 			return {
 				css: compiled.build(Array.from(classSet)),
 				classSet,

package/dist/{index.bundle-0Fe7Jx8V.mjs → index.bundle-Dnh0a6WS.mjs}

@@ -1,16 +1,23 @@
-import { C as extractTailwindV4InlineSourceCandidates, D as normalizeOptions, S as loadTailwindV4DesignSystem, v as extractRawCandidatesWithPositions, w as resolveValidTailwindV4Candidates, x as compileTailwindV4Source } from "./validate-4FCU-Ql3.mjs";
+import { C as extractTailwindV4InlineSourceCandidates, D as normalizeOptions, S as loadTailwindV4DesignSystem, _ as extractRawCandidates, v as extractRawCandidatesWithPositions, w as resolveValidTailwindV4Candidates, x as compileTailwindV4Source } from "./validate-CceFRP7h.mjs";
 import { createRequire } from "node:module";
 import process from "node:process";
 import path from "pathe";
 import { promises } from "node:fs";
 //#region src/v4/engine.ts
-async function collectRawCandidates(source, options) {
+function resolveScanSources(options, compiledSources) {
+	if (Array.isArray(options?.scanSources)) return options.scanSources;
+	if (options?.scanSources === true) return compiledSources;
+	return [];
+}
+async function collectRawCandidates(source, options, compiledSources = []) {
 	const rawCandidates = /* @__PURE__ */ new Set();
 	for (const candidate of options?.candidates ?? []) rawCandidates.add(candidate);
 	for (const candidateSource of options?.sources ?? []) {
 		const candidates = await extractRawCandidatesWithPositions(candidateSource.content, candidateSource.extension);
 		for (const candidate of candidates) rawCandidates.add(candidate.rawCandidate);
 	}
+	const filesystemSources = resolveScanSources(options, compiledSources);
+	if (filesystemSources.length > 0) for (const candidate of await extractRawCandidates(filesystemSources)) rawCandidates.add(candidate);
 	const inlineSources = extractTailwindV4InlineSourceCandidates(source.css);
 	for (const candidate of inlineSources.included) rawCandidates.add(candidate);
 	for (const candidate of inlineSources.excluded) rawCandidates.delete(candidate);
@@ -26,11 +33,11 @@ function createTailwindV4Engine(source) {
 			return resolveValidTailwindV4Candidates(await loadTailwindV4DesignSystem(source), candidates);
 		},
 		async generate(options) {
-			const rawCandidates = await collectRawCandidates(source, options);
+			const { compiled, dependencies } = await compileTailwindV4Source(source);
+			const rawCandidates = await collectRawCandidates(source, options, compiled.sources);
 			const classSet = resolveValidTailwindV4Candidates(await loadTailwindV4DesignSystem(source), rawCandidates);
 			const inlineSources = extractTailwindV4InlineSourceCandidates(source.css);
 			for (const candidate of inlineSources.excluded) classSet.delete(candidate);
-			const { compiled, dependencies } = await compileTailwindV4Source(source);
 			return {
 				css: compiled.build(Array.from(classSet)),
 				classSet,

package/dist/index.d.mts

@@ -101,6 +101,13 @@ interface TailwindV4CandidateSource {
 interface TailwindV4GenerateOptions {
   candidates?: Iterable<string>;
   sources?: TailwindV4CandidateSource[];
+  /**
+   * 扫描文件系统 source entries 中的候选类名。
+   *
+   * - `true`：使用 Tailwind v4 编译入口解析出的 `@source` 列表。
+   * - `TailwindV4SourcePattern[]`：使用调用方显式传入的 source 列表。
+   */
+  scanSources?: boolean | TailwindV4SourcePattern[];
 }
 interface TailwindV4SourcePattern {
   base: string;

package/dist/index.d.ts

@@ -101,6 +101,13 @@ interface TailwindV4CandidateSource {
 interface TailwindV4GenerateOptions {
   candidates?: Iterable<string>;
   sources?: TailwindV4CandidateSource[];
+  /**
+   * 扫描文件系统 source entries 中的候选类名。
+   *
+   * - `true`：使用 Tailwind v4 编译入口解析出的 `@source` 列表。
+   * - `TailwindV4SourcePattern[]`：使用调用方显式传入的 source 列表。
+   */
+  scanSources?: boolean | TailwindV4SourcePattern[];
 }
 interface TailwindV4SourcePattern {
   base: string;

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_validate = require("./validate-BuhhSYBe.js");
-const require_index_bundle = require("./index.bundle-C4Y53Ygf.js");
+const require_validate = require("./validate-Bo-Ua7Kg.js");
+const require_index_bundle = require("./index.bundle-BkqJb7rw.js");
 exports.CacheStore = require_validate.CacheStore;
 exports.MIGRATION_REPORT_KIND = require_validate.MIGRATION_REPORT_KIND;
 exports.MIGRATION_REPORT_SCHEMA_VERSION = require_validate.MIGRATION_REPORT_SCHEMA_VERSION;

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { D as normalizeOptions, O as CacheStore, S as loadTailwindV4DesignSystem, _ as extractRawCandidates, a as tailwindcssPatchCommands, b as groupTokensByFile, c as MIGRATION_REPORT_KIND, d as getPatchStatusReport, f as runTailwindBuild, g as extractProjectCandidatesWithPositions, h as collectClassesFromTailwindV4, k as logger, l as MIGRATION_REPORT_SCHEMA_VERSION, m as collectClassesFromContexts, n as VALIDATE_FAILURE_REASONS, o as migrateConfigFiles, p as loadRuntimeContexts, r as ValidateCommandError, s as restoreConfigFiles, t as VALIDATE_EXIT_CODES, u as TailwindcssPatcher, v as extractRawCandidatesWithPositions, w as resolveValidTailwindV4Candidates, y as extractValidCandidates } from "./validate-4FCU-Ql3.mjs";
-import { a as resolveTailwindV4SourceFromPatchOptions, i as resolveTailwindV4Source, n as defineConfig, o as createTailwindV4Engine, r as mountTailwindcssPatchCommands, t as createTailwindcssPatchCli } from "./index.bundle-0Fe7Jx8V.mjs";
+import { D as normalizeOptions, O as CacheStore, S as loadTailwindV4DesignSystem, _ as extractRawCandidates, a as tailwindcssPatchCommands, b as groupTokensByFile, c as MIGRATION_REPORT_KIND, d as getPatchStatusReport, f as runTailwindBuild, g as extractProjectCandidatesWithPositions, h as collectClassesFromTailwindV4, k as logger, l as MIGRATION_REPORT_SCHEMA_VERSION, m as collectClassesFromContexts, n as VALIDATE_FAILURE_REASONS, o as migrateConfigFiles, p as loadRuntimeContexts, r as ValidateCommandError, s as restoreConfigFiles, t as VALIDATE_EXIT_CODES, u as TailwindcssPatcher, v as extractRawCandidatesWithPositions, w as resolveValidTailwindV4Candidates, y as extractValidCandidates } from "./validate-CceFRP7h.mjs";
+import { a as resolveTailwindV4SourceFromPatchOptions, i as resolveTailwindV4Source, n as defineConfig, o as createTailwindV4Engine, r as mountTailwindcssPatchCommands, t as createTailwindcssPatchCli } from "./index.bundle-Dnh0a6WS.mjs";
 export { CacheStore, MIGRATION_REPORT_KIND, MIGRATION_REPORT_SCHEMA_VERSION, TailwindcssPatcher, VALIDATE_EXIT_CODES, VALIDATE_FAILURE_REASONS, ValidateCommandError, collectClassesFromContexts, collectClassesFromTailwindV4, createTailwindV4Engine, createTailwindcssPatchCli, defineConfig, extractProjectCandidatesWithPositions, extractRawCandidates, extractRawCandidatesWithPositions, extractValidCandidates, getPatchStatusReport, groupTokensByFile, loadRuntimeContexts, loadTailwindV4DesignSystem, logger, migrateConfigFiles, mountTailwindcssPatchCommands, normalizeOptions, resolveTailwindV4Source, resolveTailwindV4SourceFromPatchOptions, resolveValidTailwindV4Candidates, restoreConfigFiles, runTailwindBuild, tailwindcssPatchCommands };

package/dist/{validate-BuhhSYBe.js → validate-Bo-Ua7Kg.js}

@@ -23,7 +23,7 @@ _babel_traverse = require_chunk.__toESM(_babel_traverse);
 let _babel_parser = require("@babel/parser");
 let tailwindcss_config = require("tailwindcss-config");
 //#region package.json
-var version = "9.1.0";
+var version = "9.2.1";
 //#endregion
 //#region src/constants.ts
 const pkgName = "tailwindcss-patch";
@@ -1592,6 +1592,31 @@ function unique(values) {
 function createRequireBase(base) {
 	return pathe.default.join(base, "package.json");
 }
+function isRelativeSpecifier(id) {
+	return id.startsWith("./") || id.startsWith("../") || id === "." || id === "..";
+}
+function isAbsoluteSpecifier(id) {
+	return pathe.default.isAbsolute(id);
+}
+function isCssSpecifier(id) {
+	return pathe.default.extname(id) === ".css";
+}
+function createCssResolutionCandidates(id) {
+	if (isCssSpecifier(id)) return [id];
+	return [`${id}/index.css`, id];
+}
+function createFallbackCssResolver(baseCandidates) {
+	const bases = unique(baseCandidates);
+	return async (id) => {
+		if (isRelativeSpecifier(id) || isAbsoluteSpecifier(id)) return;
+		for (const base of bases) {
+			const requireFromBase = (0, node_module.createRequire)(createRequireBase(base));
+			for (const candidate of createCssResolutionCandidates(id)) try {
+				return requireFromBase.resolve(candidate);
+			} catch {}
+		}
+	};
+}
 async function importResolvedModule(resolved) {
 	return import((0, node_url.pathToFileURL)(resolved).href);
 }
@@ -1656,31 +1681,53 @@ async function loadTailwindV4DesignSystem(source) {
 	return promise;
 }
 async function compileTailwindV4Source(source) {
-	const node = await loadTailwindV4NodeModule([
-		source.projectRoot,
-		source.base,
-		...source.baseFallbacks
-	]);
-	const dependencies = new Set(source.dependencies);
-	return {
-		compiled: await node.compile(source.css, {
-			base: source.base,
-			onDependency(dependency) {
-				dependencies.add(pathe.default.resolve(dependency));
-			}
-		}),
-		dependencies
-	};
+	const bases = unique([source.base, ...source.baseFallbacks]);
+	if (bases.length === 0) throw new Error("No base directories provided for Tailwind CSS v4 compiler.");
+	const node = await loadTailwindV4NodeModule([source.projectRoot, ...bases]);
+	let lastError;
+	for (const base of bases) {
+		const dependencies = new Set(source.dependencies);
+		try {
+			return {
+				compiled: await node.compile(source.css, {
+					base,
+					customCssResolver: createFallbackCssResolver([source.projectRoot, ...bases]),
+					onDependency(dependency) {
+						dependencies.add(pathe.default.resolve(dependency));
+					}
+				}),
+				dependencies
+			};
+		} catch (error) {
+			lastError = error;
+		}
+	}
+	if (lastError instanceof Error) throw lastError;
+	throw new Error("Failed to compile Tailwind CSS v4 source.");
 }
 //#endregion
 //#region src/extraction/candidate-extractor.ts
 let oxideImportPromise;
 const designSystemCandidateCache = /* @__PURE__ */ new Map();
+function createOxideRuntimeDependencyError(cause) {
+	return new Error([
+		"tailwindcss-patch could not load @tailwindcss/oxide, which is required for source candidate scanning.",
+		"This dependency should be installed automatically by tailwindcss-patch.",
+		"Reinstall dependencies without disabling optional dependencies, or install @tailwindcss/oxide@^4.2.4 manually if your package manager omitted it."
+	].join(" "), { cause });
+}
 async function importOxide() {
-	return import("@tailwindcss/oxide");
+	try {
+		return await import("@tailwindcss/oxide");
+	} catch (error) {
+		throw createOxideRuntimeDependencyError(error);
+	}
 }
 function getOxideModule() {
 	oxideImportPromise ??= importOxide();
+	oxideImportPromise.catch(() => {
+		oxideImportPromise = void 0;
+	});
 	return oxideImportPromise;
 }
 async function extractRawCandidatesWithPositions(content, extension = "html") {

package/dist/{validate-4FCU-Ql3.mjs → validate-CceFRP7h.mjs}

@@ -16,7 +16,7 @@ import _babelTraverse from "@babel/traverse";
 import { parse, parse as parse$1 } from "@babel/parser";
 import { loadConfig } from "tailwindcss-config";
 //#region package.json
-var version = "9.1.0";
+var version = "9.2.1";
 //#endregion
 //#region src/constants.ts
 const pkgName = "tailwindcss-patch";
@@ -1590,6 +1590,31 @@ function unique(values) {
 function createRequireBase(base) {
 	return path.join(base, "package.json");
 }
+function isRelativeSpecifier(id) {
+	return id.startsWith("./") || id.startsWith("../") || id === "." || id === "..";
+}
+function isAbsoluteSpecifier(id) {
+	return path.isAbsolute(id);
+}
+function isCssSpecifier(id) {
+	return path.extname(id) === ".css";
+}
+function createCssResolutionCandidates(id) {
+	if (isCssSpecifier(id)) return [id];
+	return [`${id}/index.css`, id];
+}
+function createFallbackCssResolver(baseCandidates) {
+	const bases = unique(baseCandidates);
+	return async (id) => {
+		if (isRelativeSpecifier(id) || isAbsoluteSpecifier(id)) return;
+		for (const base of bases) {
+			const requireFromBase = createRequire(createRequireBase(base));
+			for (const candidate of createCssResolutionCandidates(id)) try {
+				return requireFromBase.resolve(candidate);
+			} catch {}
+		}
+	};
+}
 async function importResolvedModule(resolved) {
 	return import(pathToFileURL(resolved).href);
 }
@@ -1654,31 +1679,53 @@ async function loadTailwindV4DesignSystem(source) {
 	return promise;
 }
 async function compileTailwindV4Source(source) {
-	const node = await loadTailwindV4NodeModule([
-		source.projectRoot,
-		source.base,
-		...source.baseFallbacks
-	]);
-	const dependencies = new Set(source.dependencies);
-	return {
-		compiled: await node.compile(source.css, {
-			base: source.base,
-			onDependency(dependency) {
-				dependencies.add(path.resolve(dependency));
-			}
-		}),
-		dependencies
-	};
+	const bases = unique([source.base, ...source.baseFallbacks]);
+	if (bases.length === 0) throw new Error("No base directories provided for Tailwind CSS v4 compiler.");
+	const node = await loadTailwindV4NodeModule([source.projectRoot, ...bases]);
+	let lastError;
+	for (const base of bases) {
+		const dependencies = new Set(source.dependencies);
+		try {
+			return {
+				compiled: await node.compile(source.css, {
+					base,
+					customCssResolver: createFallbackCssResolver([source.projectRoot, ...bases]),
+					onDependency(dependency) {
+						dependencies.add(path.resolve(dependency));
+					}
+				}),
+				dependencies
+			};
+		} catch (error) {
+			lastError = error;
+		}
+	}
+	if (lastError instanceof Error) throw lastError;
+	throw new Error("Failed to compile Tailwind CSS v4 source.");
 }
 //#endregion
 //#region src/extraction/candidate-extractor.ts
 let oxideImportPromise;
 const designSystemCandidateCache = /* @__PURE__ */ new Map();
+function createOxideRuntimeDependencyError(cause) {
+	return new Error([
+		"tailwindcss-patch could not load @tailwindcss/oxide, which is required for source candidate scanning.",
+		"This dependency should be installed automatically by tailwindcss-patch.",
+		"Reinstall dependencies without disabling optional dependencies, or install @tailwindcss/oxide@^4.2.4 manually if your package manager omitted it."
+	].join(" "), { cause });
+}
 async function importOxide() {
-	return import("@tailwindcss/oxide");
+	try {
+		return await import("@tailwindcss/oxide");
+	} catch (error) {
+		throw createOxideRuntimeDependencyError(error);
+	}
 }
 function getOxideModule() {
 	oxideImportPromise ??= importOxide();
+	oxideImportPromise.catch(() => {
+		oxideImportPromise = void 0;
+	});
 	return oxideImportPromise;
 }
 async function extractRawCandidatesWithPositions(content, extension = "html") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwindcss-patch",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "description": "patch tailwindcss for exposing context and extract classes",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -66,6 +66,7 @@
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
     "@tailwindcss/node": "^4.2.4",
+    "@tailwindcss/oxide": "^4.2.4",
     "cac": "6.7.14",
     "consola": "^3.4.2",
     "fs-extra": "^11.3.4",
@@ -77,7 +78,6 @@
     "@tailwindcss-mangle/config": "7.0.1"
   },
   "devDependencies": {
-    "@tailwindcss/oxide": "^4.2.4",
     "@tailwindcss/postcss": "^4.2.4",
     "@tailwindcss/vite": "^4.2.4",
     "tailwindcss": "^4.1.18",

package/src/extraction/candidate-extractor.ts

@@ -14,12 +14,31 @@ import { getTailwindV4DesignSystemCacheKey, loadTailwindV4DesignSystem } from '.
 let oxideImportPromise: ReturnType<typeof importOxide> | undefined
 const designSystemCandidateCache = new Map<string, Map<string, boolean>>()
 
+function createOxideRuntimeDependencyError(cause: unknown) {
+  return new Error(
+    [
+      'tailwindcss-patch could not load @tailwindcss/oxide, which is required for source candidate scanning.',
+      'This dependency should be installed automatically by tailwindcss-patch.',
+      'Reinstall dependencies without disabling optional dependencies, or install @tailwindcss/oxide@^4.2.4 manually if your package manager omitted it.',
+    ].join(' '),
+    { cause },
+  )
+}
+
 async function importOxide() {
-  return import('@tailwindcss/oxide')
+  try {
+    return await import('@tailwindcss/oxide')
+  }
+  catch (error) {
+    throw createOxideRuntimeDependencyError(error)
+  }
 }
 
 function getOxideModule() {
   oxideImportPromise ??= importOxide()
+  oxideImportPromise.catch(() => {
+    oxideImportPromise = undefined
+  })
   return oxideImportPromise
 }
 

package/src/v4/engine.ts

@@ -3,12 +3,30 @@ import type {
   TailwindV4GenerateOptions,
   TailwindV4GenerateResult,
   TailwindV4ResolvedSource,
+  TailwindV4SourcePattern,
 } from './types'
-import { extractRawCandidatesWithPositions } from '../extraction/candidate-extractor'
+import { extractRawCandidates, extractRawCandidatesWithPositions } from '../extraction/candidate-extractor'
 import { extractTailwindV4InlineSourceCandidates, resolveValidTailwindV4Candidates } from './candidates'
 import { compileTailwindV4Source, loadTailwindV4DesignSystem } from './node-adapter'
 
-async function collectRawCandidates(source: TailwindV4ResolvedSource, options: TailwindV4GenerateOptions | undefined) {
+function resolveScanSources(
+  options: TailwindV4GenerateOptions | undefined,
+  compiledSources: TailwindV4SourcePattern[],
+) {
+  if (Array.isArray(options?.scanSources)) {
+    return options.scanSources
+  }
+  if (options?.scanSources === true) {
+    return compiledSources
+  }
+  return []
+}
+
+async function collectRawCandidates(
+  source: TailwindV4ResolvedSource,
+  options: TailwindV4GenerateOptions | undefined,
+  compiledSources: TailwindV4SourcePattern[] = [],
+) {
   const rawCandidates = new Set<string>()
 
   for (const candidate of options?.candidates ?? []) {
@@ -22,6 +40,13 @@ async function collectRawCandidates(source: TailwindV4ResolvedSource, options: T
     }
   }
 
+  const filesystemSources = resolveScanSources(options, compiledSources)
+  if (filesystemSources.length > 0) {
+    for (const candidate of await extractRawCandidates(filesystemSources)) {
+      rawCandidates.add(candidate)
+    }
+  }
+
   const inlineSources = extractTailwindV4InlineSourceCandidates(source.css)
   for (const candidate of inlineSources.included) {
     rawCandidates.add(candidate)
@@ -44,17 +69,15 @@ export function createTailwindV4Engine(source: TailwindV4ResolvedSource): Tailwi
       return resolveValidTailwindV4Candidates(designSystem, candidates)
     },
     async generate(options): Promise<TailwindV4GenerateResult> {
-      const rawCandidates = await collectRawCandidates(source, options)
+      const { compiled, dependencies } = await compileTailwindV4Source(source)
+      const rawCandidates = await collectRawCandidates(source, options, compiled.sources)
       const designSystem = await loadTailwindV4DesignSystem(source)
       const classSet = resolveValidTailwindV4Candidates(designSystem, rawCandidates)
       const inlineSources = extractTailwindV4InlineSourceCandidates(source.css)
-      // TODO: Non-inline `@source not "..."` is surfaced through `compiled.sources`;
-      // apply it here if generate() grows filesystem SourceEntry scanning.
       for (const candidate of inlineSources.excluded) {
         classSet.delete(candidate)
       }
 
-      const { compiled, dependencies } = await compileTailwindV4Source(source)
       const css = compiled.build(Array.from(classSet))
 
       return {

package/src/v4/node-adapter.ts

@@ -20,6 +20,7 @@ interface TailwindV4NodeModule {
   compile: (css: string, options: {
     base: string
     onDependency: (dependency: string) => void
+    customCssResolver?: (id: string, base: string) => Promise<string | false | undefined>
   }) => Promise<TailwindV4CompiledSource>
   __unstable__loadDesignSystem: (css: string, options: { base: string }) => Promise<TailwindV4DesignSystem>
 }
@@ -35,6 +36,45 @@ function createRequireBase(base: string) {
   return path.join(base, 'package.json')
 }
 
+function isRelativeSpecifier(id: string) {
+  return id.startsWith('./') || id.startsWith('../') || id === '.' || id === '..'
+}
+
+function isAbsoluteSpecifier(id: string) {
+  return path.isAbsolute(id)
+}
+
+function isCssSpecifier(id: string) {
+  return path.extname(id) === '.css'
+}
+
+function createCssResolutionCandidates(id: string) {
+  if (isCssSpecifier(id)) {
+    return [id]
+  }
+  return [`${id}/index.css`, id]
+}
+
+function createFallbackCssResolver(baseCandidates: string[]) {
+  const bases = unique(baseCandidates)
+  return async (id: string) => {
+    if (isRelativeSpecifier(id) || isAbsoluteSpecifier(id)) {
+      return undefined
+    }
+
+    for (const base of bases) {
+      const requireFromBase = createRequire(createRequireBase(base))
+      for (const candidate of createCssResolutionCandidates(id)) {
+        try {
+          return requireFromBase.resolve(candidate)
+        }
+        catch {}
+      }
+    }
+    return undefined
+  }
+}
+
 async function importResolvedModule(resolved: string): Promise<TailwindV4NodeModule> {
   return import(pathToFileURL(resolved).href) as unknown as Promise<TailwindV4NodeModule>
 }
@@ -133,17 +173,37 @@ export async function loadTailwindV4DesignSystem(source: TailwindV4ResolvedSourc
 }
 
 export async function compileTailwindV4Source(source: TailwindV4ResolvedSource) {
-  const node = await loadTailwindV4NodeModule([source.projectRoot, source.base, ...source.baseFallbacks])
-  const dependencies = new Set(source.dependencies)
-  const compiled = await node.compile(source.css, {
-    base: source.base,
-    onDependency(dependency) {
-      dependencies.add(path.resolve(dependency))
-    },
-  })
+  const bases = unique([source.base, ...source.baseFallbacks])
+  if (bases.length === 0) {
+    throw new Error('No base directories provided for Tailwind CSS v4 compiler.')
+  }
+
+  const node = await loadTailwindV4NodeModule([source.projectRoot, ...bases])
+  let lastError: unknown
+
+  for (const base of bases) {
+    const dependencies = new Set(source.dependencies)
+    try {
+      const compiled = await node.compile(source.css, {
+        base,
+        customCssResolver: createFallbackCssResolver([source.projectRoot, ...bases]),
+        onDependency(dependency) {
+          dependencies.add(path.resolve(dependency))
+        },
+      })
+
+      return {
+        compiled,
+        dependencies,
+      }
+    }
+    catch (error) {
+      lastError = error
+    }
+  }
 
-  return {
-    compiled,
-    dependencies,
+  if (lastError instanceof Error) {
+    throw lastError
   }
+  throw new Error('Failed to compile Tailwind CSS v4 source.')
 }

package/src/v4/types.ts

@@ -24,6 +24,13 @@ export interface TailwindV4CandidateSource {
 export interface TailwindV4GenerateOptions {
   candidates?: Iterable<string>
   sources?: TailwindV4CandidateSource[]
+  /**
+   * 扫描文件系统 source entries 中的候选类名。
+   *
+   * - `true`：使用 Tailwind v4 编译入口解析出的 `@source` 列表。
+   * - `TailwindV4SourcePattern[]`：使用调用方显式传入的 source 列表。
+   */
+  scanSources?: boolean | TailwindV4SourcePattern[]
 }
 
 export interface TailwindV4SourcePattern {