@mochi-css/config 3.0.0 → 3.1.0

package/README.md

@@ -38,7 +38,7 @@ All Mochi-CSS integrations automatically load this file - you don't need to pass
 Identity helper that provides full type inference for your config file.
 
 ```typescript
-function defineConfig(config: MochiConfig): MochiConfig
+function defineConfig(config: Partial<Config>): Partial<Config>
 ```
 
 ---
@@ -48,7 +48,7 @@ function defineConfig(config: MochiConfig): MochiConfig
 Finds and loads the nearest `mochi.config.*` file. Returns `{}` if no file is found.
 
 ```typescript
-async function loadConfig(cwd?: string): Promise<MochiConfig>
+async function loadConfig(cwd?: string): Promise<Partial<Config>>
 ```
 
 Searched file names (in order): `mochi.config.mts`, `mochi.config.cts`, `mochi.config.ts`, `mochi.config.mjs`, `mochi.config.cjs`, `mochi.config.js`.
@@ -62,14 +62,15 @@ Runs all `MochiPlugin.onConfigResolved` hooks in order.
 
 ```typescript
 async function resolveConfig(
-    fileConfig: MochiConfig,
-    inlineOpts?: MochiConfig,
-    defaults?: Partial<ResolvedConfig>,
-): Promise<ResolvedConfig>
+    fileConfig: Partial<Config>,
+    inlineOpts?: Partial<Config>,
+    defaults?: Partial<Config>,
+): Promise<Config>
 ```
 
 **Merge behaviour:**
-- Arrays (`roots`, `extractors`, `esbuildPlugins`): file config + inline options concatenated, falling back to defaults
+
+- Arrays (`roots`, `plugins`): file config + inline options concatenated, falling back to defaults
 - Scalar values (`splitCss`, `tmpDir`): inline options take precedence over file config, then defaults
 - Callbacks (`onDiagnostic`): both callbacks are called when both are provided
 
@@ -77,50 +78,60 @@ async function resolveConfig(
 
 ## Types
 
-### `MochiConfig`
-
-The user-facing config. All fields are optional.
-
-| Field            | Type               | Description                                               |
-|------------------|--------------------|-----------------------------------------------------------|
-| `roots`          | `RootEntry[]`      | Directories scanned for source files (default: `["src"]`) |
-| `extractors`     | `StyleExtractor[]` | Style extractors - merged with defaults from integrations |
-| `splitCss`  | `boolean`          | Emit per-source-file CSS instead of one global file       |
-| `onDiagnostic`   | `OnDiagnostic`     | Callback for warnings and non-fatal errors                |
-| `esbuildPlugins` | `EsbuildPlugin[]`  | esbuild plugins forwarded to the bundler                  |
-| `plugins`        | `MochiPlugin[]`    | Mochi plugins - run after config is resolved              |
-| `tmpDir`         | `string`           | Manifest/styles output directory                          |
+### `Config`
 
-### `ResolvedConfig`
+The config shape. All fields are optional in `defineConfig`; `resolveConfig` fills required fields from defaults.
 
-Same as `MochiConfig` but with required fields and no `plugins` key. Produced by `resolveConfig`.
+| Field          | Type            | Description                                                   |
+| -------------- | --------------- | ------------------------------------------------------------- |
+| `roots`        | `RootEntry[]`   | Directories scanned for source files (default: `["src"]`)     |
+| `splitCss`     | `boolean`       | Emit per-source-file CSS instead of one global file           |
+| `onDiagnostic` | `OnDiagnostic`  | Callback for warnings and non-fatal errors                    |
+| `plugins`      | `MochiPlugin[]` | Mochi plugins — register stages, transforms, and emit hooks   |
+| `tmpDir`       | `string`        | Manifest/styles output directory                              |
+| `debug`        | `boolean`       | Enable debug output                                           |
 
 ### `MochiPlugin`
 
-Hook interface for extending the resolved config.
+Hook interface for extending the build pipeline.
 
 ```typescript
 interface MochiPlugin {
     name: string
-    onConfigResolved?: (config: ResolvedConfig) => Promise<ResolvedConfig> | ResolvedConfig
+    // Called during config resolution — mutate or replace the config object.
+    onConfigResolved?(config: Config): Promise<Config> | Config
+    // Called after config is resolved — register stages, transforms, and emit hooks.
+    onLoad?(context: PluginContext): void
 }
 ```
 
+### `PluginContext`
+
+Passed to `onLoad`. Each field is a collector that plugins call `register()` on.
+
+| Field              | Purpose                                                           |
+|--------------------|-------------------------------------------------------------------|
+| `stages`           | Register analysis pipeline stages                                 |
+| `sourceTransforms` | Register `AstPostProcessor` hooks (run after analysis)            |
+| `emitHooks`        | Register `EmitHook` hooks (run after evaluation)                  |
+| `cleanup`          | Register cleanup functions called at the end of each build        |
+| `filePreProcess`   | Register source-level text transformations (used by Vite/Next)    |
+| `onDiagnostic`     | Diagnostics callback from the resolved config                     |
+
 ---
 
 ## Writing a Plugin
 
 ```typescript
 import type { MochiPlugin } from "@mochi-css/config"
-import { myExtractor } from "./myExtractor"
 
 export const myPlugin: MochiPlugin = {
     name: "my-plugin",
-    onConfigResolved(config) {
-        return {
-            ...config,
-            extractors: [...config.extractors, myExtractor],
-        }
+    onLoad(context) {
+        // Register an emit hook that writes a file after every build
+        context.emitHooks.register(async (_index, ctx) => {
+            ctx.emitChunk("my-output.txt", "hello from my-plugin")
+        })
     },
 }
 ```
@@ -134,3 +145,24 @@ export default defineConfig({
     plugins: [myPlugin],
 })
 ```
+
+---
+
+## `styledIdPlugin`
+
+A built-in plugin that injects stable `s-` class IDs into every `styled()` call matched by the given extractors. This keeps class names stable across incremental builds.
+
+```typescript
+import { styledIdPlugin } from "@mochi-css/config"
+import { myExtractor } from "./myExtractor"
+
+export default defineConfig({
+    plugins: [styledIdPlugin([myExtractor])],
+})
+```
+
+The plugin registers two hooks:
+- A `filePreProcess` transformation that inserts stable IDs into the raw source (used by Vite/Next `transform` hooks).
+- A `sourceTransforms` hook that injects the same IDs directly into the AST (used during CSS extraction).
+
+It is idempotent — calls that already carry an `s-` ID are skipped.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AstPostProcessor, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StyleExtractor, StyleExtractor as StyleExtractor$1 } from "@mochi-css/builder";
+import { AstPostProcessor, EmitHook, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StageDefinition, StyleExtractor } from "@mochi-css/builder";
 
 //#region src/merge.d.ts
 declare function mergeArrays<T>(a: T[] | undefined, b: T[] | undefined): T[] | undefined;
@@ -41,22 +41,54 @@ type FileTransformData = {
   filter?: string;
 };
 type FileTransformationHookProvider = TransformationHookProvider<string, [FileTransformOptions], FileTransformData>;
-interface AnalysisTransformHookProvider {
+interface SourceTransformHookProvider {
   register(hook: AstPostProcessor): void;
 }
-declare class AnalysisHookCollector implements AnalysisTransformHookProvider {
+interface StageHookProvider {
+  register(stage: StageDefinition<any[], any>): void;
+}
+interface EmitHookProvider {
+  register(hook: EmitHook): void;
+}
+interface CleanupHookProvider {
+  register(fn: () => void): void;
+}
+declare class SourceTransformCollector implements SourceTransformHookProvider {
   private readonly hooks;
   register(hook: AstPostProcessor): void;
-  getHooks(): AstPostProcessor[];
+  getAll(): AstPostProcessor[];
+}
+declare class StageCollector implements StageHookProvider {
+  private readonly stageList;
+  register(stage: StageDefinition<any[], any>): void;
+  getAll(): readonly StageDefinition<any[], any>[];
+}
+declare class EmitHookCollector implements EmitHookProvider {
+  private readonly hooks;
+  register(hook: EmitHook): void;
+  getAll(): EmitHook[];
+}
+declare class CleanupCollector implements CleanupHookProvider {
+  private readonly fns;
+  register(fn: () => void): void;
+  runAll(): void;
 }
 interface PluginContext {
-  readonly sourceTransform: FileTransformationHookProvider;
-  readonly analysisTransform: AnalysisTransformHookProvider;
+  readonly filePreProcess: FileTransformationHookProvider;
+  readonly sourceTransforms: SourceTransformHookProvider;
+  readonly stages: StageHookProvider;
+  readonly emitHooks: EmitHookProvider;
+  readonly cleanup: CleanupHookProvider;
+  readonly onDiagnostic: OnDiagnostic$1;
 }
 declare class FullContext implements PluginContext {
-  readonly sourceTransform: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
-  readonly analysisTransform: AnalysisHookCollector;
-  getAnalysisHooks(): AstPostProcessor[];
+  readonly filePreProcess: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
+  readonly sourceTransforms: SourceTransformCollector;
+  readonly stages: StageCollector;
+  readonly emitHooks: EmitHookCollector;
+  readonly cleanup: CleanupCollector;
+  readonly onDiagnostic: OnDiagnostic$1;
+  constructor(onDiagnostic: OnDiagnostic$1);
 }
 //#endregion
 //#region src/plugin/Plugin.d.ts
@@ -69,7 +101,6 @@ interface Plugin<Config$1 extends object> {
 //#region src/config/index.d.ts
 interface Config {
   roots: RootEntry$1[];
-  extractors: StyleExtractor$1[];
   splitCss: boolean;
   onDiagnostic?: OnDiagnostic$1;
   plugins: Plugin<Config>[];
@@ -83,11 +114,13 @@ declare function loadConfig(cwd?: string): Promise<Partial<Config>>;
 //#endregion
 //#region src/styledIdPlugin.d.ts
 /**
- * Returns a MochiPlugin that injects stable `s-` class IDs into every `styled()` call.
- * - Registers a `sourceTransform` for runtime source injection (Vite/Next `transform` hook).
- * - Registers an `analysisTransform` for CSS extraction via direct AST mutation.
+ * Returns a MochiPlugin that injects stable `s-` class IDs into every call expression
+ * matched by the given extractors.
+ * - Registers a `filePreProcess` transformation for runtime source injection (Vite/Next `transform` hook).
+ * - Registers a `sourceTransforms` hook for CSS extraction via direct AST mutation,
+ *   using data from the extractor pipeline stages (`extractedCallExpressions`).
  */
-declare function styledIdPlugin(): MochiPlugin;
+declare function styledIdPlugin(extractors: StyleExtractor[]): MochiPlugin;
 //#endregion
-export { type AnalysisTransformHookProvider, Config, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type StyleExtractor, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
+export { type CleanupHookProvider, Config, type EmitHookProvider, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type SourceTransformHookProvider, type StageHookProvider, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AstPostProcessor, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StyleExtractor, StyleExtractor as StyleExtractor$1 } from "@mochi-css/builder";
+import { AstPostProcessor, EmitHook, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StageDefinition, StyleExtractor } from "@mochi-css/builder";
 
 //#region src/merge.d.ts
 declare function mergeArrays<T>(a: T[] | undefined, b: T[] | undefined): T[] | undefined;
@@ -41,22 +41,54 @@ type FileTransformData = {
   filter?: string;
 };
 type FileTransformationHookProvider = TransformationHookProvider<string, [FileTransformOptions], FileTransformData>;
-interface AnalysisTransformHookProvider {
+interface SourceTransformHookProvider {
   register(hook: AstPostProcessor): void;
 }
-declare class AnalysisHookCollector implements AnalysisTransformHookProvider {
+interface StageHookProvider {
+  register(stage: StageDefinition<any[], any>): void;
+}
+interface EmitHookProvider {
+  register(hook: EmitHook): void;
+}
+interface CleanupHookProvider {
+  register(fn: () => void): void;
+}
+declare class SourceTransformCollector implements SourceTransformHookProvider {
   private readonly hooks;
   register(hook: AstPostProcessor): void;
-  getHooks(): AstPostProcessor[];
+  getAll(): AstPostProcessor[];
+}
+declare class StageCollector implements StageHookProvider {
+  private readonly stageList;
+  register(stage: StageDefinition<any[], any>): void;
+  getAll(): readonly StageDefinition<any[], any>[];
+}
+declare class EmitHookCollector implements EmitHookProvider {
+  private readonly hooks;
+  register(hook: EmitHook): void;
+  getAll(): EmitHook[];
+}
+declare class CleanupCollector implements CleanupHookProvider {
+  private readonly fns;
+  register(fn: () => void): void;
+  runAll(): void;
 }
 interface PluginContext {
-  readonly sourceTransform: FileTransformationHookProvider;
-  readonly analysisTransform: AnalysisTransformHookProvider;
+  readonly filePreProcess: FileTransformationHookProvider;
+  readonly sourceTransforms: SourceTransformHookProvider;
+  readonly stages: StageHookProvider;
+  readonly emitHooks: EmitHookProvider;
+  readonly cleanup: CleanupHookProvider;
+  readonly onDiagnostic: OnDiagnostic$1;
 }
 declare class FullContext implements PluginContext {
-  readonly sourceTransform: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
-  readonly analysisTransform: AnalysisHookCollector;
-  getAnalysisHooks(): AstPostProcessor[];
+  readonly filePreProcess: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
+  readonly sourceTransforms: SourceTransformCollector;
+  readonly stages: StageCollector;
+  readonly emitHooks: EmitHookCollector;
+  readonly cleanup: CleanupCollector;
+  readonly onDiagnostic: OnDiagnostic$1;
+  constructor(onDiagnostic: OnDiagnostic$1);
 }
 //#endregion
 //#region src/plugin/Plugin.d.ts
@@ -69,7 +101,6 @@ interface Plugin<Config$1 extends object> {
 //#region src/config/index.d.ts
 interface Config {
   roots: RootEntry$1[];
-  extractors: StyleExtractor$1[];
   splitCss: boolean;
   onDiagnostic?: OnDiagnostic$1;
   plugins: Plugin<Config>[];
@@ -83,11 +114,13 @@ declare function loadConfig(cwd?: string): Promise<Partial<Config>>;
 //#endregion
 //#region src/styledIdPlugin.d.ts
 /**
- * Returns a MochiPlugin that injects stable `s-` class IDs into every `styled()` call.
- * - Registers a `sourceTransform` for runtime source injection (Vite/Next `transform` hook).
- * - Registers an `analysisTransform` for CSS extraction via direct AST mutation.
+ * Returns a MochiPlugin that injects stable `s-` class IDs into every call expression
+ * matched by the given extractors.
+ * - Registers a `filePreProcess` transformation for runtime source injection (Vite/Next `transform` hook).
+ * - Registers a `sourceTransforms` hook for CSS extraction via direct AST mutation,
+ *   using data from the extractor pipeline stages (`extractedCallExpressions`).
  */
-declare function styledIdPlugin(): MochiPlugin;
+declare function styledIdPlugin(extractors: StyleExtractor[]): MochiPlugin;
 //#endregion
-export { type AnalysisTransformHookProvider, Config, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type StyleExtractor, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
+export { type CleanupHookProvider, Config, type EmitHookProvider, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type SourceTransformHookProvider, type StageHookProvider, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
 //# sourceMappingURL=index.d.ts.map