@pitlane/assets 0.0.0-stage → 0.2.0

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 };

package/dist/types-DlTsImzF.d.mts

@@ -0,0 +1,106 @@
+//#region src/types.d.ts
+/**
+ * An import map as the HTML standard defines it: specifier mappings, optional
+ * scoped mappings, and optional integrity metadata.
+ */
+interface ImportMap {
+  imports: Record<string, string>;
+  scopes?: Record<string, Record<string, string>>;
+  integrity?: Record<string, string>;
+}
+/**
+ * What a browser needs to load one script entry: its URL, the URLs worth
+ * `modulepreload` hints, and the import map its imports resolve through.
+ *
+ * Structurally the `ScriptEntry` of `remix/assets`.
+ */
+interface ScriptEntry {
+  /** The public URL of the entry module. */
+  href: string;
+  /** The entry module's URL followed by its static JavaScript dependencies, shallowest first. */
+  preloads: string[];
+  /** The complete client import map, or `{ imports: {} }` when chunk import maps are disabled. */
+  importMap: ImportMap;
+}
+/** The JavaScript and CSS one source module requires in one environment. */
+interface AssetMetadata {
+  /** Public URLs of the chunks holding the module and their static JavaScript dependencies. */
+  preloads: string[];
+  /** Public URLs of the stylesheets those chunks require. */
+  stylesheets: string[];
+}
+/** Every source module observed in one environment's graph, keyed by portable source key. */
+interface AssetEnvironment {
+  role: "client" | "server";
+  modules: Record<string, AssetMetadata>;
+}
+/** The manifest a production build produces. */
+interface BuildAssetsManifest {
+  mode: "build";
+  environments: Record<string, AssetEnvironment>;
+  /** Browser-entry source keys mapped to public URLs. */
+  entries: Record<string, string>;
+  /** Non-script asset source keys mapped to public URLs. */
+  assets: Record<string, string>;
+  importMap: ImportMap;
+  /** The server environment this manifest was written for. */
+  serverEnvironment?: string;
+}
+/** The manifest a development server supplies, refreshed as the graph changes. */
+interface DevAssetsManifest {
+  mode: "dev";
+  environments: Record<string, AssetEnvironment>;
+  /** Browser-entry source keys mapped to development URLs. */
+  entries: Record<string, string>;
+  /** Non-script asset source keys mapped to development URLs. */
+  assets: Record<string, string>;
+  /** The server environment this manifest was written for. */
+  serverEnvironment?: string;
+}
+/**
+ * Everything `createAssetResolver` accepts. `{ mode: "unavailable" }` is
+ * what `@pitlane/assets/manifest` exports when no build integration replaced it.
+ */
+type AssetsManifest = BuildAssetsManifest | DevAssetsManifest | {
+  mode: "unavailable";
+};
+/**
+ * A bundler's output, normalized for `createAssetManifest`.
+ *
+ * Paths and filenames are already portable: source keys are relative to the
+ * project root, and `file`/`stylesheets` are emitted filenames relative to
+ * `base` or absolute public URLs.
+ */
+interface AssetBuild {
+  /** The public base relative emitted filenames resolve against, such as `/` or `https://cdn.example/app/`. */
+  base: string;
+  /** Every participating environment by name. Exactly one has the client role. */
+  environments: Record<string, AssetBuildEnvironment>;
+  /** The import map the bundler generated for the client build, when it generated one. */
+  importMap?: ImportMap;
+}
+/** One environment's output graph. */
+interface AssetBuildEnvironment {
+  role: "client" | "server";
+  /** Emitted chunks by opaque, environment-local identity. */
+  chunks: Record<string, AssetBuildChunk>;
+  /** Browser-entry source keys mapped to chunk identities. Populated only on the client. */
+  entries: Record<string, string>;
+  /** Source keys mapped to emitted non-script files. */
+  assets: Record<string, string>;
+}
+/** One emitted JavaScript chunk. */
+interface AssetBuildChunk {
+  /** The emitted filename, or an absolute public URL. */
+  file: string;
+  /** Source keys of every module the chunk contains. */
+  modules: string[];
+  /** Chunk identities this chunk imports statically, in import order. */
+  imports: string[];
+  /** Chunk identities this chunk imports dynamically. */
+  dynamicImports: string[];
+  /** Emitted stylesheet filenames, or absolute public URLs, the chunk requires. */
+  stylesheets: string[];
+}
+//#endregion
+export { AssetMetadata as a, DevAssetsManifest as c, AssetEnvironment as i, ImportMap as l, AssetBuildChunk as n, AssetsManifest as o, AssetBuildEnvironment as r, BuildAssetsManifest as s, AssetBuild as t, ScriptEntry as u };

package/dist/vite-plugin.d.mts

@@ -0,0 +1,58 @@
+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[];
+  /** Server environments whose module graphs provide metadata. Defaults to `["ssr"]`. */
+  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 {
+  /** The server environment that transformed the owner. */
+  environment: string;
+  /** The resolved server module ID declaring these entries. */
+  owner: string;
+  /** Resolved browser module IDs; an empty list removes the owner's declarations. */
+  entries: string[];
+}
+/** Available on the resolved plugin named `pitlane-assets`. */
+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