@jsenv/core 40.6.2 → 40.7.1

package/dist/build/build.js

@@ -1,10 +1,10 @@
-import { parseHtml, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, stringifyHtmlAst, applyBabelPlugins, generateUrlForInlineContent, parseJsWithAcorn, visitHtmlNodes, analyzeScriptNode, getHtmlNodeText, getHtmlNodeAttribute, getHtmlNodePosition, getUrlForContentInsideHtml, setHtmlNodeAttributes, setHtmlNodeText, parseCssUrls, getHtmlNodeAttributePosition, parseSrcSet, removeHtmlNodeText, parseJsUrls, getUrlForContentInsideJs, analyzeLinkNode, injectJsenvScript, findHtmlNode, removeHtmlNode, insertHtmlNodeAfter } from "@jsenv/ast";
+import { parseHtml, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, stringifyHtmlAst, applyBabelPlugins, generateUrlForInlineContent, injectJsenvScript, parseJsWithAcorn, visitHtmlNodes, analyzeScriptNode, getHtmlNodeText, getHtmlNodeAttribute, getHtmlNodePosition, getUrlForContentInsideHtml, setHtmlNodeAttributes, setHtmlNodeText, parseCssUrls, getHtmlNodeAttributePosition, parseSrcSet, removeHtmlNodeText, parseJsUrls, getUrlForContentInsideJs, analyzeLinkNode, findHtmlNode, removeHtmlNode, insertHtmlNodeAfter } from "@jsenv/ast";
 import { jsenvPluginBundling } from "@jsenv/plugin-bundling";
 import { jsenvPluginMinification } from "@jsenv/plugin-minification";
 import { jsenvPluginTranspilation, jsenvPluginJsModuleFallback } from "@jsenv/plugin-transpilation";
 import { memoryUsage } from "node:process";
 import { readFileSync, existsSync, readdirSync, lstatSync, realpathSync } from "node:fs";
-import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, urlIsInsideOf, ensureWindowsDriveLetter, setUrlFilename, moveUrl, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, applyNodeEsmResolution, RUNTIME_COMPAT, normalizeUrl, ANSI, CONTENT_TYPE, urlToFilename, DATA_URL, errorToHTML, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, defaultLookupPackageScope, defaultReadPackageJson, readCustomConditionsFromProcessArgs, readEntryStatSync, ensurePathnameTrailingSlash, compareFileUrls, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, isSpecifierForNodeBuiltin, renderDetails, humanizeDuration, humanizeFileSize, renderTable, renderBigSection, distributePercentages, humanizeMemory, comparePathnames, UNICODE, escapeRegexpSpecialChars, injectQueryParamIntoSpecifierWithoutEncoding, renderUrlOrRelativeUrlFilename, injectQueryParams, assertAndNormalizeDirectoryUrl, Abort, raceProcessTeardownEvents, startMonitoringCpuUsage, startMonitoringMemoryUsage, createLookupPackageDirectory, readPackageAtOrNull, inferRuntimeCompatFromClosestPackage, browserDefaultRuntimeCompat, nodeDefaultRuntimeCompat, clearDirectorySync, createTaskLog, ensureEmptyDirectory, updateJsonFileSync, createDynamicLog } from "./jsenv_core_packages.js";
+import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, urlIsOrIsInsideOf, ensureWindowsDriveLetter, setUrlFilename, moveUrl, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, applyNodeEsmResolution, RUNTIME_COMPAT, normalizeUrl, ANSI, CONTENT_TYPE, urlToFilename, DATA_URL, errorToHTML, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, defaultLookupPackageScope, defaultReadPackageJson, readCustomConditionsFromProcessArgs, readEntryStatSync, ensurePathnameTrailingSlash, compareFileUrls, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, isSpecifierForNodeBuiltin, renderDetails, humanizeDuration, humanizeFileSize, renderTable, renderBigSection, distributePercentages, humanizeMemory, comparePathnames, UNICODE, escapeRegexpSpecialChars, injectQueryParamIntoSpecifierWithoutEncoding, renderUrlOrRelativeUrlFilename, injectQueryParams, assertAndNormalizeDirectoryUrl, Abort, raceProcessTeardownEvents, startMonitoringCpuUsage, startMonitoringMemoryUsage, createLookupPackageDirectory, readPackageAtOrNull, inferRuntimeCompatFromClosestPackage, browserDefaultRuntimeCompat, nodeDefaultRuntimeCompat, clearDirectorySync, createTaskLog, ensureEmptyDirectory, updateJsonFileSync, createDynamicLog } from "./jsenv_core_packages.js";
 import { pathToFileURL } from "node:url";
 import { generateSourcemapFileUrl, createMagicSource, composeTwoSourcemaps, generateSourcemapDataUrl, SOURCEMAP } from "@jsenv/sourcemap";
 import { performance } from "node:perf_hooks";
@@ -306,7 +306,7 @@ ${error.message}`,
       name: "TRANSFORM_URL_CONTENT_ERROR",
       code: "PARSE_ERROR",
       reason: error.message,
-      stack: error.stack,
+      stack: transformError.stack,
       trace,
       asResponse: error.asResponse,
     });
@@ -531,7 +531,7 @@ const determineFileUrlForOutDirectory = (urlInfo) => {
   if (!url.startsWith("file:")) {
     return url;
   }
-  if (!urlIsInsideOf(url, rootDirectoryUrl)) {
+  if (!urlIsOrIsInsideOf(url, rootDirectoryUrl)) {
     const fsRootUrl = ensureWindowsDriveLetter("file:///", url);
     url = `${rootDirectoryUrl}@fs/${url.slice(fsRootUrl.length)}`;
   }
@@ -1858,6 +1858,7 @@ const createUrlInfo = (url, context) => {
     contentLength: undefined,
     contentFinalized: false,
     contentSideEffects: [],
+    contentInjections: {},
 
     sourcemap: null,
     sourcemapIsWrong: false,
@@ -2122,6 +2123,176 @@ ${urlInfo.url}`,
   return urlInfo;
 };
 
+const injectionSymbol = Symbol.for("jsenv_injection");
+const INJECTIONS = {
+  global: (value) => {
+    return { [injectionSymbol]: "global", value };
+  },
+  optional: (value) => {
+    return { [injectionSymbol]: "optional", value };
+  },
+};
+
+const isPlaceholderInjection = (value) => {
+  return (
+    !value || !value[injectionSymbol] || value[injectionSymbol] !== "global"
+  );
+};
+
+const applyContentInjections = (content, contentInjections, urlInfo) => {
+  const keys = Object.keys(contentInjections);
+  const globals = {};
+  const placeholderReplacements = [];
+  for (const key of keys) {
+    const contentInjection = contentInjections[key];
+    if (contentInjection && contentInjection[injectionSymbol]) {
+      const valueBehindSymbol = contentInjection[injectionSymbol];
+      if (valueBehindSymbol === "global") {
+        globals[key] = contentInjection.value;
+      } else if (valueBehindSymbol === "optional") {
+        placeholderReplacements.push({
+          key,
+          isOptional: true,
+          value: contentInjection.value,
+        });
+      } else {
+        throw new Error(`unknown injection type "${valueBehindSymbol}"`);
+      }
+    } else {
+      placeholderReplacements.push({
+        key,
+        value: contentInjection,
+      });
+    }
+  }
+
+  const needGlobalsInjection = Object.keys(globals).length > 0;
+  const needPlaceholderReplacements = placeholderReplacements.length > 0;
+
+  if (needGlobalsInjection && needPlaceholderReplacements) {
+    const globalInjectionResult = injectGlobals(content, globals, urlInfo);
+    const replaceInjectionResult = injectPlaceholderReplacements(
+      globalInjectionResult.content,
+      placeholderReplacements,
+      urlInfo,
+    );
+    return {
+      content: replaceInjectionResult.content,
+      sourcemap: composeTwoSourcemaps(
+        globalInjectionResult.sourcemap,
+        replaceInjectionResult.sourcemap,
+      ),
+    };
+  }
+  if (needGlobalsInjection) {
+    return injectGlobals(content, globals, urlInfo);
+  }
+  if (needPlaceholderReplacements) {
+    return injectPlaceholderReplacements(
+      content,
+      placeholderReplacements,
+      urlInfo,
+    );
+  }
+  return null;
+};
+
+const injectPlaceholderReplacements = (
+  content,
+  placeholderReplacements,
+  urlInfo,
+) => {
+  const magicSource = createMagicSource(content);
+  for (const { key, isOptional, value } of placeholderReplacements) {
+    let index = content.indexOf(key);
+    if (index === -1) {
+      if (!isOptional) {
+        urlInfo.context.logger.warn(
+          `placeholder "${key}" not found in ${urlInfo.url}.
+--- suggestion a ---
+Add "${key}" in that file.
+--- suggestion b ---
+Fix eventual typo in "${key}"?
+--- suggestion c ---
+Mark injection as optional using INJECTIONS.optional():
+import { INJECTIONS } from "@jsenv/core";
+
+return {
+  "${key}": INJECTIONS.optional(${JSON.stringify(value)}),
+};`,
+        );
+      }
+      continue;
+    }
+
+    while (index !== -1) {
+      const start = index;
+      const end = index + key.length;
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" ||
+          urlInfo.type === "js_module" ||
+          urlInfo.type === "html"
+            ? JSON.stringify(value, null, "  ")
+            : value,
+      });
+      index = content.indexOf(key, end);
+    }
+  }
+  return magicSource.toContentAndSourcemap();
+};
+
+const injectGlobals = (content, globals, urlInfo) => {
+  if (urlInfo.type === "html") {
+    return globalInjectorOnHtml(content, globals, urlInfo);
+  }
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return globalsInjectorOnJs(content, globals, urlInfo);
+  }
+  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
+};
+const globalInjectorOnHtml = (content, globals, urlInfo) => {
+  // ideally we would inject an importmap but browser support is too low
+  // (even worse for worker/service worker)
+  // so for now we inject code into entry points
+  const htmlAst = parseHtml({
+    html: content,
+    url: urlInfo.url,
+    storeOriginalPositions: false,
+  });
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker: false,
+  });
+  injectJsenvScript(htmlAst, {
+    content: clientCode,
+    pluginName: "jsenv:inject_globals",
+  });
+  return {
+    content: stringifyHtmlAst(htmlAst),
+  };
+};
+const globalsInjectorOnJs = (content, globals, urlInfo) => {
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker:
+      urlInfo.subtype === "worker" ||
+      urlInfo.subtype === "service_worker" ||
+      urlInfo.subtype === "shared_worker",
+  });
+  const magicSource = createMagicSource(content);
+  magicSource.prepend(clientCode);
+  return magicSource.toContentAndSourcemap();
+};
+const generateClientCodeForGlobals = (globals, { isWebWorker = false }) => {
+  const globalName = isWebWorker ? "self" : "window";
+  return `Object.assign(${globalName}, ${JSON.stringify(
+    globals,
+    null,
+    "  ",
+  )});`;
+};
+
 const defineGettersOnPropertiesDerivedFromOriginalContent = (
   urlInfo,
 ) => {
@@ -2402,6 +2573,7 @@ const createUrlInfoTransformer = ({
       contentLength,
       sourcemap,
       sourcemapIsWrong,
+      contentInjections,
     } = transformations;
     if (type) {
       urlInfo.type = type;
@@ -2409,13 +2581,23 @@ const createUrlInfoTransformer = ({
     if (contentType) {
       urlInfo.contentType = contentType;
     }
-    const contentModified = setContentProperties(urlInfo, {
-      content,
-      contentAst,
-      contentEtag,
-      contentLength,
-    });
-
+    if (Object.hasOwn(transformations, "contentInjections")) {
+      if (contentInjections) {
+        Object.assign(urlInfo.contentInjections, contentInjections);
+      }
+      if (content === undefined) {
+        return;
+      }
+    }
+    let contentModified;
+    if (Object.hasOwn(transformations, "content")) {
+      contentModified = setContentProperties(urlInfo, {
+        content,
+        contentAst,
+        contentEtag,
+        contentLength,
+      });
+    }
     if (
       sourcemap &&
       mayHaveSourcemap(urlInfo) &&
@@ -2607,6 +2789,15 @@ const createUrlInfoTransformer = ({
     if (transformations) {
       applyTransformations(urlInfo, transformations);
     }
+    const { contentInjections } = urlInfo;
+    if (contentInjections && Object.keys(contentInjections).length > 0) {
+      const injectionTransformations = applyContentInjections(
+        urlInfo.content,
+        contentInjections,
+        urlInfo,
+      );
+      applyTransformations(urlInfo, injectionTransformations);
+    }
     applyContentEffects(urlInfo);
     urlInfo.contentFinalized = true;
   };
@@ -2752,6 +2943,7 @@ const createKitchen = ({
       inlineContentClientFileUrl,
       isSupportedOnCurrentClients: memoizeIsSupported(clientRuntimeCompat),
       isSupportedOnFutureClients: memoizeIsSupported(runtimeCompat),
+      isPlaceholderInjection,
       getPluginMeta: null,
       sourcemaps,
       outDirectoryUrl,
@@ -3927,10 +4119,10 @@ const generateHtmlForSyntaxError = (
     errorLinkText: `${htmlRelativeUrl}:${line}:${column}`,
     syntaxErrorHTML: errorToHTML(htmlErrorContentFrame),
   };
-  const html = replacePlaceholders$1(htmlForSyntaxError, replacers);
+  const html = replacePlaceholders(htmlForSyntaxError, replacers);
   return html;
 };
-const replacePlaceholders$1 = (html, replacers) => {
+const replacePlaceholders = (html, replacers) => {
   return html.replace(/\$\{(\w+)\}/g, (match, name) => {
     const replacer = replacers[name];
     if (replacer === undefined) {
@@ -3943,10 +4135,19 @@ const replacePlaceholders$1 = (html, replacers) => {
   });
 };
 
-const createPluginStore = (plugins) => {
+const createPluginStore = async (plugins) => {
   const allDevServerRoutes = [];
+  const allDevServerServices = [];
   const pluginArray = [];
-  const addPlugin = (plugin) => {
+
+  const pluginPromises = [];
+  const addPlugin = async (plugin) => {
+    if (plugin && typeof plugin.then === "function") {
+      pluginPromises.push(plugin);
+      const value = await plugin;
+      addPlugin(value);
+      return;
+    }
     if (Array.isArray(plugin)) {
       for (const subplugin of plugin) {
         addPlugin(subplugin);
@@ -3965,21 +4166,28 @@ const createPluginStore = (plugins) => {
         allDevServerRoutes.push(devServerRoute);
       }
     }
+    if (plugin.devServerServices) {
+      const devServerServices = plugin.devServerServices;
+      for (const devServerService of devServerServices) {
+        allDevServerServices.push(devServerService);
+      }
+    }
     pluginArray.push(plugin);
   };
   addPlugin(jsenvPluginHtmlSyntaxErrorFallback());
   for (const plugin of plugins) {
     addPlugin(plugin);
   }
+  await Promise.all(pluginPromises);
 
   return {
     pluginArray,
-
     allDevServerRoutes,
+    allDevServerServices,
   };
 };
 
-const createPluginController = (
+const createPluginController = async (
   pluginStore,
   kitchen,
   { initialPuginsMeta = {} } = {},
@@ -4002,7 +4210,7 @@ const createPluginController = (
       pluginCandidate.destroy?.();
       continue;
     }
-    const initPluginResult = initPlugin(pluginCandidate, kitchen);
+    const initPluginResult = await initPlugin(pluginCandidate, kitchen);
     if (!initPluginResult) {
       pluginCandidate.destroy?.();
       continue;
@@ -4054,6 +4262,7 @@ const createPluginController = (
         key === "serverEvents" ||
         key === "mustStayFirst" ||
         key === "devServerRoutes" ||
+        key === "devServerServices" ||
         key === "effect"
       ) {
         continue;
@@ -4227,6 +4436,7 @@ const createPluginController = (
 const HOOK_NAMES = [
   "init",
   "devServerRoutes", // is called only during dev/tests
+  "devServerServices", // is called only during dev/tests
   "resolveReference",
   "redirectReference",
   "transformReferenceSearchParams",
@@ -4281,12 +4491,12 @@ const testAppliesDuring = (plugin, kitchen) => {
     `"appliesDuring" must be an object or a string, got ${appliesDuring}`,
   );
 };
-const initPlugin = (plugin, kitchen) => {
+const initPlugin = async (plugin, kitchen) => {
   const { init } = plugin;
   if (!init) {
     return true;
   }
-  const initReturnValue = init(kitchen.context, { plugin });
+  const initReturnValue = await init(kitchen.context, { plugin });
   if (initReturnValue === false) {
     return false;
   }
@@ -4365,6 +4575,9 @@ const returnValueAssertions = [
           return undefined;
         }
         if (typeof content !== "string" && !Buffer.isBuffer(content) && !body) {
+          if (Object.hasOwn(valueReturned, "contentInjections")) {
+            return undefined;
+          }
           throw new Error(
             `Unexpected "content" returned by "${hook.plugin.name}" ${hook.name} hook: it must be a string or a buffer; got ${content}`,
           );
@@ -6143,10 +6356,7 @@ const jsenvPluginVersionSearchParam = () => {
 
 const FILE_AND_SERVER_URLS_CONVERTER = {
   asServerUrl: (fileUrl, serverRootDirectoryUrl) => {
-    if (fileUrl === serverRootDirectoryUrl) {
-      return "/";
-    }
-    if (urlIsInsideOf(fileUrl, serverRootDirectoryUrl)) {
+    if (urlIsOrIsInsideOf(fileUrl, serverRootDirectoryUrl)) {
       const urlRelativeToServer = urlToRelativeUrl(
         fileUrl,
         serverRootDirectoryUrl,
@@ -6172,103 +6382,6 @@ const FILE_AND_SERVER_URLS_CONVERTER = {
   },
 };
 
-const jsenvPluginInjections = (rawAssociations) => {
-  let resolvedAssociations;
-
-  return {
-    name: "jsenv:injections",
-    appliesDuring: "*",
-    init: (context) => {
-      resolvedAssociations = URL_META.resolveAssociations(
-        { injectionsGetter: rawAssociations },
-        context.rootDirectoryUrl,
-      );
-    },
-    transformUrlContent: async (urlInfo) => {
-      const { injectionsGetter } = URL_META.applyAssociations({
-        url: asUrlWithoutSearch(urlInfo.url),
-        associations: resolvedAssociations,
-      });
-      if (!injectionsGetter) {
-        return null;
-      }
-      if (typeof injectionsGetter !== "function") {
-        throw new TypeError("injectionsGetter must be a function");
-      }
-      const injections = await injectionsGetter(urlInfo);
-      if (!injections) {
-        return null;
-      }
-      const keys = Object.keys(injections);
-      if (keys.length === 0) {
-        return null;
-      }
-      return replacePlaceholders(urlInfo.content, injections, urlInfo);
-    },
-  };
-};
-
-const injectionSymbol = Symbol.for("jsenv_injection");
-const INJECTIONS = {
-  optional: (value) => {
-    return { [injectionSymbol]: "optional", value };
-  },
-};
-
-// we export this because it is imported by jsenv_plugin_placeholder.js and unit test
-const replacePlaceholders = (content, replacements, urlInfo) => {
-  const magicSource = createMagicSource(content);
-  for (const key of Object.keys(replacements)) {
-    let index = content.indexOf(key);
-    const replacement = replacements[key];
-    let isOptional;
-    let value;
-    if (replacement && replacement[injectionSymbol]) {
-      const valueBehindSymbol = replacement[injectionSymbol];
-      isOptional = valueBehindSymbol === "optional";
-      value = replacement.value;
-    } else {
-      value = replacement;
-    }
-    if (index === -1) {
-      if (!isOptional) {
-        urlInfo.context.logger.warn(
-          `placeholder "${key}" not found in ${urlInfo.url}.
---- suggestion a ---
-Add "${key}" in that file.
---- suggestion b ---
-Fix eventual typo in "${key}"?
---- suggestion c ---
-Mark injection as optional using INJECTIONS.optional():
-import { INJECTIONS } from "@jsenv/core";
-
-return {
-  "${key}": INJECTIONS.optional(${JSON.stringify(value)}),
-};`,
-        );
-      }
-      continue;
-    }
-
-    while (index !== -1) {
-      const start = index;
-      const end = index + key.length;
-      magicSource.replace({
-        start,
-        end,
-        replacement:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(value, null, "  ")
-            : value,
-      });
-      index = content.indexOf(key, end);
-    }
-  }
-  return magicSource.toContentAndSourcemap();
-};
-
 /*
  * NICE TO HAVE:
  * 
@@ -6299,6 +6412,7 @@ const htmlFileUrlForDirectory = import.meta.resolve(
 );
 
 const jsenvPluginDirectoryListing = ({
+  spa,
   urlMocks = false,
   autoreload = true,
   directoryContentMagicName,
@@ -6340,7 +6454,7 @@ const jsenvPluginDirectoryListing = ({
             return null;
           }
         }
-        return `${htmlFileUrlForDirectory}?url=${encodeURIComponent(url)}&enoent`;
+        return `${htmlFileUrlForDirectory}?url=${encodeURIComponent(requestedUrl)}&enoent`;
       }
       const isDirectory = fsStat?.isDirectory();
       if (!isDirectory) {
@@ -6366,34 +6480,35 @@ const jsenvPluginDirectoryListing = ({
         if (urlWithoutSearch !== String(htmlFileUrlForDirectory)) {
           return null;
         }
-        const requestedUrl = urlInfo.searchParams.get("url");
-        if (!requestedUrl) {
+        const urlNotFound = urlInfo.searchParams.get("url");
+        if (!urlNotFound) {
           return null;
         }
+
         urlInfo.headers["cache-control"] = "no-cache";
         const enoent = urlInfo.searchParams.has("enoent");
         if (enoent) {
           urlInfo.status = 404;
-          urlInfo.headers["cache-control"] = "no-cache";
         }
         const request = urlInfo.context.request;
         const { rootDirectoryUrl, mainFilePath } = urlInfo.context;
-        return replacePlaceholders(
-          urlInfo.content,
+        const directoryListingInjections = generateDirectoryListingInjection(
+          urlNotFound,
           {
-            ...generateDirectoryListingInjection(requestedUrl, {
-              autoreload,
-              request,
-              urlMocks,
-              directoryContentMagicName,
-              rootDirectoryUrl,
-              mainFilePath,
-              packageDirectory,
-              enoent,
-            }),
+            spa,
+            autoreload,
+            request,
+            urlMocks,
+            directoryContentMagicName,
+            rootDirectoryUrl,
+            mainFilePath,
+            packageDirectory,
+            enoent,
           },
-          urlInfo,
         );
+        return {
+          contentInjections: directoryListingInjections,
+        };
       },
     },
     devServerRoutes: [
@@ -6412,8 +6527,10 @@ const jsenvPluginDirectoryListing = ({
               directoryRelativeUrl,
               rootDirectoryUrl,
             );
-            const closestDirectoryUrl =
-              getFirstExistingDirectoryUrl(requestedUrl);
+            const closestDirectoryUrl = getFirstExistingDirectoryUrl(
+              requestedUrl,
+              rootDirectoryUrl,
+            );
             const sendMessage = (message) => {
               websocket.send(JSON.stringify(message));
             };
@@ -6471,8 +6588,9 @@ const jsenvPluginDirectoryListing = ({
 };
 
 const generateDirectoryListingInjection = (
-  requestedUrl,
+  urlNotFound,
   {
+    spa,
     rootDirectoryUrl,
     mainFilePath,
     packageDirectory,
@@ -6485,7 +6603,7 @@ const generateDirectoryListingInjection = (
 ) => {
   let serverRootDirectoryUrl = rootDirectoryUrl;
   const firstExistingDirectoryUrl = getFirstExistingDirectoryUrl(
-    requestedUrl,
+    urlNotFound,
     serverRootDirectoryUrl,
   );
   const directoryContentItems = getDirectoryContentItems({
@@ -6536,8 +6654,8 @@ const generateDirectoryListingInjection = (
   const { host } = new URL(request.url);
   const websocketUrl = `${websocketScheme}://${host}/.internal/directory_content.websocket?directory=${encodeURIComponent(directoryUrlRelativeToServer)}`;
 
-  const navItems = [];
-  {
+  const generateBreadcrumb = () => {
+    const breadcrumb = [];
     const lastItemUrl = firstExistingDirectoryUrl;
     const lastItemRelativeUrl = urlToRelativeUrl(lastItemUrl, rootDirectoryUrl);
     const rootDirectoryUrlName = urlToFilename(rootDirectoryUrl);
@@ -6547,7 +6665,6 @@ const generateDirectoryListingInjection = (
     } else {
       parts = [rootDirectoryUrlName];
     }
-
     let i = 0;
     while (i < parts.length) {
       const part = parts[i];
@@ -6568,7 +6685,7 @@ const generateDirectoryListingInjection = (
         navItemUrl,
         serverRootDirectoryUrl,
       );
-      let urlRelativeToDocument = urlToRelativeUrl(navItemUrl, requestedUrl);
+      let urlRelativeToDocument = urlToRelativeUrl(navItemUrl, urlNotFound);
       const isServerRootDirectory = navItemUrl === serverRootDirectoryUrl;
       if (isServerRootDirectory) {
         urlRelativeToServer = `/${directoryContentMagicName}`;
@@ -6576,7 +6693,7 @@ const generateDirectoryListingInjection = (
       }
       const name = part;
       const isCurrent = navItemUrl === String(firstExistingDirectoryUrl);
-      navItems.push({
+      breadcrumb.push({
         url: navItemUrl,
         urlRelativeToServer,
         urlRelativeToDocument,
@@ -6586,34 +6703,47 @@ const generateDirectoryListingInjection = (
       });
       i++;
     }
-  }
+    return breadcrumb;
+  };
+  const breadcrumb = generateBreadcrumb();
 
   let enoentDetails = null;
   if (enoent) {
+    const buildEnoentPathInfo = (urlBase, closestExistingUrl) => {
+      let filePathExisting;
+      let filePathNotFound;
+      const existingIndex = String(closestExistingUrl).length;
+      filePathExisting = urlToRelativeUrl(
+        closestExistingUrl,
+        serverRootDirectoryUrl,
+      );
+      filePathNotFound = urlBase.slice(existingIndex);
+      return [filePathExisting, filePathNotFound];
+    };
     const fileRelativeUrl = urlToRelativeUrl(
-      requestedUrl,
+      urlNotFound,
       serverRootDirectoryUrl,
     );
-    let filePathExisting;
-    let filePathNotFound;
-    const existingIndex = String(firstExistingDirectoryUrl).length;
-    filePathExisting = urlToRelativeUrl(
-      firstExistingDirectoryUrl,
-      serverRootDirectoryUrl,
-    );
-    filePathNotFound = requestedUrl.slice(existingIndex);
     enoentDetails = {
-      fileUrl: requestedUrl,
+      fileUrl: urlNotFound,
       fileRelativeUrl,
+    };
+
+    const [filePathExisting, filePathNotFound] = buildEnoentPathInfo(
+      urlNotFound,
+      firstExistingDirectoryUrl,
+    );
+    Object.assign(enoentDetails, {
       filePathExisting: `/${filePathExisting}`,
       filePathNotFound,
-    };
+    });
   }
 
   return {
     __DIRECTORY_LISTING__: {
+      spa,
       enoentDetails,
-      navItems,
+      breadcrumb,
       urlMocks,
       directoryContentMagicName,
       directoryUrl: firstExistingDirectoryUrl,
@@ -6626,16 +6756,16 @@ const generateDirectoryListingInjection = (
     },
   };
 };
-const getFirstExistingDirectoryUrl = (requestedUrl, serverRootDirectoryUrl) => {
-  let firstExistingDirectoryUrl = new URL("./", requestedUrl);
-  while (!existsSync(firstExistingDirectoryUrl)) {
-    firstExistingDirectoryUrl = new URL("../", firstExistingDirectoryUrl);
-    if (!urlIsInsideOf(firstExistingDirectoryUrl, serverRootDirectoryUrl)) {
-      firstExistingDirectoryUrl = new URL(serverRootDirectoryUrl);
+const getFirstExistingDirectoryUrl = (urlBase, serverRootDirectoryUrl) => {
+  let directoryUrlCandidate = new URL("./", urlBase);
+  while (!existsSync(directoryUrlCandidate)) {
+    directoryUrlCandidate = new URL("../", directoryUrlCandidate);
+    if (!urlIsOrIsInsideOf(directoryUrlCandidate, serverRootDirectoryUrl)) {
+      directoryUrlCandidate = new URL(serverRootDirectoryUrl);
       break;
     }
   }
-  return firstExistingDirectoryUrl;
+  return directoryUrlCandidate;
 };
 const getDirectoryContentItems = ({
   serverRootDirectoryUrl,
@@ -6679,6 +6809,7 @@ const getDirectoryContentItems = ({
 };
 
 const jsenvPluginFsRedirection = ({
+  spa,
   directoryContentMagicName,
   magicExtensions = ["inherit", ".js"],
   magicDirectoryIndex = true,
@@ -6768,11 +6899,19 @@ const jsenvPluginFsRedirection = ({
         // 3. The url pathname does not ends with "/"
         //    In that case we assume client explicitely asks to load a directory
         if (
+          spa &&
           !urlToExtension(urlObject) &&
           !urlToPathname(urlObject).endsWith("/")
         ) {
-          const { mainFilePath, rootDirectoryUrl } =
+          const { requestedUrl, rootDirectoryUrl, mainFilePath } =
             reference.ownerUrlInfo.context;
+          const closestHtmlRootFile = getClosestHtmlRootFile(
+            requestedUrl,
+            rootDirectoryUrl,
+          );
+          if (closestHtmlRootFile) {
+            return closestHtmlRootFile;
+          }
           return new URL(mainFilePath, rootDirectoryUrl);
         }
         return null;
@@ -6822,9 +6961,29 @@ const resolveSymlink = (fileUrl) => {
   return realUrlObject.href;
 };
 
+const getClosestHtmlRootFile = (requestedUrl, serverRootDirectoryUrl) => {
+  let directoryUrl = new URL("./", requestedUrl);
+  while (true) {
+    const indexHtmlFileUrl = new URL(`index.html`, directoryUrl);
+    if (existsSync(indexHtmlFileUrl)) {
+      return indexHtmlFileUrl.href;
+    }
+    const filename = urlToFilename(directoryUrl);
+    const htmlFileUrlCandidate = new URL(`${filename}.html`, directoryUrl);
+    if (existsSync(htmlFileUrlCandidate)) {
+      return htmlFileUrlCandidate.href;
+    }
+    if (!urlIsOrIsInsideOf(directoryUrl, serverRootDirectoryUrl)) {
+      return null;
+    }
+    directoryUrl = new URL("../", directoryUrl);
+  }
+};
+
 const directoryContentMagicName = "...";
 
 const jsenvPluginProtocolFile = ({
+  spa = true,
   magicExtensions,
   magicDirectoryIndex,
   preserveSymlinks,
@@ -6836,6 +6995,7 @@ const jsenvPluginProtocolFile = ({
 }) => {
   return [
     jsenvPluginFsRedirection({
+      spa,
       directoryContentMagicName,
       magicExtensions,
       magicDirectoryIndex,
@@ -6891,6 +7051,7 @@ const jsenvPluginProtocolFile = ({
     ...(directoryListing
       ? [
           jsenvPluginDirectoryListing({
+            spa,
             ...directoryListing,
             directoryContentMagicName,
             rootDirectoryUrl,
@@ -7085,6 +7246,69 @@ const asValidFilename = (string) => {
   return string;
 };
 
+const jsenvPluginInjections = (rawAssociations) => {
+  const getDefaultInjections = (urlInfo) => {
+    if (urlInfo.context.dev && urlInfo.type === "html") {
+      const relativeUrl = urlToRelativeUrl(
+        urlInfo.url,
+        urlInfo.context.rootDirectoryUrl,
+      );
+      return {
+        HTML_ROOT_PATHNAME: INJECTIONS.global(`/${relativeUrl}`),
+      };
+    }
+    return null;
+  };
+  let getInjections = null;
+
+  return {
+    name: "jsenv:injections",
+    appliesDuring: "*",
+    init: (context) => {
+      if (rawAssociations && Object.keys(rawAssociations).length > 0) {
+        const resolvedAssociations = URL_META.resolveAssociations(
+          { injectionsGetter: rawAssociations },
+          context.rootDirectoryUrl,
+        );
+        getInjections = (urlInfo) => {
+          const { injectionsGetter } = URL_META.applyAssociations({
+            url: asUrlWithoutSearch(urlInfo.url),
+            associations: resolvedAssociations,
+          });
+          if (!injectionsGetter) {
+            return null;
+          }
+          if (typeof injectionsGetter !== "function") {
+            throw new TypeError("injectionsGetter must be a function");
+          }
+          return injectionsGetter(urlInfo);
+        };
+      }
+    },
+    transformUrlContent: async (urlInfo) => {
+      const defaultInjections = getDefaultInjections(urlInfo);
+      if (!getInjections) {
+        return {
+          contentInjections: defaultInjections,
+        };
+      }
+      const injectionsResult = getInjections(urlInfo);
+      if (!injectionsResult) {
+        return {
+          contentInjections: defaultInjections,
+        };
+      }
+      const injections = await injectionsResult;
+      return {
+        contentInjections: {
+          ...defaultInjections,
+          ...injections,
+        },
+      };
+    },
+  };
+};
+
 /*
  * Some code uses globals specific to Node.js in code meant to run in browsers...
  * This plugin will replace some node globals to things compatible with web:
@@ -7277,6 +7501,8 @@ const babelPluginMetadataExpressionPaths = (
  * - replaced by true: When scenario matches (import.meta.dev and it's the dev server)
  * - left as is to be evaluated to undefined (import.meta.build but it's the dev server)
  * - replaced by undefined (import.meta.dev but it's build; the goal is to ensure it's tree-shaked)
+ *
+ * TODO: ideally during dev we would keep import.meta.dev and ensure we set it to true rather than replacing it with true?
  */
 
 
@@ -7382,14 +7608,12 @@ const babelPluginMetadataImportMetaScenarios = () => {
 
 const jsenvPluginGlobalScenarios = () => {
   const transformIfNeeded = (urlInfo) => {
-    return replacePlaceholders(
-      urlInfo.content,
-      {
+    return {
+      contentInjections: {
         __DEV__: INJECTIONS.optional(urlInfo.context.dev),
         __BUILD__: INJECTIONS.optional(urlInfo.context.build),
       },
-      urlInfo,
-    );
+    };
   };
 
   return {
@@ -7822,7 +8046,7 @@ const jsenvPluginAutoreloadServer = ({
     serverEvents: {
       reload: (serverEventInfo) => {
         const formatUrlForClient = (url) => {
-          if (urlIsInsideOf(url, serverEventInfo.rootDirectoryUrl)) {
+          if (urlIsOrIsInsideOf(url, serverEventInfo.rootDirectoryUrl)) {
             return urlToRelativeUrl(url, serverEventInfo.rootDirectoryUrl);
           }
           if (url.startsWith("file:")) {
@@ -8397,6 +8621,7 @@ const jsenvPluginChromeDevtoolsJson = () => {
     devServerRoutes: [
       {
         endpoint: "GET /.well-known/appspecific/com.chrome.devtools.json",
+        declarationSource: import.meta.url,
         fetch: (request, { kitchen }) => {
           const { rootDirectoryUrl } = kitchen.context;
           return Response.json({
@@ -8632,6 +8857,7 @@ const getCorePlugins = ({
   transpilation = true,
   inlining = true,
   http = false,
+  spa,
 
   clientAutoreload,
   clientAutoreloadOnServerRestart,
@@ -8661,7 +8887,7 @@ const getCorePlugins = ({
 
   return [
     jsenvPluginReferenceAnalysis(referenceAnalysis),
-    ...(injections ? [jsenvPluginInjections(injections)] : []),
+    jsenvPluginInjections(injections),
     jsenvPluginTranspilation(transpilation),
     // "jsenvPluginInlining" must be very soon because all other plugins will react differently once they see the file is inlined
     ...(inlining ? [jsenvPluginInlining()] : []),
@@ -8674,6 +8900,7 @@ const getCorePlugins = ({
      */
     jsenvPluginProtocolHttp(http),
     jsenvPluginProtocolFile({
+      spa,
       magicExtensions,
       magicDirectoryIndex,
       directoryListing,
@@ -9783,7 +10010,7 @@ const createBuildSpecifierManager = ({
         // const urlInfoInsideThisDirectorySet = new Set();
         const versionsInfluencingThisDirectorySet = new Set();
         for (const [url, urlInfo] of finalKitchen.graph.urlInfoMap) {
-          if (!urlIsInsideOf(url, directoryUrl)) {
+          if (!urlIsOrIsInsideOf(url, directoryUrl)) {
             continue;
           }
           // ideally we should exclude eventual directories as the are redundant
@@ -10182,7 +10409,7 @@ const createBuildSpecifierManager = ({
           }
           if (
             urlInfo.type === "asset" &&
-            urlIsInsideOf(urlInfo.url, buildDirectoryUrl)
+            urlIsOrIsInsideOf(urlInfo.url, buildDirectoryUrl)
           ) {
             return;
           }
@@ -10497,7 +10724,7 @@ const createBuildUrlsGenerator = ({
     if (buildUrlFromMap) {
       return buildUrlFromMap;
     }
-    if (urlIsInsideOf(url, buildDirectoryUrl)) {
+    if (urlIsOrIsInsideOf(url, buildDirectoryUrl)) {
       if (ownerUrlInfo.searchParams.has("dynamic_import_id")) {
         const ownerDirectoryPath = determineDirectoryPath({
           sourceDirectoryUrl,
@@ -10912,7 +11139,7 @@ const build = async ({
               );
             }
           }
-          if (!urlIsInsideOf(sourceUrl, sourceDirectoryUrl)) {
+          if (!urlIsOrIsInsideOf(sourceUrl, sourceDirectoryUrl)) {
             throw new Error(
               `The key "${key}" in "entryPoints" is invalid: it must be inside the source directory at ${sourceDirectoryUrl}.`,
             );
@@ -10963,7 +11190,7 @@ const build = async ({
                 `The buildRelativeUrl "${buildRelativeUrl}"${forEntryPointOrEmpty} is invalid: it must be a relative url.`,
               );
             }
-            if (!urlIsInsideOf(buildUrl, buildDirectoryUrl)) {
+            if (!urlIsOrIsInsideOf(buildUrl, buildDirectoryUrl)) {
               throw new Error(
                 `The buildRelativeUrl "${buildRelativeUrl}"${forEntryPointOrEmpty} is invalid: it must be inside the build directory at ${buildDirectoryUrl}.`,
               );
@@ -11463,7 +11690,7 @@ const build = async ({
           let hasSomeOutdatedSideEffectUrl = false;
           for (const packageSideEffectUrl of packageSideEffectUrlSet) {
             if (
-              urlIsInsideOf(packageSideEffectUrl, buildDirectoryUrl) &&
+              urlIsOrIsInsideOf(packageSideEffectUrl, buildDirectoryUrl) &&
               !buildSideEffectUrlSet.has(packageSideEffectUrl)
             ) {
               hasSomeOutdatedSideEffectUrl = true;
@@ -11763,7 +11990,7 @@ const prepareEntryPointBuild = async (
   });
 
   let _getOtherEntryBuildInfo;
-  const rawPluginStore = createPluginStore([
+  const rawPluginStore = await createPluginStore([
     ...(mappings ? [jsenvPluginMappings(mappings)] : []),
     {
       name: "jsenv:other_entry_point_build_during_craft",
@@ -11808,7 +12035,7 @@ const prepareEntryPointBuild = async (
       packageSideEffects,
     }),
   ]);
-  const rawPluginController = createPluginController(
+  const rawPluginController = await createPluginController(
     rawPluginStore,
     rawKitchen,
   );
@@ -11879,7 +12106,7 @@ const prepareEntryPointBuild = async (
           rawKitchen.graph.getUrlInfo(entryReference.url).type === "html" &&
           rawKitchen.context.isSupportedOnCurrentClients("importmap"),
       });
-      const finalPluginStore = createPluginStore([
+      const finalPluginStore = await createPluginStore([
         jsenvPluginReferenceAnalysis({
           ...referenceAnalysis,
           fetchInlineUrls: false,
@@ -11912,7 +12139,7 @@ const prepareEntryPointBuild = async (
         },
         buildSpecifierManager.jsenvPluginMoveToBuildDirectory,
       ]);
-      const finalPluginController = createPluginController(
+      const finalPluginController = await createPluginController(
         finalPluginStore,
         finalKitchen,
         {