@jsenv/core 41.4.3 → 41.4.4

package/dist/build/build.js

@@ -2364,11 +2364,21 @@ ${urlInfo.url}`,
 
 const injectionSymbol = Symbol.for("jsenv_injection");
 const INJECTIONS = {
+  /**
+   * Inject `Object.assign(window, { [key]: value })` at the top of the file
+   * (into a script for html, into the module itself for js) instead of
+   * replacing a placeholder: the value is read at runtime as a global.
+   */
   global: (value) => {
     return { [injectionSymbol]: "global", value };
   },
+  /**
+   * Replace the placeholder when the file contains it, stay silent when it does not
+   * (without this a missing placeholder is reported as a warning).
+   */
   optional: (value) => {
-    if (value && value[injectionSymbol] === "optional") {
+    if (value && value[injectionSymbol]) {
+      // a global injection is not a placeholder, it can't be missing from the file
       return value;
     }
     return { [injectionSymbol]: "optional", value };
@@ -2473,12 +2483,7 @@ return {
       magicSource.replace({
         start,
         end,
-        replacement:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(value, null, "  ")
-            : value,
+        replacement: asReplacement(value, urlInfo),
       });
       index = content.indexOf(key, end);
     }
@@ -2486,6 +2491,19 @@ return {
   return magicSource.toContentAndSourcemap();
 };
 
+// In JS the placeholder stands for a value, so it must be substituted by a literal.
+// Everywhere else (html attributes and text, css, ...) it stands for a piece of text
+// and is substituted as-is, so it can be concatenated: href="__BACKEND_URL__/users/me"
+const asReplacement = (value, urlInfo) => {
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return JSON.stringify(value, null, "  ");
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value, null, "  ");
+};
+
 const injectGlobals = (content, globals, urlInfo) => {
   if (urlInfo.type === "html") {
     return globalInjectorOnHtml(content, globals, urlInfo);
@@ -6560,7 +6578,9 @@ const jsenvPluginVersionSearchParam = () => {
  * of them, the page switcher (cmd+K) opens one in the current tab. Whoever asks
  * gets the same answer.
  *
- * Each page comes with what kind of page it is, read from where it sits and
+ * Each page comes with where its file is (so it can be opened in an editor as
+ * well as in the browser) and with what kind of page it is, read from where it
+ * sits and
  * what it is called — the two conventions this repo already follows:
  * - "experiment": something tried out, under a lab/ directory or named
  *   *_experiment.html;
@@ -6659,6 +6679,10 @@ const createHtmlPageLister = ({ rootDirectoryUrl }) => {
       );
       return {
         url: `/${relativeUrl}`,
+        // Where the file actually is, so whoever wants to open it in an editor
+        // rather than in the browser has what GET /.internal/open_file/* asks
+        // for (a file url) without having to know the root directory.
+        fileUrl,
         kind: readKind(meta),
         // Relative to the root and without its trailing slash, which is how a
         // tree names its own nodes.
@@ -7212,6 +7236,10 @@ const jsenvPluginFsRedirection = ({
           }
           const { requestedUrl, rootDirectoryUrl, mainFilePath } =
             reference.ownerUrlInfo.context;
+          if (!requestedUrl) {
+            // the SPA fallback answers a request; during build there is none
+            return null;
+          }
           const closestHtmlRootFile = getClosestHtmlRootFile(
             requestedUrl,
             rootDirectoryUrl,
@@ -7624,18 +7652,45 @@ const jsenvPluginInjections = (rawAssociations) => {
           { injectionsGetter: rawAssociations },
           context.rootDirectoryUrl,
         );
-        getInjections = (urlInfo) => {
+        const findInjectionsGetter = (urlInfo) => {
           const { injectionsGetter } = URL_META.applyAssociations({
             url: asUrlWithoutSearch(urlInfo.url),
             associations: resolvedAssociations,
           });
-          if (!injectionsGetter) {
+          if (injectionsGetter) {
+            return { injectionsGetter, isInherited: false };
+          }
+          if (urlInfo.isInline) {
+            // content inlined into a file (a <script> inside html) is authored in that
+            // file, so injections configured for the file must reach it too
+            const found = findInjectionsGetter(
+              urlInfo.firstReference.ownerUrlInfo,
+            );
+            if (found) {
+              return {
+                injectionsGetter: found.injectionsGetter,
+                isInherited: true,
+              };
+            }
+          }
+          return null;
+        };
+        getInjections = async (urlInfo) => {
+          const found = findInjectionsGetter(urlInfo);
+          if (!found) {
             return null;
           }
+          const { injectionsGetter, isInherited } = found;
           if (typeof injectionsGetter !== "function") {
             throw new TypeError("injectionsGetter must be a function");
           }
-          return injectionsGetter(urlInfo);
+          const injections = await injectionsGetter(urlInfo);
+          if (!injections || !isInherited) {
+            return injections;
+          }
+          // the file holds several inline contents; a placeholder configured for the file
+          // is expected in one of them, not in each
+          return asOptionalInjections(injections);
         };
       }
     },
@@ -7646,13 +7701,12 @@ const jsenvPluginInjections = (rawAssociations) => {
           contentInjections: defaultInjections,
         };
       }
-      const injectionsResult = getInjections(urlInfo);
-      if (!injectionsResult) {
+      const injections = await getInjections(urlInfo);
+      if (!injections) {
         return {
           contentInjections: defaultInjections,
         };
       }
-      const injections = await injectionsResult;
       return {
         contentInjections: {
           ...defaultInjections,
@@ -7663,6 +7717,14 @@ const jsenvPluginInjections = (rawAssociations) => {
   };
 };
 
+const asOptionalInjections = (injections) => {
+  const optionalInjections = {};
+  for (const key of Object.keys(injections)) {
+    optionalInjections[key] = INJECTIONS.optional(injections[key]);
+  }
+  return optionalInjections;
+};
+
 /*
  * 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:
@@ -11064,6 +11126,11 @@ const createBuildSpecifierManager = ({
       registerHtmlRefine((htmlAst, { registerHtmlMutation }) => {
         visitHtmlNodes(htmlAst, {
           link: (node) => {
+            if (getHtmlNodeAttribute(node, "jsenv-ignore") !== undefined) {
+              // reference analysis skipped this node, so it has no urlInfo in the graph
+              // and there is nothing to resync
+              return;
+            }
             const href = getHtmlNodeAttribute(node, "href");
             if (href === undefined || href.startsWith("data:")) {
               return;
@@ -11902,6 +11969,25 @@ const jsenvPluginMappings = (mappings) => {
  *        How URLs are versioned for this entry point (defaults to "search_param")
  * @param {('none'|'inline'|'file'|'programmatic')} [entryPoint.sourcemaps]
  *        Sourcemap generation strategy for this entry point (defaults to "none")
+ * @param {object} [entryPoint.injections]
+ *        Values to inject into files, as { urlPattern: getInjections }.
+ *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
+ *        values are functions receiving urlInfo and returning (or resolving to)
+ *        an object of placeholders to replace, named `__LIKE_THIS__` by convention:
+ *
+ *          injections: {
+ *            "./index.html": () => ({ __BACKEND_URL__: "https://api.example.com" }),
+ *          }
+ *
+ *        In JS files the value is injected as a JS literal (a string value brings its own quotes),
+ *        everywhere else it is injected as-is, so it can be concatenated:
+ *        `href="__BACKEND_URL__/users/me"`.
+ *        An html url pattern also covers what is inlined in that html: an inline
+ *        `<script>window.backendUrl = __BACKEND_URL__;</script>` gets the JS literal,
+ *        which is how a value is shared with every js file of the page.
+ *        Use INJECTIONS.optional(value) for a placeholder that may be absent from the file
+ *        and INJECTIONS.global(value) to inject `Object.assign(window, { ... })` instead of
+ *        replacing a placeholder.
  *
  * @return {Promise<Object>} buildReturnValue
  * @return {Promise<Object>} [buildReturnValue.buildInlineContents]
@@ -11939,6 +12025,17 @@ const build = async ({
   {
     const unexpectedParamNames = Object.keys(rest);
     if (unexpectedParamNames.length > 0) {
+      const entryPointParamNames = unexpectedParamNames.filter((name) =>
+        Object.hasOwn(entryPointDefaultParams, name),
+      );
+      if (entryPointParamNames.length > 0) {
+        throw new TypeError(
+          `${entryPointParamNames.join(",")}: param(s) configured per entry point, move them into entryPoints, as in:
+entryPoints: {
+  "./index.html": { ${entryPointParamNames.map((name) => `${name}: ...`).join(", ")} },
+}`,
+        );
+      }
       throw new TypeError(
         `${unexpectedParamNames.join(",")}: there is no such param`,
       );

package/dist/js/page_switcher.js

@@ -2,6 +2,11 @@
  * cmd+K / ctrl+K on any dev-served page: the .html files the server serves, as a
  * tree one walks, filter as you type, Enter to go there.
  *
+ * cmd+E / ctrl+E is the other half of the same question: instead of going to a
+ * page, open its file in the editor (the server does it, see
+ * GET /.internal/open_file/*). Pressed on the page itself it opens the page one
+ * is on; pressed inside the switcher it opens the row one is looking at.
+ *
  * A tree rather than a list of paths, because the paths are mostly the same
  * path: folding every directory that holds a single thing turns
  * "packages/frontend/navi/src/layout/demos/…" repeated forty times into one
@@ -25,6 +30,10 @@
 // another injected client. A function scope owes nothing to anybody.
 (() => {
   const PAGES_ENDPOINT = "/.internal/pages.json";
+  // The server asks the OS to open a file in whatever editor is configured
+  // (VSCode here) — it takes a file url, which is why the page list carries one
+  // per page (see html_pages.js).
+  const OPEN_FILE_ENDPOINT = "/.internal/open_file/";
   const STORAGE_KEY = "jsenv_page_switcher";
   // Open across a reload: this is a dev tool on a page one is editing, and a hot
   // reload in the middle of looking for the next page should not close what one
@@ -56,15 +65,20 @@
     }
   };
 
-  const isSwitcherKey = (event) => {
-    if (event.key !== "k" && event.key !== "K") {
-      return false;
-    }
-    // cmd on mac, ctrl elsewhere — the same split every editor makes.
-    return window.navigator.platform.toLowerCase().includes("mac")
+  // cmd on mac, ctrl elsewhere — the same split every editor makes.
+  const isCommandKey = (event) =>
+    window.navigator.platform.toLowerCase().includes("mac")
       ? event.metaKey && !event.ctrlKey
       : event.ctrlKey && !event.metaKey;
-  };
+
+  const isSwitcherKey = (event) =>
+    (event.key === "k" || event.key === "K") && isCommandKey(event);
+  // E for edit, next to K for the same reason the two belong together: K asks
+  // "which page", E asks "where does this page live". Outside the switcher it
+  // means the page one is on; inside it, the row one is looking at — so the
+  // same press reads the same way in both places.
+  const isEditorKey = (event) =>
+    (event.key === "e" || event.key === "E") && isCommandKey(event);
 
   const STYLE_TEXT = /* css */ `
     :host {
@@ -230,6 +244,32 @@
     }
   `;
 
+  const FLASH_STYLE_TEXT = /* css */ `
+    :host {
+      position: fixed;
+      right: 16px;
+      bottom: 16px;
+      /* Above the switcher's own panel: it is the switcher that triggers it. */
+      z-index: 2147483647;
+      display: block;
+      font-family: system-ui, sans-serif;
+      pointer-events: none;
+    }
+    .flash {
+      padding: 8px 14px;
+      color: light-dark(#0f172a, #e2e8f0);
+      font-size: 13px;
+      background: light-dark(white, #1e293b);
+      border-radius: 8px;
+      box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+      color-scheme: light dark;
+    }
+    .flash[data-error] {
+      color: light-dark(#991b1b, #fecaca);
+      background: light-dark(#fee2e2, #7f1d1d);
+    }
+  `;
+
   let pagesPromise = null;
   const loadPages = () => {
     // Once per page load: the list is a filesystem scan behind a short cache
@@ -240,6 +280,54 @@
     return pagesPromise;
   };
 
+  // Opening a file in an editor happens in another application, on another
+  // screen sometimes: without a word here, a press that failed and a press that
+  // worked look exactly the same. Its own host and its own shadow root, so it
+  // can be shown whether or not the switcher is open.
+  let flashHost = null;
+  let flashBox = null;
+  let flashTimeout = null;
+  const flash = (message, isError) => {
+    if (!flashHost) {
+      flashHost = document.createElement("div");
+      const shadow = flashHost.attachShadow({ mode: "open" });
+      const style = document.createElement("style");
+      style.textContent = FLASH_STYLE_TEXT;
+      flashBox = document.createElement("div");
+      flashBox.className = "flash";
+      shadow.append(style, flashBox);
+    }
+    flashBox.textContent = message;
+    flashBox.toggleAttribute("data-error", Boolean(isError));
+    // Appended last every time, so it sits above the switcher's host when both
+    // are on the page and they share the same z-index.
+    document.body.append(flashHost);
+    window.clearTimeout(flashTimeout);
+    flashTimeout = window.setTimeout(() => flashHost.remove(), 2500);
+  };
+
+  const openInEditor = async (file) => {
+    if (!file || !file.fileUrl) {
+      flash("This page is not a file the server lists.", true);
+      return;
+    }
+    flash(`Opening ${file.name || file.url} in editor…`);
+    try {
+      const response = await fetch(
+        `${OPEN_FILE_ENDPOINT}${encodeURIComponent(file.fileUrl)}`,
+      );
+      if (response.status === 404) {
+        // The route exists only when the server is willing to expose the
+        // machine it runs on (see start_server.js).
+        flash("This server does not open files in an editor.", true);
+      } else if (!response.ok) {
+        flash(`Editor said no (${response.status}).`, true);
+      }
+    } catch {
+      flash("Could not reach the dev server.", true);
+    }
+  };
+
   const readStoredState = () => {
     try {
       const stored = JSON.parse(
@@ -396,7 +484,11 @@
     panel.className = "panel";
     const input = document.createElement("input");
     input.type = "search";
-    input.placeholder = "Go to page…";
+    // The other key is written where one is already looking: a shortcut nobody
+    // is told about is a shortcut nobody presses. Both names, not the one this
+    // platform uses — the reader knows which of the two their keyboard has, and
+    // it keeps what the panel says the same everywhere.
+    input.placeholder = "Go to page…  (cmd/ctrl+E to open in editor)";
     input.setAttribute("aria-label", "Go to page");
     const kindsRow = document.createElement("div");
     kindsRow.className = "kinds";
@@ -664,6 +756,21 @@
         toggleCollapsed(row.node.path);
         return;
       }
+      if (isEditorKey(event)) {
+        // Taken whatever the row is: let go of on a directory it would reach
+        // the page below and open the page one came from, which is not what a
+        // key pressed inside an open switcher can be asking for.
+        stop();
+        const row = rows[currentIndex];
+        if (!row || row.type !== "file") {
+          return;
+        }
+        // Done with the switcher: the answer to "where does this live" arrives
+        // in the editor, not here.
+        close();
+        openInEditor(row.file);
+        return;
+      }
       if (isSwitcherKey(event)) {
         stop();
         close();
@@ -708,15 +815,31 @@
   // preventDefault, the key was theirs and nothing happens here.
   const listenSwitcherKey = () => {
     window.addEventListener("keydown", (event) => {
-      if (event.defaultPrevented || !isSwitcherKey(event)) {
+      if (event.defaultPrevented) {
         return;
       }
-      // Ours now: the browser has its own use for cmd+K (the address bar), which
-      // it must not get.
-      event.preventDefault();
-      openSwitcher();
+      if (isSwitcherKey(event)) {
+        // Ours now: the browser has its own use for cmd+K (the address bar),
+        // which it must not get.
+        event.preventDefault();
+        openSwitcher();
+        return;
+      }
+      if (isEditorKey(event)) {
+        event.preventDefault();
+        openCurrentPageInEditor();
+      }
     });
   };
+  // The page one is looking at, in the editor. The list is where the file url
+  // comes from, so a page the server does not list (an @fs url, something under
+  // node_modules) says so rather than opening the wrong thing.
+  const openCurrentPageInEditor = async () => {
+    const here = currentPageUrl();
+    const pages = await loadPages();
+    const page = pages.find((candidate) => candidate.url === here);
+    openInEditor(page && { ...page, name: here.split("/").pop() });
+  };
   const setup = () => {
     listenSwitcherKey();
     if (wasOpen()) {

package/dist/jsenv_core.js

@@ -3,11 +3,21 @@ import "@jsenv/sourcemap";
 
 const injectionSymbol = Symbol.for("jsenv_injection");
 const INJECTIONS = {
+  /**
+   * Inject `Object.assign(window, { [key]: value })` at the top of the file
+   * (into a script for html, into the module itself for js) instead of
+   * replacing a placeholder: the value is read at runtime as a global.
+   */
   global: (value) => {
     return { [injectionSymbol]: "global", value };
   },
+  /**
+   * Replace the placeholder when the file contains it, stay silent when it does not
+   * (without this a missing placeholder is reported as a warning).
+   */
   optional: (value) => {
-    if (value && value[injectionSymbol] === "optional") {
+    if (value && value[injectionSymbol]) {
+      // a global injection is not a placeholder, it can't be missing from the file
       return value;
     }
     return { [injectionSymbol]: "optional", value };

package/dist/start_dev_server/start_dev_server.js

@@ -1321,7 +1321,9 @@ const jsenvPluginClientMonitoring = () => {
 
 /*
  * cmd+K (ctrl+K elsewhere) on any page the dev server serves opens a list of
- * the .html files it serves, filter as you type, Enter to go there.
+ * the .html files it serves, filter as you type, Enter to go there. cmd+E
+ * (ctrl+E elsewhere) opens a page's file in the editor instead of going to it:
+ * the current page from anywhere, the selected row from inside the switcher.
  *
  * The list is the one the filesystem plugin already publishes for everyone
  * (GET /.internal/pages.json, see protocol_file/html_pages.js) — this only adds
@@ -3327,7 +3329,9 @@ const FILE_AND_SERVER_URLS_CONVERTER = {
  * of them, the page switcher (cmd+K) opens one in the current tab. Whoever asks
  * gets the same answer.
  *
- * Each page comes with what kind of page it is, read from where it sits and
+ * Each page comes with where its file is (so it can be opened in an editor as
+ * well as in the browser) and with what kind of page it is, read from where it
+ * sits and
  * what it is called — the two conventions this repo already follows:
  * - "experiment": something tried out, under a lab/ directory or named
  *   *_experiment.html;
@@ -3426,6 +3430,10 @@ const createHtmlPageLister = ({ rootDirectoryUrl }) => {
       );
       return {
         url: `/${relativeUrl}`,
+        // Where the file actually is, so whoever wants to open it in an editor
+        // rather than in the browser has what GET /.internal/open_file/* asks
+        // for (a file url) without having to know the root directory.
+        fileUrl,
         kind: readKind(meta),
         // Relative to the root and without its trailing slash, which is how a
         // tree names its own nodes.
@@ -4092,6 +4100,10 @@ const jsenvPluginFsRedirection = ({
           }
           const { requestedUrl, rootDirectoryUrl, mainFilePath } =
             reference.ownerUrlInfo.context;
+          if (!requestedUrl) {
+            // the SPA fallback answers a request; during build there is none
+            return null;
+          }
           const closestHtmlRootFile = getClosestHtmlRootFile(
             requestedUrl,
             rootDirectoryUrl,
@@ -4986,11 +4998,21 @@ const jsenvPluginDirectoryReferenceEffect = (
 
 const injectionSymbol = Symbol.for("jsenv_injection");
 const INJECTIONS = {
+  /**
+   * Inject `Object.assign(window, { [key]: value })` at the top of the file
+   * (into a script for html, into the module itself for js) instead of
+   * replacing a placeholder: the value is read at runtime as a global.
+   */
   global: (value) => {
     return { [injectionSymbol]: "global", value };
   },
+  /**
+   * Replace the placeholder when the file contains it, stay silent when it does not
+   * (without this a missing placeholder is reported as a warning).
+   */
   optional: (value) => {
-    if (value && value[injectionSymbol] === "optional") {
+    if (value && value[injectionSymbol]) {
+      // a global injection is not a placeholder, it can't be missing from the file
       return value;
     }
     return { [injectionSymbol]: "optional", value };
@@ -5095,12 +5117,7 @@ return {
       magicSource.replace({
         start,
         end,
-        replacement:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(value, null, "  ")
-            : value,
+        replacement: asReplacement(value, urlInfo),
       });
       index = content.indexOf(key, end);
     }
@@ -5108,6 +5125,19 @@ return {
   return magicSource.toContentAndSourcemap();
 };
 
+// In JS the placeholder stands for a value, so it must be substituted by a literal.
+// Everywhere else (html attributes and text, css, ...) it stands for a piece of text
+// and is substituted as-is, so it can be concatenated: href="__BACKEND_URL__/users/me"
+const asReplacement = (value, urlInfo) => {
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return JSON.stringify(value, null, "  ");
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value, null, "  ");
+};
+
 const injectGlobals = (content, globals, urlInfo) => {
   if (urlInfo.type === "html") {
     return globalInjectorOnHtml(content, globals, urlInfo);
@@ -5181,18 +5211,45 @@ const jsenvPluginInjections = (rawAssociations) => {
           { injectionsGetter: rawAssociations },
           context.rootDirectoryUrl,
         );
-        getInjections = (urlInfo) => {
+        const findInjectionsGetter = (urlInfo) => {
           const { injectionsGetter } = URL_META.applyAssociations({
             url: asUrlWithoutSearch(urlInfo.url),
             associations: resolvedAssociations,
           });
-          if (!injectionsGetter) {
+          if (injectionsGetter) {
+            return { injectionsGetter, isInherited: false };
+          }
+          if (urlInfo.isInline) {
+            // content inlined into a file (a <script> inside html) is authored in that
+            // file, so injections configured for the file must reach it too
+            const found = findInjectionsGetter(
+              urlInfo.firstReference.ownerUrlInfo,
+            );
+            if (found) {
+              return {
+                injectionsGetter: found.injectionsGetter,
+                isInherited: true,
+              };
+            }
+          }
+          return null;
+        };
+        getInjections = async (urlInfo) => {
+          const found = findInjectionsGetter(urlInfo);
+          if (!found) {
             return null;
           }
+          const { injectionsGetter, isInherited } = found;
           if (typeof injectionsGetter !== "function") {
             throw new TypeError("injectionsGetter must be a function");
           }
-          return injectionsGetter(urlInfo);
+          const injections = await injectionsGetter(urlInfo);
+          if (!injections || !isInherited) {
+            return injections;
+          }
+          // the file holds several inline contents; a placeholder configured for the file
+          // is expected in one of them, not in each
+          return asOptionalInjections(injections);
         };
       }
     },
@@ -5203,13 +5260,12 @@ const jsenvPluginInjections = (rawAssociations) => {
           contentInjections: defaultInjections,
         };
       }
-      const injectionsResult = getInjections(urlInfo);
-      if (!injectionsResult) {
+      const injections = await getInjections(urlInfo);
+      if (!injections) {
         return {
           contentInjections: defaultInjections,
         };
       }
-      const injections = await injectionsResult;
       return {
         contentInjections: {
           ...defaultInjections,
@@ -5220,6 +5276,14 @@ const jsenvPluginInjections = (rawAssociations) => {
   };
 };
 
+const asOptionalInjections = (injections) => {
+  const optionalInjections = {};
+  for (const key of Object.keys(injections)) {
+    optionalInjections[key] = INJECTIONS.optional(injections[key]);
+  }
+  return optionalInjections;
+};
+
 const jsenvPluginInliningAsDataUrl = () => {
   return {
     name: "jsenv:inlining_as_data_url",
@@ -11434,6 +11498,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
  * @param {boolean} [params.supervisor=true] - Script supervisor (better error reporting).
  * @param {boolean|object} [params.directoryListing=true] - Directory listing pages.
+ * @param {object} [params.injections] - Values to inject into files, as `{ urlPattern: getInjections }`. Keys are url patterns relative to sourceDirectoryUrl (`"./index.html"`, `"**\/*.js"`), values are functions receiving `urlInfo` and returning (or resolving to) an object of placeholders to replace, named `__LIKE_THIS__` by convention. In JS the value is injected as a JS literal (a string brings its own quotes), everywhere else as-is so it can be concatenated: `href="__BACKEND_URL__/users/me"`. An html url pattern also covers what is inlined in that html, so `<script>window.backendUrl = __BACKEND_URL__;</script>` shares the value with every js file of the page. See `INJECTIONS.optional` and `INJECTIONS.global`.
  * @param {object} [params.runtimeCompat] - Target runtimes; warns when dev code wouldn't survive the build.
  * @param {string} [params.sourcemaps="inline"] - Sourcemap mode.
  * @param {AbortSignal} [params.signal] - Abort to stop the server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "41.4.3",
+  "version": "41.4.4",
   "type": "module",
   "description": "Tool to develop, test and build js projects",
   "repository": {

package/src/build/build.js

@@ -133,6 +133,25 @@ import { jsenvPluginMappings } from "./jsenv_plugin_mappings.js";
  *        How URLs are versioned for this entry point (defaults to "search_param")
  * @param {('none'|'inline'|'file'|'programmatic')} [entryPoint.sourcemaps]
  *        Sourcemap generation strategy for this entry point (defaults to "none")
+ * @param {object} [entryPoint.injections]
+ *        Values to inject into files, as { urlPattern: getInjections }.
+ *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
+ *        values are functions receiving urlInfo and returning (or resolving to)
+ *        an object of placeholders to replace, named `__LIKE_THIS__` by convention:
+ *
+ *          injections: {
+ *            "./index.html": () => ({ __BACKEND_URL__: "https://api.example.com" }),
+ *          }
+ *
+ *        In JS files the value is injected as a JS literal (a string value brings its own quotes),
+ *        everywhere else it is injected as-is, so it can be concatenated:
+ *        `href="__BACKEND_URL__/users/me"`.
+ *        An html url pattern also covers what is inlined in that html: an inline
+ *        `<script>window.backendUrl = __BACKEND_URL__;</script>` gets the JS literal,
+ *        which is how a value is shared with every js file of the page.
+ *        Use INJECTIONS.optional(value) for a placeholder that may be absent from the file
+ *        and INJECTIONS.global(value) to inject `Object.assign(window, { ... })` instead of
+ *        replacing a placeholder.
  *
  * @return {Promise<Object>} buildReturnValue
  * @return {Promise<Object>} [buildReturnValue.buildInlineContents]
@@ -170,6 +189,17 @@ export const build = async ({
   {
     const unexpectedParamNames = Object.keys(rest);
     if (unexpectedParamNames.length > 0) {
+      const entryPointParamNames = unexpectedParamNames.filter((name) =>
+        Object.hasOwn(entryPointDefaultParams, name),
+      );
+      if (entryPointParamNames.length > 0) {
+        throw new TypeError(
+          `${entryPointParamNames.join(",")}: param(s) configured per entry point, move them into entryPoints, as in:
+entryPoints: {
+  "./index.html": { ${entryPointParamNames.map((name) => `${name}: ...`).join(", ")} },
+}`,
+        );
+      }
       throw new TypeError(
         `${unexpectedParamNames.join(",")}: there is no such param`,
       );

package/src/build/build_specifier_manager.js

@@ -898,6 +898,11 @@ export const createBuildSpecifierManager = ({
       registerHtmlRefine((htmlAst, { registerHtmlMutation }) => {
         visitHtmlNodes(htmlAst, {
           link: (node) => {
+            if (getHtmlNodeAttribute(node, "jsenv-ignore") !== undefined) {
+              // reference analysis skipped this node, so it has no urlInfo in the graph
+              // and there is nothing to resync
+              return;
+            }
             const href = getHtmlNodeAttribute(node, "href");
             if (href === undefined || href.startsWith("data:")) {
               return;

package/src/dev/start_dev_server.js

@@ -51,6 +51,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
  * @param {boolean} [params.supervisor=true] - Script supervisor (better error reporting).
  * @param {boolean|object} [params.directoryListing=true] - Directory listing pages.
+ * @param {object} [params.injections] - Values to inject into files, as `{ urlPattern: getInjections }`. Keys are url patterns relative to sourceDirectoryUrl (`"./index.html"`, `"**\/*.js"`), values are functions receiving `urlInfo` and returning (or resolving to) an object of placeholders to replace, named `__LIKE_THIS__` by convention. In JS the value is injected as a JS literal (a string brings its own quotes), everywhere else as-is so it can be concatenated: `href="__BACKEND_URL__/users/me"`. An html url pattern also covers what is inlined in that html, so `<script>window.backendUrl = __BACKEND_URL__;</script>` shares the value with every js file of the page. See `INJECTIONS.optional` and `INJECTIONS.global`.
  * @param {object} [params.runtimeCompat] - Target runtimes; warns when dev code wouldn't survive the build.
  * @param {string} [params.sourcemaps="inline"] - Sourcemap mode.
  * @param {AbortSignal} [params.signal] - Abort to stop the server.

package/src/kitchen/url_graph/url_info_injections.js

@@ -3,11 +3,21 @@ import { composeTwoSourcemaps, createMagicSource } from "@jsenv/sourcemap";
 
 const injectionSymbol = Symbol.for("jsenv_injection");
 export const INJECTIONS = {
+  /**
+   * Inject `Object.assign(window, { [key]: value })` at the top of the file
+   * (into a script for html, into the module itself for js) instead of
+   * replacing a placeholder: the value is read at runtime as a global.
+   */
   global: (value) => {
     return { [injectionSymbol]: "global", value };
   },
+  /**
+   * Replace the placeholder when the file contains it, stay silent when it does not
+   * (without this a missing placeholder is reported as a warning).
+   */
   optional: (value) => {
-    if (value && value[injectionSymbol] === "optional") {
+    if (value && value[injectionSymbol]) {
+      // a global injection is not a placeholder, it can't be missing from the file
       return value;
     }
     return { [injectionSymbol]: "optional", value };
@@ -112,12 +122,7 @@ return {
       magicSource.replace({
         start,
         end,
-        replacement:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(value, null, "  ")
-            : value,
+        replacement: asReplacement(value, urlInfo),
       });
       index = content.indexOf(key, end);
     }
@@ -125,6 +130,19 @@ return {
   return magicSource.toContentAndSourcemap();
 };
 
+// In JS the placeholder stands for a value, so it must be substituted by a literal.
+// Everywhere else (html attributes and text, css, ...) it stands for a piece of text
+// and is substituted as-is, so it can be concatenated: href="__BACKEND_URL__/users/me"
+const asReplacement = (value, urlInfo) => {
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return JSON.stringify(value, null, "  ");
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value, null, "  ");
+};
+
 export const injectGlobals = (content, globals, urlInfo) => {
   if (urlInfo.type === "html") {
     return globalInjectorOnHtml(content, globals, urlInfo);

package/src/plugins/injections/jsenv_plugin_injections.js

@@ -26,18 +26,45 @@ export const jsenvPluginInjections = (rawAssociations) => {
           { injectionsGetter: rawAssociations },
           context.rootDirectoryUrl,
         );
-        getInjections = (urlInfo) => {
+        const findInjectionsGetter = (urlInfo) => {
           const { injectionsGetter } = URL_META.applyAssociations({
             url: asUrlWithoutSearch(urlInfo.url),
             associations: resolvedAssociations,
           });
-          if (!injectionsGetter) {
+          if (injectionsGetter) {
+            return { injectionsGetter, isInherited: false };
+          }
+          if (urlInfo.isInline) {
+            // content inlined into a file (a <script> inside html) is authored in that
+            // file, so injections configured for the file must reach it too
+            const found = findInjectionsGetter(
+              urlInfo.firstReference.ownerUrlInfo,
+            );
+            if (found) {
+              return {
+                injectionsGetter: found.injectionsGetter,
+                isInherited: true,
+              };
+            }
+          }
+          return null;
+        };
+        getInjections = async (urlInfo) => {
+          const found = findInjectionsGetter(urlInfo);
+          if (!found) {
             return null;
           }
+          const { injectionsGetter, isInherited } = found;
           if (typeof injectionsGetter !== "function") {
             throw new TypeError("injectionsGetter must be a function");
           }
-          return injectionsGetter(urlInfo);
+          const injections = await injectionsGetter(urlInfo);
+          if (!injections || !isInherited) {
+            return injections;
+          }
+          // the file holds several inline contents; a placeholder configured for the file
+          // is expected in one of them, not in each
+          return asOptionalInjections(injections);
         };
       }
     },
@@ -48,13 +75,12 @@ export const jsenvPluginInjections = (rawAssociations) => {
           contentInjections: defaultInjections,
         };
       }
-      const injectionsResult = getInjections(urlInfo);
-      if (!injectionsResult) {
+      const injections = await getInjections(urlInfo);
+      if (!injections) {
         return {
           contentInjections: defaultInjections,
         };
       }
-      const injections = await injectionsResult;
       return {
         contentInjections: {
           ...defaultInjections,
@@ -64,3 +90,11 @@ export const jsenvPluginInjections = (rawAssociations) => {
     },
   };
 };
+
+const asOptionalInjections = (injections) => {
+  const optionalInjections = {};
+  for (const key of Object.keys(injections)) {
+    optionalInjections[key] = INJECTIONS.optional(injections[key]);
+  }
+  return optionalInjections;
+};

package/src/plugins/page_switcher/client/page_switcher.js

@@ -2,6 +2,11 @@
  * cmd+K / ctrl+K on any dev-served page: the .html files the server serves, as a
  * tree one walks, filter as you type, Enter to go there.
  *
+ * cmd+E / ctrl+E is the other half of the same question: instead of going to a
+ * page, open its file in the editor (the server does it, see
+ * GET /.internal/open_file/*). Pressed on the page itself it opens the page one
+ * is on; pressed inside the switcher it opens the row one is looking at.
+ *
  * A tree rather than a list of paths, because the paths are mostly the same
  * path: folding every directory that holds a single thing turns
  * "packages/frontend/navi/src/layout/demos/…" repeated forty times into one
@@ -25,6 +30,10 @@
 // another injected client. A function scope owes nothing to anybody.
 (() => {
   const PAGES_ENDPOINT = "/.internal/pages.json";
+  // The server asks the OS to open a file in whatever editor is configured
+  // (VSCode here) — it takes a file url, which is why the page list carries one
+  // per page (see html_pages.js).
+  const OPEN_FILE_ENDPOINT = "/.internal/open_file/";
   const STORAGE_KEY = "jsenv_page_switcher";
   // Open across a reload: this is a dev tool on a page one is editing, and a hot
   // reload in the middle of looking for the next page should not close what one
@@ -56,15 +65,20 @@
     }
   };
 
-  const isSwitcherKey = (event) => {
-    if (event.key !== "k" && event.key !== "K") {
-      return false;
-    }
-    // cmd on mac, ctrl elsewhere — the same split every editor makes.
-    return window.navigator.platform.toLowerCase().includes("mac")
+  // cmd on mac, ctrl elsewhere — the same split every editor makes.
+  const isCommandKey = (event) =>
+    window.navigator.platform.toLowerCase().includes("mac")
       ? event.metaKey && !event.ctrlKey
       : event.ctrlKey && !event.metaKey;
-  };
+
+  const isSwitcherKey = (event) =>
+    (event.key === "k" || event.key === "K") && isCommandKey(event);
+  // E for edit, next to K for the same reason the two belong together: K asks
+  // "which page", E asks "where does this page live". Outside the switcher it
+  // means the page one is on; inside it, the row one is looking at — so the
+  // same press reads the same way in both places.
+  const isEditorKey = (event) =>
+    (event.key === "e" || event.key === "E") && isCommandKey(event);
 
   const STYLE_TEXT = /* css */ `
     :host {
@@ -230,6 +244,32 @@
     }
   `;
 
+  const FLASH_STYLE_TEXT = /* css */ `
+    :host {
+      position: fixed;
+      right: 16px;
+      bottom: 16px;
+      /* Above the switcher's own panel: it is the switcher that triggers it. */
+      z-index: 2147483647;
+      display: block;
+      font-family: system-ui, sans-serif;
+      pointer-events: none;
+    }
+    .flash {
+      padding: 8px 14px;
+      color: light-dark(#0f172a, #e2e8f0);
+      font-size: 13px;
+      background: light-dark(white, #1e293b);
+      border-radius: 8px;
+      box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+      color-scheme: light dark;
+    }
+    .flash[data-error] {
+      color: light-dark(#991b1b, #fecaca);
+      background: light-dark(#fee2e2, #7f1d1d);
+    }
+  `;
+
   let pagesPromise = null;
   const loadPages = () => {
     // Once per page load: the list is a filesystem scan behind a short cache
@@ -240,6 +280,54 @@
     return pagesPromise;
   };
 
+  // Opening a file in an editor happens in another application, on another
+  // screen sometimes: without a word here, a press that failed and a press that
+  // worked look exactly the same. Its own host and its own shadow root, so it
+  // can be shown whether or not the switcher is open.
+  let flashHost = null;
+  let flashBox = null;
+  let flashTimeout = null;
+  const flash = (message, isError) => {
+    if (!flashHost) {
+      flashHost = document.createElement("div");
+      const shadow = flashHost.attachShadow({ mode: "open" });
+      const style = document.createElement("style");
+      style.textContent = FLASH_STYLE_TEXT;
+      flashBox = document.createElement("div");
+      flashBox.className = "flash";
+      shadow.append(style, flashBox);
+    }
+    flashBox.textContent = message;
+    flashBox.toggleAttribute("data-error", Boolean(isError));
+    // Appended last every time, so it sits above the switcher's host when both
+    // are on the page and they share the same z-index.
+    document.body.append(flashHost);
+    window.clearTimeout(flashTimeout);
+    flashTimeout = window.setTimeout(() => flashHost.remove(), 2500);
+  };
+
+  const openInEditor = async (file) => {
+    if (!file || !file.fileUrl) {
+      flash("This page is not a file the server lists.", true);
+      return;
+    }
+    flash(`Opening ${file.name || file.url} in editor…`);
+    try {
+      const response = await fetch(
+        `${OPEN_FILE_ENDPOINT}${encodeURIComponent(file.fileUrl)}`,
+      );
+      if (response.status === 404) {
+        // The route exists only when the server is willing to expose the
+        // machine it runs on (see start_server.js).
+        flash("This server does not open files in an editor.", true);
+      } else if (!response.ok) {
+        flash(`Editor said no (${response.status}).`, true);
+      }
+    } catch {
+      flash("Could not reach the dev server.", true);
+    }
+  };
+
   const readStoredState = () => {
     try {
       const stored = JSON.parse(
@@ -396,7 +484,11 @@
     panel.className = "panel";
     const input = document.createElement("input");
     input.type = "search";
-    input.placeholder = "Go to page…";
+    // The other key is written where one is already looking: a shortcut nobody
+    // is told about is a shortcut nobody presses. Both names, not the one this
+    // platform uses — the reader knows which of the two their keyboard has, and
+    // it keeps what the panel says the same everywhere.
+    input.placeholder = "Go to page…  (cmd/ctrl+E to open in editor)";
     input.setAttribute("aria-label", "Go to page");
     const kindsRow = document.createElement("div");
     kindsRow.className = "kinds";
@@ -664,6 +756,21 @@
         toggleCollapsed(row.node.path);
         return;
       }
+      if (isEditorKey(event)) {
+        // Taken whatever the row is: let go of on a directory it would reach
+        // the page below and open the page one came from, which is not what a
+        // key pressed inside an open switcher can be asking for.
+        stop();
+        const row = rows[currentIndex];
+        if (!row || row.type !== "file") {
+          return;
+        }
+        // Done with the switcher: the answer to "where does this live" arrives
+        // in the editor, not here.
+        close();
+        openInEditor(row.file);
+        return;
+      }
       if (isSwitcherKey(event)) {
         stop();
         close();
@@ -708,15 +815,31 @@
   // preventDefault, the key was theirs and nothing happens here.
   const listenSwitcherKey = () => {
     window.addEventListener("keydown", (event) => {
-      if (event.defaultPrevented || !isSwitcherKey(event)) {
+      if (event.defaultPrevented) {
         return;
       }
-      // Ours now: the browser has its own use for cmd+K (the address bar), which
-      // it must not get.
-      event.preventDefault();
-      openSwitcher();
+      if (isSwitcherKey(event)) {
+        // Ours now: the browser has its own use for cmd+K (the address bar),
+        // which it must not get.
+        event.preventDefault();
+        openSwitcher();
+        return;
+      }
+      if (isEditorKey(event)) {
+        event.preventDefault();
+        openCurrentPageInEditor();
+      }
     });
   };
+  // The page one is looking at, in the editor. The list is where the file url
+  // comes from, so a page the server does not list (an @fs url, something under
+  // node_modules) says so rather than opening the wrong thing.
+  const openCurrentPageInEditor = async () => {
+    const here = currentPageUrl();
+    const pages = await loadPages();
+    const page = pages.find((candidate) => candidate.url === here);
+    openInEditor(page && { ...page, name: here.split("/").pop() });
+  };
   const setup = () => {
     listenSwitcherKey();
     if (wasOpen()) {

package/src/plugins/page_switcher/jsenv_plugin_page_switcher.js

@@ -1,6 +1,8 @@
 /*
  * cmd+K (ctrl+K elsewhere) on any page the dev server serves opens a list of
- * the .html files it serves, filter as you type, Enter to go there.
+ * the .html files it serves, filter as you type, Enter to go there. cmd+E
+ * (ctrl+E elsewhere) opens a page's file in the editor instead of going to it:
+ * the current page from anywhere, the selected row from inside the switcher.
  *
  * The list is the one the filesystem plugin already publishes for everyone
  * (GET /.internal/pages.json, see protocol_file/html_pages.js) — this only adds

package/src/plugins/protocol_file/html_pages.js

@@ -6,7 +6,9 @@
  * of them, the page switcher (cmd+K) opens one in the current tab. Whoever asks
  * gets the same answer.
  *
- * Each page comes with what kind of page it is, read from where it sits and
+ * Each page comes with where its file is (so it can be opened in an editor as
+ * well as in the browser) and with what kind of page it is, read from where it
+ * sits and
  * what it is called — the two conventions this repo already follows:
  * - "experiment": something tried out, under a lab/ directory or named
  *   *_experiment.html;
@@ -107,6 +109,10 @@ export const createHtmlPageLister = ({ rootDirectoryUrl }) => {
       );
       return {
         url: `/${relativeUrl}`,
+        // Where the file actually is, so whoever wants to open it in an editor
+        // rather than in the browser has what GET /.internal/open_file/* asks
+        // for (a file url) without having to know the root directory.
+        fileUrl,
         kind: readKind(meta),
         // Relative to the root and without its trailing slash, which is how a
         // tree names its own nodes.

package/src/plugins/protocol_file/jsenv_plugin_fs_redirection.js

@@ -98,6 +98,10 @@ export const jsenvPluginFsRedirection = ({
           }
           const { requestedUrl, rootDirectoryUrl, mainFilePath } =
             reference.ownerUrlInfo.context;
+          if (!requestedUrl) {
+            // the SPA fallback answers a request; during build there is none
+            return null;
+          }
           const closestHtmlRootFile = getClosestHtmlRootFile(
             requestedUrl,
             rootDirectoryUrl,