@animus-ui/extract 0.1.3 → 0.1.4

package/dist/index.cjs

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let crypto = require("crypto");
 let fs = require("fs");
 let path = require("path");
+let module$1 = require("module");
 let browserslist = require("browserslist");
 browserslist = __toESM(browserslist);
 let lightningcss = require("lightningcss");
@@ -121,7 +122,8 @@ function buildAnalyzeProjectArgs(inputs) {
 		inputs.pathAliasesJson,
 		inputs.keyframesJson,
 		inputs.staticCssJson,
-		inputs.conditionAliasesJson
+		inputs.conditionAliasesJson,
+		inputs.externalDirsJson
 	];
 }
 //#endregion
@@ -139,7 +141,7 @@ function createV2EngineApi(deps) {
 		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) => {
+			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson, externalDirsJson) => {
 				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);
@@ -162,6 +164,7 @@ function createV2EngineApi(deps) {
 					packageResolutionJson: packageResolutionJson ?? void 0,
 					pathAliasesJson: pathAliasesJson ?? void 0,
 					staticCssJson: staticCssJson ?? void 0,
+					externalDirsJson: externalDirsJson ?? void 0,
 					devMode
 				};
 				const engine = new native.ExtractEngine(config);
@@ -220,8 +223,10 @@ function assertNoRetiredEngineSelection(engineOption) {
 //#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.
+* extraction plugins, and for content-addressing copied asset bytes. The
+* algorithm/encoding is a cross-plugin contract: cache keys written by one
+* build path must compare equal in the next. Accepts a Buffer directly so
+* binary sources hash without an intermediate string copy.
 */
 function contentHash(source) {
 	return (0, crypto.createHash)("md5").update(source).digest("hex");
@@ -284,6 +289,14 @@ const PACKAGE_SRC_EXCLUDES = [
 	".test.",
 	".spec."
 ];
+/** Exclusions for the compiled-output fallback when a package does not ship src/. */
+const PACKAGE_OUTPUT_EXCLUDES = [
+	"node_modules",
+	".test.",
+	".spec.",
+	".d.ts",
+	".map"
+];
 const isFile = (path$2) => {
 	try {
 		return (0, fs.statSync)(path$2).isFile();
@@ -305,6 +318,42 @@ function resolveAbsolutePathSpecifier(absSpecifier, extensionsSet) {
 		...Array.from(extensionsSet, (ext) => (0, path.join)(absSpecifier, `index${ext}`))
 	].find(isFile) ?? null;
 }
+/** The package-name half of a bare specifier (`@scope/name/sub` → `@scope/name`). */
+function bareSpecifierPackageName(specifier) {
+	const segments = specifier.split("/");
+	return specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+}
+function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
+	if ((0, path.isAbsolute)(specifier)) {
+		const resolved = resolveAbsolutePathSpecifier(specifier, extensionsSet);
+		if (!resolved) return null;
+		return !(0, path.relative)(srcDir, resolved).startsWith("..") ? resolved : null;
+	}
+	const packageName = bareSpecifierPackageName(specifier);
+	return resolveAbsolutePathSpecifier((0, path.join)(srcDir, specifier.slice(packageName.length + 1) || "index"), extensionsSet);
+}
+/**
+* The D13 dist-freshness check: applicable only when a specifier has BOTH a
+* walked src/ tree and a resolved dist entry that exists on disk outside that
+* tree; stale when the dist entry's mtime is older than the newest walked
+* source file's. Not applicable (never stale) when the entry resolves inside
+* src/ (no dist to skew), when the entry file is missing, or when no source
+* file's mtime is readable. Detection only — reporting is the caller's policy.
+*/
+function distEntryIsStale(absEntry, srcDir, srcFiles) {
+	if (!(0, path.relative)(srcDir, absEntry).startsWith("..")) return false;
+	let distMtime;
+	try {
+		distMtime = (0, fs.statSync)(absEntry).mtimeMs;
+	} catch {
+		return false;
+	}
+	let newestSrcMtime = -Infinity;
+	for (const srcFile of srcFiles) try {
+		newestSrcMtime = Math.max(newestSrcMtime, (0, fs.statSync)(srcFile).mtimeMs);
+	} catch {}
+	return distMtime < newestSrcMtime;
+}
 /**
 * Shared external-package source collection (spec:
 * external-package-file-discovery), consumed by both extraction plugins.
@@ -330,6 +379,8 @@ async function collectExternalPackageSources(opts) {
 	const packageMap = {};
 	const sourceEntries = /* @__PURE__ */ new Map();
 	const packageDirs = [];
+	const dirOwners = {};
+	const fileOwners = {};
 	const outcomes = [];
 	const alreadyIngested = (relPath) => hasEntry(relPath) || pushed.has(relPath);
 	for (const specifier of specifiers) {
@@ -350,17 +401,30 @@ async function collectExternalPackageSources(opts) {
 		}
 		const srcDir = (0, path.join)(findPackageRoot(absEntry), "src");
 		let fileCount = 0;
+		let staleDist = false;
 		if ((0, fs.existsSync)(srcDir)) {
 			packageDirs.push(srcDir);
-			const srcEntry = (0, path.join)(srcDir, "index.ts");
-			if ((0, fs.existsSync)(srcEntry)) {
+			dirOwners[srcDir] ??= specifier;
+			const srcEntry = sourceEntryForSpecifier(specifier, srcDir, extensionsSet);
+			if (srcEntry) {
 				packageMap[specifier] = (0, path.relative)(rootDir, srcEntry);
 				sourceEntries.set(specifier, srcEntry);
 			} else packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			if (!(0, path.isAbsolute)(specifier)) {
+				const packageName = bareSpecifierPackageName(specifier);
+				if (packageName !== specifier && !(packageName in packageMap)) {
+					const rootEntry = sourceEntryForSpecifier(packageName, srcDir, extensionsSet);
+					if (rootEntry) {
+						packageMap[packageName] = (0, path.relative)(rootDir, rootEntry);
+						sourceEntries.set(packageName, rootEntry);
+					}
+				}
+			}
 			const pkgFiles = discoverFiles(srcDir, srcDir, [], extensionsSet).filter((absPath) => {
 				const inPkg = (0, path.relative)(srcDir, absPath);
 				return !PACKAGE_SRC_EXCLUDES.some((pattern) => inPkg.includes(pattern));
 			});
+			staleDist = distEntryIsStale(absEntry, srcDir, pkgFiles);
 			for (const pkgFile of pkgFiles) {
 				const relPath = (0, path.relative)(rootDir, pkgFile);
 				if (alreadyIngested(relPath)) {
@@ -381,28 +445,48 @@ async function collectExternalPackageSources(opts) {
 					source: processed.source
 				});
 				pushed.add(processed.relPath);
+				fileOwners[processed.relPath] ??= specifier;
 				fileCount++;
 			}
 		} else {
-			packageDirs.push((0, path.dirname)(absEntry));
-			const relPath = (0, path.relative)(rootDir, absEntry);
-			packageMap[specifier] = relPath;
-			if (alreadyIngested(relPath)) fileCount++;
-			else try {
-				const source = (0, fs.readFileSync)(absEntry, "utf-8");
+			const outputDir = (0, path.dirname)(absEntry);
+			packageDirs.push(outputDir);
+			dirOwners[outputDir] ??= specifier;
+			packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			const outputExtensions = new Set(extensionsSet);
+			outputExtensions.add((0, path.extname)(absEntry));
+			const outputFiles = discoverFiles(outputDir, outputDir, [], outputExtensions).filter((file) => {
+				const relToOutput = (0, path.relative)(outputDir, file);
+				return !PACKAGE_OUTPUT_EXCLUDES.some((pattern) => relToOutput.includes(pattern));
+			});
+			if (!outputFiles.includes(absEntry)) outputFiles.unshift(absEntry);
+			for (const outputFile of outputFiles) {
+				const outputRelPath = (0, path.relative)(rootDir, outputFile);
+				if (alreadyIngested(outputRelPath)) {
+					fileCount++;
+					continue;
+				}
+				let source;
+				try {
+					source = (0, fs.readFileSync)(outputFile, "utf-8");
+				} catch (err) {
+					onUnreadable(outputRelPath, err);
+					continue;
+				}
+				const processed = await preprocessFile(source, outputRelPath, outputFile);
+				if (!processed) continue;
 				entries.push({
-					path: relPath,
-					source
+					path: processed.relPath,
+					source: processed.source
 				});
-				pushed.add(relPath);
+				pushed.add(processed.relPath);
+				fileOwners[processed.relPath] ??= specifier;
 				fileCount++;
-			} catch (err) {
-				onUnreadable(relPath, err);
 			}
 		}
 		outcomes.push({
 			specifier,
-			outcome: fileCount > 0 ? "resolved" : "empty",
+			outcome: staleDist ? "stale-dist" : fileCount > 0 ? "resolved" : "empty",
 			fileCount
 		});
 	}
@@ -411,24 +495,33 @@ async function collectExternalPackageSources(opts) {
 		packageMap,
 		sourceEntries,
 		packageDirs,
+		dirOwners,
+		fileOwners,
 		outcomes
 	};
 }
 /**
-* Extract external DS package names from `includes` declarations in the system file.
+* Extract external DS package names from inheritance declarations in the
+* system file.
 *
-* Supports two forms:
-*   - Primary (1.0+):  `createSystem({ includes: [identifier, ...] })` constructor arg
-*   - Legacy:          `.includes([identifier, ...])` chain method (RC migration fallback)
+* Supports four forms:
+*   - Primary:            `createSystem(...).extend(identifier)` chain calls
+*                         (repeatable, mixable with `.from()` links; each call
+*                         contributes one source; a library-bundle identifier
+*                         traces its base import)
+*   - Deprecated chain:   `createSystem(...).from(identifier)` chain calls
+*   - Deprecated alias:   `createSystem({ includes: [identifier, ...] })`
+*   - Legacy:             `.includes([identifier, ...])` chain method (RC
+*                         migration fallback)
 *
 * For each identifier found, traces back to its import declaration and returns
 * 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.
+* too). Only packages explicitly declared through one of these forms are
+* treated as external DS dependencies.
 *
-* Falls back to empty array if no `includes` declaration is found.
+* Falls back to empty array if no declaration is found.
 */
 /**
 * The message for the strict/warn gate over unresolvable includes, or null
@@ -441,6 +534,18 @@ function unresolvableIncludesMessage(outcomes) {
 	if (unresolvable.length === 0) return null;
 	return `[animus-extract] unresolvable include specifier(s): ${unresolvable.join(", ")}`;
 }
+/**
+* The message for the strict/warn gate over stale dist entries
+* (first-class-extension D13), or null when no declared specifier is stale.
+* A stale dist silently skews merged registry content while discovery
+* compiles the fresh sources, so it surfaces like an unresolvable specifier:
+* non-strict consumers warn with this line, strict consumers throw it.
+*/
+function staleDistIncludesMessage(outcomes) {
+	const stale = outcomes.filter((record) => record.outcome === "stale-dist").map((record) => record.specifier);
+	if (stale.length === 0) return null;
+	return `[animus-extract] stale dist for include specifier(s): ${stale.join(", ")} — dist entry is older than the newest src/ file; rebuild the package(s) before extracting`;
+}
 function extractSystemFilePackages(systemFilePath) {
 	let source;
 	try {
@@ -463,6 +568,94 @@ function extractSystemFilePackages(systemFilePath) {
 	};
 	collectIdentifiers(constructorRegex);
 	collectIdentifiers(chainRegex);
+	const IDENT_START_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*/;
+	/** Position after any run of whitespace, line comments, block comments. */
+	const skipTrivia = (from) => {
+		let pos = from;
+		for (;;) {
+			while (pos < source.length && /\s/.test(source[pos])) pos++;
+			if (source.startsWith("//", pos)) {
+				const newline = source.indexOf("\n", pos);
+				pos = newline === -1 ? source.length : newline + 1;
+				continue;
+			}
+			if (source.startsWith("/*", pos)) {
+				const close = source.indexOf("*/", pos + 2);
+				pos = close === -1 ? source.length : close + 2;
+				continue;
+			}
+			return pos;
+		}
+	};
+	/**
+	* Consume consecutive extend/from links starting at `from`, collecting
+	* each link's base identifier; tolerates trivia between tokens and a
+	* trailing comma in the argument list. Returns the position after the
+	* last consumed link (`from` itself when none matched).
+	*/
+	const consumeChainLinks = (from) => {
+		let pos = from;
+		for (;;) {
+			let cursor = skipTrivia(pos);
+			if (source[cursor] !== ".") return pos;
+			cursor = skipTrivia(cursor + 1);
+			const method = IDENT_START_RE.exec(source.slice(cursor))?.[0];
+			if (method !== "extend" && method !== "from") return pos;
+			cursor = skipTrivia(cursor + method.length);
+			if (source[cursor] !== "(") return pos;
+			cursor = skipTrivia(cursor + 1);
+			const base = IDENT_START_RE.exec(source.slice(cursor))?.[0];
+			if (!base) return pos;
+			cursor = skipTrivia(cursor + base.length);
+			while (source[cursor] === ".") {
+				const afterDot = skipTrivia(cursor + 1);
+				const segment = IDENT_START_RE.exec(source.slice(afterDot))?.[0];
+				if (!segment) break;
+				cursor = skipTrivia(afterDot + segment.length);
+			}
+			if (source[cursor] === ",") cursor = skipTrivia(cursor + 1);
+			if (source[cursor] !== ")") return pos;
+			identifiers.add(base);
+			pos = cursor + 1;
+		}
+	};
+	/** Identifier assigned directly before `index` (`const x = <here>`), if any. */
+	const boundIdentifierBefore = (index) => {
+		const match = /([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*$/.exec(source.slice(0, index));
+		return match ? match[1] : null;
+	};
+	const chainRootIdentifiers = /* @__PURE__ */ new Set();
+	const createSystemAnchor = /createSystem\s*\(/g;
+	let anchorMatch;
+	while ((anchorMatch = createSystemAnchor.exec(source)) !== null) {
+		let pos = anchorMatch.index + anchorMatch[0].length;
+		let depth = 1;
+		while (pos < source.length && depth > 0) {
+			const ch = source[pos];
+			if (ch === "(") depth++;
+			else if (ch === ")") depth--;
+			pos++;
+		}
+		consumeChainLinks(pos);
+		const bound = boundIdentifierBefore(anchorMatch.index);
+		if (bound) chainRootIdentifiers.add(bound);
+	}
+	const scannedRoots = /* @__PURE__ */ new Set();
+	for (;;) {
+		const pendingRoots = [...chainRootIdentifiers].filter((root) => !scannedRoots.has(root));
+		if (pendingRoots.length === 0) break;
+		for (const root of pendingRoots) {
+			scannedRoots.add(root);
+			const rootUse = new RegExp(`(?<![a-zA-Z0-9_$])${root.replace(/\$/g, "\\$")}(?![a-zA-Z0-9_$])`, "g");
+			let useMatch;
+			while ((useMatch = rootUse.exec(source)) !== null) {
+				const afterIdentifier = useMatch.index + useMatch[0].length;
+				if (consumeChainLinks(afterIdentifier) === afterIdentifier) continue;
+				const bound = boundIdentifierBefore(useMatch.index);
+				if (bound) chainRootIdentifiers.add(bound);
+			}
+		}
+	}
 	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;
@@ -483,14 +676,265 @@ function extractSystemFilePackages(systemFilePath) {
 		const specifier = importMap.get(id);
 		if (!specifier) continue;
 		if (specifier.startsWith(".")) packages.add((0, path.resolve)(systemFileDir, specifier));
-		else {
-			const pkgName = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
-			packages.add(pkgName);
-		}
+		else packages.add(specifier);
 	}
 	return Array.from(packages);
 }
 //#endregion
+//#region pipeline/asset-placeholders.ts
+/**
+* Host-side handling of `asset()` placeholders (global-styles-system):
+* `animus-asset:<specifier>` markers ride through the sandbox and the
+* emitter byte-exact; each HOST plugin substitutes them with its bundler's
+* resolved asset URL after extraction. This module owns the shared scanning
+* and replacement mechanics — resolution and strict gating stay at the
+* plugin call sites.
+*/
+/** Mirrors the producer-side constant in `@animus-ui/system`'s `asset.ts`
+*  (extract must not take a runtime dependency on system); the pairing is
+*  pinned by a contract test in `tests/asset-placeholders.test.ts`. */
+const ASSET_PLACEHOLDER_PREFIX = "animus-asset:";
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const PREFIX_RE = escapeRegExp(ASSET_PLACEHOLDER_PREFIX);
+/**
+* Quoted `url('animus-asset:<specifier>')` form — the emitter always quotes
+* `url()` values, so a quoted match carries the FULL specifier, including
+* whitespace and parentheses (D5 pins the placeholder as specifier-verbatim,
+* so scanning fidelity is the only place such characters can be honored).
+*/
+const QUOTED_PLACEHOLDER_RE = new RegExp(`(['"])${PREFIX_RE}([^'"]*?)\\1`, "g");
+/** Bare-form fallback: a placeholder up to CSS url()/quote/whitespace. */
+const BARE_PLACEHOLDER_RE = new RegExp(`${PREFIX_RE}([^'")\\s]+)`, "g");
+/** Unique asset specifiers referenced by placeholders, in appearance order. */
+function findAssetSpecifiers(css) {
+	if (!css.includes("animus-asset:")) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const remainder = css.replace(QUOTED_PLACEHOLDER_RE, (_match, _quote, specifier) => {
+		seen.add(specifier);
+		return "";
+	});
+	for (const match of remainder.matchAll(BARE_PLACEHOLDER_RE)) seen.add(match[1]);
+	return [...seen];
+}
+/**
+* Replace each specifier's placeholder with its substitution. Specifiers
+* absent from the map keep their placeholder — the caller decides whether
+* that is a strict failure or a warn-and-emit-literally. A substitution may
+* itself be a bundler marker (e.g. Vite's `__VITE_ASSET__<ref>__`) that the
+* host's own asset pipeline resolves to a hashed file name later.
+*
+* Each replacement is anchored to a following delimiter (quote, `)`,
+* whitespace, or end of input) so a specifier that textually prefixes a
+* longer one can never clobber the longer placeholder; longest-first
+* ordering additionally lets the longer of two mapped specifiers claim its
+* occurrences before the shorter runs.
+*/
+function substituteAssetPlaceholders(css, urlBySpecifier) {
+	if (urlBySpecifier.size === 0) return css;
+	if (!css.includes("animus-asset:")) return css;
+	const specifiers = [...urlBySpecifier.keys()].sort((a, b) => b.length - a.length);
+	let out = css;
+	for (const specifier of specifiers) {
+		const placeholder = new RegExp(escapeRegExp(ASSET_PLACEHOLDER_PREFIX + specifier) + String.raw`(?=['")\s]|$)`, "g");
+		out = out.replace(placeholder, () => urlBySpecifier.get(specifier));
+	}
+	return out;
+}
+//#endregion
+//#region pipeline/resolve-asset.ts
+/**
+* Node-side asset specifier resolution shared by the host plugins (the
+* asset() contract, global-styles-system): host path aliases apply FIRST —
+* an alias such as `@fonts` works in application modules, so
+* `asset('@fonts/inter.woff2')` must resolve identically — then direct Node
+* resolution, then the package-root fallback (exports maps rarely list
+* asset subpaths). Bundler-native resolution (Vite's `this.resolve`) is
+* still preferred where available; this resolver covers the paths that have
+* no bundler hook (Next's session, Vite's dev re-analysis).
+*/
+const requireByRoot = /* @__PURE__ */ new Map();
+function requireAnchoredAt(rootDir) {
+	let req = requireByRoot.get(rootDir);
+	if (!req) {
+		req = (0, module$1.createRequire)((0, path.join)(rootDir, "package.json"));
+		requireByRoot.set(rootDir, req);
+	}
+	return req;
+}
+function packageRootFromEntry(entry) {
+	let current = (0, path.dirname)(entry);
+	while (true) {
+		if ((0, fs.existsSync)((0, path.join)(current, "package.json"))) return current;
+		const parent = (0, path.dirname)(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+const aliasTableCache = /* @__PURE__ */ new Map();
+function parseAliasTable(pathAliasesJson) {
+	const cached = aliasTableCache.get(pathAliasesJson);
+	if (cached) return cached;
+	let aliases;
+	try {
+		aliases = JSON.parse(pathAliasesJson).aliases ?? [];
+	} catch {
+		aliases = [];
+	}
+	aliasTableCache.set(pathAliasesJson, aliases);
+	return aliases;
+}
+/**
+* Map a specifier through the harvested host alias table (the same
+* `pathAliasesJson` wire the engine consumes — entries pre-sorted longest
+* pattern first by `buildPathAliasesJson`). Returns an absolute path to an
+* EXISTING file, or null when no alias claims the specifier.
+*/
+function resolveThroughPathAliases(specifier, rootDir, pathAliasesJson) {
+	if (!pathAliasesJson) return null;
+	const aliases = parseAliasTable(pathAliasesJson);
+	for (const alias of aliases) {
+		let mapped = null;
+		if (alias.type === "exact") {
+			if (alias.pattern === specifier) mapped = alias.replacement;
+		} else if (specifier.startsWith(alias.pattern)) mapped = alias.replacement + specifier.slice(alias.pattern.length);
+		if (mapped === null) continue;
+		const absolute = (0, path.isAbsolute)(mapped) ? mapped : (0, path.join)(rootDir, mapped);
+		if ((0, fs.existsSync)(absolute)) return absolute;
+	}
+	return null;
+}
+/**
+* Resolve an asset specifier to an absolute file: host aliases, then direct
+* Node resolution anchored at `rootDir`, then the package-root fallback.
+* Returns null when nothing matches — strict gating stays at the caller.
+*/
+function resolveAssetFile(specifier, rootDir, pathAliasesJson) {
+	const aliased = resolveThroughPathAliases(specifier, rootDir, pathAliasesJson);
+	if (aliased) return aliased;
+	const requireFromRoot = requireAnchoredAt(rootDir);
+	try {
+		return requireFromRoot.resolve(specifier);
+	} catch {}
+	const segments = specifier.split("/");
+	const packageName = specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+	const subpath = specifier.slice(packageName.length + 1);
+	if (!subpath) return null;
+	for (const modulesDir of requireFromRoot.resolve.paths(packageName) ?? []) {
+		const packageRoot = (0, path.join)(modulesDir, packageName);
+		if (!(0, fs.existsSync)((0, path.join)(packageRoot, "package.json"))) continue;
+		const candidate = (0, path.join)(packageRoot, subpath);
+		if ((0, fs.existsSync)(candidate)) return candidate;
+	}
+	try {
+		const packageRoot = packageRootFromEntry(requireFromRoot.resolve(packageName));
+		if (!packageRoot) return null;
+		const candidate = (0, path.join)(packageRoot, subpath);
+		return (0, fs.existsSync)(candidate) ? candidate : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region pipeline/correlate-external-tokens.ts
+/**
+* Index the loader-captured theme manifests by owning specifier. Module paths
+* are canonical absolute paths (symlinks resolved), so each package dir is
+* realpath'd before prefix-matching; a module outside every known package dir
+* (typically the consumer's own theme) contributes nothing.
+*/
+function buildSourceTokenIndex(opts) {
+	const index = /* @__PURE__ */ new Map();
+	if (!opts.sourceThemeManifestsJson) return index;
+	let manifests;
+	try {
+		manifests = JSON.parse(opts.sourceThemeManifestsJson);
+	} catch {
+		return index;
+	}
+	const realDirOwners = [];
+	const addOwnerDir = (dir, specifier) => {
+		if (!realDirOwners.some((entry) => entry.dir === dir)) realDirOwners.push({
+			dir,
+			specifier
+		});
+	};
+	for (const [dir, specifier] of Object.entries(opts.dirOwners)) {
+		let real = dir;
+		try {
+			real = (0, fs.realpathSync)(dir);
+		} catch {}
+		addOwnerDir(real, specifier);
+		let packageRoot = real;
+		while (packageRoot !== (0, path.dirname)(packageRoot) && !(0, fs.existsSync)((0, path.join)(packageRoot, "package.json"))) packageRoot = (0, path.dirname)(packageRoot);
+		if ((0, fs.existsSync)((0, path.join)(packageRoot, "package.json"))) addOwnerDir(packageRoot, specifier);
+	}
+	for (const [modulePath, exports] of Object.entries(manifests)) {
+		const owner = realDirOwners.find(({ dir }) => modulePath === dir || modulePath.startsWith(dir + path.sep));
+		if (!owner) continue;
+		let tokens = index.get(owner.specifier);
+		if (!tokens) {
+			tokens = /* @__PURE__ */ new Set();
+			index.set(owner.specifier, tokens);
+		}
+		for (const paths of Object.values(exports)) for (const token of paths) tokens.add(token);
+	}
+	return index;
+}
+/**
+* The correlation join. Returns one teaching-error message per distinct
+* (component, token, specifier) whose file belongs to a discovered source AND
+* whose token that source's manifest defines. The messages follow the
+* standard severity routing at the CALLER (throw under `strict`, warn
+* otherwise) — this join never reports on its own.
+*/
+function correlateExternalTokenDiagnostics(opts) {
+	const messages = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const diagnostic of opts.diagnostics ?? []) {
+		if (diagnostic.kind !== "external-token-candidate" || !diagnostic.token) continue;
+		const specifier = opts.fileOwners[diagnostic.file];
+		if (!specifier) continue;
+		if (!opts.sourceTokens.get(specifier)?.has(diagnostic.token)) continue;
+		const key = `${diagnostic.component}\u0000${diagnostic.token}\u0000${specifier}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		messages.push(`${diagnostic.component} (from '${specifier}') references token '${diagnostic.token}', which the consumer theme does not define — inherit the source's tokens with createTheme().extend(...) using the tokens (or bundle) export of '${specifier}'`);
+	}
+	return messages;
+}
+const indexCache = /* @__PURE__ */ new WeakMap();
+/**
+* The complete cross-source token-contract gate both plugins share
+* (extraction-diagnostics): index the loader-captured source manifests,
+* join them against the engine's candidates, and route the resulting
+* teaching errors — throw under `strict`, warn otherwise. One entry point
+* so the two hosts cannot drift on wiring or severity semantics.
+*/
+function enforceExternalTokenContracts(opts) {
+	const manifestsJson = opts.sourceThemeManifestsJson ?? "";
+	const cached = indexCache.get(opts.dirOwners);
+	let sourceTokens;
+	if (cached && cached.manifestsJson === manifestsJson) sourceTokens = cached.index;
+	else {
+		sourceTokens = buildSourceTokenIndex({
+			sourceThemeManifestsJson: opts.sourceThemeManifestsJson,
+			dirOwners: opts.dirOwners
+		});
+		indexCache.set(opts.dirOwners, {
+			manifestsJson,
+			index: sourceTokens
+		});
+	}
+	const messages = correlateExternalTokenDiagnostics({
+		diagnostics: opts.diagnostics,
+		fileOwners: opts.fileOwners,
+		sourceTokens
+	});
+	if (messages.length === 0) return;
+	if (opts.strict) throw new Error(`${opts.prefix} ${messages.join("\n")}`);
+	for (const message of messages) opts.warn(message);
+}
+//#endregion
 //#region pipeline/path-aliases.ts
 /**
 * Normalize alias pairs: strip a `rootDir` prefix from targets, classify
@@ -643,9 +1087,15 @@ function buildAnalysisInputs(opts) {
 		pathAliasesJson: opts.pathAliasesJson,
 		keyframesJson: opts.system.keyframesJson,
 		staticCssJson: opts.staticCssJson ?? null,
-		conditionAliasesJson: opts.system.conditionAliasesJson ?? null
+		conditionAliasesJson: opts.system.conditionAliasesJson ?? null,
+		externalDirsJson: opts.externalDirs?.length && hasSourceThemeManifests(opts.system) ? JSON.stringify(opts.externalDirs) : null
 	};
 }
+/** Whether the loader captured at least one source built-theme manifest. */
+function hasSourceThemeManifests(system) {
+	const json = system.sourceThemeManifestsJson;
+	return typeof json === "string" && json.length > 0 && json !== "{}";
+}
 /**
 * The one analysis invocation both plugins share: build the emitter
 * config, serialize inputs, call the NAPI `analyzeProject`, parse the
@@ -778,7 +1228,8 @@ function loadSystemConfig(engineApi, opts) {
 		conditionAliasesJson: config.conditionAliases || null,
 		globalStyleBlocksJson: config.globalStyleBlocks || null,
 		keyframesJson: config.keyframesBlocks || null,
-		dependencies: config.dependencies ?? []
+		dependencies: config.dependencies ?? [],
+		sourceThemeManifestsJson: config.sourceThemeManifests || null
 	};
 }
 //#endregion
@@ -1136,17 +1587,23 @@ exports.collectExternalPackageSources = collectExternalPackageSources;
 exports.contentHash = contentHash;
 exports.createV2EngineApi = createV2EngineApi;
 exports.discoverFiles = discoverFiles;
+exports.enforceExternalTokenContracts = enforceExternalTokenContracts;
 exports.extractSystemFilePackages = extractSystemFilePackages;
+exports.findAssetSpecifiers = findAssetSpecifiers;
 exports.findPackageRoot = findPackageRoot;
 exports.formatRustTimingWaterfall = formatRustTimingWaterfall;
 exports.loadSystemConfig = loadSystemConfig;
 exports.postProcessCss = postProcessCss;
 exports.preprocessMdx = preprocessMdx;
 exports.readTsconfigAliasPairs = readTsconfigAliasPairs;
+exports.resolveAssetFile = resolveAssetFile;
 exports.resolveLightningTargets = resolveLightningTargets;
+exports.resolveThroughPathAliases = resolveThroughPathAliases;
 exports.runProjectAnalysis = runProjectAnalysis;
 exports.serializeStaticCss = serializeStaticCss;
+exports.staleDistIncludesMessage = staleDistIncludesMessage;
 exports.stripLeadingLayerDeclaration = stripLeadingLayerDeclaration;
+exports.substituteAssetPlaceholders = substituteAssetPlaceholders;
 exports.surfaceManifestDiagnostics = surfaceManifestDiagnostics;
 exports.toWatchKeys = toWatchKeys;
 exports.unresolvableIncludesMessage = unresolvableIncludesMessage;