@animus-ui/extract 0.1.7 → 0.1.9

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { createRequire } from "node:module";
 import { createHash } from "crypto";
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "fs";
-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "path";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "path";
+import { realpathSync as realpathSync$1 } from "node:fs";
+import path, { basename, dirname as dirname$1, join as join$1, normalize } from "node:path";
 import { createRequire as createRequire$1 } from "module";
 import browserslist from "browserslist";
 import { browserslistToTargets, transform } from "lightningcss";
 import { isUnitlessProperty } from "@animus-ui/properties";
-import { realpathSync as realpathSync$1 } 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
@@ -103,7 +103,8 @@ function buildAnalyzeProjectArgs(inputs) {
 		inputs.keyframesJson,
 		inputs.staticCssJson,
 		inputs.conditionAliasesJson,
-		inputs.externalDirsJson
+		inputs.externalDirsJson,
+		inputs.transformSourcesJson
 	];
 }
 //#endregion
@@ -122,7 +123,7 @@ function createV2EngineApi(deps) {
 		return {
 			loadSystemModule: (...args) => native.loadSystemModule(...args),
 			scanKeyframesExports: (entryPath, rootDir) => native.scanKeyframesExports(entryPath, rootDir) ?? null,
-			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson, externalDirsJson) => {
+			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson, externalDirsJson, transformSourcesJson) => {
 				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);
@@ -146,6 +147,7 @@ function createV2EngineApi(deps) {
 					pathAliasesJson: pathAliasesJson ?? void 0,
 					staticCssJson: staticCssJson ?? void 0,
 					externalDirsJson: externalDirsJson ?? void 0,
+					transformSourcesJson: transformSourcesJson ?? void 0,
 					devMode
 				};
 				const engine = new native.ExtractEngine(config);
@@ -317,6 +319,126 @@ function discoverFiles(dir, rootDir, excludePatterns, extensionsSet) {
 	return results;
 }
 //#endregion
+//#region pipeline/source-identity.ts
+/**
+* SourceId derivation authority + allowlist membership (openspec:
+* external-source-watch-ingestion, design D1/D2/D5).
+*
+* One shared derivation produces the canonical source identity consumed by
+* discovery, watch ingestion, ownership, deletion pruning, and diagnostics
+* — raw event paths are lookup INPUTS only, so event spelling (symlink
+* alias vs canonical, lexical vs realpath) can never fork identity.
+*
+* The containment and volume helpers are pure and path-API-injectable so
+* Windows semantics are unit-testable via `path.win32` on any host; runtime
+* callers use the ambient platform implementation.
+*/
+/**
+* Structural containment: `target` is the root itself or a descendant of it,
+* decided by `relative()` shape — never by string prefixing, so `/ui` can
+* never claim `/ui-old`, and a cross-drive win32 target (whose relative()
+* result is absolute) is never contained.
+*/
+function isPathWithinRoot(root, target, pathApi = path) {
+	const rel = pathApi.relative(root, target);
+	return rel === "" || !pathApi.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + pathApi.sep);
+}
+/**
+* Cross-volume gate (design D5): two paths share a platform path root
+* (win32 drive letter or UNC share; always true on posix). Compared
+* case-insensitively — win32 drive letters are case-insensitive.
+*/
+function sharesVolumeRoot(a, b, pathApi = path) {
+	const volumeOf = (p) => pathApi.parse(pathApi.resolve(p)).root.toLowerCase();
+	return volumeOf(a) === volumeOf(b);
+}
+function canonicalize(p) {
+	try {
+		return realpathSync$1(p);
+	} catch {
+		return null;
+	}
+}
+function createSourceIdentity(rootDir) {
+	const normalizedRootDir = path.normalize(rootDir);
+	const canonicalRootDir = canonicalize(normalizedRootDir) ?? normalizedRootDir;
+	const roots = [];
+	const aliases = /* @__PURE__ */ new Map();
+	const owningRecord = (canonicalPath) => {
+		let owner = null;
+		for (const record of roots) {
+			if (!isPathWithinRoot(record.canonical, canonicalPath)) continue;
+			if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+		}
+		return owner;
+	};
+	return {
+		rootDir: normalizedRootDir,
+		canonicalRootDir,
+		registerExternalRoot(root) {
+			const asRegistered = path.normalize(root);
+			const canonical = canonicalize(asRegistered) ?? asRegistered;
+			const existing = roots.find((record) => record.canonical === canonical);
+			if (existing) return existing.canonical;
+			roots.push({
+				asRegistered,
+				canonical
+			});
+			return canonical;
+		},
+		externalRoots() {
+			return roots.map((record) => record.canonical);
+		},
+		resolveSourceId(inputPath) {
+			const lexical = path.normalize(inputPath);
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			const owner = owningRecord(canonical);
+			const ownedBy = (record) => {
+				const pathInRoot = path.relative(record.canonical, canonical);
+				return {
+					sourceKey: path.relative(normalizedRootDir, path.join(record.asRegistered, pathInRoot)),
+					owningRoot: record.canonical,
+					pathInRoot
+				};
+			};
+			const ownerIsMoreSpecific = owner !== null && owner.canonical.length > canonicalRootDir.length;
+			let resolved;
+			if (!ownerIsMoreSpecific && isPathWithinRoot(canonicalRootDir, canonical)) {
+				const key = path.relative(canonicalRootDir, canonical);
+				resolved = {
+					sourceKey: key,
+					owningRoot: null,
+					pathInRoot: key
+				};
+			} else if (owner) resolved = ownedBy(owner);
+			else return null;
+			aliases.set(lexical, resolved);
+			aliases.set(canonical, resolved);
+			return resolved;
+		},
+		resolveDeletedSourceId(inputPath) {
+			return aliases.get(path.normalize(inputPath)) ?? null;
+		},
+		containingExternalRoot(inputPath) {
+			const lexical = path.normalize(inputPath);
+			let owner = null;
+			for (const record of roots) {
+				if (!(isPathWithinRoot(record.canonical, lexical) || isPathWithinRoot(record.asRegistered, lexical))) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			if (owner) return owner.canonical;
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			for (const record of roots) {
+				if (!isPathWithinRoot(record.canonical, canonical)) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			return owner?.canonical ?? null;
+		}
+	};
+}
+//#endregion
 //#region pipeline/discover-packages.ts
 /**
 * Walk up from a resolved package entry file to the nearest directory
@@ -341,6 +463,20 @@ const PACKAGE_SRC_EXCLUDES = [
 	".test.",
 	".spec."
 ];
+/** True when a PACKAGE-RELATIVE path matches a package-source exclusion
+*  fragment (the "within the package" filter — see PACKAGE_SRC_EXCLUDES). */
+function isExcludedPackageRelativePath(rel) {
+	return PACKAGE_SRC_EXCLUDES.some((pattern) => rel.includes(pattern));
+}
+/**
+* THE package-source walk (guardrail G1 — one policy): shared discovery with
+* no consumer patterns, then exclusion by package-relative path so fragments
+* in the package's own location can't blank out its sources. Used by the
+* collector, hosts' dirty-root rewalks, and watch-path classification alike.
+*/
+function walkPackageSources(packageDir, extensionsSet) {
+	return discoverFiles(packageDir, packageDir, [], extensionsSet).filter((absPath) => !isExcludedPackageRelativePath(relative(packageDir, absPath)));
+}
 /** Exclusions for the compiled-output fallback when a package does not ship src/. */
 const PACKAGE_OUTPUT_EXCLUDES = [
 	"node_modules",
@@ -379,7 +515,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 	if (isAbsolute(specifier)) {
 		const resolved = resolveAbsolutePathSpecifier(specifier, extensionsSet);
 		if (!resolved) return null;
-		return !relative(srcDir, resolved).startsWith("..") ? resolved : null;
+		return isPathWithinRoot(srcDir, resolved) ? resolved : null;
 	}
 	const packageName = bareSpecifierPackageName(specifier);
 	return resolveAbsolutePathSpecifier(join(srcDir, specifier.slice(packageName.length + 1) || "index"), extensionsSet);
@@ -393,7 +529,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 * file's mtime is readable. Detection only — reporting is the caller's policy.
 */
 function distEntryIsStale(absEntry, srcDir, srcFiles) {
-	if (!relative(srcDir, absEntry).startsWith("..")) return false;
+	if (isPathWithinRoot(srcDir, absEntry)) return false;
 	let distMtime;
 	try {
 		distMtime = statSync(absEntry).mtimeMs;
@@ -425,15 +561,20 @@ function distEntryIsStale(absEntry, srcDir, srcFiles) {
 * them — any warning or gate is the caller's policy.
 */
 async function collectExternalPackageSources(opts) {
-	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable } = opts;
+	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable, onPackageResolved } = opts;
 	const entries = [];
 	const pushed = /* @__PURE__ */ new Set();
 	const packageMap = {};
 	const sourceEntries = /* @__PURE__ */ new Map();
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
 	const packageDirs = [];
-	const dirOwners = {};
+	const dirOwnerSets = {};
+	const dirExtensions = {};
 	const fileOwners = {};
 	const outcomes = [];
+	const claimDir = (dir, specifier) => {
+		(dirOwnerSets[dir] ??= []).push(specifier);
+	};
 	const alreadyIngested = (relPath) => hasEntry(relPath) || pushed.has(relPath);
 	for (const specifier of specifiers) {
 		let absEntry;
@@ -456,12 +597,15 @@ async function collectExternalPackageSources(opts) {
 		let staleDist = false;
 		if (existsSync(srcDir)) {
 			packageDirs.push(srcDir);
-			dirOwners[srcDir] ??= specifier;
+			claimDir(srcDir, specifier);
+			dirExtensions[srcDir] = [...extensionsSet];
+			onPackageResolved?.(specifier, srcDir);
 			const srcEntry = sourceEntryForSpecifier(specifier, srcDir, extensionsSet);
 			if (srcEntry) {
 				packageMap[specifier] = relative(rootDir, srcEntry);
 				sourceEntries.set(specifier, srcEntry);
 			} else packageMap[specifier] = relative(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, srcEntry ?? absEntry);
 			if (!isAbsolute(specifier)) {
 				const packageName = bareSpecifierPackageName(specifier);
 				if (packageName !== specifier && !(packageName in packageMap)) {
@@ -469,13 +613,11 @@ async function collectExternalPackageSources(opts) {
 					if (rootEntry) {
 						packageMap[packageName] = relative(rootDir, rootEntry);
 						sourceEntries.set(packageName, rootEntry);
+						keyframesScanEntries.set(packageName, rootEntry);
 					}
 				}
 			}
-			const pkgFiles = discoverFiles(srcDir, srcDir, [], extensionsSet).filter((absPath) => {
-				const inPkg = relative(srcDir, absPath);
-				return !PACKAGE_SRC_EXCLUDES.some((pattern) => inPkg.includes(pattern));
-			});
+			const pkgFiles = walkPackageSources(srcDir, extensionsSet);
 			staleDist = distEntryIsStale(absEntry, srcDir, pkgFiles);
 			for (const pkgFile of pkgFiles) {
 				const relPath = relative(rootDir, pkgFile);
@@ -503,10 +645,13 @@ async function collectExternalPackageSources(opts) {
 		} else {
 			const outputDir = dirname(absEntry);
 			packageDirs.push(outputDir);
-			dirOwners[outputDir] ??= specifier;
+			claimDir(outputDir, specifier);
+			onPackageResolved?.(specifier, outputDir);
 			packageMap[specifier] = relative(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, absEntry);
 			const outputExtensions = new Set(extensionsSet);
 			outputExtensions.add(extname(absEntry));
+			dirExtensions[outputDir] = [...outputExtensions];
 			const outputFiles = discoverFiles(outputDir, outputDir, [], outputExtensions).filter((file) => {
 				const relToOutput = relative(outputDir, file);
 				return !PACKAGE_OUTPUT_EXCLUDES.some((pattern) => relToOutput.includes(pattern));
@@ -546,12 +691,78 @@ async function collectExternalPackageSources(opts) {
 		entries,
 		packageMap,
 		sourceEntries,
+		keyframesScanEntries,
 		packageDirs,
-		dirOwners,
+		dirOwnerSets,
+		dirExtensions,
 		fileOwners,
 		outcomes
 	};
 }
+/** First-declared specifier per package dir — the single-value ownership
+*  view correlation consumers key on, derived from `dirOwnerSets`. */
+function firstOwners(dirOwnerSets) {
+	const owners = {};
+	for (const [dir, specifiers] of Object.entries(dirOwnerSets)) if (specifiers.length > 0) owners[dir] = specifiers[0];
+	return owners;
+}
+/**
+* Excise a set of rejected specifiers from a collection result ATOMICALLY
+* (openspec: external-source-watch-ingestion, design D5): the returned copy
+* carries no entries, package-map targets, source entries, package dirs, or
+* ownership for the rejected packages — a package dir is removed only when
+* EVERY specifier that claimed it is rejected (a dir-level rejection, such
+* as the cross-volume gate, always rejects them together). Outcome records
+* are reporting inputs, not membership, and pass through untouched.
+*/
+function excludeCollectedPackages(collected, rejectedSpecifiers, rootDir) {
+	if (rejectedSpecifiers.size === 0) return collected;
+	const rejectedDirs = Object.entries(collected.dirOwnerSets).filter(([, specs]) => specs.every((s) => rejectedSpecifiers.has(s))).map(([dir]) => dir);
+	const underRejectedDir = (absPath) => rejectedDirs.some((dir) => isPathWithinRoot(dir, absPath));
+	const targetRejected = (specifier, absTarget) => rejectedSpecifiers.has(specifier) || underRejectedDir(absTarget);
+	const packageMap = {};
+	for (const [specifier, relTarget] of Object.entries(collected.packageMap)) {
+		if (targetRejected(specifier, resolve(rootDir, relTarget))) continue;
+		packageMap[specifier] = relTarget;
+	}
+	const sourceEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.sourceEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		sourceEntries.set(specifier, absEntry);
+	}
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.keyframesScanEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		keyframesScanEntries.set(specifier, absEntry);
+	}
+	const dirOwnerSets = {};
+	for (const [dir, specs] of Object.entries(collected.dirOwnerSets)) {
+		const kept = specs.filter((s) => !rejectedSpecifiers.has(s));
+		if (kept.length === 0) continue;
+		dirOwnerSets[dir] = kept;
+	}
+	const dirExtensions = {};
+	for (const [dir, exts] of Object.entries(collected.dirExtensions)) {
+		if (rejectedDirs.includes(dir)) continue;
+		dirExtensions[dir] = exts;
+	}
+	const fileOwners = {};
+	for (const [relPath, owner] of Object.entries(collected.fileOwners)) {
+		if (rejectedSpecifiers.has(owner)) continue;
+		fileOwners[relPath] = owner;
+	}
+	return {
+		entries: collected.entries.filter((entry) => !rejectedSpecifiers.has(collected.fileOwners[entry.path])),
+		packageMap,
+		sourceEntries,
+		keyframesScanEntries,
+		packageDirs: collected.packageDirs.filter((dir) => !rejectedDirs.includes(dir)),
+		dirOwnerSets,
+		dirExtensions,
+		fileOwners,
+		outcomes: collected.outcomes
+	};
+}
 /**
 * Extract external DS package names from inheritance declarations in the
 * system file.
@@ -921,7 +1132,7 @@ function buildSourceTokenIndex(opts) {
 		if (existsSync(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 + sep));
+		const owner = realDirOwners.find(({ dir }) => isPathWithinRoot(dir, modulePath));
 		if (!owner) continue;
 		let tokens = index.get(owner.specifier);
 		if (!tokens) {
@@ -1062,16 +1273,42 @@ function postProcessCss(css, opts) {
 /** Stable code for selector forms with no substitutable subject.
 *  Mirrors the Rust constant in `extract-v2/src/eval.rs`. */
 const SELECTOR_UNSUPPORTED_SUBJECT = "animus.selector.unsupported-subject";
+/** Unresolved-parent chain-drop message (mirrors the Rust diagnostic in
+*  `extract-v2` — the ONE encoding of this message shape; consumers match
+*  through the helpers below, never their own regex copies). */
+const UNRESOLVED_PARENT_RE = /chain dropped: could not resolve parent component '([^']+)'/;
+/** True when the diagnostic reports a chain dropped for an unresolved
+*  parent component. */
+function isUnresolvedParentDrop(diagnostic) {
+	return typeof diagnostic?.message === "string" && UNRESOLVED_PARENT_RE.test(diagnostic.message);
+}
+/** The parent binding named by an unresolved-parent drop, or null when the
+*  diagnostic is not one. */
+function unresolvedParentName(diagnostic) {
+	if (typeof diagnostic?.message !== "string") return null;
+	return UNRESOLVED_PARENT_RE.exec(diagnostic.message)?.[1] ?? null;
+}
 /** True when the selector string carries at least one substitutable `&`
 *  subject outside quoted text (mirrors the Rust `selector_subject` walk —
 *  ancestor, leading, and repeated subjects all count; a `&` inside a
 *  quoted attribute value does not). */
 function hasSelectorSubject(value) {
 	let quote = null;
-	for (const c of value) if (quote !== null) {
-		if (c === quote) quote = null;
-	} else if (c === "\"" || c === "'") quote = c;
-	else if (c === "&") return true;
+	let escaped = false;
+	for (const c of value) {
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (c === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote !== null) {
+			if (c === quote) quote = null;
+		} else if (c === "\"" || c === "'") quote = c;
+		else if (c === "&") return true;
+	}
 	return false;
 }
 /**
@@ -1201,6 +1438,7 @@ function buildAnalysisInputs(opts) {
 		keyframesJson: opts.system.keyframesJson,
 		staticCssJson: opts.staticCssJson ?? null,
 		conditionAliasesJson: opts.system.conditionAliasesJson ?? null,
+		transformSourcesJson: opts.system.transformSourcesJson ?? null,
 		externalDirsJson: opts.externalDirs?.length && hasSourceThemeManifests(opts.system) ? JSON.stringify(opts.externalDirs) : null
 	};
 }
@@ -1342,6 +1580,7 @@ function loadSystemConfig(engineApi, opts) {
 		contextualVarsJson,
 		selectorAliasesJson: config.selectorAliases || null,
 		conditionAliasesJson: config.conditionAliases || null,
+		transformSourcesJson: config.transformSources || null,
 		globalStyleBlocksJson: config.globalStyleBlocks || null,
 		keyframesJson: config.keyframesBlocks || null,
 		dependencies: config.dependencies ?? [],
@@ -1587,6 +1826,22 @@ function readTsconfigAliasPairs(rootDir) {
 	return pairs;
 }
 //#endregion
+//#region pipeline/error-diagnostics.ts
+/**
+* Throw when the diagnostics carry any `kind: "error"` entry — one
+* aggregated `Error` naming EVERY offender (component, file, message — one
+* line per entry, each prefixed `[animus]`). Warning-only diagnostics
+* (`bail`/`skip`/`warn`, any severity) never trip this gate; their routing
+* stays with `surfaceManifestDiagnostics`. Callers accept the manifest only
+* past this point, so no stylesheet from a failing analysis is published.
+*/
+function assertNoErrorDiagnostics(diagnostics) {
+	const errors = (diagnostics ?? []).filter((diagnostic) => diagnostic.kind === "error");
+	if (errors.length === 0) return;
+	const lines = [...new Set(errors.map((diagnostic) => `[animus] ${diagnostic.component || "<unknown component>"} (${diagnostic.file || "<unknown file>"}): ${diagnostic.message || "<no message>"}`))];
+	throw new Error(lines.join("\n"));
+}
+//#endregion
 //#region pipeline/mdx-preprocessor.ts
 /**
 * MDX source preprocessor for the extraction pipeline.
@@ -1644,6 +1899,79 @@ async function preprocessMdx(source, filename) {
 	}
 }
 //#endregion
+//#region pipeline/replacement-plans.ts
+const snapshotByManifest = /* @__PURE__ */ new WeakMap();
+function snapshotFilePlans(manifest) {
+	const memoKey = manifest !== null && typeof manifest === "object" ? manifest : null;
+	if (memoKey) {
+		const cached = snapshotByManifest.get(memoKey);
+		if (cached) return cached;
+	}
+	const entriesByFile = /* @__PURE__ */ new Map();
+	for (const [id, desc] of Object.entries(manifest?.components ?? {})) {
+		const file = desc.file;
+		if (!file) continue;
+		const list = entriesByFile.get(file) ?? [];
+		list.push([id, desc.replacement ?? ""]);
+		entriesByFile.set(file, list);
+	}
+	const snapshot = /* @__PURE__ */ new Map();
+	for (const [file, entries] of entriesByFile) {
+		entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+		snapshot.set(file, JSON.stringify(entries));
+	}
+	if (memoKey) snapshotByManifest.set(memoKey, snapshot);
+	return snapshot;
+}
+/**
+* Rel paths whose plan changed between two snapshots: absent→present,
+* present→absent, and any change to membership or replacement content.
+* `exclude` drops one path (the changed file itself on the edit path — its
+* own modules are already in the update set).
+*/
+function diffFilePlans(prev, next, opts) {
+	const changed = /* @__PURE__ */ new Set();
+	for (const [file, plan] of next) if (prev.get(file) !== plan) changed.add(file);
+	for (const file of prev.keys()) if (!next.has(file)) changed.add(file);
+	if (opts?.exclude) changed.delete(opts.exclude);
+	return [...changed].sort();
+}
+/** Domain prefix keeping the epoch hash disjoint from every other
+*  contentHash use in the pipeline (design D5). */
+const REPLACEMENT_PLANS_DOMAIN = "animus-replacement-plans-v1\0";
+/** Section marker for the served-dependency witness. Leads with NUL: every
+*  plan entry ends `…\0` and neither file paths nor plan JSON contain NUL,
+*  so `\0\0` is unreachable from entry serialization alone — a snapshot can
+*  never forge the witness section. */
+const SERVED_DEPENDENCY_DOMAIN = "\0animus-served-dependency-v1\0";
+/**
+* Canonical replacement epoch: contentHash over the domain-prefixed, sorted
+* canonical serialization of a file-plan snapshot — each entry contributes
+* `file + '\0' + plan + '\0'` (unambiguous: neither file paths nor the
+* JSON plan strings contain NUL). Byte-identical plans → identical epoch;
+* any membership/replacement/absent↔present change moves it.
+*
+* `servedDependencyWitness` extends the epoch to content the plans cannot
+* see but restored modules depend on: transformed modules import the
+* session's served system-props artifact, so a consumer passes that
+* artifact's content here and an offline change to it moves the epoch —
+* invalidating persistent-cache snapshots that reference the old epoch
+* artifact. Absence and empty-string are distinct values.
+*
+* This is THE epoch definition — integrations consume this hash (or the
+* snapshot diff) and never define their own. Epoch values compare only for
+* equality (a moved value invalidates), so the serialization is free to
+* evolve with a domain bump: sessions running different serializations
+* simply disagree once and rebuild.
+*/
+function hashReplacementPlans(snapshot, servedDependencyWitness) {
+	const entries = [...snapshot.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	let serialized = REPLACEMENT_PLANS_DOMAIN;
+	for (const [file, plan] of entries) serialized += file + "\0" + plan + "\0";
+	if (servedDependencyWitness !== void 0) serialized += SERVED_DEPENDENCY_DOMAIN + servedDependencyWitness;
+	return contentHash(serialized);
+}
+//#endregion
 //#region pipeline/utils.ts
 /** Convert camelCase CSS property names to kebab-case. */
 function camelToKebab(str) {
@@ -1695,4 +2023,4 @@ function realpathThroughNearestExistingAncestor(path) {
 	}
 }
 //#endregion
-export { ANIMUS_LAYERS, DEFAULT_EXTENSIONS, KEYFRAMES_EXPORT_COLLISION, KEYFRAMES_EXTERNAL_ENTRY_FAILED, RETIRED_ENGINE_MESSAGE, applyPrefix, applyUnitFallback, assembleStylesheet, assertNoRetiredEngineSelection, buildAnalysisInputs, buildAnalyzeProjectArgs, buildDynamicPropConfig, buildPathAliasesJson, buildSystemPropsModule, camelToKebab, clearEngineCache, collectExternalPackageSources, contentHash, createV2EngineApi, discoverFiles, enforceExternalTokenContracts, extractSystemFilePackages, findAssetSpecifiers, findPackageRoot, formatRustTimingWaterfall, loadSystemConfig, mergeExternalKeyframes, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveAssetFile, resolveLightningTargets, resolveThroughPathAliases, runProjectAnalysis, serializeStaticCss, staleDistIncludesMessage, stripLeadingLayerDeclaration, substituteAssetPlaceholders, surfaceManifestDiagnostics, toWatchKeys, unresolvableIncludesMessage, validateLayerOrder };
+export { ANIMUS_LAYERS, DEFAULT_EXTENSIONS, KEYFRAMES_EXPORT_COLLISION, KEYFRAMES_EXTERNAL_ENTRY_FAILED, RETIRED_ENGINE_MESSAGE, applyPrefix, applyUnitFallback, assembleStylesheet, assertNoErrorDiagnostics, assertNoRetiredEngineSelection, buildAnalysisInputs, buildAnalyzeProjectArgs, buildDynamicPropConfig, buildPathAliasesJson, buildSystemPropsModule, camelToKebab, clearEngineCache, collectExternalPackageSources, contentHash, createSourceIdentity, createV2EngineApi, diffFilePlans, discoverFiles, enforceExternalTokenContracts, excludeCollectedPackages, extractSystemFilePackages, findAssetSpecifiers, findPackageRoot, firstOwners, formatRustTimingWaterfall, hashReplacementPlans, isExcludedPackageRelativePath, isPathWithinRoot, isUnresolvedParentDrop, loadSystemConfig, mergeExternalKeyframes, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveAbsolutePathSpecifier, resolveAssetFile, resolveLightningTargets, resolveThroughPathAliases, runProjectAnalysis, serializeStaticCss, sharesVolumeRoot, snapshotFilePlans, staleDistIncludesMessage, stripLeadingLayerDeclaration, substituteAssetPlaceholders, surfaceManifestDiagnostics, toWatchKeys, unresolvableIncludesMessage, unresolvedParentName, validateLayerOrder, walkPackageSources };

package/dist/manifest-diagnostics.d.ts

@@ -15,6 +15,16 @@ export type ManifestDiagnostic = {
 /** Stable code for selector forms with no substitutable subject.
  *  Mirrors the Rust constant in `extract-v2/src/eval.rs`. */
 export declare const SELECTOR_UNSUPPORTED_SUBJECT = "animus.selector.unsupported-subject";
+/** True when the diagnostic reports a chain dropped for an unresolved
+ *  parent component. */
+export declare function isUnresolvedParentDrop(diagnostic: {
+    message?: unknown;
+}): boolean;
+/** The parent binding named by an unresolved-parent drop, or null when the
+ *  diagnostic is not one. */
+export declare function unresolvedParentName(diagnostic: {
+    message?: unknown;
+}): string | null;
 export interface DiagnosticPolicy {
     /** When true, error-severity diagnostics throw instead of warning. */
     strict?: boolean;

package/dist/manifest-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-diagnostics.d.ts","sourceRoot":"","sources":["../pipeline/manifest-diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;6EACyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;sBACkB;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;6DAC6D;AAC7D,eAAO,MAAM,4BAA4B,wCACF,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;gEAC4D;IAC5D,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;wCAGwC;AACxC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAYzD;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7C,kBAAkB,EAAE,CAuBtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE;IAAE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAAE,EAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,MAAM,GAAE,gBAAqB,GAC5B,IAAI,CA+BN"}
+{"version":3,"file":"manifest-diagnostics.d.ts","sourceRoot":"","sources":["../pipeline/manifest-diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;6EACyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;sBACkB;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;6DAC6D;AAC7D,eAAO,MAAM,4BAA4B,wCACF,CAAC;AAQxC;wBACwB;AACxB,wBAAgB,sBAAsB,CAAC,UAAU,EAAE;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAKV;AAED;6BAC6B;AAC7B,wBAAgB,oBAAoB,CAAC,UAAU,EAAE;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAGhB;AAED,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;gEAC4D;IAC5D,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;wCAGwC;AACxC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAqBzD;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7C,kBAAkB,EAAE,CAuBtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE;IAAE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAAE,EAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,MAAM,GAAE,gBAAqB,GAC5B,IAAI,CA+BN"}

package/dist/replacement-plans.d.ts

@@ -0,0 +1,46 @@
+/**
+ * File-plan snapshot/diff — the invalidation candidate source shared by
+ * every analysis path (openspec: dev-transform-coherence,
+ * dev-served-transform-coherence). A file's plan is the keyed, ordered set
+ * of (component id, replacement) pairs the manifest holds for it. A file
+ * with NO entries is ABSENT from the snapshot — a distinct state from a
+ * present entry whose replacement is empty, so raw↔extracted transitions
+ * are plan changes like any other.
+ *
+ * Lives in the shared pipeline package so the Vite diff consumer and the
+ * Next (webpack/Turbopack) epoch consumers share ONE semantic definition
+ * (design D5, next-webpack-served-transform-coherence).
+ */
+export type FilePlanSnapshot = Map<string, string>;
+export declare function snapshotFilePlans(manifest: any): FilePlanSnapshot;
+/**
+ * Rel paths whose plan changed between two snapshots: absent→present,
+ * present→absent, and any change to membership or replacement content.
+ * `exclude` drops one path (the changed file itself on the edit path — its
+ * own modules are already in the update set).
+ */
+export declare function diffFilePlans(prev: FilePlanSnapshot, next: FilePlanSnapshot, opts?: {
+    exclude?: string;
+}): string[];
+/**
+ * Canonical replacement epoch: contentHash over the domain-prefixed, sorted
+ * canonical serialization of a file-plan snapshot — each entry contributes
+ * `file + '\0' + plan + '\0'` (unambiguous: neither file paths nor the
+ * JSON plan strings contain NUL). Byte-identical plans → identical epoch;
+ * any membership/replacement/absent↔present change moves it.
+ *
+ * `servedDependencyWitness` extends the epoch to content the plans cannot
+ * see but restored modules depend on: transformed modules import the
+ * session's served system-props artifact, so a consumer passes that
+ * artifact's content here and an offline change to it moves the epoch —
+ * invalidating persistent-cache snapshots that reference the old epoch
+ * artifact. Absence and empty-string are distinct values.
+ *
+ * This is THE epoch definition — integrations consume this hash (or the
+ * snapshot diff) and never define their own. Epoch values compare only for
+ * equality (a moved value invalidates), so the serialization is free to
+ * evolve with a domain bump: sessions running different serializations
+ * simply disagree once and rebuild.
+ */
+export declare function hashReplacementPlans(snapshot: FilePlanSnapshot, servedDependencyWitness?: string): string;
+//# sourceMappingURL=replacement-plans.d.ts.map

package/dist/replacement-plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replacement-plans.d.ts","sourceRoot":"","sources":["../pipeline/replacement-plans.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAQnD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,gBAAgB,CA4BjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,gBAAgB,EACtB,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1B,MAAM,EAAE,CAUV;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,uBAAuB,CAAC,EAAE,MAAM,GAC/B,MAAM,CAYR"}

package/dist/run-analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-analysis.d.ts","sourceRoot":"","sources":["../pipeline/run-analysis.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,EAAE,GAAG,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB;6EACyE;IACzE,MAAM,EAAE,oBAAoB,CAAC;IAC7B,4DAA4D;IAC5D,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB;;8CAE0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,wBAAwB,EAAE,kBAAkB,EAAE,CAAC;CAC1E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,GACpB,oBAAoB,CAiCtB;AAQD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAEhC,SAAS,EAAE,MAAM,GAAG,EACpB,IAAI,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5E,qBAAqB,CAgCvB;AAED;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,IAAI,CAQ3D"}
+{"version":3,"file":"run-analysis.d.ts","sourceRoot":"","sources":["../pipeline/run-analysis.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,EAAE,GAAG,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB;6EACyE;IACzE,MAAM,EAAE,oBAAoB,CAAC;IAC7B,4DAA4D;IAC5D,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB;;8CAE0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,wBAAwB,EAAE,kBAAkB,EAAE,CAAC;CAC1E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,GACpB,oBAAoB,CAkCtB;AAQD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAEhC,SAAS,EAAE,MAAM,GAAG,EACpB,IAAI,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5E,qBAAqB,CAgCvB;AAED;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,IAAI,CAQ3D"}