@jsenv/core 40.6.2 → 40.7.1

package/dist/start_dev_server/start_dev_server.js

@@ -1,10 +1,10 @@
 import { WebSocketResponse, pickContentType, ServerEvents, jsenvServiceCORS, jsenvAccessControlAllowedHeaders, composeTwoResponses, serveDirectory, jsenvServiceErrorHandler, startServer } from "@jsenv/server";
 import { convertFileSystemErrorToResponseProperties } from "@jsenv/server/src/internal/convertFileSystemErrorToResponseProperties.js";
-import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, moveUrl, urlIsInsideOf, ensureWindowsDriveLetter, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, setUrlFilename, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, applyNodeEsmResolution, RUNTIME_COMPAT, normalizeUrl, ANSI, CONTENT_TYPE, errorToHTML, DATA_URL, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, defaultLookupPackageScope, defaultReadPackageJson, readCustomConditionsFromProcessArgs, readEntryStatSync, urlToFilename, ensurePathnameTrailingSlash, compareFileUrls, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, isSpecifierForNodeBuiltin, memoizeByFirstArgument, assertAndNormalizeDirectoryUrl, createTaskLog, formatError, readPackageAtOrNull } from "./jsenv_core_packages.js";
+import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, moveUrl, urlIsOrIsInsideOf, ensureWindowsDriveLetter, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, setUrlFilename, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, applyNodeEsmResolution, RUNTIME_COMPAT, normalizeUrl, ANSI, CONTENT_TYPE, errorToHTML, DATA_URL, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, defaultLookupPackageScope, defaultReadPackageJson, readCustomConditionsFromProcessArgs, readEntryStatSync, ensurePathnameTrailingSlash, compareFileUrls, urlToFilename, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, isSpecifierForNodeBuiltin, memoizeByFirstArgument, assertAndNormalizeDirectoryUrl, createTaskLog, formatError, readPackageAtOrNull } from "./jsenv_core_packages.js";
 import { readFileSync, existsSync, readdirSync, lstatSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { generateSourcemapFileUrl, createMagicSource, composeTwoSourcemaps, generateSourcemapDataUrl, SOURCEMAP } from "@jsenv/sourcemap";
-import { parseHtml, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, stringifyHtmlAst, applyBabelPlugins, generateUrlForInlineContent, parseJsWithAcorn, parseCssUrls, getHtmlNodeAttribute, getHtmlNodePosition, getHtmlNodeAttributePosition, setHtmlNodeAttributes, parseSrcSet, getUrlForContentInsideHtml, removeHtmlNodeText, setHtmlNodeText, getHtmlNodeText, analyzeScriptNode, visitHtmlNodes, parseJsUrls, getUrlForContentInsideJs, analyzeLinkNode, injectJsenvScript } from "@jsenv/ast";
+import { parseHtml, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, stringifyHtmlAst, applyBabelPlugins, generateUrlForInlineContent, injectJsenvScript, parseJsWithAcorn, parseCssUrls, getHtmlNodeAttribute, getHtmlNodePosition, getHtmlNodeAttributePosition, setHtmlNodeAttributes, parseSrcSet, getUrlForContentInsideHtml, removeHtmlNodeText, setHtmlNodeText, getHtmlNodeText, analyzeScriptNode, visitHtmlNodes, parseJsUrls, getUrlForContentInsideJs, analyzeLinkNode } from "@jsenv/ast";
 import { performance } from "node:perf_hooks";
 import { jsenvPluginSupervisor } from "@jsenv/plugin-supervisor";
 import { jsenvPluginTranspilation } from "@jsenv/plugin-transpilation";
@@ -165,7 +165,7 @@ const watchSourceFiles = (
 
 const WEB_URL_CONVERTER = {
   asWebUrl: (fileUrl, webServer) => {
-    if (urlIsInsideOf(fileUrl, webServer.rootDirectoryUrl)) {
+    if (urlIsOrIsInsideOf(fileUrl, webServer.rootDirectoryUrl)) {
       return moveUrl({
         url: fileUrl,
         from: webServer.rootDirectoryUrl,
@@ -365,7 +365,7 @@ ${error.message}`,
       name: "TRANSFORM_URL_CONTENT_ERROR",
       code: "PARSE_ERROR",
       reason: error.message,
-      stack: error.stack,
+      stack: transformError.stack,
       trace,
       asResponse: error.asResponse,
     });
@@ -590,7 +590,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)}`;
   }
@@ -1898,6 +1898,7 @@ const createUrlInfo = (url, context) => {
     contentLength: undefined,
     contentFinalized: false,
     contentSideEffects: [],
+    contentInjections: {},
 
     sourcemap: null,
     sourcemapIsWrong: false,
@@ -2162,6 +2163,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,
 ) => {
@@ -2442,6 +2613,7 @@ const createUrlInfoTransformer = ({
       contentLength,
       sourcemap,
       sourcemapIsWrong,
+      contentInjections,
     } = transformations;
     if (type) {
       urlInfo.type = type;
@@ -2449,13 +2621,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) &&
@@ -2647,6 +2829,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;
   };
@@ -2792,6 +2983,7 @@ const createKitchen = ({
       inlineContentClientFileUrl,
       isSupportedOnCurrentClients: memoizeIsSupported(clientRuntimeCompat),
       isSupportedOnFutureClients: memoizeIsSupported(runtimeCompat),
+      isPlaceholderInjection,
       getPluginMeta: null,
       sourcemaps,
       outDirectoryUrl,
@@ -3632,10 +3824,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) {
@@ -3648,10 +3840,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);
@@ -3670,21 +3871,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 = {} } = {},
@@ -3707,7 +3915,7 @@ const createPluginController = (
       pluginCandidate.destroy?.();
       continue;
     }
-    const initPluginResult = initPlugin(pluginCandidate, kitchen);
+    const initPluginResult = await initPlugin(pluginCandidate, kitchen);
     if (!initPluginResult) {
       pluginCandidate.destroy?.();
       continue;
@@ -3759,6 +3967,7 @@ const createPluginController = (
         key === "serverEvents" ||
         key === "mustStayFirst" ||
         key === "devServerRoutes" ||
+        key === "devServerServices" ||
         key === "effect"
       ) {
         continue;
@@ -3932,6 +4141,7 @@ const createPluginController = (
 const HOOK_NAMES = [
   "init",
   "devServerRoutes", // is called only during dev/tests
+  "devServerServices", // is called only during dev/tests
   "resolveReference",
   "redirectReference",
   "transformReferenceSearchParams",
@@ -3986,12 +4196,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;
   }
@@ -4070,6 +4280,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}`,
           );
@@ -5848,10 +6061,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,
@@ -5877,103 +6087,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:
  * 
@@ -6004,6 +6117,7 @@ const htmlFileUrlForDirectory = import.meta.resolve(
 );
 
 const jsenvPluginDirectoryListing = ({
+  spa,
   urlMocks = false,
   autoreload = true,
   directoryContentMagicName,
@@ -6045,7 +6159,7 @@ const jsenvPluginDirectoryListing = ({
             return null;
           }
         }
-        return `${htmlFileUrlForDirectory}?url=${encodeURIComponent(url)}&enoent`;
+        return `${htmlFileUrlForDirectory}?url=${encodeURIComponent(requestedUrl)}&enoent`;
       }
       const isDirectory = fsStat?.isDirectory();
       if (!isDirectory) {
@@ -6071,34 +6185,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: [
@@ -6117,8 +6232,10 @@ const jsenvPluginDirectoryListing = ({
               directoryRelativeUrl,
               rootDirectoryUrl,
             );
-            const closestDirectoryUrl =
-              getFirstExistingDirectoryUrl(requestedUrl);
+            const closestDirectoryUrl = getFirstExistingDirectoryUrl(
+              requestedUrl,
+              rootDirectoryUrl,
+            );
             const sendMessage = (message) => {
               websocket.send(JSON.stringify(message));
             };
@@ -6176,8 +6293,9 @@ const jsenvPluginDirectoryListing = ({
 };
 
 const generateDirectoryListingInjection = (
-  requestedUrl,
+  urlNotFound,
   {
+    spa,
     rootDirectoryUrl,
     mainFilePath,
     packageDirectory,
@@ -6190,7 +6308,7 @@ const generateDirectoryListingInjection = (
 ) => {
   let serverRootDirectoryUrl = rootDirectoryUrl;
   const firstExistingDirectoryUrl = getFirstExistingDirectoryUrl(
-    requestedUrl,
+    urlNotFound,
     serverRootDirectoryUrl,
   );
   const directoryContentItems = getDirectoryContentItems({
@@ -6241,8 +6359,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);
@@ -6252,7 +6370,6 @@ const generateDirectoryListingInjection = (
     } else {
       parts = [rootDirectoryUrlName];
     }
-
     let i = 0;
     while (i < parts.length) {
       const part = parts[i];
@@ -6273,7 +6390,7 @@ const generateDirectoryListingInjection = (
         navItemUrl,
         serverRootDirectoryUrl,
       );
-      let urlRelativeToDocument = urlToRelativeUrl(navItemUrl, requestedUrl);
+      let urlRelativeToDocument = urlToRelativeUrl(navItemUrl, urlNotFound);
       const isServerRootDirectory = navItemUrl === serverRootDirectoryUrl;
       if (isServerRootDirectory) {
         urlRelativeToServer = `/${directoryContentMagicName}`;
@@ -6281,7 +6398,7 @@ const generateDirectoryListingInjection = (
       }
       const name = part;
       const isCurrent = navItemUrl === String(firstExistingDirectoryUrl);
-      navItems.push({
+      breadcrumb.push({
         url: navItemUrl,
         urlRelativeToServer,
         urlRelativeToDocument,
@@ -6291,34 +6408,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,
@@ -6331,16 +6461,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,
@@ -6384,6 +6514,7 @@ const getDirectoryContentItems = ({
 };
 
 const jsenvPluginFsRedirection = ({
+  spa,
   directoryContentMagicName,
   magicExtensions = ["inherit", ".js"],
   magicDirectoryIndex = true,
@@ -6473,11 +6604,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;
@@ -6527,9 +6666,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,
@@ -6541,6 +6700,7 @@ const jsenvPluginProtocolFile = ({
 }) => {
   return [
     jsenvPluginFsRedirection({
+      spa,
       directoryContentMagicName,
       magicExtensions,
       magicDirectoryIndex,
@@ -6596,6 +6756,7 @@ const jsenvPluginProtocolFile = ({
     ...(directoryListing
       ? [
           jsenvPluginDirectoryListing({
+            spa,
             ...directoryListing,
             directoryContentMagicName,
             rootDirectoryUrl,
@@ -6872,6 +7033,69 @@ const jsenvPluginDirectoryReferenceEffect = (
   };
 };
 
+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,
+        },
+      };
+    },
+  };
+};
+
 const jsenvPluginInliningAsDataUrl = () => {
   return {
     name: "jsenv:inlining_as_data_url",
@@ -7317,6 +7541,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?
  */
 
 
@@ -7422,14 +7648,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 {
@@ -7862,7 +8086,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:")) {
@@ -8437,6 +8661,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({
@@ -8672,6 +8897,7 @@ const getCorePlugins = ({
   transpilation = true,
   inlining = true,
   http = false,
+  spa,
 
   clientAutoreload,
   clientAutoreloadOnServerRestart,
@@ -8701,7 +8927,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()] : []),
@@ -8714,6 +8940,7 @@ const getCorePlugins = ({
      */
     jsenvPluginProtocolHttp(http),
     jsenvPluginProtocolFile({
+      spa,
       magicExtensions,
       magicDirectoryIndex,
       directoryListing,
@@ -8956,6 +9183,7 @@ const startDevServer = async ({
   ribbon = true,
   // toolbar = false,
   onKitchenCreated = () => {},
+  spa,
 
   sourcemaps = "inline",
   sourcemapsSourcesContent,
@@ -9106,7 +9334,7 @@ const startDevServer = async ({
       read: readPackageAtOrNull,
     };
 
-    const devServerPluginStore = createPluginStore([
+    const devServerPluginStore = await createPluginStore([
       jsenvPluginServerEvents({ clientAutoreload }),
       ...plugins,
       ...getCorePlugins({
@@ -9124,6 +9352,7 @@ const startDevServer = async ({
         supervisor,
         injections,
         transpilation,
+        spa,
 
         clientAutoreload,
         clientAutoreloadOnServerRestart,
@@ -9131,7 +9360,7 @@ const startDevServer = async ({
         ribbon,
       }),
     ]);
-    const getOrCreateKitchen = (request) => {
+    const getOrCreateKitchen = async (request) => {
       const { runtimeName, runtimeVersion } = parseUserAgentHeader(
         request.headers["user-agent"] || "",
       );
@@ -9253,7 +9482,7 @@ const startDevServer = async ({
           );
         },
       );
-      const devServerPluginController = createPluginController(
+      const devServerPluginController = await createPluginController(
         devServerPluginStore,
         kitchen,
       );
@@ -9269,8 +9498,8 @@ const startDevServer = async ({
 
     finalServices.push({
       name: "jsenv:dev_server_routes",
-      augmentRouteFetchSecondArg: (request) => {
-        const kitchen = getOrCreateKitchen(request);
+      augmentRouteFetchSecondArg: async (request) => {
+        const kitchen = await getOrCreateKitchen(request);
         return { kitchen };
       },
       routes: [
@@ -9473,6 +9702,7 @@ const startDevServer = async ({
         },
       ],
     });
+    finalServices.push(...devServerPluginStore.allDevServerServices);
   }
   // jsenv error handler service
   {
@@ -9501,7 +9731,7 @@ const startDevServer = async ({
           body: response.body,
         });
         return {
-          status: 200,
+          status: response.status,
           headers: {
             "content-type": "application/json",
             "content-length": Buffer.byteLength(body),