@animus-ui/next-plugin 0.1.31 → 0.1.35

package/README.md

@@ -71,6 +71,47 @@ export default withAnimus({
 Under webpack (`next dev` / `next build` on 15, or `--webpack` on 16) the
 plugin behaves exactly as before.
 
+## Third-party stylesheets
+
+A library's plain CSS outside any `@layer` beats every Animus layer. With
+`quarantine`, [`@animus-ui/layergate`](../layergate/README.md) loads it into
+`anm-vendor`, a layer below all of Animus's, so Animus's styles win and the
+library's still apply where Animus sets nothing:
+
+```bash
+npm install -D @animus-ui/layergate
+```
+
+```tsx
+export default withAnimus({
+  system: './src/ds.ts',
+  quarantine: {
+    sheets: ['react-grid-layout/css/styles.css'], // delivered ahead of Animus's own CSS
+    dependencies: ['react-datepicker'], // CSS these packages' modules import
+    optOut: [], // exact files whose own rules stay unlayered
+  },
+})(nextConfig);
+```
+
+It needs webpack: `next dev` and `next build` on Next 15, `--webpack` on
+Next 16. Turbopack runs no loader on the stylesheets a stylesheet imports,
+so with `quarantine` set any Turbopack run fails config loading, whatever
+the `turbopack` option says. Next marks a Turbopack run by setting
+`TURBOPACK`, so Animus refuses whenever that variable is set, even empty.
+The converse: a `TURBOPACK` inherited from the environment also refuses a
+webpack build of Next 15, loudly, so clear stale values in CI.
+
+Vendor stylesheets layergate finishes are not kept in webpack's persistent
+cache, so a warm rebuild finishes them again: about 118 ms per 200 vendor
+sheets in a synthetic measurement.
+
+`sheets` arrive at the head of Animus's own stylesheet, on every page.
+`!important` declarations and animations still win, and are reported. App
+CSS keeps its own rules unlayered; where it imports a vendor file, that file
+is layered. CSS Modules are left alone. A remote `@import` in a vendor
+stylesheet is an error: vendor the sheet locally, or opt the file out if
+unlayered is acceptable.
+
 ## Appearance bootstrap (no-FOUC color mode)
 
 Optional. Restores a persisted color mode before first paint with zero runtime
@@ -128,6 +169,49 @@ Two rules either way:
   you add to the script tag. The full CSP footguns are documented in the
   [`@animus-ui/vite-plugin` README](https://github.com/codecaaron/animus/tree/main/packages/vite-plugin#content-security-policy).
 
+## Font preloads
+
+A font face declared with `preload: true` can start loading before the
+stylesheet's `@font-face` applies. The plugin injects nothing into the
+document, so render the component that delivers it. It renders nothing when
+no face preloads.
+
+**App Router:** render `AnimusFontPreloads` in the root layout. React hoists
+each preload into `<head>` ahead of the stylesheets, and dedupes it by href,
+against `next/font` too.
+
+```tsx
+// app/layout.tsx
+import { AnimusFontPreloads } from '@animus-ui/next-plugin/font-preloads';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <AnimusFontPreloads />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+**Pages Router:** render `AnimusFontPreloadLinks` inside `<Head>` in
+`pages/_document.tsx`. It renders plain `<link>` tags, which any React
+version renders.
+
+Each preload names the URL the stylesheet's `url()` loads (the hashed
+`/_next/static/media/…` file, under webpack and Turbopack, in build and in
+development), so the browser fetches the file once. `withAnimus` adds this
+package to `transpilePackages`, so Next bundles the component and resolves
+the module it reads. Nothing detects a layout that never renders the
+component: the faces then load when the stylesheet applies, as without
+`preload`.
+
 ## MDX
 
 Animus reads each `.mdx` file as the JSX it renders: its imports, exports,

package/dist/font-preloads.cjs

@@ -0,0 +1,60 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
+let react = require("react");
+let react_dom = require("react-dom");
+let virtual_animus_font_preloads = require("virtual:animus/font-preloads");
+virtual_animus_font_preloads = require_rolldown_runtime.__toESM(virtual_animus_font_preloads);
+//#region src/font-preloads.ts
+/**
+* The font preloads the system's faces ask for (`preload: true`), rendered
+* into the document. Server-only; it imports neither the engine nor Node.
+*/
+/** The origins of the absolute hrefs, once each: an asset prefix on
+*  another host makes the bundler's URLs absolute. `fontPreloadOrigins`'s
+*  rule, restated: its module would bring the engine into the bundle. A
+*  malformed href warms no origin, and never fails the render. */
+const ORIGINS = [...new Set(virtual_animus_font_preloads.default.flatMap(({ href }) => {
+	if (!/^(?:https?:)?\/\//i.test(href)) return [];
+	try {
+		const { origin } = new URL(href, "https://animus.invalid");
+		return [href.startsWith("//") ? `//${href.slice(2).split(/[/?#]/)[0]}` : origin];
+	} catch {
+		return [];
+	}
+}))];
+/**
+* App Router: render it in the root layout. React hoists each preload into
+* `<head>` ahead of the stylesheets and dedupes it by href, against
+* `next/font` too. Renders nothing; a no-op when no face preloads.
+*/
+function AnimusFontPreloads() {
+	for (const origin of ORIGINS) (0, react_dom.preconnect)(origin, { crossOrigin: "" });
+	for (const { href, type } of virtual_animus_font_preloads.default) (0, react_dom.preload)(href, {
+		as: "font",
+		type,
+		crossOrigin: ""
+	});
+	return null;
+}
+/**
+* Pages Router: render it inside `<Head>` in `pages/_document`, as plain
+* `<link>` tags any React version renders. Empty when no face preloads.
+*/
+function AnimusFontPreloadLinks() {
+	return (0, react.createElement)(react.Fragment, null, ...ORIGINS.map((origin) => (0, react.createElement)("link", {
+		key: origin,
+		rel: "preconnect",
+		href: origin,
+		crossOrigin: ""
+	})), ...virtual_animus_font_preloads.default.map(({ href, type }) => (0, react.createElement)("link", {
+		key: href,
+		rel: "preload",
+		href,
+		as: "font",
+		type,
+		crossOrigin: ""
+	})));
+}
+//#endregion
+exports.AnimusFontPreloadLinks = AnimusFontPreloadLinks;
+exports.AnimusFontPreloads = AnimusFontPreloads;

package/dist/font-preloads.d.ts

@@ -0,0 +1,13 @@
+import type { ReactElement } from 'react';
+/**
+ * App Router: render it in the root layout. React hoists each preload into
+ * `<head>` ahead of the stylesheets and dedupes it by href, against
+ * `next/font` too. Renders nothing; a no-op when no face preloads.
+ */
+export declare function AnimusFontPreloads(): null;
+/**
+ * Pages Router: render it inside `<Head>` in `pages/_document`, as plain
+ * `<link>` tags any React version renders. Empty when no face preloads.
+ */
+export declare function AnimusFontPreloadLinks(): ReactElement;
+//# sourceMappingURL=font-preloads.d.ts.map

package/dist/font-preloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-preloads.d.ts","sourceRoot":"","sources":["../src/font-preloads.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AA4B1C;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,CAuBrD"}

package/dist/font-preloads.mjs

@@ -0,0 +1,56 @@
+import { Fragment, createElement } from "react";
+import { preconnect, preload } from "react-dom";
+import preloads from "virtual:animus/font-preloads";
+//#region src/font-preloads.ts
+/**
+* The font preloads the system's faces ask for (`preload: true`), rendered
+* into the document. Server-only; it imports neither the engine nor Node.
+*/
+/** The origins of the absolute hrefs, once each: an asset prefix on
+*  another host makes the bundler's URLs absolute. `fontPreloadOrigins`'s
+*  rule, restated: its module would bring the engine into the bundle. A
+*  malformed href warms no origin, and never fails the render. */
+const ORIGINS = [...new Set(preloads.flatMap(({ href }) => {
+	if (!/^(?:https?:)?\/\//i.test(href)) return [];
+	try {
+		const { origin } = new URL(href, "https://animus.invalid");
+		return [href.startsWith("//") ? `//${href.slice(2).split(/[/?#]/)[0]}` : origin];
+	} catch {
+		return [];
+	}
+}))];
+/**
+* App Router: render it in the root layout. React hoists each preload into
+* `<head>` ahead of the stylesheets and dedupes it by href, against
+* `next/font` too. Renders nothing; a no-op when no face preloads.
+*/
+function AnimusFontPreloads() {
+	for (const origin of ORIGINS) preconnect(origin, { crossOrigin: "" });
+	for (const { href, type } of preloads) preload(href, {
+		as: "font",
+		type,
+		crossOrigin: ""
+	});
+	return null;
+}
+/**
+* Pages Router: render it inside `<Head>` in `pages/_document`, as plain
+* `<link>` tags any React version renders. Empty when no face preloads.
+*/
+function AnimusFontPreloadLinks() {
+	return createElement(Fragment, null, ...ORIGINS.map((origin) => createElement("link", {
+		key: origin,
+		rel: "preconnect",
+		href: origin,
+		crossOrigin: ""
+	})), ...preloads.map(({ href, type }) => createElement("link", {
+		key: href,
+		rel: "preload",
+		href,
+		as: "font",
+		type,
+		crossOrigin: ""
+	})));
+}
+//#endregion
+export { AnimusFontPreloadLinks, AnimusFontPreloads };

package/dist/index.cjs

@@ -1,20 +1,21 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_turbopack_config = require("./turbopack-config-BoNfzhNu.cjs");
+const require_turbopack_config = require("./turbopack-config-W5eoa_xN.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");
 let path = require("path");
 let url = require("url");
+let module$1 = require("module");
 //#region src/same-directory.ts
 /** Whether two paths name one directory: by real path, which resolves a
 *  trailing slash, a symlink and the filesystem's own spelling, else by
 *  device and inode. */
 function sameDirectory(a, b) {
-	const real = (path$5) => {
+	const real = (path$12) => {
 		try {
-			return fs.realpathSync.native(path$5);
+			return fs.realpathSync.native(path$12);
 		} catch {
-			return (0, path.resolve)(path$5);
+			return (0, path.resolve)(path$12);
 		}
 	};
 	if (real(a) === real(b)) return true;
@@ -27,11 +28,97 @@ function sameDirectory(a, b) {
 	}
 }
 //#endregion
-//#region src/plugin.ts
+//#region src/watch-ignored.ts
+/**
+* webpack's `watchOptions.ignored`, read as Watchpack reads it, so Animus can
+* wrap it: its own epoch file stays ignored, and the files and directories it
+* registers are watched whatever the host ignores (Next ignores every
+* `node_modules` path, where an installed source kit lives).
+*/
 /** The value arrives from a consumer's `next.config`, so the union above is a
 *  model of what webpack accepts, not a proof about the value in hand. */
 const isWatchIgnoreString = (ignored) => Object.prototype.toString.call(ignored) === "[object String]";
 const isWatchIgnoreMatcher = (ignored) => Object.prototype.toString.call(ignored) === "[object Function]";
+/** A glob as Watchpack compiles it (`glob-to-regexp` with `globstar` and
+*  `extended`, then matching the path or anything under it). */
+function globSource(glob) {
+	let source = "";
+	let inGroup = false;
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index];
+		switch (char) {
+			case "/":
+			case "$":
+			case "^":
+			case "+":
+			case ".":
+			case "(":
+			case ")":
+			case "=":
+			case "!":
+			case "|":
+				source += `\\${char}`;
+				break;
+			case "?":
+				source += ".";
+				break;
+			case "{":
+				inGroup = true;
+				source += "(";
+				break;
+			case "}":
+				inGroup = false;
+				source += ")";
+				break;
+			case ",":
+				source += inGroup ? "|" : "\\,";
+				break;
+			case "*": {
+				const before = glob[index - 1];
+				let stars = 1;
+				while (glob[index + 1] === "*") {
+					stars += 1;
+					index += 1;
+				}
+				const after = glob[index + 1];
+				if (stars > 1 && (before === "/" || before === void 0) && (after === "/" || after === void 0)) {
+					source += "((?:[^/]*(?:/|$))*)";
+					index += 1;
+				} else source += "([^/]*)";
+				break;
+			}
+			default: source += char;
+		}
+	}
+	return `^${source}(?:$|\\/)`;
+}
+/** What `ignored` ignores, as Watchpack decides it; nothing when unset. */
+function ignoredMatcher(ignored) {
+	const slashed = (path$6) => path$6.replace(/\\/g, "/");
+	if (ignored === void 0 || ignored === null) return () => false;
+	if (isWatchIgnoreMatcher(ignored)) return (path$7) => Boolean(ignored(path$7));
+	if (ignored instanceof RegExp) return (path$8) => ignored.test(slashed(path$8));
+	const sources = (isWatchIgnoreString(ignored) ? [ignored] : ignored).map((entry) => entry instanceof RegExp ? entry.source : entry.length > 0 ? globSource(entry) : null).filter((source) => source !== null);
+	if (sources.length === 0) return () => false;
+	const pattern = new RegExp(sources.join("|"));
+	return (path$9) => pattern.test(slashed(path$9));
+}
+/** Windows paths compare without case, as `path.win32.relative` does. */
+const comparable = process.platform === "win32" ? (path$10) => path$10.toLowerCase() : (path$11) => path$11;
+/** Whether a path is one of `directories` or lies under one where a kit's
+*  sources can live: never in the kit's own `node_modules` or another path
+*  ingestion excludes, which stay as the host decides. A prefix test:
+*  webpack's watcher asks for every path it watches. */
+function withinDirectories(directories) {
+	const prefixes = directories.map((dir) => comparable(dir.endsWith(path.sep) ? dir : dir + path.sep)).sort((a, b) => b.length - a.length);
+	return (path$5) => {
+		const key = comparable(path$5) + path.sep;
+		const prefix = prefixes.find((candidate) => key.startsWith(candidate));
+		return prefix !== void 0 && !(0, _animus_ui_extract_pipeline.isExcludedPackageRelativePath)(key.slice(prefix.length));
+	};
+}
+//#endregion
+//#region src/plugin.ts
 const UNSUPPORTED_WEBPACK_MESSAGE = "[animus-extract] Unsupported webpack: NormalModule.getCompilationHooks(compilation).needBuild is required for dev transform coherence and this webpack does not expose it. Use a Next.js version whose webpack exposes this hook.";
 const PLUGIN_NAME = "AnimusWebpackPlugin";
 var AnimusWebpackPlugin = class {
@@ -48,6 +135,16 @@ var AnimusWebpackPlugin = class {
 	/** This turn's rejected analysis. A rejection must fail the compilation,
 	*  never `watchRun`: webpack stops watching after a failed `watchRun`. */
 	watchFailure = null;
+	/** What the Session's watch plan last registered: `watchIgnored` never
+	*  ignores it. */
+	registered = {
+		files: /* @__PURE__ */ new Set(),
+		directories: () => false
+	};
+	/** Other files the watcher must see, by the plugins that read them. */
+	alsoWatched = [];
+	/** The webpack config Next hands its watcher, when withAnimus made it. */
+	watchedConfig;
 	/** `development` is `next dev`: an error-level diagnostic reports and the
 	*  compilation keeps publishing, whatever the emission mode. */
 	constructor(options, { development = false, build } = {}) {
@@ -55,6 +152,7 @@ var AnimusWebpackPlugin = class {
 		(0, _animus_ui_extract_pipeline.assertSupportedEngine)(options.engine);
 		this.session = new _animus_ui_extract_session.ExtractionSession(options, { build });
 		this.session.development = development;
+		this.session.writesFontPreloadsModule = true;
 		this.session.delivery = {
 			...this.session.delivery,
 			systemPropsModuleId: _animus_ui_extract_session.TURBOPACK_SYSTEM_PROPS_ID
@@ -67,19 +165,39 @@ var AnimusWebpackPlugin = class {
 		if (!Array.isArray(loaders)) return false;
 		return loaders.some((entry) => entry?.loader !== void 0 && this.animusLoaderPaths.has(entry.loader));
 	}
-	appendEpochWatchIgnore(compiler) {
-		const options = compiler.options;
-		if (!options) return;
-		const epochPath = (0, _animus_ui_extract_session.replacementEpochPath)((0, _animus_ui_extract_session.sessionArtifactDir)(this.session.rootDir ?? compiler.context, this.session.sessionId));
-		options.watchOptions ??= {};
-		const watchOptions = options.watchOptions;
-		const ignored = watchOptions.ignored;
-		if (ignored === void 0 || ignored === null) watchOptions.ignored = [epochPath];
-		else if (Array.isArray(ignored)) {
-			if (!ignored.includes(epochPath)) ignored.push(epochPath);
-		} else if (isWatchIgnoreString(ignored)) watchOptions.ignored = [ignored, epochPath];
-		else if (ignored instanceof RegExp) watchOptions.ignored = (path$1) => path$1 === epochPath || ignored.test(path$1);
-		else if (isWatchIgnoreMatcher(ignored)) watchOptions.ignored = (path$2) => path$2 === epochPath || Boolean(ignored(path$2));
+	/** The webpack config whose watch options the host's watcher reads,
+	*  rewritten when the plugin is applied. */
+	watchConfig(config) {
+		this.watchedConfig = config;
+	}
+	/** Makes `watchIgnored` watch the paths `watches` names too: one matcher
+	*  owns the host's watch options. */
+	watchAlso(watches) {
+		this.alsoWatched.push(watches);
+	}
+	/**
+	* `watchOptions.ignored` for the host's own `ignored`: this session's epoch
+	* file stays ignored, and every file and directory the Session's watch plan
+	* registers is watched, whatever the host ignores. Next ignores every
+	* `node_modules` path, where an installed source kit and its system live.
+	*/
+	watchIgnored(ignored, context) {
+		const hostIgnores = ignoredMatcher(ignored);
+		let epochRoot;
+		let epochPath;
+		const epoch = () => {
+			const root = this.session.rootDir ?? context;
+			if (root !== epochRoot) {
+				epochRoot = root;
+				epochPath = root === void 0 ? void 0 : (0, _animus_ui_extract_session.replacementEpochPath)((0, _animus_ui_extract_session.sessionArtifactDir)(root, this.session.sessionId));
+			}
+			return epochPath;
+		};
+		return (path$2) => {
+			if (path$2 === epoch()) return true;
+			if (this.registered.files.has(path$2) || this.registered.directories(path$2)) return false;
+			return hostIgnores(path$2) && !this.alsoWatched.some((watches) => watches(path$2));
+		};
 	}
 	/** Webpack's export conditions select the system's kit files as they
 	*  select the bundle's; `...`, webpack's own defaults, names none. Its
@@ -127,7 +245,15 @@ var AnimusWebpackPlugin = class {
 		if (compiler.options?.name === "edge-server") return;
 		const NormalModule = compiler.webpack?.NormalModule;
 		if (NormalModule?.getCompilationHooks === void 0) throw new Error(UNSUPPORTED_WEBPACK_MESSAGE);
-		this.appendEpochWatchIgnore(compiler);
+		const options = compiler.options;
+		if (options) {
+			options.watchOptions ??= {};
+			options.watchOptions.ignored = this.watchIgnored(options.watchOptions.ignored, compiler.context);
+		}
+		if (this.watchedConfig) this.watchedConfig.watchOptions = {
+			...this.watchedConfig.watchOptions,
+			ignored: this.watchIgnored(this.watchedConfig.watchOptions?.ignored, compiler.context)
+		};
 		compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
 			const epochMoved = this.epochMovedForNextCompilation;
 			this.epochMovedForNextCompilation = false;
@@ -145,6 +271,10 @@ var AnimusWebpackPlugin = class {
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
 			const registerSystemDependencies = () => {
 				const plan = this.session.watchPlan();
+				this.registered = {
+					files: /* @__PURE__ */ new Set([...plan.files, ...plan.missing]),
+					directories: withinDirectories(plan.directories)
+				};
 				for (const path$3 of plan.files) if ((0, fs.existsSync)(path$3)) compilation.fileDependencies.add(path$3);
 				else compilation.missingDependencies.add(path$3);
 				for (const path$4 of plan.missing) compilation.missingDependencies.add(path$4);
@@ -174,13 +304,13 @@ var AnimusWebpackPlugin = class {
 			this.extractAliases(_compiler);
 			this.extractConditions(_compiler);
 			if (await this.rejoin()) {
-				this.session.agreeWithSystemAuthority();
+				await this.session.agreeWithSystemAuthority();
 				return;
 			}
 			const existing = (0, _animus_ui_extract_session.getAnalysisStartedPromise)(this.session.key);
 			if (existing) {
 				await existing;
-				this.session.agreeWithSystemAuthority();
+				await this.session.agreeWithSystemAuthority();
 				return;
 			}
 			const promise = this.session.runFullPipeline();
@@ -212,7 +342,7 @@ var AnimusWebpackPlugin = class {
 	}
 	async analyzeWatchTurn(compiler) {
 		if (!this.initialized && await this.rejoin()) {
-			this.session.agreeWithSystemAuthority();
+			await this.session.agreeWithSystemAuthority();
 			this.initialized = true;
 			this.lastBuiltEpoch = (0, _animus_ui_extract_session.getReplacementEpoch)(this.session.key);
 			this.epochMovedForNextCompilation = true;
@@ -230,7 +360,7 @@ var AnimusWebpackPlugin = class {
 				if ((0, _animus_ui_extract_session.getAnalysisStartedPromise)(this.session.key) === startup) (0, _animus_ui_extract_session.resetAnalysisStartedPromise)(this.session.key);
 				throw err;
 			}
-			this.session.agreeWithSystemAuthority();
+			await this.session.agreeWithSystemAuthority();
 			this.initialized = true;
 			this.lastBuiltEpoch = (0, _animus_ui_extract_session.getReplacementEpoch)(this.session.key);
 			this.epochMovedForNextCompilation = this.watchFailure !== null;
@@ -240,7 +370,7 @@ var AnimusWebpackPlugin = class {
 			modifiedFiles: compiler.modifiedFiles,
 			removedFiles: compiler.removedFiles
 		});
-		this.session.agreeWithSystemAuthority();
+		await this.session.agreeWithSystemAuthority();
 		const epoch = (0, _animus_ui_extract_session.getReplacementEpoch)(this.session.key);
 		this.epochMovedForNextCompilation = this.lastBuiltEpoch !== null && epoch !== null && epoch !== this.lastBuiltEpoch;
 		if (epoch !== null) this.lastBuiltEpoch = epoch;
@@ -296,6 +426,29 @@ var AnimusWebpackPlugin = class {
 	}
 };
 //#endregion
+//#region src/quarantine.ts
+/**
+* layergate's webpack plugin for the `quarantine` option, loaded on first
+* use: layergate is an optional peer. Only the client compiler builds
+* stylesheets, so only it gets one.
+*/
+/** The error Turbopack meets: it runs no loader on a stylesheet's
+*  imports, so layergate cannot load a graph there. */
+const QUARANTINE_TURBOPACK_MESSAGE = "[animus-extract] the `quarantine` option needs webpack: Turbopack runs no loader on the stylesheets a stylesheet imports, so it cannot keep them in `anm-vendor`. Run `next build --webpack` and `next dev --webpack`, or remove `quarantine` [layergate.turbopack]";
+function quarantinePlugin(options, order, declaredBy) {
+	let layergate;
+	try {
+		layergate = (0, module$1.createRequire)(require("url").pathToFileURL(__filename).href)("@animus-ui/layergate/webpack");
+	} catch (cause) {
+		throw (0, _animus_ui_extract_pipeline.layergateMissing)("@animus-ui/next-plugin", cause);
+	}
+	return new layergate.LayergatePlugin({
+		...(0, _animus_ui_extract_pipeline.layergateOptions)(options, order),
+		declaredBy,
+		watchIgnored: false
+	});
+}
+//#endregion
 //#region src/with-animus.ts
 const __filename$1 = (0, url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
 const __dirname$1 = (0, path.dirname)(__filename$1);
@@ -313,7 +466,8 @@ function withAnimus(options) {
 		"turbopack",
 		"unstable_turbopack",
 		"loaderPath",
-		"phase"
+		"phase",
+		"quarantine"
 	], [], {
 		onUnknownKey: "warn",
 		warn: (message) => console.warn(`[animus-extract] ${message}`)
@@ -325,8 +479,10 @@ function withAnimus(options) {
 	const build = (0, _animus_ui_extract_session.createBuildId)();
 	const appRoot = options.root === void 0 ? process.cwd() : (0, path.resolve)(options.root);
 	return (authoredConfig) => {
-		const nextConfig = withSourceKits(authoredConfig, appRoot);
-		if (require_turbopack_config.resolveTurbopackMode(options)) {
+		const nextConfig = withTranspiled(authoredConfig, transpiledPackages(appRoot));
+		const turbopack = require_turbopack_config.resolveTurbopackMode(options);
+		if (options.quarantine && (turbopack || "TURBOPACK" in process.env)) throw new _animus_ui_extract_pipeline.AnimusConfigError(QUARANTINE_TURBOPACK_MESSAGE);
+		if (turbopack) {
 			warnTurbopackCwdRoot(options, appRoot);
 			return turbopackConfig(nextConfig, options, build, appRoot);
 		}
@@ -338,8 +494,11 @@ function withAnimus(options) {
 				if (context.dir?.length && !sameDirectory(context.dir, appRoot)) throw new _animus_ui_extract_pipeline.AnimusConfigError(`[animus-extract] Next builds ${context.dir}, but Animus read the app's source kits from ${appRoot}. Run next from the app directory, or pass withAnimus({ root }) naming it.`);
 				const rootDir = appRoot;
 				const { mode } = (0, _animus_ui_extract_pipeline.resolveMode)(options.mode, () => context.dev === true ? "development" : "production");
+				const vendorOrder = options.quarantine ? (0, _animus_ui_extract_pipeline.withVendorLayer)(options.layers) : void 0;
+				const layers = vendorOrder ?? options.layers;
 				const plugin = new AnimusWebpackPlugin({
 					...options,
+					layers,
 					mode
 				}, {
 					development: context.dev === true,
@@ -352,13 +511,15 @@ function withAnimus(options) {
 				const stubCssPath = (0, _animus_ui_extract_session.stylesPath)(sessionDir);
 				if (!(0, fs.existsSync)(stubCssPath)) {
 					const { declaration } = (0, _animus_ui_extract_pipeline.assembleStylesheet)({
-						layers: options.layers,
+						layers,
 						variableCss: "",
 						globalCss: "",
 						split: true
 					});
 					(0, fs.writeFileSync)(stubCssPath, declaration);
 				}
+				const sessionFontPreloadsPath = (0, _animus_ui_extract_session.fontPreloadsPath)(sessionDir);
+				if (!(0, fs.existsSync)(sessionFontPreloadsPath)) (0, fs.writeFileSync)(sessionFontPreloadsPath, (0, _animus_ui_extract_pipeline.fontPreloadsModule)([]));
 				if (!warnedGitignore) {
 					warnedGitignore = true;
 					try {
@@ -371,6 +532,12 @@ function withAnimus(options) {
 				const isExternalPackageFile = (filePath) => plugin.getExternalPackageDirs().some((dir) => (0, _animus_ui_extract_pipeline.isPathWithinRoot)(dir, filePath));
 				config.plugins = config.plugins || [];
 				config.plugins.push(plugin);
+				plugin.watchConfig(config);
+				if (options.quarantine && vendorOrder && context.isServer !== true) {
+					const gate = quarantinePlugin(options.quarantine, vendorOrder, stubCssPath);
+					config.plugins.push(gate);
+					plugin.watchAlso((path$1) => gate.watches(path$1));
+				}
 				const DefinePlugin = context.webpack?.DefinePlugin;
 				if (DefinePlugin) config.plugins.push(new DefinePlugin({ __ANIMUS_DEV__: JSON.stringify(mode === "development") }));
 				config.resolve = config.resolve || {};
@@ -382,6 +549,7 @@ function withAnimus(options) {
 					compiler.hooks.normalModuleFactory.tap("AnimusVirtualResolve", (nmf) => {
 						nmf.hooks.beforeResolve.tap("AnimusVirtualResolve", (resolveData) => {
 							if (resolveData.request === "virtual:animus/system-props") resolveData.request = sessionSystemPropsPath;
+							if (resolveData.request === _animus_ui_extract_session.FONT_PRELOADS_MODULE_ID) resolveData.request = sessionFontPreloadsPath;
 							if (resolveData.request === "virtual:animus/styles.css" || resolveData.request === _animus_ui_extract_session.ANIMUS_CSS_MODULE_ID) resolveData.request = (0, _animus_ui_extract_session.stylesPath)(sessionDir);
 							const srcEntry = plugin.getExternalSourceEntries().get(resolveData.request);
 							if (srcEntry) {
@@ -438,11 +606,7 @@ function bindTurbopackWatchDeathReport(outcome, rootDir) {
 		console.error(`[animus-extract] dev watcher for ${rootDir} died — source edits are no longer extracted; restart the dev server`);
 	};
 }
-/** The config with the source kits the app depends on added to
-*  `transpilePackages`. The kit redirect points both bundles at a kit's
-*  source, but Next's server keeps an installed package external, and so
-*  loads its runtime entry, unless the package is transpiled; transpiling
-*  also compiles its TypeScript source. */
+const NEXT_PLUGIN_PACKAGE = "@animus-ui/next-plugin";
 let warnedTurbopackCwd = false;
 /** Turbopack's loaders get no app dir either, so a cwd that is not the app
 *  cannot be detected later: warn at startup when the cwd holds no Next
@@ -459,15 +623,25 @@ function warnTurbopackCwdRoot(options, appRoot) {
 	warnedTurbopackCwd = true;
 	console.warn(`[animus-extract] the current directory (${appRoot}) holds no next.config: under Turbopack, Animus reads the app from the current directory. Run next from the app directory, or pass withAnimus({ root }) naming it.`);
 }
-function withSourceKits(nextConfig, rootDir) {
+/** The config with `packages` added to `transpilePackages`. Next's server
+*  keeps an installed package external, and so loads its runtime entry,
+*  unless the package is transpiled. */
+function withTranspiled(nextConfig, packages) {
 	const declared = nextConfig.transpilePackages ?? [];
-	const kits = (0, _animus_ui_extract_pipeline.sourceKitDependencies)(rootDir, (0, _animus_ui_extract_session.requireEngine)()).map((kit) => kit.name).filter((name) => !declared.includes(name));
-	if (kits.length === 0) return nextConfig;
+	const added = packages.filter((name) => !declared.includes(name));
+	if (added.length === 0) return nextConfig;
 	return {
 		...nextConfig,
-		transpilePackages: [...declared, ...kits]
+		transpilePackages: [...declared, ...added]
 	};
 }
+/** The packages Next must transpile: the source kits the app depends on,
+*  since the kit redirect points both bundles at a kit's TypeScript source,
+*  and this package, whose font-preloads entry imports the session module
+*  only the bundle's alias resolves. */
+function transpiledPackages(rootDir) {
+	return [...(0, _animus_ui_extract_pipeline.sourceKitDependencies)(rootDir, (0, _animus_ui_extract_session.requireEngine)()).map((kit) => kit.name), NEXT_PLUGIN_PACKAGE];
+}
 function turbopackConfig(nextConfig, options, build, appRoot) {
 	const resolveExtensions = nextConfig.turbopack?.resolveExtensions ?? nextConfig.experimental?.turbo?.resolveExtensions;
 	const outputExclude = nextConfig.distDir ? (0, _animus_ui_extract_pipeline.outputExclusion)(appRoot, (0, path.resolve)(appRoot, nextConfig.distDir)) : null;
@@ -525,6 +699,7 @@ async function analyzeForTurbopack(options, phase, rootDir, resolveExtensions, o
 		unbundledComputedImports: true,
 		build: `${build}-${phase}`
 	});
+	session.writesFontPreloadsModule = true;
 	const owner = turbopackOwner(build);
 	owner.session?.close();
 	owner.watcher?.close();