@pitlane/assets 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @pitlane/assets
 
+## 0.2.0
+
+### Minor Changes
+
+- f14d251: `assets()` accepts `allowFiles`, `allowPackages`, and `denyFiles`, the browser boundary options of `remix/assets`, and reads them the same way. Setting `allowFiles` turns the boundary on: `vite build` fails, listing each file and its importer, when a file outside it would reach the client output, including files that server code links and the build copies there. `vite dev` fails the browser transform of such a module and refuses to serve such a file. Without `allowFiles` nothing changes. With `remix()`, pass the options as `remix({ assets: { allowFiles, … } })`. Upgrade if you deploy the same app to the `remix/assets` Node server and to a bundled host such as Oxygen or Cloudflare, so a file the Node server refuses no longer ships silently from the build.
+- f14d251: `@pitlane/assets/vite-plugin` exports `ASSETS_MANIFEST_FILE`, the name of the manifest module `vite build` writes at the root of each server environment's output directory. Server bundles import that file by a relative path, so a host that deploys a single module, such as Shopify Oxygen, has to fold it into the bundle in a later build. Use the constant there instead of hardcoding `__pitlane_assets_manifest.js`.
+
+### Patch Changes
+
+- The API reference and installed declarations now document `assets()` and every `AssetsPluginOptions` member, and the default `@pitlane/assets/manifest` export. No behavior changed.
+- d7fcdd4: The development manifest no longer rebuilds from scratch. `assets()` under `vite dev` now keeps the import edges it recorded for every module and, after an edit, transforms only the changed file before answering the next request; modules the server never executed, such as lazy routes, are no longer transformed again on every invalidation. Browser modules it discovers are transformed through Vite's own request pipeline, so the browser's first load reads the cache instead of transforming them a second time.
+
+    On an app with about 1,900 server modules and 400 browser modules, an edit that previously held the next request for 20–45 seconds now answers in under 2 seconds, the same as the previous `@pitlane/dev` integration, and the first manifest costs about a third less. The dev manifest's contents are unchanged.
+
+- 92ce0a2: `vite build` no longer publishes server-only files into the client output. The copy from each server build into the client output directory took every file the server bundle emitted, so server sourcemaps, `.dev.vars` and `wrangler.json` from `@cloudflare/vite-plugin`, `oxygen.json` from MiniOxygen, and anything else a plugin wrote beside the server bundle ended up in the publicly served directory. Only the stylesheets the server code imports, the fonts and images they reference, and the files the server code imports are copied now, and the server's half of the asset manifest names only those files. Upgrade if you deploy the client output of an app built with server sourcemaps or a platform plugin.
+- 8e38080: The development manifest no longer stays out of date after a build that changes kept interrupting. Under `vite dev`, `assets()` builds the manifest again when a module it reads is invalidated mid-build, and gives up after three builds so a plugin that invalidates modules on every transform cannot hold the request forever. Vite then cached the manifest it gave up on, and it stayed cached, missing the last change's stylesheets and browser entries, until another edit invalidated it. That was most likely on a cold start, where Vite's dependency optimizer re-runs and invalidates the browser module graph. The next import of `@pitlane/assets/manifest` now builds it again, and a build that completes uninterrupted is cached as before.
+- d8670f8: The development manifest no longer keeps what a module imported, or which browser entries it named, before an edit. Under `vite dev`, `assets()` can transform one module more than once at the same time: the manifest's discovery and the module runner each ask for it, or an edit invalidates the module mid-transform. If a transform of the old code finished last, the manifest kept that code's stylesheets and literal `getScriptEntry()` and `getHref()` inputs until the module changed again, including in the first manifest a dev server built. A transform whose module was invalidated after its request began now records nothing, and a manifest being built when that happens is built again.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/manifest.d.mts

@@ -12,6 +12,7 @@ import { o as AssetsManifest } from "./types-DlTsImzF.mjs";
  *
  * @module @pitlane/assets/manifest
  */
+/** `{ mode: "unavailable" }`, until `assets()` or an alias replaces this module. */
 declare let manifest: AssetsManifest;
 //#endregion
 export { manifest as default };

package/dist/manifest.mjs

@@ -11,6 +11,7 @@
 *
 * @module @pitlane/assets/manifest
 */
+/** `{ mode: "unavailable" }`, until `assets()` or an alias replaces this module. */
 let manifest = { mode: "unavailable" };
 //#endregion
 export { manifest as default };

package/dist/vite-plugin.d.mts

@@ -1,5 +1,14 @@
 import { PluginOption } from "vite";
+//#region src/vite/state.d.ts
+/**
+ * The manifest module a build writes at the root of each server environment's
+ * output directory. The server chunks that read the manifest import this file
+ * by a relative path, so a host that deploys a single module must bundle it in.
+ */
+export declare const ASSETS_MANIFEST_FILE = "__pitlane_assets_manifest.js";
+//#endregion
 //#region src/vite-plugin.d.ts
+/** Options for {@link assets}. `remix()` from `@pitlane/vite-plugin-remix` accepts them as `remix({ assets })`. */
 export interface AssetsPluginOptions {
   /** Extra source keys to make available as client entries or assets. */
   include?: string[];
@@ -7,6 +16,21 @@ export interface AssetsPluginOptions {
   serverEnvironments?: string[];
   /** Override Vite's native setting. With neither setting present, maps are disabled. */
   chunkImportMap?: boolean;
+  /**
+   * Files and globs, relative to the Vite root, that may reach the browser.
+   * Setting it turns on the browser boundary: a build that would publish any
+   * other file fails, and `vite dev` refuses to serve one. Read as
+   * `remix/assets` reads it; a directory path matches every file below it.
+   */
+  allowFiles?: string[];
+  /**
+   * Packages that may reach the browser, with their `dependencies` and
+   * installed `optionalDependencies`. Peer dependencies are not included.
+   * Requires `allowFiles`.
+   */
+  allowPackages?: string[];
+  /** Files and globs refused even when `allowFiles` or `allowPackages` allows them. Requires `allowFiles`. */
+  denyFiles?: string[];
 }
 /** Browser entries declared by one server module's development transform. */
 export interface AssetEntryRegistration {
@@ -22,5 +46,13 @@ export interface AssetsPluginApi {
   /** Replace an owner's declarations; an empty list removes them. Builds use `emitFile` instead. */
   setBrowserEntries(registration: AssetEntryRegistration): void;
 }
+/**
+ * The Vite plugins that give `@pitlane/assets` its manifest: they serve
+ * browser entries during `vite dev`, emit them in a build, and replace
+ * `@pitlane/assets/manifest` with the manifest of the current dev server or
+ * build. Setting `allowFiles` also enforces the browser boundary.
+ *
+ * @throws When `allowPackages` or `denyFiles` is set without `allowFiles`.
+ */
 export declare function assets(options?: AssetsPluginOptions): PluginOption;
 //#endregion

package/dist/vite-plugin.mjs

@@ -1,11 +1,90 @@
 import { n as quotedList, t as assetsSpecifier } from "./specifier-DLC81sXY.mjs";
 import { t as createAssetManifest } from "./build-BbA-Zq1m.mjs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, posix, relative, resolve } from "node:path";
-import { isCSSRequest, normalizePath, parseSync } from "vite";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createFilter, isCSSRequest, normalizePath, parseSync } from "vite";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import MagicString from "magic-string";
-import { existsSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/vite/boundary-policy.ts
+/**
+* Builds the access check `remix/assets` applies to the files it serves.
+* `root` is a real path; files passed to the check are real absolute paths.
+*/
+function createBrowserBoundary(root, options) {
+	let allowMatchers = options.allowFiles.map((pattern) => fileMatcher(root, pattern));
+	let denyMatchers = (options.denyFiles ?? []).map((pattern) => ({
+		pattern,
+		matches: fileMatcher(root, pattern)
+	}));
+	let packageRoots = allowedPackageRoots(root, (options.allowPackages ?? []).map((name) => name.trim()));
+	return (file) => {
+		if (file.includes("/node_modules/@oxc-project/runtime/")) return { allowed: true };
+		if (!(allowMatchers.some((matches) => matches(file)) || packageRoots.some((directory) => within(directory, file)))) return { allowed: false };
+		let denial = denyMatchers.find(({ matches }) => matches(file));
+		return denial ? {
+			allowed: false,
+			deniedBy: denial.pattern
+		} : { allowed: true };
+	};
+}
+/** Whether `file` is `directory` or below it. */
+function within(directory, file) {
+	return file === directory || file.startsWith(`${directory}/`);
+}
+function fileMatcher(root, pattern) {
+	let path = normalizePath(isAbsolute(pattern) ? pattern : join(root, pattern));
+	if (/[*?[\]{}()!+@]/.test(pattern)) return createFilter(path, null, { resolve: false });
+	if (!existsSync(path)) return (file) => file === path;
+	let real = normalizePath(realpathSync(path));
+	return statSync(real).isDirectory() ? (file) => within(real, file) : (file) => file === real;
+}
+/** Whether `name` is a bare or scoped package name, not a path, as `remix/assets` requires. */
+function isPackageName(name) {
+	let scoped = name.startsWith("@");
+	let parts = (scoped ? name.slice(1) : name).split("/");
+	return parts.length === (scoped ? 2 : 1) && parts.every((part) => /^[\w.~-]+$/.test(part) && part !== "." && part !== "..");
+}
+/**
+* The real directories of each named package and of everything its
+* `dependencies` and installed `optionalDependencies` pull in, transitively.
+* Peer dependencies are left out, as `remix/assets` leaves them out.
+*/
+function allowedPackageRoots(root, names) {
+	let roots = /* @__PURE__ */ new Set();
+	let pending = names.map((name) => {
+		if (!isPackageName(name)) throw new Error(`[assets] allowPackages values must be package names. Received ${JSON.stringify(name)}.`);
+		let directory = packageDirectory(name, root);
+		if (!directory) throw new Error(`[assets] Could not resolve allowed package "${name}".`);
+		return directory;
+	});
+	while (pending.length > 0) {
+		let directory = pending.pop();
+		if (roots.has(directory)) continue;
+		roots.add(directory);
+		let manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+		for (let name of Object.keys(manifest.dependencies ?? {})) {
+			let dependency = packageDirectory(name, directory);
+			if (!dependency) throw new Error(`[assets] Could not resolve dependency "${name}" of allowed package ${directory}.`);
+			pending.push(dependency);
+		}
+		for (let name of Object.keys(manifest.optionalDependencies ?? {})) {
+			let dependency = packageDirectory(name, directory);
+			if (dependency) pending.push(dependency);
+		}
+	}
+	return [...roots];
+}
+/** The real directory Node's lookup finds for package `name` from `from`, or `undefined`. */
+function packageDirectory(name, from) {
+	for (let directory = from;; directory = dirname(directory)) {
+		let candidate = join(directory, "node_modules", name);
+		if (existsSync(join(candidate, "package.json"))) return normalizePath(realpathSync(candidate));
+		if (dirname(directory) === directory) return void 0;
+	}
+}
+//#endregion
 //#region src/vite/entries.ts
 function sourceKey(root, id) {
 	let file = id.split("?")[0].split("#")[0];
@@ -22,6 +101,217 @@ function fileModule(id) {
 	return !id.startsWith("\0") && isAbsolute(id.split("?")[0]);
 }
 //#endregion
+//#region src/vite/folded-files.ts
+/** `context`, with `addWatchFile` reporting each file to `observe` before Vite records it. */
+function watching(context, observe) {
+	return new Proxy(context, { get(target, property) {
+		if (property === "addWatchFile") return (file) => {
+			observe(file);
+			target.addWatchFile(file);
+		};
+		let value = Reflect.get(target, property, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+}
+function unsupported(name) {
+	return /* @__PURE__ */ new Error(`[assets] This Vite version does not expose the ${name} hook the browser boundary reads. Use a supported Vite version.`);
+}
+/** Calls `observe` with every file the folding plugins report, by wrapping their hooks' contexts. */
+function observeFoldedFiles(config, observe) {
+	let plugin = (name) => config.plugins.find((candidate) => candidate.name === name);
+	for (let name of ["vite:css", "vite:worker-import-meta-url"]) {
+		let hook = plugin(name)?.transform;
+		if (typeof hook !== "object") throw unsupported(name);
+		let handler = hook.handler;
+		hook.handler = function(code, id, options) {
+			let context = watching(this, (file) => observe(this.environment, name, id, file));
+			return handler.call(context, code, id, options);
+		};
+	}
+	let hook = plugin("vite:worker")?.load;
+	if (typeof hook !== "object") throw unsupported("vite:worker");
+	let handler = hook.handler;
+	hook.handler = function(id, options) {
+		let context = watching(this, (file) => observe(this.environment, "vite:worker", id, file));
+		return handler.call(context, id, options);
+	};
+}
+//#endregion
+//#region src/vite/boundary.ts
+function describe({ file, importer, deniedBy }) {
+	let reason = deniedBy ? `matches denyFiles ${JSON.stringify(deniedBy)}` : "not in allowFiles or allowPackages";
+	return `${file}${importer ? ` (imported by ${importer})` : ""}: ${reason}`;
+}
+/** Query-free path of a module id or emitted file name. */
+function filePath(id) {
+	return normalizePath(id.split(/[?#]/, 1)[0]);
+}
+/**
+* A page, or an inline script Vite proxies out of one: the boundary governs
+* what a page loads, not the page. An HTML file a module imports is data.
+*/
+function htmlDocument(id) {
+	return filePath(id).endsWith(".html") && (!id.includes("?") || /[?&]html-proxy\b/.test(id));
+}
+/**
+* The server files a build copies into the client output: every stylesheet
+* the server graph imports, except as a string or URL, and the assets its
+* chunks link.
+*/
+function publishedServerFiles(bundle) {
+	let files = [];
+	for (let output of Object.values(bundle)) {
+		if (output.type !== "chunk" || !output.viteMetadata) continue;
+		for (let id of output.moduleIds) if (isCSSRequest(id) && !/[?&](?:inline|raw|url)\b/.test(id)) files.push(id);
+		for (let fileName of output.viteMetadata.importedAssets) {
+			let asset = bundle[fileName];
+			if (asset?.type === "asset") files.push(...asset.originalFileNames);
+		}
+	}
+	return files;
+}
+/**
+* Holds the client graph and every file the build publishes for the browser
+* to `allowFiles`, `allowPackages`, and `denyFiles`, the way `remix/assets`
+* holds the files its asset server answers.
+*/
+function browserBoundary(options, serverEnvironments) {
+	let root = "";
+	let inspect;
+	let viteClient = normalizePath(dirname(fileURLToPath(import.meta.resolve("vite/dist/client/client.mjs"))));
+	/** Build module id → the files a folding plugin read into it. */
+	let foldedFiles = /* @__PURE__ */ new Map();
+	function refusal(file, importer) {
+		let verdict = inspect(file);
+		if (verdict.allowed) return;
+		return {
+			file: sourceKey(root, file),
+			importer: importer && sourceKey(root, importer),
+			deniedBy: verdict.deniedBy
+		};
+	}
+	/** The real path of the file `path` names from the root, or `undefined` when none exists. */
+	function existingFile(path) {
+		let file = resolve(root, filePath(path));
+		if (!existsSync(file) || !statSync(file).isFile()) return;
+		return normalizePath(realpathSync(file));
+	}
+	/** The source file a dev request reaches, or `undefined` when Vite itself supplies it. */
+	function servedSource(environment, file) {
+		if (within(viteClient, file)) return;
+		let optimizer = environment.depsOptimizer;
+		if (!optimizer?.isOptimizedDepFile(file)) return file;
+		let { optimized, discovered } = optimizer.metadata;
+		let dependency = [...Object.values(optimized), ...Object.values(discovered)].find((info) => normalizePath(info.file) === file);
+		return dependency?.src && normalizePath(dependency.src);
+	}
+	function devRefusal(environment, file, importer) {
+		let source = servedSource(environment, file);
+		if (!source) return;
+		importer ??= [...environment.moduleGraph.getModulesByFile(file) ?? []].flatMap((module) => [...module.importers]).find((module) => module.file)?.file ?? void 0;
+		return refusal(source, importer);
+	}
+	return {
+		name: "pitlane-assets-boundary",
+		sharedDuringBuild: true,
+		configResolved(config) {
+			root = config.root;
+			inspect = createBrowserBoundary(normalizePath(realpathSync(root)), options);
+			observeFoldedFiles(config, (environment, plugin, module, file) => {
+				if (plugin === "vite:css" && !isCSSRequest(file) && !config.assetsInclude(file)) return;
+				if (environment.mode === "build") {
+					let files = foldedFiles.get(module);
+					if (!files) foldedFiles.set(module, files = /* @__PURE__ */ new Set());
+					files.add(file);
+					return;
+				}
+				if (environment.name !== "client" || environment.mode !== "dev") return;
+				let source = existingFile(file);
+				let refused = source && devRefusal(environment, source, module);
+				if (refused) throw new Error(`[assets] Outside the browser boundary: ${describe(refused)}`);
+			});
+		},
+		configureServer(server) {
+			let client = server.environments.client;
+			let { publicDir, base } = server.config;
+			server.middlewares.use(((request, _response, next) => {
+				let path;
+				try {
+					path = decodeURIComponent(filePath(request.url ?? "/"));
+				} catch {
+					return next();
+				}
+				if (base !== "/" && path.startsWith(base)) path = `/${path.slice(base.length)}`;
+				if (path.startsWith("/@") && !path.startsWith("/@fs/")) return next();
+				if (publicDir && existsSync(join(publicDir, path))) return next();
+				if (htmlDocument(path)) return next();
+				let requested = join(root, path);
+				if (path.startsWith("/@fs/")) {
+					let fsPath = path.slice(5);
+					requested = /^[A-Za-z]:\//.test(fsPath) ? fsPath : `/${fsPath}`;
+				}
+				let file = existingFile(requested);
+				let refused = file && devRefusal(client, file);
+				if (!refused) return next();
+				next(/* @__PURE__ */ new Error(`[assets] Outside the browser boundary: ${describe(refused)}`));
+			}));
+		},
+		transform: {
+			order: "pre",
+			handler(_code, id) {
+				let environment = this.environment;
+				if (environment.mode !== "dev" || environment.name !== "client" || !fileModule(id)) return;
+				if (htmlDocument(id)) return;
+				let refused = devRefusal(environment, existingFile(id) ?? filePath(id));
+				if (refused) throw new Error(`[assets] Outside the browser boundary: ${describe(refused)}`);
+			}
+		},
+		generateBundle(_options, bundle) {
+			let name = this.environment.name;
+			let published = [];
+			if (name === "client") {
+				for (let id of this.getModuleIds()) {
+					if (!fileModule(id)) continue;
+					let info = this.getModuleInfo(id);
+					let importer = [...info?.importers ?? [], ...info?.dynamicImporters ?? []].find(fileModule);
+					published.push({
+						path: id,
+						importer
+					});
+				}
+				for (let output of Object.values(bundle)) {
+					if (output.type !== "asset" || output.names.some(isCSSRequest)) continue;
+					for (let path of output.originalFileNames) published.push({ path });
+				}
+			} else if (serverEnvironments.includes(name)) for (let path of publishedServerFiles(bundle)) {
+				let importer = this.getModuleInfo(path)?.importers.find(fileModule);
+				published.push({
+					path,
+					importer
+				});
+			}
+			let refusals = /* @__PURE__ */ new Map();
+			for (let { path, importer } of published) {
+				let entries = [{
+					path,
+					importer
+				}, ...[...foldedFiles.get(path) ?? []].map((file) => ({
+					path: file,
+					importer: path
+				}))];
+				for (let entry of entries) {
+					let file = !htmlDocument(entry.path) && existingFile(entry.path);
+					let refused = file && refusal(file, entry.importer);
+					if (refused && !refusals.get(refused.file)?.importer) refusals.set(refused.file, refused);
+				}
+			}
+			if (refusals.size === 0) return;
+			let lines = [...refusals.values()].map(describe);
+			this.error(`[assets] Outside the browser boundary:\n  ${lines.join("\n  ")}`);
+		}
+	};
+}
+//#endregion
 //#region src/vite/output.ts
 function captureOutput(bundle, config, role, assetFiles, entryFiles) {
 	let graph = {
@@ -31,8 +321,10 @@ function captureOutput(bundle, config, role, assetFiles, entryFiles) {
 		assets: Object.create(null)
 	};
 	let globalStylesheets = config.build.cssCodeSplit ? [] : Object.values(bundle).flatMap((output) => output.type === "asset" && output.originalFileNames.includes("style.css") ? [output.fileName] : []);
+	let linked = role === "server" ? linkedFiles(bundle, globalStylesheets) : void 0;
 	for (let output of Object.values(bundle)) {
 		if (output.type === "asset") {
+			if (linked && !linked.has(output.fileName)) continue;
 			let stylesheet = output.names.some(isCSSRequest);
 			for (let file of output.originalFileNames) {
 				if (stylesheet && !isCSSRequest(file)) continue;
@@ -54,6 +346,15 @@ function captureOutput(bundle, config, role, assetFiles, entryFiles) {
 	for (let [key, file] of entryFiles) if (bundle[file]?.type === "chunk") graph.entries[key] = file;
 	return graph;
 }
+function linkedFiles(bundle, globalStylesheets) {
+	let files = new Set(globalStylesheets);
+	for (let output of Object.values(bundle)) {
+		if (output.type !== "chunk" || !output.viteMetadata) continue;
+		for (let file of output.viteMetadata.importedCss) files.add(file);
+		for (let file of output.viteMetadata.importedAssets) files.add(file);
+	}
+	return files;
+}
 function captureImportMap(bundle, fileName) {
 	let output = bundle[fileName];
 	if (output?.type !== "asset") throw new Error(`[assets] The client build did not emit its configured import map "${fileName}".`);
@@ -324,7 +625,12 @@ function literalInputs(modules, id) {
 }
 //#endregion
 //#region src/vite/state.ts
-const MANIFEST_FILE = "__pitlane_assets_manifest.js";
+/**
+* The manifest module a build writes at the root of each server environment's
+* output directory. The server chunks that read the manifest import this file
+* by a relative path, so a host that deploys a single module must bundle it in.
+*/
+const ASSETS_MANIFEST_FILE = "__pitlane_assets_manifest.js";
 const MANIFEST_ID = "\0pitlane:assets-manifest";
 const MANIFEST_EXTERNAL = "pitlane:assets-build-manifest";
 const EMPTY_INPUT = "\0pitlane:assets-empty-input";
@@ -372,16 +678,26 @@ async function writeManifests(state) {
 		});
 		let output = state.outputs.get(name);
 		await mkdir(output.outDir, { recursive: true });
-		await writeFile(resolve(output.outDir, MANIFEST_FILE), `export default JSON.parse(${JSON.stringify(JSON.stringify({
+		await writeFile(resolve(output.outDir, ASSETS_MANIFEST_FILE), `export default JSON.parse(${JSON.stringify(JSON.stringify({
 			...manifest,
 			serverEnvironment: name
 		}))});\n`);
-		for (let asset of Object.values(output.bundle)) {
-			if (asset.type !== "asset" || twins.get(name).has(asset.fileName)) continue;
-			let destination = resolve(client.outDir, asset.fileName);
-			await mkdir(dirname(destination), { recursive: true });
-			await writeFile(destination, asset.source);
-		}
+		await publishLinkedFiles(output, twins.get(name), client.outDir);
+	}
+}
+/**
+* Copies the stylesheets and assets a server graph links into the public client
+* output, so every URL its manifest names is served. A stylesheet with a client
+* twin already is.
+*/
+async function publishLinkedFiles(output, twin, publicDir) {
+	let linked = /* @__PURE__ */ new Set([...Object.values(output.graph.chunks).flatMap((chunk) => chunk.stylesheets), ...Object.values(output.graph.assets)]);
+	for (let file of linked) {
+		let asset = output.bundle[file];
+		if (asset?.type !== "asset" || twin.has(file)) continue;
+		let destination = resolve(publicDir, file);
+		await mkdir(dirname(destination), { recursive: true });
+		await writeFile(destination, asset.source);
 	}
 }
 function importMapFileName(config) {
@@ -440,7 +756,7 @@ function assetBuild(state) {
 		},
 		renderChunk(code, chunk) {
 			if (!code.includes("pitlane:assets-build-manifest")) return;
-			let file = posix.relative(posix.dirname(chunk.fileName), MANIFEST_FILE);
+			let file = posix.relative(posix.dirname(chunk.fileName), ASSETS_MANIFEST_FILE);
 			if (!file.startsWith(".")) file = `./${file}`;
 			return {
 				code: code.replaceAll(MANIFEST_EXTERNAL, file),
@@ -566,6 +882,26 @@ function assetStyles() {
 	};
 }
 //#endregion
+//#region src/vite/transform-start.ts
+let invalidations = 0;
+let requestStart = new AsyncLocalStorage();
+/** Counts a hard invalidation and returns its place on the timeline. */
+function countInvalidation() {
+	return ++invalidations;
+}
+/** Runs `request`, which loads and transforms a module, as starting now. */
+function startRequest(request) {
+	return requestStart.run(invalidations, request);
+}
+/**
+* The place on the timeline where the calling transform's request started.
+* A transform no request started, such as one a plugin runs through
+* `pluginContainer.transform` itself, started where this is called.
+*/
+function requestStarted() {
+	return requestStart.getStore() ?? invalidations;
+}
+//#endregion
 //#region src/vite/dev-graph.ts
 /** CSS requests that import a string or URL rather than apply a stylesheet. */
 const NON_STYLESHEET_QUERY = /[?&](?:inline|url|raw)\b/;
@@ -613,28 +949,55 @@ function followed(environment, id) {
 	return (noExternal === void 0 ? [] : Array.isArray(noExternal) ? noExternal : [noExternal]).some((pattern) => typeof pattern === "string" ? pattern === pkg : pattern.test(pkg));
 }
 /**
+* A module is analyzed once. Its edge record was written by the transform
+* hook, whether the runner or discovery ran that transform, and stays
+* current until the module is invalidated, which drops the record. Keying
+* this on `transformResult` instead would re-transform every module the
+* runner has not executed on each rebuild.
+*
+* Client discovery goes through `transformRequest`, so it shares Vite's
+* in-flight and cached transforms with the import analysis that warms a
+* browser module's dependencies, and the browser later reads the cache.
 * Server discovery must not populate `transformResult`: the module runner
-* would treat its stale instance as current. Client transforms may warm
-* and cache their dependencies after the optimizer has initialized.
+* asks whether a module it already evaluated is still current by that
+* field, so a transform cached between a file change and the runner's next
+* import would keep its stale instance alive.
 */
 async function analyze(environment, id, edges) {
-	if (environment.moduleGraph.getModuleById(id)?.transformResult && edges.has(id)) return;
+	if (edges.has(id)) return;
 	let { root } = environment.config;
 	try {
-		await environment.moduleGraph.ensureEntryFromUrl(servedPath(root, id));
-		let loaded = await environment.pluginContainer.load(id);
-		let code = loaded == null ? null : typeof loaded === "string" ? loaded : loaded.code;
-		if (code == null) {
-			if (!fileModule(id)) throw new Error("No plugin loaded the module.");
-			code = await readFile(id.split("?")[0], "utf8");
+		let url = servedPath(root, id);
+		if (environment.config.consumer === "client") {
+			await environment.transformRequest(url.startsWith("/@id/") ? id : url);
+			if (edges.has(id)) return;
 		}
-		await environment.pluginContainer.transform(code, id);
+		await startRequest(() => transformOutsideCache(environment, id, url));
 	} catch (error) {
 		let name = fileModule(id) ? sourceKey(root, id) : id;
 		throw new Error(`[assets] Could not analyze "${name}" for the "${environment.name}" development asset manifest: ${error.message}`, { cause: error });
 	}
 }
 /**
+* Loads and transforms a module as `transformRequest` does, handing the load
+* result's source map and module type to the transform, but without reading
+* or populating Vite's transform cache.
+*/
+async function transformOutsideCache(environment, id, url) {
+	await environment.moduleGraph.ensureEntryFromUrl(url);
+	let loaded = await environment.pluginContainer.load(id);
+	let source = typeof loaded === "string" ? { code: loaded } : loaded;
+	let code = source?.code;
+	if (code == null) {
+		if (!fileModule(id)) throw new Error("No plugin loaded the module.");
+		code = await readFile(id.split("?")[0], "utf8");
+	}
+	await environment.pluginContainer.transform(code, id, {
+		inMap: source?.map,
+		moduleType: source?.moduleType
+	});
+}
+/**
 * Every module reachable from `roots` through static and dynamic edges,
 * transforming each one the graph has not analyzed yet. Stylesheets are
 * leaves: their own `@import`s are inlined by Vite's CSS pipeline. Passing
@@ -784,12 +1147,48 @@ function assetDevelopment(state) {
 	};
 	let snapshots = /* @__PURE__ */ new Map();
 	let building = /* @__PURE__ */ new Set();
-	/** Invalidates a server environment's manifest and, through Vite, every module importing it. */
+	/** Server environments invalidated while their snapshot was being built. */
+	let stale = /* @__PURE__ */ new Set();
+	/** Environment name → module id → where its last hard invalidation is on the transform timeline. */
+	let invalidations = /* @__PURE__ */ new Map();
+	/**
+	* Invalidates a server environment's manifest and, through Vite, every
+	* module importing it. A manifest being built is marked instead, and
+	* `load` builds it again, since Vite would cache the code `load` returns.
+	*/
 	function invalidate(name, timestamp) {
+		if (building.has(name)) return void stale.add(name);
 		let environment = server?.environments[name];
 		let manifest = environment?.moduleGraph.getModuleById(MANIFEST_ID);
 		if (manifest) environment.moduleGraph.invalidateModule(manifest, /* @__PURE__ */ new Set(), timestamp, true);
 	}
+	/** The modules of `environment` a server environment's snapshot was computed from. */
+	function tracked(environment, serverName) {
+		let snapshot = snapshots.get(serverName);
+		if (environment === serverName) return snapshot?.server;
+		if (environment === "client") return snapshot?.client;
+	}
+	/** Invalidates every snapshot computed, or being computed, from module `id` of `environment`. */
+	function invalidateSnapshotsWith(environment, id, timestamp) {
+		for (let serverName of snapshots.keys()) if (tracked(environment, serverName)?.has(id)) invalidate(serverName, timestamp);
+		for (let serverName of building) if (environment === serverName || environment === "client") stale.add(serverName);
+	}
+	function sameEdges(previous, next) {
+		return previous.static.length === next.static.length && previous.dynamic.length === next.dynamic.length && previous.static.every((edge, index) => edge === next.static[index]) && previous.dynamic.every((edge, index) => edge === next.dynamic[index]);
+	}
+	/**
+	* Records what a transform of module `id` found: its edges and, in a
+	* server environment, its resolver usage.
+	*/
+	function recordTransform(environment, id, edges, usage) {
+		let edgeRecords = environmentEdges(graph, environment);
+		let previous = edgeRecords.get(id);
+		edgeRecords.set(id, edges);
+		if (previous && !sameEdges(previous, edges)) invalidateSnapshotsWith(environment, id);
+		let usageRecords = graph.resolverUsage.get(environment);
+		if (usage) usageRecords?.set(id, usage);
+		else usageRecords?.delete(id);
+	}
 	return {
 		name: "pitlane-assets-dev",
 		apply: "serve",
@@ -799,10 +1198,26 @@ function assetDevelopment(state) {
 			handler(devServer) {
 				server = devServer;
 				for (let environment of Object.values(devServer.environments)) {
-					let { name } = environment;
+					let { name, moduleGraph } = environment;
+					let edges = environmentEdges(graph, name);
+					let invalidated = /* @__PURE__ */ new Map();
+					invalidations.set(name, invalidated);
+					let invalidateModule = moduleGraph.invalidateModule;
+					moduleGraph.invalidateModule = (mod, seen, timestamp, isHmr, softInvalidate) => {
+						if (!softInvalidate && mod.id && mod.id !== "\0pitlane:assets-manifest" && !isCSSRequest(mod.id)) {
+							edges.delete(mod.id);
+							if (!isHmr) invalidated.set(mod.id, countInvalidation());
+							invalidateSnapshotsWith(name, mod.id, timestamp);
+						}
+						invalidateModule.call(moduleGraph, mod, seen, timestamp, isHmr, softInvalidate);
+					};
+					let { transformRequest, warmupRequest } = environment;
+					environment.transformRequest = (url) => startRequest(() => transformRequest.call(environment, url));
+					environment.warmupRequest = (url) => startRequest(() => warmupRequest.call(environment, url));
 					if (!state.serverEnvironments.includes(name)) continue;
 					let roots = /* @__PURE__ */ new Set();
 					graph.roots.set(name, roots);
+					graph.resolverUsage.set(name, /* @__PURE__ */ new Map());
 					let fetchModule = environment.fetchModule;
 					environment.fetchModule = async (id, importer, options) => {
 						let fetched = await fetchModule.call(environment, id, importer, options);
@@ -830,32 +1245,45 @@ function assetDevelopment(state) {
 			if (!state.serverEnvironments.includes(name)) throw unservedEnvironmentError(name, state.serverEnvironments);
 			building.add(name);
 			try {
-				let snapshot = await createDevSnapshot(server, state, graph, name);
+				let snapshot;
+				let passes = 0;
+				do {
+					stale.delete(name);
+					snapshot = await createDevSnapshot(server, state, graph, name);
+				} while (stale.has(name) && ++passes < 3);
 				snapshots.set(name, snapshot);
+				if (stale.has(name)) {
+					let { moduleGraph } = server.environments[name];
+					moduleGraph.invalidateModule(await moduleGraph.ensureEntryFromUrl(MANIFEST_ID));
+				}
 				return `export default JSON.parse(${JSON.stringify(JSON.stringify(snapshot.manifest))});\n`;
 			} finally {
 				building.delete(name);
+				stale.delete(name);
 			}
 		},
 		transform: { async handler(code, id) {
 			if (id === "\0pitlane:assets-manifest" || isCSSRequest(id)) return;
 			let name = this.environment.name;
-			let specifiers = importSpecifiers(code);
+			let invalidated = invalidations.get(name);
+			let started = requestStarted();
+			let resolve = (specifier) => this.resolve(specifier, id);
 			let resolveAll = async (list) => {
-				let resolved = await Promise.all(list.map((specifier) => this.resolve(specifier, id)));
+				let resolved = await Promise.all(list.map(resolve));
 				return [...new Set(resolved.flatMap((result) => result && !result.external ? [result.id] : []))];
 			};
-			let [staticEdges, dynamicEdges] = await Promise.all([resolveAll(specifiers.static), resolveAll(specifiers.dynamic)]);
-			environmentEdges(graph, name).set(id, {
+			let specifiers = importSpecifiers(code);
+			let usage = state.serverEnvironments.includes(name) ? scanResolverUsage(code, id) : void 0;
+			let [staticEdges, dynamicEdges, linkedUsage] = await Promise.all([
+				resolveAll(specifiers.static),
+				resolveAll(specifiers.dynamic),
+				usage && linkResolverUsage(usage, resolve)
+			]);
+			if ((invalidated?.get(id) ?? 0) > started) return;
+			recordTransform(name, id, {
 				static: staticEdges,
 				dynamic: dynamicEdges
-			});
-			if (!state.serverEnvironments.includes(name)) return;
-			let modules = graph.resolverUsage.get(name);
-			if (!modules) graph.resolverUsage.set(name, modules = /* @__PURE__ */ new Map());
-			let usage = scanResolverUsage(code, id);
-			if (!usage) return void modules.delete(id);
-			modules.set(id, await linkResolverUsage(usage, (specifier) => this.resolve(specifier, id)));
+			}, linkedUsage);
 		} },
 		hotUpdate: {
 			order: "post",
@@ -868,9 +1296,9 @@ function assetDevelopment(state) {
 				}
 				let name = this.environment.name;
 				let ids = modules.flatMap((module) => module.id ? [module.id] : []);
-				for (let [serverName, snapshot] of snapshots) {
-					let tracked = name === serverName ? snapshot.server : name === "client" ? snapshot.client : void 0;
-					if (tracked && (tracked.has(path) || ids.some((id) => tracked.has(id)))) invalidate(serverName, timestamp);
+				for (let serverName of snapshots.keys()) {
+					let set = tracked(name, serverName);
+					if (set && (set.has(path) || ids.some((id) => set.has(id)))) invalidate(serverName, timestamp);
 				}
 			}
 		}
@@ -878,7 +1306,17 @@ function assetDevelopment(state) {
 }
 //#endregion
 //#region src/vite-plugin.ts
+/**
+* The Vite plugins that give `@pitlane/assets` its manifest: they serve
+* browser entries during `vite dev`, emit them in a build, and replace
+* `@pitlane/assets/manifest` with the manifest of the current dev server or
+* build. Setting `allowFiles` also enforces the browser boundary.
+*
+* @throws When `allowPackages` or `denyFiles` is set without `allowFiles`.
+*/
 function assets(options = {}) {
+	let { allowFiles, allowPackages, denyFiles } = options;
+	if (!allowFiles && (allowPackages || denyFiles)) throw new Error("[assets] allowPackages and denyFiles refine allowFiles. Set allowFiles to turn on the browser boundary.");
 	let state = {
 		serverEnvironments: options.serverEnvironments ?? ["ssr"],
 		inputs: /* @__PURE__ */ new Map(),
@@ -961,8 +1399,13 @@ function assets(options = {}) {
 		},
 		assetBuild(state),
 		assetDevelopment(state),
-		assetStyles()
+		assetStyles(),
+		allowFiles && browserBoundary({
+			allowFiles,
+			allowPackages,
+			denyFiles
+		}, state.serverEnvironments)
 	];
 }
 //#endregion
-export { assets };
+export { ASSETS_MANIFEST_FILE, assets };

package/package.json

@@ -1,76 +1,74 @@
 {
-    "name": "@pitlane/assets",
-    "version": "0.1.0",
-    "description": "Framework-neutral asset resolution for bundled applications.",
-    "keywords": [
-        "assets",
-        "import-map",
-        "manifest",
-        "modulepreload",
-        "pitlane",
-        "vite",
-        "vite-plugin"
-    ],
-    "homepage": "https://pitlane.tools/package/assets/",
-    "bugs": {
-        "url": "https://github.com/pitlane-tools/pitlane/issues"
+  "name": "@pitlane/assets",
+  "version": "0.2.0",
+  "description": "Framework-neutral asset resolution for bundled applications.",
+  "keywords": [
+    "assets",
+    "import-map",
+    "manifest",
+    "modulepreload",
+    "pitlane",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://pitlane.tools/package/assets/",
+  "bugs": {
+    "url": "https://github.com/pitlane-tools/pitlane/issues"
+  },
+  "license": "MIT",
+  "author": "Mark Malstrom <mark@malstrom.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pitlane-tools/pitlane.git",
+    "directory": "packages/assets"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE.upstream"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
-    "license": "MIT",
-    "author": "Mark Malstrom <mark@malstrom.me>",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/pitlane-tools/pitlane.git",
-        "directory": "packages/assets"
+    "./manifest": {
+      "types": "./dist/manifest.d.mts",
+      "import": "./dist/manifest.mjs"
     },
-    "files": [
-        "dist",
-        "CHANGELOG.md",
-        "LICENSE.upstream"
-    ],
-    "type": "module",
-    "types": "./dist/index.d.mts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.mts",
-            "import": "./dist/index.mjs"
-        },
-        "./manifest": {
-            "types": "./dist/manifest.d.mts",
-            "import": "./dist/manifest.mjs"
-        },
-        "./build": {
-            "types": "./dist/build.d.mts",
-            "import": "./dist/build.mjs"
-        },
-        "./vite-plugin": {
-            "types": "./dist/vite-plugin.d.mts",
-            "import": "./dist/vite-plugin.mjs"
-        }
+    "./build": {
+      "types": "./dist/build.d.mts",
+      "import": "./dist/build.mjs"
     },
-    "scripts": {
-        "prepublishOnly": "vp run build"
-    },
-    "dependencies": {
-        "magic-string": "^0.30.21"
-    },
-    "devDependencies": {
-        "@types/node": "^25.5.0",
-        "fast-check": "4.10.2",
-        "playwright": "1.61.1",
-        "remix": "3.0.0",
-        "typescript": "^7.0.2",
-        "vite": "npm:@voidzero-dev/vite-plus-core@^1.0.0",
-        "vite-plus": "^1.0.0"
-    },
-    "peerDependencies": {
-        "vite": ">=8.1.0"
-    },
-    "peerDependenciesMeta": {
-        "vite": {
-            "optional": true
-        }
-    },
-    "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.mts",
+      "import": "./dist/vite-plugin.mjs"
+    }
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "fast-check": "4.10.2",
+    "playwright": "1.61.1",
+    "remix": "3.0.0",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^1.0.0",
+    "vite-plus": "^1.0.0"
+  },
+  "peerDependencies": {
+    "vite": ">=8.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
     }
-}
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {}
+}