@weapp-vite/tailwindcss 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ice breaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @weapp-vite/tailwindcss
+
+基于 `weapp-tailwindcss/core` 的实验性、宿主无关 Tailwind 控制器。
+
+`createTailwindController` 惰性创建上游编译器并管理失效与释放。`prepareTailwindRoots` 用封存的输入生成本批编译结果，预处理判定和输出排除由宿主提供。`prepareTailwindOutput` 封存宿主的最终 CSS 投影和候选集合，返回原生 CSS 与使用同一份 `CompilerSnapshot` 的 JS/模板转换。
+
+宿主负责 Vite 预处理、CSS Modules、活跃模块图、文件监听、原生样式策略及 emit/write。控制器不创建 watcher，不启动 DevEngine，不写构建输出，也不调用 `notifyPayloadDelivered`。
+
+Tailwind 扫描、候选删除、CSS 生成与类名转换仍由上游 core 实现。框架特定的 HTML defaults、Vue SFC、Page/layout 和传输协议不在本包中。
+
+首期以微信双宿主运行时为验收目标；支付宝与抖音提供编译/适配契约验证，不宣称其运行时 HMR 已完成验收。
+
+Node.js 版本要求随编译内核：`^22.18.0 || >=24.11.0`。

package/dist/index.d.mts

@@ -0,0 +1,61 @@
+import { HmrCompilerPreparation, HmrCompilerRequest } from "@weapp-vite/hmr";
+import { Compiler, Compiler as Compiler$1, CompilerCssTransformOptions, CompilerGenerateRequest, CompilerGenerateRequest as CompilerGenerateRequest$1, CompilerGenerateResult, CompilerGenerateResult as CompilerGenerateResult$1, CompilerSnapshot, CompilerSnapshot as CompilerSnapshot$1, CreateCompilerOptions, CreateCompilerOptions as CreateCompilerOptions$1 } from "weapp-tailwindcss/core";
+//#region src/controller.d.ts
+export interface TailwindControllerOptions {
+  compiler?: CreateCompilerOptions$1;
+  loadCore?: () => Promise<Pick<typeof import('weapp-tailwindcss/core'), 'createCompiler'>>;
+}
+/** 编译器按宿主生命周期惰性创建；不创建 Vite、DevEngine、watcher 或输出写入者。 */
+export declare class TailwindController {
+  private readonly options;
+  private instance?;
+  private closed;
+  private disposal?;
+  constructor(options?: TailwindControllerOptions);
+  getCompiler(): Promise<Compiler$1>;
+  /** 空控制器的失效不启动 Tailwind；实际编译根由 core 统一失效。 */
+  invalidate(files: Iterable<string>): Promise<readonly string[]>;
+  remove(id: string): Promise<void>;
+  dispose(): Promise<void>;
+}
+export declare function createTailwindController(options?: TailwindControllerOptions): TailwindController;
+/** 同一份 core 快照用于所有转换；宿主提供最终资产，公共层不推断框架输出归属。 */
+export declare function createTailwindPreparation(compiler: Compiler$1, snapshot: CompilerSnapshot$1, assets?: NonNullable<HmrCompilerPreparation['assets']>): HmrCompilerPreparation;
+//#endregion
+//#region src/output.d.ts
+export interface TailwindOutputInput {
+  id: string;
+  target?: CompilerSnapshot$1['target'];
+  css: string;
+  classSet: Iterable<string>;
+  dependencies?: Iterable<string>;
+  styleOptions?: CompilerCssTransformOptions;
+}
+export interface TailwindOutput {
+  css: string;
+  snapshot: CompilerSnapshot$1;
+  preparation: HmrCompilerPreparation;
+}
+/** 在宿主回调内封存投影，再异步转换；Vite 最终 CSS 和所有补丁共用同一身份集合。 */
+export declare function prepareTailwindOutput(compiler: Compiler$1 | Promise<Compiler$1>, input: TailwindOutputInput): Promise<TailwindOutput>;
+//#endregion
+//#region src/roots.d.ts
+export interface TailwindRootState {
+  request: CompilerGenerateRequest$1;
+  result: CompilerGenerateResult$1;
+  rawSources: ReadonlyMap<string, string | null | undefined>;
+}
+export interface TailwindRootHost {
+  cwd: string;
+  sourceId: (file: string) => string;
+  isOutput?: (file: string) => boolean;
+  reusePreprocessedCss?: (file: string, previous: string | null | undefined, current: string | null | undefined) => boolean;
+}
+/** 使用封存源码驱动上游完整候选生成；框架预处理与输出排除由宿主提供。 */
+export declare function prepareTailwindRoots<K>(compiler: Compiler$1, request: HmrCompilerRequest, roots: ReadonlyMap<K, TailwindRootState>, options: TailwindRootHost): Promise<Map<K, CompilerGenerateResult$1>>;
+//#endregion
+//#region src/sources.d.ts
+/** 返回上游实际扫描边界中的文件，宿主将它们登记到现有 watcher。 */
+export declare function listTailwindSourceFiles(result: CompilerGenerateResult$1, cwd: string): Promise<string[]>;
+//#endregion
+export type { Compiler, CompilerGenerateRequest, CompilerGenerateResult, CompilerSnapshot, CreateCompilerOptions };

package/dist/index.mjs

@@ -0,0 +1,183 @@
+import { CompilerHmrResyncError, normalizeHmrSourceMap } from "@weapp-vite/hmr";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { createTailwindV4CompiledSourceEntries, createTailwindV4SourceEntryMatcher, resolveProjectSourceFiles } from "@weapp-tailwindcss/engine";
+import path from "pathe";
+//#region src/controller.ts
+/** 编译器按宿主生命周期惰性创建；不创建 Vite、DevEngine、watcher 或输出写入者。 */
+var TailwindController = class {
+	options;
+	instance;
+	closed = false;
+	disposal;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	getCompiler() {
+		if (this.closed) return Promise.reject(/* @__PURE__ */ new Error("Tailwind controller is disposed"));
+		this.instance ??= (this.options.loadCore?.() ?? import("weapp-tailwindcss/core")).then((core) => core.createCompiler(this.options.compiler));
+		return this.instance;
+	}
+	/** 空控制器的失效不启动 Tailwind；实际编译根由 core 统一失效。 */
+	async invalidate(files) {
+		return this.instance ? (await this.instance).invalidate(files) : [];
+	}
+	async remove(id) {
+		if (this.instance) await (await this.instance).remove(id);
+	}
+	dispose() {
+		this.closed = true;
+		this.disposal ??= this.instance?.then((compiler) => compiler.dispose()) ?? Promise.resolve();
+		return this.disposal;
+	}
+};
+function createTailwindController(options = {}) {
+	return new TailwindController(options);
+}
+function labelMap(value, fileName, code) {
+	const map = normalizeHmrSourceMap(value);
+	if (!map?.sources.includes("")) return map;
+	return {
+		...map,
+		sources: map.sources.map((source) => source || fileName),
+		sourcesContent: map.sources.map((source, index) => map.sourcesContent?.[index] ?? (source === "" ? code : null))
+	};
+}
+/** 同一份 core 快照用于所有转换；宿主提供最终资产，公共层不推断框架输出归属。 */
+function createTailwindPreparation(compiler, snapshot, assets = []) {
+	return {
+		assets,
+		dependencies: snapshot.dependencies,
+		transformTemplate: async ({ code, fileName }) => ({ code: await compiler.transformTemplate(code, snapshot, { filename: fileName }) }),
+		transformJavaScript: async ({ code, fileName, sourcemap }) => {
+			const result = await compiler.transformJavaScript(code, snapshot, {
+				filename: fileName,
+				generateMap: sourcemap !== false
+			});
+			if (result.error) throw result.error;
+			return {
+				code: result.code,
+				map: labelMap(result.map, fileName, code)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/output.ts
+/** 在宿主回调内封存投影，再异步转换；Vite 最终 CSS 和所有补丁共用同一身份集合。 */
+function prepareTailwindOutput(compiler, input) {
+	const css = input.css;
+	const snapshotInput = {
+		id: input.id,
+		classSet: new Set(input.classSet),
+		dependencies: input.dependencies ? [...input.dependencies] : [],
+		target: input.target ?? "weapp"
+	};
+	const styleOptions = input.styleOptions ? { ...input.styleOptions } : void 0;
+	return Promise.resolve(compiler).then(async (instance) => {
+		const snapshot = instance.createSnapshot(snapshotInput);
+		return {
+			css: (await instance.transformCss(css, snapshot, styleOptions)).css,
+			snapshot,
+			preparation: createTailwindPreparation(instance, snapshot)
+		};
+	});
+}
+//#endregion
+//#region src/roots.ts
+const caches = /* @__PURE__ */ new WeakMap();
+/** 使用封存源码驱动上游完整候选生成；框架预处理与输出排除由宿主提供。 */
+async function prepareTailwindRoots(compiler, request, roots, options) {
+	const cache = caches.get(compiler) ?? /* @__PURE__ */ new WeakMap();
+	caches.set(compiler, cache);
+	const capturedRoots = new Map(roots);
+	request = {
+		...request,
+		changedFiles: [...request.changedFiles],
+		sources: new Map(request.sources)
+	};
+	const entries = /* @__PURE__ */ new Map();
+	for (const [index, root] of capturedRoots) {
+		const base = root.request.sourceOptions?.projectRoot ?? root.request.source?.base ?? options.cwd;
+		const matches = createTailwindV4SourceEntryMatcher(createTailwindV4CompiledSourceEntries(root.result.root, [...root.result.sources], base));
+		const sources = [...request.sources].flatMap(([file, content]) => content !== null && matches?.(file) && !options.isOutput?.(file) ? [{
+			content,
+			extension: path.extname(file).slice(1)
+		}] : []);
+		const sourceOptions = root.request.sourceOptions;
+		if (!sourceOptions) throw new Error("Tailwind HMR requires a captured source entry");
+		const cssSources = sourceOptions.cssSources?.map((source) => {
+			if (!source.file) return source;
+			const id = options.sourceId(source.file ?? "");
+			const raw = request.sources.get(id);
+			const previous = root.rawSources.get(id);
+			if (raw === previous || raw === void 0) return source;
+			if (options.reusePreprocessedCss?.(id, previous, raw)) return source;
+			if (typeof raw !== "string" || source.css !== previous) throw new CompilerHmrResyncError(request.changedFiles, "Compiler root requires a new preprocessed input");
+			return {
+				...source,
+				css: raw
+			};
+		});
+		const entrySources = (sourceOptions.cssEntries ?? []).map((file) => {
+			const css = request.sources.get(options.sourceId(file));
+			if (typeof css !== "string") throw new TypeError(`Missing captured Tailwind CSS input: ${file}`);
+			return {
+				file,
+				css,
+				base: path.dirname(file),
+				dependencies: [file]
+			};
+		});
+		const memoryRoots = new Set([...cssSources ?? [], ...entrySources].flatMap((source) => source.file ? [options.sourceId(source.file)] : []));
+		const dependencyVersions = /* @__PURE__ */ new Map();
+		const checkDependency = (file) => {
+			const id = options.sourceId(file);
+			if (memoryRoots.has(id)) return;
+			const expected = request.sources.get(id);
+			const source = readFileSync(file, "utf8");
+			const stat = statSync(file, { bigint: true });
+			const version = `${stat.mtimeNs}:${stat.ctimeNs}:${stat.ino}:${stat.size}`;
+			if (expected !== source || dependencyVersions.has(id) && dependencyVersions.get(id) !== version) throw new CompilerHmrResyncError(request.changedFiles, "Compiler dependency changed outside the captured input view");
+			dependencyVersions.set(id, version);
+		};
+		for (const file of root.result.dependencies) checkDependency(file);
+		const signature = createHash("sha256").update(JSON.stringify([
+			cssSources,
+			entrySources,
+			sources,
+			[...dependencyVersions]
+		])).digest("hex");
+		const cached = cache.get(root);
+		const generated = cached?.signature === signature ? cached.result : await compiler.generate({
+			...root.request,
+			sourceOptions: {
+				...sourceOptions,
+				cssEntries: [],
+				cssSources: [...cssSources ?? [], ...entrySources]
+			},
+			sources,
+			scanSources: false
+		});
+		entries.set(index, generated);
+		for (const file of generated.dependencies) checkDependency(file);
+		cache.set(root, {
+			signature,
+			result: generated
+		});
+	}
+	return entries;
+}
+//#endregion
+//#region src/sources.ts
+/** 返回上游实际扫描边界中的文件，宿主将它们登记到现有 watcher。 */
+function listTailwindSourceFiles(result, cwd) {
+	const sources = createTailwindV4CompiledSourceEntries(result.root, [...result.sources], cwd);
+	return resolveProjectSourceFiles({
+		cwd,
+		sources,
+		filter: createTailwindV4SourceEntryMatcher(sources)
+	});
+}
+//#endregion
+export { TailwindController, createTailwindController, createTailwindPreparation, listTailwindSourceFiles, prepareTailwindOutput, prepareTailwindRoots };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@weapp-vite/tailwindcss",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "基于 weapp-tailwindcss/core 的宿主无关编译控制器",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weapp-vite/weapp-vite.git",
+    "directory": "packages/tailwindcss"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": "^22.18.0 || >=24.11.0"
+  },
+  "dependencies": {
+    "@weapp-tailwindcss/engine": "0.1.1",
+    "@weapp-vite/hmr": "0.1.0",
+    "pathe": "^2.0.3",
+    "weapp-tailwindcss": "^5.5.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run -c vitest.config.ts",
+    "test:types": "tsd --files \"test-d/**/*.test-d.ts\"",
+    "lint": "eslint ."
+  }
+}