@jsenv/core 41.4.11 → 41.4.12

package/dist/build/build.js

@@ -9429,6 +9429,12 @@ const jsenvPluginCustomElementsRedefine = () => {
 const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -9441,7 +9447,7 @@ const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -9476,9 +9482,19 @@ const jsenvPluginRibbon = ({
           src: ribbonClientFileReference.generatedSpecifier,
           initCall: {
             callee: "injectRibbon",
-            params: {
-              text: urlInfo.context.dev ? "DEV" : "BUILD",
-            },
+            params: withoutUndefinedValues({
+              text:
+                text === undefined
+                  ? urlInfo.context.dev
+                    ? "DEV"
+                    : "BUILD"
+                  : text,
+              color,
+              textColor,
+              href,
+              target,
+              position,
+            }),
           },
           pluginName: "jsenv:ribbon",
         });
@@ -9488,6 +9504,16 @@ const jsenvPluginRibbon = ({
   };
 };
 
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};
+
 /**
  * HTML page server by jsenv dev server will listen for drop events
  * and redirect the browser to the dropped file location.
@@ -12174,6 +12200,18 @@ 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 {boolean|object} [entryPoint.ribbon=false]
+ *        Inject a ribbon marking the page as non-production. Disabled by default
+ *        because the ribbon ends up inside the build directory: enable it on the
+ *        builds meant for a preview/review app, not on the production build.
+ *
+ *          ribbon: {
+ *            text: "preview",
+ *            color: "#7c3aed",
+ *            href: "https://github.com/org/repo/pull/42",
+ *          }
+ *
+ *        See startDevServer "ribbon" param for the full list of options.
  * @param {object} [entryPoint.injections]
  *        Values to inject into files, as { urlPattern: getInjections }.
  *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
@@ -12991,6 +13029,7 @@ const entryPointDefaultParams = {
   magicDirectoryIndex: undefined,
   directoryReferenceEffect: undefined,
   scenarioPlaceholders: undefined,
+  ribbon: false,
   injections: undefined,
   transpilation: {},
   preserveComments: undefined,
@@ -13045,6 +13084,7 @@ const prepareEntryPointBuild = async (
     magicDirectoryIndex,
     directoryReferenceEffect,
     scenarioPlaceholders,
+    ribbon,
     injections,
     transpilation,
     preserveComments,
@@ -13221,6 +13261,7 @@ const prepareEntryPointBuild = async (
       inlining: false,
       http,
       scenarioPlaceholders,
+      ribbon,
       packageSideEffects,
     }),
   ]);

package/dist/client/ribbon/ribbon.js

@@ -1,49 +1,117 @@
-const injectRibbon = ({ text }) => {
+/*
+ * A ribbon marking a page as non-production: "DEV" while developing, whatever
+ * the app wants otherwise ("preview", a version number, a branch name).
+ *
+ * Two shapes, picked by "position":
+ * - a corner ("top-right", "top-left", "bottom-right", "bottom-left") draws the
+ *   diagonal band clipped by a 100x100 square in that corner
+ * - an edge ("top", "bottom") draws a full width horizontal band
+ *
+ * The container never captures pointer events; only the visible band does, and
+ * only when "href" turns it into a link. A corner ribbon therefore costs the app
+ * nothing: the rest of the 100x100 square keeps letting clicks through to the
+ * interface underneath, which usually lives exactly there.
+ */
+
+const CORNER_POSITIONS = {
+  "top-right": {
+    placement: `top: 0; right: 0;`,
+    transform: `translate(26px, -26px) rotate(45deg)`,
+  },
+  "top-left": {
+    placement: `top: 0; left: 0;`,
+    transform: `translate(-26px, -26px) rotate(-45deg)`,
+  },
+  "bottom-right": {
+    placement: `bottom: 0; right: 0;`,
+    transform: `translate(26px, 26px) rotate(-45deg)`,
+  },
+  "bottom-left": {
+    placement: `bottom: 0; left: 0;`,
+    transform: `translate(-26px, 26px) rotate(45deg)`,
+  },
+};
+const EDGE_POSITIONS = {
+  top: `top: 0; left: 0; right: 0;`,
+  bottom: `bottom: 0; left: 0; right: 0;`,
+};
+const DARK_TEXT_COLOR = "rgb(55, 7, 7)";
+const LIGHT_TEXT_COLOR = "rgb(255, 255, 255)";
+
+const injectRibbon = ({
+  text = "DEV",
+  color = "orange",
+  textColor,
+  href,
+  target = "_blank",
+  position = "top-right",
+}) => {
+  if (!CORNER_POSITIONS[position] && !EDGE_POSITIONS[position]) {
+    console.warn(
+      `unknown ribbon position "${position}", falling back to "top-right"`,
+    );
+    position = "top-right";
+  }
+  if (textColor === undefined) {
+    textColor = pickTextColorFor(color);
+  }
+  const corner = CORNER_POSITIONS[position];
   const css = /* css */ `
     #jsenv_ribbon_container {
       position: fixed;
-      top: 0;
-      right: 0;
       z-index: 1001;
-      width: 100px;
-      height: 100px;
-      opacity: 0.5;
       pointer-events: none;
       overflow: hidden;
-    }
-    #jsenv_ribbon {
-      position: absolute;
-      top: -10px;
-      right: -10px;
-      width: 100%;
-      height: 100%;
+      ${corner
+        ? `width: 100px; height: 100px; ${corner.placement}`
+        : EDGE_POSITIONS[position]}
     }
     #jsenv_ribbon_text {
-      position: absolute;
-      top: 20px;
-      left: 0px;
       display: block;
-      width: 125px;
-      color: rgb(55, 7, 7);
+      color: ${textColor};
       font-weight: 700;
       font-size: 16px;
       font-family: "Lato", sans-serif;
       text-align: center;
+      text-decoration: none;
       text-shadow: 0 1px 1px rgba(0, 0, 0, 0.2);
-      line-height: 36px;
-      background-color: orange;
+      background-color: ${color};
       box-shadow: 0 5px 10px rgba(0, 0, 0, 0.1);
-      transform: rotate(45deg);
+      opacity: 0.8;
+      transition: opacity 150ms ease;
       user-select: none;
+      ${corner
+        ? `
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      width: 150px;
+      margin-top: -18px;
+      margin-left: -75px;
+      line-height: 36px;
+      transform: ${corner.transform};`
+        : `
+      position: relative;
+      width: 100%;
+      line-height: 28px;`}
+    }
+    /* A ribbon without href never receives pointer events, so it stays at 0.8:
+       covering enough to be read in one go, transparent enough to guess what is
+       underneath */
+    #jsenv_ribbon_text:hover,
+    #jsenv_ribbon_text:focus-visible {
+      opacity: 1;
     }
   `;
+  const tagName = href ? "a" : "div";
+  const linkAttributes = href
+    ? ` href="${escapeHtmlAttributeValue(href)}" target="${escapeHtmlAttributeValue(target)}" rel="noopener noreferrer" style="pointer-events: auto;"`
+    : "";
   const html = /* html */ `<div id="jsenv_ribbon_container">
       <style>
         ${css}
       </style>
-      <div id="jsenv_ribbon">
-        <div id="jsenv_ribbon_text">${text}</div>
-      </div>
+      <${tagName} id="jsenv_ribbon_text"${linkAttributes}>${text}</${tagName}>
     </div>`;
   class JsenvRibbonHtmlElement extends HTMLElement {
     constructor({ hidden }) {
@@ -72,6 +140,34 @@ const injectRibbon = ({ text }) => {
   );
 };
 
+// The browser is the only one knowing what "orange" or "oklch(...)" resolves to,
+// so we let it resolve the color before deciding between dark and light text
+const pickTextColorFor = (color) => {
+  const probeElement = document.createElement("div");
+  probeElement.style.color = color;
+  document.body.appendChild(probeElement);
+  const colorComputed = getComputedStyle(probeElement).color;
+  probeElement.remove();
+  const rgbMatch = /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(
+    colorComputed,
+  );
+  if (!rgbMatch) {
+    return DARK_TEXT_COLOR;
+  }
+  const r = parseFloat(rgbMatch[1]);
+  const g = parseFloat(rgbMatch[2]);
+  const b = parseFloat(rgbMatch[3]);
+  const brightness = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  if (brightness > 0.55) {
+    return DARK_TEXT_COLOR;
+  }
+  return LIGHT_TEXT_COLOR;
+};
+
+const escapeHtmlAttributeValue = (value) => {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+};
+
 const appendIntoRespectingLineBreaksAndIndentation = (
   node,
   parentNode,

package/dist/start_build_server/start_build_server.js

@@ -1,4 +1,6 @@
-import { startServer, createFileSystemFetch, serverPluginCORS, jsenvAccessControlAllowedHeaders, serverPluginErrorHandler } from "@jsenv/server";
+import { createFileSystemFetch, startServer, serverPluginCORS, jsenvAccessControlAllowedHeaders, serverPluginErrorHandler } from "@jsenv/server";
+import { parseHtml, injectJsenvScript, stringifyHtmlAst } from "@jsenv/ast";
+import { readFileSync } from "node:fs";
 import { createLogger, Abort, raceProcessTeardownEvents, createTaskLog } from "./jsenv_core_packages.js";
 import "./jsenv_core_node_modules.js";
 import "node:process";
@@ -6,6 +8,43 @@ import "node:os";
 import "node:tty";
 import "node:util";
 
+/*
+ * Inject the ribbon into an html string, inlining the client code.
+ *
+ * Used when serving files that must not be modified on the filesystem (the build
+ * directory served by startBuildServer): the ribbon exists only in what the
+ * server sends, never in the artifact that gets deployed.
+ */
+
+
+const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
+let ribbonClientFileContent;
+
+const injectRibbonIntoHtml = (
+  html,
+  { text = "BUILD", color, textColor, href, target, position } = {},
+) => {
+  if (ribbonClientFileContent === undefined) {
+    ribbonClientFileContent = String(
+      readFileSync(new URL(ribbonClientFileUrl)),
+    );
+  }
+  const htmlAst = parseHtml({ html, url: "file:///ribbon.html" });
+  const params = { text, color, textColor, href, target, position };
+  for (const key of Object.keys(params)) {
+    if (params[key] === undefined) {
+      delete params[key];
+    }
+  }
+  injectJsenvScript(htmlAst, {
+    type: "module",
+    content: `${ribbonClientFileContent}
+injectRibbon(${JSON.stringify(params)});`,
+    pluginName: "jsenv:ribbon",
+  });
+  return stringifyHtmlAst(htmlAst);
+};
+
 /*
  * startBuildServer is mean to interact with the build files;
  * files that will be deployed to production server(s).
@@ -26,11 +65,16 @@ import "node:util";
  * Start a server for build files.
  * @param {Object} buildServerParameters
  * @param {string|url} buildServerParameters.buildDirectoryUrl Directory where build files are written
+ * @param {boolean|object} [buildServerParameters.ribbon=false] Inject a ribbon in the html responses,
+ *        marking the page as non-production. The build directory itself is left untouched.
+ *        As an object: `text`, `color`, `textColor`, `href`, `target`, `position`
+ *        (see startDevServer "ribbon" param).
  * @return {Object} A build server object
  */
 const startBuildServer = async ({
   buildDirectoryUrl,
   buildDirectoryMainFileRelativeUrl = "index.html",
+  ribbon = false,
   port = 9779,
   routes = [],
   serverPlugins = [],
@@ -46,6 +90,9 @@ const startBuildServer = async ({
   keepProcessAlive = true,
 }) => {
   const logger = createLogger({ logLevel });
+  if (ribbon === true) {
+    ribbon = {};
+  }
   const operation = Abort.startOperation();
   operation.addAbortSignal(signal);
   if (handleSIGINT) {
@@ -58,6 +105,9 @@ const startBuildServer = async ({
     });
   }
 
+  const fileSystemFetch = createFileSystemFetch(buildDirectoryUrl, {
+    mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
+  });
   const startBuildServerTask = createTaskLog("start build server", {
     disabled: !logger.levels.info,
   });
@@ -96,9 +146,9 @@ const startBuildServer = async ({
       {
         endpoint: "GET /",
         description: "Serve build files",
-        fetch: createFileSystemFetch(buildDirectoryUrl, {
-          mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
-        }),
+        fetch: ribbon
+          ? withRibbonInjectedInHtml(fileSystemFetch, ribbon)
+          : fileSystemFetch,
       },
     ],
   });
@@ -120,4 +170,44 @@ const startBuildServer = async ({
   };
 };
 
+const withRibbonInjectedInHtml = (fetch, ribbon) => {
+  return async (request, helpers) => {
+    const response = await fetch(request, helpers);
+    if (!response || response.status !== 200) {
+      return response;
+    }
+    const contentType = response.headers?.["content-type"];
+    if (!contentType || !contentType.startsWith("text/html")) {
+      return response;
+    }
+    const html = await readResponseBodyAsString(response.body);
+    const htmlWithRibbon = injectRibbonIntoHtml(html, ribbon);
+    const bodyBuffer = Buffer.from(htmlWithRibbon);
+    const headers = {
+      ...response.headers,
+      "content-length": bodyBuffer.length,
+    };
+    // the body is generated per request; what the file on disk hashes to or when
+    // it was modified does not describe it
+    delete headers.etag;
+    delete headers["last-modified"];
+    return {
+      ...response,
+      headers,
+      body: bodyBuffer,
+    };
+  };
+};
+
+const readResponseBodyAsString = async (body) => {
+  if (typeof body === "string" || Buffer.isBuffer(body)) {
+    return String(body);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return String(Buffer.concat(chunks));
+};
+
 export { startBuildServer };

package/dist/start_dev_server/start_dev_server.js

@@ -7258,6 +7258,12 @@ const jsenvPluginCustomElementsRedefine = () => {
 const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -7270,7 +7276,7 @@ const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -7305,9 +7311,19 @@ const jsenvPluginRibbon = ({
           src: ribbonClientFileReference.generatedSpecifier,
           initCall: {
             callee: "injectRibbon",
-            params: {
-              text: urlInfo.context.dev ? "DEV" : "BUILD",
-            },
+            params: withoutUndefinedValues({
+              text:
+                text === undefined
+                  ? urlInfo.context.dev
+                    ? "DEV"
+                    : "BUILD"
+                  : text,
+              color,
+              textColor,
+              href,
+              target,
+              position,
+            }),
           },
           pluginName: "jsenv:ribbon",
         });
@@ -7317,6 +7333,16 @@ const jsenvPluginRibbon = ({
   };
 };
 
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};
+
 /**
  * HTML page server by jsenv dev server will listen for drop events
  * and redirect the browser to the dropped file location.
@@ -11692,7 +11718,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {Array} [params.serverPlugins=[]] - `@jsenv/server`-level plugins.
  * @param {boolean|object} [params.clientAutoreload=true] - Live reload; also gates the server-events channel.
  * @param {boolean|object} [params.serverTiming={ minDuration: 0.5 }] - server-timing response headers; `minDuration` (ms) drops entries that took less (0 when run by the test plan, so tests see every entry).
- * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
+ * @param {boolean|object} [params.ribbon=true] - The "ribbon" overlay marking the page as non-production. As an object: `text` (defaults to `"DEV"`), `color` (background, defaults to `"orange"`), `textColor` (defaults to dark or light depending on `color`), `href` (turns the ribbon into a link; only then does it capture clicks), `target` (defaults to `"_blank"`), `position` (`"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"` draw a diagonal corner ribbon; `"top"`, `"bottom"` draw a full width band), `htmlInclude` (defaults to `"/**\/*.html"`).
  * @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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "41.4.11",
+  "version": "41.4.12",
   "type": "module",
   "description": "Tool to develop, test and build js projects",
   "repository": {
@@ -72,12 +72,12 @@
     "test:snapshot_clear": "npx @jsenv/filesystem clear **/tests/**/side_effects/"
   },
   "dependencies": {
-    "@jsenv/ast": "6.8.5",
-    "@jsenv/js-module-fallback": "1.4.38",
+    "@jsenv/ast": "6.9.0",
+    "@jsenv/js-module-fallback": "1.4.39",
     "@jsenv/plugin-bundling": "2.10.16",
-    "@jsenv/plugin-minification": "1.7.6",
-    "@jsenv/plugin-supervisor": "1.8.9",
-    "@jsenv/plugin-transpilation": "1.5.79",
+    "@jsenv/plugin-minification": "1.7.7",
+    "@jsenv/plugin-supervisor": "1.8.10",
+    "@jsenv/plugin-transpilation": "1.5.80",
     "@jsenv/server": "17.6.0",
     "@jsenv/sourcemap": "1.4.2",
     "react-table": "7.8.0"

package/src/build/build.js

@@ -134,6 +134,18 @@ 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 {boolean|object} [entryPoint.ribbon=false]
+ *        Inject a ribbon marking the page as non-production. Disabled by default
+ *        because the ribbon ends up inside the build directory: enable it on the
+ *        builds meant for a preview/review app, not on the production build.
+ *
+ *          ribbon: {
+ *            text: "preview",
+ *            color: "#7c3aed",
+ *            href: "https://github.com/org/repo/pull/42",
+ *          }
+ *
+ *        See startDevServer "ribbon" param for the full list of options.
  * @param {object} [entryPoint.injections]
  *        Values to inject into files, as { urlPattern: getInjections }.
  *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
@@ -953,6 +965,7 @@ const entryPointDefaultParams = {
   magicDirectoryIndex: undefined,
   directoryReferenceEffect: undefined,
   scenarioPlaceholders: undefined,
+  ribbon: false,
   injections: undefined,
   transpilation: {},
   preserveComments: undefined,
@@ -1007,6 +1020,7 @@ const prepareEntryPointBuild = async (
     magicDirectoryIndex,
     directoryReferenceEffect,
     scenarioPlaceholders,
+    ribbon,
     injections,
     transpilation,
     preserveComments,
@@ -1183,6 +1197,7 @@ const prepareEntryPointBuild = async (
       inlining: false,
       http,
       scenarioPlaceholders,
+      ribbon,
       packageSideEffects,
     }),
   ]);

package/src/build/start_build_server.js

@@ -23,15 +23,22 @@ import {
   startServer,
 } from "@jsenv/server";
 
+import { injectRibbonIntoHtml } from "../plugins/ribbon/ribbon_html_injection.js";
+
 /**
  * Start a server for build files.
  * @param {Object} buildServerParameters
  * @param {string|url} buildServerParameters.buildDirectoryUrl Directory where build files are written
+ * @param {boolean|object} [buildServerParameters.ribbon=false] Inject a ribbon in the html responses,
+ *        marking the page as non-production. The build directory itself is left untouched.
+ *        As an object: `text`, `color`, `textColor`, `href`, `target`, `position`
+ *        (see startDevServer "ribbon" param).
  * @return {Object} A build server object
  */
 export const startBuildServer = async ({
   buildDirectoryUrl,
   buildDirectoryMainFileRelativeUrl = "index.html",
+  ribbon = false,
   port = 9779,
   routes = [],
   serverPlugins = [],
@@ -47,6 +54,9 @@ export const startBuildServer = async ({
   keepProcessAlive = true,
 }) => {
   const logger = createLogger({ logLevel });
+  if (ribbon === true) {
+    ribbon = {};
+  }
   const operation = Abort.startOperation();
   operation.addAbortSignal(signal);
   if (handleSIGINT) {
@@ -60,6 +70,9 @@ export const startBuildServer = async ({
     });
   }
 
+  const fileSystemFetch = createFileSystemFetch(buildDirectoryUrl, {
+    mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
+  });
   const startBuildServerTask = createTaskLog("start build server", {
     disabled: !logger.levels.info,
   });
@@ -98,9 +111,9 @@ export const startBuildServer = async ({
       {
         endpoint: "GET /",
         description: "Serve build files",
-        fetch: createFileSystemFetch(buildDirectoryUrl, {
-          mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
-        }),
+        fetch: ribbon
+          ? withRibbonInjectedInHtml(fileSystemFetch, ribbon)
+          : fileSystemFetch,
       },
     ],
   });
@@ -121,3 +134,43 @@ export const startBuildServer = async ({
     },
   };
 };
+
+const withRibbonInjectedInHtml = (fetch, ribbon) => {
+  return async (request, helpers) => {
+    const response = await fetch(request, helpers);
+    if (!response || response.status !== 200) {
+      return response;
+    }
+    const contentType = response.headers?.["content-type"];
+    if (!contentType || !contentType.startsWith("text/html")) {
+      return response;
+    }
+    const html = await readResponseBodyAsString(response.body);
+    const htmlWithRibbon = injectRibbonIntoHtml(html, ribbon);
+    const bodyBuffer = Buffer.from(htmlWithRibbon);
+    const headers = {
+      ...response.headers,
+      "content-length": bodyBuffer.length,
+    };
+    // the body is generated per request; what the file on disk hashes to or when
+    // it was modified does not describe it
+    delete headers.etag;
+    delete headers["last-modified"];
+    return {
+      ...response,
+      headers,
+      body: bodyBuffer,
+    };
+  };
+};
+
+const readResponseBodyAsString = async (body) => {
+  if (typeof body === "string" || Buffer.isBuffer(body)) {
+    return String(body);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return String(Buffer.concat(chunks));
+};

package/src/dev/start_dev_server.js

@@ -48,7 +48,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {Array} [params.serverPlugins=[]] - `@jsenv/server`-level plugins.
  * @param {boolean|object} [params.clientAutoreload=true] - Live reload; also gates the server-events channel.
  * @param {boolean|object} [params.serverTiming={ minDuration: 0.5 }] - server-timing response headers; `minDuration` (ms) drops entries that took less (0 when run by the test plan, so tests see every entry).
- * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
+ * @param {boolean|object} [params.ribbon=true] - The "ribbon" overlay marking the page as non-production. As an object: `text` (defaults to `"DEV"`), `color` (background, defaults to `"orange"`), `textColor` (defaults to dark or light depending on `color`), `href` (turns the ribbon into a link; only then does it capture clicks), `target` (defaults to `"_blank"`), `position` (`"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"` draw a diagonal corner ribbon; `"top"`, `"bottom"` draw a full width band), `htmlInclude` (defaults to `"/**\/*.html"`).
  * @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`.

package/src/plugins/ribbon/client/ribbon.js

@@ -1,49 +1,117 @@
-export const injectRibbon = ({ text }) => {
+/*
+ * A ribbon marking a page as non-production: "DEV" while developing, whatever
+ * the app wants otherwise ("preview", a version number, a branch name).
+ *
+ * Two shapes, picked by "position":
+ * - a corner ("top-right", "top-left", "bottom-right", "bottom-left") draws the
+ *   diagonal band clipped by a 100x100 square in that corner
+ * - an edge ("top", "bottom") draws a full width horizontal band
+ *
+ * The container never captures pointer events; only the visible band does, and
+ * only when "href" turns it into a link. A corner ribbon therefore costs the app
+ * nothing: the rest of the 100x100 square keeps letting clicks through to the
+ * interface underneath, which usually lives exactly there.
+ */
+
+const CORNER_POSITIONS = {
+  "top-right": {
+    placement: `top: 0; right: 0;`,
+    transform: `translate(26px, -26px) rotate(45deg)`,
+  },
+  "top-left": {
+    placement: `top: 0; left: 0;`,
+    transform: `translate(-26px, -26px) rotate(-45deg)`,
+  },
+  "bottom-right": {
+    placement: `bottom: 0; right: 0;`,
+    transform: `translate(26px, 26px) rotate(-45deg)`,
+  },
+  "bottom-left": {
+    placement: `bottom: 0; left: 0;`,
+    transform: `translate(-26px, 26px) rotate(45deg)`,
+  },
+};
+const EDGE_POSITIONS = {
+  top: `top: 0; left: 0; right: 0;`,
+  bottom: `bottom: 0; left: 0; right: 0;`,
+};
+const DARK_TEXT_COLOR = "rgb(55, 7, 7)";
+const LIGHT_TEXT_COLOR = "rgb(255, 255, 255)";
+
+export const injectRibbon = ({
+  text = "DEV",
+  color = "orange",
+  textColor,
+  href,
+  target = "_blank",
+  position = "top-right",
+}) => {
+  if (!CORNER_POSITIONS[position] && !EDGE_POSITIONS[position]) {
+    console.warn(
+      `unknown ribbon position "${position}", falling back to "top-right"`,
+    );
+    position = "top-right";
+  }
+  if (textColor === undefined) {
+    textColor = pickTextColorFor(color);
+  }
+  const corner = CORNER_POSITIONS[position];
   const css = /* css */ `
     #jsenv_ribbon_container {
       position: fixed;
-      top: 0;
-      right: 0;
       z-index: 1001;
-      width: 100px;
-      height: 100px;
-      opacity: 0.5;
       pointer-events: none;
       overflow: hidden;
-    }
-    #jsenv_ribbon {
-      position: absolute;
-      top: -10px;
-      right: -10px;
-      width: 100%;
-      height: 100%;
+      ${corner
+        ? `width: 100px; height: 100px; ${corner.placement}`
+        : EDGE_POSITIONS[position]}
     }
     #jsenv_ribbon_text {
-      position: absolute;
-      top: 20px;
-      left: 0px;
       display: block;
-      width: 125px;
-      color: rgb(55, 7, 7);
+      color: ${textColor};
       font-weight: 700;
       font-size: 16px;
       font-family: "Lato", sans-serif;
       text-align: center;
+      text-decoration: none;
       text-shadow: 0 1px 1px rgba(0, 0, 0, 0.2);
-      line-height: 36px;
-      background-color: orange;
+      background-color: ${color};
       box-shadow: 0 5px 10px rgba(0, 0, 0, 0.1);
-      transform: rotate(45deg);
+      opacity: 0.8;
+      transition: opacity 150ms ease;
       user-select: none;
+      ${corner
+        ? `
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      width: 150px;
+      margin-top: -18px;
+      margin-left: -75px;
+      line-height: 36px;
+      transform: ${corner.transform};`
+        : `
+      position: relative;
+      width: 100%;
+      line-height: 28px;`}
+    }
+    /* A ribbon without href never receives pointer events, so it stays at 0.8:
+       covering enough to be read in one go, transparent enough to guess what is
+       underneath */
+    #jsenv_ribbon_text:hover,
+    #jsenv_ribbon_text:focus-visible {
+      opacity: 1;
     }
   `;
+  const tagName = href ? "a" : "div";
+  const linkAttributes = href
+    ? ` href="${escapeHtmlAttributeValue(href)}" target="${escapeHtmlAttributeValue(target)}" rel="noopener noreferrer" style="pointer-events: auto;"`
+    : "";
   const html = /* html */ `<div id="jsenv_ribbon_container">
       <style>
         ${css}
       </style>
-      <div id="jsenv_ribbon">
-        <div id="jsenv_ribbon_text">${text}</div>
-      </div>
+      <${tagName} id="jsenv_ribbon_text"${linkAttributes}>${text}</${tagName}>
     </div>`;
   class JsenvRibbonHtmlElement extends HTMLElement {
     constructor({ hidden }) {
@@ -72,6 +140,34 @@ export const injectRibbon = ({ text }) => {
   );
 };
 
+// The browser is the only one knowing what "orange" or "oklch(...)" resolves to,
+// so we let it resolve the color before deciding between dark and light text
+const pickTextColorFor = (color) => {
+  const probeElement = document.createElement("div");
+  probeElement.style.color = color;
+  document.body.appendChild(probeElement);
+  const colorComputed = getComputedStyle(probeElement).color;
+  probeElement.remove();
+  const rgbMatch = /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(
+    colorComputed,
+  );
+  if (!rgbMatch) {
+    return DARK_TEXT_COLOR;
+  }
+  const r = parseFloat(rgbMatch[1]);
+  const g = parseFloat(rgbMatch[2]);
+  const b = parseFloat(rgbMatch[3]);
+  const brightness = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  if (brightness > 0.55) {
+    return DARK_TEXT_COLOR;
+  }
+  return LIGHT_TEXT_COLOR;
+};
+
+const escapeHtmlAttributeValue = (value) => {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+};
+
 const appendIntoRespectingLineBreaksAndIndentation = (
   node,
   parentNode,

package/src/plugins/ribbon/jsenv_plugin_ribbon.js

@@ -5,6 +5,12 @@ import { asUrlWithoutSearch } from "@jsenv/urls";
 export const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("./client/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -17,7 +23,7 @@ export const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -52,9 +58,19 @@ export const jsenvPluginRibbon = ({
           src: ribbonClientFileReference.generatedSpecifier,
           initCall: {
             callee: "injectRibbon",
-            params: {
-              text: urlInfo.context.dev ? "DEV" : "BUILD",
-            },
+            params: withoutUndefinedValues({
+              text:
+                text === undefined
+                  ? urlInfo.context.dev
+                    ? "DEV"
+                    : "BUILD"
+                  : text,
+              color,
+              textColor,
+              href,
+              target,
+              position,
+            }),
           },
           pluginName: "jsenv:ribbon",
         });
@@ -63,3 +79,13 @@ export const jsenvPluginRibbon = ({
     },
   };
 };
+
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};

package/src/plugins/ribbon/ribbon_html_injection.js

@@ -0,0 +1,38 @@
+/*
+ * Inject the ribbon into an html string, inlining the client code.
+ *
+ * Used when serving files that must not be modified on the filesystem (the build
+ * directory served by startBuildServer): the ribbon exists only in what the
+ * server sends, never in the artifact that gets deployed.
+ */
+
+import { injectJsenvScript, parseHtml, stringifyHtmlAst } from "@jsenv/ast";
+import { readFileSync } from "node:fs";
+
+const ribbonClientFileUrl = import.meta.resolve("./client/ribbon.js");
+let ribbonClientFileContent;
+
+export const injectRibbonIntoHtml = (
+  html,
+  { text = "BUILD", color, textColor, href, target, position } = {},
+) => {
+  if (ribbonClientFileContent === undefined) {
+    ribbonClientFileContent = String(
+      readFileSync(new URL(ribbonClientFileUrl)),
+    );
+  }
+  const htmlAst = parseHtml({ html, url: "file:///ribbon.html" });
+  const params = { text, color, textColor, href, target, position };
+  for (const key of Object.keys(params)) {
+    if (params[key] === undefined) {
+      delete params[key];
+    }
+  }
+  injectJsenvScript(htmlAst, {
+    type: "module",
+    content: `${ribbonClientFileContent}
+injectRibbon(${JSON.stringify(params)});`,
+    pluginName: "jsenv:ribbon",
+  });
+  return stringifyHtmlAst(htmlAst);
+};