@remix-run/assets 0.2.0 → 0.3.0

package/dist/lib/scripts/transform.js

@@ -2,12 +2,15 @@ import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { getTsconfig } from 'get-tsconfig';
+import MagicString from 'magic-string';
 import { minify } from 'oxc-minify';
+import { parseSync, visitorKeys } from 'oxc-parser';
 import { transform as oxcTransform } from 'oxc-transform';
 import { init as esModuleLexerInit, parse as esModuleLexer } from 'es-module-lexer';
 import { isCommonJS, mayContainCommonJSModuleGlobals } from "./cjs-check.js";
 import { createAssetServerCompilationError, isAssetServerCompilationError, } from "../compilation-error.js";
 import { generateFingerprint } from "../fingerprint.js";
+import { maskAuthoredInjectedPackageSpecifier, mayContainInjectedPackageSpecifier, restoreAuthoredInjectedPackageSpecifier, } from "../injected-packages.js";
 import { normalizeFilePath } from "../paths.js";
 import { composeSourceMaps, rewriteSourceMapSources, stringifySourceMap } from "../source-maps.js";
 const scriptModuleTypes = [
@@ -108,7 +111,7 @@ export async function transformModule(record, args) {
             sourceMaps: args.sourceMaps ?? undefined,
             target: args.target ?? undefined,
         });
-        analysis.unresolvedImports = analysis.unresolvedImports.filter((unresolved) => !args.externalSet.has(unresolved.specifier));
+        analysis.unresolvedImports = analysis.unresolvedImports.filter((unresolved) => !args.externalSet.has(getDisplayImportSpecifier(unresolved.specifier)));
         if (mayContainCommonJSModuleGlobals(sourceText) && isCommonJS(analysis.rawCode)) {
             throw createAssetServerCompilationError(`CommonJS module detected: ${resolvedPath}. ` +
                 `This module uses CommonJS (require/module.exports) which is not supported. ` +
@@ -178,9 +181,10 @@ function isPackageImportSpecifier(specifier) {
     return !specifier.startsWith('./') && !specifier.startsWith('../') && !specifier.startsWith('/');
 }
 async function analyzeModuleSource(sourceText, resolvedPath, transformOptions, options) {
+    let maskedSourceText = maskAuthoredInjectedPackageImports(sourceText, resolvedPath);
     let transformResult;
     try {
-        transformResult = await oxcTransform(resolvedPath, sourceText, getTransformOptions(resolvedPath, transformOptions, options));
+        transformResult = await oxcTransform(resolvedPath, maskedSourceText, getTransformOptions(resolvedPath, transformOptions, options));
         assertNoCompilerErrors(transformResult.errors, resolvedPath, 'transform');
     }
     catch (error) {
@@ -325,6 +329,78 @@ async function getUnresolvedImportsFromLexer(rawCode) {
     }
     return unresolvedImports;
 }
+function getDisplayImportSpecifier(specifier) {
+    return restoreAuthoredInjectedPackageSpecifier(specifier) ?? specifier;
+}
+function maskAuthoredInjectedPackageImports(sourceText, resolvedPath) {
+    if (!mayContainInjectedPackageSpecifier(sourceText)) {
+        return sourceText;
+    }
+    let parseResult = parseSync(resolvedPath, sourceText, {
+        lang: getSourceLanguageForPath(resolvedPath),
+        sourceType: 'module',
+    });
+    if (parseResult.errors.length > 0) {
+        return sourceText;
+    }
+    let replacements = [];
+    walkAst(parseResult.program, (node) => {
+        if (node.type !== 'ImportDeclaration' &&
+            node.type !== 'ExportAllDeclaration' &&
+            node.type !== 'ExportNamedDeclaration' &&
+            node.type !== 'ImportExpression') {
+            return;
+        }
+        let source = 'source' in node ? node.source : null;
+        if (!isStringLiteralNode(source))
+            return;
+        let maskedSpecifier = maskAuthoredInjectedPackageSpecifier(source.value);
+        if (maskedSpecifier == null)
+            return;
+        replacements.push({
+            end: source.end - 1,
+            specifier: maskedSpecifier,
+            start: source.start + 1,
+        });
+    });
+    if (replacements.length === 0)
+        return sourceText;
+    let rewrittenSource = new MagicString(sourceText);
+    for (let replacement of replacements) {
+        rewrittenSource.overwrite(replacement.start, replacement.end, replacement.specifier);
+    }
+    return rewrittenSource.toString();
+}
+function walkAst(node, visit) {
+    visit(node);
+    let keys = visitorKeys[node.type];
+    if (!keys)
+        return;
+    let walkableNode = node;
+    for (let key of keys) {
+        let value = walkableNode[key];
+        if (Array.isArray(value)) {
+            for (let child of value) {
+                if (isAstNode(child)) {
+                    walkAst(child, visit);
+                }
+            }
+            continue;
+        }
+        if (isAstNode(value)) {
+            walkAst(value, visit);
+        }
+    }
+}
+function isAstNode(value) {
+    return typeof value === 'object' && value !== null && 'type' in value;
+}
+function isStringLiteralNode(node) {
+    return (node?.type === 'Literal' &&
+        typeof node.start === 'number' &&
+        typeof node.end === 'number' &&
+        typeof node.value === 'string');
+}
 function getStaticImportSpecifier(source, imported) {
     if (imported.n != null) {
         return imported.n;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remix-run/assets",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Fetch-based server for compiling browser JS/TS and CSS assets on demand",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@oxc-project/runtime": "^0.121.0",
     "chokidar": "^5.0.0",
     "es-module-lexer": "^2.0.0",
     "get-tsconfig": "^4.13.6",
@@ -43,7 +44,9 @@
   "devDependencies": {
     "@types/node": "^24.6.0",
     "@types/picomatch": "^4.0.3",
-    "@typescript/native-preview": "7.0.0-dev.20251125.1"
+    "@typescript/native-preview": "7.0.0-dev.20251125.1",
+    "@remix-run/assert": "0.2.0",
+    "@remix-run/test": "0.3.0"
   },
   "keywords": [
     "remix",
@@ -58,7 +61,8 @@
     "bench": "pnpm --dir ./bench run bench",
     "build": "tsgo -p tsconfig.build.json",
     "clean": "git clean -fdX",
-    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "test": "remix-test",
+    "test:bun": "bun x --bun remix-test",
     "typecheck": "tsgo --noEmit"
   }
 }

package/src/lib/access.ts

@@ -1,4 +1,5 @@
 import { createFileMatcher } from './file-matcher.ts'
+import { isInjectedPackageFilePath } from './injected-packages.ts'
 
 type AccessPolicy = {
   isAllowed(filePath: string): boolean
@@ -16,6 +17,7 @@ export function createAccessPolicy(options: {
 
   return {
     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

package/src/lib/asset-server.ts

@@ -3,7 +3,8 @@ import * as fs from 'node:fs'
 import { createAccessPolicy } from './access.ts'
 import { isAssetServerCompilationError } from './compilation-error.ts'
 import { getFingerprintRequestCacheControl, parseFingerprintSuffix } from './fingerprint.ts'
-import { normalizeFilePath } from './paths.ts'
+import { getInjectedPackageRouteConfigs } from './injected-packages.ts'
+import { normalizeFilePath, normalizePathname } from './paths.ts'
 import { compileRoutes } from './routes.ts'
 import type { CompiledRoutes } from './routes.ts'
 import { createResponseForScript, createScriptCompiler } from './scripts/compiler.ts'
@@ -54,7 +55,9 @@ interface AssetServerScriptOptions {
 const scriptExtensionSet = new Set<string>(supportedScriptExtensions)
 
 export interface AssetServerOptions {
-  /** File patterns keyed by public URL patterns. */
+  /** Public mount path for this asset server, e.g. `'/assets'`. */
+  basePath: string
+  /** File patterns keyed by public URL patterns relative to `basePath`. */
   fileMap: Readonly<Record<string, string>>
   /**
    * Root directory used to resolve relative file paths. Defaults to `process.cwd()`.
@@ -135,6 +138,7 @@ export interface AssetServer {
 
 type ResolvedAssetServerOptions = {
   allow: readonly string[]
+  basePath: string
   buildId?: string
   define?: Record<string, string>
   deny?: readonly string[]
@@ -174,8 +178,9 @@ export function getInternalWatchTargets(assetServer: AssetServer): readonly stri
  * @example
  * ```ts
  * let assetServer = createAssetServer({
+ *   basePath: '/assets',
  *   fileMap: {
- *     '/assets/app/*path': 'app/*path',
+ *     '/app/*path': 'app/*path',
  *   },
  *   allow: ['app/**'],
  * })
@@ -433,6 +438,7 @@ function defaultErrorHandler(error: unknown): void {
 
 function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetServerOptions {
   let rootDir = normalizeFilePath(fs.realpathSync(path.resolve(options.rootDir ?? process.cwd())))
+  let basePath = normalizeBasePath(options.basePath)
   let scriptOptions = options.scripts ?? {}
   let fingerprintOptions = normalizeFingerprintOptions({
     fingerprint: options.fingerprint,
@@ -441,6 +447,7 @@ function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetSe
 
   return {
     allow: options.allow,
+    basePath,
     buildId: fingerprintOptions.buildId,
     define: scriptOptions.define,
     deny: options.deny,
@@ -449,10 +456,13 @@ function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetSe
     minify: options.minify ?? false,
     onError: options.onError ?? defaultErrorHandler,
     rootDir,
-    routes: compileRoutes({
-      fileMap: options.fileMap,
-      rootDir,
-    }),
+    routes: compileRoutes(basePath, [
+      {
+        fileMap: options.fileMap,
+        rootDir,
+      },
+      ...getInjectedPackageRouteConfigs(),
+    ]),
     sourceMapSourcePaths: options.sourceMapSourcePaths ?? 'url',
     sourceMaps: options.sourceMaps,
     scriptsTarget: resolveScriptTarget(options.target),
@@ -461,6 +471,14 @@ function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetSe
   }
 }
 
+function normalizeBasePath(basePath: string): string {
+  if (typeof basePath !== 'string') {
+    throw new TypeError('basePath must be a string')
+  }
+
+  return normalizePathname(basePath || '/').replace(/\/+$/, '') || '/'
+}
+
 function normalizeFingerprintOptions(options: {
   fingerprint: AssetServerOptions['fingerprint']
   watch: AssetServerOptions['watch']

package/src/lib/injected-packages.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { getFilePathDirectory, normalizeFilePath } from './paths.ts'
+
+type ResolvedInjectedPackage = {
+  packageJsonPath: string
+  packageRoot: string
+}
+
+const injectedPackageNames = ['@oxc-project/runtime'] as const
+const injectedPackagesBasePath = '/__@remix/injected'
+
+const resolvedInjectedPackages = new Map<string, ResolvedInjectedPackage>()
+
+export function isInjectedPackageFilePath(filePath: string): boolean {
+  let normalizedFilePath = normalizeFilePath(filePath)
+
+  for (let packageName of injectedPackageNames) {
+    let packageRoot = getResolvedInjectedPackage(packageName).packageRoot
+    if (normalizedFilePath === packageRoot || normalizedFilePath.startsWith(`${packageRoot}/`)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+export function getInjectedPackageRouteConfigs(): {
+  fileMap: Record<string, string>
+  rootDir: string
+}[] {
+  return injectedPackageNames.map((packageName) => {
+    let { packageRoot } = getResolvedInjectedPackage(packageName)
+
+    return {
+      fileMap: {
+        [getInjectedPackageRoutePattern(packageName)]: `${packageName}/*path`,
+      },
+      rootDir: getInjectedPackageRouteRoot(packageRoot, packageName),
+    }
+  })
+}
+
+export function getInjectedPackageNameForSpecifier(specifier: string): string | null {
+  for (let packageName of injectedPackageNames) {
+    if (specifier === packageName || specifier.startsWith(`${packageName}/`)) {
+      return packageName
+    }
+  }
+
+  return null
+}
+
+export function mayContainInjectedPackageSpecifier(sourceText: string): boolean {
+  return injectedPackageNames.some((packageName) => sourceText.includes(packageName))
+}
+
+export function maskAuthoredInjectedPackageSpecifier(specifier: string): string | null {
+  let packageName = getInjectedPackageNameForSpecifier(specifier)
+  if (!packageName) return null
+
+  let maskedPackageName = getMaskedInjectedPackageName(packageName)
+  return `${maskedPackageName}${specifier.slice(packageName.length)}`
+}
+
+export function restoreAuthoredInjectedPackageSpecifier(specifier: string): string | null {
+  for (let packageName of injectedPackageNames) {
+    let maskedPackageName = getMaskedInjectedPackageName(packageName)
+    if (specifier === maskedPackageName) {
+      return packageName
+    }
+    if (specifier.startsWith(`${maskedPackageName}/`)) {
+      return `${packageName}${specifier.slice(maskedPackageName.length)}`
+    }
+  }
+
+  return null
+}
+
+function getMaskedInjectedPackageName(packageName: string): string {
+  return `~${packageName.slice(1)}`
+}
+
+export function getInjectedPackageImporterPath(): string {
+  return normalizeFilePath(fileURLToPath(import.meta.url))
+}
+
+function getResolvedInjectedPackage(packageName: string): ResolvedInjectedPackage {
+  let existing = resolvedInjectedPackages.get(packageName)
+  if (existing) return existing
+
+  let packageJsonUrl = import.meta.resolve(`${packageName}/package.json`)
+  let packageJsonPath = normalizeFilePath(fs.realpathSync(fileURLToPath(packageJsonUrl)))
+
+  let resolvedInjectedPackage = {
+    packageJsonPath,
+    packageRoot: normalizeFilePath(fs.realpathSync(getFilePathDirectory(packageJsonPath))),
+  }
+
+  resolvedInjectedPackages.set(packageName, resolvedInjectedPackage)
+  return resolvedInjectedPackage
+}
+
+function getInjectedPackageRoutePattern(packageName: string): string {
+  return `${injectedPackagesBasePath}/${packageName}/*path`
+}
+
+function getInjectedPackageRouteRoot(packageRoot: string, packageName: string): string {
+  let routeRoot = packageRoot
+
+  for (let _segment of packageName.split('/')) {
+    routeRoot = getFilePathDirectory(routeRoot)
+  }
+
+  return routeRoot
+}

package/src/lib/paths.ts

@@ -57,6 +57,34 @@ export function getFilePathDirectory(filePath: string): string {
   return path.posix.dirname(normalizeWindowsPath(filePath))
 }
 
+export function getRelativeFilePath(fromPath: string, toPath: string): string {
+  let normalizedFromPath = normalizeFilePath(fromPath)
+  let normalizedToPath = normalizeFilePath(toPath)
+
+  if (normalizedFromPath.startsWith('//') || normalizedToPath.startsWith('//')) {
+    return normalizeWindowsPath(
+      path.win32.relative(
+        normalizedFromPath.replace(/\//g, '\\'),
+        normalizedToPath.replace(/\//g, '\\'),
+      ),
+    )
+  }
+
+  if (
+    windowsDriveLetterRE.test(normalizedFromPath) ||
+    windowsDriveLetterRE.test(normalizedToPath)
+  ) {
+    return normalizeWindowsPath(
+      path.win32.relative(
+        normalizedFromPath.replace(/\//g, '\\'),
+        normalizedToPath.replace(/\//g, '\\'),
+      ),
+    )
+  }
+
+  return path.posix.relative(normalizedFromPath, normalizedToPath)
+}
+
 export function getFilePathBaseName(filePath: string): string {
   return path.posix.basename(normalizeWindowsPath(filePath))
 }

package/src/lib/routes.ts

@@ -1,18 +1,23 @@
-import * as path from 'node:path'
 import { RoutePattern } from '@remix-run/route-pattern'
 
 import {
+  getRelativeFilePath,
   isAbsoluteFilePath,
   normalizeFilePath,
   normalizePathname,
   resolveFilePath,
 } from './paths.ts'
 
-export interface AssetRouteDefinition {
+interface AssetRouteDefinition {
   urlPattern: string
   filePattern: string
 }
 
+interface RouteConfig {
+  fileMap: Readonly<Record<string, string>>
+  rootDir: string
+}
+
 interface CompiledRoute {
   rootDir: string
   urlPattern: RoutePattern
@@ -34,21 +39,26 @@ function normalizeFilePattern(pattern: string): string {
   return normalizePathname(pattern)
 }
 
-export function compileRoutes(options: {
-  fileMap: Readonly<Record<string, string>>
-  rootDir: string
-}): CompiledRoutes {
-  if (Object.keys(options.fileMap).length === 0) {
+export function compileRoutes(
+  basePath: string,
+  routeConfigs: readonly RouteConfig[],
+): CompiledRoutes {
+  if (routeConfigs.every((routeConfig) => Object.keys(routeConfig.fileMap).length === 0)) {
     throw new Error('createAssetServer() requires at least one configured fileMap entry.')
   }
 
-  let compiledRoutes = Object.entries(options.fileMap).map(([urlPattern, filePattern]) =>
-    compileRoute(
-      {
-        urlPattern,
-        filePattern,
-      },
-      { rootDir: options.rootDir },
+  let compiledRoutes = routeConfigs.flatMap((routeConfig) =>
+    Object.entries(routeConfig.fileMap).map(([urlPattern, filePattern]) =>
+      compileRoute(
+        {
+          filePattern,
+          urlPattern,
+        },
+        {
+          basePath,
+          rootDir: routeConfig.rootDir,
+        },
+      ),
     ),
   )
 
@@ -69,8 +79,7 @@ export function compileRoutes(options: {
       let normalizedFilePath = normalizeFilePath(filePath)
 
       for (let route of compiledRoutes) {
-        let relativeFilePath = getRelativeFilePath(normalizedFilePath, route.rootDir)
-        if (relativeFilePath === null) continue
+        let relativeFilePath = getRelativeFilePath(route.rootDir, normalizedFilePath)
         let match = route.filePattern.ast.pathname.match(relativeFilePath)
         if (!match) continue
         return normalizePathname(route.urlPattern.href(getPathnameParams(route.filePattern, match)))
@@ -84,10 +93,15 @@ export function compileRoutes(options: {
 function compileRoute(
   route: AssetRouteDefinition,
   options: {
+    basePath: string
     rootDir: string
   },
 ): CompiledRoute {
-  let urlPatternSource = normalizePathname(route.urlPattern)
+  let basePath = normalizePathname(options.basePath).replace(/\/+$/, '') || '/'
+  let relativeUrlPattern = normalizePathname(route.urlPattern)
+  let urlPatternSource = normalizePathname(
+    `${basePath.replace(/\/+$/, '')}/${relativeUrlPattern.replace(/^\/+/, '')}`,
+  )
   let filePatternSource = normalizeFilePattern(route.filePattern)
 
   let urlPattern = new RoutePattern(urlPatternSource)
@@ -104,11 +118,6 @@ function compileRoute(
   }
 }
 
-function getRelativeFilePath(filePath: string, rootDir: string): string | null {
-  if (filePath[1] === ':' && rootDir[1] === ':' && filePath[0] !== rootDir[0]) return null
-  return path.posix.relative(rootDir, filePath)
-}
-
 function getPathnameParams(
   pattern: RoutePattern,
   match: Array<{ name: string; type: ':' | '*'; value: string }>,

package/src/lib/scripts/resolve.ts

@@ -7,6 +7,11 @@ import {
   isAssetServerCompilationError,
 } from '../compilation-error.ts'
 import type { AssetServerCompilationError } from '../compilation-error.ts'
+import {
+  getInjectedPackageNameForSpecifier,
+  getInjectedPackageImporterPath,
+  restoreAuthoredInjectedPackageSpecifier,
+} from '../injected-packages.ts'
 import type { ModuleRecord, ModuleTracking } from '../module-store.ts'
 import { normalizeFilePath } from '../paths.ts'
 import type { CompiledRoutes } from '../routes.ts'
@@ -81,6 +86,11 @@ type ResolvedSpec = {
   specifier: string
 }
 
+type NormalizedSpecifierResolution = {
+  importerPath: string
+  specifier: string
+}
+
 export async function resolveModule(
   record: ScriptRecord,
   transformed: TransformedModule,
@@ -109,9 +119,10 @@ export async function resolveModule(
   let deps = new Set<string>()
 
   for (let unresolved of transformed.unresolvedImports) {
+    let displaySpecifier = getDisplayImportSpecifier(unresolved.specifier)
     let trackedResolution = getTrackedRelativeImportResolution(
       transformed.importerDir,
-      unresolved.specifier,
+      displaySpecifier,
       args.isWatchIgnored,
     )
 
@@ -119,7 +130,7 @@ export async function resolveModule(
     if (!resolvedSpec?.absolutePath) {
       return failResolve(
         createAssetServerCompilationError(
-          `Failed to resolve import "${unresolved.specifier}" in ${transformed.resolvedPath}. ` +
+          `Failed to resolve import "${displaySpecifier}" in ${transformed.resolvedPath}. ` +
             `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
           {
             code: 'IMPORT_RESOLUTION_FAILED',
@@ -136,7 +147,7 @@ export async function resolveModule(
     if (!resolvedImport) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedSpec.absolutePath}", is not a supported script file. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedSpec.absolutePath}", is not a supported script file. ` +
             `Supported extensions are ${supportedScriptExtensions.join(', ')}.`,
           {
             code: 'IMPORT_NOT_SUPPORTED',
@@ -152,7 +163,7 @@ export async function resolveModule(
     if (!args.isAllowed(resolvedImport.identityPath)) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is not allowed by the asset server allow/deny configuration. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is not allowed by the asset server allow/deny configuration. ` +
             `Add a matching allow rule for this file path, remove a conflicting deny rule for this file path, or mark this import as external.`,
           {
             code: 'IMPORT_NOT_ALLOWED',
@@ -169,7 +180,7 @@ export async function resolveModule(
     if (!stableUrlPathname) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is outside all configured fileMap entries. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is outside all configured fileMap entries. ` +
             `Add a matching fileMap entry for this file path, or mark this import as external.`,
           {
             code: 'IMPORT_OUTSIDE_FILE_MAP',
@@ -323,11 +334,17 @@ async function batchResolveSpecifiers(
 
   try {
     for (let specifier of specifiers) {
-      let resolutionResult = await resolverFactory.resolveFileAsync(importerPath, specifier)
+      let normalizedResolution = normalizeSpecifierResolution(specifier, importerPath)
+      let resolutionResult = await resolverFactory.resolveFileAsync(
+        normalizedResolution.importerPath,
+        normalizedResolution.specifier,
+      )
       if (resolutionResult.error) {
         throw createAssetServerCompilationError(
-          `Failed to resolve import "${specifier}" in ${importerPath}. ` +
-            `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
+          normalizedResolution.importerPath === getInjectedPackageImporterPath()
+            ? `Failed to resolve injected import "${specifier}" from asset server.`
+            : `Failed to resolve import "${normalizedResolution.specifier}" in ${normalizedResolution.importerPath}. ` +
+                `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
           {
             code: 'IMPORT_RESOLUTION_FAILED',
           },
@@ -370,6 +387,35 @@ function formatUnknownError(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+function normalizeSpecifierResolution(
+  specifier: string,
+  importerPath: string,
+): NormalizedSpecifierResolution {
+  let authoredInjectedPackageSpecifier = restoreAuthoredInjectedPackageSpecifier(specifier)
+  if (authoredInjectedPackageSpecifier) {
+    return {
+      importerPath,
+      specifier: authoredInjectedPackageSpecifier,
+    }
+  }
+
+  if (getInjectedPackageNameForSpecifier(specifier)) {
+    return {
+      importerPath: getInjectedPackageImporterPath(),
+      specifier,
+    }
+  }
+
+  return {
+    importerPath,
+    specifier,
+  }
+}
+
+function getDisplayImportSpecifier(specifier: string): string {
+  return restoreAuthoredInjectedPackageSpecifier(specifier) ?? specifier
+}
+
 function failResolve(
   error: unknown,
   trackedFiles: ReadonlySet<string>,