@remix-run/assets 0.4.4 → 0.6.0

package/dist/lib/access.d.ts

@@ -1,10 +1,41 @@
-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: {
-    allow: readonly string[];
-    deny?: readonly string[];
+    allowFiles: readonly string[];
+    allowPackages?: readonly string[];
+    denyFiles?: readonly string[];
+    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":"AAGA,KAAK,YAAY,GAAG;IAClB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC,CAAA;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CAcf"}
+{"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

@@ -1,17 +1,338 @@
-import { createFileMatcher } from "./file-matcher.js";
-import { isInjectedPackageFilePath } from "./injected-packages.js";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createFileMatcher } from './file-matcher.js';
+import { isInjectedPackageFilePath } from './injected-packages.js';
+import { normalizeFilePath } from './paths.js';
+const packageStateFileNames = new Set([
+    'bun.lock',
+    'bun.lockb',
+    'npm-shrinkwrap.json',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    'yarn.lock',
+]);
+const packageManagerRootFileNames = packageStateFileNames;
+const packageNamePartPattern = /^[A-Za-z0-9._~-]+$/;
 export function createAccessPolicy(options) {
-    let allowMatchers = options.allow.map((pattern) => createFileMatcher(pattern, options.rootDir));
-    let denyMatchers = (options.deny ?? []).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) => ({
+        matcher: createFileMatcher(pattern, options.rootDir),
+        pattern,
+    }));
+    let packageSearchRoots = [options.rootDir, ...(options.packageSearchRoots ?? [])];
+    let packageRootPaths = createPackageRootPaths({
+        allowPackageNames,
+        searchRoots: packageSearchRoots,
+    });
+    let allowPackageRootPathTrie = createPackageRootPathTrie(packageRootPaths);
+    let packageStateDirectories = allowPackageNames.size === 0 ? [] : getPackageStateDirectories(packageSearchRoots);
+    let packageRootsDirty = false;
+    function refreshPackageRootPathTries() {
+        if (!packageRootsDirty)
+            return;
+        packageRootPaths = createPackageRootPaths({
+            allowPackageNames,
+            searchRoots: packageSearchRoots,
+        });
+        allowPackageRootPathTrie = createPackageRootPathTrie(packageRootPaths);
+        packageRootsDirty = false;
+    }
+    function getAllowedPackageName(filePath) {
+        if (allowPackageNames.size === 0)
+            return undefined;
+        refreshPackageRootPathTries();
+        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 [];
+            return packageStateDirectories;
+        },
+        handleFileEvent(filePath) {
+            if (allowPackageNames.size === 0)
+                return;
+            if (!isPackageStateFileEvent(filePath, packageStateDirectories))
+                return;
+            packageRootsDirty = true;
+        },
+        inspect,
         isAllowed(filePath) {
-            if (isInjectedPackageFilePath(filePath))
-                return true;
-            if (!allowMatchers.some((matcher) => matcher(filePath)))
-                return false;
-            if (denyMatchers.length > 0 && denyMatchers.some((matcher) => matcher(filePath)))
-                return false;
-            return true;
+            return inspect(filePath).allowed;
         },
     };
 }
+function normalizePackageNames(packageOption, optionName) {
+    let packageNames = new Set();
+    for (let packageName of packageOption ?? []) {
+        if (typeof packageName !== 'string') {
+            throw new TypeError(`${optionName} values must be strings`);
+        }
+        let normalizedPackageName = packageName.trim();
+        if (!isValidPackageName(normalizedPackageName)) {
+            throw new TypeError(`${optionName} values must be package names. Received "${packageName}".`);
+        }
+        packageNames.add(normalizedPackageName);
+    }
+    return packageNames;
+}
+function validatePackageName(packageName, message) {
+    if (!isValidPackageName(packageName)) {
+        throw new TypeError(message);
+    }
+}
+function createPackageRootPaths(options) {
+    let allowPackageRootPaths = new Map();
+    let allowQueue = [];
+    let seenAllowedPackageRoots = new Set();
+    let searchRoots = normalizePackageSearchRoots(options.searchRoots);
+    for (let packageName of options.allowPackageNames) {
+        let foundPackage = false;
+        for (let searchRoot of searchRoots) {
+            let packageJsonPath = findPackageJsonPath(packageName, searchRoot);
+            if (packageJsonPath === null)
+                continue;
+            foundPackage = true;
+            allowQueue.push({ packageJsonPath, packageName });
+        }
+        if (!foundPackage) {
+            throw new TypeError(`Could not resolve allowed package "${packageName}".`);
+        }
+    }
+    while (allowQueue.length > 0) {
+        let { packageJsonPath, packageName } = allowQueue.shift();
+        let packageRootPath = normalizeFilePath(path.dirname(packageJsonPath));
+        if (seenAllowedPackageRoots.has(packageRootPath))
+            continue;
+        seenAllowedPackageRoots.add(packageRootPath);
+        let packageJson = readPackageJson(packageJsonPath);
+        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);
+            if (dependencyPackageJsonPath === null) {
+                throw new TypeError(`Could not resolve dependency "${dependencyName}" from ${packageJsonPath}.`);
+            }
+            allowQueue.push({
+                packageJsonPath: dependencyPackageJsonPath,
+                packageName: dependencyName,
+            });
+        }
+        for (let dependencyName of Object.keys(packageJson.optionalDependencies ?? {})) {
+            validatePackageName(dependencyName, `Optional dependency "${dependencyName}" from ${packageJsonPath} must be a package name.`);
+            let dependencyPackageJsonPath = findPackageJsonPath(dependencyName, packageRootPath);
+            if (dependencyPackageJsonPath !== null) {
+                allowQueue.push({
+                    packageJsonPath: dependencyPackageJsonPath,
+                    packageName: dependencyName,
+                });
+            }
+        }
+    }
+    return allowPackageRootPaths;
+}
+function createPackageRootPathTrie(packageRootPaths) {
+    let rootNode = createPackageRootPathTrieNode();
+    for (let [packageRootPath, packageName] of packageRootPaths) {
+        let node = rootNode;
+        for (let segment of getFilePathSegments(packageRootPath)) {
+            let childNode = node.children.get(segment);
+            if (!childNode) {
+                childNode = createPackageRootPathTrieNode();
+                node.children.set(segment, childNode);
+            }
+            node = childNode;
+        }
+        node.packageName = packageName;
+    }
+    return rootNode;
+}
+function createPackageRootPathTrieNode() {
+    return {
+        children: new Map(),
+    };
+}
+function getPackageNameFromRootPathTrie(filePath, trie) {
+    let node = trie;
+    if (node.packageName !== undefined)
+        return node.packageName;
+    for (let segment of getFilePathSegments(filePath)) {
+        let childNode = node.children.get(segment);
+        if (!childNode)
+            return undefined;
+        if (childNode.packageName !== undefined)
+            return childNode.packageName;
+        node = childNode;
+    }
+    return undefined;
+}
+function getFilePathSegments(filePath) {
+    return normalizeFilePath(filePath).split('/');
+}
+function normalizePackageSearchRoots(searchRoots) {
+    let normalizedSearchRoots = new Set();
+    for (let searchRoot of searchRoots) {
+        let normalizedSearchRoot = normalizeFilePath(searchRoot);
+        normalizedSearchRoots.add(normalizedSearchRoot);
+        if (path.basename(normalizedSearchRoot) === 'node_modules') {
+            normalizedSearchRoots.add(path.dirname(normalizedSearchRoot));
+        }
+    }
+    return [...normalizedSearchRoots];
+}
+function getPackageStateDirectories(searchRoots) {
+    let packageStateDirectories = new Set();
+    for (let searchRoot of searchRoots) {
+        let packageManagerRoot = findPackageManagerRoot(searchRoot);
+        if (packageManagerRoot !== null) {
+            packageStateDirectories.add(packageManagerRoot);
+        }
+    }
+    return [...packageStateDirectories];
+}
+function isPackageStateFileEvent(filePath, packageStateDirectories) {
+    let normalizedFilePath = normalizeFilePath(filePath);
+    let fileName = path.basename(normalizedFilePath);
+    if (!packageStateFileNames.has(fileName))
+        return false;
+    let directory = path.dirname(normalizedFilePath);
+    return packageStateDirectories.some((packageStateDirectory) => directory === packageStateDirectory);
+}
+function findPackageManagerRoot(startDirectory) {
+    let directory = normalizePackageStateSearchRoot(startDirectory);
+    while (true) {
+        if (hasPackageManagerRootFile(directory))
+            return directory;
+        let parentDirectory = path.dirname(directory);
+        if (parentDirectory === directory)
+            return null;
+        directory = parentDirectory;
+    }
+}
+function normalizePackageStateSearchRoot(searchRoot) {
+    let normalizedSearchRoot = normalizeFilePath(searchRoot);
+    return path.basename(normalizedSearchRoot) === 'node_modules'
+        ? path.dirname(normalizedSearchRoot)
+        : normalizedSearchRoot;
+}
+function hasPackageManagerRootFile(directory) {
+    for (let fileName of packageManagerRootFileNames) {
+        try {
+            let stat = fs.statSync(path.join(directory, fileName));
+            if (stat.isFile())
+                return true;
+        }
+        catch (error) {
+            if (isPathNotFoundError(error))
+                continue;
+            throw error;
+        }
+    }
+    return false;
+}
+function findPackageJsonPath(packageName, startDirectory) {
+    let directory = normalizeFilePath(startDirectory);
+    while (true) {
+        let packageJsonPath = resolvePackageJsonPath(directory, packageName);
+        if (packageJsonPath !== null)
+            return packageJsonPath;
+        let parentDirectory = path.dirname(directory);
+        if (parentDirectory === directory)
+            return null;
+        directory = parentDirectory;
+    }
+}
+function resolvePackageJsonPath(directory, packageName) {
+    let packagePath = path.basename(directory) === 'node_modules'
+        ? path.join(directory, packageName, 'package.json')
+        : path.join(directory, 'node_modules', packageName, 'package.json');
+    try {
+        return normalizeFilePath(fs.realpathSync(packagePath));
+    }
+    catch (error) {
+        if (isPathNotFoundError(error))
+            return null;
+        throw error;
+    }
+}
+function readPackageJson(packageJsonPath) {
+    let packageJson;
+    try {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    }
+    catch (error) {
+        if (isPathNotFoundError(error))
+            return {};
+        throw error;
+    }
+    if (packageJson === null || typeof packageJson !== 'object') {
+        return {};
+    }
+    return {
+        dependencies: readDependencyMap(packageJson, 'dependencies'),
+        optionalDependencies: readDependencyMap(packageJson, 'optionalDependencies'),
+    };
+}
+function readDependencyMap(packageJson, key) {
+    if (!(key in packageJson))
+        return undefined;
+    let value = packageJson[key];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    let dependencies = {};
+    for (let [dependencyName, dependencyVersion] of Object.entries(value)) {
+        if (typeof dependencyVersion === 'string') {
+            dependencies[dependencyName] = dependencyVersion;
+        }
+    }
+    return dependencies;
+}
+function isValidPackageName(packageName) {
+    if (packageName.length === 0)
+        return false;
+    let packageNameParts = packageName.startsWith('@')
+        ? packageName.slice(1).split('/')
+        : packageName.split('/');
+    if (packageNameParts.length !== (packageName.startsWith('@') ? 2 : 1))
+        return false;
+    return packageNameParts.every((part) => part.length > 0 && part !== '.' && part !== '..' && packageNamePartPattern.test(part));
+}
+function isPathNotFoundError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'ENOENT' ||
+            error.code === 'ENOTDIR'));
+}

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

@@ -1,5 +1,9 @@
 import type { AssetRequestTransformMap, AssetServerFilesOptions, AssetTransformInvocation } from './files/config.ts';
+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 {
     /**
@@ -16,6 +20,88 @@ interface AssetServerWatchOptions {
      */
     pollInterval?: number;
 }
+/**
+ * Bridge used by an asset server to watch browser source files and publish update events through a
+ * server-level HMR runtime.
+ *
+ * The asset server registers its file handler, keeps the channel's watched-file set in sync with
+ * compiled assets, injects `url` into its browser HMR client, and closes the channel when the asset
+ * server closes.
+ */
+export interface BrowserHmrChannel {
+    /** Absolute EventSource URL that receives the browser HMR events produced by this channel. */
+    readonly url: string;
+    /** Releases the channel and all file-watching resources it owns. */
+    close(): void;
+    /**
+     * Registers the asset server's handler for file changes reported by the channel's watcher.
+     *
+     * @param handler Callback that converts a batch of file changes into browser update or reload
+     * events.
+     * @returns A cleanup function that stops forwarding file changes to this handler.
+     */
+    onFileEvents(handler: BrowserHmrFileEventHandler): () => void;
+    /**
+     * Applies additions and removals to the channel's set of watched absolute file paths.
+     *
+     * @param delta Files to add and remove from the watcher.
+     */
+    updateWatchedFiles(delta: BrowserHmrWatchedFileDelta): void;
+}
+/**
+ * Creates the browser HMR channel owned by an asset server instance.
+ *
+ * Returning `undefined` leaves browser HMR inactive. The asset server invokes this factory once,
+ * after construction, and closes a returned channel from `assetServer.close()`.
+ *
+ * @returns A channel, no channel, or a promise for either result.
+ */
+export type BrowserHmrChannelFactory = () => BrowserHmrChannel | undefined | Promise<BrowserHmrChannel | undefined>;
+/**
+ * Converts a watcher batch into ordered browser update or reload events.
+ *
+ * @param events File additions, changes, and removals reported together by the watcher.
+ * @returns Browser events to publish in their returned order.
+ */
+export type BrowserHmrFileEventHandler = (events: readonly BrowserHmrFileEvent[]) => Promise<readonly BrowserHmrEvent[]>;
+/**
+ * Watched file delta for a browser HMR channel.
+ */
+export interface BrowserHmrWatchedFileDelta {
+    /** Absolute source file paths newly required by the asset server's compiled module graph. */
+    add: readonly string[];
+    /** Absolute source file paths no longer required by the asset server's compiled module graph. */
+    remove: readonly string[];
+}
+/**
+ * File watcher event reported to a browser HMR channel.
+ */
+export type BrowserHmrFileEvent = {
+    /** Filesystem operation observed by the channel's watcher. */
+    event: 'add' | 'change' | 'unlink';
+    /** Absolute path of the source file that changed. */
+    filePath: string;
+};
+/**
+ * Browser HMR event emitted to connected clients.
+ */
+export type BrowserHmrEvent = {
+    /** Absolute source file paths that triggered this update. */
+    files?: string[];
+    /** Update time used to bypass browser module and stylesheet caches. */
+    timestamp: number;
+    /** Browser update event. */
+    type: 'update';
+    /** Accepted JavaScript and CSS module updates for the browser to apply in place. */
+    updates: Extract<HmrPayload, {
+        type: 'browser:update';
+    }>['updates'];
+} | {
+    /** Absolute source file paths that could not be handled in place. */
+    files?: string[];
+    /** Browser reload event. */
+    type: 'reload';
+};
 interface FingerprintOptions {
     /**
      * Per-build invalidation token that must change whenever fingerprinted asset URLs
@@ -33,6 +119,16 @@ interface AssetServerScriptOptions {
     define?: Record<string, string>;
     /** Import specifiers to leave unrewritten (CDN URLs, import map entries, etc.) */
     external?: string[];
+    /**
+     * Synchronous loaders that post-process compiled JavaScript.
+     *
+     * Loaders use Node's synchronous `load` hook signature. Later loaders wrap earlier loaders: for
+     * `[first, second]`, `second` is entered first and delegates through `first` to the default
+     * behavior. As a result, transformations performed after `nextLoad()` are applied in array order.
+     * Loaders run after TypeScript/JavaScript transformation and before HMR analysis and minification.
+     * Only `format: 'module'` is supported, and import attributes are unsupported.
+     */
+    loaders?: readonly ModuleLoader[];
 }
 /**
  * Options used to construct an {@link AssetServer} via {@link createAssetServer}.
@@ -40,9 +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 relative to `basePath`. */
-    /** 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()`.
      */
@@ -50,11 +151,16 @@ export interface AssetServerOptions<transforms extends AssetRequestTransformMap
     /**
      * Glob patterns or file paths that are allowed to be served. Relative values are resolved from `rootDir`.
      */
-    allow: readonly string[];
+    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 be within a configured mount.
+     */
+    allowPackages?: readonly string[];
     /**
      * Glob patterns or file paths that are denied from being served. Relative values are resolved from `rootDir`.
      */
-    deny?: readonly string[];
+    denyFiles?: readonly string[];
     /**
      * Controls optional source-based URL fingerprinting for rewritten asset URLs.
      *
@@ -93,6 +199,13 @@ export interface AssetServerOptions<transforms extends AssetRequestTransformMap
      * module extensions are not allowed here.
      */
     files?: AssetServerFilesOptions<transforms>;
+    /**
+     * Enables `import.meta.hot` and coordinates browser updates through a server-level HMR runtime.
+     *
+     * HMR requires `watch` to be enabled. The factory is called once for this asset server. Returning
+     * `undefined` leaves HMR inactive; a returned channel is closed by `assetServer.close()`.
+     */
+    hmr?: BrowserHmrChannelFactory;
     /**
      * Enable filesystem-backed cache invalidation for long-lived server instances.
      * Enabled by default. Pass `true` to use the default watcher options, an options
@@ -132,7 +245,19 @@ export interface AssetServer<transforms extends AssetRequestTransformMap = {}> {
      */
     getPreloads(filePath: string | readonly string[]): Promise<string[]>;
     /**
-     * Closes any watcher resources owned by this server instance.
+     * 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.
+     *
+     * @returns A promise that resolves after owned development resources have been released.
      */
     close(): Promise<void>;
 }
@@ -142,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
@@ -151,15 +276,17 @@ export declare function getInternalWatchTargets<transforms extends AssetRequestT
  * ```ts
  * let assetServer = createAssetServer({
  *   basePath: '/assets',
- *   fileMap: {
- *     '/app/*path': 'app/*path',
- *   },
- *   allow: ['app/**'],
+ *   allowFiles: ['app/routes.ts', 'app/**\/public/**'],
+ *   allowPackages: ['remix'],
+ *   denyFiles: ['app/**\/*.test.*'],
  * })
  *
  * route('/assets/*path', ({ request }) => assetServer.fetch(request))
  * ```
  */
 export declare function createAssetServer<const transforms extends AssetRequestTransformMap = {}>(options: AssetServerCreateOptions<transforms>): AssetServer<transforms>;
+export declare function createScriptHmrPayload(updates: ScriptHmrUpdate[]): Extract<HmrPayload, {
+    type: 'browser:reload' | 'browser:update';
+}> | null;
 export {};
 //# sourceMappingURL=asset-server.d.ts.map

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

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