playground: load grep and find on demand

The standalone WASM modules (grep ~1.4 MB, find ~2.0 MB) were fetched
eagerly at startup, adding ~3.4 MB (~22%) to the initial download for
visitors who never use them. Load them on demand instead: the first time
a command runs it auto-loads its module (with a live 'loading… done'
notice), and a row of 'Load' buttons lets visitors pre-warm them. A
shared in-flight map dedupes a click and a command racing to load the
same module, and buttons stay in sync via a 'uutils:program-loaded'
event whether the module was loaded by click or by use.

Author: sylvestre

content/playground.md

@@ -13,6 +13,10 @@ template = "page.html"
   <span class="locale-help">Missing a translation or your language? <a href="https://hosted.weblate.org/projects/rust-coreutils/">Help translate on Weblate</a></span>
 </div>
 
+<div class="playground-loaders" id="playground-loaders">
+  <span class="playground-loaders-label">Extra programs:</span>
+</div>
+
 <div id="wasm-playground"></div>
 
 <p class="playground-version" id="playground-version"></p>
@@ -24,6 +28,47 @@ template = "page.html"
 <script defer>
   document.addEventListener("DOMContentLoaded", function() {
     initPlayground("wasm-playground");
+    // Build a "Load" button per optional standalone program (grep, find).
+    // These ship as their own WASM modules and load on demand to keep the
+    // initial page download light; running the command auto-loads it too.
+    var loaderBar = document.getElementById("playground-loaders");
+    if (loaderBar && Array.isArray(window.uutilsPrograms)) {
+      window.uutilsPrograms.forEach(function(cmd) {
+        var btn = document.createElement("button");
+        btn.className = "playground-loader";
+        var markLoaded = function() {
+          btn.disabled = true;
+          btn.classList.add("loaded");
+          btn.textContent = "✓ " + cmd + " loaded";
+        };
+        var setIdleLabel = function(size) {
+          btn.textContent = "Load " + cmd + (size ? " (" + (size / 1024 / 1024).toFixed(1) + " MB)" : "");
+        };
+        setIdleLabel(0);
+        window.programSize(cmd).then(function(size) {
+          if (!btn.classList.contains("loaded") && !btn.disabled) setIdleLabel(size);
+        });
+        btn.addEventListener("click", function() {
+          if (btn.disabled) return;
+          btn.disabled = true;
+          btn.textContent = "Loading " + cmd + "…";
+          window.loadProgram(cmd).then(function(mod) {
+            if (mod) {
+              markLoaded();
+            } else {
+              btn.disabled = false;
+              btn.textContent = cmd + " unavailable";
+            }
+          });
+        });
+        // Keep the button in sync if the program is loaded by running it.
+        document.addEventListener("uutils:program-loaded", function(e) {
+          if (e.detail && e.detail.cmd === cmd) markLoaded();
+        });
+        if (window.isProgramLoaded(cmd)) markLoaded();
+        loaderBar.appendChild(btn);
+      });
+    }
     // Populate the locale dropdown from the build-generated list
     if (typeof WASM_LOCALES !== "undefined") {
       var sel = document.getElementById("locale-select");

static/js/wasm-terminal.js

@@ -80,6 +80,9 @@ let wasmModule = null;
 // Compiled standalone modules, keyed by command name (e.g. "grep", "find").
 // A key is present only once its module has loaded successfully.
 const standaloneModules = {};
+// In-flight loads, keyed by command name, so a button click and a command that
+// both trigger a load (or two rapid clicks) share one fetch instead of racing.
+const standaloneLoading = {};
 let wasiShim = null;
 let terminal = null;
 let inputBuffer = "";
@@ -167,32 +170,54 @@ async function loadWasm() {
 }
 
 /**
- * Load the optional standalone WASM modules (grep, find, …). Each is optional:
- * if a binary isn't present (e.g. local dev without a CI build), its error is
- * swallowed and the corresponding command reports that it's unavailable rather
- * than breaking the terminal or blocking the coreutils module.
+ * Load one optional standalone module (grep, find, …) on demand. These are not
+ * part of the eager startup download — they're fetched the first time the user
+ * runs the command or clicks its "Load" button, keeping the initial page load
+ * to just the coreutils multicall binary.
+ *
+ * Concurrent callers share a single in-flight fetch. Returns the compiled
+ * module, or null if it's unknown or its binary isn't present (e.g. local dev
+ * without a CI build) — in which case the command reports it's unavailable
+ * rather than breaking the terminal.
+ *
+ * When `announce` is set and a terminal exists, a "loading <cmd>… done" notice
+ * is printed live; the button UI instead reacts to the `uutils:program-loaded`
+ * event dispatched on success.
  */
-async function loadStandaloneWasm() {
-  await Promise.all(
-    Object.entries(STANDALONE_WASM_URLS).map(async ([cmd, url]) => {
-      if (standaloneModules[cmd]) return;
-      try {
-        const { module, size } = await compileWasmModule(url);
-        standaloneModules[cmd] = module;
-        wasmSize += size;
-      } catch (e) {
-        console.warn(`${cmd} WASM unavailable:`, e.message);
+function loadStandalone(cmd, { announce = false } = {}) {
+  if (standaloneModules[cmd]) return Promise.resolve(standaloneModules[cmd]);
+  if (standaloneLoading[cmd]) return standaloneLoading[cmd];
+  const url = STANDALONE_WASM_URLS[cmd];
+  if (!url) return Promise.resolve(null);
+  const notify = announce && terminal;
+  if (notify) terminal.write(`loading ${cmd}… `);
+  standaloneLoading[cmd] = (async () => {
+    try {
+      const { module, size } = await compileWasmModule(url);
+      standaloneModules[cmd] = module;
+      wasmSize += size;
+      if (notify) terminal.write(`done (${(size / 1024 / 1024).toFixed(1)} MB)\r\n`);
+      if (typeof document !== "undefined") {
+        document.dispatchEvent(new CustomEvent("uutils:program-loaded", { detail: { cmd, size } }));
       }
-    })
-  );
+      return module;
+    } catch (e) {
+      console.warn(`${cmd} WASM unavailable:`, e.message);
+      if (notify) terminal.write("unavailable\r\n");
+      return null;
+    } finally {
+      delete standaloneLoading[cmd];
+    }
+  })();
+  return standaloneLoading[cmd];
 }
 
 async function initWasm() {
   if (wasmReady) return;
   try {
-    // The standalone modules are optional and loadStandaloneWasm swallows its
-    // own errors, so they never block the coreutils module from becoming ready.
-    await Promise.all([loadWasiShim(), loadWasm(), loadStandaloneWasm()]);
+    // Only the coreutils multicall binary loads eagerly; the standalone
+    // modules (grep, find) are fetched on demand — see loadStandalone.
+    await Promise.all([loadWasiShim(), loadWasm()]);
     wasmReady = true;
   } catch (e) {
     // Will fall back to JS implementations
@@ -583,10 +608,12 @@ async function executeCommandLine(line) {
     }
 
     // Some utilities (grep, find) are separate WASM modules rather than part
-    // of the coreutils multicall binary.
+    // of the coreutils multicall binary, and are loaded on demand. Fetch the
+    // module the first time the command is used (no-op once cached).
     const isStandalone = cmd in STANDALONE_WASM_URLS;
     if (isStandalone && !standaloneModules[cmd]) {
-      return `${cmd} is not available in this build.\n`;
+      const mod = await loadStandalone(cmd, { announce: true });
+      if (!mod) return `${cmd} is not available in this build.\n`;
     }
 
     try {
@@ -887,6 +914,7 @@ async function initPlayground(containerId) {
     terminal.writeln("");
     terminal.writeln("Type \x1b[1;32mhelp\x1b[0m for available commands.");
     terminal.writeln("Sample data files: names.txt, numbers.txt, fruits.txt, csv.txt, words.txt");
+    terminal.writeln("\x1b[2mgrep and find load on demand — just run them, or use the buttons below.\x1b[0m");
   } catch (e) {
     terminal.writeln(" \x1b[1;31mfailed\x1b[0m");
     terminal.writeln("Failed to load WASM binary. Commands are not available.");
@@ -934,6 +962,25 @@ window.uutilsExecute = executeCommandLine;
 window.runInTerminal = runInTerminal;
 window.setLocale = setLocale;
 
+// On-demand loading of the optional standalone programs (grep, find), used by
+// the "Load" buttons on the playground page.
+window.uutilsPrograms = Object.keys(STANDALONE_WASM_URLS);
+window.loadProgram = (cmd) => loadStandalone(cmd);
+window.isProgramLoaded = (cmd) => !!standaloneModules[cmd];
+// Best-effort byte size of a program's module, for the button label (0 if the
+// server doesn't report Content-Length or the binary is missing).
+window.programSize = async (cmd) => {
+  const url = STANDALONE_WASM_URLS[cmd];
+  if (!url) return 0;
+  try {
+    const r = await fetch(url, { method: "HEAD" });
+    const cl = r.ok ? r.headers.get("content-length") : null;
+    return cl ? parseInt(cl, 10) : 0;
+  } catch {
+    return 0;
+  }
+};
+
 // Expose internals for testing
 window._uutilsTestInternals = {
   parseCommandLine,
@@ -951,6 +998,7 @@ window._uutilsTestInternals = {
   get grepReady() { return !!standaloneModules.grep; },
   get findReady() { return !!standaloneModules.find; },
   initWasm,
+  loadStandalone,
   LOCALE_SHORTCUTS,
   SAMPLE_FILES,
   AVAILABLE_COMMANDS,

static/js/wasm-terminal.test.html

@@ -450,7 +450,10 @@ <h1>wasm-terminal unit tests</h1>
         "w\nx\n");
     }
 
-    // ===== grep (standalone WASM module) =====
+    // ===== grep (standalone WASM module, loaded on demand) =====
+    // grep is no longer eager-loaded; pull it in via the on-demand loader,
+    // which also exercises that path. Skips gracefully if grep.wasm is absent.
+    await T.loadStandalone("grep");
     if (T.grepReady) {
       section("grep WASM module");
 
@@ -472,16 +475,21 @@ <h1>wasm-terminal unit tests</h1>
       section("grep WASM module (SKIPPED - grep.wasm not loaded)");
     }
 
-    // ===== find (standalone WASM module) =====
+    // ===== find (standalone WASM module, auto-loaded on first use) =====
+    // Unlike grep above, exercise the hybrid auto-load path: the first find
+    // command should fetch find.wasm on demand. The probe result doubles as the
+    // "find by exact name" assertion. Skips gracefully if find.wasm is absent.
+    const findProbe = await executeCommandLine("find . -name names.txt");
     if (T.findReady) {
       section("find WASM module");
 
+      assert("find auto-loaded on first use", T.findReady, true);
+
       assert("find in AVAILABLE_COMMANDS",
         AVAILABLE_COMMANDS.includes("find"), true);
 
-      await assertAsync("find by exact name",
-        executeCommandLine("find . -name names.txt"),
-        "./names.txt\n");
+      assert("find by exact name (via auto-load)",
+        findProbe, "./names.txt\n");
 
       await assertAsync("find with no matches",
         executeCommandLine("find . -name '*.csv'"),

static/style.css

@@ -539,6 +539,48 @@ main img {
   cursor: pointer;
 }
 
+.playground-loaders {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5em;
+  margin: 0.6em 0 0;
+  font-size: 0.9em;
+}
+
+.playground-loaders-label {
+  opacity: 0.8;
+}
+
+.playground-loader {
+  padding: 0.3em 0.7em;
+  background: var(--highlight-bg-color);
+  color: var(--highlight-fg-color);
+  border: 1px solid var(--header-border-color);
+  border-radius: 0.3em;
+  font-family: "Fira Code", monospace;
+  font-size: 0.85em;
+  cursor: pointer;
+  transition: border-color 0.2s, background-color 0.2s, opacity 0.2s;
+}
+
+.playground-loader:hover:not(:disabled) {
+  border-color: var(--accent-color);
+  background: var(--accent-color);
+  color: white;
+}
+
+.playground-loader:disabled {
+  cursor: default;
+}
+
+.playground-loader.loaded {
+  border-color: #2ea043;
+  background: #2ea043;
+  color: white;
+  opacity: 0.9;
+}
+
 #wasm-playground {
   width: 100%;
   min-height: 480px;