@pitlane/assets 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @pitlane/assets
+
+## 0.1.0
+
+### Minor Changes
+
+- 3053134: New package: framework-neutral asset resolution for server-rendered apps.
+
+    `createAssetResolver(manifest)` resolves source paths such as `app/entry.browser.ts` or `file:app/counter.tsx#Counter` to the URLs the current Vite dev server or build produced. Its `getScriptEntry`, `getHref`, `getPreloads`, `getStylesheets`, and `getImportMap` methods return script URLs, `modulepreload` hints, stylesheet lists, and the client import map. The resolver matches the asset server from `remix/assets`, so it can be passed to Remix's `render({ assets })`, and imports no framework, so any other renderer can use it too. Looking up a server module's stylesheets never compiles that module for the browser.
+
+    `@pitlane/assets/manifest` is the manifest the `assets()` Vite plugin from `@pitlane/assets/vite-plugin` supplies. Published as is, it is `{ mode: "unavailable" }`, and every lookup explains how to supply one. `@pitlane/assets/build` exports `createAssetManifest`, which turns another bundler's normalized output into the same manifest.
+
+    Generated manifests preserve source keys and environment names through JSON serialization, including names such as `__proto__`.
+
+    Chunk import maps are off by default. With `assets({ chunkImportMap: true })`, `renderImportMap({ value, nonce })` serializes the returned map into a `<script type="importmap">` string that delivers it safely. The Vite plugin requires Vite 8.1 or later.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Malstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.upstream

@@ -0,0 +1,23 @@
+CSS development integration includes adaptations from @hiogawa/vite-plugin-fullstack.
+
+MIT License
+
+Copyright (c) 2024 Hiroshi Ogawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @pitlane/assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-neutral asset resolution for server-rendered apps built with Vite or another bundler.
+
+A server-rendered page has to name its browser entry script, its stylesheets, `modulepreload` hints, and the chunks of the islands it hydrates. Those URLs differ between `vite dev` and a production build. This package resolves source paths such as `app/entry.browser.ts` to the URLs the current dev server or build produced, through a resolver you construct from a manifest. The runtime imports no framework and no bundler. Its methods match the asset server from `remix/assets`, so it can be passed to Remix's `render({ assets })`. React, Preact, Vue, and plain HTML renderers use the returned strings directly.
+
+```sh
+npm install @pitlane/assets
+```
+
+Requires Node `^20.19.0 || >=22.12.0`. Install it as a runtime dependency, since application code imports the resolver. `vite` 8.1 or newer is an optional peer dependency, needed only for `@pitlane/assets/vite-plugin`.
+
+| Entry point                   | Contents                                                         |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `@pitlane/assets`             | `createAssetResolver`, `renderImportMap`, and the manifest types |
+| `@pitlane/assets/manifest`    | The manifest a build integration supplies                        |
+| `@pitlane/assets/build`       | `createAssetManifest`, for integrations with other bundlers      |
+| `@pitlane/assets/vite-plugin` | `assets()`, the Vite integration                                 |
+
+## Usage
+
+Add the plugin to your Vite config:
+
+```ts
+// vite.config.ts
+import { assets } from "@pitlane/assets/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [assets()],
+});
+```
+
+Construct the resolver once, from the manifest the plugin supplies:
+
+```ts
+// app/assets.ts
+import { createAssetResolver } from "@pitlane/assets";
+import manifest from "@pitlane/assets/manifest";
+
+export let assets = createAssetResolver(manifest);
+
+export let scriptEntry = await assets.getScriptEntry("app/entry.browser.ts");
+export let stylesheets = await assets.getStylesheets("app/entry.server.ts");
+```
+
+`scriptEntry` is `{ href, preloads, importMap }`: the entry's URL, its chunk and static JavaScript dependencies for `modulepreload` links, and the client import map. Under `vite dev`, `href` is the dev URL, `preloads` is empty, and the map is `{ imports: {} }`.
+
+Keys are paths from the project root. `./app/x.ts`, `/app/x.ts`, `file:app/x.ts`, and `app/x.ts#Export` all name `app/x.ts`, and a module outside the root keeps its leading `../`. A string literal passed to a resolver's `getScriptEntry` or `getHref` in server code registers that module as a browser input: a script entry for `getScriptEntry`, an emitted asset for `getHref`. The receiver must be the result of `createAssetResolver()` imported from `@pitlane/assets` or `pitlane/assets`, a top-level variable holding one, or such a variable copied, imported, renamed, re-exported (including through `export *`), or default-exported from another module. Each such name must be declared only once in its module. A namespace import, a function parameter, `this`, another object's same-named method, a same-named function from another module, or a resolver imported from a dependency Vite externalizes registers nothing. List computed paths, and keys called through those receivers, in `assets({ include: [...] })`.
+
+| Method | Returns |
+| --- | --- |
+| `getScriptEntry(key)` | `{ href, preloads, importMap }` for a browser entry |
+| `getHref(key)` | The URL of a browser entry, stylesheet, or other asset |
+| `getPreloads(key \| key[])` | `modulepreload` URLs for scripts, and the URL of an explicitly requested stylesheet |
+| `getStylesheets(key \| key[])` | Stylesheets the modules need, from the client graph and the current server graph |
+| `getImportMap(key \| key[])` | The complete client import map |
+
+Looking up a module's stylesheets never compiles it for the browser, so `getStylesheets("app/entry.server.ts")` is safe for server code.
+
+## Chunk import maps
+
+Off by default. `assets({ chunkImportMap: true })` enables Vite's chunk import maps for the client build, so a dependency's new hash changes one map entry instead of every importing chunk. Deliver the map before any `modulepreload` link or module script. `renderImportMap({ value, nonce })` returns it as a `<script type="importmap">` string, with every `<` escaped so the map cannot close the element, or `""` when the map is empty:
+
+```ts
+import { renderImportMap } from "@pitlane/assets";
+
+let html = renderImportMap({ value: scriptEntry.importMap });
+```
+
+The option requires browser support for import maps and `import.meta.resolve`, and cannot be combined with Vite's `experimental.renderBuiltUrl`.
+
+## Without Vite
+
+As published, `@pitlane/assets/manifest` exports `{ mode: "unavailable" }`. A resolver built from it constructs normally and rejects every lookup with instructions for supplying a manifest, so tests and type checkers can import your `app/assets.ts`.
+
+Other bundlers produce a manifest with `createAssetManifest(build)` from `@pitlane/assets/build`. It takes a normalized description of the emitted chunks, their modules, static and dynamic imports, and stylesheets, and computes preloads, stylesheet lists, and public URLs:
+
+```ts
+import { createAssetManifest } from "@pitlane/assets/build";
+import { createAssetResolver } from "@pitlane/assets";
+
+let manifest = createAssetManifest({
+    base: "/",
+    environments: {
+        client: {
+            role: "client",
+            chunks: {
+                main: {
+                    file: "assets/main-a1.js",
+                    modules: ["src/main.ts"],
+                    imports: [],
+                    dynamicImports: [],
+                    stylesheets: ["assets/main-b2.css"],
+                },
+            },
+            entries: { "src/main.ts": "main" },
+            assets: {},
+        },
+    },
+});
+
+let assets = createAssetResolver(manifest);
+await assets.getScriptEntry("src/main.ts");
+// { href: "/assets/main-a1.js", preloads: ["/assets/main-a1.js"], importMap: { imports: {} } }
+```
+
+## Documentation
+
+- [Asset resolution](https://pitlane.tools/guides/assets): resolver methods, source keys, registration, Remix and non-Remix documents, chunk import maps, and errors.
+- [Manifest integrations](https://pitlane.tools/guides/asset-build): the `createAssetManifest` input model for integration authors.
+
+## License
+
+MIT

package/dist/build-BbA-Zq1m.mjs

@@ -0,0 +1,161 @@
+import { n as quotedList, r as normalizeSourceKey } from "./specifier-DLC81sXY.mjs";
+//#region src/generate.ts
+const CHUNK_LISTS = [
+	"modules",
+	"imports",
+	"dynamicImports",
+	"stylesheets"
+];
+/**
+* Converts a bundler's normalized output into the manifest
+* `createAssetResolver` reads.
+*
+* It walks each environment's static chunk graph to record, for every source
+* module, its `modulepreload` URLs (its chunk first, then dependencies
+* shallowest first) and stylesheets (a dependency's before its importer's).
+* Dynamic imports are validated and never followed. It reads no files,
+* invents no edges, and generates no import map; `serverEnvironment` is left
+* for the integration to set per server.
+*
+* @throws When there is not exactly one client environment, an edge or entry
+* names a missing chunk, a chunk lacks one of its lists, a server environment
+* lists entries, a source key is an absolute file URL, or one source key maps
+* to two URLs.
+*/
+function createAssetManifest(build) {
+	let clients = Object.keys(build.environments).filter((name) => build.environments[name].role === "client");
+	if (clients.length !== 1) {
+		let found = clients.length === 0 ? "none" : quotedList(clients, "conjunction");
+		throw new Error(`createAssetManifest() needs exactly one client environment; found ${found}.`);
+	}
+	let publicUrl = (file) => resolvePublicUrl(build.base, file);
+	let environments = Object.create(null);
+	let entries = new SourceIndex();
+	let assets = new SourceIndex();
+	for (let [name, environment] of Object.entries(build.environments)) {
+		validateEnvironment(name, environment);
+		let entryChunks = /* @__PURE__ */ new Map();
+		for (let [rawKey, chunkId] of Object.entries(environment.entries)) {
+			let key = sourceKey(name, rawKey);
+			entries.record(key, publicUrl(environment.chunks[chunkId].file), name);
+			entryChunks.set(key, chunkId);
+		}
+		for (let [rawKey, file] of Object.entries(environment.assets)) assets.record(sourceKey(name, rawKey), publicUrl(file), name);
+		environments[name] = {
+			role: environment.role,
+			modules: indexModules(name, environment, entryChunks, publicUrl)
+		};
+	}
+	return {
+		mode: "build",
+		environments,
+		entries: entries.urls,
+		assets: assets.urls,
+		importMap: build.importMap ?? { imports: {} }
+	};
+}
+function validateEnvironment(name, environment) {
+	let { chunks } = environment;
+	let where = (chunkId) => `chunk "${chunkId}" in the "${name}" environment`;
+	for (let [chunkId, chunk] of Object.entries(chunks)) {
+		if (typeof chunk.file !== "string") throw new Error(`createAssetManifest(): ${where(chunkId)} has no file.`);
+		for (let list of CHUNK_LISTS) if (!Array.isArray(chunk[list])) throw new Error(`createAssetManifest(): ${where(chunkId)} has no ${list} list.`);
+	}
+	for (let [chunkId, chunk] of Object.entries(chunks)) {
+		let edges = [...chunk.imports.map((target) => ["imports", target]), ...chunk.dynamicImports.map((target) => ["dynamically imports", target])];
+		for (let [verb, target] of edges) if (!Object.hasOwn(chunks, target)) throw new Error(`createAssetManifest(): ${where(chunkId)} ${verb} "${target}", which is not a chunk in that environment.`);
+	}
+	let entryKeys = Object.keys(environment.entries);
+	if (environment.role === "server" && entryKeys.length > 0) throw new Error(`createAssetManifest(): the "${name}" environment lists browser entries, but only the client environment has them.`);
+	for (let key of entryKeys) {
+		let chunkId = environment.entries[key];
+		if (!Object.hasOwn(chunks, chunkId)) throw new Error(`createAssetManifest(): browser entry "${key}" in the "${name}" environment names chunk "${chunkId}", which is not a chunk in that environment.`);
+	}
+}
+/**
+* Every source module's metadata: the union over each chunk it belongs to,
+* with a browser entry's own chunk first so its preloads lead with its URL.
+*/
+function indexModules(name, environment, entryChunks, publicUrl) {
+	let memberships = /* @__PURE__ */ new Map();
+	let join = (key, chunkId) => {
+		let chunkIds = memberships.get(key) ?? [];
+		if (!chunkIds.includes(chunkId)) chunkIds.push(chunkId);
+		memberships.set(key, chunkIds);
+	};
+	for (let [key, chunkId] of entryChunks) join(key, chunkId);
+	for (let [chunkId, chunk] of Object.entries(environment.chunks)) for (let rawKey of chunk.modules) join(sourceKey(name, rawKey), chunkId);
+	let closures = /* @__PURE__ */ new Map();
+	let closureOf = (chunkId) => {
+		let closure = closures.get(chunkId) ?? staticClosure(environment.chunks, chunkId, publicUrl);
+		closures.set(chunkId, closure);
+		return closure;
+	};
+	let modules = Object.create(null);
+	for (let [key, chunkIds] of memberships) {
+		let preloads = /* @__PURE__ */ new Set();
+		let stylesheets = /* @__PURE__ */ new Set();
+		for (let closure of chunkIds.map(closureOf)) {
+			for (let href of closure.preloads) preloads.add(href);
+			for (let href of closure.stylesheets) stylesheets.add(href);
+		}
+		modules[key] = {
+			preloads: [...preloads],
+			stylesheets: [...stylesheets]
+		};
+	}
+	return modules;
+}
+/**
+* The chunks reachable from `root` through static imports. Preloads are in
+* breadth-first order, so shallower chunks come first; stylesheets are in
+* post-order, so a dependency's styles precede its importer's, matching the
+* order the modules evaluate. Each chunk is visited once, which ends cycles.
+*/
+function staticClosure(chunks, root, publicUrl) {
+	let order = [root];
+	let queued = new Set(order);
+	for (let index = 0; index < order.length; index++) for (let dependency of chunks[order[index]].imports) {
+		if (queued.has(dependency)) continue;
+		queued.add(dependency);
+		order.push(dependency);
+	}
+	let stylesheets = /* @__PURE__ */ new Set();
+	let visited = /* @__PURE__ */ new Set();
+	let visit = (chunkId) => {
+		if (visited.has(chunkId)) return;
+		visited.add(chunkId);
+		let chunk = chunks[chunkId];
+		for (let dependency of chunk.imports) visit(dependency);
+		for (let file of chunk.stylesheets) stylesheets.add(publicUrl(file));
+	};
+	visit(root);
+	return {
+		preloads: [...new Set(order.map((chunkId) => publicUrl(chunks[chunkId].file)))],
+		stylesheets: [...stylesheets]
+	};
+}
+function sourceKey(environment, rawKey) {
+	let key = normalizeSourceKey(rawKey);
+	if (key !== null) return key;
+	throw new Error(`createAssetManifest(): source key "${rawKey}" in the "${environment}" environment is an absolute file URL. Normalize it to a path relative to the project root.`);
+}
+/** `key → url` across environments, rejecting a second, different URL for one key. */
+var SourceIndex = class {
+	urls = Object.create(null);
+	#environments = Object.create(null);
+	record(key, url, environment) {
+		let existing = Object.hasOwn(this.urls, key) ? this.urls[key] : void 0;
+		if (existing !== void 0 && existing !== url) throw new Error(`createAssetManifest(): source key "${key}" maps to "${existing}" in the "${this.#environments[key]}" environment and "${url}" in the "${environment}" environment.`);
+		this.urls[key] = url;
+		this.#environments[key] = environment;
+	}
+};
+/** Absolute URLs (`/x`, `//host/x`, `https://…`) stay as they are; relative files join the base. */
+function resolvePublicUrl(base, file) {
+	if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(file)) return file;
+	if (base === "" || base.endsWith("/")) return base + file;
+	return `${base}/${file}`;
+}
+//#endregion
+export { createAssetManifest as t };

package/dist/build.d.mts

@@ -0,0 +1,21 @@
+import { a as AssetMetadata, i as AssetEnvironment, l as ImportMap, n as AssetBuildChunk, r as AssetBuildEnvironment, s as BuildAssetsManifest, t as AssetBuild } from "./types-DlTsImzF.mjs";
+//#region src/generate.d.ts
+/**
+ * Converts a bundler's normalized output into the manifest
+ * `createAssetResolver` reads.
+ *
+ * It walks each environment's static chunk graph to record, for every source
+ * module, its `modulepreload` URLs (its chunk first, then dependencies
+ * shallowest first) and stylesheets (a dependency's before its importer's).
+ * Dynamic imports are validated and never followed. It reads no files,
+ * invents no edges, and generates no import map; `serverEnvironment` is left
+ * for the integration to set per server.
+ *
+ * @throws When there is not exactly one client environment, an edge or entry
+ * names a missing chunk, a chunk lacks one of its lists, a server environment
+ * lists entries, a source key is an absolute file URL, or one source key maps
+ * to two URLs.
+ */
+export declare function createAssetManifest(build: AssetBuild): BuildAssetsManifest;
+//#endregion
+export type { AssetBuild, AssetBuildChunk, AssetBuildEnvironment, AssetEnvironment, AssetMetadata, BuildAssetsManifest, ImportMap };

package/dist/build.mjs

@@ -0,0 +1,2 @@
+import { t as createAssetManifest } from "./build-BbA-Zq1m.mjs";
+export { createAssetManifest };

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { a as AssetMetadata, c as DevAssetsManifest, i as AssetEnvironment, l as ImportMap, o as AssetsManifest, s as BuildAssetsManifest, u as ScriptEntry } from "./types-DlTsImzF.mjs";
+//#region src/resolver.d.ts
+/**
+ * Resolves portable source keys, such as `app/entry.browser.ts` or
+ * `file:app/counter.tsx#Counter`, to the URLs a build or development server
+ * produced for them.
+ *
+ * Structurally compatible with the resolution methods of a `remix/assets`
+ * asset server, so it can be passed to `render({ assets })`.
+ */
+interface AssetResolver {
+  /** A registered browser entry's URL, `modulepreload` URLs, and the client import map. */
+  getScriptEntry(path: string): Promise<ScriptEntry>;
+  /** The URL of a registered browser entry, stylesheet, or other asset. */
+  getHref(path: string): Promise<string>;
+  /** Scripts' chunks and static JavaScript dependencies, and explicitly requested stylesheets. */
+  getPreloads(path: string | readonly string[]): Promise<string[]>;
+  /** Stylesheets the modules need, from the client graph and the current server graph. */
+  getStylesheets(path: string | readonly string[]): Promise<string[]>;
+  /** The complete client import map, after checking the keys belong to the client graph. */
+  getImportMap(path: string | readonly string[]): Promise<ImportMap>;
+}
+/**
+ * Constructs the resolver for a manifest, usually the default export of
+ * `@pitlane/assets/manifest`. Construct it once, in a module of the app's own.
+ */
+export declare function createAssetResolver(manifest: AssetsManifest): AssetResolver;
+//#endregion
+//#region src/import-map.d.ts
+/** Options for {@link renderImportMap}. */
+interface RenderImportMapOptions {
+  /** The map to serialize, such as `ScriptEntry.importMap`. */
+  value: ImportMap;
+  /** A nonce from the application's existing Content Security Policy. */
+  nonce?: string;
+}
+/**
+ * Serializes an import map into an inline `<script type="importmap">` element
+ * for server-rendered HTML, or `""` when the map has no mappings.
+ *
+ * Every `<` in the JSON is written as `\u003c`, so no key or URL can end the
+ * script element; the browser parses the same strings back. The nonce is
+ * written as an escaped, quoted attribute. Place the result before any
+ * `modulepreload` link or module script.
+ */
+export declare function renderImportMap({ value, nonce }: RenderImportMapOptions): string;
+//#endregion
+export type { AssetEnvironment, AssetMetadata, AssetResolver, AssetsManifest, BuildAssetsManifest, DevAssetsManifest, ImportMap, RenderImportMapOptions, ScriptEntry };

package/dist/index.mjs

@@ -0,0 +1,146 @@
+import { n as quotedList, r as normalizeSourceKey, t as assetsSpecifier } from "./specifier-DLC81sXY.mjs";
+//#region src/resolver.ts
+/**
+* Constructs the resolver for a manifest, usually the default export of
+* `@pitlane/assets/manifest`. Construct it once, in a module of the app's own.
+*/
+function createAssetResolver(manifest) {
+	if (manifest.mode === "unavailable") return unavailableResolver();
+	return manifestResolver(manifest);
+}
+function unavailableResolver() {
+	let fail = (method) => async (path) => {
+		throw new Error(`${call(method, path)} has no asset manifest to read: ${assetsSpecifier("manifest")} was not supplied by a build integration. Add assets() from ${assetsSpecifier("vite-plugin")} to your Vite config, or pass createAssetResolver() a manifest from createAssetManifest() in ${assetsSpecifier("build")}.`);
+	};
+	return {
+		getScriptEntry: fail("getScriptEntry"),
+		getHref: fail("getHref"),
+		getPreloads: fail("getPreloads"),
+		getStylesheets: fail("getStylesheets"),
+		getImportMap: fail("getImportMap")
+	};
+}
+function manifestResolver(manifest) {
+	let { environments, entries, assets } = manifest;
+	let clientName = Object.keys(environments).find((name) => environments[name].role === "client") ?? "client";
+	let stylesheetEnvironments = [.../* @__PURE__ */ new Set([clientName, manifest.serverEnvironment ?? clientName])];
+	/** The client graph's metadata for a key, which a registered entry always has. */
+	function clientMetadata(key) {
+		let metadata = own(environments[clientName]?.modules ?? {}, key);
+		if (metadata) return metadata;
+		let href = own(entries, key);
+		return href === void 0 ? void 0 : {
+			preloads: [href],
+			stylesheets: []
+		};
+	}
+	function requireClientMetadata(method, path, key) {
+		let metadata = clientMetadata(key);
+		if (metadata) return metadata;
+		throw new Error(`${call(method, path)} found no module "${key}" in the "${clientName}" environment's graph.`);
+	}
+	function missingRegistration(method, path, key, what) {
+		let observedIn = Object.keys(environments).find((name) => Object.hasOwn(environments[name].modules, key));
+		let observation = observedIn ? `The module is in the "${observedIn}" graph but is not registered as a browser entry.` : "No environment's graph contains the module.";
+		return /* @__PURE__ */ new Error(`${call(method, path)} found no ${what} "${key}" in the "${clientName}" environment. ${observation} Pass the key to ${method}() as a string literal in server code, or list it in assets({ include }) from ${assetsSpecifier("vite-plugin")}.`);
+	}
+	return {
+		async getScriptEntry(path) {
+			let key = sourceKey("getScriptEntry", path);
+			let href = own(entries, key);
+			if (href === void 0) throw missingRegistration("getScriptEntry", path, key, "browser entry");
+			if (manifest.mode === "dev") return {
+				href,
+				preloads: [],
+				importMap: { imports: {} }
+			};
+			return {
+				href,
+				preloads: [...clientMetadata(key).preloads],
+				importMap: copyImportMap(manifest.importMap)
+			};
+		},
+		async getHref(path) {
+			let key = sourceKey("getHref", path);
+			let href = own(entries, key) ?? own(assets, key);
+			if (href === void 0) throw missingRegistration("getHref", path, key, "browser entry or asset");
+			return href;
+		},
+		async getPreloads(paths) {
+			let preloads = /* @__PURE__ */ new Set();
+			for (let path of asList(paths)) {
+				let key = sourceKey("getPreloads", path);
+				let stylesheet = own(assets, key);
+				if (stylesheet !== void 0 && /\.css(?:[?#]|$)/.test(stylesheet)) {
+					preloads.add(stylesheet);
+					continue;
+				}
+				for (let href of requireClientMetadata("getPreloads", path, key).preloads) preloads.add(href);
+			}
+			return manifest.mode === "dev" ? [] : [...preloads];
+		},
+		async getStylesheets(paths) {
+			let stylesheets = /* @__PURE__ */ new Set();
+			for (let path of asList(paths)) {
+				let key = sourceKey("getStylesheets", path);
+				let found = stylesheetEnvironments.flatMap((name) => {
+					let graph = own(environments, name);
+					return (graph && own(graph.modules, key)) ?? [];
+				});
+				if (found.length === 0) throw new Error(`${call("getStylesheets", path)} found no module "${key}" in the ${quotedList(stylesheetEnvironments, "disjunction")} environment's graph.`);
+				for (let href of found.flatMap((metadata) => metadata.stylesheets)) stylesheets.add(href);
+			}
+			return [...stylesheets];
+		},
+		async getImportMap(paths) {
+			let list = asList(paths);
+			for (let path of list) requireClientMetadata("getImportMap", path, sourceKey("getImportMap", path));
+			if (list.length === 0 || manifest.mode === "dev") return { imports: {} };
+			return copyImportMap(manifest.importMap);
+		}
+	};
+}
+/** Reads a source key's record without reaching `Object.prototype` members such as `constructor`. */
+function own(record, key) {
+	return Object.hasOwn(record, key) ? record[key] : void 0;
+}
+/** Callers merge their own mappings into the returned map; the manifest's stays intact. */
+function copyImportMap(map) {
+	return structuredClone(map);
+}
+function sourceKey(method, path) {
+	let key = normalizeSourceKey(path);
+	if (key !== null) return key;
+	throw new Error(`${call(method, path)} received an absolute file URL. Pass the source key relative to the project root instead, such as "file:app/counter.tsx" or "app/counter.tsx".`);
+}
+function asList(paths) {
+	return typeof paths === "string" ? [paths] : paths;
+}
+/** How a message names the call that failed, such as `assets.getHref("app/logo.svg")`. */
+function call(method, path) {
+	return `assets.${method}(${JSON.stringify(path)})`;
+}
+//#endregion
+//#region src/import-map.ts
+/**
+* Serializes an import map into an inline `<script type="importmap">` element
+* for server-rendered HTML, or `""` when the map has no mappings.
+*
+* Every `<` in the JSON is written as `\u003c`, so no key or URL can end the
+* script element; the browser parses the same strings back. The nonce is
+* written as an escaped, quoted attribute. Place the result before any
+* `modulepreload` link or module script.
+*/
+function renderImportMap({ value, nonce }) {
+	if (!hasMappings(value)) return "";
+	let json = JSON.stringify(value).replaceAll("<", "\\u003c");
+	return `<script type="importmap"${nonce === void 0 ? "" : ` nonce="${escapeAttribute(nonce)}"`}>${json}<\/script>`;
+}
+function hasMappings({ imports, scopes = {}, integrity = {} }) {
+	return Object.keys(imports).length > 0 || Object.values(scopes).some((scope) => Object.keys(scope).length > 0) || Object.keys(integrity).length > 0;
+}
+function escapeAttribute(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+//#endregion
+export { createAssetResolver, renderImportMap };

package/dist/manifest.d.mts

@@ -0,0 +1,17 @@
+import { o as AssetsManifest } from "./types-DlTsImzF.mjs";
+//#region src/manifest.d.ts
+/**
+ * The manifest `@pitlane/assets/manifest` exports when no build integration
+ * replaced the module. A resolver constructed from it works, and every lookup
+ * explains how to supply a real manifest.
+ *
+ * `assets()` from `@pitlane/assets/vite-plugin` replaces this module with the
+ * manifest of the current dev server or build. A graph Vite did not build can
+ * alias the module to its own, or pass a manifest to `createAssetResolver`
+ * directly.
+ *
+ * @module @pitlane/assets/manifest
+ */
+declare let manifest: AssetsManifest;
+//#endregion
+export { manifest as default };

package/dist/manifest.mjs

@@ -0,0 +1,16 @@
+//#region src/manifest.ts
+/**
+* The manifest `@pitlane/assets/manifest` exports when no build integration
+* replaced the module. A resolver constructed from it works, and every lookup
+* explains how to supply a real manifest.
+*
+* `assets()` from `@pitlane/assets/vite-plugin` replaces this module with the
+* manifest of the current dev server or build. A graph Vite did not build can
+* alias the module to its own, or pass a manifest to `createAssetResolver`
+* directly.
+*
+* @module @pitlane/assets/manifest
+*/
+let manifest = { mode: "unavailable" };
+//#endregion
+export { manifest as default };

package/dist/specifier-DLC81sXY.mjs

@@ -0,0 +1,47 @@
+//#region src/source-key.ts
+/**
+* Reduces any accepted spelling of a source module to its portable key: the
+* slash-separated path from the project root, such as `app/counter.tsx` or,
+* for a linked module outside the root, `../shared/widget.ts`.
+*
+* `./`, a leading `/` (a project-root marker), `file:`, and an `#export`
+* fragment are dropped, and dot segments collapse lexically. Returns `null`
+* for an absolute file URL, whose meaning depends on the machine that wrote
+* it.
+*/
+function normalizeSourceKey(path) {
+	let key = path;
+	let fragment = key.indexOf("#");
+	if (fragment !== -1) key = key.slice(0, fragment);
+	if (key.startsWith("file:")) {
+		key = key.slice(5);
+		if (key.startsWith("/")) return null;
+	}
+	let segments = [];
+	for (let segment of key.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === ".." && segments.length > 0 && segments.at(-1) !== "..") segments.pop();
+		else segments.push(segment);
+	}
+	return segments.join("/");
+}
+//#endregion
+//#region src/specifier.ts
+/**
+* Each module of the `pitlane` umbrella adds the package it re-exports to
+* this set when it loads, so a package can name itself the way the app
+* imports it. An app that installed only `pitlane` cannot import
+* `@pitlane/assets/vite-plugin` under a strict package manager.
+*/
+const UMBRELLA_PACKAGES = Symbol.for("pitlane.umbrella.packages");
+/** The specifier the app imports `subpath` of this package by, for error messages. */
+function assetsSpecifier(subpath) {
+	return `${globalThis[UMBRELLA_PACKAGES]?.has("@pitlane/assets") ? "pitlane/assets" : "@pitlane/assets"}/${subpath}`;
+}
+/** Quotes and joins names for a message: `"a"`, `"a" and "b"`, `"a", "b", and "c"`. */
+function quotedList(names, type) {
+	let quoted = names.map((name) => `"${name}"`);
+	return new Intl.ListFormat("en", { type }).format(quoted);
+}
+//#endregion
+export { quotedList as n, normalizeSourceKey as r, assetsSpecifier as t };