@animus-ui/vite-plugin 0.1.32 → 0.1.36

package/README.md

@@ -60,7 +60,8 @@ export default defineConfig({
 ```
 
 The plugin is **delivery-only**: it injects `artifact.code` verbatim as an inline
-`<script data-animus-bootstrap>` at the start of `<head>`, ahead of every
+`<script data-animus-bootstrap>` in `<head>`, after the charset and viewport
+metas (so the charset stays within the first 1024 bytes) and ahead of every
 stylesheet reference, and interprets no appearance semantics. Omit the option and
 the built HTML is byte-for-byte what it was before.
 
@@ -96,6 +97,75 @@ supplies either `cspHash` or a per-request nonce. Worked App Router and Pages
 Router examples live in the
 [`@animus-ui/next-plugin` README](https://github.com/codecaaron/animus/tree/main/packages/next-plugin#appearance-bootstrap-no-fouc-color-mode).
 
+## Font preloads
+
+A font face declared with `preload: true` gets a
+`<link rel="preload" as="font" crossorigin data-animus-preload>` in `<head>`,
+after the charset and viewport metas and ahead of every stylesheet link. Its
+href is the URL the stylesheet's `url()` loads: the hashed asset in a build,
+the dev server's URL in development. A root-relative or absolute URL that
+`index.html` already preloads gets no second preload. A build warns, naming
+the HTML page, when the finished page preloads the same file through another
+tag: one written in the page for an `asset()` file, or one a plugin adds from
+an `index.html` hook that runs after Animus's.
+
+`fontPreloads` selects the faces that preload in place of their `preload`
+flags, for an app that renders only some of a system's faces. A family name
+selects every face of the family; `{ family, weight?, style? }` selects the
+faces whose declared weight contains `weight` (a variable face's range
+`'100 900'` contains 600) and whose style is `style` (`'normal'` when
+omitted):
+
+```ts
+animusExtract({
+  system: './src/ds.ts',
+  fontPreloads: [
+    { family: 'Apercu', weight: 400 },
+    { family: 'Apercu', weight: 'bold' },
+    { family: 'Suisse', weight: 700 },
+  ],
+});
+```
+
+`[]` preloads none. An entry no face matches reports
+`animus.style.font-preload-unmatched`; a malformed one, such as a weight
+range, reports `animus.style.font-preload-invalid`.
+
+A preload competes with the critical CSS and JavaScript for first paint, so
+preload WOFF2 and only the faces the first screen needs: a large TrueType
+file can delay first paint by seconds on a slow link. A preloaded file that
+is not WOFF2 or WOFF, or an `asset()` file over 150 KB, reports
+`animus.style.font-face-preload-costly`.
+
+## 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:
+
+```sh
+bun add -D @animus-ui/layergate
+```
+
+```ts
+animusExtract({
+  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
+  },
+});
+```
+
+`sheets` arrive at the head of Animus's own stylesheet, wherever it is
+imported, so no extra import is needed. Their fonts and images keep
+resolving, files outside the project root included.
+`!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.
+
 ## MDX
 
 Animus reads each `.mdx` file as the JSX it renders: its imports, exports,

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE3C,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,cAAc,GACrB,IAAI,CA4EN"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE3C,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,cAAc,GACrB,IAAI,CA+EN"}

package/dist/context.d.ts

@@ -29,9 +29,11 @@ export declare class PluginContext {
     pathAliasesJson: string | null;
     /** Vite's export conditions, so the loader reads the files Vite serves. */
     resolveConditions: string[];
+    private viteExtensionPolicy;
     /** Vite's resolved extension order; the built-in policy until
      *  `configResolved`. */
-    extensionPolicy: HostExtensionPolicy;
+    get extensionPolicy(): HostExtensionPolicy;
+    set extensionPolicy(policy: HostExtensionPolicy);
     /** Vite's asset classification, captured at `configResolved`. */
     assetClassification: HostAssetClassification;
     /** How Vite's build expands computed loads, captured at
@@ -85,6 +87,12 @@ export declare class PluginContext {
     /** Coalesces a burst of invalidations into one full reload. */
     private readonly reloadWindow;
     base: string;
+    /** Vite's root and `server.origin`, which a dev asset URL is served
+     *  under. */
+    viteRoot: string;
+    serverOrigin: string;
+    /** Vite's resolved public directory; empty when it serves none. */
+    publicDir: string;
     assetUrlBySpecifier: Map<string, string>;
     /** Where dev asset() copies live, immutable and content-named; null in a
      *  build, or when the dev server does not serve the directory, which
@@ -162,7 +170,16 @@ export declare class PluginContext {
     /** A build-strictness check that failed: a build throws `message`, and
      *  development reports it at error level and takes the non-strict path. */
     strictFailure(message: string, cause?: unknown): void;
-    devFsUrl(absPath: string): string;
+    /** The URL Vite's dev server serves `absPath` at, the form its dev CSS
+     *  pass writes (`fileToDevUrl`): root-relative inside its root, `/@fs/`
+     *  outside, under `server.origin` and the base. Every consumer, the
+     *  stylesheet that pass rewrites, component CSS it does not, and a font
+     *  preload, then names one URL, and the browser fetches the file once. */
+    devServedUrl(absPath: string): string;
+    /** A root-relative URL a face names as written, as Vite's dev CSS pass
+     *  writes it: under `server.origin` and the base where it names a public
+     *  file or a file under the root, else unchanged. */
+    devRootRelativeUrl(href: string): string;
     /** A dev asset() URL: an immutable content-named copy of `absPath`, so an
      *  edit gets a new URL, or the live file where copies are not served. */
     devAssetUrl(specifier: string, absPath: string): string;

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/index-html.d.ts

@@ -1,8 +1,24 @@
 import type { PluginContext } from './context';
 import type { HtmlTagDescriptor } from 'vite';
 /**
- * Vite serializes one `head-prepend` bucket in array order, so the bootstrap
- * script precedes the layer declaration and every stylesheet reference.
+ * The hrefs a finished document preloads both through Animus's tag and
+ * through another, which the page wrote or a hook running after Animus's
+ * added: the browser may then fetch the file twice. Each href is compared
+ * as the browser resolves it against `pageUrl`, the URL the page is served
+ * at, and reported as Animus wrote it.
  */
-export declare function buildIndexHtmlTags(ctx: PluginContext): HtmlTagDescriptor[];
+export declare function duplicatedFontPreloads(html: string, pageUrl: string): string[];
+/**
+ * The hook's result: the tags written after the charset and viewport metas,
+ * each on its own line indented as the element it follows, so the charset
+ * stays in the first 1024 bytes however long the tags are; as `head-prepend`
+ * tags for a document without a `<head>`.
+ */
+export declare function injectHeadTags(html: string, tags: HtmlTagDescriptor[]): string | HtmlTagDescriptor[];
+/**
+ * Animus's head tags in document order: the bootstrap script, so it runs
+ * before first paint and ahead of every stylesheet, the layer declaration,
+ * the font preloads, then the development bridge.
+ */
+export declare function buildIndexHtmlTags(ctx: PluginContext, html?: string): HtmlTagDescriptor[];
 //# sourceMappingURL=index-html.d.ts.map

package/dist/index-html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-html.d.ts","sourceRoot":"","sources":["../src/index-html.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,iBAAiB,EAAE,CAqC1E"}
+{"version":3,"file":"index-html.d.ts","sourceRoot":"","sources":["../src/index-html.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AA0C9C;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,CAeV;AAsED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,iBAAiB,EAAE,GACxB,MAAM,GAAG,iBAAiB,EAAE,CAU9B;AAkCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,aAAa,EAClB,IAAI,SAAK,GACR,iBAAiB,EAAE,CAuCrB"}

package/dist/index.cjs

@@ -4,10 +4,10 @@ Object.defineProperties(exports, {
 });
 let _animus_ui_extract_pipeline = require("@animus-ui/extract/pipeline");
 let path = require("path");
+let vite = require("vite");
 let fs = require("fs");
 let _animus_ui_extract_session = require("@animus-ui/extract/session");
 let child_process = require("child_process");
-let vite = require("vite");
 let crypto = require("crypto");
 //#region src/asset-copy-dirs.ts
 /**
@@ -192,7 +192,7 @@ function applyResolvedConfig(ctx, config) {
 		const copyDir = (0, path.resolve)(config.cacheDir, "animus-assets", processCopyDir());
 		const served = (0, vite.isFileLoadingAllowed)(config, (0, path.join)(copyDir, "asset"));
 		ctx.assetCopyDir = served ? copyDir : null;
-		ctx.servesFile = (path$9) => (0, vite.isFileLoadingAllowed)(config, path$9);
+		ctx.servesFile = (path$11) => (0, vite.isFileLoadingAllowed)(config, path$11);
 		if (!served) ctx.warn(`[animus-extract] asset() copies in ${copyDir} are not served under server.fs; serving the live files instead, so an edited asset keeps its URL`);
 	}
 	ctx.outputExcludes = (0, _animus_ui_extract_pipeline.outputExclusions)(config.root, (0, _animus_ui_extract_pipeline.viteOutputTargets)(config));
@@ -204,6 +204,9 @@ function applyResolvedConfig(ctx, config) {
 	ctx.log(`extension order: ${ctx.extensionPolicy.resolverVersion}`);
 	ctx.logger = config.logger;
 	ctx.base = config.base ?? "/";
+	ctx.viteRoot = config.root;
+	ctx.serverOrigin = config.server.origin ?? "";
+	ctx.publicDir = config.publicDir;
 	ctx.lcssTargets = (0, _animus_ui_extract_pipeline.resolveLightningTargets)(ctx.options.targets, ctx.rootDir);
 	ctx.log(`Lightning CSS targets resolved (${Object.keys(ctx.lcssTargets).length} browsers)`);
 	const pairs = [];
@@ -348,9 +351,15 @@ var PluginContext = class {
 	pathAliasesJson = null;
 	/** Vite's export conditions, so the loader reads the files Vite serves. */
 	resolveConditions = [];
+	viteExtensionPolicy;
 	/** Vite's resolved extension order; the built-in policy until
 	*  `configResolved`. */
-	extensionPolicy = _animus_ui_extract_pipeline.BUILT_IN_EXTENSION_POLICY;
+	get extensionPolicy() {
+		return this.viteExtensionPolicy ?? (0, _animus_ui_extract_pipeline.builtInExtensionPolicy)();
+	}
+	set extensionPolicy(policy) {
+		this.viteExtensionPolicy = policy;
+	}
 	/** Vite's asset classification, captured at `configResolved`. */
 	assetClassification = (0, _animus_ui_extract_pipeline.builtInAssetClassification)("noHost");
 	/** How Vite's build expands computed loads, captured at
@@ -436,6 +445,12 @@ var PluginContext = class {
 		this.devServer?.hot?.send({ type: "full-reload" });
 	});
 	base = "/";
+	/** Vite's root and `server.origin`, which a dev asset URL is served
+	*  under. */
+	viteRoot = "";
+	serverOrigin = "";
+	/** Vite's resolved public directory; empty when it serves none. */
+	publicDir = "";
 	assetUrlBySpecifier = /* @__PURE__ */ new Map();
 	/** Where dev asset() copies live, immutable and content-named; null in a
 	*  build, or when the dev server does not serve the directory, which
@@ -520,6 +535,7 @@ var PluginContext = class {
 			engine: options.engine,
 			runtimeImport: options.runtimeImport,
 			closedDynamicImports: options.closedDynamicImports,
+			fontPreloads: options.fontPreloads,
 			mode: this.emissionProd ? "production" : "development"
 		}, {
 			build: this.build,
@@ -555,7 +571,7 @@ var PluginContext = class {
 	*  between sees one generation. */
 	observeOutcome(session, outcome) {
 		let systemPropsChanged = false;
-		if (outcome.kind === "held") for (const [path$6, hash] of outcome.abortedOriginals) this.abortedParseHashes.set(path$6, hash);
+		if (outcome.kind === "held") for (const [path$7, hash] of outcome.abortedOriginals) this.abortedParseHashes.set(path$7, hash);
 		else {
 			this.abortedParseHashes.clear();
 			const before = this.systemPropsModule;
@@ -646,13 +662,36 @@ var PluginContext = class {
 		if (!report) throw new Error(message, cause === void 0 ? void 0 : { cause });
 		report(message);
 	}
-	devFsUrl(absPath) {
-		return `${this.base.endsWith("/") ? this.base.slice(0, -1) : this.base}/@fs${absPath}`;
+	/** The URL Vite's dev server serves `absPath` at, the form its dev CSS
+	*  pass writes (`fileToDevUrl`): root-relative inside its root, `/@fs/`
+	*  outside, under `server.origin` and the base. Every consumer, the
+	*  stylesheet that pass rewrites, component CSS it does not, and a font
+	*  preload, then names one URL, and the browser fetches the file once. */
+	devServedUrl(absPath) {
+		const base = this.base.endsWith("/") ? this.base.slice(0, -1) : this.base;
+		const root = this.viteRoot.endsWith("/") ? this.viteRoot : `${this.viteRoot}/`;
+		const path$8 = this.viteRoot !== "" && absPath.startsWith(root) ? `/${absPath.slice(root.length)}` : `/@fs${absPath}`;
+		return `${this.serverOrigin}${base}${path$8}`;
+	}
+	/** A root-relative URL a face names as written, as Vite's dev CSS pass
+	*  writes it: under `server.origin` and the base where it names a public
+	*  file or a file under the root, else unchanged. */
+	devRootRelativeUrl(href) {
+		if (!href.startsWith("/") || href.startsWith("//")) return href;
+		let path$6;
+		try {
+			path$6 = decodeURI(href.split(/[?#]/)[0]);
+		} catch {
+			return href;
+		}
+		if (![this.publicDir, this.viteRoot].some((dir) => dir !== "" && (0, fs.existsSync)((0, path.join)(dir, path$6)))) return href;
+		const base = this.base.endsWith("/") ? this.base.slice(0, -1) : this.base;
+		return `${this.serverOrigin}${base}${href}`;
 	}
 	/** A dev asset() URL: an immutable content-named copy of `absPath`, so an
 	*  edit gets a new URL, or the live file where copies are not served. */
 	devAssetUrl(specifier, absPath) {
-		if (this.assetCopyDir === null) return this.devFsUrl(absPath);
+		if (this.assetCopyDir === null) return this.devServedUrl(absPath);
 		const { fileName } = (0, _animus_ui_extract_pipeline.writeAssetCopy)(absPath, this.assetCopyDir);
 		const copyPath = (0, path.join)(this.assetCopyDir, fileName);
 		if (!this.servesFile(copyPath)) {
@@ -660,12 +699,12 @@ var PluginContext = class {
 				this.unservedAssetCopies.add(specifier);
 				this.warn(`[animus-extract] the copy of asset() ${specifier} is not served under server.fs; serving the live file instead, so an edit keeps its URL`);
 			}
-			return this.devFsUrl(absPath);
+			return this.devServedUrl(absPath);
 		}
 		if (this.assetSourceBySpecifier.get(specifier) !== absPath) this.devServer?.watcher?.add(absPath);
 		this.assetSourceBySpecifier.set(specifier, absPath);
 		this.retainAssetCopy(absPath, fileName);
-		return this.devFsUrl(copyPath);
+		return this.devServedUrl(copyPath);
 	}
 	/** Keeps each source's current copy and the one before it; an asset
 	*  edit reloads the page, so an older URL is never fetched again. A copy
@@ -773,8 +812,8 @@ var PluginContext = class {
 			plan.missing,
 			directories
 		]) {
-			const added = paths.filter((path$7) => !registered.has(path$7));
-			for (const path$8 of added) registered.add(path$8);
+			const added = paths.filter((path$9) => !registered.has(path$9));
+			for (const path$10 of added) registered.add(path$10);
 			if (added.length > 0) watcher.add(added);
 		}
 	}
@@ -1283,11 +1322,145 @@ function invalidateStaleModules(ctx, environment, modules, analyzed) {
 }
 //#endregion
 //#region src/index-html.ts
+const LINK_TAG_RE = /<link\b[^>]*>/gi;
+/** Marks the preloads Animus writes, so another preload of the same file
+*  can be told from Animus's own. */
+const ANIMUS_PRELOAD_MARKER = "data-animus-preload";
+const MARKER_RE = /\sdata-animus-preload(?=[\s=/>])/i;
+const REL_RE = /\srel\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+const HREF_RE = /\shref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+function attribute(tag, re) {
+	const match = re.exec(tag);
+	return match ? match[1] ?? match[2] ?? match[3] : void 0;
+}
+/** Each `<link rel="preload">` in `html`, with its href. */
+function* preloadLinks(html) {
+	for (const [tag] of html.matchAll(LINK_TAG_RE)) {
+		const rel = attribute(tag, REL_RE)?.toLowerCase().split(/\s+/) ?? [];
+		const href = attribute(tag, HREF_RE);
+		if (rel.includes("preload") && href !== void 0) yield [tag, href];
+	}
+}
+const ENTITY_RE = /&(?:#x([0-9a-f]+)|#(\d+)|(amp|lt|gt|quot|apos));/gi;
+const NAMED_ENTITIES = /* @__PURE__ */ new Map([
+	["amp", "&"],
+	["lt", "<"],
+	["gt", ">"],
+	["quot", "\""],
+	["apos", "'"]
+]);
+/** An attribute value as the browser reads it: character references decoded. */
+function attributeText(value) {
+	return value.replace(ENTITY_RE, (_, hex, decimal, named) => named === void 0 ? String.fromCodePoint(Number.parseInt(hex ?? decimal, hex ? 16 : 10)) : NAMED_ENTITIES.get(named.toLowerCase()));
+}
+/**
+* The hrefs a finished document preloads both through Animus's tag and
+* through another, which the page wrote or a hook running after Animus's
+* added: the browser may then fetch the file twice. Each href is compared
+* as the browser resolves it against `pageUrl`, the URL the page is served
+* at, and reported as Animus wrote it.
+*/
+function duplicatedFontPreloads(html, pageUrl) {
+	const resolved = (href) => {
+		try {
+			return new URL(attributeText(href), pageUrl).href;
+		} catch {
+			return href;
+		}
+	};
+	const ours = /* @__PURE__ */ new Map();
+	const others = /* @__PURE__ */ new Set();
+	for (const [tag, href] of preloadLinks(html)) if (MARKER_RE.test(tag)) ours.set(resolved(href), href);
+	else others.add(resolved(href));
+	return [...ours].filter(([url]) => others.has(url)).map(([, href]) => href);
+}
+/** The hrefs the document already preloads. */
+function preloadedHrefs(html) {
+	return new Set([...preloadLinks(html)].map(([, href]) => href));
+}
+/** The head elements Animus's tags go after (the charset and viewport
+*  metas), the stylesheets they go before, and what holds neither. */
+const HEAD_SCAN_RE = /<!--[\s\S]*?-->|<script\b[\s\S]*?<\/script\s*>|<\/head\s*>|<style\b|<(?:meta|link)\b[^>]*>/gi;
+/** Where Animus's head tags go: after the head's charset and viewport
+*  metas, so they cannot push the charset past the 1024 bytes a browser
+*  sniffs for it, and before its first stylesheet; -1 without a `<head>`. */
+function headTagOffset(html) {
+	const open = /<head\b[^>]*>/i.exec(html);
+	if (open === null) return -1;
+	const start = open.index + open[0].length;
+	let offset = start;
+	for (const match of html.slice(start).matchAll(HEAD_SCAN_RE)) {
+		const [element] = match;
+		const lower = element.toLowerCase();
+		if (lower.startsWith("</head") || lower.startsWith("<style")) break;
+		if (lower.startsWith("<link")) {
+			if ((attribute(element, REL_RE)?.toLowerCase().split(/\s+/))?.includes("stylesheet")) break;
+		} else if (lower.startsWith("<meta") && (/\scharset\s*=/i.test(element) || /\shttp-equiv\s*=\s*["']?content-type\b/i.test(element) || /\sname\s*=\s*["']?viewport\b/i.test(element))) offset = start + match.index + element.length;
+	}
+	return offset;
+}
+/** As `escape-html` escapes, which Vite applies to attribute values. */
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/** A tag as Vite serializes it, `children` as written, except that an
+*  undefined attribute is left out rather than written "undefined". */
+function serializeTag({ tag, attrs = {}, children }) {
+	const serialized = Object.entries(attrs).map(([key, value]) => {
+		if (value === true) return ` ${key}`;
+		if (value === false || value === void 0) return "";
+		return ` ${key}="${escapeHtml(value)}"`;
+	}).join("");
+	if (tag === "link" || tag === "meta" || tag === "base") return `<${tag}${serialized}>`;
+	return `<${tag}${serialized}>${Array.isArray(children) ? "" : children ?? ""}</${tag}>`;
+}
+/**
+* The hook's result: the tags written after the charset and viewport metas,
+* each on its own line indented as the element it follows, so the charset
+* stays in the first 1024 bytes however long the tags are; as `head-prepend`
+* tags for a document without a `<head>`.
+*/
+function injectHeadTags(html, tags) {
+	const offset = headTagOffset(html);
+	if (offset === -1) return tags;
+	if (tags.length === 0) return html;
+	const lineStart = html.lastIndexOf("\n", offset - 1) + 1;
+	const indent = /^[ \t]*/.exec(html.slice(lineStart))[0];
+	const inserted = tags.map((tag) => `\n${indent}${serializeTag(tag)}`).join("");
+	return html.slice(0, offset) + inserted + html.slice(offset);
+}
+/** The preloads for the faces that ask for one, by the URL the stylesheet's
+*  own `url()` gets, each marked as Animus's; one the document already
+*  preloads is left out. */
+function fontPreloadTags(ctx, html) {
+	const published = ctx.served?.fontPreloads ?? [];
+	if (published.length === 0) return [];
+	const existing = preloadedHrefs(html);
+	return (0, _animus_ui_extract_pipeline.substituteFontPreloads)(published, ctx.assetUrlBySpecifier).map((preload) => ctx.isProd ? preload : {
+		...preload,
+		href: ctx.devRootRelativeUrl(preload.href)
+	}).filter(({ href }) => !existing.has(href)).map(({ href, type }) => {
+		const attrs = {
+			rel: "preload",
+			href,
+			as: "font"
+		};
+		if (type !== void 0) attrs.type = type;
+		attrs.crossorigin = true;
+		attrs[ANIMUS_PRELOAD_MARKER] = true;
+		return {
+			tag: "link",
+			attrs,
+			injectTo: "head-prepend"
+		};
+	});
+}
 /**
-* Vite serializes one `head-prepend` bucket in array order, so the bootstrap
-* script precedes the layer declaration and every stylesheet reference.
+* Animus's head tags in document order: the bootstrap script, so it runs
+* before first paint and ahead of every stylesheet, the layer declaration,
+* the font preloads, then the development bridge.
 */
-function buildIndexHtmlTags(ctx) {
+function buildIndexHtmlTags(ctx, html = "") {
 	const tags = [];
 	const bootstrap = ctx.options.appearanceBootstrap;
 	if (bootstrap?.code) tags.push({
@@ -1302,6 +1475,7 @@ function buildIndexHtmlTags(ctx) {
 		children: ctx.layerDeclaration,
 		injectTo: "head-prepend"
 	});
+	tags.push(...fontPreloadTags(ctx, html));
 	if (!ctx.isProd) tags.push({
 		tag: "script",
 		attrs: {
@@ -1314,6 +1488,32 @@ function buildIndexHtmlTags(ctx) {
 	return tags;
 }
 //#endregion
+//#region src/quarantine-plugin.ts
+/**
+* layergate's Vite plugin for the `quarantine` option, loaded on first use:
+* layergate is an optional peer.
+*/
+function quarantinePlugin(options, layers) {
+	const order = (0, _animus_ui_extract_pipeline.withVendorLayer)(layers);
+	let plugin;
+	return {
+		order,
+		plugin: () => plugin ??= load(options, order)
+	};
+}
+async function load(options, order) {
+	let layergate;
+	try {
+		({layergate} = await import("@animus-ui/layergate/vite"));
+	} catch (cause) {
+		throw (0, _animus_ui_extract_pipeline.layergateMissing)("@animus-ui/vite-plugin", cause);
+	}
+	return layergate({
+		...(0, _animus_ui_extract_pipeline.layergateOptions)(options, order),
+		declaredBy: VIRTUAL_CSS_ID
+	});
+}
+//#endregion
 //#region src/virtual-modules.ts
 /**
 * Keyed on the whole option record: two instances sharing a key means the
@@ -1427,6 +1627,27 @@ if (import.meta.hot) {
 	return null;
 }
 //#endregion
+//#region src/watch-ignored.ts
+/** A path as a glob that matches only itself. Each special character
+*  goes in a bracket: the watcher turns every backslash in an ignored
+*  glob into a slash, so a backslash escape would split the path. */
+function literal(path) {
+	return path.replace(/\\/g, "/").replace(/[()[\]{}*?!+@|]/g, "[$&]");
+}
+/**
+* `server.watch.ignored` entries that watch installed kits. Vite always
+* ignores every `node_modules` path, where an installed kit lives, and
+* watches what a negated glob names. Each glob names a kit root and the
+* paths under it that ingestion would read: a segment holding an excluded
+* name, the kit's own `node_modules` among them, stays ignored, so the
+* watcher never walks into it. The segment test is a regex lookahead,
+* which picomatch keeps as written.
+*/
+function kitWatchNegations(roots) {
+	const excluded = _animus_ui_extract_pipeline.PACKAGE_SRC_EXCLUDES.map((name) => `*${literal(name)}`).join("|");
+	return roots.map((root) => `!${literal(root)}*(/(?!${excluded})*)`);
+}
+//#endregion
 //#region src/index.ts
 async function sourceKitConfig(rootDir, systemPath, engine) {
 	const kits = /* @__PURE__ */ new Map();
@@ -1438,45 +1659,73 @@ async function sourceKitConfig(rootDir, systemPath, engine) {
 			exclude: names,
 			include: [...kits.values()].flatMap((kit) => kit.dependencies.map((dependency) => `${kit.name} > ${dependency}`))
 		},
-		ssr: { noExternal: names }
+		ssr: { noExternal: names },
+		roots: [...kits.values()].map((kit) => kit.root)
 	};
 }
+/** The URL a build's root is served at, for resolving a page's hrefs: an
+*  absolute `base`, a root-relative one on a stand-in origin, or the root
+*  for a relative one, which every page resolves from its own location. */
+function servedBase(base) {
+	const origin = "https://animus.invalid/";
+	if (/^[a-z][a-z\d+.-]*:/i.test(base)) return new URL(base.replace(/\/?$/, "/"));
+	if (base.startsWith("/")) return new URL(base.replace(/\/?$/, "/"), origin);
+	return new URL(origin);
+}
 function animusExtract(options) {
 	(0, _animus_ui_extract_pipeline.assertSupportedEngine)(options.engine);
-	(0, _animus_ui_extract_pipeline.assertKnownOptionKeys)(options, ["verify", "appearanceBootstrap"], [{
+	(0, _animus_ui_extract_pipeline.assertKnownOptionKeys)(options, [
+		"verify",
+		"appearanceBootstrap",
+		"quarantine"
+	], [{
 		key: "root",
 		reason: "the Vite driver derives its root from the resolved Vite config"
 	}], {
 		onUnknownKey: "warn",
 		warn: (message) => console.warn(`[animus-extract] ${message}`)
 	});
-	const ctx = new PluginContext(options);
+	const vendor = options.quarantine ? quarantinePlugin(options.quarantine, options.layers) : null;
+	const ctx = new PluginContext(vendor ? {
+		...options,
+		layers: vendor.order
+	} : options);
 	return {
 		name: "animus-extract",
 		enforce: "pre",
 		async config(userConfig, env) {
+			const vendorConfig = await (await vendor?.plugin())?.config.call(this, userConfig, env);
+			const withVendor = (own) => vendorConfig ? (0, vite.mergeConfig)(own, vendorConfig) : own;
 			const { mode } = (0, _animus_ui_extract_pipeline.resolveMode)(options.mode, () => env.command === "build" ? "production" : "development");
 			const define = { __ANIMUS_DEV__: mode === "development" };
 			const root = (0, path.resolve)(userConfig.root ?? process.cwd());
 			const kits = await sourceKitConfig(root, (0, path.resolve)(root, options.system), ctx.kitEngine());
-			return kits ? {
+			if (!kits) return withVendor({ define });
+			const { roots, ...config } = kits;
+			const watched = env.command === "serve" && userConfig.server?.watch !== null ? { server: { watch: { ignored: kitWatchNegations(roots) } } } : {};
+			return withVendor({
 				define,
-				...kits
-			} : { define };
+				...config,
+				...watched
+			});
 		},
-		configureServer(server) {
+		async configureServer(server) {
+			await (await vendor?.plugin())?.configureServer.call(this, server);
 			ctx.devServer = server;
 			ctx.registerSystemWatchPaths();
 		},
-		configResolved(config) {
+		async configResolved(config) {
 			applyResolvedConfig(ctx, config);
+			(await vendor?.plugin())?.configResolved.call(this, config);
 		},
-		buildEnd() {
+		async buildEnd() {
+			(await vendor?.plugin())?.buildEnd.call(this);
 			if (!ctx.builds.end(this.environment ?? ctx.builds.single)) return;
 			cancelSystemReload(ctx);
 			ctx.close();
 		},
 		async buildStart() {
+			await (await vendor?.plugin())?.buildStart.call(this);
 			await ctx.builds.open(this.environment ?? ctx.builds.single);
 			await runBuildStart(ctx, async (specifier, importer) => {
 				return (await this.resolve(specifier, importer))?.id ?? null;
@@ -1486,7 +1735,9 @@ function animusExtract(options) {
 				source
 			}) : void 0);
 		},
-		async resolveId(id, importer) {
+		async resolveId(id, importer, resolveOptions) {
+			const owned = await (await vendor?.plugin())?.resolveId.call(this, id, importer, resolveOptions);
+			if (owned) return owned;
 			const virtual = resolveVirtualId(ctx, id);
 			if (virtual !== null || !id.startsWith(".") || importer === void 0) return virtual;
 			const importerPath = importer.split("?")[0];
@@ -1498,20 +1749,43 @@ function animusExtract(options) {
 				moduleSideEffects: true
 			};
 		},
-		load(id) {
-			return loadVirtualModule(ctx, id);
+		async load(id) {
+			const layergate = await vendor?.plugin();
+			const loaded = await layergate?.load.call(this, id);
+			if (loaded) return loaded;
+			const own = loadVirtualModule(ctx, id);
+			if (layergate && id === RESOLVED_CSS_ID && own !== null) return await layergate.stylesheetHead.call(this, id) + own;
+			return own;
 		},
-		transform(code, id) {
+		async transform(code, id) {
+			if (vendor && /\.css(?:$|\?)/.test(id)) return (await vendor.plugin()).transform.call(this, code, id);
 			return transformSource(ctx, code, id);
 		},
+		generateBundle: {
+			order: "post",
+			handler(_output, bundle) {
+				if (!ctx.served?.fontPreloads.length) return;
+				for (const file of Object.values(bundle)) {
+					if (file.type !== "asset" || !file.fileName.endsWith(".html")) continue;
+					const html = Buffer.from(file.source).toString("utf8");
+					if (!html.includes("data-animus-preload")) continue;
+					for (const href of duplicatedFontPreloads(html, new URL(file.fileName, servedBase(ctx.base)).href)) ctx.warn(`[animus-extract] ${file.fileName} preloads ${href} twice: Animus's font preload and another preload tag, written in the page or added by a plugin whose index.html hook runs after Animus's, so the browser may fetch it twice. Remove the other preload; Animus's names the URL the stylesheet's url() loads.`);
+				}
+			}
+		},
 		transformIndexHtml: {
 			order: "pre",
-			handler() {
-				return buildIndexHtmlTags(ctx);
+			handler(html) {
+				return injectHeadTags(html, buildIndexHtmlTags(ctx, html));
 			}
 		},
 		async hotUpdate(hmr) {
-			return handleHotUpdate(ctx, this.environment, hmr);
+			const vendorModules = (await vendor?.plugin())?.hotUpdate.call(this, hmr);
+			const next = vendorModules ? {
+				...hmr,
+				modules: vendorModules
+			} : hmr;
+			return await handleHotUpdate(ctx, this.environment, next) ?? vendorModules;
 		}
 	};
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import type { ClosedDynamicImport, DiagnosticLevels, StaticCssConfig } from '@animus-ui/extract/pipeline';
+import type { AnimusQuarantineOptions, ClosedDynamicImport, FontPreloadEntry, DiagnosticLevels, StaticCssConfig } from '@animus-ui/extract/pipeline';
 import type { Plugin } from 'vite';
 export { discoverFiles } from '@animus-ui/extract/pipeline';
+export type { AnimusQuarantineOptions } from '@animus-ui/extract/pipeline';
 export interface AnimusExtractOptions {
     /** Path to a module exporting a SystemInstance from `@animus-ui/system`. */
     system: string;
@@ -25,6 +26,11 @@ export interface AnimusExtractOptions {
      * still load any module.
      */
     closedDynamicImports?: ClosedDynamicImport[];
+    /** The font faces this app preloads, in place of each typed face's own
+     *  `preload` flag, so a face declared once for every product preloads only
+     *  where the app renders it: family names, or `{ family, weight?, style? }`
+     *  (see `FontPreloadEntry`). `[]` preloads none. */
+    fontPreloads?: FontPreloadEntry[];
     /**
      * Substrings, or globs when `*`/`?` present. Replaces the defaults `dist`,
      * `.test.`, `.spec.`; `node_modules`, `.next`, `.animus` always apply.
@@ -107,6 +113,15 @@ export interface AnimusExtractOptions {
         code: string;
         cspHash: string;
     };
+    /**
+     * Load third-party stylesheets into `anm-vendor`, a layer below every
+     * Animus layer, so their normal rules never beat Animus's. Needs
+     * `@animus-ui/layergate`. `sheets` are delivered with Animus's stylesheet,
+     * ahead of it; `dependencies` also covers `.css` your modules import from
+     * packages; `optOut` keeps a file's own rules outside the layer. App CSS
+     * and CSS Modules are left alone.
+     */
+    quarantine?: AnimusQuarantineOptions;
 }
 export declare function animusExtract(options: AnimusExtractOptions): Plugin;
 export default animusExtract;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAEhB,eAAe,EAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AA4C5D,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf;;;0DAGsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC7C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;+CAE2C;IAC3C,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IACpC;;sDAEkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;gBAEY;IACZ,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;OAGG;IACH,mBAAmB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAMD,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAkInE;eAEc,aAAa"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EACV,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAEhB,eAAe,EAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,MAAM,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AA+C3E,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf;;;0DAGsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC7C;;;wDAGoD;IACpD,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;+CAE2C;IAC3C,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IACpC;;sDAEkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;gBAEY;IACZ,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;OAGG;IACH,mBAAmB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,uBAAuB,CAAC;CACtC;AAiBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CA4MnE;eAEc,aAAa"}

package/dist/quarantine-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { AnimusQuarantineOptions } from '@animus-ui/extract/pipeline';
+import type { LayergatePlugin } from '@animus-ui/layergate/vite';
+export interface Quarantine {
+    /** The layer order, `anm-vendor` first, Animus's stylesheet declares. */
+    order: string[];
+    /** layergate's plugin, whose hooks Animus's own run. */
+    plugin(): Promise<LayergatePlugin>;
+}
+export declare function quarantinePlugin(options: AnimusQuarantineOptions, layers: readonly string[] | undefined): Quarantine;
+//# sourceMappingURL=quarantine-plugin.d.ts.map

package/dist/quarantine-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quarantine-plugin.d.ts","sourceRoot":"","sources":["../src/quarantine-plugin.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACpC;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACpC,UAAU,CAIZ"}

package/dist/watch-ignored.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `server.watch.ignored` entries that watch installed kits. Vite always
+ * ignores every `node_modules` path, where an installed kit lives, and
+ * watches what a negated glob names. Each glob names a kit root and the
+ * paths under it that ingestion would read: a segment holding an excluded
+ * name, the kit's own `node_modules` among them, stays ignored, so the
+ * watcher never walks into it. The segment test is a regex lookahead,
+ * which picomatch keeps as written.
+ */
+export declare function kitWatchNegations(roots: readonly string[]): string[];
+//# sourceMappingURL=watch-ignored.d.ts.map

package/dist/watch-ignored.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-ignored.d.ts","sourceRoot":"","sources":["../src/watch-ignored.ts"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAKpE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animus-ui/vite-plugin",
-  "version": "0.1.32",
+  "version": "0.1.36",
   "description": "Animus static CSS extraction Vite plugin",
   "keywords": [
     "animus",
@@ -39,16 +39,23 @@
     "compile": "bun check"
   },
   "dependencies": {
-    "@animus-ui/extract": "0.1.32",
+    "@animus-ui/extract": "0.1.36",
     "browserslist": "^4.28.8",
     "lightningcss": "^1.33.0"
   },
   "devDependencies": {
-    "@animus-ui/assertions": "0.1.32"
+    "@animus-ui/assertions": "0.1.36",
+    "@animus-ui/layergate": "0.1.36"
   },
   "peerDependencies": {
+    "@animus-ui/layergate": "0.1.36",
     "vite": ">=8 <9"
   },
+  "peerDependenciesMeta": {
+    "@animus-ui/layergate": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.12.0"
   }