@ecopages/postcss-processor 0.2.0-alpha.2 → 0.2.0-alpha.20

package/CHANGELOG.md

@@ -8,15 +8,14 @@ All notable changes to `@ecopages/postcss-processor` are documented here.
 
 ### Features
 
-- **Runtime CSS loaders** — Added `css-loader-plugin.ts`, `css-loader.bun.ts`, and `css-runtime-contract.ts` to support runtime CSS loading. CSS is now cached at runtime to avoid redundant processing during HMR (`cbaafea4`, `e7653c9b`).
-- **`PostcssProcessor` class** — New `postcss-processor.ts` exposes a programmatic API for the processor separate from the plugin DSL.
+- Added reusable runtime CSS loading, a public `PostcssProcessor` class, and build-adapter registration for the plugin.
 
-### Refactoring
+### Bug Fixes
 
-- `plugin.ts` significantly overhauled to integrate with the new build adapter and support build dependency graph registration (`e7653c9b`).
-- Test suite updated for esbuild adapter and Node runtime compatibility (`31a44458`).
-- Removed unused `@types/postcss` dev dependency.
+- Fixed runtime PostCSS config loading and stylesheet rebuilds for Tailwind-driven template changes.
+
+- Fixed direct stylesheet processing and preset output so Tailwind v4 preserves injected references and nested BEM selectors.
 
 ### Tests
 
-- Updated `plugin.test.ts`, `postcss-processor.test.ts`, and `presets.test.ts` for new plugin contract.
+- Added processor and preset coverage for the runtime CSS loader and build adapter flow.

package/README.md

@@ -1,56 +1,32 @@
-# PostCSS Processor
+# @ecopages/postcss-processor
 
-This module provides a PostCSS processor plugin for Ecopages and utility functions for processing CSS files and strings using PostCSS. It includes built-in presets for Tailwind CSS (v3 and v4).
+PostCSS processing pipeline for Ecopages. It provides a processor plugin that seamlessly integrates PostCSS into the Ecopages build system, and includes built-in presets for Tailwind CSS (v3 and v4).
 
 ## Features
 
-- **Ecopages Processor Plugin**: Seamless integration with Ecopages build system.
-- **Tailwind Presets**: Ready-to-use configurations for Tailwind CSS v3 and v4.
-- **Automatic Configuration**: Detects `postcss.config.{js,ts,etc}` automatically.
-- **Standalone Usage**: Process CSS files or strings directly.
-- **Bun Loader**: Automatically registers a Bun loader for importing CSS in TS/JS files.
+- **Ecopages Processor Plugin**: Hook right into the build pipeline.
+- **Tailwind Presets**: Pre-configured pipelines for Tailwind CSS v3 and v4.
+- **Automatic Configuration**: Detects existing `postcss.config.{js,ts,etc}`.
+- **Bun Loader**: Registers a Bun loader for importing CSS in TS/JS files.
 
-## Install
+## Installation
 
 ```bash
-bunx jsr add @ecopages/postcss-processor
+bun add @ecopages/postcss-processor
 ```
 
-## Usage with Ecopages
+## Usage
 
-Integrate the processor into your `eco.config.ts` using one of the available presets.
-
-### Tailwind v3 Preset
-
-Includes `tailwindcss`, `autoprefixer`, `postcss-import`, `cssnano`.
-
-```bash
-bun add -D tailwindcss@3.4.19
-```
-
-```typescript
-// eco.config.ts
-import { ConfigBuilder } from '@ecopages/core';
-import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
-
-const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
-
-export default config;
-```
+Integrate the processor into your `eco.config.ts` using a preset.
 
 ### Tailwind v4 Preset (Recommended)
 
-Includes `@tailwindcss/postcss`, `autoprefixer`, `postcss-nested`, `cssnano`, and handles `@reference` injection for `@apply`.
-
-```bash
-bun add -D @tailwindcss/postcss tailwindcss
-```
+Requires `@tailwindcss/postcss` and `tailwindcss` to be installed.
 
 ```typescript
 // eco.config.ts
 import path from 'node:path';
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
 import { tailwindV4Preset } from '@ecopages/postcss-processor/presets/tailwind-v4';
 
@@ -58,7 +34,7 @@ const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin(
 			tailwindV4Preset({
-				referencePath: path.resolve(import.meta.dir, 'src/styles/app.css'),
+				referencePath: path.resolve(import.meta.dirname, 'src/styles/app.css'),
 			}),
 		),
 	])
@@ -67,53 +43,41 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-### Browser Support
-
-By default, the presets target a broad range of modern browsers (`>0.3%, not ie 11, not dead, not op_mini all`).
-
-To override this, add a `browserslist` configuration to your `package.json` or create a `.browserslistrc` file in your project root. The processor will automatically detect and use your custom configuration.
-
-### Custom Configuration
-
-You can also use a standard `postcss.config.js` file or pass plugins manually.
-
-**Using `postcss.config.js`:**
-Create the file in your root, and simply add `postcssProcessorPlugin()` to your config without arguments.
+### Tailwind v3 Preset
 
-**Manual Configuration:**
+Requires `tailwindcss@3`, `autoprefixer`, `postcss-import`, and `cssnano` to be installed.
 
 ```typescript
+// eco.config.ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import myPlugin from 'postcss-my-plugin';
+import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
+
+const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
 
-postcssProcessorPlugin({
-	plugins: {
-		'my-plugin': myPlugin(),
-	},
-});
+export default config;
 ```
 
-**Advanced Configuration:**
+## Custom Configuration
 
-For advanced use cases, use transformation hooks to modify CSS before or after processing:
+To use your own `postcss.config.js`, simply call `postcssProcessorPlugin()` without arguments.
+
+You can also pass raw plugins or transformation hooks manually:
 
 ```typescript
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+import myPlugin from 'postcss-my-plugin';
 
 const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin({
-			// Define a filter for files to process (defaults to /\.css$/)
 			filter: /\.css$/,
-			// Provide a function to transform input before processing
-			transformInput: async (css) => `/* My Custom Header */\n${css}`,
-			// Provide a function to transform output after processing
-			transformOutput: async (css) => css.replace('blue', 'red'),
-			// Explicitly provide plugins (overrides defaults)
 			plugins: {
-				/* custom plugins */
+				'my-plugin': myPlugin(),
 			},
+			transformInput: async (css) => `/* Header */\n${css}`,
+			transformOutput: async (css) => css.replace('blue', 'red'),
 		}),
 	])
 	.build();
@@ -121,9 +85,9 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-## Standalone Usage
+## Standalone Processing
 
-You can use the underlying processor functions directly:
+You can bypass Ecopages entirely and use the processor utilities directly:
 
 ```typescript
 import { PostCssProcessor } from '@ecopages/postcss-processor';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/postcss-processor",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.20",
   "description": "Postcss processor, transform string or postcss file to css",
   "keywords": [
     "postcss",
@@ -17,17 +17,17 @@
     "directory": "packages/processors/postcss-processor"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-alpha.2",
-    "@ecopages/file-system": "0.2.0-alpha.2",
-    "@ecopages/logger": "latest",
+    "@ecopages/file-system": "0.2.0-alpha.20",
+    "@ecopages/logger": "^0.2.3",
     "autoprefixer": "^10.4.0",
     "browserslist": "^4.28.1",
-    "cssnano": "^6.0.0",
+    "cssnano": "^7.1.4",
     "postcss": "^8.4.32",
-    "postcss-import": "^15.0.0",
+    "postcss-import": "^16.1.1",
     "postcss-nested": "^7.0.2"
   },
   "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.20",
     "@tailwindcss/postcss": ">=4",
     "tailwindcss": ">=3"
   },

package/src/index.d.ts

@@ -1,2 +1,2 @@
-export * from './plugin';
-export * from './postcss-processor';
+export * from './plugin.js';
+export * from './postcss-processor.js';

package/src/index.js

@@ -1,2 +1,2 @@
-export * from "./plugin";
-export * from "./postcss-processor";
+export * from "./plugin.js";
+export * from "./postcss-processor.js";

package/src/plugin.d.ts

@@ -9,6 +9,15 @@ import type postcss from 'postcss';
  * Record of PostCSS plugins keyed by name
  */
 export type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
+/**
+ * Lazily creates PostCSS plugins.
+ *
+ * This is primarily used in development when a non-CSS file change forces the
+ * processor to rebuild tracked stylesheets. Some plugins, including Tailwind,
+ * keep internal caches in long-lived plugin instances, so recreating them is
+ * required to pick up newly discovered classes.
+ */
+export type PluginFactoryRecord = Record<string, () => postcss.AcceptedPlugin>;
 /**
  * Configuration for the PostCSS processor
  */
@@ -17,6 +26,13 @@ export interface PostCssProcessorPluginConfig {
      * Regex filter to match files to process
      */
     filter?: RegExp;
+    /**
+     * CSS entry files to rebuild when a non-CSS dependency changes.
+     *
+     * Use this when the processor watches template or script files that affect a
+     * known stylesheet entry, such as a Tailwind reference file.
+     */
+    dependencyEntryPaths?: string[];
     /**
      * Function to transform the contents of the file.
      * It can be handy to add a custom header or footer to the file.
@@ -38,6 +54,13 @@ export interface PostCssProcessorPluginConfig {
      * @default undefined (uses default plugins)
      */
     plugins?: PluginsRecord;
+    /**
+     * Factory functions for recreating stateful PostCSS plugins.
+     *
+     * When provided, Ecopages uses these factories to build a fresh plugin list
+     * for dependency-driven stylesheet rebuilds during development.
+     */
+    pluginFactories?: PluginFactoryRecord;
 }
 /**
  * PostCssProcessorPlugin
@@ -45,26 +68,78 @@ export interface PostCssProcessorPluginConfig {
  */
 export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
     static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>>;
+    private buildContributionsPrepared;
     private postcssPlugins;
+    private pluginFactories?;
     private readonly runtimeCssCache;
+    private readonly trackedCssFiles;
+    private watchQueue;
+    /**
+     * Maps an imported CSS file path → set of tracked CSS entry files that import it.
+     * Used to resolve which parent entry files need re-processing when a dependency changes.
+     */
+    private readonly cssDependencyMap;
     private getCssFilter;
     private resolveProcessedCssPath;
     private readProcessedCssFromDist;
     private persistProcessedCss;
     private prewarmRuntimeCssCache;
+    /**
+     * Regex to match CSS @import statements and extract the path.
+     * Handles: @import './foo.css'; @import "./foo.css"; @import url('./foo.css');
+     */
+    private static readonly CSS_IMPORT_REGEX;
+    /**
+     * Builds the CSS dependency map by scanning tracked CSS files for @import directives.
+     * Maps each imported file to the set of tracked entry files that import it (directly or transitively).
+     */
+    private buildCssDependencyMap;
+    /**
+     * Extracts resolved absolute paths of CSS files imported via @import in the given CSS content.
+     * Recursively follows imports to capture transitive dependencies.
+     * It skips bare module imports like @import 'tailwindcss'.
+     * It recursively follows imports to capture transitive dependencies.
+     */
+    private extractCssImports;
+    /**
+     * Resolves a changed CSS file to its parent entry file(s) if it is an @import dependency.
+     * Returns an empty array if the file is not an import dependency (i.e., it's an entry file itself).
+     */
+    private resolveEntryFiles;
     private transformCssSync;
     private transformCssAsync;
     matchesFileFilter(filepath: string): boolean;
+    private materializePluginFactories;
+    private refreshConfiguredPlugins;
+    private enqueueWatchTask;
+    private getTrackedCssFiles;
+    private getTrackedCssEntryFiles;
+    private getDependencyEntryFiles;
+    private handleDependencyChange;
     constructor(config?: Omit<ProcessorConfig<PostCssProcessorPluginConfig>, 'name' | 'description'>);
     /**
      * Handles CSS file changes during development.
-     * Processes the file and broadcasts a css-update event for hot reloading.
+     * If the file is an @import dependency, re-processes the parent entry file(s) instead.
+     * Broadcasts a css-update event for hot reloading.
      */
     private handleCssChange;
+    /**
+     * Processes a CSS file and broadcasts a css-update event.
+     * Skips broadcast if the processed output hasn't changed.
+     */
+    private processAndBroadcast;
     get buildPlugins(): EcoBuildPlugin[];
     get plugins(): EcoBuildPlugin[];
     /**
-     * Setup the PostCSS processor.
+     * Resolves the configured PostCSS plugin list before config build seals the
+     * app manifest.
+     *
+     * @remarks
+     * Runtime setup reuses this prepared list and only performs cache prewarming.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Prepares build contributions if not already done and prewarms the runtime CSS cache.
      */
     setup(): Promise<void>;
     /**