@animus-ui/next-plugin 0.1.1 → 0.1.3

package/dist/index.mjs

@@ -1,67 +1,161 @@
-import { a as getSharedEngine, c as resetAnalysisPromise, d as setSharedCss, f as setSharedEngine, g as __require, h as setSharedSystemProps, i as getSharedCss, l as setAnalysisPromise, m as setSharedExternalEntries, n as getAnalysisPromise, o as getSharedExternalDirs, p as setSharedExternalDirs, s as getSharedExternalEntries, t as engineApi, u as setManifestJson } from "./singleton-CmwFBCJ5.mjs";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { t as __require } from "./chunk-y_GBKt04.mjs";
+import { a as getSharedExternalDirs, c as setAnalysisPromise, d as setSharedEngine, f as setSharedExternalDirs, i as getSharedCss, l as setManifestJson, m as setSharedSystemProps, n as getAnalysisPromise, o as getSharedExternalEntries, p as setSharedExternalEntries, s as resetAnalysisPromise, t as engineApi, u as setSharedCss } from "./singleton-BKALu7Mk.mjs";
+import { DEFAULT_EXTENSIONS, assembleStylesheet, assertNoRetiredEngineSelection, buildPathAliasesJson, buildSystemPropsModule, clearEngineCache, collectExternalPackageSources, contentHash, discoverFiles, extractSystemFilePackages, formatRustTimingWaterfall, loadSystemConfig, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveLightningTargets, runProjectAnalysis, serializeStaticCss, toWatchKeys, unresolvableIncludesMessage } from "@animus-ui/extract/pipeline";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, watch, writeFileSync } from "fs";
 import { dirname, extname, join, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
-import { DEFAULT_EXTENSIONS, applyPrefix, applyUnitFallback, assembleStylesheet, extractSystemFilePackages, preprocessMdx } from "@animus-ui/extract/pipeline";
-import { createHash } from "crypto";
-//#region src/analyze-project-args.ts
-function buildAnalyzeProjectArgs(inputs, devMode) {
-	return [
-		inputs.filesJson,
-		inputs.scalesJson,
-		inputs.variableMapJson,
-		inputs.contextualVarsJson,
-		inputs.propConfigJson,
-		inputs.groupRegistryJson,
-		inputs.packageResolutionJson,
-		devMode,
-		inputs.emitterConfigJson,
-		inputs.selectorAliasesJson,
-		null,
-		inputs.globalStyleBlocksJson,
-		inputs.pathAliasesJson,
-		inputs.keyframesJson
-	];
-}
-function buildProductionAnalyzeProjectArgs(inputs) {
-	return buildAnalyzeProjectArgs(inputs, false);
-}
-function buildHmrAnalyzeProjectArgs(inputs) {
-	return buildAnalyzeProjectArgs(inputs, true);
+//#region src/resolve-packages.ts
+/**
+* Resolve external DS package specifiers to rootDir-relative entry paths.
+* Node-generic (no webpack APIs): Pass 1 walks the consumer's workspaces for
+* matching package names; Pass 2 falls back to `require.resolve`. Specifiers
+* that resolve nowhere are simply omitted (spec: silent skip).
+*/
+function resolvePackagesByName(rootDir, names) {
+	if (names.length === 0) return {};
+	const nameSet = new Set(names);
+	const resolved = /* @__PURE__ */ new Set();
+	const packageMap = {};
+	try {
+		const rootPkg = JSON.parse(readFileSync(join(rootDir, "package.json"), "utf-8"));
+		const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages ?? [];
+		for (const ws of workspaces) {
+			const wsDir = resolve(rootDir, ws);
+			if (!existsSync(wsDir)) continue;
+			try {
+				const pkg = JSON.parse(readFileSync(join(wsDir, "package.json"), "utf-8"));
+				const name = pkg.name || "";
+				if (nameSet.has(name)) {
+					const entryPath = resolve(wsDir, pkg.main || pkg.module || "index.ts");
+					if (existsSync(entryPath)) {
+						packageMap[name] = relative(rootDir, entryPath);
+						resolved.add(name);
+					}
+				}
+			} catch {}
+		}
+	} catch {}
+	for (const name of nameSet) {
+		if (resolved.has(name)) continue;
+		try {
+			packageMap[name] = relative(rootDir, __require.resolve(name, { paths: [rootDir] }));
+		} catch {}
+	}
+	return packageMap;
 }
 //#endregion
-//#region src/manifest-diagnostics.ts
-function surfaceManifestDiagnostics(manifest, warn) {
-	for (const diagnostic of manifest.diagnostics ?? []) {
-		if (diagnostic.kind !== "warn") continue;
-		warn(`⚠ ${diagnostic.file}: ${diagnostic.component}: ${diagnostic.message}`);
+//#region src/timing.ts
+/**
+* Verbose build-timing waterfall: JS phases, analysis sub-phases, and the
+* shared Rust phase table. `ANIMUS_TIMING_JSON=1` additionally dumps a
+* machine-readable merged record.
+*/
+function logBuildTimings(bt, rustTiming, log, verbose) {
+	if (!verbose) return;
+	const pad = (label, width) => label + " ".repeat(Math.max(0, width - label.length));
+	for (const [key, label] of [
+		["systemLoad", "system-load"],
+		["fileDiscovery", "file-discovery"],
+		["fileRead", "file-read+hash"],
+		["packageResolve", "pkg-resolve"],
+		["analysis", "analysis"]
+	]) {
+		const ms = bt[key] ?? 0;
+		if (ms === 0 && !Object.hasOwn(bt, key)) continue;
+		log(`  ${pad(label, 17)}${String(ms).padStart(5)}ms`);
+		if (key === "analysis") for (const [sk, sl] of [
+			["jsonSerialize", "json-serialize"],
+			["rustExtract", "rust-extract"],
+			["jsonParse", "json-parse"]
+		]) {
+			const sms = bt[sk] ?? 0;
+			log(`    ${pad(sl, 15)}${String(sms).padStart(5)}ms`);
+			if (sk === "rustExtract" && rustTiming) for (const line of formatRustTimingWaterfall(rustTiming, {
+				indent: "      ",
+				labelWidth: 13
+			})) log(line);
+		}
+	}
+	log(`  total             ${String(bt.total).padStart(5)}ms`);
+	if (process.env.ANIMUS_TIMING_JSON === "1") {
+		const merged = {};
+		for (const [k, v] of Object.entries(bt)) merged[`buildStart.${k}`] = v;
+		if (rustTiming) {
+			for (const [k, v] of Object.entries(rustTiming)) if (typeof v === "number") merged[`rust.${k}`] = v;
+		}
+		console.info(`[animus:timing] ${JSON.stringify(merged)}`);
 	}
 }
 //#endregion
-//#region src/plugin.ts
-const PLUGIN_NAME = "AnimusWebpackPlugin";
-var AnimusWebpackPlugin = class {
-	options;
+//#region src/extraction-session.ts
+/**
+* Module id the Rust emitter injects for the extracted stylesheet — also the
+* exact resolve.alias key with-animus registers for it, which the adapter's
+* alias harvesting must skip.
+*/
+const ANIMUS_CSS_MODULE_ID = ".animus/styles.css";
+/** Default path fragments excluded from source discovery (full + watch). */
+const DEFAULT_EXCLUDE = [
+	"node_modules",
+	"dist",
+	".test.",
+	".spec.",
+	".next",
+	".animus"
+];
+/**
+* Bundler-agnostic extraction pipeline: system loading, source discovery
+* and ingestion, external-package collection, analysis, stylesheet and
+* system-props emission, and watch-cycle diffing.
+*
+* The webpack adapter (plugin.ts) owns only bundler wiring: hook
+* registration, alias harvesting from the compiler config, in-memory asset
+* replacement, and translating watch events into `handleWatchUpdate`
+* change sets. Keeping this class free of webpack types is deliberate — a
+* future Turbopack integration must drive the same session from outside
+* the bundler (Turbopack has no compiler-hook surface), reusing everything
+* here unchanged.
+*
+* Outputs are published through the package singleton (shared CSS,
+* manifest, system props) and written to `.animus/` on disk.
+*/
+var ExtractionSession = class {
+	/** Set by the adapter before any pipeline run. */
 	rootDir = null;
-	configJson = "";
-	groupRegistryJson = "";
-	themeJson = "";
-	variableMapJson = "";
-	variableCss = "";
-	contextualVarsJson = null;
-	selectorAliasesJson = null;
-	globalCss = "";
-	globalStyleBlocksJson = null;
-	keyframesBlocksJson = null;
+	/** Serialized path aliases, harvested by the adapter from bundler config. */
 	pathAliasesJson = null;
+	/** When set (Turbopack orchestration), every analysis also persists
+	*  `.animus/analysis-inputs.json` so isolated loader workers can hydrate.
+	*  Webpack mode leaves this off — its loader shares the process. */
+	persistAnalysisInputs = false;
+	/** Emitter identity override for the system-props module id. Webpack mode
+	*  (null) injects the absolute `.animus/system-props.js` path, resolved by
+	*  NormalModuleReplacement; Turbopack rejects absolute-path imports, so
+	*  its driver sets the virtual id that `resolveAlias` maps to disk. */
+	systemPropsModuleId = null;
+	/** Absolute directory prefixes for external DS packages (loader allowlisting). */
+	externalPackageDirs = [];
+	/** External package specifier → absolute source entry path. */
+	externalSourceEntries = /* @__PURE__ */ new Map();
+	options;
+	staticCssJson;
+	system = null;
+	/** Full package-resolution map from the last full pipeline — replayed by
+	*  incremental passes (sourceEntries alone omits dist-resolved packages). */
+	lastPackageMap = {};
 	fileCache = /* @__PURE__ */ new Map();
+	systemDependencyKeys = /* @__PURE__ */ new Set();
+	/** Loader-reported dependency paths for bundler watch registration. */
+	systemDependencyPaths = [];
+	systemDependencyHashes = /* @__PURE__ */ new Map();
 	lastCssHash = null;
 	lastSystemPropsHash = null;
-	externalPackageDirs = [];
-	externalSourceEntries = /* @__PURE__ */ new Map();
+	lastManifestHash = null;
+	lastAnalysisInputsHash = null;
+	lcssTargets = null;
 	constructor(options) {
 		this.options = options;
-		setSharedEngine(options.engine ?? "v2");
+		this.staticCssJson = serializeStaticCss(options.staticCss);
 	}
 	get verbose() {
 		return this.options.verbose === true || process.env.ANIMUS_DEBUG === "1" || process.env.ANIMUS_DEBUG === "true";
@@ -78,176 +172,82 @@ var AnimusWebpackPlugin = class {
 	elapsed(t) {
 		return this.verbose ? Math.round(performance.now() - t) : 0;
 	}
-	logBuildTimings(bt, rustTiming) {
-		if (!this.verbose) return;
-		for (const [key, label] of [
-			["systemLoad", "system-load"],
-			["fileDiscovery", "file-discovery"],
-			["fileRead", "file-read+hash"],
-			["packageResolve", "pkg-resolve"],
-			["analysis", "analysis"]
-		]) {
-			const ms = bt[key] ?? 0;
-			if (ms === 0 && !Object.hasOwn(bt, key)) continue;
-			const pad = " ".repeat(Math.max(0, 17 - label.length));
-			this.log(`  ${label}${pad}${String(ms).padStart(5)}ms`);
-			if (key === "analysis") for (const [sk, sl] of [
-				["jsonSerialize", "json-serialize"],
-				["rustExtract", "rust-extract"],
-				["jsonParse", "json-parse"]
-			]) {
-				const sms = bt[sk] ?? 0;
-				const spad = " ".repeat(Math.max(0, 15 - sl.length));
-				this.log(`    ${sl}${spad}${String(sms).padStart(5)}ms`);
-				if (sk === "rustExtract" && rustTiming) for (const [rk, rl] of [
-					["parseAndWalk", "parse+walk"],
-					["importResolution", "imports"],
-					["extensionProvenance", "provenance"],
-					["topologicalSort", "topo-sort"],
-					["chainEvaluation", "chains"],
-					["jsxScanning", "jsx-scan"],
-					["systemPropAggregation", "sys-props"],
-					["usageLedger", "usage"],
-					["reconciliation", "reconcile"],
-					["cssGeneration", "css-gen"],
-					["manifestSerialization", "serialize"]
-				]) {
-					const rms = rustTiming[rk] ?? 0;
-					const rpad = " ".repeat(Math.max(0, 13 - rl.length));
-					const rextra = rk === "parseAndWalk" ? `  (${rustTiming.fileCount ?? 0} files, ${rustTiming.cacheHits ?? 0} cached)` : "";
-					this.log(`      ${rl}${rpad}${String(rms).padStart(5)}ms${rextra}`);
-				}
-			}
-		}
-		this.log(`  total             ${String(bt.total).padStart(5)}ms`);
-		if (process.env.ANIMUS_TIMING_JSON === "1") {
-			const merged = {};
-			for (const [k, v] of Object.entries(bt)) merged[`buildStart.${k}`] = v;
-			if (rustTiming) {
-				for (const [k, v] of Object.entries(rustTiming)) if (typeof v === "number") merged[`rust.${k}`] = v;
-			}
-			console.info(`[animus:timing] ${JSON.stringify(merged)}`);
-		}
-	}
-	initialized = false;
-	/** Extract path aliases from webpack's resolve.alias config. */
-	extractAliases(compiler) {
-		const rootDir = compiler.context;
-		const rawAlias = compiler.options?.resolve?.alias;
-		if (!rawAlias || typeof rawAlias !== "object") return;
-		const entries = [];
-		for (const [key, value] of Object.entries(rawAlias)) {
-			const target = Array.isArray(value) ? value[0] : value;
-			if (typeof target !== "string") continue;
-			if (key.includes(".animus")) continue;
-			const replacement = target.startsWith(rootDir) ? target.slice(rootDir.length + 1) : target;
-			if (/\.\w+$/.test(replacement)) entries.push({
-				pattern: key,
-				replacement,
-				type: "exact"
-			});
-			else entries.push({
-				pattern: key.endsWith("/") ? key : key + "/",
-				replacement: replacement.endsWith("/") ? replacement : replacement + "/",
-				type: "prefix"
-			});
-		}
-		entries.sort((a, b) => b.pattern.length - a.pattern.length);
-		if (entries.length > 0) this.pathAliasesJson = JSON.stringify({ aliases: entries });
-	}
-	apply(compiler) {
-		if (compiler.options?.name === "edge-server") return;
-		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
-			const stage = compiler.webpack?.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL ?? -2e3;
-			const RawSource = compiler.webpack?.sources.RawSource;
-			compilation.hooks.processAssets.tap({
-				name: PLUGIN_NAME,
-				stage
-			}, () => {
-				const css = getSharedCss();
-				if (!css || !RawSource) return;
-				const cssPath = join(this.rootDir || compiler.context, ".animus", "styles.css");
-				if (compilation.getAsset(cssPath)) {
-					compilation.updateAsset(cssPath, new RawSource(css));
-					return;
-				}
-				const relPath = ".animus/styles.css";
-				if (compilation.getAsset(relPath)) compilation.updateAsset(relPath, new RawSource(css));
-			});
-		});
-		compiler.hooks.run.tapPromise(PLUGIN_NAME, async (_compiler) => {
-			this.rootDir = _compiler.context;
-			this.extractAliases(_compiler);
-			const existing = getAnalysisPromise();
-			if (existing) {
-				await existing;
-				return;
-			}
-			const promise = this.runFullPipeline();
-			setAnalysisPromise(promise);
-			await promise;
-		});
-		compiler.hooks.watchRun.tapPromise(PLUGIN_NAME, async (_compiler) => {
-			this.rootDir = _compiler.context;
-			this.extractAliases(_compiler);
-			if (!this.initialized) {
-				const existing = getAnalysisPromise();
-				if (existing) {
-					await existing;
-					this.initialized = true;
-					return;
-				}
-				const promise = this.runFullPipeline();
-				setAnalysisPromise(promise);
-				await promise;
-				this.initialized = true;
-				return;
-			}
-			await this.handleWatchUpdate();
-		});
+	/** Resolve the scan configuration from options — the single source of the
+	*  exclude/extension policy shared by the full and incremental pipelines. */
+	resolveScanConfig() {
+		const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
+		return {
+			excludePatterns: this.options.exclude ?? DEFAULT_EXCLUDE,
+			extensionsSet,
+			shouldHandleMdx: extensionsSet.has(".mdx")
+		};
 	}
-	async handleWatchUpdate() {
-		if (this.configJson === "") return;
+	/**
+	* Incremental watch pass: geological reset when the system file changed,
+	* otherwise content-hash diffing restricted to the watcher's change sets
+	* (falling back to a full discovery walk when no sets are provided).
+	*/
+	async handleWatchUpdate(changes) {
+		if (!this.system) return;
 		const rootDir = this.rootDir;
-		const resolvedSystemPath = resolve(rootDir, this.options.system);
 		try {
-			const systemSource = readFileSync(resolvedSystemPath, "utf-8");
-			const systemRelPath = relative(rootDir, resolvedSystemPath);
-			const cached = this.fileCache.get(systemRelPath);
-			const currentHash = createHash("md5").update(systemSource).digest("hex");
-			if (cached && cached.hash !== currentHash) {
+			let systemHit;
+			if (!changes.modifiedFiles && !changes.removedFiles) for (const [dep, hash] of this.systemDependencyHashes) {
+				let current = "";
+				try {
+					current = contentHash(readFileSync(dep, "utf-8"));
+				} catch {}
+				if (current !== hash) {
+					systemHit = dep;
+					break;
+				}
+			}
+			else systemHit = [...changes.modifiedFiles ?? [], ...changes.removedFiles ?? []].find((path) => toWatchKeys(path).some((key) => this.systemDependencyKeys.has(key)));
+			if (systemHit) {
+				this.log(`geological reset: system dependency changed (${relative(rootDir, systemHit)})`);
 				this.resetForHmr();
-				this.initialized = false;
 				const promise = this.runFullPipeline();
 				setAnalysisPromise(promise);
 				await promise;
-				this.initialized = true;
 				return;
 			}
-		} catch {}
-		const excludePatterns = this.options.exclude ?? [
-			"node_modules",
-			"dist",
-			".test.",
-			".spec.",
-			".next",
-			".animus"
-		];
-		const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
-		const shouldHandleMdx = extensionsSet.has(".mdx");
-		const files = this.discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet);
+		} catch (err) {
+			this.warn(`HMR geological-reset check failed: ${String(err)}`);
+		}
+		const { excludePatterns, extensionsSet, shouldHandleMdx } = this.resolveScanConfig();
+		let removedAny = false;
+		if (changes.removedFiles) for (const removedPath of changes.removedFiles) {
+			const rel = relative(rootDir, removedPath);
+			if (this.fileCache.delete(rel) || this.fileCache.delete(rel + ".tsx")) removedAny = true;
+		}
+		let files;
+		if (changes.modifiedFiles) {
+			files = [];
+			for (const modifiedPath of changes.modifiedFiles) {
+				if (!extensionsSet.has(extname(modifiedPath))) continue;
+				const rel = relative(rootDir, modifiedPath);
+				if (rel.startsWith("..")) continue;
+				if (excludePatterns.some((pattern) => modifiedPath.includes(pattern) || rel.includes(pattern))) continue;
+				files.push(modifiedPath);
+			}
+		} else files = discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet);
 		const changedPaths = [];
 		for (const filePath of files) {
 			let relPath = relative(rootDir, filePath);
-			let source = readFileSync(filePath, "utf-8");
+			let source;
+			try {
+				source = readFileSync(filePath, "utf-8");
+			} catch {
+				continue;
+			}
 			if (shouldHandleMdx && extname(filePath) === ".mdx") {
-				const result = await preprocessMdx(source, relPath);
-				if (result.kind !== "ok") continue;
-				source = result.source;
-				relPath = relPath + ".tsx";
+				const processed = await this.preprocessMdxEntry(source, relPath, { warn: false });
+				if (!processed) continue;
+				source = processed.source;
+				relPath = processed.relPath;
 			}
 			const cached = this.fileCache.get(relPath);
-			const hash = createHash("md5").update(source).digest("hex");
+			const hash = contentHash(source);
 			if (!cached || cached.hash !== hash) {
 				changedPaths.push(relPath);
 				this.fileCache.set(relPath, {
@@ -256,39 +256,74 @@ var AnimusWebpackPlugin = class {
 				});
 			}
 		}
-		if (changedPaths.length > 0) {
-			const fileEntries = this.buildFileEntriesFromCache(changedPaths);
+		if (changedPaths.length > 0 || removedAny) {
+			const fileEntries = this.buildFileEntriesFromCache();
 			resetAnalysisPromise();
 			const promise = this.runIncrementalPipeline(fileEntries);
 			setAnalysisPromise(promise);
 			await promise;
 		}
 	}
+	/**
+	* Preprocess one `.mdx` entry into scanner-consumable tsx. Returns the
+	* rewritten source plus the `relPath + '.tsx'` path on success, or null
+	* when the file must be skipped.
+	*
+	* `warn: false` (incremental watch pass) skips silently — the full
+	* pipeline already surfaced the warning. `warn: true` (full pipeline)
+	* warns ONCE for a missing @mdx-js/mdx dependency via the shared
+	* `missingDepFlag` holder, and every time for a preprocessing error.
+	*/
+	async preprocessMdxEntry(source, relPath, opts) {
+		const result = await preprocessMdx(source, relPath);
+		if (result.kind === "missing-dep") {
+			if (opts.warn && opts.missingDepFlag && !opts.missingDepFlag.warned) {
+				console.warn("[animus] ⚠ .mdx in extensions but @mdx-js/mdx not installed; MDX files skipped");
+				opts.missingDepFlag.warned = true;
+			}
+			return null;
+		}
+		if (result.kind === "error") {
+			if (opts.warn) console.warn(`[animus] ⚠ MDX preprocessing failed for ${relPath}: ${result.error}`);
+			return null;
+		}
+		return {
+			source: result.source,
+			relPath: relPath + ".tsx"
+		};
+	}
 	async runFullPipeline() {
 		const pipelineStart = this.now();
 		const bt = {};
-		try {
-			const { clearAnalysisCache } = engineApi();
-			clearAnalysisCache();
-		} catch {}
+		clearEngineCache(engineApi);
 		const rootDir = this.rootDir;
 		const resolvedSystemPath = resolve(rootDir, this.options.system);
 		let t = this.now();
-		this.loadSystem(rootDir, resolvedSystemPath);
+		this.system = loadSystemConfig(engineApi, {
+			systemPath: resolvedSystemPath,
+			rootDir,
+			prefix: this.options.prefix
+		});
+		{
+			const deps = this.system.dependencies ?? [];
+			const keys = /* @__PURE__ */ new Set();
+			for (const key of toWatchKeys(resolvedSystemPath)) keys.add(key);
+			for (const dep of deps) for (const key of toWatchKeys(dep)) keys.add(key);
+			this.systemDependencyKeys = keys;
+			this.systemDependencyPaths = deps;
+			const hashes = /* @__PURE__ */ new Map();
+			for (const dep of deps.length > 0 ? deps : [resolvedSystemPath]) try {
+				hashes.set(dep, contentHash(readFileSync(dep, "utf-8")));
+			} catch {
+				hashes.set(dep, "");
+			}
+			this.systemDependencyHashes = hashes;
+		}
 		bt.systemLoad = this.elapsed(t);
 		t = this.now();
-		const excludePatterns = this.options.exclude ?? [
-			"node_modules",
-			"dist",
-			".test.",
-			".spec.",
-			".next",
-			".animus"
-		];
-		const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
-		const shouldHandleMdx = extensionsSet.has(".mdx");
-		let mdxMissingDepWarned = false;
-		const files = this.discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet);
+		const { excludePatterns, extensionsSet, shouldHandleMdx } = this.resolveScanConfig();
+		const missingDepFlag = { warned: false };
+		const files = discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet);
 		bt.fileDiscovery = this.elapsed(t);
 		t = this.now();
 		const fileEntries = [];
@@ -296,22 +331,15 @@ var AnimusWebpackPlugin = class {
 			let source = readFileSync(filePath, "utf-8");
 			let relPath = relative(rootDir, filePath);
 			if (shouldHandleMdx && extname(filePath) === ".mdx") {
-				const result = await preprocessMdx(source, relPath);
-				if (result.kind === "missing-dep") {
-					if (!mdxMissingDepWarned) {
-						console.warn("[animus] ⚠ .mdx in extensions but @mdx-js/mdx not installed; MDX files skipped");
-						mdxMissingDepWarned = true;
-					}
-					continue;
-				}
-				if (result.kind === "error") {
-					console.warn(`[animus] ⚠ MDX preprocessing failed for ${relPath}: ${result.error}`);
-					continue;
-				}
-				source = result.source;
-				relPath = relPath + ".tsx";
+				const processed = await this.preprocessMdxEntry(source, relPath, {
+					warn: true,
+					missingDepFlag
+				});
+				if (!processed) continue;
+				source = processed.source;
+				relPath = processed.relPath;
 			}
-			const hash = createHash("md5").update(source).digest("hex");
+			const hash = contentHash(source);
 			this.fileCache.set(relPath, {
 				hash,
 				source
@@ -326,216 +354,51 @@ var AnimusWebpackPlugin = class {
 		bt.fileCount = fileEntries.length;
 		t = this.now();
 		const packageNames = extractSystemFilePackages(resolvedSystemPath);
-		const packageMap = this.resolvePackagesByName(rootDir, packageNames);
-		const excludePatternsForPkgs = [
-			"dist",
-			".test.",
-			".spec."
-		];
-		const collectedPkgDirs = [];
-		this.externalSourceEntries.clear();
-		for (const [specifier, entryRelPath] of Object.entries(packageMap)) {
-			const absEntry = resolve(rootDir, entryRelPath);
-			let pkgRoot = dirname(absEntry);
-			while (pkgRoot !== dirname(pkgRoot) && !existsSync(join(pkgRoot, "package.json"))) pkgRoot = dirname(pkgRoot);
-			const srcDir = join(pkgRoot, "src");
-			if (existsSync(srcDir)) {
-				collectedPkgDirs.push(srcDir);
-				const srcEntry = join(srcDir, "index.ts");
-				if (existsSync(srcEntry)) {
-					packageMap[specifier] = relative(rootDir, srcEntry);
-					this.externalSourceEntries.set(specifier, srcEntry);
-				}
-				const pkgFiles = this.discoverFiles(srcDir, rootDir, excludePatternsForPkgs, extensionsSet);
-				for (const pkgFile of pkgFiles) {
-					let pkgRelPath = relative(rootDir, pkgFile);
-					if (!fileEntries.some((e) => e.path === pkgRelPath)) try {
-						let pkgSource = readFileSync(pkgFile, "utf-8");
-						if (shouldHandleMdx && extname(pkgFile) === ".mdx") {
-							const result = await preprocessMdx(pkgSource, pkgRelPath);
-							if (result.kind === "missing-dep") {
-								if (!mdxMissingDepWarned) {
-									console.warn("[animus] ⚠ .mdx in extensions but @mdx-js/mdx not installed; MDX files skipped");
-									mdxMissingDepWarned = true;
-								}
-								continue;
-							}
-							if (result.kind === "error") {
-								console.warn(`[animus] ⚠ MDX preprocessing failed for ${pkgRelPath}: ${result.error}`);
-								continue;
-							}
-							pkgSource = result.source;
-							pkgRelPath = pkgRelPath + ".tsx";
-						}
-						const pkgHash = createHash("md5").update(pkgSource).digest("hex");
-						this.fileCache.set(pkgRelPath, {
-							hash: pkgHash,
-							source: pkgSource
-						});
-						fileEntries.push({
-							path: pkgRelPath,
-							source: pkgSource,
-							hash: pkgHash
-						});
-					} catch {}
-				}
-			} else collectedPkgDirs.push(dirname(absEntry));
-		}
-		this.externalPackageDirs = collectedPkgDirs;
-		setSharedExternalDirs(collectedPkgDirs);
-		setSharedExternalEntries(this.externalSourceEntries);
-		bt.packageResolve = this.elapsed(t);
-		const { analyzeProject } = engineApi();
-		const animusDirPath = join(rootDir, ".animus");
-		const emitterConfig = JSON.stringify({
-			runtime_import: "@animus-ui/system/runtime",
-			css_module_id: ".animus/styles.css",
-			system_props_module_id: join(animusDirPath, "system-props.js")
-		});
-		t = this.now();
-		const fileEntriesJson = JSON.stringify(fileEntries);
-		const packageMapJson = JSON.stringify(packageMap);
-		bt.jsonSerialize = this.elapsed(t);
-		t = this.now();
-		const manifestJson = analyzeProject(...buildProductionAnalyzeProjectArgs({
-			filesJson: fileEntriesJson,
-			scalesJson: this.themeJson,
-			variableMapJson: this.variableMapJson,
-			contextualVarsJson: this.contextualVarsJson || null,
-			propConfigJson: this.configJson,
-			groupRegistryJson: this.groupRegistryJson,
-			packageResolutionJson: packageMapJson,
-			emitterConfigJson: emitterConfig,
-			selectorAliasesJson: this.selectorAliasesJson,
-			globalStyleBlocksJson: this.globalStyleBlocksJson,
-			pathAliasesJson: this.pathAliasesJson,
-			keyframesJson: this.keyframesBlocksJson
-		}));
-		bt.rustExtract = this.elapsed(t);
-		t = this.now();
-		const manifest = JSON.parse(manifestJson);
-		surfaceManifestDiagnostics(manifest, (message) => this.warn(message));
-		bt.jsonParse = this.elapsed(t);
-		bt.analysis = (bt.jsonSerialize ?? 0) + (bt.rustExtract ?? 0) + (bt.jsonParse ?? 0);
-		if (manifest?.report) this.log(`Extracted ${manifest.report.components_extracted ?? "?"}/${manifest.report.components_total ?? "?"} components (${bt.analysis}ms)`);
-		this.globalCss = manifest?.sheets?.global || "";
-		let componentCss = manifest?.css || "";
-		componentCss = applyUnitFallback(componentCss);
-		const { declaration, variables, body } = assembleStylesheet({
-			layers: this.options.layers,
-			variableCss: this.variableCss,
-			globalCss: this.globalCss,
-			componentCss,
-			split: true
+		const preResolved = resolvePackagesByName(rootDir, packageNames);
+		const collected = await collectExternalPackageSources({
+			specifiers: packageNames,
+			resolveSpecifier: (name) => preResolved[name] ? resolve(rootDir, preResolved[name]) : null,
+			rootDir,
+			extensionsSet,
+			hasEntry: (relPath) => fileEntries.some((e) => e.path === relPath),
+			preprocessFile: async (source, relPath, absPath) => {
+				if (shouldHandleMdx && extname(absPath) === ".mdx") return this.preprocessMdxEntry(source, relPath, {
+					warn: true,
+					missingDepFlag
+				});
+				return {
+					source,
+					relPath
+				};
+			},
+			onUnreadable: (relPath, err) => this.warn(`skipped unreadable package file ${relPath}: ${String(err)}`)
 		});
-		const fullCss = [
-			declaration,
-			variables,
-			body
-		].filter(Boolean).join("\n");
-		setSharedCss(fullCss);
-		const cssHash = createHash("md5").update(fullCss).digest("hex");
-		if (cssHash !== this.lastCssHash) {
-			const animusDir = join(rootDir, ".animus");
-			if (!existsSync(animusDir)) mkdirSync(animusDir, { recursive: true });
-			writeFileSync(join(animusDir, "styles.css"), fullCss);
-			this.lastCssHash = cssHash;
+		for (const record of collected.outcomes) if (record.outcome === "empty") this.warn(`include '${record.specifier}' resolved but discovered no component sources`);
+		const unresolvableMessage = unresolvableIncludesMessage(collected.outcomes);
+		if (unresolvableMessage !== null) {
+			if (this.options.strict) throw new Error(unresolvableMessage);
+			this.warn(unresolvableMessage);
 		}
-		const systemPropMap = JSON.stringify(manifest?.system_prop_map ?? {});
-		const dynamicProps = manifest?.dynamic_props ?? {};
-		const dynamicPropConfig = {};
-		for (const [propName, meta] of Object.entries(dynamicProps)) dynamicPropConfig[propName] = {
-			varName: meta.var_name,
-			slotClass: meta.slot_class,
-			...meta.transform_name ? { transformName: meta.transform_name } : {},
-			...meta.scale_values && Object.keys(meta.scale_values).length > 0 ? { scaleValues: meta.scale_values } : {}
-		};
-		const transformsSource = "{}";
-		const animusDir = join(rootDir, ".animus");
-		if (!existsSync(animusDir)) mkdirSync(animusDir, { recursive: true });
-		const systemPropsContent = `export const systemPropMap = ${systemPropMap};\nexport const systemPropGroups = ${this.groupRegistryJson};\nexport const dynamicPropConfig = ${JSON.stringify(dynamicPropConfig)};\nexport const transforms = ${transformsSource};\n`;
-		setSharedSystemProps(systemPropsContent);
-		writeFileSync(join(animusDir, "system-props.js"), systemPropsContent);
-		setManifestJson(manifestJson);
-		bt.total = this.elapsed(pipelineStart);
-		this.logBuildTimings(bt, manifest?.timing);
-	}
-	loadSystem(rootDir, systemPath) {
-		const { loadSystemModule } = engineApi();
-		const config = loadSystemModule(systemPath, rootDir);
-		this.configJson = config.propConfig;
-		this.groupRegistryJson = config.groupRegistry;
-		this.themeJson = config.scalesJson;
-		this.variableMapJson = config.variableMapJson;
-		this.variableCss = config.variableCss;
-		this.contextualVarsJson = config.contextualVarsJson;
-		this.selectorAliasesJson = config.selectorAliases || null;
-		if (this.options.prefix) {
-			const prefixed = applyPrefix(this.options.prefix, this.variableMapJson, this.variableCss, this.themeJson, this.contextualVarsJson || void 0);
-			this.variableMapJson = prefixed.variableMapJson;
-			this.variableCss = prefixed.variableCss;
-			if (prefixed.themeJson) this.themeJson = prefixed.themeJson;
-			if (prefixed.contextualVarsJson) this.contextualVarsJson = prefixed.contextualVarsJson;
-		}
-		this.globalStyleBlocksJson = config.globalStyleBlocks || null;
-		this.keyframesBlocksJson = config.keyframesBlocks || null;
-	}
-	discoverFiles(dir, rootDir, excludePatterns, extensionsSet) {
-		const results = [];
-		const walk = (currentDir) => {
-			let entries;
-			try {
-				entries = readdirSync(currentDir);
-			} catch {
-				return;
-			}
-			for (const entry of entries) {
-				const fullPath = join(currentDir, entry);
-				const relPath = relative(rootDir, fullPath);
-				if (excludePatterns.some((p) => relPath.includes(p))) continue;
-				let stat;
-				try {
-					stat = statSync(fullPath);
-				} catch {
-					continue;
-				}
-				if (stat.isDirectory()) walk(fullPath);
-				else if (extensionsSet.has(extname(entry))) results.push(fullPath);
-			}
-		};
-		walk(dir);
-		return results;
-	}
-	resolvePackagesByName(rootDir, names) {
-		if (names.length === 0) return {};
-		const nameSet = new Set(names);
-		const resolved = /* @__PURE__ */ new Set();
-		const packageMap = {};
-		try {
-			const workspaces = JSON.parse(readFileSync(join(rootDir, "package.json"), "utf-8")).workspaces || [];
-			for (const ws of workspaces) {
-				const wsDir = resolve(rootDir, ws);
-				if (!existsSync(wsDir)) continue;
-				try {
-					const pkg = JSON.parse(readFileSync(join(wsDir, "package.json"), "utf-8"));
-					const name = pkg.name || "";
-					if (nameSet.has(name)) {
-						const entryPath = resolve(wsDir, pkg.main || pkg.module || "index.ts");
-						if (existsSync(entryPath)) {
-							packageMap[name] = relative(rootDir, entryPath);
-							resolved.add(name);
-						}
-					}
-				} catch {}
-			}
-		} catch {}
-		for (const name of nameSet) {
-			if (resolved.has(name)) continue;
-			try {
-				packageMap[name] = relative(rootDir, __require.resolve(name, { paths: [rootDir] }));
-			} catch {}
+		const packageMap = collected.packageMap;
+		this.lastPackageMap = packageMap;
+		this.externalSourceEntries = collected.sourceEntries;
+		for (const entry of collected.entries) {
+			const hash = contentHash(entry.source);
+			this.fileCache.set(entry.path, {
+				hash,
+				source: entry.source
+			});
+			fileEntries.push({
+				path: entry.path,
+				source: entry.source,
+				hash
+			});
 		}
-		return packageMap;
+		this.externalPackageDirs = collected.packageDirs;
+		setSharedExternalDirs(collected.packageDirs);
+		setSharedExternalEntries(collected.sourceEntries);
+		bt.packageResolve = this.elapsed(t);
+		await this.analyzeAndEmit(fileEntries, packageMap, false, bt, pipelineStart);
 	}
 	/**
 	* Reset analysis state for HMR geological reset.
@@ -544,22 +407,21 @@ var AnimusWebpackPlugin = class {
 		resetAnalysisPromise();
 		this.lastCssHash = null;
 		this.lastSystemPropsHash = null;
-		try {
-			const { clearAnalysisCache } = engineApi();
-			clearAnalysisCache();
-		} catch {}
+		this.lastManifestHash = null;
+		this.lastAnalysisInputsHash = null;
+		clearEngineCache(engineApi);
 	}
 	/**
-	* Build cache-aware file entries: full source for changed files,
-	* empty source + hash for unchanged (Rust cache-hit path skips these).
+	* Build file entries from cache: every cached file rides with full source.
+	* The v2 engine has NO Rust-side cache (extract-v2-spine DEF-7: uncached
+	* re-analysis beats a cache-hit path), so it must always receive full sources
+	* (openspec: retire-extract-v1 removed the v1 empty-source cache contract).
 	*/
-	buildFileEntriesFromCache(changedPaths) {
-		const changedSet = new Set(changedPaths);
-		const fullSources = getSharedEngine() === "v2";
+	buildFileEntriesFromCache() {
 		const entries = [];
 		for (const [path, { hash, source }] of this.fileCache) entries.push({
 			path,
-			source: fullSources || changedSet.has(path) ? source : "",
+			source,
 			hash
 		});
 		return entries;
@@ -569,88 +431,238 @@ var AnimusWebpackPlugin = class {
 	* Reuses system config from the last full pipeline run.
 	*/
 	async runIncrementalPipeline(fileEntries) {
-		const rootDir = this.rootDir;
 		const bt = {};
 		const pipelineStart = this.now();
-		const { analyzeProject } = engineApi();
-		const animusDirPath = join(rootDir, ".animus");
-		const emitterConfig = JSON.stringify({
-			runtime_import: "@animus-ui/system/runtime",
-			css_module_id: ".animus/styles.css",
-			system_props_module_id: join(animusDirPath, "system-props.js")
-		});
-		const packageMapJson = JSON.stringify(Object.fromEntries(Array.from(this.externalSourceEntries).map(([spec, entry]) => [spec, relative(rootDir, entry)])));
-		let t = this.now();
-		const fileEntriesJson = JSON.stringify(fileEntries);
-		bt.jsonSerialize = this.elapsed(t);
-		t = this.now();
-		const manifestJson = analyzeProject(...buildHmrAnalyzeProjectArgs({
-			filesJson: fileEntriesJson,
-			scalesJson: this.themeJson,
-			variableMapJson: this.variableMapJson,
-			contextualVarsJson: this.contextualVarsJson || null,
-			propConfigJson: this.configJson,
-			groupRegistryJson: this.groupRegistryJson,
-			packageResolutionJson: packageMapJson,
-			emitterConfigJson: emitterConfig,
-			selectorAliasesJson: this.selectorAliasesJson,
-			globalStyleBlocksJson: this.globalStyleBlocksJson,
+		await this.analyzeAndEmit(fileEntries, this.lastPackageMap, true, bt, pipelineStart);
+	}
+	/**
+	* Shared analysis + emit core for both pipelines — the single call site
+	* that routes every manifest through the shared `runProjectAnalysis`,
+	* reachable from both runFullPipeline (production) and
+	* runIncrementalPipeline (HMR).
+	*
+	* Owns diagnostic surfacing, CSS assembly + styles.css write guard,
+	* system-props module emit, and the timing log. The `devMode` flag is the
+	* ONLY behavioral fork:
+	*
+	* - `false` (production): computes bt.analysis + logs the extraction
+	*   report, and writes system-props.js UNCONDITIONALLY (no
+	*   lastSystemPropsHash guard).
+	* - `true` (HMR): skips the report log, and guards the system-props.js
+	*   write by lastSystemPropsHash.
+	*
+	* The styles.css write guard (lastCssHash) is identical on both paths.
+	*/
+	async analyzeAndEmit(fileEntries, packageMap, devMode, bt, pipelineStart) {
+		const system = this.system;
+		const result = runProjectAnalysis(engineApi, {
+			fileEntries,
+			packageMap,
+			system,
+			emitter: {
+				runtimeImport: "@animus-ui/system/runtime",
+				cssModuleId: ANIMUS_CSS_MODULE_ID,
+				systemPropsModuleId: this.systemPropsModuleId ?? join(this.rootDir, ".animus", "system-props.js")
+			},
 			pathAliasesJson: this.pathAliasesJson,
-			keyframesJson: this.keyframesBlocksJson
-		}));
-		bt.rustExtract = this.elapsed(t);
-		t = this.now();
-		const manifest = JSON.parse(manifestJson);
-		surfaceManifestDiagnostics(manifest, (message) => this.warn(message));
-		bt.jsonParse = this.elapsed(t);
-		this.globalCss = manifest?.sheets?.global || "";
-		let componentCss = manifest?.css || "";
-		componentCss = applyUnitFallback(componentCss);
-		const { declaration: hmrDecl, variables: hmrVars, body: hmrBody } = assembleStylesheet({
+			staticCssJson: this.staticCssJson,
+			devMode,
+			warn: (message) => this.warn(message)
+		});
+		bt.jsonSerialize = result.timings.serializeMs;
+		bt.rustExtract = result.timings.extractMs;
+		bt.jsonParse = result.timings.parseMs;
+		const manifest = result.manifest;
+		if (!devMode) {
+			bt.analysis = (bt.jsonSerialize ?? 0) + (bt.rustExtract ?? 0) + (bt.jsonParse ?? 0);
+			if (manifest?.report) this.log(`Extracted ${manifest.report.components_extracted ?? "?"}/${manifest.report.components_total ?? "?"} components (${bt.analysis}ms)`);
+		}
+		const { declaration, variables, body } = assembleStylesheet({
 			layers: this.options.layers,
-			variableCss: this.variableCss,
-			globalCss: this.globalCss,
-			componentCss,
+			variableCss: system.variableCss,
+			globalCss: result.globalCss,
+			componentCss: result.componentCss,
 			split: true
 		});
+		if (this.lcssTargets === null) this.lcssTargets = resolveLightningTargets(this.options.targets, this.rootDir);
 		const fullCss = [
-			hmrDecl,
-			hmrVars,
-			hmrBody
+			declaration,
+			variables,
+			postProcessCss(body, {
+				minify: this.options.minify ?? process.env.NODE_ENV === "production",
+				targets: this.lcssTargets,
+				warnFn: (msg) => this.warn(msg)
+			})
 		].filter(Boolean).join("\n");
 		setSharedCss(fullCss);
-		const cssHash = createHash("md5").update(fullCss).digest("hex");
+		const cssHash = contentHash(fullCss);
 		if (cssHash !== this.lastCssHash) {
-			const animusDir = join(rootDir, ".animus");
-			if (!existsSync(animusDir)) mkdirSync(animusDir, { recursive: true });
-			writeFileSync(join(animusDir, "styles.css"), fullCss);
+			this.writeAnimusFile("styles.css", fullCss);
 			this.lastCssHash = cssHash;
 		}
-		const systemPropMap = JSON.stringify(manifest?.system_prop_map ?? {});
-		const dynamicProps = manifest?.dynamic_props ?? {};
-		const dynamicPropConfig = {};
-		for (const [propName, meta] of Object.entries(dynamicProps)) dynamicPropConfig[propName] = {
-			varName: meta.var_name,
-			slotClass: meta.slot_class,
-			...meta.transform_name ? { transformName: meta.transform_name } : {},
-			...meta.scale_values && Object.keys(meta.scale_values).length > 0 ? { scaleValues: meta.scale_values } : {}
-		};
-		const systemPropsContent = `export const systemPropMap = ${systemPropMap};\nexport const systemPropGroups = ${this.groupRegistryJson};\nexport const dynamicPropConfig = ${JSON.stringify(dynamicPropConfig)};\nexport const transforms = {};\n`;
+		const systemPropsContent = buildSystemPropsModule({
+			systemPropMapJson: JSON.stringify(manifest?.system_prop_map ?? {}),
+			groupRegistryJson: system.groupRegistryJson,
+			dynamicProps: manifest?.dynamic_props ?? {}
+		});
 		setSharedSystemProps(systemPropsContent);
-		const systemPropsHash = createHash("md5").update(systemPropsContent).digest("hex");
-		if (systemPropsHash !== this.lastSystemPropsHash) {
-			const spDir = join(rootDir, ".animus");
-			if (!existsSync(spDir)) mkdirSync(spDir, { recursive: true });
-			writeFileSync(join(spDir, "system-props.js"), systemPropsContent);
-			this.lastSystemPropsHash = systemPropsHash;
+		if (devMode) {
+			const systemPropsHash = contentHash(systemPropsContent);
+			if (systemPropsHash !== this.lastSystemPropsHash) {
+				this.writeAnimusFile("system-props.js", systemPropsContent);
+				this.lastSystemPropsHash = systemPropsHash;
+			}
+		} else this.writeAnimusFile("system-props.js", systemPropsContent);
+		setManifestJson(result.manifestJson);
+		const manifestHash = contentHash(result.manifestJson);
+		if (this.lastManifestHash === null) this.lastManifestHash = this.diskArtifactHash("manifest.json");
+		if (manifestHash !== this.lastManifestHash) {
+			this.writeAnimusFile("manifest.json", result.manifestJson);
+			this.lastManifestHash = manifestHash;
+		}
+		if (this.persistAnalysisInputs) {
+			const inputsJson = JSON.stringify(result.inputs);
+			const inputsHash = contentHash(inputsJson);
+			if (this.lastAnalysisInputsHash === null) this.lastAnalysisInputsHash = this.diskArtifactHash("analysis-inputs.json");
+			if (inputsHash !== this.lastAnalysisInputsHash) {
+				this.writeAnimusFile("analysis-inputs.json", inputsJson);
+				this.lastAnalysisInputsHash = inputsHash;
+			}
 		}
-		setManifestJson(manifestJson);
 		bt.total = this.elapsed(pipelineStart);
-		this.logBuildTimings(bt, manifest?.timing);
+		logBuildTimings(bt, manifest?.timing, (msg) => this.log(msg), this.verbose);
 	}
-	/** Expose file cache for HMR change detection */
-	getFileCache() {
-		return this.fileCache;
+	/** Content hash of an existing `.animus/` artifact, or null when absent or
+	*  unreadable. Seeds a null write guard so a FRESH session never rewrites a
+	*  byte-identical artifact (spec: next-turbopack-integration — a rewrite
+	*  changes mtime/inode and needlessly re-keys Turbopack loader-worker
+	*  hydration). */
+	diskArtifactHash(name) {
+		try {
+			return contentHash(readFileSync(join(this.rootDir, ".animus", name), "utf-8"));
+		} catch {
+			return null;
+		}
+	}
+	/** Ensure `.animus/` exists and write one generated artifact into it.
+	*  Write-then-rename so cross-process readers (Turbopack loader workers)
+	*  can never observe a torn half-written file. The tmp name carries the
+	*  pid — Next dev evaluates the config in more than one process, and two
+	*  sessions writing the same artifact must not race on one tmp path. */
+	writeAnimusFile(name, content) {
+		const dir = join(this.rootDir, ".animus");
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		const tmpPath = join(dir, `.${name}.${process.pid}.tmp`);
+		writeFileSync(tmpPath, content);
+		renameSync(tmpPath, join(dir, name));
+	}
+};
+//#endregion
+//#region src/plugin.ts
+const PLUGIN_NAME = "AnimusWebpackPlugin";
+/**
+* Webpack adapter for the extraction pipeline. All pipeline logic lives in
+* the bundler-agnostic ExtractionSession — this class owns only the webpack
+* wiring: hook registration, cross-compiler analysis dedup, alias
+* harvesting from the compiler config, watch-event translation, and
+* in-memory CSS asset replacement.
+*/
+var AnimusWebpackPlugin = class {
+	options;
+	session;
+	initialized = false;
+	aliasesExtracted = false;
+	constructor(options) {
+		this.options = options;
+		assertNoRetiredEngineSelection(options.engine);
+		setSharedEngine(options.engine ?? "v2");
+		this.session = new ExtractionSession(options);
+	}
+	/** Extract path aliases from webpack's resolve.alias config. Runs once per
+	*  plugin instance — the resolve config is immutable after apply. */
+	extractAliases(compiler) {
+		if (this.aliasesExtracted) return;
+		this.aliasesExtracted = true;
+		const rootDir = compiler.context;
+		const rawAlias = compiler.options?.resolve?.alias;
+		if (!rawAlias || typeof rawAlias !== "object") return;
+		const pairs = [];
+		for (const [key, value] of Object.entries(rawAlias)) {
+			const target = Array.isArray(value) ? value[0] : value;
+			if (typeof target !== "string") continue;
+			if (key === ".animus/styles.css") continue;
+			pairs.push({
+				pattern: key,
+				target
+			});
+		}
+		const built = buildPathAliasesJson(pairs, rootDir);
+		if (built) this.session.pathAliasesJson = built.json;
+	}
+	apply(compiler) {
+		if (compiler.options?.name === "edge-server") return;
+		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
+			const registerSystemDependencies = () => {
+				for (const dep of this.session.systemDependencyPaths) if (existsSync(dep)) compilation.fileDependencies.add(dep);
+				else compilation.missingDependencies.add(dep);
+			};
+			registerSystemDependencies();
+			const stage = compiler.webpack?.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL ?? -2e3;
+			const RawSource = compiler.webpack?.sources.RawSource;
+			compilation.hooks.processAssets.tap({
+				name: PLUGIN_NAME,
+				stage
+			}, () => {
+				registerSystemDependencies();
+				const css = getSharedCss();
+				if (!css || !RawSource) return;
+				const cssPath = join(this.session.rootDir || compiler.context, ".animus", "styles.css");
+				if (compilation.getAsset(cssPath)) {
+					compilation.updateAsset(cssPath, new RawSource(css));
+					return;
+				}
+				if (compilation.getAsset(".animus/styles.css")) compilation.updateAsset(ANIMUS_CSS_MODULE_ID, new RawSource(css));
+			});
+		});
+		compiler.hooks.run.tapPromise(PLUGIN_NAME, async (_compiler) => {
+			this.session.rootDir = _compiler.context;
+			this.extractAliases(_compiler);
+			const existing = getAnalysisPromise();
+			if (existing) {
+				await existing;
+				return;
+			}
+			const promise = this.session.runFullPipeline();
+			setAnalysisPromise(promise);
+			await promise;
+		});
+		compiler.hooks.watchRun.tapPromise(PLUGIN_NAME, async (_compiler) => {
+			this.session.rootDir = _compiler.context;
+			this.extractAliases(_compiler);
+			if (!this.initialized) {
+				const existing = getAnalysisPromise();
+				if (existing) {
+					await existing;
+					this.initialized = true;
+					return;
+				}
+				const promise = this.session.runFullPipeline();
+				setAnalysisPromise(promise);
+				await promise;
+				this.initialized = true;
+				return;
+			}
+			await this.session.handleWatchUpdate({
+				modifiedFiles: _compiler.modifiedFiles,
+				removedFiles: _compiler.removedFiles
+			});
+		});
+	}
+	/**
+	* Reset analysis state for HMR geological reset.
+	*/
+	resetForHmr() {
+		this.session.resetForHmr();
 	}
 	/** Expose options for the loader */
 	getOptions() {
@@ -659,18 +671,187 @@ var AnimusWebpackPlugin = class {
 	/** Expose external package directories for webpack loader allowlisting.
 	*  Falls back to shared globalThis state for non-owning compiler instances. */
 	getExternalPackageDirs() {
-		return this.externalPackageDirs.length > 0 ? this.externalPackageDirs : getSharedExternalDirs();
+		return this.session.externalPackageDirs.length > 0 ? this.session.externalPackageDirs : getSharedExternalDirs();
 	}
 	/** Expose external package source entries for webpack resolve alias.
 	*  Falls back to shared globalThis state for non-owning compiler instances. */
 	getExternalSourceEntries() {
-		return this.externalSourceEntries.size > 0 ? this.externalSourceEntries : getSharedExternalEntries();
+		return this.session.externalSourceEntries.size > 0 ? this.session.externalSourceEntries : getSharedExternalEntries();
 	}
 };
 //#endregion
+//#region src/turbopack-config.ts
+/** The single glob the Animus loader registers under. `.mjs` is included
+*  for webpack parity: an external package without `src/` is ingested via
+*  its resolved dist entry (often `dist/index.mjs`) and must still reach
+*  the loader — manifest lookup remains the file-level gate. */
+const ANIMUS_TURBOPACK_RULE_GLOB = "*.{ts,tsx,js,jsx,mjs}";
+/** Virtual system-props id emitted into transformed sources under Turbopack
+*  (absolute-path imports are rejected there); resolveAlias maps it to the
+*  on-disk artifact. */
+const TURBOPACK_SYSTEM_PROPS_ID = "virtual:animus/system-props";
+/**
+* Resolve whether Turbopack wiring is active for this process. Default is
+* `'auto'`: active exactly when the TURBOPACK environment variable is set
+* (Next sets it for every Turbopack dev/build). The stable `turbopack`
+* option wins over the deprecated `unstable_turbopack` alias.
+*/
+function resolveTurbopackMode(options, env = process.env) {
+	const mode = options.turbopack?.mode ?? options.unstable_turbopack?.mode ?? "auto";
+	if (mode === "on") return true;
+	if (mode === "auto") return env.TURBOPACK !== void 0;
+	return false;
+}
+/**
+* Build the `turbopack` config fragment: one glob-keyed loader rule
+* (file-level allowlisting lives in the loader via manifest lookup — Next 15
+* rules have no condition algebra) plus resolve aliases for the virtual
+* system-props id, the emitter's stylesheet id, and each collected external
+* package specifier redirected to its source entry.
+*/
+function buildTurbopackConfig(args) {
+	const { rootDir, loaderPath, options, externalSourceEntries } = args;
+	const loaderOptions = {
+		rootDir,
+		...options.strict !== void 0 ? { strict: options.strict } : {},
+		...options.cssImportTarget !== void 0 ? { cssImportTarget: options.cssImportTarget } : {}
+	};
+	const resolveAlias = {
+		[TURBOPACK_SYSTEM_PROPS_ID]: "./.animus/system-props.js",
+		".animus/styles.css": "./.animus/styles.css"
+	};
+	for (const [specifier, srcEntry] of externalSourceEntries) resolveAlias[specifier] = `./${relative(rootDir, srcEntry).replace(/\\/g, "/")}`;
+	return {
+		rules: { [ANIMUS_TURBOPACK_RULE_GLOB]: { loaders: [{
+			loader: loaderPath,
+			options: loaderOptions
+		}] } },
+		resolveAlias
+	};
+}
+/**
+* Locate the Turbopack loader module: built dist first, source fallback for
+* in-repo development. CJS preferred — Turbopack's loader-runner follows
+* the webpack loader contract (`module.exports = fn`), and the .cjs build
+* is loadable by every runner version; ESM default-export acceptance is
+* not guaranteed.
+*/
+function resolveTurbopackLoaderPath(pluginDir) {
+	for (const candidate of ["turbopack-loader.cjs", "turbopack-loader.mjs"]) {
+		const distPath = resolve(pluginDir, candidate);
+		if (existsSync(distPath)) return distPath;
+	}
+	return resolve(pluginDir, "turbopack-loader.ts");
+}
+//#endregion
+//#region src/turbopack-orchestrator.ts
+/**
+* Out-of-band pipeline orchestration for Turbopack (spec:
+* next-turbopack-integration). Turbopack exposes no compiler hooks, so the
+* pipeline runs during next.config resolution and, in dev, from a
+* filesystem watcher — the bundler only ever sees the `.animus/` disk
+* artifacts.
+*/
+/** Run the full pipeline with the Turbopack emitter identity: hydration
+*  artifacts persisted, and the virtual system-props id (Turbopack rejects
+*  the webpack path's absolute-path imports). */
+async function runTurbopackPipeline(session) {
+	session.persistAnalysisInputs = true;
+	session.systemPropsModuleId = TURBOPACK_SYSTEM_PROPS_ID;
+	await session.runFullPipeline();
+}
+const activeWatcherRoots = /* @__PURE__ */ new Set();
+const IGNORED_SEGMENTS = new Set([
+	".animus",
+	".next",
+	"node_modules"
+]);
+/**
+* Start the dev watcher: fs.watch per eligible top-level directory (plus a
+* non-recursive watch on the root itself), debounced into
+* existence-partitioned modified/removed sets feeding
+* `session.handleWatchUpdate` (serialized — updates never overlap).
+* Generated and vendored trees (`.animus`, `.next`, node_modules) are never
+* registered with the OS — recursive registration of those trees exhausts
+* inotify/kqueue descriptors (EMFILE/ENOSPC) on large projects.
+* Idempotent per project root; unref'd so it never holds the process open.
+* Asynchronous FSWatcher errors degrade to no-watch with a warning instead
+* of crashing the dev server. Returns a close handle, or null when this
+* root is already watched or the platform lacks recursive fs.watch (Linux
+* before Node 20 — degrades to no-watch with a warning).
+*/
+function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watch) {
+	if (activeWatcherRoots.has(rootDir)) return null;
+	activeWatcherRoots.add(rootDir);
+	const pendingPaths = /* @__PURE__ */ new Set();
+	const watchers = /* @__PURE__ */ new Map();
+	let timer = null;
+	let updateChain = Promise.resolve();
+	let closed = false;
+	const flush = () => {
+		timer = null;
+		const modifiedFiles = /* @__PURE__ */ new Set();
+		const removedFiles = /* @__PURE__ */ new Set();
+		for (const path of pendingPaths) (existsSync(path) ? modifiedFiles : removedFiles).add(path);
+		pendingPaths.clear();
+		updateChain = updateChain.then(() => session.handleWatchUpdate({
+			modifiedFiles,
+			removedFiles
+		}).catch((err) => {
+			console.warn(`[animus-extract] Turbopack watch update failed: ${String(err)}`);
+		}));
+	};
+	const closeAll = () => {
+		if (closed) return;
+		closed = true;
+		if (timer) clearTimeout(timer);
+		timer = null;
+		for (const watcher of watchers.values()) watcher.close();
+		watchers.clear();
+		activeWatcherRoots.delete(rootDir);
+	};
+	const onWatcherError = (err) => {
+		closeAll();
+		console.warn(`[animus-extract] Turbopack dev watcher failed (${String(err)}); source edits require a dev-server restart`);
+	};
+	const onEvent = (baseDir, filename) => {
+		if (closed || !filename) return;
+		const rel = filename.toString();
+		if (rel.split(/[\\/]/).some((segment) => IGNORED_SEGMENTS.has(segment))) return;
+		const abs = join(baseDir, rel);
+		if (baseDir === rootDir && !watchers.has(abs)) try {
+			if (statSync(abs).isDirectory()) addWatcher(abs, true);
+		} catch {}
+		pendingPaths.add(abs);
+		if (!timer) {
+			timer = setTimeout(flush, debounceMs);
+			timer.unref?.();
+		}
+	};
+	const addWatcher = (dir, recursive) => {
+		const watcher = watchFn(dir, { recursive }, (_event, filename) => onEvent(dir, filename));
+		watcher.on("error", onWatcherError);
+		watcher.unref?.();
+		watchers.set(dir, watcher);
+	};
+	try {
+		addWatcher(rootDir, false);
+		for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+			if (!entry.isDirectory() || IGNORED_SEGMENTS.has(entry.name)) continue;
+			addWatcher(join(rootDir, entry.name), true);
+		}
+	} catch (err) {
+		closeAll();
+		console.warn(`[animus-extract] Turbopack dev watcher unavailable (${String(err)}); source edits require a dev-server restart`);
+		return null;
+	}
+	return { close: closeAll };
+}
+//#endregion
 //#region src/with-animus.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let warnedGitignore = false;
+let warnedUnstableTurbopack = false;
 /**
 * Wrap a Next.js config to enable Animus static CSS extraction.
 *
@@ -682,16 +863,30 @@ let warnedGitignore = false;
 */
 function withAnimus(options) {
 	if (!options.system) throw new Error("[animus-extract] Missing required option `system`. Provide the path to your SystemInstance module: withAnimus({ system: \"./src/ds.ts\" })");
+	if (options.unstable_turbopack && !options.turbopack && !warnedUnstableTurbopack) {
+		warnedUnstableTurbopack = true;
+		console.warn("[animus-extract] `unstable_turbopack` is deprecated — rename it to `turbopack` (same shape)");
+	}
 	return (nextConfig) => {
+		if (resolveTurbopackMode(options)) return wireTurbopack(nextConfig, options);
 		const existingWebpack = nextConfig.webpack;
 		return {
 			...nextConfig,
 			webpack(config, context) {
+				if (typeof existingWebpack === "function") config = existingWebpack(config, context);
 				const rootDir = process.cwd();
 				const animusDir = join(rootDir, ".animus");
 				if (!existsSync(animusDir)) mkdirSync(animusDir, { recursive: true });
 				const stubCssPath = join(animusDir, "styles.css");
-				if (!existsSync(stubCssPath)) writeFileSync(stubCssPath, "@layer anm-global, anm-base, anm-variants, anm-compounds, anm-states, anm-system, anm-custom;\n");
+				if (!existsSync(stubCssPath)) {
+					const { declaration } = assembleStylesheet({
+						layers: options.layers,
+						variableCss: "",
+						globalCss: "",
+						split: true
+					});
+					writeFileSync(stubCssPath, declaration);
+				}
 				if (!warnedGitignore) {
 					warnedGitignore = true;
 					try {
@@ -701,19 +896,13 @@ function withAnimus(options) {
 						}
 					} catch {}
 				}
-				const plugin = new AnimusWebpackPlugin({
-					system: options.system,
-					exclude: options.exclude,
-					strict: options.strict,
-					verbose: options.verbose,
-					prefix: options.prefix,
-					engine: options.engine
-				});
+				const plugin = new AnimusWebpackPlugin(options);
+				const isExternalPackageFile = (filePath) => plugin.getExternalPackageDirs().some((dir) => filePath.startsWith(dir + sep) || filePath === dir);
 				config.plugins = config.plugins || [];
 				config.plugins.push(plugin);
 				config.resolve = config.resolve || {};
 				config.resolve.alias = config.resolve.alias || {};
-				config.resolve.alias[".animus/styles.css"] = join(rootDir, ".animus", "styles.css");
+				config.resolve.alias[ANIMUS_CSS_MODULE_ID] = join(rootDir, ".animus", "styles.css");
 				const systemPropsPath = join(rootDir, ".animus", "system-props.js");
 				config.plugins.push({ apply(compiler) {
 					compiler.hooks.normalModuleFactory.tap("AnimusVirtualResolve", (nmf) => {
@@ -732,24 +921,62 @@ function withAnimus(options) {
 				config.module.rules.push({
 					test: (filePath) => {
 						if (/\.[jt]sx?$/.test(filePath)) return true;
-						if (/\.mjs$/.test(filePath)) return plugin.getExternalPackageDirs().some((dir) => filePath.startsWith(dir + sep) || filePath === dir);
-						return false;
+						return /\.mjs$/.test(filePath) && isExternalPackageFile(filePath);
 					},
 					exclude: (filePath) => {
 						if (!filePath.includes("node_modules")) return false;
-						return !plugin.getExternalPackageDirs().some((dir) => filePath.startsWith(dir + sep) || filePath === dir);
+						return !isExternalPackageFile(filePath);
 					},
 					enforce: "pre",
 					use: [{
 						loader: actualLoaderPath,
-						options: { strict: options.strict }
+						options: {
+							strict: options.strict,
+							cssImportTarget: options.cssImportTarget
+						}
 					}]
 				});
-				if (typeof existingWebpack === "function") return existingWebpack(config, context);
 				return config;
 			}
 		};
 	};
 }
+/**
+* Turbopack wiring: run the full extraction now (artifacts on disk before
+* bundling), start the dev watcher, and merge the generated rules/aliases
+* into `nextConfig.turbopack`. Consumer-managed rules for the same glob are
+* a hard error — silently stacking loaders would be undebuggable.
+*/
+async function wireTurbopack(nextConfig, options) {
+	const rootDir = process.cwd();
+	const session = new ExtractionSession(options);
+	session.rootDir = rootDir;
+	const builtAliases = buildPathAliasesJson(readTsconfigAliasPairs(rootDir), rootDir);
+	if (builtAliases) session.pathAliasesJson = builtAliases.json;
+	await runTurbopackPipeline(session);
+	if (process.env.NODE_ENV === "development") startTurbopackWatcher(session, rootDir);
+	const fragment = buildTurbopackConfig({
+		rootDir,
+		loaderPath: resolveTurbopackLoaderPath(__dirname),
+		options,
+		externalSourceEntries: session.externalSourceEntries
+	});
+	const existing = nextConfig.turbopack ?? {};
+	if (existing.rules && "*.{ts,tsx,js,jsx,mjs}" in existing.rules) throw new Error(`[animus-extract] turbopack.rules['${ANIMUS_TURBOPACK_RULE_GLOB}'] is already configured — remove the consumer rule or disable unstable_turbopack`);
+	return {
+		...nextConfig,
+		turbopack: {
+			...existing,
+			rules: {
+				...existing.rules,
+				...fragment.rules
+			},
+			resolveAlias: {
+				...existing.resolveAlias,
+				...fragment.resolveAlias
+			}
+		}
+	};
+}
 //#endregion
 export { withAnimus };