lvyjs-plugin-postcss 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-present, Yuxi (Evan) You
+
+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

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# lvyjs-plugin-postcss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LVY 的通用样式插件。通过公开 `resolveId / load / emitAsset` 接口处理 CSS、可选 Sass/SCSS/Less，并将生成 CSS 的文件绝对路径导出给应用。
+
+## 安装与使用
+
+```sh
+npm install -D lvyjs lvyjs-plugin-postcss
+```
+
+需要 `lvyjs >= 0.3.0-alpha.6`，Node.js 22.18+（22.x）或 24.11+。未发布时先在仓库根目录运行 `yarn install`，在本包目录运行 `npm run build`，通过 workspace 使用。
+
+```ts
+// lvy.config.ts
+import { defineConfig } from 'lvyjs'
+import postcss from 'lvyjs-plugin-postcss'
+
+export default defineConfig({
+  plugins: [postcss()]
+})
+```
+
+```ts
+// src/index.ts
+import stylesheet from './style.css'
+import { readFile } from 'node:fs/promises'
+const css = await readFile(stylesheet, 'utf8')
+```
+
+把 CSS 内容交给页面模板、服务端响应或渲染器。插件不会自动注入浏览器样式。开发中依赖变化会重新编译并重启应用；构建目录中的 CSS 由 LVY 输出，移动完整构建目录后仍可读取。
+
+```sh
+lvy src/index.ts
+lvy build
+```
+
+TypeScript 的样式导入声明已经从 LVY 迁入本包：
+
+```ts
+// src/env.d.ts
+/// <reference types="lvyjs-plugin-postcss/env" />
+```
+
+## PostCSS 配置
+
+使用 `postcss-load-config` 在项目目录发现配置，支持 `postcss.config.cjs/mjs/js/ts`、`.postcssrc` 和 `package.json` 的 `postcss` 字段。配置错误或缺失的插件会导致编译失败；没有配置文件时使用默认步骤。`config` 指定搜索目录，搜索不会越过这个目录。
+
+```js
+// postcss.config.mjs
+import cssnano from 'cssnano'
+export default {
+  plugins: [cssnano({ preset: 'default' })]
+}
+```
+
+```js
+// postcss.config.cjs
+module.exports = {
+  plugins: {
+    cssnano: { preset: 'default' }
+  }
+}
+```
+
+额外插件需要由项目安装。也可以在 LVY 配置中传入 `postcss({ config: false, plugins: [...] })`。开发时支持修改、添加、删除配置文件，以及 PostCSS `dependency` 和 `dir-dependency` 消息声明的依赖。CJS 配置的本地辅助模块也会被监听和重新加载；ESM 辅助模块的修改建议通过重启开发命令重新加载。
+
+默认处理顺序：预处理 Sass/Less → `postcss-import` → URL 别名替换 → autoprefixer → 配置文件插件 → `plugins` 参数中的插件。如果配置文件显式提供同名默认插件，默认实例不会重复添加，其参数和顺序由配置文件控制。
+
+## 别名和预处理器
+
+CSS 入口、CSS 内部 `@import`、Sass `@use` 和 Less `@import` 支持 LVY `alias.entries` 的边界匹配；普通 CSS 相对路径和包导入保留 `postcss-import` 的解析能力。
+
+```css
+@import '@src/theme.css';
+@import './base.css';
+```
+
+按需安装预处理器：
+
+```sh
+npm install -D sass less
+```
+
+```scss
+@use '@src/tokens';
+.card {
+  color: tokens.$brand;
+}
+```
+
+Sass/Less 是可选 peer dependencies，纯 CSS 项目无需安装。编译依赖会参与开发监听。CSS 中 `@import` 引入预处理器文件时，会先编译再内联。
+
+`url()` 默认只替换别名，不复制图片/字体资源。生成的 CSS 位于资源目录，相对 URL 应由应用或部署流程处理；CSS 文件本身的可移动性不包含它引用的外部资源。暂不提供 CSS Modules；`?raw/?url` 导入留给其他插件。
+
+## 与 Tailwind 插件的关系
+
+两个包是独立的 LVY 插件，不相互依赖。同一 CSS 入口由第一个匹配的 `load` 处理，不会因为插件排列自动组成 CSS 流水线。
+
+- Tailwind CSS 4 专用项目使用 `lvyjs-plugin-tailwindcss`。
+- 通用 PostCSS 项目使用本包。
+- 两者共存时，通过互不重叠的 `include` 区分入口。
+
+```ts
+plugins: [
+  tailwindcss({ include: /\.tailwind\.css$/ }),
+  postcss({ include: /\.postcss\.(css|scss|sass|less)$/ })
+]
+```
+
+同一个入口需要 Tailwind 加其他 PostCSS 步骤时，只启用本包，在配置中使用官方适配器：
+
+```sh
+npm install -D tailwindcss@^4.3.3 @tailwindcss/postcss@^4.3.3
+```
+
+```ts
+plugins: [postcss({ imports: false, urls: false, autoprefixer: false })]
+```
+
+```js
+// postcss.config.mjs
+import tailwindcss from '@tailwindcss/postcss'
+import cssnano from 'cssnano'
+export default {
+  plugins: [tailwindcss(), cssnano({ preset: 'default' })]
+}
+```
+
+关闭默认步骤后，让官方 Tailwind 适配器负责导入、URL 和前缀处理，避免重复加工。类名扫描和增量缓存行为由该适配器决定；若需要本仓库“删除类名立即清除 CSS”的专用验收保证，使用独立 Tailwind 插件。
+
+## 参数
+
+| 参数             | 默认值                         | 说明                                                               |
+| ---------------- | ------------------------------ | ------------------------------------------------------------------ |
+| `include`        | `/\.(css\|scss\|sass\|less)$/` | 入口匹配规则                                                       |
+| `config`         | 项目根目录                     | 配置搜索目录；`false` 关闭发现                                     |
+| `plugins`        | `[]`                           | 追加 PostCSS 插件                                                  |
+| `imports`        | `true`                         | 默认内联导入与别名解析                                             |
+| `urls`           | `true`                         | 默认 URL 别名处理                                                  |
+| `autoprefixer`   | `true`                         | `false` 关闭，也可传 autoprefixer 参数                             |
+| `processOptions` | `{}`                           | 覆盖 PostCSS 处理选项；`from/to` 由入口确定                        |
+| `sourcemap`      | 遵循配置                       | `true` 嵌入 map，`false` 关闭；配置开启的外部 map 也转换为内嵌 map |
+| `watchDelay`     | `100`                          | 开发重启防抖毫秒数                                                 |
+
+旧配置 `styles: { filter: ... }` 迁移为 `plugins: [postcss({ include: ... })]`，旧 `styles: false` 则不启用样式插件。LVY 核心已移除样式处理及 PostCSS 依赖。
+
+## 验收
+
+```sh
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```
+
+测试运行真实 LVY CLI，覆盖配置与依赖更新、预处理器、别名、前缀、map、构建目录移动、错误退出、两个独立插件的入口分工，以及官方 Tailwind PostCSS 适配器的组合处理。
+
+首次入口 CSS 或 PostCSS 配置编译失败后，修正相应文件也可触发开发进程恢复；监听在编译开始前注册。
+
+同时使用两个插件时，只引用 `lvyjs-plugin-postcss/env`，它已包含 CSS、Sass/SCSS/Less 声明。无需同时引用两个插件的 `env`，以免产生重复的 CSS 默认导出声明。

package/env.d.ts

@@ -0,0 +1,19 @@
+declare module '*.css' {
+  const path: string
+  export default path
+}
+
+declare module '*.scss' {
+  const path: string
+  export default path
+}
+
+declare module '*.sass' {
+  const path: string
+  export default path
+}
+
+declare module '*.less' {
+  const path: string
+  export default path
+}

package/lib/index.d.ts

@@ -0,0 +1,27 @@
+import { AcceptedPlugin, ProcessOptions } from "postcss";
+import autoprefixer from "autoprefixer";
+import { LvyPlugin } from "lvyjs";
+//#region src/index.d.ts
+interface PostcssOptions {
+  /** Entries handled by this plugin. Defaults to CSS/SCSS/Sass/Less. */
+  include?: RegExp;
+  /** Config search directory relative to the project, or false to disable discovery. */
+  config?: string | false;
+  /** Additional PostCSS plugins, after the plugins in the config file. */
+  plugins?: AcceptedPlugin[];
+  /** Inline CSS imports with alias support. Defaults to true. */
+  imports?: boolean;
+  /** Rewrite URL aliases. Defaults to true. Does not copy resources. */
+  urls?: boolean;
+  /** Add vendor prefixes. Defaults to true. */
+  autoprefixer?: boolean | Parameters<typeof autoprefixer>[0];
+  /** Override PostCSS process options. from/to always refer to the source entry. */
+  processOptions?: Omit<ProcessOptions, 'from' | 'to'>;
+  /** Embed a CSS source map; overrides the config's map option when specified. */
+  sourcemap?: boolean;
+  /** Debounce development restarts, in milliseconds. Defaults to 100. */
+  watchDelay?: number;
+}
+declare function postcssPlugin(options?: PostcssOptions): LvyPlugin;
+//#endregion
+export { PostcssOptions, postcssPlugin as default, postcssPlugin as postcss };

package/lib/index.js

@@ -0,0 +1,212 @@
+import { SourceWatcher } from "./watch.js";
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import postcss from "postcss";
+import loadConfig from "postcss-load-config";
+import postcssImport from "postcss-import";
+import postcssUrl from "postcss-url";
+import autoprefixer from "autoprefixer";
+import { readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/index.ts
+const ownRequire = createRequire(import.meta.url);
+const prefix = "\0lvy-postcss:";
+const configNames = [
+	"package.json",
+	".postcssrc",
+	...[
+		"json",
+		"js",
+		"cjs",
+		"mjs",
+		"ts",
+		"cts",
+		"mts",
+		"yaml",
+		"yml"
+	].flatMap((ext) => [`.postcssrc.${ext}`, `postcss.config.${ext}`])
+];
+function postcssPlugin(options = {}) {
+	let env = {
+		cwd: process.cwd(),
+		command: "dev"
+	};
+	let aliases = [];
+	let watcher;
+	let excluded = [];
+	let configDirectory = env.cwd;
+	let projectRequire = createRequire(resolve(env.cwd, "package.json"));
+	const entries = /* @__PURE__ */ new Map();
+	const include = options.include ?? /\.(css|scss|sass|less)$/;
+	const knownConfigFiles = /* @__PURE__ */ new Set();
+	const aliasPath = (source) => {
+		const alias = aliases.find((alias) => source === alias.find || source.startsWith(alias.find + "/"));
+		return alias ? source.replace(alias.find, alias.replacement) : source;
+	};
+	const close = async () => {
+		await watcher?.close();
+		entries.clear();
+	};
+	const preprocess = async (file, files) => {
+		files.add(file);
+		if (/\.less$/.test(file)) {
+			let less;
+			try {
+				less = projectRequire("less");
+			} catch {
+				throw new Error("LESS requires the optional dependency: npm install -D less");
+			}
+			const result = await less.render(await readFile(file, "utf8"), {
+				filename: file,
+				plugins: [{ install(engine, manager) {
+					const fileManager = new engine.FileManager();
+					fileManager.loadFile = function(name, current, ...args) {
+						return engine.FileManager.prototype.loadFile.call(this, aliasPath(name), current, ...args);
+					};
+					manager.addFileManager(fileManager);
+				} }]
+			});
+			for (const path of result.imports ?? []) files.add(resolve(path));
+			return result.css;
+		}
+		if (/\.(scss|sass)$/.test(file)) {
+			let sass;
+			try {
+				sass = projectRequire("sass");
+			} catch {
+				throw new Error("Sass/SCSS requires the optional dependency: npm install -D sass");
+			}
+			const result = await sass.compileAsync(file, { importers: [{ findFileUrl(source) {
+				const mapped = aliasPath(source);
+				return mapped === source ? null : pathToFileURL(resolve(env.cwd, mapped));
+			} }] });
+			for (const url of result.loadedUrls) if (url.protocol === "file:") files.add(fileURLToPath(url));
+			return result.css;
+		}
+		return readFile(file, "utf8");
+	};
+	return {
+		name: "lvy:postcss",
+		enforce: "pre",
+		configResolved(config, environment) {
+			env = environment;
+			if (options.watchDelay !== void 0 && (!Number.isFinite(options.watchDelay) || options.watchDelay < 0)) throw new Error("watchDelay must be a nonnegative number");
+			if (!options.include && config.plugins?.some((plugin) => plugin && typeof plugin === "object" && "name" in plugin && plugin.name === "lvy:tailwindcss")) console.warn("[lvy:postcss] PostCSS 与 Tailwind 同时启用时，请用 include 区分入口；同一入口由先匹配的插件处理。");
+			configDirectory = resolve(env.cwd, options.config || ".");
+			projectRequire = createRequire(resolve(env.cwd, "package.json"));
+			const build = config.build && typeof config.build === "object" ? config.build : {};
+			excluded = [
+				build.dir ?? build.OutputOptions?.dir ?? "lib",
+				".lvy",
+				...typeof build.tsdown === "object" && typeof build.tsdown.outDir === "string" ? [build.tsdown.outDir] : []
+			].map((path) => resolve(env.cwd, path));
+			aliases = config.alias ? config.alias.entries ?? [] : [];
+		},
+		configureDev(context) {
+			watcher = new SourceWatcher(context, excluded, options.watchDelay ?? 100, (message) => console.warn(`[lvy:postcss] ${message}`));
+			return close;
+		},
+		resolveId(source, importer) {
+			if (source.startsWith(prefix)) return source;
+			if (source.includes("?") || source.includes("#")) return null;
+			include.lastIndex = 0;
+			if (!include.test(source)) return null;
+			const mapped = aliasPath(source);
+			if (!isAbsolute(mapped) && !mapped.startsWith(".") && !mapped.startsWith("file:") && mapped === source) return null;
+			const path = mapped.startsWith("file:") ? fileURLToPath(mapped) : resolve(importer && isAbsolute(importer) ? dirname(importer) : env.cwd, mapped);
+			const id = prefix + createHash("sha256").update(path).digest("hex").slice(0, 24) + ".js";
+			entries.set(id, path);
+			return id;
+		},
+		async load(id) {
+			if (!id.startsWith(prefix)) return null;
+			const file = entries.get(id);
+			if (!file) return null;
+			const files = /* @__PURE__ */ new Set([file]);
+			if (options.config !== false) for (const name of configNames) files.add(resolve(configDirectory, name));
+			if (this.command === "dev") await watcher?.watchFiles(file, files);
+			for (const path of knownConfigFiles) delete projectRequire.cache[path];
+			let configured;
+			let collectConfigFiles = () => {};
+			if (options.config !== false) {
+				try {
+					configured = await loadConfig({
+						cwd: env.cwd,
+						env: env.command === "build" ? "production" : "development"
+					}, configDirectory, { stopDir: configDirectory });
+					files.add(configured.file);
+					knownConfigFiles.add(configured.file);
+					const visited = /* @__PURE__ */ new Set();
+					const collect = (path) => {
+						if (visited.has(path)) return;
+						visited.add(path);
+						const mod = projectRequire.cache[path];
+						for (const child of mod?.children ?? []) {
+							if (child.filename.includes("/node_modules/")) continue;
+							knownConfigFiles.add(child.filename);
+							files.add(child.filename);
+							collect(child.filename);
+						}
+					};
+					collectConfigFiles = () => collect(configured.file);
+				} catch (error) {
+					if (!(error instanceof Error) || !error.message.startsWith("No PostCSS Config found")) throw error;
+				}
+				for (const name of configNames) files.add(resolve(configDirectory, name));
+			}
+			const plugins = [];
+			const userPlugins = [...configured?.plugins ?? [], ...options.plugins ?? []];
+			const configuredNames = new Set(userPlugins.map((plugin) => plugin.postcssPlugin));
+			if (options.imports !== false && !configuredNames.has("postcss-import")) {
+				const importOptions = { load: (filename) => preprocess(filename, files) };
+				if (aliases.length) importOptions.resolve = (source, from, opts, node) => {
+					const mapped = aliasPath(source);
+					if (mapped !== source) return resolve(from, mapped);
+					return ownRequire("postcss-import/lib/resolve-id.js")(source, from, opts, node ?? { error: (message) => new Error(message) });
+				};
+				plugins.push(postcssImport(importOptions));
+			}
+			if (options.urls !== false && !configuredNames.has("postcss-url")) plugins.push(postcssUrl({ url: (asset) => aliasPath(asset.url).replace(/\\/g, "/") }));
+			if (options.autoprefixer !== false && !configuredNames.has("autoprefixer")) plugins.push(autoprefixer(typeof options.autoprefixer === "object" ? options.autoprefixer : {}));
+			plugins.push(...userPlugins);
+			const input = await preprocess(file, files);
+			const processOptions = {
+				...configured?.options,
+				...options.processOptions,
+				from: file,
+				to: file
+			};
+			if (options.sourcemap !== void 0) processOptions.map = options.sourcemap ? { inline: true } : false;
+			else if (processOptions.map) processOptions.map = {
+				...typeof processOptions.map === "object" ? processOptions.map : {},
+				inline: true
+			};
+			const result = await postcss(plugins).process(input, processOptions);
+			collectConfigFiles();
+			for (const warning of result.warnings()) this.warn(warning.toString());
+			const globs = [];
+			for (const message of result.messages) {
+				if (message.type === "dependency" && typeof message.file === "string") files.add(resolve(message.file));
+				if (message.type === "dir-dependency" && typeof message.dir === "string") globs.push({
+					base: resolve(message.dir),
+					pattern: typeof message.glob === "string" ? message.glob : "**/*"
+				});
+			}
+			if (this.command === "build") {
+				for (const path of files) this.addWatchFile(path);
+				for (const glob of globs) this.addWatchFile(glob.base);
+			} else await watcher?.update(file, {
+				files,
+				globs
+			});
+			return this.emitAsset({
+				name: /\.css$/.test(file) ? basename(file) : basename(file) + ".css",
+				source: result.css
+			});
+		},
+		closeBundle: close
+	};
+}
+//#endregion
+export { postcssPlugin as default, postcssPlugin as postcss };

package/lib/watch.d.ts

@@ -0,0 +1,36 @@
+import { DevContext } from "lvyjs";
+//#region src/watch.d.ts
+type WatchSnapshot = {
+  files: Set<string>;
+  globs: {
+    base: string;
+    pattern: string;
+  }[];
+};
+declare const within: (path: string, directory: string) => boolean;
+/** Own the directory watch: LVY's literal file API cannot express filtered source globs. */
+declare class SourceWatcher {
+  private dev;
+  private excluded;
+  private delay;
+  private warn;
+  private watcher?;
+  private timer?;
+  private snapshots;
+  private matches;
+  private files;
+  private explicitModules;
+  private targets;
+  private ready?;
+  private closed;
+  private updates;
+  private settleReady?;
+  constructor(dev: DevContext, excluded: string[], delay: number, warn: (message: string) => void);
+  private ignored;
+  watchFiles(entry: string, files: Iterable<string>): Promise<void>;
+  update(entry: string, snapshot: WatchSnapshot): Promise<void>;
+  private updateSnapshot;
+  close(): Promise<void>;
+}
+//#endregion
+export { SourceWatcher, WatchSnapshot, within };

package/lib/watch.js

@@ -0,0 +1,122 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import chokidar from "chokidar";
+import picomatch from "picomatch";
+//#region src/watch.ts
+const within = (path, directory) => {
+	const part = relative(directory, path);
+	return part === "" || !part.startsWith(`..${sep}`) && part !== ".." && !isAbsolute(part);
+};
+const posix = (path) => path.split(sep).join("/");
+/** Own the directory watch: LVY's literal file API cannot express filtered source globs. */
+var SourceWatcher = class {
+	dev;
+	excluded;
+	delay;
+	warn;
+	watcher;
+	timer;
+	snapshots = /* @__PURE__ */ new Map();
+	matches = [];
+	files = /* @__PURE__ */ new Set();
+	explicitModules = [];
+	targets = /* @__PURE__ */ new Set();
+	ready;
+	closed = false;
+	updates = Promise.resolve();
+	settleReady;
+	constructor(dev, excluded, delay, warn) {
+		this.dev = dev;
+		this.excluded = excluded;
+		this.delay = delay;
+		this.warn = warn;
+	}
+	ignored = (input) => {
+		const path = resolve(input);
+		if (this.excluded.some((directory) => within(path, directory))) return true;
+		if (/(?:^|[\\/])(?:\.git|\.lvy)(?:[\\/]|$)/.test(path)) return true;
+		if (this.files.has(path)) return false;
+		if (/(?:^|[\\/])node_modules(?:[\\/]|$)/.test(path)) return !this.explicitModules.some((directory) => within(path, directory) || within(directory, path));
+		return false;
+	};
+	async watchFiles(entry, files) {
+		const previous = this.snapshots.get(entry);
+		await this.update(entry, {
+			files: /* @__PURE__ */ new Set([...previous?.files ?? [], ...files]),
+			globs: previous?.globs ?? []
+		});
+	}
+	update(entry, snapshot) {
+		const pending = this.updates.then(() => this.updateSnapshot(entry, snapshot));
+		this.updates = pending.catch(() => {});
+		return pending;
+	}
+	async updateSnapshot(entry, snapshot) {
+		if (this.closed) return;
+		this.snapshots.set(entry, snapshot);
+		this.files = new Set([...this.snapshots.values()].flatMap((value) => [...value.files]));
+		const globs = [...this.snapshots.values()].flatMap((value) => value.globs);
+		this.explicitModules = globs.filter((glob) => /(?:^|[\\/])node_modules(?:[\\/]|$)/.test(glob.base)).map((glob) => glob.base);
+		this.matches = globs.filter((glob) => !glob.pattern.startsWith("!")).map((glob) => {
+			const match = picomatch(glob.pattern, { dot: false });
+			return (path) => within(path, glob.base) && match(posix(relative(glob.base, path)));
+		});
+		const directories = globs.filter((glob) => !glob.pattern.startsWith("!")).map((glob) => glob.base);
+		const roots = [...new Set(directories)].filter((path) => !directories.some((parent) => parent !== path && within(path, parent)));
+		const targets = /* @__PURE__ */ new Set([...roots, ...[...this.files].filter((path) => {
+			return !(!/(?:^|[\\/])node_modules(?:[\\/]|$)/.test(path) || this.explicitModules.some((root) => within(path, root))) || !roots.some((root) => within(path, root));
+		})]);
+		const removed = [...this.targets].filter((path) => !targets.has(path));
+		const added = [...targets].filter((path) => !this.targets.has(path));
+		if (this.watcher && (removed.length || added.length)) {
+			await this.watcher.close();
+			this.watcher = void 0;
+			this.ready = void 0;
+		}
+		if (this.closed) return;
+		if (!this.watcher) {
+			this.watcher = chokidar.watch([...targets], {
+				ignoreInitial: true,
+				ignored: this.ignored
+			});
+			this.watcher.on("all", (event, path) => {
+				if (![
+					"add",
+					"change",
+					"unlink"
+				].includes(event) || this.ignored(path)) return;
+				const absolute = resolve(path);
+				if (!this.files.has(absolute) && !this.matches.some((match) => match(absolute))) return;
+				clearTimeout(this.timer);
+				this.timer = setTimeout(() => {
+					if (!this.closed) this.dev.restart();
+				}, this.delay);
+			});
+			this.watcher.on("error", (error) => this.warn(`Source watch failed: ${String(error)}`));
+			this.ready = new Promise((resolveReady, reject) => {
+				const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("PostCSS dependency watch did not become ready")), 3e4);
+				this.settleReady = () => {
+					clearTimeout(timer);
+					resolveReady();
+				};
+				this.watcher.once("ready", this.settleReady);
+				this.watcher.once("error", (error) => {
+					clearTimeout(timer);
+					reject(error);
+				});
+			});
+		} else this.watcher.add([...targets].filter((path) => !this.targets.has(path)));
+		this.targets = targets;
+		await this.ready;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		clearTimeout(this.timer);
+		this.settleReady?.();
+		await this.updates;
+		await this.watcher?.close();
+		this.snapshots.clear();
+	}
+};
+//#endregion
+export { SourceWatcher, within };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "lvyjs-plugin-postcss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "PostCSS and optional Sass/Less integration for LVY",
+  "type": "module",
+  "license": "MIT",
+  "author": "lemonade",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./env": {
+      "types": "./env.d.ts"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE",
+    "env.d.ts"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.11.0"
+  },
+  "peerDependencies": {
+    "lvyjs": ">=0.3.0-alpha.6 <1",
+    "sass": "^1.0.0",
+    "less": "^4.0.0"
+  },
+  "dependencies": {
+    "postcss": "^8.4.47",
+    "postcss-import": "^16.1.0",
+    "postcss-url": "^10.1.3",
+    "autoprefixer": "^10.4.20",
+    "postcss-load-config": "^6.0.1",
+    "chokidar": "^5.0.0",
+    "picomatch": "^4.0.3",
+    "tsx": "^4.23.12"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/picomatch": "^4.0.2",
+    "lvyjs": "0.3.0-alpha.6",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "@types/postcss-import": "^14.0.3",
+    "@types/postcss-url": "^10.0.4",
+    "@types/less": "^3.0.8",
+    "sass": "^1.99.0",
+    "less": "^4.6.4",
+    "@tailwindcss/postcss": "^4.3.3",
+    "tailwindcss": "^4.3.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lemonade-lab/lvyjs.git",
+    "directory": "packages/lvyjs-plugin-postcss"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    },
+    "less": {
+      "optional": true
+    }
+  }
 }