@remix-run/assets 0.5.0 → 0.6.0

package/README.md

@@ -6,9 +6,9 @@ Fetch-based server for compiling browser assets on demand.
 
 - **On-Demand Compilation** - Compile browser scripts and styles on demand
 - **File Serving** - Serve configured file assets like images and fonts with optional transforms
-- **Custom File Mapping** - Define patterns for mapping public URLs to file paths on disk
 - **Access Control** - Control exactly which files and packages can be served
 - **Preloads** - Generate preload URLs for scripts and styles based on imports
+- **Inspection** - List browser-reachable assets and explain URL-to-file mappings
 - **Caching** - Conservative caching by default with stable URLs, ETags, and revalidation
 - **Optional Fingerprinting** - Source-based fingerprinted URLs for long-lived browser caching
 - **Source Maps** - Serve inline or external sourcemaps
@@ -21,6 +21,12 @@ Fetch-based server for compiling browser assets on demand.
 npm i remix
 ```
 
+The optional image transform examples also use Sharp:
+
+```sh
+npm i sharp
+```
+
 ## Usage
 
 Use `createAssetServer` to serve browser assets from a URL namespace in your app.
@@ -31,10 +37,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -51,6 +53,64 @@ router.get('/assets/*', ({ request }) => {
 
 This example gives you an `/assets/*` endpoint that serves compiled browser source from `public/` directories throughout `app/` and from the `remix` package.
 
+## Shared Configuration
+
+Keep JSON-compatible asset mapping, access, and file-type settings in `remix.json` so the running
+server and Remix CLI use the same configuration:
+
+```jsonc
+{
+  "$schema": "./node_modules/remix/schema/remix.json",
+  "assets": {
+    "basePath": "/assets",
+    "mounts": {
+      "app": "app",
+      "npm": "node_modules",
+    },
+    "allowFiles": ["app/routes.ts", "app/**/public/**"],
+    "allowPackages": ["remix"],
+    "denyFiles": ["app/**/*.test.*"],
+    "files": {
+      "extensions": [".svg", ".png", ".jpg", ".woff2"],
+    },
+  },
+}
+```
+
+Load it from application code and add runtime-only behavior there:
+
+```ts
+import { createAssetServer, defineFileTransform } from 'remix/assets'
+import { loadConfig } from 'remix/cli'
+import sharp from 'sharp'
+
+let config = await loadConfig(import.meta.dirname)
+if (config.assets === undefined) throw new Error('Missing assets configuration')
+if (config.assets.files === undefined) throw new Error('Missing asset file configuration')
+
+let assetServer = createAssetServer({
+  ...config.assets,
+  files: {
+    ...config.assets.files,
+    transforms: {
+      webp: defineFileTransform({
+        extensions: ['.png', '.jpg'],
+        async transform(bytes) {
+          return {
+            content: await sharp(bytes).webp({ quality: 80 }).toBuffer(),
+            extension: '.webp',
+          }
+        },
+      }),
+    },
+  },
+})
+```
+
+`loadConfig()` accepts either a config file or a directory. When given a directory, it searches
+upward for the nearest `remix.json`. Run `remix assets` to list reachable files, or
+`remix assets inspect <url-or-file>` to inspect one mapping and its access decision.
+
 ## Root Directory
 
 Use `rootDir` to specify the root directory of the asset server, which is used to resolve relative file paths. Defaults to `process.cwd()`.
@@ -62,10 +122,6 @@ import { createAssetServer } from 'remix/assets'
 let assetServer = createAssetServer({
   rootDir: path.resolve(import.meta.dirname, '..'),
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
@@ -80,10 +136,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   denyFiles: ['app/**/*.server.*'],
@@ -92,28 +144,26 @@ let assetServer = createAssetServer({
 
 Values for `allowFiles` and `denyFiles` are file paths or globs. Relative values are resolved from `rootDir`. Absolute file paths match exactly, and absolute directory paths also match their descendants.
 
-Values for `allowPackages` are exact package names. Dependencies and installed optional dependencies of packages in `allowPackages` are also allowed automatically. Peer dependencies must be listed explicitly if they should be browser-reachable. Allowed package files must still be reachable through `fileMap`.
+Values for `allowPackages` are exact package names. Dependencies and installed optional dependencies of packages in `allowPackages` are also allowed automatically. Peer dependencies must be listed explicitly if they should be browser-reachable. Allowed package files must still be reachable through `mounts`.
 
-## File Map
+## Mounts
 
-Use `fileMap` to map public URLs to file paths on disk. `basePath` defines the shared public mount point, and the `fileMap` keys are URL patterns relative to that base path. The values are root-relative file path patterns.
+By default, the asset server mounts the `app` directory at `/app` and `node_modules` at `/npm`. Use `mounts` to replace these defaults. Keys are public paths relative to `basePath`, and values are directory paths relative to `rootDir`.
 
 ```ts
 import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
+  mounts: {
+    source: 'app',
+    vendor: 'node_modules',
   },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
 ```
 
-`fileMap` entries use [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern) syntax for both URL and file patterns. Wildcards must be named, and the same params must appear in both patterns so imports can be rewritten back to public URLs. For example, with `basePath: '/assets'`, a `fileMap` key of `'/app/*path'` is served at `/assets/app/*path`.
-
 ### File watching
 
 The file system is watched by default so source changes are picked up without requiring a server restart.
@@ -123,10 +173,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
@@ -145,10 +191,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: false,
@@ -162,10 +204,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: {
@@ -183,6 +221,20 @@ let src = await assetServer.getHref('app/actions/public/entry.ts')
 // '/assets/app/actions/public/entry.ts'
 ```
 
+## Inspection
+
+Use `getAssets()` for a sorted list of files that are currently browser-reachable through the
+asset server. Use `getAssetDetails()` with a public URL or file path to inspect its mapping, file
+type, access rules, and reachability status.
+
+```ts
+let assets = await assetServer.getAssets()
+// [{ url: '/assets/app/actions/public/entry.ts', filePath: '/project/app/actions/public/entry.ts', ... }]
+
+let details = await assetServer.getAssetDetails('/assets/app/actions/public/entry.ts')
+// { status: 'reachable', type: 'script', ... }
+```
+
 For configured `files` assets, you can also pass a `transform` pipeline to build a request URL with custom file transforms. Basic transforms are written as strings, while dynamic transforms use `[name, param]` tuples.
 
 ```ts
@@ -221,10 +273,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: false,
@@ -247,10 +295,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   target: {
@@ -272,10 +316,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   sourceMaps: 'external',
@@ -289,10 +329,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   sourceMaps: 'inline',
@@ -309,10 +345,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   minify: true,
@@ -330,10 +362,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   scripts: {
@@ -355,10 +383,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   scripts: {
@@ -376,7 +400,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: { '/app/*path': 'app/*path' },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   denyFiles: ['app/**/*.test.*'],
   scripts: {
@@ -404,10 +427,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -430,10 +449,6 @@ import sharp from 'sharp'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -464,10 +479,6 @@ import { createAssetServer, defineFileTransform } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -512,10 +523,6 @@ import { optimize as optimizeSvg } from 'svgo'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -548,10 +555,6 @@ import { createFsFileStorage } from 'remix/file-storage/fs'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -573,10 +576,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -624,10 +623,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   onError(error) {
@@ -651,7 +646,6 @@ import { createAssetServer } from 'remix/assets'
 let isDevelopment = process.env.NODE_ENV === 'development'
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: { '/app/*path': 'app/*path' },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   denyFiles: ['app/**/*.test.*'],
   hmr: isDevelopment
@@ -798,7 +792,6 @@ if (import.meta.hot) {
 - [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - A Fetch-based router that pairs naturally with `assets`
 - [`node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr) - Provides the server-side `import.meta.hot` runtime and browser HMR channel used by `hmr`
 - [`ui-hmr`](https://github.com/remix-run/remix/tree/main/packages/ui-hmr) - Provides a Remix UI component HMR loader for `scripts.loaders`
-- [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern) - Route-pattern syntax for URL and route file matching
 
 ## License
 

package/dist/assets.d.ts

@@ -1,5 +1,7 @@
 export { createAssetServer } from './lib/asset-server.ts';
 export { defineFileTransform } from './lib/files/config.ts';
+export type { AssetAccessDetails, AssetAccessRule } from './lib/access.ts';
 export type { AssetServer, AssetServerOptions, BrowserHmrChannel } from './lib/asset-server.ts';
+export type { AssetDetails, AssetKind, AssetStatus } from './lib/inspection.ts';
 export type { ModuleLoader } from './lib/loaders.ts';
 //# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC/F,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC1E,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC/F,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC/E,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/lib/access.d.ts

@@ -1,6 +1,34 @@
-type AccessPolicy = {
+/** Access-policy result for an inspected asset file. */
+export interface AssetAccessDetails {
+    /** Whether the asset server may serve the file. */
+    allowed: boolean;
+    /** The first configured rule that allowed the file, when one matched. */
+    allowedBy?: AssetAccessRule;
+    /** The first matching `denyFiles` pattern, when access was denied. */
+    deniedBy?: string;
+}
+/** Rule that allows an inspected asset file to be served. */
+export type AssetAccessRule = 
+/** A matching `allowFiles` entry. */
+{
+    kind: 'file';
+    value: string;
+}
+/** A runtime file provided internally by the asset server. */
+ | {
+    kind: 'injected';
+    value: string;
+}
+/** A matching `allowPackages` entry. */
+ | {
+    kind: 'package';
+    value: string;
+};
+export type AccessPolicy = {
+    getAllowedPackageRoots(): readonly string[];
     getPackageWatchDirectories(): readonly string[];
     handleFileEvent(filePath: string): void;
+    inspect(filePath: string): AssetAccessDetails;
     isAllowed(filePath: string): boolean;
 };
 export declare function createAccessPolicy(options: {
@@ -10,5 +38,4 @@ export declare function createAccessPolicy(options: {
     packageSearchRoots?: readonly string[];
     rootDir: string;
 }): AccessPolicy;
-export {};
 //# sourceMappingURL=access.d.ts.map

package/dist/lib/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/lib/access.ts"],"names":[],"mappings":"AAMA,KAAK,YAAY,GAAG;IAClB,0BAA0B,IAAI,SAAS,MAAM,EAAE,CAAA;IAC/C,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC,CAAA;AAcD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CAwDf"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/lib/access.ts"],"names":[],"mappings":"AAMA,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,yEAAyE;IACzE,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,6DAA6D;AAC7D,MAAM,MAAM,eAAe;AACzB,qCAAqC;AACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACjC,8DAA8D;GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACrC,wCAAwC;GACtC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,YAAY,GAAG;IACzB,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAAA;IAC3C,0BAA0B,IAAI,SAAS,MAAM,EAAE,CAAA;IAC/C,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAAA;IAC7C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC,CAAA;AAcD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CAoFf"}

package/dist/lib/access.js

@@ -15,9 +15,15 @@ const packageStateFileNames = new Set([
 const packageManagerRootFileNames = packageStateFileNames;
 const packageNamePartPattern = /^[A-Za-z0-9._~-]+$/;
 export function createAccessPolicy(options) {
-    let allowMatchers = options.allowFiles.map((pattern) => createFileMatcher(pattern, options.rootDir));
+    let allowMatchers = options.allowFiles.map((pattern) => ({
+        matcher: createFileMatcher(pattern, options.rootDir),
+        pattern,
+    }));
     let allowPackageNames = normalizePackageNames(options.allowPackages, 'allowPackages');
-    let denyMatchers = (options.denyFiles ?? []).map((pattern) => createFileMatcher(pattern, options.rootDir));
+    let denyMatchers = (options.denyFiles ?? []).map((pattern) => ({
+        matcher: createFileMatcher(pattern, options.rootDir),
+        pattern,
+    }));
     let packageSearchRoots = [options.rootDir, ...(options.packageSearchRoots ?? [])];
     let packageRootPaths = createPackageRootPaths({
         allowPackageNames,
@@ -36,13 +42,40 @@ export function createAccessPolicy(options) {
         allowPackageRootPathTrie = createPackageRootPathTrie(packageRootPaths);
         packageRootsDirty = false;
     }
-    function isAllowedPackage(filePath) {
+    function getAllowedPackageName(filePath) {
         if (allowPackageNames.size === 0)
-            return false;
+            return undefined;
         refreshPackageRootPathTries();
-        return isPathInPackageRootPathTrie(filePath, allowPackageRootPathTrie);
+        return getPackageNameFromRootPathTrie(filePath, allowPackageRootPathTrie);
+    }
+    function inspect(filePath) {
+        if (isInjectedPackageFilePath(filePath)) {
+            return { allowed: true, allowedBy: { kind: 'injected', value: '@remix-run/assets' } };
+        }
+        let allowedBy;
+        let allowMatch = allowMatchers.find(({ matcher }) => matcher(filePath));
+        if (allowMatch) {
+            allowedBy = { kind: 'file', value: allowMatch.pattern };
+        }
+        else {
+            let packageName = getAllowedPackageName(filePath);
+            if (packageName !== undefined) {
+                allowedBy = { kind: 'package', value: packageName };
+            }
+        }
+        if (!allowedBy)
+            return { allowed: false };
+        let denyMatch = denyMatchers.find(({ matcher }) => matcher(filePath));
+        if (denyMatch) {
+            return { allowed: false, allowedBy, deniedBy: denyMatch.pattern };
+        }
+        return { allowed: true, allowedBy };
     }
     return {
+        getAllowedPackageRoots() {
+            refreshPackageRootPathTries();
+            return [...packageRootPaths.keys()];
+        },
         getPackageWatchDirectories() {
             if (allowPackageNames.size === 0)
                 return [];
@@ -55,15 +88,9 @@ export function createAccessPolicy(options) {
                 return;
             packageRootsDirty = true;
         },
+        inspect,
         isAllowed(filePath) {
-            if (isInjectedPackageFilePath(filePath))
-                return true;
-            if (!allowMatchers.some((matcher) => matcher(filePath)) && !isAllowedPackage(filePath)) {
-                return false;
-            }
-            if (denyMatchers.length > 0 && denyMatchers.some((matcher) => matcher(filePath)))
-                return false;
-            return true;
+            return inspect(filePath).allowed;
         },
     };
 }
@@ -87,7 +114,7 @@ function validatePackageName(packageName, message) {
     }
 }
 function createPackageRootPaths(options) {
-    let allowPackageRootPaths = new Set();
+    let allowPackageRootPaths = new Map();
     let allowQueue = [];
     let seenAllowedPackageRoots = new Set();
     let searchRoots = normalizePackageSearchRoots(options.searchRoots);
@@ -105,13 +132,13 @@ function createPackageRootPaths(options) {
         }
     }
     while (allowQueue.length > 0) {
-        let { packageJsonPath } = allowQueue.shift();
+        let { packageJsonPath, packageName } = allowQueue.shift();
         let packageRootPath = normalizeFilePath(path.dirname(packageJsonPath));
         if (seenAllowedPackageRoots.has(packageRootPath))
             continue;
         seenAllowedPackageRoots.add(packageRootPath);
         let packageJson = readPackageJson(packageJsonPath);
-        allowPackageRootPaths.add(packageRootPath);
+        allowPackageRootPaths.set(packageRootPath, packageName);
         for (let dependencyName of Object.keys(packageJson.dependencies ?? {})) {
             validatePackageName(dependencyName, `Dependency "${dependencyName}" from ${packageJsonPath} must be a package name.`);
             let dependencyPackageJsonPath = findPackageJsonPath(dependencyName, packageRootPath);
@@ -138,7 +165,7 @@ function createPackageRootPaths(options) {
 }
 function createPackageRootPathTrie(packageRootPaths) {
     let rootNode = createPackageRootPathTrieNode();
-    for (let packageRootPath of packageRootPaths) {
+    for (let [packageRootPath, packageName] of packageRootPaths) {
         let node = rootNode;
         for (let segment of getFilePathSegments(packageRootPath)) {
             let childNode = node.children.get(segment);
@@ -148,29 +175,28 @@ function createPackageRootPathTrie(packageRootPaths) {
             }
             node = childNode;
         }
-        node.packageRoot = true;
+        node.packageName = packageName;
     }
     return rootNode;
 }
 function createPackageRootPathTrieNode() {
     return {
         children: new Map(),
-        packageRoot: false,
     };
 }
-function isPathInPackageRootPathTrie(filePath, trie) {
+function getPackageNameFromRootPathTrie(filePath, trie) {
     let node = trie;
-    if (node.packageRoot)
-        return true;
+    if (node.packageName !== undefined)
+        return node.packageName;
     for (let segment of getFilePathSegments(filePath)) {
         let childNode = node.children.get(segment);
         if (!childNode)
-            return false;
-        if (childNode.packageRoot)
-            return true;
+            return undefined;
+        if (childNode.packageName !== undefined)
+            return childNode.packageName;
         node = childNode;
     }
-    return false;
+    return undefined;
 }
 function getFilePathSegments(filePath) {
     return normalizeFilePath(filePath).split('/');

package/dist/lib/asset-server.d.ts

@@ -3,6 +3,7 @@ import type { HmrPayload } from './hmr.ts';
 import type { ModuleLoader } from './loaders.ts';
 import type { ScriptHmrUpdate } from './scripts/compiler.ts';
 import type { AssetTarget } from './target.ts';
+import { type AssetDetails } from './inspection.ts';
 import type { ChokidarWatcher } from './watch.ts';
 interface AssetServerWatchOptions {
     /**
@@ -135,8 +136,14 @@ interface AssetServerScriptOptions {
 export interface AssetServerOptions<transforms extends AssetRequestTransformMap = {}> {
     /** Public mount path for this asset server, e.g. `'/assets'`. */
     basePath: string;
-    /** File patterns keyed by public URL patterns. */
-    fileMap: Readonly<Record<string, string>>;
+    /**
+     * Directories to mount at public URL paths.
+     *
+     * Each key is a public URL path and its value is a directory relative to `rootDir`. Defaults to
+     * `{ app: 'app', npm: 'node_modules' }`. Public paths must not contain query strings, fragments,
+     * or encoded dot segments.
+     */
+    mounts?: Readonly<Record<string, string>>;
     /**
      * Root directory used to resolve relative file paths. Defaults to `process.cwd()`.
      */
@@ -147,7 +154,7 @@ export interface AssetServerOptions<transforms extends AssetRequestTransformMap
     allowFiles: readonly string[];
     /**
      * Exact package names whose files are allowed to be served. Dependencies and installed optional
-     * dependencies are allowed automatically. Package files must still match `fileMap`.
+     * dependencies are allowed automatically. Package files must still be within a configured mount.
      */
     allowPackages?: readonly string[];
     /**
@@ -237,6 +244,16 @@ export interface AssetServer<transforms extends AssetRequestTransformMap = {}> {
      * Returns preload URLs for one or more served asset files, ordered shallowest-first.
      */
     getPreloads(filePath: string | readonly string[]): Promise<string[]>;
+    /**
+     * Returns diagnostic details about one public asset URL or file path, including the matched mount
+     * roots, access rules, file type, and browser-reachability status.
+     */
+    getAssetDetails(input: string): Promise<AssetDetails>;
+    /**
+     * Returns every file currently reachable through this asset server, sorted by public URL and
+     * then absolute file path.
+     */
+    getAssets(): Promise<AssetDetails[]>;
     /**
      * Closes this server's filesystem watcher and browser HMR channel.
      *
@@ -250,7 +267,7 @@ export declare function getInternalWatchTargets<transforms extends AssetRequestT
  * Create an asset server instance
  *
  * Compiles TypeScript/JavaScript scripts and CSS styles on demand with optional
- * source-based URL fingerprinting, caching, and configurable file mapping.
+ * source-based URL fingerprinting, caching, and configurable directory mounts.
  *
  * @param options Server configuration
  * @returns A {@link AssetServer} with `fetch()`, `getHref()`, and `getPreloads()` methods
@@ -259,9 +276,6 @@ export declare function getInternalWatchTargets<transforms extends AssetRequestT
  * ```ts
  * let assetServer = createAssetServer({
  *   basePath: '/assets',
- *   fileMap: {
- *     '/app/*path': 'app/*path',
- *   },
  *   allowFiles: ['app/routes.ts', 'app/**\/public/**'],
  *   allowPackages: ['remix'],
  *   denyFiles: ['app/**\/*.test.*'],