@animus-ui/next-plugin 0.1.9 → 0.1.12

package/dist/turbopack-loader.cjs

@@ -19,14 +19,14 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_session_paths = require("./session-paths-CZoi19NW.cjs");
-const require_loader_core = require("./loader-core-C40WbC6s.cjs");
+const require_loader_core = require("./loader-core-BthLSJQF.cjs");
 let _animus_ui_extract_pipeline = require("@animus-ui/extract/pipeline");
+let _animus_ui_extract_session = require("@animus-ui/extract/session");
 let fs = require("fs");
 fs = __toESM(fs);
 let path = require("path");
@@ -34,11 +34,8 @@ let path = require("path");
 let engine = null;
 let sentSources = null;
 let driftWarned = false;
-/** Hydration identity: `${commitPath}:${contentHash(commitRaw)}` — the
-*  commit CONTENT keys hydration; mtime/size never do (design D1). */
 let hydratedKey = null;
 let hydratedManifestJson = null;
-/** Committed per-file analyzed content hashes (from the inputs). */
 let hydratedFileHashes = null;
 const engineModuleId = "@animus-ui/extract";
 const engineApi = (0, _animus_ui_extract_pipeline.createV2EngineApi)({
@@ -61,15 +58,18 @@ const engineApi = (0, _animus_ui_extract_pipeline.createV2EngineApi)({
 		}
 	}
 });
+let engineApiImpl = engineApi;
+/** @internal test seam. */
+function __setTurbopackLoaderEngineApiForTests(api) {
+	engineApiImpl = api ?? engineApi;
+}
 let fsImpl = fs;
-/** @internal test seam — pass null to restore the real fs. */
+/** @internal test seam. */
 function __setTurbopackLoaderFsForTests(fs$1) {
 	fsImpl = fs$1 ?? fs;
 }
-/** Epoch artifact paths SEEN on disk (per-worker) — the artifact is never
-*  deleted once written, so a positive probe is stable; negatives re-probe. */
 const epochSeenPaths = /* @__PURE__ */ new Set();
-/** @internal test seam — drop worker-local hydration state. */
+/** @internal test seam. */
 function __resetTurbopackLoaderStateForTests() {
 	hydratedKey = null;
 	hydratedManifestJson = null;
@@ -83,16 +83,10 @@ function readFileOrNull(path$1) {
 		return null;
 	}
 }
-const SEQLOCK_RETRIES = 5;
-/**
-* Seqlock-style artifact read: commit C0 → payloads → hash verification
-* against C0 → commit re-read; accept only if unchanged, else retry
-* (bounded) — a torn or mismatched set is never consumed (design D1).
-* Hydration replays the committed analysis inputs once per commit content.
-*/
+const ARTIFACT_READ_RETRIES = 5;
 function hydrateSession(sessionDir, sessionId) {
-	const commitPath = require_session_paths.analysisCommitPath(sessionDir);
-	for (let attempt = 0; attempt < SEQLOCK_RETRIES; attempt++) {
+	const commitPath = (0, _animus_ui_extract_session.analysisCommitPath)(sessionDir);
+	for (let attempt = 0; attempt < ARTIFACT_READ_RETRIES; attempt++) {
 		const c0raw = readFileOrNull(commitPath);
 		if (c0raw === null) return { kind: "absent" };
 		let c0;
@@ -114,26 +108,26 @@ function hydrateSession(sessionDir, sessionId) {
 				commitRaw: c0raw
 			}
 		};
-		const manifestRaw = readFileOrNull(require_session_paths.manifestPath(sessionDir));
-		const inputsRaw = readFileOrNull(require_session_paths.analysisInputsPath(sessionDir));
+		const manifestRaw = readFileOrNull((0, _animus_ui_extract_session.manifestPath)(sessionDir));
+		const inputsRaw = readFileOrNull((0, _animus_ui_extract_session.analysisInputsPath)(sessionDir));
 		if (manifestRaw === null || inputsRaw === null) continue;
 		if ((0, _animus_ui_extract_pipeline.contentHash)(manifestRaw) !== c0.manifestHash || (0, _animus_ui_extract_pipeline.contentHash)(inputsRaw) !== c0.inputsHash) continue;
 		if (readFileOrNull(commitPath) !== c0raw) continue;
 		let inputs;
 		let fileHashes;
 		try {
-			const envelopeSession = require_session_paths.readJsonEnvelope(manifestRaw)?.sessionId;
+			const envelopeSession = (0, _animus_ui_extract_session.readJsonEnvelope)(manifestRaw)?.sessionId;
 			if (envelopeSession !== void 0 && envelopeSession !== sessionId) return {
 				kind: "foreign",
 				artifactSessionId: String(envelopeSession)
 			};
 			const inputsParsed = JSON.parse(inputsRaw);
 			inputs = inputsParsed;
-			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map(JSON.parse(inputs.filesJson).map((entry) => [entry.path, entry.hash ?? (0, _animus_ui_extract_pipeline.contentHash)(entry.source)]));
+			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map((0, _animus_ui_extract_pipeline.parseFilesJson)(inputs.filesJson, "animus-next-turbopack").map((entry) => [entry.path, entry.hash ?? (0, _animus_ui_extract_pipeline.contentHash)(entry.source)]));
 		} catch {
 			return { kind: "torn" };
 		}
-		const { analyzeProject } = engineApi();
+		const { analyzeProject } = engineApiImpl();
 		hydratedManifestJson = analyzeProject(...(0, _animus_ui_extract_pipeline.buildAnalyzeProjectArgs)(inputs));
 		hydratedFileHashes = fileHashes;
 		hydratedKey = key;
@@ -149,7 +143,7 @@ function hydrateSession(sessionDir, sessionId) {
 	return { kind: "torn" };
 }
 function readStatus(sessionDir) {
-	const raw = readFileOrNull(require_session_paths.analysisStatusPath(sessionDir));
+	const raw = readFileOrNull((0, _animus_ui_extract_session.analysisStatusPath)(sessionDir));
 	if (raw === null) return null;
 	try {
 		return JSON.parse(raw);
@@ -157,54 +151,47 @@ function readStatus(sessionDir) {
 		return null;
 	}
 }
+const hasReadableDeadline = (status) => Object.prototype.toString.call(status.deadlineAt) === "[object Number]";
 const CATCHUP_POLL_INITIAL_MS = 10;
 const CATCHUP_POLL_MAX_MS = 25;
 const CATCHUP_WAIT_MARGIN_MS = 50;
-const CATCHUP_WATCHDOG_MS = 2e3;
-/** The loader cannot read the orchestrator's configured debounce, so its
-*  own ceiling assumes the default watcher debounce. */
-const DEFAULT_DEBOUNCE_CEILING_MS = 75;
+/** Bounds the one wait carrying no deadline — a status whose `deadlineAt` is
+*  not numeric. The session-published deadline bounds every other wait.
+*  Equal to the session's status watchdog by coincidence only: never unify
+*  them, and never re-derive a deadline from the watcher debounce. */
+const CATCHUP_NO_DEADLINE_CAP_MS = 2e3;
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const ACTIVE_STATES = new Set([
+const ACTIVE_STATES = /* @__PURE__ */ new Set([
 	"starting",
 	"debouncing",
 	"analyzing",
 	"committing"
 ]);
-/**
-* Turbopack loader for Animus source transformation. Derives everything
-* from the incoming source, its JSON-serializable options (carrying the
-* session identity), and the session's COMMITTED disk artifacts written by
-* the out-of-band orchestrator. Async by contract — the evidence-based
-* catch-up (design D3) waits, bounded, for an imminent commit.
-*/
 function animusTurbopackLoader(source) {
-	if (typeof this.async !== "function") throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
+	if (this.async === void 0) throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
 	const callback = this.async();
-	runLoader(this, source).then((code) => callback(null, code), (err) => callback(err instanceof Error ? err : new Error(String(err))));
+	runLoader(this, source).then((code) => callback(null, code), (thrown) => callback(thrown instanceof Error ? thrown : new Error(String(thrown))));
 }
 async function runLoader(ctx, source) {
 	const opts = ctx.getOptions?.() ?? {};
 	const rootDir = opts.rootDir ?? ctx.rootContext;
 	const sessionId = opts.sessionId;
-	const sessionDir = opts.sessionDir ?? (sessionId !== void 0 ? require_session_paths.sessionArtifactDir(rootDir, sessionId) : void 0);
+	const sessionDir = opts.sessionDir ?? (sessionId !== void 0 ? (0, _animus_ui_extract_session.sessionArtifactDir)(rootDir, sessionId) : void 0);
 	if (sessionId === void 0 || sessionDir === void 0) return source;
-	const commitPath = require_session_paths.analysisCommitPath(sessionDir);
-	const statusPath = require_session_paths.analysisStatusPath(sessionDir);
-	const epochPath = require_session_paths.replacementEpochPath(sessionDir);
-	if (typeof ctx.addDependency === "function" && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
+	const commitPath = (0, _animus_ui_extract_session.analysisCommitPath)(sessionDir);
+	const statusPath = (0, _animus_ui_extract_session.analysisStatusPath)(sessionDir);
+	const epochPath = (0, _animus_ui_extract_session.replacementEpochPath)(sessionDir);
+	if (ctx.addDependency !== void 0 && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
 		epochSeenPaths.add(epochPath);
 		ctx.addDependency(epochPath);
 	}
 	const filename = (0, path.relative)(rootDir, ctx.resourcePath);
-	/** EVERY failing path registers the commit + status artifacts as
-	*  dependencies BEFORE throwing (the loader-runner sends dependency IPC
-	*  ahead of the error check upstream), so a landing commit or status
-	*  transition re-triggers the invocation — the documented
-	*  read→registration race makes this a recovery aid, never the primary
-	*  wakeup (design D3). Successful paths add NO commit/status dependency. */
+	/** Registers commit and status as dependencies before throwing: the runner
+	*  sends dependency IPC ahead of the error, so a landing commit re-fires.
+	*  Failure paths only — successful paths register neither, so this must not
+	*  be hoisted out of the failure helper. */
 	const coverageFailure = (message) => {
 		ctx.addDependency?.(commitPath);
 		ctx.addDependency?.(statusPath);
@@ -214,12 +201,12 @@ async function runLoader(ctx, source) {
 		source,
 		filename,
 		manifestJson,
-		engineApi,
+		engineApi: engineApiImpl,
 		opts
 	});
 	const outcome = hydrateSession(sessionDir, sessionId);
 	if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId} — refusing to transform from a foreign generation`);
-	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${SEQLOCK_RETRIES} attempts`);
+	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${ARTIFACT_READ_RETRIES} attempts`);
 	let sourceHash = null;
 	if (outcome.kind === "ok") {
 		const analyzedHash = outcome.hydration.fileHashes.get(filename);
@@ -237,17 +224,9 @@ async function runLoader(ctx, source) {
 		transform
 	});
 }
-/**
-* The catch-up decision table (design D3 — implemented verbatim). Waits —
-* polled, bounded — ONLY in the two evidence states: commit absent while an
-* attempt is active, or the active attempt's pending set contains this file
-* at its current hash. Everything else fails immediately with its stable
-* diagnostic. The moment a commit lands that covers the input, the seqlock
-* hydration consumes it and the transform proceeds with no diagnostic.
-*/
 async function awaitCoverage(args) {
 	const { source, sourceHash, filename, sessionId, sessionDir, coverageFailure, transform } = args;
-	const ceiling = Date.now() + DEFAULT_DEBOUNCE_CEILING_MS + CATCHUP_WATCHDOG_MS + CATCHUP_WAIT_MARGIN_MS;
+	const noDeadlineCap = Date.now() + CATCHUP_NO_DEADLINE_CAP_MS + CATCHUP_WAIT_MARGIN_MS;
 	let poll = CATCHUP_POLL_INITIAL_MS;
 	for (;;) {
 		const outcome = hydrateSession(sessionDir, sessionId);
@@ -269,14 +248,15 @@ async function awaitCoverage(args) {
 			if (!(status.pending ?? []).some(([key, hash]) => key === filename && hash === sourceHash)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: the active analysis attempt (${status.attemptId}) has not observed ${filename} at its current content`);
 		}
 		const now = Date.now();
-		if (typeof status.deadlineAt === "number" && now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
-		if (now > ceiling) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
+		if (hasReadableDeadline(status)) {
+			if (now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
+		} else if (now > noDeadlineCap) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
 		await sleep(poll);
 		poll = CATCHUP_POLL_MAX_MS;
 	}
 }
 //#endregion
 exports.__resetTurbopackLoaderStateForTests = __resetTurbopackLoaderStateForTests;
+exports.__setTurbopackLoaderEngineApiForTests = __setTurbopackLoaderEngineApiForTests;
 exports.__setTurbopackLoaderFsForTests = __setTurbopackLoaderFsForTests;
-exports.__toESM = __toESM;
 exports.default = animusTurbopackLoader;

package/dist/turbopack-loader.d.ts

@@ -1,39 +1,27 @@
 import * as nodeFs from 'fs';
-import type { LoaderPolicyOptions } from './loader-core';
-/** JSON-serializable loader options (Turbopack forwards them across process
- *  boundaries). The session identity is a REAL task input (design D2):
- *  restarts mint a new session id, so cross-session cache reuse is
- *  impossible by construction — restart-cold is normative. */
+import type { LoaderContextBase, LoaderPolicyOptions } from './loader-core';
+import type { EngineApi } from '@animus-ui/extract/pipeline';
+/** Turbopack runs loaders in isolated worker processes, so globalThis-keyed
+ *  session state answers about another process: identity arrives through
+ *  these options. The session barrel may be imported here for its pure path
+ *  builders and JSON readers only, never for its singleton accessors. */
 export interface TurbopackLoaderOptions extends LoaderPolicyOptions {
     rootDir?: string;
     sessionId?: string;
     sessionDir?: string;
 }
 type LoaderCallback = (err: Error | null, content?: string) => void;
-type LoaderContext = {
-    resourcePath: string;
-    rootContext: string;
-    getOptions: () => TurbopackLoaderOptions;
-    /** File-dependency registration (Turbopack loader-runner IPC sends
-     *  dependencies BEFORE the error check — throw-after-addDependency is a
-     *  sound recovery primitive; see design D3). */
-    addDependency?: (file: string) => void;
-    /** Async-completion handle (webpack loader convention) — required: the
-     *  evidence-based catch-up wait cannot run synchronously. */
+type LoaderContext = LoaderContextBase<TurbopackLoaderOptions> & {
     async?: () => LoaderCallback;
 };
+type LoaderEngineApi = () => Pick<EngineApi, 'analyzeProject' | 'transformFile'>;
+/** @internal test seam. */
+export declare function __setTurbopackLoaderEngineApiForTests(api: LoaderEngineApi | null): void;
 type LoaderFs = Pick<typeof nodeFs, 'readFileSync' | 'existsSync'>;
-/** @internal test seam — pass null to restore the real fs. */
+/** @internal test seam. */
 export declare function __setTurbopackLoaderFsForTests(fs: LoaderFs | null): void;
-/** @internal test seam — drop worker-local hydration state. */
+/** @internal test seam. */
 export declare function __resetTurbopackLoaderStateForTests(): void;
-/**
- * Turbopack loader for Animus source transformation. Derives everything
- * from the incoming source, its JSON-serializable options (carrying the
- * session identity), and the session's COMMITTED disk artifacts written by
- * the out-of-band orchestrator. Async by contract — the evidence-based
- * catch-up (design D3) waits, bounded, for an imminent commit.
- */
 export default function animusTurbopackLoader(this: LoaderContext, source: string): void;
 export {};
 //# sourceMappingURL=turbopack-loader.d.ts.map

package/dist/turbopack-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turbopack-loader.d.ts","sourceRoot":"","sources":["../src/turbopack-loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,MAAM,IAAI,CAAC;AAc7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAOzD;;;8DAG8D;AAC9D,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpE,KAAK,aAAa,GAAG;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,sBAAsB,CAAC;IACzC;;oDAEgD;IAChD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;iEAC6D;IAC7D,KAAK,CAAC,EAAE,MAAM,cAAc,CAAC;CAC9B,CAAC;AAgDF,KAAK,QAAQ,GAAG,IAAI,CAAC,OAAO,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;AAGnE,8DAA8D;AAC9D,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAExE;AAMD,+DAA+D;AAC/D,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D;AAkKD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CAcN"}
+{"version":3,"file":"turbopack-loader.d.ts","sourceRoot":"","sources":["../src/turbopack-loader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,MAAM,MAAM,IAAI,CAAC;AAK7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAEV,SAAS,EAEV,MAAM,6BAA6B,CAAC;AAUrC;;;yEAGyE;AACzE,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpE,KAAK,aAAa,GAAG,iBAAiB,CAAC,sBAAsB,CAAC,GAAG;IAC/D,KAAK,CAAC,EAAE,MAAM,cAAc,CAAC;CAC9B,CAAC;AAgCF,KAAK,eAAe,GAAG,MAAM,IAAI,CAC/B,SAAS,EACT,gBAAgB,GAAG,eAAe,CACnC,CAAC;AAGF,2BAA2B;AAC3B,wBAAgB,qCAAqC,CACnD,GAAG,EAAE,eAAe,GAAG,IAAI,GAC1B,IAAI,CAEN;AAED,KAAK,QAAQ,GAAG,IAAI,CAAC,OAAO,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;AAGnE,2BAA2B;AAC3B,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAExE;AAID,2BAA2B;AAC3B,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D;AA6ID,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CAYN"}

package/dist/turbopack-loader.mjs

@@ -1,20 +1,21 @@
-import { S as __require, _ as replacementEpochPath, d as analysisStatusPath, g as readJsonEnvelope, l as analysisCommitPath, m as manifestPath, u as analysisInputsPath, v as sessionArtifactDir } from "./session-paths-DfYIPDcM.mjs";
-import { t as transformWithManifest } from "./loader-core-D6Tm_b8F.mjs";
-import { buildAnalyzeProjectArgs, contentHash, createV2EngineApi } from "@animus-ui/extract/pipeline";
+import { t as transformWithManifest } from "./loader-core-x6cOzF9v.mjs";
+import { createRequire } from "node:module";
+import { buildAnalyzeProjectArgs, contentHash, createV2EngineApi, parseFilesJson } from "@animus-ui/extract/pipeline";
+import { analysisCommitPath, analysisInputsPath, analysisStatusPath, manifestPath, readJsonEnvelope, replacementEpochPath, sessionArtifactDir } from "@animus-ui/extract/session";
 import * as nodeFs from "fs";
 import { relative } from "path";
+//#region \0rolldown/runtime.js
+var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
+//#endregion
 //#region src/turbopack-loader.ts
 let engine = null;
 let sentSources = null;
 let driftWarned = false;
-/** Hydration identity: `${commitPath}:${contentHash(commitRaw)}` — the
-*  commit CONTENT keys hydration; mtime/size never do (design D1). */
 let hydratedKey = null;
 let hydratedManifestJson = null;
-/** Committed per-file analyzed content hashes (from the inputs). */
 let hydratedFileHashes = null;
 const engineModuleId = "@animus-ui/extract";
-const engineApi = createV2EngineApi({
+const engineApi$1 = createV2EngineApi({
 	label: "animus-next-turbopack",
 	isV2: () => true,
 	loadNativeEngine: () => __require(engineModuleId),
@@ -34,15 +35,18 @@ const engineApi = createV2EngineApi({
 		}
 	}
 });
+let engineApiImpl = engineApi$1;
+/** @internal test seam. */
+function __setTurbopackLoaderEngineApiForTests(api) {
+	engineApiImpl = api ?? engineApi$1;
+}
 let fsImpl = nodeFs;
-/** @internal test seam — pass null to restore the real fs. */
+/** @internal test seam. */
 function __setTurbopackLoaderFsForTests(fs) {
 	fsImpl = fs ?? nodeFs;
 }
-/** Epoch artifact paths SEEN on disk (per-worker) — the artifact is never
-*  deleted once written, so a positive probe is stable; negatives re-probe. */
 const epochSeenPaths = /* @__PURE__ */ new Set();
-/** @internal test seam — drop worker-local hydration state. */
+/** @internal test seam. */
 function __resetTurbopackLoaderStateForTests() {
 	hydratedKey = null;
 	hydratedManifestJson = null;
@@ -56,16 +60,10 @@ function readFileOrNull(path) {
 		return null;
 	}
 }
-const SEQLOCK_RETRIES = 5;
-/**
-* Seqlock-style artifact read: commit C0 → payloads → hash verification
-* against C0 → commit re-read; accept only if unchanged, else retry
-* (bounded) — a torn or mismatched set is never consumed (design D1).
-* Hydration replays the committed analysis inputs once per commit content.
-*/
+const ARTIFACT_READ_RETRIES = 5;
 function hydrateSession(sessionDir, sessionId) {
 	const commitPath = analysisCommitPath(sessionDir);
-	for (let attempt = 0; attempt < SEQLOCK_RETRIES; attempt++) {
+	for (let attempt = 0; attempt < ARTIFACT_READ_RETRIES; attempt++) {
 		const c0raw = readFileOrNull(commitPath);
 		if (c0raw === null) return { kind: "absent" };
 		let c0;
@@ -102,11 +100,11 @@ function hydrateSession(sessionDir, sessionId) {
 			};
 			const inputsParsed = JSON.parse(inputsRaw);
 			inputs = inputsParsed;
-			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map(JSON.parse(inputs.filesJson).map((entry) => [entry.path, entry.hash ?? contentHash(entry.source)]));
+			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map(parseFilesJson(inputs.filesJson, "animus-next-turbopack").map((entry) => [entry.path, entry.hash ?? contentHash(entry.source)]));
 		} catch {
 			return { kind: "torn" };
 		}
-		const { analyzeProject } = engineApi();
+		const { analyzeProject } = engineApiImpl();
 		hydratedManifestJson = analyzeProject(...buildAnalyzeProjectArgs(inputs));
 		hydratedFileHashes = fileHashes;
 		hydratedKey = key;
@@ -130,33 +128,28 @@ function readStatus(sessionDir) {
 		return null;
 	}
 }
+const hasReadableDeadline = (status) => Object.prototype.toString.call(status.deadlineAt) === "[object Number]";
 const CATCHUP_POLL_INITIAL_MS = 10;
 const CATCHUP_POLL_MAX_MS = 25;
 const CATCHUP_WAIT_MARGIN_MS = 50;
-const CATCHUP_WATCHDOG_MS = 2e3;
-/** The loader cannot read the orchestrator's configured debounce, so its
-*  own ceiling assumes the default watcher debounce. */
-const DEFAULT_DEBOUNCE_CEILING_MS = 75;
+/** Bounds the one wait carrying no deadline — a status whose `deadlineAt` is
+*  not numeric. The session-published deadline bounds every other wait.
+*  Equal to the session's status watchdog by coincidence only: never unify
+*  them, and never re-derive a deadline from the watcher debounce. */
+const CATCHUP_NO_DEADLINE_CAP_MS = 2e3;
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const ACTIVE_STATES = new Set([
+const ACTIVE_STATES = /* @__PURE__ */ new Set([
 	"starting",
 	"debouncing",
 	"analyzing",
 	"committing"
 ]);
-/**
-* Turbopack loader for Animus source transformation. Derives everything
-* from the incoming source, its JSON-serializable options (carrying the
-* session identity), and the session's COMMITTED disk artifacts written by
-* the out-of-band orchestrator. Async by contract — the evidence-based
-* catch-up (design D3) waits, bounded, for an imminent commit.
-*/
 function animusTurbopackLoader(source) {
-	if (typeof this.async !== "function") throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
+	if (this.async === void 0) throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
 	const callback = this.async();
-	runLoader(this, source).then((code) => callback(null, code), (err) => callback(err instanceof Error ? err : new Error(String(err))));
+	runLoader(this, source).then((code) => callback(null, code), (thrown) => callback(thrown instanceof Error ? thrown : new Error(String(thrown))));
 }
 async function runLoader(ctx, source) {
 	const opts = ctx.getOptions?.() ?? {};
@@ -167,17 +160,15 @@ async function runLoader(ctx, source) {
 	const commitPath = analysisCommitPath(sessionDir);
 	const statusPath = analysisStatusPath(sessionDir);
 	const epochPath = replacementEpochPath(sessionDir);
-	if (typeof ctx.addDependency === "function" && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
+	if (ctx.addDependency !== void 0 && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
 		epochSeenPaths.add(epochPath);
 		ctx.addDependency(epochPath);
 	}
 	const filename = relative(rootDir, ctx.resourcePath);
-	/** EVERY failing path registers the commit + status artifacts as
-	*  dependencies BEFORE throwing (the loader-runner sends dependency IPC
-	*  ahead of the error check upstream), so a landing commit or status
-	*  transition re-triggers the invocation — the documented
-	*  read→registration race makes this a recovery aid, never the primary
-	*  wakeup (design D3). Successful paths add NO commit/status dependency. */
+	/** Registers commit and status as dependencies before throwing: the runner
+	*  sends dependency IPC ahead of the error, so a landing commit re-fires.
+	*  Failure paths only — successful paths register neither, so this must not
+	*  be hoisted out of the failure helper. */
 	const coverageFailure = (message) => {
 		ctx.addDependency?.(commitPath);
 		ctx.addDependency?.(statusPath);
@@ -187,12 +178,12 @@ async function runLoader(ctx, source) {
 		source,
 		filename,
 		manifestJson,
-		engineApi,
+		engineApi: engineApiImpl,
 		opts
 	});
 	const outcome = hydrateSession(sessionDir, sessionId);
 	if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId} — refusing to transform from a foreign generation`);
-	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${SEQLOCK_RETRIES} attempts`);
+	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${ARTIFACT_READ_RETRIES} attempts`);
 	let sourceHash = null;
 	if (outcome.kind === "ok") {
 		const analyzedHash = outcome.hydration.fileHashes.get(filename);
@@ -210,17 +201,9 @@ async function runLoader(ctx, source) {
 		transform
 	});
 }
-/**
-* The catch-up decision table (design D3 — implemented verbatim). Waits —
-* polled, bounded — ONLY in the two evidence states: commit absent while an
-* attempt is active, or the active attempt's pending set contains this file
-* at its current hash. Everything else fails immediately with its stable
-* diagnostic. The moment a commit lands that covers the input, the seqlock
-* hydration consumes it and the transform proceeds with no diagnostic.
-*/
 async function awaitCoverage(args) {
 	const { source, sourceHash, filename, sessionId, sessionDir, coverageFailure, transform } = args;
-	const ceiling = Date.now() + DEFAULT_DEBOUNCE_CEILING_MS + CATCHUP_WATCHDOG_MS + CATCHUP_WAIT_MARGIN_MS;
+	const noDeadlineCap = Date.now() + CATCHUP_NO_DEADLINE_CAP_MS + CATCHUP_WAIT_MARGIN_MS;
 	let poll = CATCHUP_POLL_INITIAL_MS;
 	for (;;) {
 		const outcome = hydrateSession(sessionDir, sessionId);
@@ -242,11 +225,12 @@ async function awaitCoverage(args) {
 			if (!(status.pending ?? []).some(([key, hash]) => key === filename && hash === sourceHash)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: the active analysis attempt (${status.attemptId}) has not observed ${filename} at its current content`);
 		}
 		const now = Date.now();
-		if (typeof status.deadlineAt === "number" && now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
-		if (now > ceiling) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
+		if (hasReadableDeadline(status)) {
+			if (now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
+		} else if (now > noDeadlineCap) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
 		await sleep(poll);
 		poll = CATCHUP_POLL_MAX_MS;
 	}
 }
 //#endregion
-export { __resetTurbopackLoaderStateForTests, __setTurbopackLoaderFsForTests, animusTurbopackLoader as default };
+export { __resetTurbopackLoaderStateForTests, __setTurbopackLoaderEngineApiForTests, __setTurbopackLoaderFsForTests, animusTurbopackLoader as default };

package/dist/types.d.ts

@@ -2,104 +2,50 @@ import type { StaticCssConfig } from '@animus-ui/extract/pipeline';
 export interface AnimusNextOptions {
     /** Path to a module exporting a SystemInstance from `@animus-ui/system`. */
     system: string;
-    /** Glob patterns to exclude from analysis. */
+    /** Substrings, or globs when `*`/`?` present. Replaces `dist`/`.test.`/
+     *  `.spec.`; `node_modules`, `.next` and `.animus` are always excluded. */
     exclude?: string[];
-    /**
-     * File extensions to scan for component definitions and JSX usages.
-     * Replaces the default list entirely (not additive). Include `.mdx` to
-     * extract components rendered from MDX files — `@mdx-js/mdx` must be
-     * installed as a peer for MDX files to be preprocessed; otherwise the
-     * plugin warns once at buildStart and skips them.
-     *
-     * @default ['.ts', '.tsx', '.js', '.jsx', '.mdx']
-     */
+    /** Extensions scanned for definitions and usages; replaces the default
+     *  `['.ts','.tsx','.js','.jsx','.mdx']`. `.mdx` needs `@mdx-js/mdx`. */
     extensions?: string[];
     /** When true, extraction failures throw instead of warning. */
     strict?: boolean;
-    /**
-     * Project-root-relative path of the single file that receives the
-     * `import '.animus/styles.css'` injection (the stylesheet import is
-     * stripped from every other file to prevent per-chunk CSS duplication).
-     * Set this when your root entry doesn't match the default detection of
-     * `app/layout.*` / `pages/_app.*`, optionally under `src/` — e.g. a
-     * nested App Router root layout like `'src/app/[locale]/layout.tsx'`.
-     */
+    /** Project-root-relative path of the one file that receives the stylesheet
+     *  import; replaces the `app/layout.*` / `pages/_app.*` detection. */
     cssImportTarget?: string;
-    /** Enable verbose logging. */
     verbose?: boolean;
     /** Namespace prefix for CSS variables and class names. */
     prefix?: string;
-    /**
-     * Forced-emission declarations for usage the scanner cannot observe
-     * (CMS-driven variants, spread-hidden props, dynamically selected
-     * components). Declared variants/states/system-prop values and custom
-     * dynamic slots are emitted as if used; entries are labeled as forced
-     * in the extraction report. Empty/absent is a no-op.
-     */
+    /** Forced-emission declarations for usage the scanner cannot observe
+     *  (CMS-driven variants, spread-hidden props). Absent is a no-op. */
     staticCss?: StaticCssConfig;
-    /**
-     * Browser targets for CSS autoprefixing and syntax lowering.
-     * Accepts a browserslist query string or array of queries.
-     * Falls back to project's browserslist config, then to `defaults`.
-     */
+    /** Browserslist query string or array. Falls back to the project's
+     *  browserslist config, then to `defaults`. */
     targets?: string | string[];
-    /**
-     * Control CSS minification of the emitted stylesheet.
-     * - `true`: always minify (dev + prod)
-     * - `false`: never minify (autoprefixing still applies)
-     * - `undefined` (default): minify in production (`NODE_ENV === 'production'`)
-     */
+    /** `true`/`false` force minification on or off; absent minifies in
+     *  production. Autoprefixing applies either way. */
     minify?: boolean;
-    /**
-     * Extraction engine selection. `'v2'` is the only engine and the default,
-     * propagated to every compiler instance (including non-owning ones). The v1
-     * engine was retired (openspec: retire-extract-v1); configuring
-     * `engine: 'v1'` (or setting `ANIMUS_ENGINE=v1`) throws — the selection is
-     * never silently upgraded.
-     *
-     * @default 'v2'
-     */
+    /** Explicit emission mode, winning over the environment signal that
+     *  otherwise decides minification and the dev-diagnostics define. */
+    mode?: 'development' | 'production';
+    /** `'v2'` is the only engine and the default. `engine: 'v1'` or
+     *  `ANIMUS_ENGINE=v1` throws — the selection is never silently upgraded. */
     engine?: 'v2';
-    /**
-     * Turbopack integration mode.
-     *
-     * - `'auto'` (default): activate whenever the process runs under
-     *   Turbopack (Next sets the `TURBOPACK` environment variable for every
-     *   Turbopack dev/build). Zero-config support for Next 16 defaults and
-     *   `next dev --turbopack` on Next 15.
-     * - `'on'`: always generate Turbopack wiring.
-     * - `'off'`: webpack-only; no Turbopack keys are generated.
-     *
-     * When active, extraction runs during next.config resolution (the wrapped
-     * config resolves asynchronously — Next awaits it), a dev watcher re-runs
-     * analysis on source changes, and per-file transforms run in a stateless
-     * loader fed by `.animus/` disk artifacts.
-     */
+    /** `'auto'` (default) generates Turbopack wiring whenever the `TURBOPACK`
+     *  environment variable is set; `'on'` always, `'off'` never. */
     turbopack?: {
         mode?: 'auto' | 'on' | 'off';
     };
-    /**
-     * @deprecated Use `turbopack` — same shape. Honored for one release
-     * cycle with a one-time warning; `turbopack` wins when both are set.
-     */
+    /** @deprecated Use `turbopack` — same shape, and it wins when both are
+     *  set. This alias warns once. */
     unstable_turbopack?: {
         mode?: 'off' | 'auto' | 'on';
     };
-    /**
-     * @internal Absolute path of the loader module registered in the webpack
-     * rule when it is not this package's own dist/src loader (test harnesses
-     * wrapping the real loader in a require-able shim). Feeds the needBuild
-     * loader-chain predicate; `withAnimus` never sets it.
-     */
+    /** @internal Absolute path of a loader module registered in place of this
+     *  package's own; feeds the needBuild loader-chain predicate. */
     loaderPath?: string;
-    /**
-     * Full `@layer` declaration order. Must include all 7 Animus `anm-*`
-     * layers (`anm-global`, `anm-base`, `anm-variants`, `anm-compounds`,
-     * `anm-states`, `anm-system`, `anm-custom`) as a subsequence. Consumer
-     * layers may be interleaved. Names are emitted as-is.
-     *
-     * @example ['reset', 'anm-global', 'anm-base', 'anm-variants', 'anm-compounds', 'anm-states', 'anm-system', 'anm-custom', 'overrides']
-     */
+    /** Full `@layer` declaration order, emitted as-is. Must contain the seven
+     *  `anm-*` layers as a subsequence; consumer layers may be interleaved. */
     layers?: string[];
 }
 //# sourceMappingURL=types.d.ts.map