@animus-ui/extract 0.1.0-next.9 → 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @animus-ui/extract
+
+Rust/NAPI static CSS extraction pipeline for Animus. Analyzes TypeScript source files using OXC, resolves builder chains against serialized system config, and emits layered CSS.
+
+This package is consumed by [`@animus-ui/vite-plugin`](../vite-plugin) and [`@animus-ui/next-plugin`](../next-plugin). You typically don't install it directly — the bundler plugins depend on it.
+
+## Platforms
+
+Pre-built binaries for:
+
+- `darwin-arm64` (macOS Apple Silicon)
+- `linux-x64-gnu` (Linux x64)
+- `linux-arm64-gnu` (Linux ARM64)
+
+## API
+
+```tsx
+import { analyzeProject } from '@animus-ui/extract';
+
+const manifest = analyzeProject(
+  fileEntriesJson,
+  scalesJson,
+  variableMapJson,
+  contextualVarsJson,
+  propConfig,
+  groupRegistry,
+  packageResolutionJson,
+  devMode,
+  prefix
+);
+```
+
+## License
+
+MIT

package/dist/assemble-stylesheet.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The 7 Animus cascade layers. Always prefixed with `anm-` to avoid
+ * collision with other frameworks' layer names (e.g., Tailwind's `base`).
+ */
+export declare const ANIMUS_LAYERS: readonly ['anm-global', 'anm-base', 'anm-variants', 'anm-compounds', 'anm-states', 'anm-system', 'anm-custom'];
+/**
+ * Validate that a consumer `layers` array contains all 7 Animus layers
+ * in the correct relative order. Consumer layers may be interleaved.
+ *
+ * @throws Error with descriptive message on violation
+ */
+export declare function validateLayerOrder(layers: string[]): void;
+/**
+ * Strip a leading `@layer ...;` declaration line from CSS if present.
+ * The Rust crate embeds this in prod-mode output; we strip it so the
+ * shared assembler controls placement.
+ */
+export declare function stripLeadingLayerDeclaration(css: string): string;
+export interface AssembleStylesheetParts {
+    declaration: string;
+    variables: string;
+    body: string;
+}
+export interface AssembleStylesheetOptions {
+    /**
+     * Custom layer order. Must contain all 7 Animus `anm-*` layers as a subsequence.
+     * Example: `['reset', 'anm-global', 'anm-base', ..., 'anm-custom', 'overrides']`
+     * Names are emitted as-is — this is the actual `@layer` declaration.
+     */
+    layers?: string[];
+    /** Variable CSS: `:root { --color-*: ... }` + color mode selectors */
+    variableCss?: string;
+    /** Global CSS: `@layer anm-global { reset + global styles }` */
+    globalCss?: string;
+    /** Component CSS from the Rust crate (may contain embedded @layer declaration) */
+    componentCss?: string;
+    /** When true, return structured `{ declaration, variables, body }` instead of a single string. */
+    split?: boolean;
+}
+/**
+ * Assemble the final stylesheet in canonical order:
+ *
+ * 1. `@layer` declaration (cascade ordering)
+ * 2. Emitted variables (`:root`, color mode selectors)
+ * 3. `@layer anm-global { ... }` (reset + global styles)
+ * 4. `@layer anm-base/variants/compounds/states/system/custom { ... }` (components)
+ *
+ * This is the single source of truth for stylesheet assembly.
+ * Both Vite and Next.js plugins must use this function.
+ */
+export declare function assembleStylesheet(options: AssembleStylesheetOptions & {
+    split: true;
+}): AssembleStylesheetParts;
+export declare function assembleStylesheet(options: AssembleStylesheetOptions & {
+    split?: false;
+}): string;
+export declare function assembleStylesheet(options: AssembleStylesheetOptions): string | AssembleStylesheetParts;
+//# sourceMappingURL=assemble-stylesheet.d.ts.map

package/dist/assemble-stylesheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble-stylesheet.d.ts","sourceRoot":"","sources":["../pipeline/assemble-stylesheet.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,aAAa,YACxB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,YAAY,CACJ,CAAC;AAiBX;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CA2BzD;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GAAG;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACnD,uBAAuB,CAAC;AAC3B,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GAAG;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACrD,MAAM,CAAC;AACV,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,MAAM,GAAG,uBAAuB,CAAC"}

package/dist/discover-packages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract external DS package names from `includes` declarations in the system file.
+ *
+ * Supports two forms:
+ *   - Primary (1.0+):  `createSystem({ includes: [identifier, ...] })` constructor arg
+ *   - 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.
+ *
+ * Falls back to empty array if no `includes` declaration is found.
+ */
+export declare function extractSystemFilePackages(systemFilePath: string): string[];
+//# sourceMappingURL=discover-packages.d.ts.map

package/dist/discover-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-packages.d.ts","sourceRoot":"","sources":["../pipeline/discover-packages.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAmF1E"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { AssembleStylesheetOptions, AssembleStylesheetParts, } from './assemble-stylesheet';
+export { ANIMUS_LAYERS, assembleStylesheet, stripLeadingLayerDeclaration, validateLayerOrder, } from './assemble-stylesheet';
+export { extractSystemFilePackages } from './discover-packages';
+export type { DefaultExtension, PreprocessMdxResult } from './mdx-preprocessor';
+export { DEFAULT_EXTENSIONS, preprocessMdx } from './mdx-preprocessor';
+export { applyPrefix } from './prefix';
+export { resolveGlobalStyles, resolveTokenAliases, resolveValue, } from './resolve-global-styles';
+export { resolveTransformPlaceholders } from './resolve-transforms';
+export { applyUnitFallback } from './unit-fallback';
+export { camelToKebab } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../pipeline/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,GACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,379 @@
+import { readFileSync } from "fs";
+import { UNITLESS_PROPERTIES } from "@animus-ui/properties";
+//#region pipeline/assemble-stylesheet.ts
+/**
+* The 7 Animus cascade layers. Always prefixed with `anm-` to avoid
+* collision with other frameworks' layer names (e.g., Tailwind's `base`).
+*/
+const ANIMUS_LAYERS = [
+	"anm-global",
+	"anm-base",
+	"anm-variants",
+	"anm-compounds",
+	"anm-states",
+	"anm-system",
+	"anm-custom"
+];
+/**
+* Build the `@layer` declaration line.
+*
+* When `isCustom` is false (default layers), uses ANIMUS_LAYERS directly.
+* When `isCustom` is true, passes names through as-is — the consumer already
+* wrote the final names including the `anm-` prefixed entries.
+*/
+function buildLayerDeclaration(layers, isCustom) {
+	return `@layer ${(isCustom ? layers : [...ANIMUS_LAYERS]).join(", ")};\n`;
+}
+/**
+* Validate that a consumer `layers` array contains all 7 Animus layers
+* in the correct relative order. Consumer layers may be interleaved.
+*
+* @throws Error with descriptive message on violation
+*/
+function validateLayerOrder(layers) {
+	const expected = [...ANIMUS_LAYERS];
+	let cursor = 0;
+	for (const layer of layers) if (cursor < expected.length && layer === expected[cursor]) cursor++;
+	if (cursor < expected.length) {
+		const missing = expected.slice(cursor);
+		const found = expected.slice(0, cursor);
+		if (!expected.every((l) => layers.includes(l))) {
+			const absent = expected.filter((l) => !layers.includes(l));
+			throw new Error(`[animus-extract] Custom layers missing required layers: ${absent.join(", ")}. All 7 Animus layers must be present: ${expected.join(", ")}`);
+		}
+		throw new Error(`[animus-extract] Custom layers have wrong order. Found ${found.join(", ")} but then expected ${missing[0]}. Required order: (${expected.join(" < ")}). You may interleave custom layers but must preserve this subsequence.`);
+	}
+}
+/**
+* Strip a leading `@layer ...;` declaration line from CSS if present.
+* The Rust crate embeds this in prod-mode output; we strip it so the
+* shared assembler controls placement.
+*/
+function stripLeadingLayerDeclaration(css) {
+	return css.replace(/^@layer\s+[^;{]+;\s*\n?/, "");
+}
+function assembleStylesheet(options) {
+	const hasCustomLayers = !!options.layers;
+	const layers = options.layers ?? ANIMUS_LAYERS;
+	if (options.layers) validateLayerOrder(options.layers);
+	const declaration = buildLayerDeclaration(layers, hasCustomLayers);
+	const variables = options.variableCss || "";
+	const componentCss = options.componentCss ? stripLeadingLayerDeclaration(options.componentCss) : "";
+	const body = [options.globalCss || "", componentCss].filter(Boolean).join("\n");
+	if (options.split) return {
+		declaration,
+		variables,
+		body
+	};
+	return [
+		declaration,
+		variables,
+		body
+	].filter(Boolean).join("\n");
+}
+//#endregion
+//#region pipeline/discover-packages.ts
+/**
+* Extract external DS package names from `includes` declarations in the system file.
+*
+* Supports two forms:
+*   - Primary (1.0+):  `createSystem({ includes: [identifier, ...] })` constructor arg
+*   - 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.
+*
+* Falls back to empty array if no `includes` declaration is found.
+*/
+function extractSystemFilePackages(systemFilePath) {
+	let source;
+	try {
+		source = readFileSync(systemFilePath, "utf-8");
+	} catch {
+		return [];
+	}
+	const identifiers = /* @__PURE__ */ new Set();
+	const constructorRegex = /createSystem\s*\(\s*\{[^}]*?\bincludes\s*:\s*\[([^\]]*)\]/gs;
+	const chainRegex = /\.includes\s*\(\s*\[([^\]]*)\]\s*\)/gs;
+	const collectIdentifiers = (regex) => {
+		let match;
+		while ((match = regex.exec(source)) !== null) {
+			const inner = match[1];
+			for (const token of inner.split(",")) {
+				const id = token.trim();
+				if (id && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(id)) identifiers.add(id);
+			}
+		}
+	};
+	collectIdentifiers(constructorRegex);
+	collectIdentifiers(chainRegex);
+	if (identifiers.size === 0) return [];
+	const importMap = /* @__PURE__ */ new Map();
+	const importRegex = /^\s*import\s+(?:([a-zA-Z_$][a-zA-Z0-9_$]*)\s*,\s*)?(?:\{([^}]*)\}|([a-zA-Z_$][a-zA-Z0-9_$]*))\s+from\s+['"]([^'"]+)['"]/gm;
+	let importMatch;
+	while ((importMatch = importRegex.exec(source)) !== null) {
+		const [, comboDefault, namedImports, defaultImport, specifier] = importMatch;
+		if (comboDefault) importMap.set(comboDefault, specifier);
+		if (defaultImport) importMap.set(defaultImport, specifier);
+		if (namedImports) for (const binding of namedImports.split(",")) {
+			const parts = binding.trim().split(/\s+as\s+/);
+			const localName = (parts[1] || parts[0]).trim();
+			if (localName) importMap.set(localName, specifier);
+		}
+	}
+	const packages = /* @__PURE__ */ new Set();
+	for (const id of identifiers) {
+		const specifier = importMap.get(id);
+		if (specifier && !specifier.startsWith(".")) {
+			const pkgName = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+			packages.add(pkgName);
+		}
+	}
+	return Array.from(packages);
+}
+//#endregion
+//#region pipeline/mdx-preprocessor.ts
+/**
+* MDX source preprocessor for the extraction pipeline.
+*
+* MDX files are first-class consumers of ds-built components but are not
+* directly parseable by OXC (which the scanner uses for .tsx/.jsx). This
+* module compiles MDX sources to scanner-consumable JSX using @mdx-js/mdx.
+*
+* @mdx-js/mdx is declared as `peerDependenciesMeta.optional` on the
+* plugin packages that import this module. The dynamic import with
+* .catch() ensures non-MDX consumers (who configure `extensions` to
+* exclude .mdx) never trigger the resolution — zero install-footprint
+* cost for them.
+*
+* The `DEFAULT_EXTENSIONS` constant is the shared source of truth for
+* both `@animus-ui/vite-plugin` and `@animus-ui/next-plugin`. Each plugin
+* imports it directly; independent redeclaration of default extensions
+* is considered a regression.
+*/
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mdx"
+];
+/**
+* Preprocess an MDX source string into scanner-consumable JSX.
+*
+* - Returns `{ kind: 'ok', source }` with JSX-compiled output on success.
+* - Returns `{ kind: 'missing-dep' }` if @mdx-js/mdx is not resolvable
+*   (consumer needs to install it).
+* - Returns `{ kind: 'error', error }` on compile failure (e.g. malformed
+*   MDX syntax). Plugins SHALL warn + skip affected files; the build
+*   continues with remaining files.
+*/
+async function preprocessMdx(source, filename) {
+	const mdxMod = await import("@mdx-js/mdx").catch(() => null);
+	if (mdxMod === null) return { kind: "missing-dep" };
+	try {
+		const vfile = await mdxMod.compile(source, {
+			outputFormat: "program",
+			development: false,
+			jsx: true
+		});
+		return {
+			kind: "ok",
+			source: `/* @mdx-source: ${filename} */\n${String(vfile)}`
+		};
+	} catch (err) {
+		return {
+			kind: "error",
+			error: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#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");
+}
+/**
+* Resolve global style blocks into CSS strings.
+*
+* 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;
+}
+//#endregion
+//#region pipeline/resolve-transforms.ts
+/**
+* Resolve __TRANSFORM__ placeholders in extracted CSS.
+*
+* 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.
+*/
+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
+export { ANIMUS_LAYERS, DEFAULT_EXTENSIONS, applyPrefix, applyUnitFallback, assembleStylesheet, camelToKebab, extractSystemFilePackages, preprocessMdx, resolveGlobalStyles, resolveTokenAliases, resolveTransformPlaceholders, resolveValue, stripLeadingLayerDeclaration, validateLayerOrder };

package/dist/mdx-preprocessor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MDX source preprocessor for the extraction pipeline.
+ *
+ * MDX files are first-class consumers of ds-built components but are not
+ * directly parseable by OXC (which the scanner uses for .tsx/.jsx). This
+ * module compiles MDX sources to scanner-consumable JSX using @mdx-js/mdx.
+ *
+ * @mdx-js/mdx is declared as `peerDependenciesMeta.optional` on the
+ * plugin packages that import this module. The dynamic import with
+ * .catch() ensures non-MDX consumers (who configure `extensions` to
+ * exclude .mdx) never trigger the resolution — zero install-footprint
+ * cost for them.
+ *
+ * The `DEFAULT_EXTENSIONS` constant is the shared source of truth for
+ * both `@animus-ui/vite-plugin` and `@animus-ui/next-plugin`. Each plugin
+ * imports it directly; independent redeclaration of default extensions
+ * is considered a regression.
+ */
+export declare const DEFAULT_EXTENSIONS: readonly ['.ts', '.tsx', '.js', '.jsx', '.mdx'];
+export type DefaultExtension = (typeof DEFAULT_EXTENSIONS)[number];
+export interface PreprocessMdxResult {
+    kind: 'ok' | 'missing-dep' | 'error';
+    /** Preprocessed JSX source. Present when kind === 'ok'. */
+    source?: string;
+    /** Error message. Present when kind === 'error'. */
+    error?: string;
+}
+/**
+ * Preprocess an MDX source string into scanner-consumable JSX.
+ *
+ * - Returns `{ kind: 'ok', source }` with JSX-compiled output on success.
+ * - Returns `{ kind: 'missing-dep' }` if @mdx-js/mdx is not resolvable
+ *   (consumer needs to install it).
+ * - Returns `{ kind: 'error', error }` on compile failure (e.g. malformed
+ *   MDX syntax). Plugins SHALL warn + skip affected files; the build
+ *   continues with remaining files.
+ */
+export declare function preprocessMdx(source: string, filename: string): Promise<PreprocessMdxResult>;
+//# sourceMappingURL=mdx-preprocessor.d.ts.map

package/dist/mdx-preprocessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx-preprocessor.d.ts","sourceRoot":"","sources":["../pipeline/mdx-preprocessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,kBAAkB,YAC7B,KAAK,EACL,MAAM,EACN,KAAK,EACL,MAAM,EACN,MAAM,CACE,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,IAAI,GAAG,aAAa,GAAG,OAAO,CAAC;IACrC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,CAAC,CA4B9B"}

package/dist/prefix.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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)" }`
+ */
+export declare function applyPrefix(prefix: string, variableMapJson: string, variableCss: string, themeJson?: string, contextualVarsJson?: string): {
+    variableMapJson: string;
+    variableCss: string;
+    themeJson?: string;
+    contextualVarsJson?: string;
+};
+//# sourceMappingURL=prefix.d.ts.map

package/dist/prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.d.ts","sourceRoot":"","sources":["../pipeline/prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B;IACD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CA0CA"}

package/dist/resolve-global-styles.d.ts

@@ -0,0 +1,25 @@
+interface PropConfigEntry {
+    property?: string;
+    properties?: string[];
+    scale?: string;
+    transform?: string;
+}
+/**
+ * Resolve {scale.path} and {scale.path/alpha} token aliases in a CSS value string.
+ * Mirrors the Rust theme_resolver's resolve_token_aliases logic.
+ */
+export declare function resolveTokenAliases(value: string, flat: Record<string, string>, variableMap: Record<string, string>): string;
+/**
+ * Resolve a single CSS value through prop config: scale lookup, transform, token aliases.
+ */
+export declare function resolveValue(raw: unknown, config: PropConfigEntry | undefined, flat: Record<string, string>, variableMap: Record<string, string>, transforms: Record<string, (v: unknown) => unknown>): string;
+/**
+ * Resolve global style blocks into CSS strings.
+ *
+ * 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.
+ */
+export declare function resolveGlobalStyles(globalStyles: Record<string, Record<string, Record<string, unknown>>>, propConfig: Record<string, PropConfigEntry>, flat: Record<string, string>, variableMap: Record<string, string>, transforms: Record<string, (v: unknown) => unknown>): Record<string, string>;
+export {};
+//# sourceMappingURL=resolve-global-styles.d.ts.map

package/dist/resolve-global-styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-global-styles.d.ts","sourceRoot":"","sources":["../pipeline/resolve-global-styles.ts"],"names":[],"mappings":"AAEA,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,GAClD,MAAM,CAkBR;AAsED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAC3C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB"}

package/dist/resolve-transforms.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve __TRANSFORM__ placeholders in extracted CSS.
+ *
+ * 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.
+ */
+export declare function resolveTransformPlaceholders(css: string, transforms: Record<string, (v: unknown) => unknown>): string;
+//# sourceMappingURL=resolve-transforms.d.ts.map

package/dist/resolve-transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-transforms.d.ts","sourceRoot":"","sources":["../pipeline/resolve-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,GAClD,MAAM,CAgBR"}

package/dist/unit-fallback.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function applyUnitFallback(css: string): string;
+//# sourceMappingURL=unit-fallback.d.ts.map

package/dist/unit-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-fallback.d.ts","sourceRoot":"","sources":["../pipeline/unit-fallback.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2CrD"}

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+/** Convert camelCase CSS property names to kebab-case. */
+export declare function camelToKebab(str: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../pipeline/utils.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/index.d.ts

@@ -10,8 +10,13 @@
  * - `group_registry_json`: group registry JSON (`{ "space": ["p", "px", ...], ... }`).
  * - `package_resolution_json`: JSON object mapping package specifiers to entry-point paths,
  *   e.g. `{ "@my-ui/components": "pkg-barrel/index.ts" }`. Pass `"{}"` when not needed.
+ * - `prefix`: optional namespace prefix for class names and CSS custom properties.
+ *   When set, `animus-` is replaced with `{prefix}-` in all generated identifiers.
+ * - `emitter_config_json`: optional JSON `{ "runtime_import": "...", "css_module_id": "..." }`.
+ *   Overrides hardcoded import paths in generated source. When `None`, defaults to
+ *   `@animus-ui/system` and `virtual:animus/styles.css`.
  */
-export declare function analyzeProject(fileEntriesJson: string, themeJson: string, variableMapJson: string, configJson: string, groupRegistryJson: string, packageResolutionJson: string, devMode?: boolean | undefined | null): string
+export declare function analyzeProject(fileEntriesJson: string, themeJson: string, variableMapJson: string, contextualVarsJson: string | undefined | null, configJson: string, groupRegistryJson: string, packageResolutionJson: string, devMode?: boolean | undefined | null, emitterConfigJson?: string | undefined | null, selectorAliasesJson?: string | undefined | null, selectorOrderJson?: string | undefined | null, globalStyleBlocksJson?: string | undefined | null, pathAliasesJson?: string | undefined | null, keyframesBlocksJson?: string | undefined | null): string
 
 /**
  * Clear the per-file extraction cache used by `analyze_project()`.
@@ -20,7 +25,7 @@ export declare function analyzeProject(fileEntriesJson: string, themeJson: strin
  */
 export declare function clearAnalysisCache(): void
 
-export declare function extract(source: string, filename: string, themeJson: string, variableMapJson: string, configJson: string, groupRegistryJson: string): ExtractionResult
+export declare function extract(source: string, filename: string, themeJson: string, variableMapJson: string, configJson: string, groupRegistryJson: string, selectorAliasesJson?: string | undefined | null, selectorOrderJson?: string | undefined | null): ExtractionResult
 
 export interface ExtractionResult {
   css: string
@@ -30,6 +35,21 @@ export interface ExtractionResult {
   errors: Array<string>
 }
 
+export declare function loadSystemModule(systemPath: string, rootDir: string, exportName?: string | undefined | null): NapiSystemConfig
+
+export interface NapiSystemConfig {
+  propConfig: string
+  groupRegistry: string
+  scalesJson: string
+  variableMapJson: string
+  variableCss: string
+  contextualVarsJson: string
+  selectorAliases?: string
+  selectorOrder?: string
+  globalStyleBlocks?: string
+  keyframesBlocks?: string
+}
+
 /**
  * Transform a single source file using a pre-built `UniverseManifest`.
  *

package/index.js

@@ -579,4 +579,5 @@ module.exports = nativeBinding
 module.exports.analyzeProject = nativeBinding.analyzeProject
 module.exports.clearAnalysisCache = nativeBinding.clearAnalysisCache
 module.exports.extract = nativeBinding.extract
+module.exports.loadSystemModule = nativeBinding.loadSystemModule
 module.exports.transformFile = nativeBinding.transformFile

package/package.json

@@ -1,22 +1,75 @@
 {
   "name": "@animus-ui/extract",
-  "version": "0.1.0-next.9",
+  "version": "0.1.0",
   "description": "Animus static CSS extraction pipeline (Rust/NAPI)",
-  "author": "codecaaron <airrobb@gmail.com>",
+  "keywords": [
+    "animus",
+    "compiler",
+    "css",
+    "css-in-js",
+    "napi",
+    "rust",
+    "static-css",
+    "zero-runtime"
+  ],
+  "homepage": "https://github.com/codecaaron/animus/tree/main/packages/extract#readme",
   "license": "MIT",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "author": "codecaaron <airrobb@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codecaaron/animus",
+    "directory": "packages/extract"
+  },
   "files": [
     "index.js",
     "index.d.ts",
-    "*.node"
+    "*.node",
+    "dist"
   ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./pipeline": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/codecaaron/animus"
+  "scripts": {
+    "build": "napi build --platform --release && bun run build:ts",
+    "build:ts": "tsdown && tsgo -p tsconfig.build.json",
+    "build:debug": "napi build --platform",
+    "compile": "tsgo -p tsconfig.build.json --noEmit"
+  },
+  "dependencies": {
+    "@animus-ui/properties": "0.1.0"
+  },
+  "devDependencies": {
+    "@animus-ui/system": "workspace:*",
+    "@mdx-js/mdx": "^3.0.0",
+    "@napi-rs/cli": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@mdx-js/mdx": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@mdx-js/mdx": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@animus-ui/extract-darwin-arm64": "0.1.0",
+    "@animus-ui/extract-linux-arm64-gnu": "0.1.0",
+    "@animus-ui/extract-linux-x64-gnu": "0.1.0"
   },
   "napi": {
     "binaryName": "animus-extract",
@@ -25,17 +78,5 @@
       "x86_64-unknown-linux-gnu",
       "aarch64-unknown-linux-gnu"
     ]
-  },
-  "scripts": {
-    "build": "napi build --platform --release",
-    "build:debug": "napi build --platform"
-  },
-  "optionalDependencies": {
-    "@animus-ui/extract-darwin-arm64": "0.1.0-next.9",
-    "@animus-ui/extract-linux-x64-gnu": "0.1.0-next.9",
-    "@animus-ui/extract-linux-arm64-gnu": "0.1.0-next.9"
-  },
-  "devDependencies": {
-    "@napi-rs/cli": "^3.0.0"
   }
 }