@animus-ui/unplugin 0.1.11

package/README.md

@@ -0,0 +1,101 @@
+# @animus-ui/unplugin
+
+Animus transform host for non-plugin bundlers — rollup, esbuild, rspack,
+and webpack entry points over the one extraction session. Transforms
+`@animus-ui/system` builder chains into static CSS at build time, delivers
+the stylesheet as a real emitted asset (`animus.css`), and supplies the
+`__ANIMUS_DEV__` define.
+
+Vite users: use [`@animus-ui/vite-plugin`](../vite-plugin). Next.js users:
+use [`@animus-ui/next-plugin`](../next-plugin). The root export's reachable
+`.vite` adapter is **unsupported** — the supported surface is exactly the
+four subpath entries below.
+
+## Install
+
+```bash
+npm install --save-dev @animus-ui/unplugin
+npm install @animus-ui/system
+```
+
+Requires Node `>=22.12.0`. Native engine binaries ship for darwin-arm64,
+linux-x64-gnu, and linux-arm64-gnu.
+
+## Setup (rollup)
+
+<!-- source lane: e2e/rollup-app/rollup.config.mjs (lane pinning removed); verified by running the lane build and the genericized shape against the lane sources — both exit 0 and emit animus.css -->
+
+```js
+// rollup.config.mjs — ESM configs use the NAMED export.
+import { animusRollup as animus } from '@animus-ui/unplugin/rollup';
+import esbuild from 'rollup-plugin-esbuild';
+
+export default {
+  input: 'src/entry.tsx',
+  plugins: [
+    // The host FIRST: its transform must see raw TSX (rollup has no
+    // enforce ordering — config order is the law).
+    animus({ system: './src/ds.ts', strict: true }),
+    esbuild({ jsx: 'automatic', target: 'es2022' }),
+  ],
+  output: { dir: 'dist', format: 'esm' },
+};
+```
+
+The other bundlers follow the same shape from their own subpaths:
+`animusEsbuild` from `@animus-ui/unplugin/esbuild`, `animusRspack` from
+`@animus-ui/unplugin/rspack`, `animusWebpack` from
+`@animus-ui/unplugin/webpack`. In CJS config files use the default export:
+
+<!-- source lane: package export shape proven by e2e/rollup-app; verified by running `node -e "require('@animus-ui/unplugin/rollup').default"` from the lane (a function) -->
+
+```js
+// CJS config files:
+const animus = require('@animus-ui/unplugin/rollup').default;
+```
+
+A Node-ESM **default** import of the CJS build binds the exports object,
+not the plugin function — in ESM configs, always use the named export.
+
+## Plugin ordering
+
+The extraction engine parses **raw TSX** — this host's transform must run
+before any TS/JSX transpilation. `enforce: 'pre'` orders webpack and rspack
+loader chains automatically; **rollup consumers must list this plugin
+before their transpiler** in the config. Mis-ordered builds emit a
+source-drift warning (`transform-time source … differs from analyze-time
+source`) followed by a bundler parse error on TSX syntax — move the Animus
+plugin first to fix it.
+
+## What it does
+
+- Runs the one `ExtractionSession` at `buildStart` inside your bundler's
+  process; per-file transforms come from retained engine state. Analysis
+  failure is build failure — never a silent passthrough.
+- Resolves the stylesheet id (`.animus/styles.css`), the system-props id,
+  and one redirect per admitted design-system kit specifier to the exact
+  entry extraction analyzed. tsconfig `paths` are the alias source.
+- Emits the extracted stylesheet as a real `animus.css` asset (for esbuild:
+  written into `outdir`, or beside `outfile`).
+- Supplies the `__ANIMUS_DEV__` dev-signal define through each bundler's
+  own mechanism.
+
+## Options
+
+Options are the shared driver core (`system`, `exclude`, `strict`, `mode`,
+`targets`, `minify`, …); unknown keys fail loud. `mode`
+(`'development' | 'production'`) selects **emission only** — the minify
+default, the dev-signal define, engine dev diagnostics — never process
+lifecycle. When absent, the bundler's own command oracle applies (webpack/
+rspack `compiler.options.mode`, rollup watch mode), else `production`
+(esbuild exposes no signal). `exclude` patterns are glob-aware and MERGE
+with the defaults (`node_modules`, `dist`, `.test.`, `.spec.`, `.next`,
+`.animus`).
+
+The full consumer contract — module-id families, the define contract,
+artifact set, platform matrix — lives in the
+[standalone extraction contract](https://github.com/codecaaron/animus/blob/main/docs/standalone-extraction.md).
+
+## License
+
+MIT

package/dist/core-B2NB6x1D.cjs

@@ -0,0 +1,425 @@
+let _animus_ui_extract_pipeline = require("@animus-ui/extract/pipeline");
+let _animus_ui_extract_session = require("@animus-ui/extract/session");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+//#region src/options.ts
+/**
+* Host option intake — the transform host is the fourth driver over the
+* shared option core (openspec: standalone-extraction-cli, D2/D9): one
+* schema, `assertKnownOptionKeys` at the boundary, and an explicit
+* emission `mode` that is plumbed — never environment-sniffed (D10).
+*
+* Unlike the Vite/Next plugin drivers, this host HONORS the core `root`
+* key: rollup and esbuild expose no root authority a plugin could derive,
+* so the host's root is the explicit option, defaulting to the process
+* working directory (the CLI's shape, not the plugin drivers').
+*/
+/**
+* Validate raw options and resolve the root authority. Throws
+* `AnimusConfigError` (the shared config-error class) on unknown keys,
+* invalid `mode` values, a retired engine selection, or a missing
+* `system`.
+*/
+function resolveHostOptions(raw, cwd = process.cwd()) {
+	const options = raw ?? {};
+	(0, _animus_ui_extract_pipeline.assertNoRetiredEngineSelection)(options.engine);
+	(0, _animus_ui_extract_pipeline.assertKnownOptionKeys)(options);
+	if (typeof options.system !== "string" || options.system.length === 0) throw new _animus_ui_extract_pipeline.AnimusConfigError("Missing required option `system` — pass `system: \"./src/ds.ts\"` to the Animus plugin.");
+	return {
+		root: options.root ? (0, node_path.resolve)(cwd, options.root) : cwd,
+		options
+	};
+}
+/**
+* Resolve the effective emission mode: the explicit option wins over every
+* bundler signal; otherwise the adapter-supplied command oracle applies;
+* otherwise production (the documented host default — never NODE_ENV).
+*/
+function resolveHostMode(explicit, oracle) {
+	return (0, _animus_ui_extract_pipeline.resolveMode)(explicit, () => oracle ?? "production").mode;
+}
+//#endregion
+//#region src/core.ts
+/**
+* The Animus transform host core (openspec: standalone-extraction-cli,
+* D4 under D10): an unplugin factory that drives the ONE
+* `ExtractionSession` at buildStart inside the consumer's bundler process
+* and serves per-file transforms from retained engine state. No artifacts,
+* no lock, no staleness protocol — analysis failure IS build failure,
+* never a passthrough (the session's strict/policy seams carry this).
+*
+* Ported from the winning DEF-1 prototype arm
+* (e2e/rollup-app/prototype/animus-t0-plugin.mjs), productized per the
+* inc 05 packet: the emitted CSS reaches the consumer as a real asset
+* (NS3 — the prototype's CSS-as-string module was measurement
+* scaffolding), `__ANIMUS_DEV__` goes through each adapter's define
+* mechanism, kit-specifier redirects come from the session's discovery
+* output (the Turbopack alias assembly generalized), and the session
+* directory is cleaned on success AND failure (inc 04 rider F6).
+*
+* ORDERING CONTRACT: the host transform must run before any TS/JSX
+* transpilation — the engine parses raw TSX. `enforce: 'pre'` covers
+* webpack/rspack; rollup consumers must list this plugin before their
+* transpiler (see the e2e/rollup-app lane config).
+*/
+/** Resolved virtual id of the stylesheet import. Deliberately
+*  extension-free: esbuild guesses loaders from extensions, and this
+*  module is a JS stub in every bundler — the CSS itself is delivered as
+*  an emitted asset, never as a module (NS3). No `\0` prefix: webpack's
+*  virtual-module bridge requires plain ids. */
+const STYLES_VIRTUAL_ID = "animus:styles";
+/** Resolved virtual id of the emitted system-props runtime module. */
+const PROPS_VIRTUAL_ID = "animus:system-props";
+/** File name of the emitted stylesheet asset. */
+const CSS_ASSET_NAME = "animus.css";
+/** Files the engine transform may rewrite — derived from the ONE shared
+*  extension set (also the Turbopack rule glob's source). */
+const ENGINE_TRANSFORM_RE = new RegExp(`\\.(?:${_animus_ui_extract_pipeline.ENGINE_TRANSFORM_EXTENSIONS.join("|")})$`);
+/** Files the transform hook claims at all (define substitution included —
+*  `.cjs` carries no components but may read the dev-signal token). */
+const TRANSFORM_INCLUDE_RE = new RegExp(`\\.(?:${[..._animus_ui_extract_pipeline.ENGINE_TRANSFORM_EXTENSIONS, "cjs"].join("|")})$`);
+/** Bare dev-signal token, assignment-guarded like @rollup/plugin-replace's
+*  `preventAssignment` — `__ANIMUS_DEV__ = x` is left alone. */
+const DEV_DEFINE_RE = /\b__ANIMUS_DEV__\b(?!\s*=[^=])/g;
+function createHostState() {
+	return {
+		pipeline: null,
+		mode: null,
+		cssText: "",
+		systemPropsJs: "",
+		kitRedirects: /* @__PURE__ */ new Map(),
+		redirectTargets: /* @__PURE__ */ new Set(),
+		externalPackageDirs: [],
+		watchPaths: [],
+		transformFile: null,
+		sessionDir: null
+	};
+}
+/**
+* The transform-claim predicate over module paths. The analysis universe
+* deliberately excludes node_modules (external kits ride their own
+* collection path), so the transform must too — the Next webpack rule's
+* exclude, ported: without it every dependency module in the graph is
+* routed through the engine, scaling build time with dependency-graph size
+* instead of source-file count. node_modules paths are claimed only when
+* they belong to an ADMITTED external package (or are a kit redirect
+* target) — those carry builder chains the engine must rewrite. Such files
+* only enter the module graph after discovery published (their specifiers
+* resolve through the pipeline-gated kitRedirects), so consulting captured
+* state here is race-free.
+*/
+function shouldClaimTransform(filePath, state) {
+	if (!filePath.includes("node_modules")) return true;
+	return state.redirectTargets.has(filePath) || state.externalPackageDirs.some((dir) => (0, _animus_ui_extract_pipeline.isPathWithinRoot)(dir, filePath));
+}
+/** Remove the one-shot session tree; idempotent, runs on success AND
+*  failure paths (inc 04 rider F6). */
+function disposeSessionDir(state, removeDir = (dir) => (0, node_fs.rmSync)(dir, {
+	recursive: true,
+	force: true
+})) {
+	if (state.sessionDir) {
+		removeDir(state.sessionDir);
+		state.sessionDir = null;
+	}
+}
+/**
+* Run one pipeline attempt through the shared drive loop, recording it as
+* `state.pipeline` for hook joiners. A failed attempt disposes the session
+* directory before rethrowing — the consumer's build fails; nothing leaks.
+*/
+async function drivePipeline(state, run, removeDir) {
+	const attempt = run();
+	state.pipeline = attempt;
+	try {
+		await attempt;
+	} catch (error) {
+		if (!state.sessionDir) state.sessionDir = (0, _animus_ui_extract_session.getSessionArtifactDir)();
+		disposeSessionDir(state, removeDir);
+		throw error;
+	}
+}
+/**
+* Map an import id onto the host's CONSTANT resolution family: the
+* stylesheet id and the system-props id — the mappings that answer without
+* the pipeline. Kit-specifier redirects are the caller's second step (they
+* exist only after discovery published, behind the pipeline join).
+*/
+function resolveAnimusId(id) {
+	if (id === _animus_ui_extract_session.ANIMUS_CSS_MODULE_ID || id.endsWith(`/${_animus_ui_extract_session.ANIMUS_CSS_MODULE_ID}`)) return STYLES_VIRTUAL_ID;
+	if (id === "animus:styles" || id === "animus:system-props") return id;
+	if (id === _animus_ui_extract_session.TURBOPACK_SYSTEM_PROPS_ID) return PROPS_VIRTUAL_ID;
+	return null;
+}
+/**
+* Substitute the bare `__ANIMUS_DEV__` token with its boolean literal —
+* the define mechanism for bundlers without a native one (rollup). The
+* token-as-initializer-conditional shape in the system runtime's is-dev
+* module folds under the bundler's own dead-branch elimination once the
+* literal lands. Returns null when the code carries no token.
+*/
+function substituteDevDefine(code, isDev) {
+	if (!code.includes("__ANIMUS_DEV__")) return null;
+	return code.replace(DEV_DEFINE_RE, isDev ? "true" : "false");
+}
+/**
+* Per-file engine transform from retained state. The path handed to the
+* engine is the rootDir-relative posix key the analysis used — external
+* kit sources ride the same derivation (`../…` keys). Files outside the
+* analysis universe come back unchanged (`hasComponents: false`); a
+* transform before analysis fails loud inside the engine adapter.
+*/
+function transformWithEngine(code, id, ctx) {
+	const filename = (0, node_path.relative)(ctx.rootDir, (0, node_path.resolve)(id)).split("\\").join("/");
+	const result = ctx.transformFile(code, filename, ctx.manifestJson);
+	return result.hasComponents ? result.code : null;
+}
+/** Strip a bundler query suffix (`?worker`, webpack resource queries). */
+function moduleFilePath(id) {
+	const query = id.indexOf("?");
+	return query === -1 ? id : id.slice(0, query);
+}
+const PLUGIN_NAME = "animus-host";
+/**
+* The one-live-host-per-process constraint, enforced where the invariant
+* lives: the SESSION singleton (its slots are what concurrent hosts would
+* clobber). Re-exported under the host's historical name; the key sits in
+* `SINGLETON_GLOBAL_KEYS`, so test harness resets clear a leaked claim.
+*/
+const claimProcessHost = _animus_ui_extract_session.claimExclusiveSessionOwner;
+/**
+* The unplugin factory. One factory invocation = one host = one session
+* per build; the singleton drive loop stays exactly-one (guardrail G1 —
+* the host defines no session class and no drive loop of its own).
+*/
+const unpluginFactory = (rawOptions, meta) => {
+	const { root, options } = resolveHostOptions(rawOptions);
+	const state = createHostState();
+	/** Release handle of this host's process claim, or null when not held. */
+	let releaseHostClaim = null;
+	/** Adapter-supplied command oracle (null = no bundler signal). */
+	let modeOracle = null;
+	let esbuildOptions = null;
+	/** Resolves once buildStart has begun — hooks that can fire before the
+	*  bundler-parallel buildStart (webpack's make taps run concurrently)
+	*  wait on this, then join the pipeline itself. */
+	let signalPipelineStarted;
+	const pipelineStarted = new Promise((res) => {
+		signalPipelineStarted = res;
+	});
+	const effectiveMode = () => resolveHostMode(options.mode, modeOracle);
+	/** The define is supplied natively where the bundler has a mechanism
+	*  (esbuild define, webpack/rspack DefinePlugin); everywhere else the
+	*  transform substitutes the token itself. */
+	const needsInlineDefine = meta.framework !== "esbuild" && meta.framework !== "webpack" && meta.framework !== "rspack";
+	async function startPipeline() {
+		signalPipelineStarted();
+		releaseHostClaim = claimProcessHost(`${PLUGIN_NAME}:${root}`);
+		try {
+			await runClaimedPipeline();
+		} catch (error) {
+			releaseClaim();
+			throw error;
+		}
+	}
+	function releaseClaim() {
+		releaseHostClaim?.();
+		releaseHostClaim = null;
+	}
+	async function runClaimedPipeline() {
+		await drivePipeline(state, async () => {
+			const mode = effectiveMode();
+			state.mode = mode;
+			const session = new _animus_ui_extract_session.ExtractionSession({
+				...options,
+				mode
+			});
+			session.driverLabel = "animus-unplugin";
+			session.rootDir = root;
+			session.systemPropsModuleId = _animus_ui_extract_session.TURBOPACK_SYSTEM_PROPS_ID;
+			const builtAliases = (0, _animus_ui_extract_pipeline.buildPathAliasesJson)((0, _animus_ui_extract_pipeline.readTsconfigAliasPairs)(root), root);
+			if (builtAliases) session.pathAliasesJson = builtAliases.json;
+			await session.runFullPipeline();
+			state.sessionDir = (0, _animus_ui_extract_session.getSessionArtifactDir)();
+			const analyzed = (0, _animus_ui_extract_session.getAnalyzedHashes)();
+			if (!analyzed || analyzed.size === 0) throw new Error(`[animus] discovery found zero source files under ${root} — check the plugin's \`root\` and \`exclude\` options`);
+			state.cssText = (0, _animus_ui_extract_session.getSharedCss)();
+			state.systemPropsJs = (0, _animus_ui_extract_session.getSharedSystemProps)();
+			state.kitRedirects = new Map(session.externalSourceEntries);
+			state.redirectTargets = new Set(state.kitRedirects.values());
+			state.externalPackageDirs = [...session.externalPackageDirs];
+			const watchPaths = /* @__PURE__ */ new Set();
+			for (const key of (0, _animus_ui_extract_session.getAnalyzedHashes)()?.keys() ?? []) watchPaths.add((0, node_path.resolve)(root, key));
+			for (const dep of session.systemDependencyPaths) watchPaths.add(dep);
+			for (const dep of session.assetDependencyPaths) watchPaths.add(dep);
+			watchPaths.add((0, node_path.join)(root, "tsconfig.json"));
+			state.watchPaths = [...watchPaths];
+			state.transformFile = (0, _animus_ui_extract_session.engineApi)().transformFile;
+		});
+	}
+	/** Join the analysis: every serving hook waits for buildStart to have
+	*  begun, then for the pipeline to have published. A rejected pipeline
+	*  rejects every joiner — analysis failure is build failure, never a
+	*  passthrough. */
+	async function joinPipeline() {
+		await pipelineStarted;
+		await state.pipeline;
+	}
+	function emitCssAsset(context) {
+		if (!state.cssText) return;
+		const assets = (0, _animus_ui_extract_session.collectSessionAssets)(state.sessionDir);
+		if (meta.framework === "esbuild") {
+			const outDir = esbuildOptions?.outdir ?? (esbuildOptions?.outfile ? (0, node_path.dirname)(esbuildOptions.outfile) : null);
+			if (outDir === null) {
+				console.warn(`[animus] esbuild build has no outdir/outfile — the extracted stylesheet (${CSS_ASSET_NAME}) was not written`);
+				return;
+			}
+			if (esbuildOptions?.write === false) {
+				console.warn(`[animus] esbuild \`write: false\` build — the extracted stylesheet (${CSS_ASSET_NAME}) and its asset files were NOT produced (no in-memory output seam); use \`write: true\` or the standalone \`animus build\` CLI for in-memory pipelines`);
+				return;
+			}
+			const absOut = (0, node_path.resolve)(esbuildOptions?.absWorkingDir ?? process.cwd(), outDir);
+			(0, node_fs.mkdirSync)(absOut, { recursive: true });
+			(0, node_fs.writeFileSync)((0, node_path.join)(absOut, CSS_ASSET_NAME), state.cssText);
+			if (assets.length > 0) {
+				(0, node_fs.mkdirSync)((0, node_path.join)(absOut, _animus_ui_extract_session.SESSION_ASSETS_DIR), { recursive: true });
+				for (const { name, bytes } of assets) (0, node_fs.writeFileSync)((0, node_path.join)(absOut, _animus_ui_extract_session.SESSION_ASSETS_DIR, name), bytes);
+			}
+			return;
+		}
+		context.emitFile({
+			type: "asset",
+			fileName: CSS_ASSET_NAME,
+			source: state.cssText
+		});
+		for (const { name, bytes } of assets) context.emitFile({
+			type: "asset",
+			fileName: `${_animus_ui_extract_session.SESSION_ASSETS_DIR}/${name}`,
+			source: bytes
+		});
+	}
+	/** Register the analysis universe with the bundler's watcher — the
+	*  session analyzes a filesystem WALK, so watch mode misses edits to
+	*  analyzed-but-unimported files (and tsconfig/system deps) without
+	*  this. esbuild has no per-plugin watch-file seam; its rebuilds rely on
+	*  the module graph alone. */
+	function registerWatchTargets(context) {
+		if (meta.framework === "esbuild") return;
+		for (const path of state.watchPaths) try {
+			context.addWatchFile(path);
+		} catch {}
+	}
+	return {
+		name: PLUGIN_NAME,
+		enforce: "pre",
+		async buildStart() {
+			await startPipeline();
+			registerWatchTargets(this);
+		},
+		async resolveId(id) {
+			const virtual = resolveAnimusId(id);
+			if (virtual !== null) return virtual;
+			if (id.startsWith(".") || id.startsWith("/") || id.startsWith("\0") || id.startsWith("animus:")) return null;
+			await joinPipeline();
+			return state.kitRedirects.get(id) ?? null;
+		},
+		loadInclude(id) {
+			return id === "animus:styles" || id === "animus:system-props" || state.redirectTargets.has(moduleFilePath(id));
+		},
+		async load(id) {
+			if (id === "animus:styles") {
+				await joinPipeline();
+				return {
+					code: "export {};\n",
+					map: null
+				};
+			}
+			if (id === "animus:system-props") {
+				await joinPipeline();
+				return {
+					code: state.systemPropsJs,
+					map: null
+				};
+			}
+			const filePath = moduleFilePath(id);
+			if (state.redirectTargets.has(filePath)) return {
+				code: (0, node_fs.readFileSync)(filePath, "utf-8"),
+				map: null
+			};
+			return null;
+		},
+		transformInclude(id) {
+			const filePath = moduleFilePath(id);
+			return !id.startsWith("\0") && !id.startsWith("animus:") && TRANSFORM_INCLUDE_RE.test(filePath) && shouldClaimTransform(filePath, state);
+		},
+		async transform(code, id) {
+			await joinPipeline();
+			const filePath = moduleFilePath(id);
+			let output = code;
+			if (ENGINE_TRANSFORM_RE.test(filePath)) {
+				const transformFile = state.transformFile ?? (0, _animus_ui_extract_session.engineApi)().transformFile;
+				const transformed = transformWithEngine(output, filePath, {
+					rootDir: root,
+					manifestJson: (0, _animus_ui_extract_session.getManifestJson)() ?? "",
+					transformFile
+				});
+				if (transformed !== null) output = transformed;
+			}
+			if (needsInlineDefine) {
+				const substituted = substituteDevDefine(output, state.mode === "development");
+				if (substituted !== null) output = substituted;
+			}
+			return output === code ? null : {
+				code: output,
+				map: null
+			};
+		},
+		buildEnd() {
+			try {
+				emitCssAsset(this);
+			} finally {
+				disposeSessionDir(state);
+				releaseClaim();
+			}
+		},
+		rollup: { async buildStart() {
+			modeOracle = this.meta?.watchMode ? "development" : "production";
+			await startPipeline();
+			registerWatchTargets(this);
+		} },
+		webpack(compiler) {
+			wireWebpackLike(compiler);
+		},
+		rspack(compiler) {
+			wireWebpackLike(compiler);
+		},
+		esbuild: { config(buildOptions) {
+			esbuildOptions = buildOptions;
+			buildOptions.define = {
+				...buildOptions.define,
+				__ANIMUS_DEV__: JSON.stringify(effectiveMode() === "development")
+			};
+		} }
+	};
+	function wireWebpackLike(compiler) {
+		modeOracle = compiler.options.mode === "development" ? "development" : "production";
+		const DefinePlugin = compiler.webpack?.DefinePlugin ?? compiler.rspack?.DefinePlugin;
+		if (!DefinePlugin) throw new Error("[animus] compiler exposes no DefinePlugin — cannot supply the __ANIMUS_DEV__ dev-signal define");
+		new DefinePlugin({ __ANIMUS_DEV__: JSON.stringify(effectiveMode() === "development") }).apply(compiler);
+		compiler.hooks.done.tap(PLUGIN_NAME, () => {
+			disposeSessionDir(state);
+			releaseClaim();
+		});
+		compiler.hooks.failed?.tap(PLUGIN_NAME, () => {
+			disposeSessionDir(state);
+			releaseClaim();
+		});
+	}
+};
+//#endregion
+Object.defineProperty(exports, "unpluginFactory", {
+	enumerable: true,
+	get: function() {
+		return unpluginFactory;
+	}
+});