@jsenv/core 41.4.3 → 41.4.5

package/dist/build/build.js

@@ -333,6 +333,7 @@ ${reason}`,
   }
   return createFailedToResolveUrlError({
     reason: `An error occured during specifier resolution`,
+    ...detailsFromInjectionsOnOwner(reference),
     ...detailsFromValueThrown(error),
   });
 };
@@ -394,6 +395,7 @@ ${reason}`,
       return createFailedToFetchUrlContentError({
         code: "NOT_FOUND",
         reason: "no entry on filesystem",
+        ...detailsFromInjectionsOnOwner(urlInfo.firstReference),
       });
     }
   }
@@ -626,6 +628,32 @@ const getFirstReferenceInProject = (reference) => {
   return getFirstReferenceInProject(firstReference);
 };
 
+// An url written by an injection cannot be resolved: the placeholder is still there
+// when references are analyzed. Rather than guessing what a placeholder looks like
+// (the key is free-form), tell the file it comes from: injections are configured for it.
+const detailsFromInjectionsOnOwner = (reference) => {
+  if (!reference) {
+    return {};
+  }
+  const ownerUrlInfo = reference.ownerUrlInfo;
+  if (ownerUrlInfo.type !== "html") {
+    // "jsenv-ignore" is an html attribute
+    return {};
+  }
+  const { hasInjections } = ownerUrlInfo.context;
+  if (!hasInjections || !hasInjections(ownerUrlInfo.url)) {
+    return {};
+  }
+  const { node, attributeName } = reference.astInfo || {};
+  if (!node || !attributeName) {
+    return {};
+  }
+  return {
+    suggestion: `injections are configured for this file; when "${reference.specifier}" is meant to be written by one of them, add "jsenv-ignore" so jsenv leaves that url alone:
+<${node.nodeName} jsenv-ignore ${attributeName}="${reference.specifier}" />`,
+  };
+};
+
 const detailsFromPluginController = (jsenvPluginsController) => {
   const currentPlugin = jsenvPluginsController.getCurrentPlugin();
   if (!currentPlugin) {
@@ -2364,11 +2392,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 +2511,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 +2519,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);
@@ -2493,7 +2539,14 @@ const injectGlobals = (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}"`);
+  throw new Error(
+    createDetailedMessage(`cannot inject globals into "${urlInfo.type}"`, {
+      file: urlInfo.url,
+      ...(urlInfo.isInline
+        ? { "inline content of": urlInfo.inlineUrlSite.url }
+        : {}),
+    }),
+  );
 };
 const globalInjectorOnHtml = (content, globals, urlInfo) => {
   // ideally we would inject an importmap but browser support is too low
@@ -6560,7 +6613,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 +6714,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 +7271,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 +7687,52 @@ const jsenvPluginInjections = (rawAssociations) => {
           { injectionsGetter: rawAssociations },
           context.rootDirectoryUrl,
         );
-        getInjections = (urlInfo) => {
+        const findInjectionsGetterForUrl = (url) => {
           const { injectionsGetter } = URL_META.applyAssociations({
-            url: asUrlWithoutSearch(urlInfo.url),
+            url: asUrlWithoutSearch(url),
             associations: resolvedAssociations,
           });
-          if (!injectionsGetter) {
+          return injectionsGetter;
+        };
+        // an url written by an injection cannot be resolved during reference analysis;
+        // errors use this to tell the file holds injections and suggest "jsenv-ignore"
+        context.hasInjections = (url) => {
+          return Boolean(findInjectionsGetterForUrl(url));
+        };
+        const findInjectionsGetter = (urlInfo) => {
+          const injectionsGetter = findInjectionsGetterForUrl(urlInfo.url);
+          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;
+          }
+          return asInheritedInjections(injections);
         };
       }
     },
@@ -7646,13 +7743,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 +7759,26 @@ const jsenvPluginInjections = (rawAssociations) => {
   };
 };
 
+// What a file inlines (a <script> or a <style> inside html) is authored in that file
+// and inherits its injections, with two adjustments:
+// - a global belongs to the file itself, injecting it into each inline content would
+//   repeat it and reach types that cannot receive globals (css)
+// - a placeholder configured for the file is expected in one of its inline contents,
+//   not in each, so a missing one is not worth a warning
+const asInheritedInjections = (injections) => {
+  const inheritedInjections = {};
+  for (const key of Object.keys(injections)) {
+    const value = injections[key];
+    if (isPlaceholderInjection(value)) {
+      inheritedInjections[key] = INJECTIONS.optional(value);
+    }
+  }
+  if (Object.keys(inheritedInjections).length === 0) {
+    return null;
+  }
+  return inheritedInjections;
+};
+
 /*
  * 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 +11180,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 +12023,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 +12079,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/client/html_syntax_error/html_syntax_error.html

@@ -8,7 +8,7 @@
 
   <body>
     <p>Syntax error: <strong>${reasonCode}</strong></p>
-    <a jsenv-ignore="" href="${errorLinkHref}">${errorLinkText}</a>
+    <a href="${errorLinkHref}">${errorLinkText}</a>
     ${syntaxErrorHTML}
   </body>
 </html>

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 };