@animus-ui/extract 0.1.1-beta.2 → 0.1.2

package/dist/index.mjs

@@ -1,5 +1,15 @@
-import { readFileSync } from "fs";
+import { createRequire } from "node:module";
+import { createHash } from "crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "path";
+import browserslist from "browserslist";
+import { browserslistToTargets, transform } from "lightningcss";
 import { UNITLESS_PROPERTIES } from "@animus-ui/properties";
+import { realpathSync } from "node:fs";
+import { basename, dirname as dirname$1, join as join$1, normalize } from "node:path";
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
 //#region pipeline/assemble-stylesheet.ts
 /**
 * The 7 Animus cascade layers. Always prefixed with `anm-` to avoid
@@ -72,8 +82,319 @@ function assembleStylesheet(options) {
 	].filter(Boolean).join("\n");
 }
 //#endregion
+//#region pipeline/analyze-project-args.ts
+/** @internal */
+function buildAnalyzeProjectArgs(inputs) {
+	return [
+		inputs.filesJson,
+		inputs.scalesJson,
+		inputs.variableMapJson,
+		inputs.contextualVarsJson,
+		inputs.propConfigJson,
+		inputs.groupRegistryJson,
+		inputs.packageResolutionJson,
+		inputs.devMode,
+		inputs.emitterConfigJson,
+		inputs.selectorAliasesJson,
+		null,
+		inputs.globalStyleBlocksJson,
+		inputs.pathAliasesJson,
+		inputs.keyframesJson,
+		inputs.staticCssJson,
+		inputs.conditionAliasesJson
+	];
+}
+//#endregion
+//#region pipeline/engine-adapter.ts
+/**
+* Build the engine-agnostic `engineApi()` both plugins call. Returns a function
+* (invoked per call site) so `isV2()` and `loadNativeEngine()` re-evaluate each
+* time — next reads its engine choice and native module dynamically from
+* globalThis.
+*/
+function createV2EngineApi(deps) {
+	const { label, isV2, loadNativeEngine, store } = deps;
+	return () => {
+		if (!isV2()) return loadNativeEngine();
+		const native = loadNativeEngine();
+		return {
+			loadSystemModule: (...args) => native.loadSystemModule(...args),
+			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson) => {
+				const filesJson = deps.rehydrateFilesJson ? deps.rehydrateFilesJson(filesJsonRaw) : filesJsonRaw;
+				const sent = /* @__PURE__ */ new Map();
+				for (const entry of JSON.parse(filesJson)) sent.set(entry.path, entry.source);
+				store.setSentSources(sent);
+				const emitterConfig = emitterConfigJson ? JSON.parse(emitterConfigJson) : {};
+				store.setEngine(null);
+				const config = {
+					runtimeImport: emitterConfig.runtime_import ?? void 0,
+					cssModuleId: emitterConfig.css_module_id ?? void 0,
+					systemPropsModuleId: emitterConfig.system_props_module_id ?? void 0,
+					themeJson: scalesJson,
+					variableMapJson,
+					contextualVarsJson: contextualVarsJson ?? void 0,
+					configJson: propConfigJson,
+					groupRegistryJson,
+					selectorAliasesJson: selectorAliasesJson ?? void 0,
+					conditionAliasesJson: conditionAliasesJson ?? void 0,
+					globalStyleBlocksJson: globalStyleBlocksJson ?? void 0,
+					keyframesJson: keyframesJson ?? void 0,
+					packageResolutionJson: packageResolutionJson ?? void 0,
+					pathAliasesJson: pathAliasesJson ?? void 0,
+					staticCssJson: staticCssJson ?? void 0,
+					devMode
+				};
+				const engine = new native.ExtractEngine(config);
+				store.setEngine(engine);
+				return engine.analyze(filesJson);
+			},
+			transformFile: (source, path, _manifest) => {
+				const engine = store.getEngine();
+				if (!engine) throw new Error(`[${label}] v2 transform before analyze — engine instance not initialized`);
+				const sentMap = store.getSentSources();
+				if (deps.passThroughUnknownPaths && sentMap && !sentMap.has(path)) return {
+					code: source,
+					hasComponents: false
+				};
+				const sent = sentMap?.get(path);
+				if (sent !== void 0 && sent !== source && !store.getDriftWarned()) {
+					store.setDriftWarned(true);
+					console.warn(`[${label}] v2: transform-time source for ${path} differs from analyze-time source — an upstream transform may be reverted`);
+				}
+				return JSON.parse(engine.transformFile(path));
+			},
+			clearAnalysisCache: () => {
+				const engine = store.getEngine();
+				if (engine) engine.clearCache();
+				store.setEngine(null);
+			}
+		};
+	};
+}
+//#endregion
+//#region pipeline/engine-retirement.ts
+/**
+* Loud rejection of the retired v1 extraction engine (openspec:
+* retire-extract-v1).
+*
+* v2 is the only engine. Selecting v1 — via a plugin `engine: 'v1'` option or
+* the `ANIMUS_ENGINE=v1` fixture env override — is a build-stopping error, never
+* a silent upgrade to v2 (design D1: a silent flip would let a pinned consumer's
+* build change engines without notice). Both extraction plugins call this before
+* any engine selection so the rejection is uniform and the message is defined
+* once.
+*/
+/** The one canonical retirement message, shared verbatim by both plugins and
+*  the env path (tasks.md cross-cutting: define once, reuse). */
+const RETIRED_ENGINE_MESSAGE = "animus: extraction engine 'v1' was retired (openspec: retire-extract-v1) — v2 is the only engine; remove the engine option / ANIMUS_ENGINE override";
+/**
+* Throw the canonical retirement error when v1 is selected through either
+* surface. Accepts the raw engine option as a string because the option type no
+* longer admits `'v1'` — callers cast it so a stale `'v1'` config still fails
+* loud at runtime instead of being silently coerced.
+*/
+function assertNoRetiredEngineSelection(engineOption) {
+	if (engineOption === "v1" || process.env.ANIMUS_ENGINE === "v1") throw new Error(RETIRED_ENGINE_MESSAGE);
+}
+//#endregion
+//#region pipeline/content-hash.ts
+/**
+* MD5 content hash used for file-change detection (HMR diffing) by both
+* extraction plugins. The algorithm/encoding is a cross-plugin contract:
+* cache keys written by one build path must compare equal in the next.
+*/
+function contentHash(source) {
+	return createHash("md5").update(source).digest("hex");
+}
+//#endregion
+//#region pipeline/discover-files.ts
+/**
+* Recursively discover source files under `dir`, skipping any path that
+* contains one of `excludePatterns` (matched as substrings of both the full
+* and root-relative path) and keeping files whose extension is in
+* `extensionsSet`.
+*
+* Single authoritative copy for both extraction plugins.
+*/
+function discoverFiles(dir, rootDir, excludePatterns, extensionsSet) {
+	const results = [];
+	let entries;
+	try {
+		entries = readdirSync(dir, { encoding: "utf8" });
+	} catch {
+		return results;
+	}
+	for (const entry of entries) {
+		const fullPath = join(dir, entry);
+		const relativePath = relative(rootDir, fullPath);
+		if (excludePatterns.some((pattern) => fullPath.includes(pattern) || relativePath.includes(pattern))) continue;
+		let stat;
+		try {
+			stat = statSync(fullPath);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) results.push(...discoverFiles(fullPath, rootDir, excludePatterns, extensionsSet));
+		else if (extensionsSet.has(extname(entry))) results.push(fullPath);
+	}
+	return results;
+}
+//#endregion
 //#region pipeline/discover-packages.ts
 /**
+* Walk up from a resolved package entry file to the nearest directory
+* containing a package.json (the package root). Stops at the filesystem
+* root and returns it if no package.json is found on the way up.
+*/
+function findPackageRoot(absEntryPath) {
+	let pkgRoot = dirname(absEntryPath);
+	while (pkgRoot !== dirname(pkgRoot) && !existsSync(join(pkgRoot, "package.json"))) pkgRoot = dirname(pkgRoot);
+	return pkgRoot;
+}
+/**
+* Exclusion fragments for discovery inside an external package's src/,
+* matched against paths RELATIVE TO the src dir. Per spec
+* external-package-file-discovery, the filters apply "within the package" —
+* an npm-installed package whose own location is under node_modules (or a
+* repo path containing 'dist') must still have its sources discovered.
+*/
+const PACKAGE_SRC_EXCLUDES = [
+	"dist",
+	"node_modules",
+	".test.",
+	".spec."
+];
+const isFile = (path) => {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+};
+/**
+* Resolve an absolute-path specifier (a relative `includes` entry already
+* resolved against the system file) without a bundler: the path itself when it
+* is a file, otherwise the extension and directory-index candidates built from
+* the caller's extension set. Used only as a fallback — a bundler resolver that
+* answers first still wins, since it also knows aliases and `.js`→`.ts` mapping.
+*/
+function resolveAbsolutePathSpecifier(absSpecifier, extensionsSet) {
+	return [
+		absSpecifier,
+		...Array.from(extensionsSet, (ext) => absSpecifier + ext),
+		...Array.from(extensionsSet, (ext) => join(absSpecifier, `index${ext}`))
+	].find(isFile) ?? null;
+}
+/**
+* Shared external-package source collection (spec:
+* external-package-file-discovery), consumed by both extraction plugins.
+* For each specifier: resolve to an absolute entry (null/throw → silently
+* skip; an absolute-path specifier falls back to a filesystem probe), walk up
+* to the package root, then either discover sources under src/ (redirecting
+* module resolution to src/index.ts when present) or fall back to ingesting
+* the resolved entry file itself.
+*
+* The only bundler-specific seams are callbacks: specifier resolution,
+* dedup against already-ingested files, per-file preprocessing (MDX), and
+* the unreadable-file warning. Hashing and caching stay in the plugins —
+* their cache policies legitimately differ.
+*
+* Alongside the aggregates, one `ExternalPackageOutcome` per declared
+* specifier records what that specifier produced. Collection never reports on
+* them — any warning or gate is the caller's policy.
+*/
+async function collectExternalPackageSources(opts) {
+	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable } = opts;
+	const entries = [];
+	const pushed = /* @__PURE__ */ new Set();
+	const packageMap = {};
+	const sourceEntries = /* @__PURE__ */ new Map();
+	const packageDirs = [];
+	const outcomes = [];
+	const alreadyIngested = (relPath) => hasEntry(relPath) || pushed.has(relPath);
+	for (const specifier of specifiers) {
+		let absEntry;
+		try {
+			absEntry = await resolveSpecifier(specifier);
+		} catch {
+			absEntry = null;
+		}
+		if (!absEntry && isAbsolute(specifier)) absEntry = resolveAbsolutePathSpecifier(specifier, extensionsSet);
+		if (!absEntry) {
+			outcomes.push({
+				specifier,
+				outcome: "unresolvable",
+				fileCount: 0
+			});
+			continue;
+		}
+		const srcDir = join(findPackageRoot(absEntry), "src");
+		let fileCount = 0;
+		if (existsSync(srcDir)) {
+			packageDirs.push(srcDir);
+			const srcEntry = join(srcDir, "index.ts");
+			if (existsSync(srcEntry)) {
+				packageMap[specifier] = relative(rootDir, srcEntry);
+				sourceEntries.set(specifier, srcEntry);
+			} else packageMap[specifier] = relative(rootDir, absEntry);
+			const pkgFiles = discoverFiles(srcDir, srcDir, [], extensionsSet).filter((absPath) => {
+				const inPkg = relative(srcDir, absPath);
+				return !PACKAGE_SRC_EXCLUDES.some((pattern) => inPkg.includes(pattern));
+			});
+			for (const pkgFile of pkgFiles) {
+				const relPath = relative(rootDir, pkgFile);
+				if (alreadyIngested(relPath)) {
+					fileCount++;
+					continue;
+				}
+				let source;
+				try {
+					source = readFileSync(pkgFile, "utf-8");
+				} catch (err) {
+					onUnreadable(relPath, err);
+					continue;
+				}
+				const processed = await preprocessFile(source, relPath, pkgFile);
+				if (!processed) continue;
+				entries.push({
+					path: processed.relPath,
+					source: processed.source
+				});
+				pushed.add(processed.relPath);
+				fileCount++;
+			}
+		} else {
+			packageDirs.push(dirname(absEntry));
+			const relPath = relative(rootDir, absEntry);
+			packageMap[specifier] = relPath;
+			if (alreadyIngested(relPath)) fileCount++;
+			else try {
+				const source = readFileSync(absEntry, "utf-8");
+				entries.push({
+					path: relPath,
+					source
+				});
+				pushed.add(relPath);
+				fileCount++;
+			} catch (err) {
+				onUnreadable(relPath, err);
+			}
+		}
+		outcomes.push({
+			specifier,
+			outcome: fileCount > 0 ? "resolved" : "empty",
+			fileCount
+		});
+	}
+	return {
+		entries,
+		packageMap,
+		sourceEntries,
+		packageDirs,
+		outcomes
+	};
+}
+/**
 * Extract external DS package names from `includes` declarations in the system file.
 *
 * Supports two forms:
@@ -81,8 +402,11 @@ function assembleStylesheet(options) {
 *   - Legacy:          `.includes([identifier, ...])` chain method (RC migration fallback)
 *
 * For each identifier found, traces back to its import declaration and returns
-* the import specifier. Only packages explicitly declared via `includes` are treated
-* as external DS dependencies.
+* the import specifier: a bare specifier normalized to its package name, a
+* relative specifier resolved against the system file's directory into an
+* absolute path (so a sibling package referenced by path contributes discovery
+* too). Only packages explicitly declared via `includes` are treated as
+* external DS dependencies.
 *
 * Falls back to empty array if no `includes` declaration is found.
 */
@@ -122,10 +446,13 @@ function extractSystemFilePackages(systemFilePath) {
 			if (localName) importMap.set(localName, specifier);
 		}
 	}
+	const systemFileDir = dirname(systemFilePath);
 	const packages = /* @__PURE__ */ new Set();
 	for (const id of identifiers) {
 		const specifier = importMap.get(id);
-		if (specifier && !specifier.startsWith(".")) {
+		if (!specifier) continue;
+		if (specifier.startsWith(".")) packages.add(resolve(systemFileDir, specifier));
+		else {
 			const pkgName = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
 			packages.add(pkgName);
 		}
@@ -133,6 +460,525 @@ function extractSystemFilePackages(systemFilePath) {
 	return Array.from(packages);
 }
 //#endregion
+//#region pipeline/path-aliases.ts
+/**
+* Normalize alias pairs: strip a `rootDir` prefix from targets, classify
+* exact (file) vs prefix (directory) matches, force trailing slashes on
+* prefix entries, and sort longest pattern first for correct matching
+* priority. Returns null when no entries survive.
+*/
+function buildPathAliasesJson(pairs, rootDir) {
+	const entries = [];
+	for (const { pattern, target, kind } of pairs) {
+		const replacement = target.startsWith(rootDir) ? target.slice(rootDir.length + 1) : target;
+		if (kind ? kind === "exact" : /\.\w+$/.test(replacement)) entries.push({
+			pattern,
+			replacement,
+			type: "exact"
+		});
+		else entries.push({
+			pattern: pattern.endsWith("/") ? pattern : pattern + "/",
+			replacement: replacement.endsWith("/") ? replacement : replacement + "/",
+			type: "prefix"
+		});
+	}
+	entries.sort((a, b) => b.pattern.length - a.pattern.length);
+	if (entries.length === 0) return null;
+	return {
+		json: JSON.stringify({ aliases: entries }),
+		count: entries.length
+	};
+}
+//#endregion
+//#region pipeline/post-process-css.ts
+/**
+* CSS post-processing (spec: css-post-processing) — Lightning CSS
+* autoprefixing, syntax lowering, and optional minification against
+* browserslist targets. The single implementation consumed by both the
+* Vite plugin (virtual-module serve time) and the Next.js plugin
+* (ExtractionSession artifact emission).
+*/
+/**
+* Resolve browser targets for Lightning CSS.
+* Priority: explicit config → project browserslist → 'defaults' fallback.
+*/
+function resolveLightningTargets(explicitTargets, rootDir) {
+	let queries;
+	if (explicitTargets) queries = Array.isArray(explicitTargets) ? explicitTargets : [explicitTargets];
+	else {
+		const detected = browserslist(void 0, { path: rootDir });
+		queries = detected.length > 0 ? detected : browserslist("defaults");
+	}
+	return browserslistToTargets(Array.isArray(queries) && typeof queries[0] === "string" && queries[0].includes(" ") ? browserslist(queries) : queries);
+}
+/**
+* Post-process CSS with Lightning CSS: autoprefixing + optional minification.
+* On failure, returns the original CSS and logs a warning.
+*/
+function postProcessCss(css, opts) {
+	if (!css) return css;
+	try {
+		return transform({
+			filename: "animus-extracted.css",
+			code: Buffer.from(css),
+			minify: opts.minify,
+			targets: opts.targets
+		}).code.toString();
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		(opts.warnFn ?? console.warn)(`[animus] Lightning CSS post-processing failed: ${msg}`);
+		return css;
+	}
+}
+//#endregion
+//#region pipeline/manifest-diagnostics.ts
+/**
+* Surface extraction-manifest diagnostics through a plugin's warn channel.
+*
+* Single authoritative copy for both extraction plugins. Surfaces `bail`
+* (component not extracted), `skip` (component skipped), and `warn` kinds;
+* unknown kinds stay silent.
+*/
+function surfaceManifestDiagnostics(manifest, warn) {
+	for (const diagnostic of manifest.diagnostics ?? []) if (diagnostic.kind === "bail") warn(`⚠ ${diagnostic.component} not extracted: ${diagnostic.message}`);
+	else if (diagnostic.kind === "skip") warn(`⚠ ${diagnostic.component}: skipped ${diagnostic.message}`);
+	else if (diagnostic.kind === "warn") warn(`⚠ ${diagnostic.file}: ${diagnostic.component}: ${diagnostic.message}`);
+}
+//#endregion
+//#region pipeline/unit-fallback.ts
+/**
+* Append `px` to bare numeric values in CSS declarations for properties
+* that expect length units. Unitless properties are preserved as-is.
+* Numbers inside CSS function calls (cubic-bezier, rgb, calc, etc.) are skipped.
+*/
+function applyUnitFallback(css) {
+	return css.replace(/([a-z-]+)\s*:\s*([^;{}]+);/g, (match, prop, value) => {
+		if (UNITLESS_PROPERTIES.has(prop)) return match;
+		let depth = 0;
+		let fixed = "";
+		let i = 0;
+		while (i < value.length) if (value[i] === "(") {
+			depth++;
+			fixed += value[i];
+			i++;
+		} else if (value[i] === ")") {
+			depth--;
+			fixed += value[i];
+			i++;
+		} else if (depth > 0) {
+			fixed += value[i];
+			i++;
+		} else {
+			const numMatch = value.slice(i).match(/^(-?\d+\.?\d*)/);
+			if (numMatch) {
+				const num = numMatch[1];
+				const after = value[i + num.length];
+				if (after && /[a-z%]/i.test(after)) fixed += num;
+				else fixed += num + "px";
+				i += num.length;
+			} else {
+				fixed += value[i];
+				i++;
+			}
+		}
+		return fixed !== value ? `${prop}:${fixed};` : match;
+	});
+}
+//#endregion
+//#region pipeline/run-analysis.ts
+/**
+* Build the named `analyzeProject` input set from analysis options. Also
+* the persistence shape for `.animus/analysis-inputs.json` — an isolated
+* process can replay the analysis from exactly this object
+* (spec: next-turbopack-integration).
+*/
+function buildAnalysisInputs(opts) {
+	return {
+		filesJson: JSON.stringify(opts.fileEntries),
+		scalesJson: opts.system.scalesJson,
+		variableMapJson: opts.system.variableMapJson,
+		contextualVarsJson: opts.system.contextualVarsJson,
+		propConfigJson: opts.system.propConfigJson,
+		groupRegistryJson: opts.system.groupRegistryJson,
+		packageResolutionJson: JSON.stringify(opts.packageMap),
+		devMode: opts.devMode,
+		emitterConfigJson: JSON.stringify({
+			runtime_import: opts.emitter.runtimeImport,
+			css_module_id: opts.emitter.cssModuleId,
+			...opts.emitter.systemPropsModuleId ? { system_props_module_id: opts.emitter.systemPropsModuleId } : {}
+		}),
+		selectorAliasesJson: opts.system.selectorAliasesJson,
+		globalStyleBlocksJson: opts.system.globalStyleBlocksJson,
+		pathAliasesJson: opts.pathAliasesJson,
+		keyframesJson: opts.system.keyframesJson,
+		staticCssJson: opts.staticCssJson ?? null,
+		conditionAliasesJson: opts.system.conditionAliasesJson ?? null
+	};
+}
+/**
+* The one analysis invocation both plugins share: build the emitter
+* config, serialize inputs, call the NAPI `analyzeProject`, parse the
+* manifest, surface its diagnostics, and resolve the CSS outputs.
+*
+* Error handling stays at the call site (strict-mode throw vs warn).
+*/
+function runProjectAnalysis(engineApi, opts) {
+	const { analyzeProject } = engineApi();
+	let t = performance.now();
+	const inputs = buildAnalysisInputs(opts);
+	const serializeMs = Math.round(performance.now() - t);
+	t = performance.now();
+	const manifestJson = analyzeProject(...buildAnalyzeProjectArgs(inputs));
+	const extractMs = Math.round(performance.now() - t);
+	t = performance.now();
+	const manifest = JSON.parse(manifestJson);
+	surfaceManifestDiagnostics(manifest, opts.warn);
+	const parseMs = Math.round(performance.now() - t);
+	return {
+		manifest,
+		manifestJson,
+		globalCss: manifest?.sheets?.global || "",
+		componentCss: applyUnitFallback(manifest?.css || ""),
+		inputs,
+		timings: {
+			serializeMs,
+			extractMs,
+			parseMs
+		}
+	};
+}
+/**
+* Clear the engine's per-file analysis cache so stale results from a prior
+* build never bleed into a fresh run. Tolerates engines without the
+* capability (older builds) — the probe is benign.
+*/
+function clearEngineCache(engineApi) {
+	try {
+		const { clearAnalysisCache } = engineApi();
+		clearAnalysisCache();
+	} catch {}
+}
+//#endregion
+//#region pipeline/static-css.ts
+/** Key-sorted stringify so semantically identical configs serialize
+*  identically (stable analysis-inputs hashing). */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+/** Serialize a staticCss option for the engine; null when absent/empty. */
+function serializeStaticCss(config) {
+	if (!config) return null;
+	const json = stableStringify(config);
+	return json === "{}" ? null : json;
+}
+//#endregion
+//#region pipeline/prefix.ts
+/**
+* Apply namespace prefix to a variable map, CSS variable declarations, and theme JSON.
+*
+* Variable map: `{ "colors.ember": "--color-ember" }` -> `{ "colors.ember": "--prefix-color-ember" }`
+* Variable CSS: `--color-ember: #FF2800` -> `--prefix-color-ember: #FF2800`
+*               `var(--color-ember)` -> `var(--prefix-color-ember)`
+* Theme JSON:   `{ "colors.ember": "var(--color-ember)" }` -> `{ "colors.ember": "var(--prefix-color-ember)" }`
+*/
+function applyPrefix(prefix, variableMapJson, variableCss, themeJson, contextualVarsJson) {
+	if (!prefix) return {
+		variableMapJson,
+		variableCss,
+		themeJson,
+		contextualVarsJson
+	};
+	const varRefRe = /var\(--([a-zA-Z][\w-]*)\)/g;
+	const map = JSON.parse(variableMapJson);
+	const prefixed = {};
+	for (const [key, varName] of Object.entries(map)) prefixed[key] = varName.startsWith("--") ? `--${prefix}-${varName.slice(2)}` : varName;
+	let css = variableCss;
+	css = css.replace(/--([a-zA-Z][\w-]*)\s*:/g, `--${prefix}-$1:`);
+	css = css.replace(varRefRe, `var(--${prefix}-$1)`);
+	const result = {
+		variableMapJson: JSON.stringify(prefixed),
+		variableCss: css
+	};
+	if (themeJson) result.themeJson = themeJson.replace(varRefRe, `var(--${prefix}-$1)`);
+	if (contextualVarsJson) {
+		const ctxVars = JSON.parse(contextualVarsJson);
+		const prefixedCtx = {};
+		for (const [scale, names] of Object.entries(ctxVars)) prefixedCtx[scale] = names.map((name) => `${prefix}-${name}`);
+		result.contextualVarsJson = JSON.stringify(prefixedCtx);
+	}
+	return result;
+}
+//#endregion
+//#region pipeline/system-config.ts
+/**
+* Load a SystemInstance via the engine's `loadSystemModule` and normalize
+* it into a SystemConfig. When `prefix` is set, CSS variable names in the
+* variable map/css (and theme + contextual vars when affected) are
+* namespaced via the shared `applyPrefix`.
+*
+* Error handling stays at the call site — the Vite plugin warns (or throws
+* in strict mode) and keeps its previous config, the Next plugin lets the
+* failure propagate.
+*/
+function loadSystemConfig(engineApi, opts) {
+	const { loadSystemModule } = engineApi();
+	const config = loadSystemModule(opts.systemPath, opts.rootDir);
+	let scalesJson = config.scalesJson;
+	let variableMapJson = config.variableMapJson;
+	let variableCss = config.variableCss;
+	let contextualVarsJson = config.contextualVarsJson || null;
+	if (opts.prefix) {
+		const prefixed = applyPrefix(opts.prefix, variableMapJson, variableCss, scalesJson, contextualVarsJson || void 0);
+		variableMapJson = prefixed.variableMapJson;
+		variableCss = prefixed.variableCss;
+		if (prefixed.themeJson) scalesJson = prefixed.themeJson;
+		if (prefixed.contextualVarsJson) contextualVarsJson = prefixed.contextualVarsJson;
+	}
+	return {
+		propConfigJson: config.propConfig,
+		groupRegistryJson: config.groupRegistry,
+		scalesJson,
+		variableMapJson,
+		variableCss,
+		contextualVarsJson,
+		selectorAliasesJson: config.selectorAliases || null,
+		conditionAliasesJson: config.conditionAliases || null,
+		globalStyleBlocksJson: config.globalStyleBlocks || null,
+		keyframesJson: config.keyframesBlocks || null,
+		dependencies: config.dependencies ?? []
+	};
+}
+//#endregion
+//#region pipeline/dynamic-prop-config.ts
+function buildDynamicPropConfig(dynamicProps) {
+	const configEntries = {};
+	for (const [propName, meta] of Object.entries(dynamicProps)) configEntries[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 } : {}
+	};
+	return configEntries;
+}
+//#endregion
+//#region pipeline/system-props-module.ts
+/**
+* Build the source of the runtime system-props module — served as
+* `virtual:animus/system-props` by the Vite plugin and written to
+* `.animus/system-props.js` by the Next plugin. One generator so the two
+* runtimes can never drift.
+*
+* Runtime transform functions for dynamic props are not yet supported
+* (transforms are resolved at extraction time via boa_engine in Rust), so
+* `transforms` defaults to an empty object literal.
+*/
+function buildSystemPropsModule(opts) {
+	const dynamicPropConfig = buildDynamicPropConfig(opts.dynamicProps);
+	return `export const systemPropMap = ${opts.systemPropMapJson};\nexport const systemPropGroups = ${opts.groupRegistryJson};\nexport const dynamicPropConfig = ${JSON.stringify(dynamicPropConfig)};\nexport const transforms = ${opts.transformsSource ?? "{}"};\n`;
+}
+//#endregion
+//#region pipeline/timing-waterfall.ts
+/**
+* Rust-side timing phases as reported in `manifest.timing`, in waterfall
+* order, with their display labels. Mirrors the timing struct in the
+* extract-v2 crate — a renamed or added Rust phase is updated here once,
+* not per plugin.
+*/
+const RUST_TIMING_PHASES = [
+	["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"]
+];
+/**
+* Format the Rust timing waterfall as log lines. `indent` and `labelWidth`
+* let each plugin keep its established column layout; the phase table and
+* the `(N files, M cached)` suffix are shared.
+*/
+function formatRustTimingWaterfall(timing, opts) {
+	const lines = [];
+	for (const [key, label] of RUST_TIMING_PHASES) {
+		const ms = timing[key] ?? 0;
+		const pad = " ".repeat(Math.max(0, opts.labelWidth - label.length));
+		const extra = key === "parseAndWalk" ? `  (${timing.fileCount ?? 0} files, ${timing.cacheHits ?? 0} cached)` : "";
+		lines.push(`${opts.indent}${label}${pad}${String(ms).padStart(5)}ms${extra}`);
+	}
+	return lines;
+}
+//#endregion
+//#region pipeline/tsconfig-paths.ts
+/**
+* tsconfig `paths` → alias pairs for the Rust `pathAliasesJson` contract
+* (via `buildPathAliasesJson`). Used by drivers that cannot harvest aliases
+* from a live bundler config — Turbopack exposes none.
+*
+* Semantics (deliberately the TypeScript subset that matters for import
+* provenance): JSONC tolerated (comments + trailing commas); `extends`
+* chains followed (string or array; missing parents and cycles skipped);
+* the NEAREST config declaring `paths` wins wholesale (TS replaces the
+* object, never merges); targets resolve against the nearest `baseUrl`
+* (resolved from its declaring config's directory) or, absent one, the
+* directory of the config declaring `paths`; first target per pattern.
+* `x/*` patterns become prefix pairs, non-wildcard patterns exact pairs,
+* bare `*` catch-alls and mid-pattern wildcards are skipped.
+*/
+/** String-aware JSONC → JSON: strips // and block comments + trailing commas. */
+function stripJsonc(text) {
+	let out = "";
+	let inString = false;
+	let inLine = false;
+	let inBlock = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		const next = text[i + 1];
+		if (inLine) {
+			if (ch === "\n") {
+				inLine = false;
+				out += ch;
+			}
+			continue;
+		}
+		if (inBlock) {
+			if (ch === "*" && next === "/") {
+				inBlock = false;
+				i++;
+			}
+			continue;
+		}
+		if (inString) {
+			out += ch;
+			if (ch === "\\") {
+				out += next ?? "";
+				i++;
+			} else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = true;
+			out += ch;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			inLine = true;
+			i++;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			inBlock = true;
+			i++;
+			continue;
+		}
+		out += ch;
+	}
+	return out.replace(/,(\s*[}\]])/g, "$1");
+}
+function readConfig(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		const json = JSON.parse(stripJsonc(raw));
+		return {
+			dir: dirname(path),
+			compilerOptions: json.compilerOptions ?? {},
+			extends: json.extends
+		};
+	} catch {
+		return null;
+	}
+}
+function resolveExtendsTarget(specifier, fromDir) {
+	if (specifier.startsWith(".") || isAbsolute(specifier)) {
+		const base = resolve(fromDir, specifier);
+		for (const candidate of [
+			base,
+			`${base}.json`,
+			join(base, "tsconfig.json")
+		]) if (existsSync(candidate)) return candidate;
+		return null;
+	}
+	try {
+		return __require.resolve(specifier.endsWith(".json") ? specifier : `${specifier}/tsconfig.json`, { paths: [fromDir] });
+	} catch {
+		try {
+			return __require.resolve(specifier, { paths: [fromDir] });
+		} catch {
+			return null;
+		}
+	}
+}
+/** Child-first flattened extends chain starting at `entryPath`. */
+function loadChain(entryPath) {
+	const chain = [];
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [entryPath];
+	while (queue.length > 0) {
+		const key = resolve(queue.shift());
+		if (visited.has(key)) continue;
+		visited.add(key);
+		const node = readConfig(key);
+		if (!node) continue;
+		chain.push(node);
+		const parents = Array.isArray(node.extends) ? node.extends : node.extends !== void 0 ? [node.extends] : [];
+		for (const parent of parents) {
+			if (typeof parent !== "string") continue;
+			const resolved = resolveExtendsTarget(parent, node.dir);
+			if (resolved) queue.push(resolved);
+		}
+	}
+	return chain;
+}
+/**
+* Read the project's tsconfig path aliases as pairs consumable by
+* `buildPathAliasesJson`. Returns an empty array when no readable tsconfig
+* (or no usable `paths`) exists.
+*/
+function readTsconfigAliasPairs(rootDir) {
+	const chain = loadChain(join(rootDir, "tsconfig.json"));
+	if (chain.length === 0) return [];
+	const pathsOwner = chain.find((node) => node.compilerOptions.paths && typeof node.compilerOptions.paths === "object");
+	if (!pathsOwner) return [];
+	const paths = pathsOwner.compilerOptions.paths;
+	const baseOwner = chain.find((node) => typeof node.compilerOptions.baseUrl === "string");
+	const base = baseOwner ? resolve(baseOwner.dir, baseOwner.compilerOptions.baseUrl) : pathsOwner.dir;
+	const pairs = [];
+	for (const [pattern, targets] of Object.entries(paths)) {
+		const target = Array.isArray(targets) ? targets[0] : void 0;
+		if (typeof target !== "string") continue;
+		const patternStars = pattern.split("*").length - 1;
+		const targetStars = target.split("*").length - 1;
+		if (pattern === "*" || patternStars > 1 || targetStars > 1) continue;
+		if (pattern.endsWith("/*")) {
+			if (!target.endsWith("/*")) continue;
+			pairs.push({
+				pattern: pattern.slice(0, -2),
+				target: resolve(base, target.slice(0, -2)),
+				kind: "prefix"
+			});
+			continue;
+		}
+		if (patternStars > 0 || targetStars > 0) continue;
+		pairs.push({
+			pattern,
+			target: resolve(base, target),
+			kind: "exact"
+		});
+	}
+	return pairs;
+}
+//#endregion
 //#region pipeline/mdx-preprocessor.ts
 /**
 * MDX source preprocessor for the extraction pipeline.
@@ -190,190 +1036,55 @@ async function preprocessMdx(source, filename) {
 	}
 }
 //#endregion
-//#region pipeline/prefix.ts
-/**
-* Apply namespace prefix to a variable map, CSS variable declarations, and theme JSON.
-*
-* Variable map: `{ "colors.ember": "--color-ember" }` -> `{ "colors.ember": "--prefix-color-ember" }`
-* Variable CSS: `--color-ember: #FF2800` -> `--prefix-color-ember: #FF2800`
-*               `var(--color-ember)` -> `var(--prefix-color-ember)`
-* Theme JSON:   `{ "colors.ember": "var(--color-ember)" }` -> `{ "colors.ember": "var(--prefix-color-ember)" }`
-*/
-function applyPrefix(prefix, variableMapJson, variableCss, themeJson, contextualVarsJson) {
-	if (!prefix) return {
-		variableMapJson,
-		variableCss,
-		themeJson,
-		contextualVarsJson
-	};
-	const varRefRe = /var\(--([a-zA-Z][\w-]*)\)/g;
-	const map = JSON.parse(variableMapJson);
-	const prefixed = {};
-	for (const [key, varName] of Object.entries(map)) prefixed[key] = varName.startsWith("--") ? `--${prefix}-${varName.slice(2)}` : varName;
-	let css = variableCss;
-	css = css.replace(/--([a-zA-Z][\w-]*)\s*:/g, `--${prefix}-$1:`);
-	css = css.replace(varRefRe, `var(--${prefix}-$1)`);
-	const result = {
-		variableMapJson: JSON.stringify(prefixed),
-		variableCss: css
-	};
-	if (themeJson) result.themeJson = themeJson.replace(varRefRe, `var(--${prefix}-$1)`);
-	if (contextualVarsJson) {
-		const ctxVars = JSON.parse(contextualVarsJson);
-		const prefixedCtx = {};
-		for (const [scale, names] of Object.entries(ctxVars)) prefixedCtx[scale] = names.map((name) => `${prefix}-${name}`);
-		result.contextualVarsJson = JSON.stringify(prefixedCtx);
-	}
-	return result;
-}
-//#endregion
 //#region pipeline/utils.ts
 /** Convert camelCase CSS property names to kebab-case. */
 function camelToKebab(str) {
 	return str.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
 }
 //#endregion
-//#region pipeline/resolve-global-styles.ts
-/**
-* Resolve {scale.path} and {scale.path/alpha} token aliases in a CSS value string.
-* Mirrors the Rust theme_resolver's resolve_token_aliases logic.
-*/
-function resolveTokenAliases(value, flat, variableMap) {
-	if (!value.includes("{")) return value;
-	return value.replace(/\{([^}]+)\}/g, (_match, content) => {
-		const slashIdx = content.indexOf("/");
-		const tokenPath = slashIdx >= 0 ? content.slice(0, slashIdx) : content;
-		const alpha = slashIdx >= 0 ? Number.parseInt(content.slice(slashIdx + 1), 10) : null;
-		const flatKey = tokenPath;
-		let resolved;
-		if (variableMap[flatKey]) resolved = `var(${variableMap[flatKey]})`;
-		else if (flat[flatKey] != null) resolved = flat[flatKey];
-		else return `{${content}}`;
-		if (alpha === 0) return "transparent";
-		if (alpha != null && alpha !== 100) return `color-mix(in srgb, ${resolved} ${alpha}%, transparent)`;
-		return resolved;
-	});
-}
-/**
-* Resolve a single CSS value through prop config: scale lookup, transform, token aliases.
-*/
-function resolveValue(raw, config, flat, variableMap, transforms) {
-	let resolved = String(raw);
-	if (config?.scale) {
-		const key = config.scale + "." + raw;
-		if (flat[key] != null) resolved = flat[key];
-	}
-	if (config?.transform && transforms[config.transform]) {
-		const fn = transforms[config.transform];
-		const input = typeof resolved === "string" && !Number.isNaN(Number(resolved)) ? Number(resolved) : resolved;
-		resolved = String(fn(input));
-	}
-	return resolveTokenAliases(resolved, flat, variableMap);
-}
-/**
-* Resolve a block of selectors -> style objects using prop config + theme.
-* @keyframes selectors are resolved with full prop config support.
-*/
-function resolveBlock(selectors, propConfig, flat, variableMap, transforms) {
-	const rules = [];
-	for (const [selector, styleObj] of Object.entries(selectors)) {
-		if (selector.startsWith("@keyframes")) {
-			const frames = [];
-			for (const [pct, frameStyles] of Object.entries(styleObj)) if (typeof frameStyles === "object" && frameStyles !== null) {
-				const decls = [];
-				for (const [prop, raw] of Object.entries(frameStyles)) {
-					const cfg = propConfig[prop];
-					const cssProps = cfg?.properties?.length ? cfg.properties : cfg ? [cfg.property] : [prop];
-					const resolved = resolveValue(raw, cfg, flat, variableMap, transforms);
-					for (const cssProp of cssProps) decls.push(`    ${camelToKebab(cssProp)}: ${resolved};`);
-				}
-				frames.push(`  ${pct} {\n${decls.join("\n")}\n  }`);
-			}
-			rules.push(`${selector} {\n${frames.join("\n")}\n}`);
-			continue;
-		}
-		const decls = [];
-		for (const [prop, raw] of Object.entries(styleObj)) {
-			const config = propConfig[prop];
-			const cssProps = config?.properties?.length ? config.properties : config ? [config.property] : [prop];
-			const resolved = resolveValue(raw, config, flat, variableMap, transforms);
-			for (const cssProp of cssProps) decls.push(`  ${camelToKebab(cssProp)}: ${resolved};`);
-		}
-		if (decls.length) rules.push(`${selector} {\n${decls.join("\n")}\n}`);
-	}
-	return rules.join("\n\n");
-}
+//#region pipeline/watch-keys.ts
 /**
-* Resolve global style blocks into CSS strings.
+* Membership keys for a filesystem path in the system-dependency watch set.
 *
-* Takes the global style map (block name -> selectors -> props -> values),
-* resolves prop shorthand, scale lookups, transforms, and token aliases,
-* and returns a map of block name -> resolved CSS string.
-*/
-function resolveGlobalStyles(globalStyles, propConfig, flat, variableMap, transforms) {
-	const result = {};
-	for (const [name, block] of Object.entries(globalStyles)) {
-		const resolved = resolveBlock(block, propConfig, flat, variableMap, transforms);
-		if (resolved) result[name] = resolved;
-	}
-	return result;
+* The loader reports symlink-resolved canonical paths; watcher events carry
+* lexical absolute paths that may traverse symlinks (bun workspace links) and
+* — for deletions — may no longer exist, so `realpathSync` on the event path
+* alone cannot produce the canonical form. Both insertion and lookup go
+* through this one normalizer: the lexical form plus a canonical form
+* reconstructed through the nearest existing ancestor.
+*/
+function toWatchKeys(input) {
+	const lexical = normalize(input);
+	const canonical = realpathThroughNearestExistingAncestor(lexical);
+	return canonical === lexical ? [lexical] : [lexical, canonical];
 }
-//#endregion
-//#region pipeline/resolve-transforms.ts
 /**
-* Resolve __TRANSFORM__ placeholders in extracted CSS.
+* Canonicalize a path that may not exist: walk up to the nearest existing
+* ancestor, realpath it, and re-append the missing suffix. Handles deleted
+* files under still-existing (possibly symlinked) directories and atomic
+* unlink/rename saves. Falls back to the input when no ancestor resolves.
 *
-* Pattern: `__TRANSFORM__name__rawValue__` -> transform function result.
-* The Rust crate emits these placeholders for CSS values that require
-* JS transform functions (e.g., size, grid) which can't be evaluated in Rust.
-*/
-function resolveTransformPlaceholders(css, transforms) {
-	return css.replace(/__TRANSFORM__(\w+)__(.+?)__/g, (_, name, rawValue) => {
-		const fn = transforms[name];
-		if (!fn) return rawValue;
-		const result = fn(rawValue !== "" && !Number.isNaN(Number(rawValue)) ? Number(rawValue) : rawValue);
-		return typeof result === "object" ? JSON.stringify(result) : String(result);
-	});
-}
-//#endregion
-//#region pipeline/unit-fallback.ts
-/**
-* Append `px` to bare numeric values in CSS declarations for properties
-* that expect length units. Unitless properties are preserved as-is.
-* Numbers inside CSS function calls (cubic-bezier, rgb, calc, etc.) are skipped.
+* Known limit: a symlink retargeted AFTER the system load canonicalizes to
+* the new target, which cannot match the recorded (old-target) dependency —
+* the membership test then fails open (no reset), identical to not having
+* this reconstruction at all. Retarget sensitivity is a resolution-input
+* concern, deliberately out of scope for the watch set.
 */
-function applyUnitFallback(css) {
-	return css.replace(/([a-z-]+)\s*:\s*([^;{}]+);/g, (match, prop, value) => {
-		if (UNITLESS_PROPERTIES.has(prop)) return match;
-		let depth = 0;
-		let fixed = "";
-		let i = 0;
-		while (i < value.length) if (value[i] === "(") {
-			depth++;
-			fixed += value[i];
-			i++;
-		} else if (value[i] === ")") {
-			depth--;
-			fixed += value[i];
-			i++;
-		} else if (depth > 0) {
-			fixed += value[i];
-			i++;
-		} else {
-			const numMatch = value.slice(i).match(/^(-?\d+\.?\d*)/);
-			if (numMatch) {
-				const num = numMatch[1];
-				const after = value[i + num.length];
-				if (after && /[a-z%]/i.test(after)) fixed += num;
-				else fixed += num + "px";
-				i += num.length;
-			} else {
-				fixed += value[i];
-				i++;
-			}
-		}
-		return fixed !== value ? `${prop}:${fixed};` : match;
-	});
+function realpathThroughNearestExistingAncestor(path) {
+	try {
+		return realpathSync(path);
+	} catch {}
+	const suffix = [];
+	let current = path;
+	for (;;) {
+		const parent = dirname$1(current);
+		if (parent === current) return path;
+		suffix.unshift(basename(current));
+		current = parent;
+		try {
+			return join$1(realpathSync(current), ...suffix);
+		} catch {}
+	}
 }
 //#endregion
-export { ANIMUS_LAYERS, DEFAULT_EXTENSIONS, applyPrefix, applyUnitFallback, assembleStylesheet, camelToKebab, extractSystemFilePackages, preprocessMdx, resolveGlobalStyles, resolveTokenAliases, resolveTransformPlaceholders, resolveValue, stripLeadingLayerDeclaration, validateLayerOrder };
+export { ANIMUS_LAYERS, DEFAULT_EXTENSIONS, RETIRED_ENGINE_MESSAGE, applyPrefix, applyUnitFallback, assembleStylesheet, assertNoRetiredEngineSelection, buildAnalysisInputs, buildAnalyzeProjectArgs, buildDynamicPropConfig, buildPathAliasesJson, buildSystemPropsModule, camelToKebab, clearEngineCache, collectExternalPackageSources, contentHash, createV2EngineApi, discoverFiles, extractSystemFilePackages, findPackageRoot, formatRustTimingWaterfall, loadSystemConfig, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveLightningTargets, runProjectAnalysis, serializeStaticCss, stripLeadingLayerDeclaration, surfaceManifestDiagnostics, toWatchKeys, validateLayerOrder };