@soleone/showcase-terminal 0.1.0 → 0.2.0

package/README.md

@@ -20,9 +20,9 @@ Keep the recipe folder in the project itself (`demo/browser/` by default), so th
 - `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.
+- `skin`: a folder or URL with the page's look, `themes.json` (palettes, same shape as `page/themes.json`) `skin.css` (fonts and other touches, loaded after the page's styles) and `skin.js` (a theme picker, below). Any of them 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 output is static: `index.html`, `files.json`, `terminal.json`, `themes.json`, `skin.css`, `skin.js` when the skin has one, `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.
 
@@ -37,6 +37,18 @@ WebContainers is free for personal and open-source use; check the StackBlitz lic
 
 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.
 
+A skin can bring its own picker as `skin.js`, an ES module whose default export the page calls once the terminal is up, instead of drawing its dropdown:
+
+```js
+export default function ({ themes, current, apply, mount }) {
+  // themes: the entries of themes.json; current: the one in use
+  // apply(theme): recolors the page and the terminal, tells the sandbox (onTheme) and remembers the choice
+  // mount: an empty element in the page header for the picker's button
+}
+```
+
+The page keeps its state where a theme kit can read it: `data-theme` on `<html>` is the theme's name, `data-mode` and the `dark` class its mode. Its own colors are the CSS variables `--page`, `--ink`, `--ink-strong`, `--ink-muted`, `--highlight`, `--surface`, `--line` and `--terminal`.
+
 From code:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleone/showcase-terminal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Build a static page that runs a CLI for real in the visitor's browser (WebContainers).",
   "license": "MIT",
   "author": "Soleone",

package/page/index.html

@@ -15,11 +15,18 @@
   <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).
+    // Puts the visitor's theme on before first paint (apply() saves the resolved colors when one is picked).
+    // data-theme holds the theme's name and .dark its mode, where a skin's theme kit expects them.
+    // A choice saved before the variables were renamed waits for themes.json instead.
     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;
+      if (saved.vars.highlight) {
+        const root = document.documentElement;
+        for (const [name, value] of Object.entries(saved.vars)) root.style.setProperty(`--${name}`, value);
+        root.style.colorScheme = root.dataset.mode = saved.mode;
+        root.dataset.theme = saved.name;
+        root.classList.toggle("dark", saved.mode === "dark");
+      }
     } catch {}
   </script>
   <style>
@@ -42,37 +49,39 @@
       --page: #111113;
       --ink: #d4d4d8;
       --ink-strong: #fafafa;
-      --muted: #a1a1aa;
-      --accent: #60a5fa;
+      --ink-muted: #a1a1aa;
+      --highlight: #60a5fa;
       --surface: #1c1c1f;
       --line: #2e2e33;
       --terminal: #0b0b0c;
     }
     @media (prefers-color-scheme: light) {
-      :root:not([data-theme="dark"]) {
+      :root:not([data-mode="dark"]) {
         color-scheme: light;
         --page: #fafafa;
         --ink: #27272a;
         --ink-strong: #09090b;
-        --muted: #52525b;
-        --accent: #2563eb;
+        --ink-muted: #52525b;
+        --highlight: #2563eb;
         --surface: #f4f4f5;
         --line: #e4e4e7;
         --terminal: #ffffff;
       }
     }
-    :root[data-theme="light"] {
+    :root[data-mode="light"] {
       color-scheme: light;
       --page: #fafafa;
       --ink: #27272a;
       --ink-strong: #09090b;
-      --muted: #52525b;
-      --accent: #2563eb;
+      --ink-muted: #52525b;
+      --highlight: #2563eb;
       --surface: #f4f4f5;
       --line: #e4e4e7;
       --terminal: #ffffff;
     }
     * { box-sizing: border-box; }
+    /* An id or class that sets display would otherwise show a hidden element (a skin's picker relies on this too). */
+    [hidden] { display: none !important; }
     html, body { margin: 0; min-height: 100%; }
     body {
       background: var(--page);
@@ -85,8 +94,8 @@
     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; }
+    .pitch { margin: 8px 0 0; color: var(--ink-muted); font-size: 17px; max-width: 62ch; text-wrap: pretty; }
+    a { color: var(--highlight); text-underline-offset: 3px; }
     .tools { display: flex; align-items: center; gap: 16px; position: relative; }
     .repo { font-size: 15px; white-space: nowrap; }
     #theme-button {
@@ -95,7 +104,7 @@
       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; }
+    #theme-button:hover, #theme-button:focus-visible, #theme-button[aria-expanded="true"] { border-color: var(--highlight); color: var(--highlight); 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 {
@@ -103,13 +112,12 @@
       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[aria-selected="true"] { color: var(--highlight); }
     #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 span { color: var(--ink-muted); font-size: 14px; margin-right: 4px; }
     .hints button {
       font: 13px/1 "JetBrainsMono Nerd Font Mono", ui-monospace, Menlo, Consolas, monospace;
       background: var(--surface);
@@ -120,7 +128,7 @@
       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:hover:not(:disabled), .hints button:focus-visible { border-color: var(--highlight); color: var(--highlight); outline: none; }
     .hints button:disabled { opacity: 0.45; cursor: progress; }
     .panel {
       flex: 1;
@@ -135,7 +143,7 @@
     #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; }
+    footer { padding-bottom: 24px; color: var(--ink-muted); font-size: 13px; }
     @media (max-width: 600px) {
       header { padding-top: 20px; }
       .pitch { font-size: 16px; }
@@ -228,9 +236,12 @@
     }
     // 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;
+      const vars = { page: theme.page, ink: theme.ink, "ink-strong": theme.inkStrong, "ink-muted": theme.muted, highlight: theme.accent, surface: theme.surface, line: theme.line, terminal: theme.terminal };
+      const root = document.documentElement;
+      for (const [name, value] of Object.entries(vars)) root.style.setProperty(`--${name}`, value);
+      root.style.colorScheme = root.dataset.mode = theme.mode;
+      root.dataset.theme = theme.name;
+      root.classList.toggle("dark", theme.mode === "dark");
       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 {}
@@ -261,8 +272,16 @@
     }
     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) {
+    // A skin's skin.js draws its own theme picker in place of the built-in one.
+    if (config.skinScript && themes.length > 1) {
+      const mount = document.createElement("div");
+      document.querySelector(".tools").append(mount);
+      // Not awaited: the shell does not wait for the picker.
+      import(new URL(config.skinScript, location.href))
+        .then(({ default: skin }) => skin({ themes, current, mount, apply: (theme) => { current = theme; apply(theme, true); } }))
+        .catch((error) => console.warn("skin.js failed", error));
+    } else if (themes.length > 1) {
+      // The theme picker: arrows preview a theme in the page and the terminal, Enter keeps it, Esc puts the old one back.
       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("");

package/src/terminal.js

@@ -74,8 +74,9 @@ function disclosure(title, externals = []) {
   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.
+// A skin is a folder or URL with the page's look: themes.json (the palettes), skin.css (anything else, such
+// as fonts) and skin.js (a theme picker in place of the built-in one). Any of them 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)) {
@@ -111,6 +112,11 @@ export async function buildTerminal(recipeDir, out) {
   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) ?? "");
+  const skinScript = await skinFile(skin, "skin.js", recipeDir);
+  if (skinScript !== null) {
+    await writeFile(path.join(out, "skin.js"), skinScript);
+    config.skinScript = "skin.js";
+  }
   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));