@soleone/showcase-terminal 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soleone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# showcase-terminal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let people try a CLI for real without installing anything: a static page that boots a Node.js sandbox ([WebContainers](https://webcontainers.io)) in the visitor's browser and opens a real shell, with the project's own code and sample data mounted.
+
+```sh
+npm install --save-dev @soleone/showcase-terminal
+
+showcase-terminal --serve                       # builds demo/browser into dist/browser, serves it on 127.0.0.1:4321
+showcase-terminal path/to/recipe --out dist/demo
+```
+
+It is one way to give a CLI the live demo that [showcase](https://github.com/Soleone/showcase) grades S, and it reads the project's facts from the same `showcase.json`. It doesn't need showcase installed.
+
+Keep the recipe folder in the project itself (`demo/browser/` by default), so the project owns its sample data and stand-ins. Relative paths in it resolve from the recipe folder. It holds `terminal.json`:
+
+- `project`: the project folder. Title, pitch and repo come from its `showcase.json`, and the page's disclosure line is written from `demo.externals` (each stand-in's `note`).
+- `mount`: target path in the sandbox → `{ from, include }`. `from` may use `~` and `$VARS`; `include` limits the top-level entries copied. Binary files (images, loops) are mounted too.
+- `env`: values may use `~` (the sandbox home, always `/home/demo`) and `$PATH` (costs one extra process at boot; write the PATH out instead).
+- `setup`: commands run before the shell opens, e.g. seeding sample data dated relative to today. Until they finish, a spinner stands in for the prompt and keys typed in the terminal are dropped, so nothing ends up in front of `start`.
+- `start`: a command typed into the shell once setup is done, to open the program right away (e.g. a TUI). The visitor sees it run and can run it again after quitting.
+- `onTheme`: a command run whenever the visitor picks a theme. Before it runs, the page writes `~/.config/showcase/theme.json` with the theme's colors and the full terminal palette (`palette`, as hex), so a program that draws its own colors can follow the page. The file is also written once before `setup`.
+- `welcome`, `hints` (buttons that type a command), `seed` (a browser module that adds files computed at visit time, such as dates relative to today), and overrides for `title`, `pitch`, `repo`, `disclosure`, `defaultTheme` (a name from `themes.json`, default the first).
+- `skin`: a folder or URL with the page's look, `themes.json` (palettes, same shape as `page/themes.json`) and `skin.css` (fonts and other touches, loaded after the page's styles). Either may be left out. Without a skin the page is plain: a dark and a light theme and system fonts.
+
+The output is static: `index.html`, `files.json`, `terminal.json`, `themes.json`, `skin.css`, `fonts/` and a `vercel.json` with the COOP/COEP headers the sandbox needs.
+
+The terminal font is JetBrainsMono Nerd Font Mono, self-hosted as WOFF2 (about 600 KB per weight) so CLI icons render. `page/fonts/build.sh` rebuilds it from a pinned Nerd Fonts release, keeping the Basic Multilingual Plane and dropping the Material Design plane.
+
+Sandbox quirks found so far:
+
+- Mounted files are not executable; `chmod` them from a setup script (one process is faster than several setup commands).
+- Extensionless ES modules exit silently, so command shims are CommonJS that `import()` the real entry point.
+- A top-level `for await` fails to parse; read streams with events.
+- Model calls: point the project at a stand-in (a setting that names the model command) that returns canned output, so nothing leaves the browser.
+
+WebContainers is free for personal and open-source use; check the StackBlitz license before using it commercially.
+
+The page has a theme picker when there is more than one theme (the choice is remembered in the visitor's browser). A theme colors the page and the terminal's 16 ANSI colors together, so whatever the CLI prints follows it; the bright colors are derived from the normal ones.
+
+From code:
+
+```js
+import { buildTerminal, serveTerminal } from "@soleone/showcase-terminal";
+
+await buildTerminal("demo/browser", "dist/browser");
+```
+
+## Hosting
+
+Deploy the output folder to any static host that can set the COOP/COEP headers. On Vercel the generated `vercel.json` sets them: `vercel deploy --prod` from the folder.
+
+## License
+
+MIT

package/bin/showcase-terminal.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { buildTerminal, serveTerminal } from "../src/terminal.js";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+const usage = `showcase-terminal ${version}: build an in-browser terminal demo for a CLI.
+
+Usage:
+  showcase-terminal [recipe]  Build the page from a folder with terminal.json (default demo/browser)
+
+Options:
+  --out <dir>    Where to write the page (default dist/browser)
+  --serve        Serve the page on 127.0.0.1 after building it
+  --port <n>     Port for --serve (default 4321)
+  --help, -h     Show this help
+  --version      Show the version`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      out: { type: "string" },
+      serve: { type: "boolean" },
+      port: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean" },
+    },
+  });
+  if (values.version) return console.log(version);
+  if (values.help) return console.log(usage);
+  if (positionals.length > 1) throw new Error("showcase-terminal takes a single recipe folder");
+
+  const { out, bytes } = await buildTerminal(positionals[0] ?? "demo/browser", values.out ?? "dist/browser");
+  console.log(`Built ${out} (${Math.round(bytes / 1024)} KB of files)`);
+  if (!values.serve) return;
+  const port = Number(values.port ?? 4321);
+  if (!Number.isInteger(port)) throw new Error("--port must be a number");
+  await serveTerminal(out, port);
+  console.log(`Serving at http://127.0.0.1:${port} (Ctrl-C to stop)`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@soleone/showcase-terminal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Build a static page that runs a CLI for real in the visitor's browser (WebContainers).",
+  "license": "MIT",
+  "author": "Soleone",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Soleone/showcase-terminal.git"
+  },
+  "homepage": "https://github.com/Soleone/showcase-terminal#readme",
+  "bugs": "https://github.com/Soleone/showcase-terminal/issues",
+  "keywords": [
+    "demo",
+    "cli",
+    "terminal",
+    "webcontainers",
+    "showcase"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/terminal.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "showcase-terminal": "./bin/showcase-terminal.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "page/",
+    "!page/fonts/build.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "release": "release-it",
+    "release:dry-run": "npm test && release-it --dry-run"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^10.0.6",
+    "release-it": "^19.2.4"
+  },
+  "overrides": {
+    "release-it": {
+      "undici": "^7.30.0"
+    }
+  }
+}

package/page/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/page/index.html

@@ -0,0 +1,453 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Try it in your browser</title>
+  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/@webcontainer/api@1.6.4/+esm" crossorigin>
+  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@6.0.0/+esm" crossorigin>
+  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/@xterm/addon-webgl@0.19.0/+esm" crossorigin>
+  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.11.0/+esm" crossorigin>
+  <link rel="preload" href="files.json" as="fetch" crossorigin>
+  <link rel="preload" href="terminal.json" as="fetch" crossorigin>
+  <link rel="preload" href="themes.json" as="fetch" crossorigin>
+  <link rel="preload" href="fonts/JetBrainsMonoNerdFontMono-Regular.woff2" as="font" type="font/woff2" crossorigin>
+  <link rel="preload" href="fonts/JetBrainsMonoNerdFontMono-Bold.woff2" as="font" type="font/woff2" crossorigin>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@6.0.0/css/xterm.css" crossorigin>
+  <script>
+    // Puts the visitor's theme on before first paint (themes.js saves the resolved colors when one is picked).
+    try {
+      const saved = JSON.parse(localStorage.getItem("browser-terminal.theme"));
+      for (const [name, value] of Object.entries(saved.vars)) document.documentElement.style.setProperty(`--${name}`, value);
+      document.documentElement.style.colorScheme = document.documentElement.dataset.theme = saved.mode;
+    } catch {}
+  </script>
+  <style>
+    /* JetBrains Mono with Nerd Font icons (SIL OFL, fonts/OFL.txt), self-hosted; see fonts/build.sh. */
+    @font-face {
+      font-family: "JetBrainsMono Nerd Font Mono";
+      src: url("fonts/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");
+      font-weight: 400;
+      font-display: block;
+    }
+    @font-face {
+      font-family: "JetBrainsMono Nerd Font Mono";
+      src: url("fonts/JetBrainsMonoNerdFontMono-Bold.woff2") format("woff2");
+      font-weight: 700;
+      font-display: block;
+    }
+    /* The plain look until themes.json has applied a theme. A skin (skin.css, themes.json) brings its own. */
+    :root {
+      color-scheme: dark;
+      --page: #111113;
+      --ink: #d4d4d8;
+      --ink-strong: #fafafa;
+      --muted: #a1a1aa;
+      --accent: #60a5fa;
+      --surface: #1c1c1f;
+      --line: #2e2e33;
+      --terminal: #0b0b0c;
+    }
+    @media (prefers-color-scheme: light) {
+      :root:not([data-theme="dark"]) {
+        color-scheme: light;
+        --page: #fafafa;
+        --ink: #27272a;
+        --ink-strong: #09090b;
+        --muted: #52525b;
+        --accent: #2563eb;
+        --surface: #f4f4f5;
+        --line: #e4e4e7;
+        --terminal: #ffffff;
+      }
+    }
+    :root[data-theme="light"] {
+      color-scheme: light;
+      --page: #fafafa;
+      --ink: #27272a;
+      --ink-strong: #09090b;
+      --muted: #52525b;
+      --accent: #2563eb;
+      --surface: #f4f4f5;
+      --line: #e4e4e7;
+      --terminal: #ffffff;
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; min-height: 100%; }
+    body {
+      background: var(--page);
+      color: var(--ink);
+      font: 16px/1.5 ui-sans-serif, system-ui, sans-serif;
+      display: flex;
+      flex-direction: column;
+      min-height: 100vh;
+    }
+    header, main, footer { width: 100%; max-width: 1120px; margin: 0 auto; padding: 0 16px; }
+    header { padding-top: 32px; display: flex; flex-wrap: wrap; align-items: end; justify-content: space-between; gap: 8px 24px; }
+    h1 { margin: 0; color: var(--ink-strong); font-size: clamp(28px, 5vw, 44px); font-weight: 600; line-height: 1.05; letter-spacing: -0.03em; }
+    .pitch { margin: 8px 0 0; color: var(--muted); font-size: 17px; max-width: 62ch; text-wrap: pretty; }
+    a { color: var(--accent); text-underline-offset: 3px; }
+    .tools { display: flex; align-items: center; gap: 16px; position: relative; }
+    .repo { font-size: 15px; white-space: nowrap; }
+    #theme-button {
+      font: inherit; font-size: 13px; line-height: 1;
+      display: inline-flex; align-items: center; gap: 8px;
+      background: var(--surface); color: var(--ink);
+      border: 1px solid var(--line); border-radius: 6px; padding: 8px 11px; cursor: pointer;
+    }
+    #theme-button:hover, #theme-button:focus-visible, #theme-button[aria-expanded="true"] { border-color: var(--accent); color: var(--accent); outline: none; }
+    .swatch { display: inline-flex; border-radius: 99px; overflow: hidden; border: 1px solid var(--line); flex: none; }
+    .swatch i { width: 9px; height: 14px; display: block; }
+    #theme-list {
+      position: absolute; top: calc(100% + 8px); right: 0; z-index: 10; width: 240px; max-height: min(60vh, 420px); overflow: auto;
+      margin: 0; padding: 4px; list-style: none;
+      background: var(--surface); border: 1px solid var(--line); border-radius: 8px; box-shadow: 0 12px 32px #0006;
+    }
+    #theme-list[hidden] { display: none; }
+    #theme-list li { display: flex; align-items: center; gap: 10px; padding: 7px 9px; border-radius: 5px; font-size: 14px; cursor: pointer; }
+    #theme-list li[aria-selected="true"] { color: var(--accent); }
+    #theme-list li.active { background: var(--line); }
+    main { flex: 1; display: flex; flex-direction: column; gap: 12px; padding-top: 24px; padding-bottom: 16px; }
+    .hints { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+    .hints span { color: var(--muted); font-size: 14px; margin-right: 4px; }
+    .hints button {
+      font: 13px/1 "JetBrainsMono Nerd Font Mono", ui-monospace, Menlo, Consolas, monospace;
+      background: var(--surface);
+      color: var(--ink);
+      border: 1px solid var(--line);
+      border-radius: 6px;
+      padding: 8px 11px;
+      cursor: pointer;
+      transition: border-color 120ms, color 120ms;
+    }
+    .hints button:hover:not(:disabled), .hints button:focus-visible { border-color: var(--accent); color: var(--accent); outline: none; }
+    .hints button:disabled { opacity: 0.45; cursor: progress; }
+    .panel {
+      flex: 1;
+      min-height: 440px;
+      display: flex;
+      background: var(--terminal);
+      border-radius: 8px;
+      padding: 14px 6px 6px 14px;
+      overflow: hidden;
+    }
+    #terminal { flex: 1; min-width: 0; }
+    #terminal .xterm, #terminal .xterm-viewport, #terminal .xterm-scrollable-element { background-color: var(--terminal) !important; }
+    /* No focus ring inside the terminal; the blinking cursor shows focus. */
+    #terminal .xterm:focus, #terminal .xterm :focus { outline: none; }
+    footer { padding-bottom: 24px; color: var(--muted); font-size: 13px; }
+    @media (max-width: 600px) {
+      header { padding-top: 20px; }
+      .pitch { font-size: 16px; }
+      .panel { min-height: 380px; padding: 8px 2px 2px 8px; }
+    }
+  </style>
+  <link rel="stylesheet" href="skin.css">
+</head>
+<body>
+  <header>
+    <div>
+      <h1 id="title">Loading…</h1>
+      <p class="pitch" id="pitch"></p>
+    </div>
+    <div class="tools">
+      <a class="repo" id="repo" hidden>Source on GitHub</a>
+      <button id="theme-button" type="button" aria-haspopup="listbox" aria-expanded="false" hidden><span class="swatch" id="theme-swatch"></span><span id="theme-name"></span></button>
+      <ul id="theme-list" role="listbox" aria-label="Theme" tabindex="-1" hidden></ul>
+    </div>
+  </header>
+  <main>
+    <div class="hints" id="hints"><span>Try</span></div>
+    <div class="panel"><div id="terminal"></div></div>
+  </main>
+  <footer id="disclosure">Runs entirely in your browser in a WebContainers Node.js sandbox.</footer>
+
+  <script type="module">
+    import { WebContainer } from "https://cdn.jsdelivr.net/npm/@webcontainer/api@1.6.4/+esm";
+
+    // Start the slow parts at once and in parallel: the sandbox boot, the files, the config, the terminal code and the font.
+    // The sandbox home is always /home/demo, so recipes can write absolute paths into their settings.
+    const started = performance.now();
+    const timings = {};
+    const mark = (name) => { timings[name] = Math.round(performance.now() - started); };
+    window.demoTimings = timings;
+    const booting = crossOriginIsolated ? WebContainer.boot({ workdirName: "demo" }) : null;
+    const filesLoad = fetch("files.json").then((response) => response.json()).then(decode);
+    const configLoad = fetch("terminal.json").then((response) => response.json());
+    const themesLoad = fetch("themes.json").then((response) => response.json()).catch(() => []);
+    const terminalCode = Promise.all([
+      import("https://cdn.jsdelivr.net/npm/@xterm/xterm@6.0.0/+esm"),
+      import("https://cdn.jsdelivr.net/npm/@xterm/addon-webgl@0.19.0/+esm"),
+      import("https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.11.0/+esm"),
+    ]);
+    // Both weights before the terminal opens: xterm measures glyphs once and does not redraw when a font arrives.
+    const mono = '"JetBrainsMono Nerd Font Mono"';
+    const fontLoad = Promise.race([
+      Promise.all([document.fonts.load(`14px ${mono}`), document.fonts.load(`bold 14px ${mono}`)]),
+      new Promise((resolve) => setTimeout(resolve, 2500)),
+    ]);
+
+    const config = await configLoad;
+    const seedLoad = config.seed ? import(new URL(config.seed, location.href)) : null;
+    document.title = `${config.title}: try it in your browser`;
+    document.getElementById("title").textContent = config.title;
+    document.getElementById("pitch").textContent = config.pitch ?? "";
+    if (config.repo) Object.assign(document.getElementById("repo"), { href: config.repo, hidden: false });
+    if (config.disclosure) document.getElementById("disclosure").textContent = config.disclosure;
+    const themes = await themesLoad;
+    const storeKey = "browser-terminal.theme";
+    const stored = (() => { try { return JSON.parse(localStorage.getItem(storeKey))?.name; } catch { return undefined; } })();
+    const pick = (name) => themes.find((theme) => theme.name === name);
+    let current = pick(stored) ?? pick(config.defaultTheme) ?? themes[0];
+    // Bright ANSI colors are the normal ones lifted a quarter of the way toward the theme's brightest ink.
+    const lift = (color, toward) => `#${[1, 3, 5].map((at) => Math.round(parseInt(color.slice(at, at + 2), 16) * 0.75 + parseInt(toward.slice(at, at + 2), 16) * 0.25).toString(16).padStart(2, "0")).join("")}`;
+    const terminalColors = ({ terminal, ink, inkStrong, accent, line, ansi }) => ({
+      background: terminal, foreground: ink, cursor: accent, cursorAccent: terminal, selectionBackground: line, selectionForeground: inkStrong,
+      black: ansi.black, red: ansi.red, green: ansi.green, yellow: ansi.yellow, blue: ansi.blue, magenta: ansi.magenta, cyan: ansi.cyan, white: ansi.white,
+      brightBlack: ansi.brightBlack, brightRed: lift(ansi.red, inkStrong), brightGreen: lift(ansi.green, inkStrong), brightYellow: lift(ansi.yellow, inkStrong),
+      brightBlue: lift(ansi.blue, inkStrong), brightMagenta: lift(ansi.magenta, inkStrong), brightCyan: lift(ansi.cyan, inkStrong), brightWhite: ansi.brightWhite,
+    });
+    let term;
+    // The sandbox learns the theme too: ~/.config/showcase/theme.json holds the page's colors and the terminal
+    // palette, rewritten on every change, and the recipe's onTheme command can turn it into a program's own theme.
+    let sandbox = null;
+    let shared = Promise.resolve();
+    let shareTimer;
+    async function writeTheme(theme) {
+      if (!sandbox || !theme) return;
+      const { container, env } = sandbox;
+      const { name, label, mode, page, ink, inkStrong, muted, accent, surface, line, terminal } = theme;
+      await container.fs.mkdir(".config/showcase", { recursive: true });
+      await container.fs.writeFile(".config/showcase/theme.json", `${JSON.stringify({ name, label, mode, page, ink, inkStrong, muted, accent, surface, line, terminal, palette: terminalColors(theme) }, null, 2)}\n`);
+      if (config.onTheme) await run(container, config.onTheme, env);
+    }
+    function shareTheme(theme) {
+      clearTimeout(shareTimer);
+      // Arrow keys preview themes quickly; only the one the visitor rests on is written.
+      shareTimer = setTimeout(() => { shared = shared.then(() => writeTheme(theme)).catch((error) => console.warn("onTheme failed", error)); }, 150);
+    }
+    // Page and terminal change together; xterm maps its palette onto whatever the programs print.
+    function apply(theme, save) {
+      const vars = { page: theme.page, ink: theme.ink, "ink-strong": theme.inkStrong, muted: theme.muted, accent: theme.accent, surface: theme.surface, line: theme.line, terminal: theme.terminal };
+      for (const [name, value] of Object.entries(vars)) document.documentElement.style.setProperty(`--${name}`, value);
+      document.documentElement.style.colorScheme = document.documentElement.dataset.theme = theme.mode;
+      if (term) term.options.theme = terminalColors(theme);
+      shareTheme(theme);
+      if (save) try { localStorage.setItem(storeKey, JSON.stringify({ name: theme.name, mode: theme.mode, vars })); } catch {}
+    }
+    if (current) apply(current);
+
+    const [[{ Terminal }, { WebglAddon }, { FitAddon }]] = await Promise.all([terminalCode, fontLoad]);
+    term = new Terminal({
+      cursorBlink: true,
+      convertEol: true,
+      fontFamily: `${mono}, ui-monospace, Menlo, Consolas, monospace`,
+      fontSize: 14,
+      lineHeight: 1.25,
+      scrollback: 5000,
+      theme: current ? terminalColors(current) : undefined,
+    });
+    const fit = new FitAddon();
+    term.loadAddon(fit);
+    term.open(document.getElementById("terminal"));
+    // GPU rendering; the DOM renderer takes over if WebGL is unavailable or its context is lost.
+    try {
+      const webgl = new WebglAddon();
+      webgl.onContextLoss(() => webgl.dispose());
+      term.loadAddon(webgl);
+      timings.renderer = "webgl";
+    } catch {
+      timings.renderer = "dom";
+    }
+    fit.fit();
+    mark("terminal");
+    // The theme picker: arrows preview a theme in the page and the terminal, Enter keeps it, Esc puts the old one back.
+    if (themes.length > 1) {
+      const button = document.getElementById("theme-button");
+      const list = document.getElementById("theme-list");
+      const swatch = (theme) => [theme.page, theme.accent, theme.ink].map((color) => `<i style="background:${color}"></i>`).join("");
+      const rows = themes.map((theme) => {
+        const row = Object.assign(document.createElement("li"), { role: "option", innerHTML: `<span class="swatch">${swatch(theme)}</span><span>${theme.label}</span>` });
+        row.dataset.name = theme.name;
+        list.append(row);
+        return row;
+      });
+      let chosen = current;
+      let cursor = 0;
+      const show = () => {
+        document.getElementById("theme-swatch").innerHTML = swatch(current);
+        document.getElementById("theme-name").textContent = current.label;
+        rows.forEach((row) => row.setAttribute("aria-selected", String(row.dataset.name === current.name)));
+      };
+      const open = (isOpen) => {
+        list.hidden = !isOpen;
+        button.setAttribute("aria-expanded", String(isOpen));
+        if (isOpen) { chosen = current; move(themes.indexOf(current)); list.focus(); }
+      };
+      const move = (index) => {
+        cursor = (index + themes.length) % themes.length;
+        rows.forEach((row, i) => row.classList.toggle("active", i === cursor));
+        rows[cursor].scrollIntoView({ block: "nearest" });
+        current = themes[cursor];
+        apply(current);
+        show();
+      };
+      const close = (keep) => {
+        if (keep) apply(current, true); else { current = chosen; apply(current); }
+        show();
+        open(false);
+        button.focus();
+      };
+      button.hidden = false;
+      show();
+      button.addEventListener("click", () => open(list.hidden));
+      list.addEventListener("click", (event) => {
+        const row = event.target.closest("li");
+        if (row) { current = pick(row.dataset.name); close(true); }
+      });
+      list.addEventListener("keydown", (event) => {
+        if (event.key === "ArrowDown") move(cursor + 1);
+        else if (event.key === "ArrowUp") move(cursor - 1);
+        else if (event.key === "Enter") close(true);
+        else if (event.key === "Escape" || event.key === "Tab") close(false);
+        else return;
+        event.preventDefault();
+      });
+      document.addEventListener("click", (event) => { if (!list.hidden && !event.target.closest(".tools")) close(false); });
+    }
+
+    // For automated checks: the terminal text.
+    window.terminalText = () => {
+      const buffer = term.buffer.active;
+      return Array.from({ length: buffer.length }, (_, row) => buffer.getLine(row)?.translateToString(true) ?? "").join("\n");
+    };
+
+    const dim = (text) => `\x1b[2m${text}\x1b[0m`;
+    const red = (text) => `\x1b[31m${text}\x1b[0m`;
+    let input;
+    const hints = document.getElementById("hints");
+    for (const hint of config.hints ?? []) {
+      const button = Object.assign(document.createElement("button"), { textContent: hint, disabled: true, title: `Run ${hint}` });
+      button.addEventListener("click", () => {
+        input?.write(`${hint}\r`);
+        term.focus();
+      });
+      hints.append(button);
+    }
+
+    // Binary files arrive as base64 (see src/terminal.js).
+    function decode(tree) {
+      for (const node of Object.values(tree)) {
+        if (node.directory) decode(node.directory);
+        else if (node.file?.base64 !== undefined) node.file = { contents: Uint8Array.from(atob(node.file.base64), (char) => char.charCodeAt(0)) };
+      }
+      return tree;
+    }
+
+    function merge(tree, extra) {
+      for (const [name, node] of Object.entries(extra)) {
+        if (node.directory && tree[name]?.directory) merge(tree[name].directory, node.directory);
+        else tree[name] = node;
+      }
+      return tree;
+    }
+
+    async function run(container, command, env) {
+      const [name, ...args] = command.split(" ");
+      const child = await container.spawn(name, args, { env });
+      let output = "";
+      child.output.pipeTo(new WritableStream({ write(data) { output += data; } }));
+      const code = await child.exit;
+      if (code !== 0) throw new Error(`'${command}' exited with ${code}\n${output}`);
+      return output;
+    }
+
+    try {
+      if (!booting) throw new Error("This page needs cross-origin isolation (COOP/COEP headers) to run the sandbox.");
+      term.write(dim("Booting a Node.js sandbox in your browser…"));
+      const [container, files, seedModule] = await Promise.all([booting, filesLoad, seedLoad]);
+      mark("boot");
+      // A recipe's seed adds files computed at visit time (dates relative to today) without starting a process.
+      await container.mount(seedModule ? merge(files, seedModule.default(files)) : files);
+      mark("mount");
+      const home = container.workdir;
+      // Env values may use ~ for the sandbox home and $PATH for the default PATH (which costs one extra process).
+      const values = Object.entries(config.env ?? {});
+      const basePath = values.some(([, value]) => value.includes("$PATH"))
+        ? (await run(container, "node -p process.env.PATH", {})).trim()
+        : "/usr/local/bin:/usr/bin:/bin";
+      const expand = (value) => value.replace(/(^|:)~(?=\/|:|$)/g, `$1${home}`).replace("$PATH", basePath);
+      const env = { HOME: home, PATH: basePath, ...Object.fromEntries(values.map(([key, value]) => [key, expand(value)])) };
+      sandbox = { container, env };
+      // Setup runs while the shell starts; the shell itself never needs the seeded files.
+      const steps = config.setup ?? [];
+      let progress = "Getting ready";
+      const setup = (async () => {
+        // The theme is in place before setup, so whatever setup or start launches reads it.
+        await writeTheme(current);
+        for (const [index, command] of steps.entries()) {
+          progress = `Setting up the sandbox (${index + 1}/${steps.length})`;
+          await run(container, command, env);
+        }
+        mark("setup");
+      })();
+
+      term.reset();
+      term.write(`${(config.welcome ?? []).join("\n")}\n\n`);
+      // Until setup is done the shell is held back: a spinner stands in for its prompt and keys are dropped,
+      // so nothing typed early ends up in front of the start command.
+      let shellOpen = false;
+      let held = "";
+      let typedEarly = false;
+      const frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+      let frame = 0;
+      const spin = () => term.write(`\r\x1b[2K${dim(`${frames[frame++ % frames.length]} ${progress}…${typedEarly ? "  Typing opens once this is done." : ""}`)}`);
+      spin();
+      const spinner = setInterval(spin, 80);
+      const openShell = () => {
+        clearInterval(spinner);
+        term.write(`\r\x1b[2K${held}`);
+        shellOpen = true;
+      };
+      const shell = await container.spawn("jsh", { env, terminal: { cols: term.cols, rows: term.rows } });
+      let prompted;
+      const firstPrompt = new Promise((resolve) => { prompted = resolve; }).then(() => mark("prompt"));
+      shell.output.pipeTo(new WritableStream({
+        write(data) {
+          if (shellOpen) term.write(data); else held += data;
+          prompted();
+        },
+      }));
+      // Buttons wait for the first prompt and the setup, so a click never runs ahead of either.
+      Promise.all([firstPrompt, setup]).then(() => {
+        openShell();
+        // The recipe's start command is typed into the shell, so the visitor sees what launched and can run it again.
+        if (config.start) input.write(`${config.start}\r`);
+        for (const button of hints.querySelectorAll("button")) button.disabled = false;
+        mark("ready");
+        window.demoReady = true;
+      }, (error) => {
+        openShell();
+        term.write(red(`\nSetup failed: ${error.message}\n`));
+        window.demoError = error.message;
+      });
+      input = shell.input.getWriter();
+      term.onData((data) => {
+        if (shellOpen) input.write(data);
+        else typedEarly = true;
+      });
+      new ResizeObserver(() => {
+        fit.fit();
+        shell.resize({ cols: term.cols, rows: term.rows });
+      }).observe(document.querySelector(".panel"));
+      term.focus();
+    } catch (error) {
+      term.write(red(`\n${error.message}\n`));
+      if (/SharedArrayBuffer|isolation|WebContainer/i.test(error.message)) {
+        term.write(dim("Try a recent Chrome, Edge or Firefox on a desktop. Safari support is partial.\n"));
+      }
+      window.demoError = error.message;
+    }
+  </script>
+</body>
+</html>

package/page/themes.json

@@ -0,0 +1 @@
+[{"name":"dark","label":"Dark","mode":"dark","page":"#111113","terminal":"#0b0b0c","surface":"#1c1c1f","line":"#2e2e33","ink":"#d4d4d8","inkStrong":"#fafafa","muted":"#a1a1aa","accent":"#60a5fa","ansi":{"red":"#f87171","green":"#4ade80","yellow":"#facc15","blue":"#60a5fa","magenta":"#c084fc","cyan":"#22d3ee","black":"#1c1c1f","white":"#d4d4d8","brightWhite":"#fafafa","brightBlack":"#a1a1aa"}},{"name":"light","label":"Light","mode":"light","page":"#fafafa","terminal":"#ffffff","surface":"#f4f4f5","line":"#e4e4e7","ink":"#27272a","inkStrong":"#09090b","muted":"#52525b","accent":"#2563eb","ansi":{"red":"#dc2626","green":"#16a34a","yellow":"#a16207","blue":"#2563eb","magenta":"#9333ea","cyan":"#0e7490","black":"#e4e4e7","white":"#27272a","brightWhite":"#09090b","brightBlack":"#52525b"}}]

package/src/terminal.js

@@ -0,0 +1,146 @@
+// Builds the browser terminal recipe: a static page that boots a Node.js sandbox (WebContainers) and opens a shell in it.
+import { copyFile, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const assets = fileURLToPath(new URL("../page/", import.meta.url));
+const skip = new Set([".git", "node_modules"]);
+
+// Paths in terminal.json may start with ~ and use $VARS.
+function resolvePath(raw, base) {
+  const expanded = raw
+    .replace(/^~(?=$|\/)/, os.homedir())
+    .replace(/\$(?:\{(\w+)\}|(\w+))/g, (_, braced, bare) => {
+      const value = process.env[braced ?? bare];
+      if (value === undefined) throw new Error(`$${braced ?? bare} not set`);
+      return value;
+    });
+  return path.resolve(base, expanded);
+}
+
+// The project's facts live in its showcase.json (github.com/Soleone/showcase). Without one, terminal.json
+// carries the title and pitch itself.
+async function readFacts(project) {
+  const file = path.join(project, "showcase.json");
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new Error(`${file}: ${error.message}`);
+  }
+}
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+// Text stays readable in files.json; anything else (images, loops) travels as base64 and the page decodes it.
+function fileNode(buffer) {
+  try {
+    return { file: { contents: utf8.decode(buffer) } };
+  } catch {
+    return { file: { base64: buffer.toString("base64") } };
+  }
+}
+
+// Reads a folder into a WebContainer FileSystemTree; `include` limits the top-level entries.
+async function tree(folder, include) {
+  const result = {};
+  for (const entry of await readdir(folder, { withFileTypes: true })) {
+    if (include ? !include.includes(entry.name) : skip.has(entry.name)) continue;
+    const file = path.join(folder, entry.name);
+    if (entry.isDirectory()) result[entry.name] = { directory: await tree(file) };
+    else if (entry.isFile()) result[entry.name] = fileNode(await readFile(file));
+  }
+  return result;
+}
+
+// Places a subtree at a path like "node_modules/my-cli" inside the root tree.
+function place(root, target, subtree) {
+  const parts = target.split("/").filter((part) => part && part !== ".");
+  let node = root;
+  for (const part of parts) {
+    node[part] ??= { directory: {} };
+    node = node[part].directory;
+  }
+  Object.assign(node, subtree);
+}
+
+const isolationHeaders = { "Cross-Origin-Embedder-Policy": "require-corp", "Cross-Origin-Opener-Policy": "same-origin" };
+
+// The page says what is not real, from the project's demo.externals.
+function disclosure(title, externals = []) {
+  const notes = externals.filter((external) => external.standIn !== "real").map((external) => external.note ?? `${external.name}: ${external.standIn} stand-in.`);
+  return [`The real ${title} runs in a Node.js sandbox in your browser (WebContainers).`, ...notes, "Reload to start over."].join(" ");
+}
+
+// A skin is a folder or URL with the page's look: themes.json (the palettes) and skin.css (anything else, such
+// as fonts). Either file may be left out; the recipe's plain look fills in.
+async function skinFile(skin, name, recipeDir) {
+  if (!skin) return null;
+  if (/^https?:\/\//.test(skin)) {
+    const url = `${skin.replace(/\/$/, "")}/${name}`;
+    const response = await fetch(url);
+    if (response.status === 404) return null;
+    if (!response.ok) throw new Error(`${url}: ${response.status}`);
+    return response.text();
+  }
+  return readFile(path.join(resolvePath(skin, recipeDir), name), "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+}
+
+export async function buildTerminal(recipeDir, out) {
+  recipeDir = path.resolve(recipeDir);
+  out = path.resolve(out);
+  const recipeFile = path.join(recipeDir, "terminal.json");
+  const { mount, project, skin, ...recipe } = JSON.parse(await readFile(recipeFile, "utf8").catch(() => {
+    throw new Error(`No terminal.json in ${recipeDir}. See https://github.com/Soleone/showcase-terminal#readme`);
+  }));
+  if (!mount) throw new Error(`${recipeFile}: mount is required`);
+  // Facts come from the project's showcase.json; terminal.json only adds what is specific to this page.
+  const facts = project ? await readFacts(resolvePath(project, recipeDir)) : {};
+  const config = { title: facts.title, pitch: facts.pitch, repo: facts.repo, ...recipe };
+  config.disclosure ??= disclosure(config.title, facts.demo?.externals);
+  const files = {};
+  for (const [target, { from, include }] of Object.entries(mount)) {
+    place(files, target, await tree(resolvePath(from, recipeDir), include));
+  }
+  await mkdir(out, { recursive: true });
+  await copyFile(path.join(assets, "index.html"), path.join(out, "index.html"));
+  await writeFile(path.join(out, "themes.json"), await skinFile(skin, "themes.json", recipeDir) ?? await readFile(path.join(assets, "themes.json")));
+  await writeFile(path.join(out, "skin.css"), await skinFile(skin, "skin.css", recipeDir) ?? "");
+  await cp(path.join(assets, "fonts"), path.join(out, "fonts"), { recursive: true, filter: (source) => !source.endsWith(".sh") });
+  await writeFile(path.join(out, "files.json"), JSON.stringify(files));
+  if (config.seed) await copyFile(path.join(recipeDir, config.seed), path.join(out, config.seed));
+  await writeFile(path.join(out, "terminal.json"), `${JSON.stringify(config, null, 2)}\n`);
+  await writeFile(path.join(out, "vercel.json"), `${JSON.stringify({
+    headers: [
+      { source: "/(.*)", headers: Object.entries(isolationHeaders).map(([key, value]) => ({ key, value })) },
+      { source: "/fonts/(.*)", headers: [{ key: "Cache-Control", value: "public, max-age=31536000, immutable" }] },
+    ],
+  }, null, 2)}\n`);
+  return { out, bytes: JSON.stringify(files).length };
+}
+
+const types = { ".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json", ".js": "text/javascript", ".woff2": "font/woff2", ".txt": "text/plain" };
+
+// Serves a built page on this machine only, with the headers the sandbox needs.
+export function serveTerminal(out, port = 4321) {
+  out = path.resolve(out);
+  return new Promise((resolve, reject) => {
+    const server = createServer(async (request, response) => {
+      const name = new URL(request.url, "http://localhost").pathname.replace(/\/$/, "/index.html");
+      const file = path.join(out, path.normalize(name));
+      if (!file.startsWith(out + path.sep)) return response.writeHead(403).end();
+      try {
+        const body = await readFile(file);
+        response.writeHead(200, { "Content-Type": types[path.extname(file)] ?? "application/octet-stream", ...isolationHeaders }).end(body);
+      } catch {
+        response.writeHead(404).end("Not found");
+      }
+    });
+    server.once("error", reject).listen(port, "127.0.0.1", () => resolve(server));
+  });
+}