@inthedark/wb 0.0.1 → 0.0.3

package/README.md

@@ -1,60 +1,60 @@
-
-# workbench
-
-an agentic ide about the human
-
-## how 2 use
-```bash
-# install & open
-npx @inthedark/wb
-
-# set up daemon on another device
-npx @inthedark/wb connect
-```
-
-## features
-
-key features:
-- fully customisable agent instructions with support for comments & imports
-- strong thread transcript UX for when you need to keep an eye on a thread (command matching + html elements for agents)
-- strong thread management UX for when you're managing LOTS of threads (thread status-sorted sidebar)
-- better shared workspace support than any other agentic ide, because a lot of work is not worktree->pr shaped; agents claim the files they need and other agents don't freak out about unclaimed dirt
-- near-identical agent behaviour across providers (codex, opencode 2, claude code) as if they're the same harness
-- agents can orchestrate subagents working in threads across providers and projects
-- customisable voice to text ("what if voice to text was like working in a rich text editor")
-- git UI for doing your own work at the same time as other agents, allowing easy commits while agents have other files claimed
-- quickly switch between saved profiles for harness/model/effort/window/fast mode/agent identity
-- automatic compaction on turn start past configurable time & token thresholds (reduce cache write costs)
-- agents can search repos with shell tools like they're on disk via vfs
-
-setup/meta:
-- built on top of other harnesses (codex, opencode 2, claude code) so you can use subscriptions
-- tailscale integration
-- daemon sleeps when idle, leaving only a light http wake service up
-
-unpolished/unfinished/broken stuff (coming soon tm!!!!!):
-- soon, autocomplete/suggestions extension for vscode & similar (highly configurable, able to be FAST)
-- worktree->pr workflow is unsupported (gonna be honest i have been in a cave working solo on wb for so long that i have not needed this yet)
-- browse AX & UX
-- search UX
-- i'd like more git ui
-- many places around the app could use a UI polish pass
-- the codebase itself could use a polish pass, esp. the react & tailwind
-
-## tech
-
-note: have tried to keep dependencies minimal for the most part
-
-`/package` — the entrypoint/installer, what actually gets published to npm  
-`/daemon/host` — wake service  
-`/daemon/server` — workbench harness  
-`/daemon/voice` - vtt service (rust)  
-`/instructions` — instructions for agents, copied into the user's `~/.workbench` folder whenever read  
-`/app/server` — server for frontend app  
-`/app/client` — frontend SPA  
-`/app/tray` — system tray application for the frontend app (rust/tauri)  
-`/shared` — shared stuff between the projects  
-`/shared/network/native` — tailscale integration (go)  
-`/test` — test runner  
-`/scripts` — stuff used by package scripts plus anything i didn't notice an agent left behind :3  
-`/docs` — help agents find things and not break them without eating all their tokens
+
+# workbench
+
+an agentic ide about the human
+
+## how 2 use
+```bash
+# install & open
+npx @inthedark/wb
+
+# set up daemon on another device
+npx @inthedark/wb connect
+```
+
+## features
+
+key features:
+- fully customisable agent instructions with support for comments & imports
+- strong thread transcript UX for when you need to keep an eye on a thread (command matching + html elements for agents)
+- strong thread management UX for when you're managing LOTS of threads (thread status-sorted sidebar)
+- better shared workspace support than any other agentic ide, because a lot of work is not worktree->pr shaped; agents claim the files they need and other agents don't freak out about unclaimed dirt
+- near-identical agent behaviour across providers (codex, opencode 2, claude code) as if they're the same harness
+- agents can orchestrate subagents working in threads across providers and projects
+- customisable voice to text ("what if voice to text was like working in a rich text editor")
+- git UI for doing your own work at the same time as other agents, allowing easy commits while agents have other files claimed
+- quickly switch between saved profiles for harness/model/effort/window/fast mode/agent identity
+- automatic compaction on turn start past configurable time & token thresholds (reduce cache write costs)
+- agents can search repos with shell tools like they're on disk via vfs
+
+setup/meta:
+- built on top of other harnesses (codex, opencode 2, claude code) so you can use subscriptions
+- tailscale integration
+- daemon sleeps when idle, leaving only a light http wake service up
+
+unpolished/unfinished/broken stuff (coming soon tm!!!!!):
+- soon, autocomplete/suggestions extension for vscode & similar (highly configurable, able to be FAST)
+- worktree->pr workflow is unsupported (gonna be honest i have been in a cave working solo on wb for so long that i have not needed this yet)
+- browse AX & UX
+- search UX
+- i'd like more git ui
+- many places around the app could use a UI polish pass
+- the codebase itself could use a polish pass, esp. the react & tailwind
+
+## tech
+
+note: have tried to keep dependencies minimal for the most part
+
+`/package` — the entrypoint/installer, what actually gets published to npm  
+`/daemon/host` — wake service  
+`/daemon/server` — workbench harness  
+`/daemon/voice` - vtt service (rust)  
+`/instructions` — instructions for agents, copied into the user's `~/.workbench` folder whenever read  
+`/app/server` — server for frontend app  
+`/app/client` — frontend SPA  
+`/app/tray` — system tray application for the frontend app (rust/tauri)  
+`/shared` — shared stuff between the projects  
+`/shared/network/native` — tailscale integration (go)  
+`/test` — test runner  
+`/scripts` — stuff used by package scripts plus anything i didn't notice an agent left behind :3  
+`/docs` — help agents find things and not break them without eating all their tokens

package/WorkbenchBootstrap.mjs

@@ -1,45 +1,45 @@
-/*
- * Exports:
- * - WorkbenchBootstrap (default): locates or installs an editable checkout and delegates to it.
- */
-import fs from "node:fs/promises";
-import { constants } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { DatabaseSync } from "node:sqlite";
-import WorkbenchBootstrapPrompt from "./WorkbenchBootstrapPrompt.mjs";
+/*
+ * Exports:
+ * - WorkbenchBootstrap (default): locates or installs an editable checkout and delegates to it.
+ */
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import WorkbenchInstallPrompt from "./WorkbenchInstallPrompt.mjs";
 import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
-
-export default class WorkbenchBootstrap {
-  constructor({
-    home = os.homedir(),
-    packageRoot = path.dirname(fileURLToPath(import.meta.url)),
-    environment = process.env,
-    prompt = new WorkbenchBootstrapPrompt(),
+
+export default class WorkbenchBootstrap {
+  constructor({
+    home = os.homedir(),
+    packageRoot = path.dirname(fileURLToPath(import.meta.url)),
+    environment = process.env,
+    prompt = new WorkbenchInstallPrompt(),
     commands = new WorkbenchBootstrapCommand(),
-    write = text => process.stdout.write(text),
-  } = {}) {
-    this.home = home;
-    this.packageRoot = packageRoot;
-    this.environment = environment;
-    this.prompt = prompt;
-    this.commands = commands;
-    this.write = write;
-    this.registry = path.join(home, ".workbench", "installation.json");
-  }
-
+    write = text => process.stdout.write(text),
+  } = {}) {
+    this.home = home;
+    this.packageRoot = packageRoot;
+    this.environment = environment;
+    this.prompt = prompt;
+    this.commands = commands;
+    this.write = write;
+    this.registry = path.join(home, ".workbench", "installation.json");
+  }
+
   async checkoutExists(root) {
     try {
       const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
       if (manifest.name !== "workbench-root") return false;
-      await fs.access(path.join(root, "wb"));
+      await fs.access(path.join(root, "wb"));
       await fs.access(path.join(root, "installation", "install.mjs"));
       await fs.access(path.join(root, "cli", "dispatch.mjs"));
-      return true;
-    } catch (error) {
-      if (error.code === "ENOENT") return false;
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
       throw error;
     }
   }
@@ -58,84 +58,84 @@ export default class WorkbenchBootstrap {
   async readInstallation() {
     try {
       const record = JSON.parse(await fs.readFile(this.registry, "utf8"));
-      if (record.version !== 1 || typeof record.root !== "string" || !path.isAbsolute(record.root)
-        || !["cloning", "setup", "ready"].includes(record.phase)) {
-        throw new Error(`Invalid Workbench installation record: ${this.registry}. Existing files were not changed.`);
-      }
-      return record;
-    } catch (error) {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    }
-  }
-
-  async writeInstallation(record) {
-    const candidate = `${this.registry}.${randomUUID()}.tmp`;
-    await fs.writeFile(candidate, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
-    await fs.rename(candidate, this.registry);
-  }
-
-  async requireTool(command, cwd) {
-    try {
-      await this.commands.run(command, ["--version"], {
-        cwd,
-        output: { write() {} },
-        errorOutput: { write() {} },
-      });
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      throw new Error(`${command} is required to install Workbench. Install it and make it available on PATH, then retry.`, { cause: error });
-    }
-  }
-
-  async discardIncomplete(record) {
-    const root = path.resolve(record.root);
-    if (root !== record.root || !["wb", "workbench"].includes(path.basename(root).toLowerCase())) {
-      throw new Error(`Cannot verify failed install destination ${record.root}; it was preserved.`);
-    }
-    let stat;
-    try { stat = await fs.lstat(root); }
-    catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      await fs.unlink(this.registry);
-      return;
-    }
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      throw new Error(`Failed install destination ${root} is not an ordinary directory; it was preserved.`);
-    }
-    if (await fs.realpath(root) !== root) {
-      throw new Error(`Failed install destination ${root} resolves elsewhere; it was preserved.`);
-    }
-    if ((await fs.readdir(root)).length) {
-      if (!await this.checkoutExists(root)) {
-        throw new Error(`Failed install destination ${root} is not a complete Workbench checkout; it was preserved.`);
-      }
-      const git = await fs.lstat(path.join(root, ".git")).catch(error => {
-        if (error.code === "ENOENT") return null;
-        throw error;
-      });
-      if (!git?.isDirectory() || git.isSymbolicLink()) {
-        throw new Error(`Failed install destination ${root} is not a regular Git clone; it was preserved.`);
-      }
-      let changes = "";
-      await this.commands.run("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
-        cwd: root,
-        output: { write: bytes => { changes += bytes.toString(); } },
-        errorOutput: { write() {} },
-      });
-      if (changes.trim()) throw new Error(`Failed install destination ${root} has changes; it was preserved.`);
-    }
-    await fs.rm(root, { recursive: true });
-    await fs.unlink(this.registry);
-  }
-
-  async run(args) {
-    const managed = this.environment.WORKBENCH_THREAD_ID || this.environment.CODEX_THREAD_ID;
-    const view = args[0] === "view" && (args.length === 1 || args.length === 2 && ["daemon", "app"].includes(args[1]));
-    const humanCommand = view || args.length === 0 || (args.length === 1 && ["connect", "disconnect", "shortcut"].includes(args[0]));
-    if (managed && humanCommand) throw new Error("Managed threads cannot install or launch Workbench services.");
-    const linked = path.resolve(this.packageRoot, "..");
-    if (await this.checkoutExists(linked)) {
+      if (record.version !== 1 || typeof record.root !== "string" || !path.isAbsolute(record.root)
+        || !["cloning", "setup", "ready"].includes(record.phase)) {
+        throw new Error(`Invalid Workbench installation record: ${this.registry}. Existing files were not changed.`);
+      }
+      return record;
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async writeInstallation(record) {
+    const candidate = `${this.registry}.${randomUUID()}.tmp`;
+    await fs.writeFile(candidate, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await fs.rename(candidate, this.registry);
+  }
+
+  async requireTool(command, cwd) {
+    try {
+      await this.commands.run(command, ["--version"], {
+        cwd,
+        output: { write() {} },
+        errorOutput: { write() {} },
+      });
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      throw new Error(`${command} is required to install Workbench. Install it and make it available on PATH, then retry.`, { cause: error });
+    }
+  }
+
+  async discardIncomplete(record) {
+    const root = path.resolve(record.root);
+    if (root !== record.root || !["wb", "workbench"].includes(path.basename(root).toLowerCase())) {
+      throw new Error(`Cannot verify failed install destination ${record.root}; it was preserved.`);
+    }
+    let stat;
+    try { stat = await fs.lstat(root); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      await fs.unlink(this.registry);
+      return;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`Failed install destination ${root} is not an ordinary directory; it was preserved.`);
+    }
+    if (await fs.realpath(root) !== root) {
+      throw new Error(`Failed install destination ${root} resolves elsewhere; it was preserved.`);
+    }
+    if ((await fs.readdir(root)).length) {
+      if (!await this.checkoutExists(root)) {
+        throw new Error(`Failed install destination ${root} is not a complete Workbench checkout; it was preserved.`);
+      }
+      const git = await fs.lstat(path.join(root, ".git")).catch(error => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (!git?.isDirectory() || git.isSymbolicLink()) {
+        throw new Error(`Failed install destination ${root} is not a regular Git clone; it was preserved.`);
+      }
+      let changes = "";
+      await this.commands.run("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
+        cwd: root,
+        output: { write: bytes => { changes += bytes.toString(); } },
+        errorOutput: { write() {} },
+      });
+      if (changes.trim()) throw new Error(`Failed install destination ${root} has changes; it was preserved.`);
+    }
+    await fs.rm(root, { recursive: true });
+    await fs.unlink(this.registry);
+  }
+
+  async run(args) {
+    const managed = this.environment.WORKBENCH_THREAD_ID || this.environment.CODEX_THREAD_ID;
+    const view = args[0] === "view" && (args.length === 1 || args.length === 2 && ["daemon", "app"].includes(args[1]));
+    const humanCommand = view || args.length === 0 || (args.length === 1 && ["connect", "disconnect", "shortcut"].includes(args[0]));
+    if (managed && humanCommand) throw new Error("Managed threads cannot install or launch Workbench services.");
+    const linked = path.resolve(this.packageRoot, "..");
+    if (await this.checkoutExists(linked)) {
       return await this.delegate(linked, args);
     }
     const installed = await this.readInstallation();
@@ -148,7 +148,7 @@ export default class WorkbenchBootstrap {
     }
     if (managed || !(args.length === 0 || (args.length === 1 && args[0] === "connect"))) {
       throw new Error("Workbench is not installed. Run wb or wb connect in an interactive terminal first.");
-    }
+    }
     await this.requireTool("git");
     await this.requireTool("bash");
     await this.requireTool("vp");
@@ -158,24 +158,24 @@ export default class WorkbenchBootstrap {
     const choice = await this.prompt.choose(
       `Workbench is not installed. This command will clone the repository and run build commands. It may take 1-2 minutes. Continue?${warning}`,
       ["Let's go!", "Cancel"],
-    );
-    if (choice !== "Let's go!") throw new DOMException("Setup cancelled.", "AbortError");
-    const defaultRoot = installed?.root ?? (process.platform === "win32"
-      ? path.join(this.environment.LOCALAPPDATA || path.join(this.home, "AppData", "Local"), "Programs", "inthedark", "wb")
-      : path.join(this.home, ".local", "lib", "inthedark", "wb"));
-    const root = path.resolve(await this.prompt.location("Install location", defaultRoot));
-    await fs.mkdir(path.dirname(this.registry), { recursive: true });
-    const lockPath = `${this.registry}.lock.sqlite3`;
-    const lock = new DatabaseSync(lockPath);
-    try {
-      lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
-    } catch (error) {
-      lock.close();
-      if (error.errcode === 5 || error.errcode === 6) {
-        throw new Error("Another Workbench installation is running. Let it finish before trying again.");
-      }
-      throw error;
-    }
+    );
+    if (choice !== "Let's go!") throw new DOMException("Setup cancelled.", "AbortError");
+    const defaultRoot = installed?.root ?? (process.platform === "win32"
+      ? path.join(this.environment.LOCALAPPDATA || path.join(this.home, "AppData", "Local"), "Programs", "inthedark", "wb")
+      : path.join(this.home, ".local", "lib", "inthedark", "wb"));
+    const root = path.resolve(await this.prompt.location("Install location", defaultRoot));
+    await fs.mkdir(path.dirname(this.registry), { recursive: true });
+    const lockPath = `${this.registry}.lock.sqlite3`;
+    const lock = new DatabaseSync(lockPath);
+    try {
+      lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
+    } catch (error) {
+      lock.close();
+      if (error.errcode === 5 || error.errcode === 6) {
+        throw new Error("Another Workbench installation is running. Let it finish before trying again.");
+      }
+      throw error;
+    }
     try {
       // Another invocation may have finished while this one was accepting input.
       const latest = await this.readInstallation();
@@ -192,49 +192,49 @@ export default class WorkbenchBootstrap {
       if (latest && latest.phase !== "ready") await this.discardIncomplete(latest);
       await this.requireEmptyDestination(root);
       let record = { version: 1, root, phase: "cloning" };
-      await this.writeInstallation(record);
-      await this.prompt.withHeader(async () => {
-        this.write(`Installing Workbench at ${root}\n`);
-        try {
-          // Install sandboxes substitute a local snapshot; ordinary installs clone the public repository.
-          const repository = this.environment.WORKBENCH_INSTALL_REPOSITORY || "https://github.com/ErisInTheDark/workbench.git";
-          await this.commands.run("git", ["clone", "--progress", "--branch", "main", "--single-branch", repository, root]);
-          if (!await this.checkoutExists(root)) throw new Error("Clone did not produce a Workbench checkout.");
-          record = { ...record, phase: "setup" };
-          await this.writeInstallation(record);
+      await this.writeInstallation(record);
+      await this.prompt.withHeader(async () => {
+        this.write(`Installing Workbench at ${root}\n`);
+        try {
+          // Install sandboxes substitute a local snapshot; ordinary installs clone the public repository.
+          const repository = this.environment.WORKBENCH_INSTALL_REPOSITORY || "https://github.com/ErisInTheDark/workbench.git";
+          await this.commands.run("git", ["clone", "--progress", "--branch", "main", "--single-branch", repository, root]);
+          if (!await this.checkoutExists(root)) throw new Error("Clone did not produce a Workbench checkout.");
+          record = { ...record, phase: "setup" };
+          await this.writeInstallation(record);
           await this.commands.run(process.execPath, [path.join(root, "installation", "install.mjs"), "--prepare"], { cwd: root });
-        } catch (error) {
-          try { await this.discardIncomplete(record); }
-          catch (cleanupError) {
-            throw new Error(`${error.message} Incomplete checkout was preserved at ${root}: ${cleanupError.message}`, { cause: error });
-          }
-          throw error;
-        }
-      });
-      record = { ...record, phase: "ready" };
-      await this.writeInstallation(record);
-    } finally {
-      // Closing the connection also releases the OS lock after normal completion;
-      // process death releases it without a stale PID or lock-file recovery path.
-      lock.close();
-    }
-    // Persist readiness before optional platform actions: missing native artifacts
-    // must not turn a usable source installation into an endless setup loop.
+        } catch (error) {
+          try { await this.discardIncomplete(record); }
+          catch (cleanupError) {
+            throw new Error(`${error.message} Incomplete checkout was preserved at ${root}: ${cleanupError.message}`, { cause: error });
+          }
+          throw error;
+        }
+      });
+      record = { ...record, phase: "ready" };
+      await this.writeInstallation(record);
+    } finally {
+      // Closing the connection also releases the OS lock after normal completion;
+      // process death releases it without a stale PID or lock-file recovery path.
+      lock.close();
+    }
+    // Persist readiness before optional platform actions: missing native artifacts
+    // must not turn a usable source installation into an endless setup loop.
     await this.commands.run(process.execPath, [path.join(root, "installation", "install.mjs"),
       args[0] === "connect" ? "--connect" : "--welcome"], { cwd: root, interactive: true });
   }
 
   async delegate(root, args) {
     return await this.commands.run(process.execPath, [path.join(root, "cli", "dispatch.mjs"), ...args], { interactive: true });
-  }
-
-  async requireEmptyDestination(root) {
-    try {
-      if ((await fs.readdir(root)).length) throw new Error(`Installation destination must be empty: ${root}. Existing files were preserved.`);
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    await fs.mkdir(path.dirname(root), { recursive: true });
-    await fs.access(path.dirname(root), constants.W_OK);
-  }
-}
+  }
+
+  async requireEmptyDestination(root) {
+    try {
+      if ((await fs.readdir(root)).length) throw new Error(`Installation destination must be empty: ${root}. Existing files were preserved.`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await fs.mkdir(path.dirname(root), { recursive: true });
+    await fs.access(path.dirname(root), constants.W_OK);
+  }
+}

package/WorkbenchBootstrapCommand.mjs

@@ -1,140 +1,140 @@
-/*
- * Exports:
+/*
+ * Exports:
  * - WorkbenchBootstrapCommand (default): owns bootstrap child commands, Windows executable lookup (including Git Bash), and failures.
- */
-import { spawn } from "node:child_process";
-import fs from "node:fs/promises";
-import path from "node:path";
-
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
 export default class WorkbenchBootstrapCommand {
-  constructor({ output = process.stdout, errorOutput = process.stderr, environment = process.env } = {}) {
-    this.output = output;
-    this.errorOutput = errorOutput;
-    this.environment = environment;
-  }
-
-  /** Environment variable by name; Windows names are case-insensitive, but copied env objects are not. */
-  variable(name) {
-    if (process.platform !== "win32") return this.environment[name];
-    const key = Object.keys(this.environment).find(candidate => candidate.toLowerCase() === name.toLowerCase());
-    return key === undefined ? undefined : this.environment[key];
-  }
-
-  async resolve(command) {
-    if (process.platform === "win32" && command === "bash") return [await this.resolveBash()];
-    if (process.platform !== "win32" || !["npm", "pnpm"].includes(command)) return [command];
-    const directories = [path.dirname(process.execPath), ...(this.variable("PATH") || "").split(path.delimiter)];
-    for (const directory of directories) {
-      if (!directory) continue;
-      const executable = path.join(directory, `${command}.exe`);
-      try {
-        await fs.access(executable);
-        return [executable];
-      } catch (error) {
-        if (error.code !== "ENOENT") throw error;
-      }
-      // npm/pnpm's Windows cmd wrappers cannot safely forward arbitrary paths.
-      // Invoke their installed Node entry instead of adding a command-shell layer.
-      const entry = command === "npm" ? "npm/bin/npm-cli.js" : "pnpm/bin/pnpm.cjs";
-      const script = path.join(directory, "node_modules", entry);
-      try {
-        await fs.access(script);
-        return [process.execPath, script];
-      } catch (error) {
-        if (error.code !== "ENOENT") throw error;
-      }
-    }
-    throw new Error(`Cannot locate ${command}'s executable or Node entry. Install ${command} and ensure it is on PATH.`);
-  }
-
-  /**
-   * Windows bash that can run Workbench. Git for Windows usually puts only git on PATH, and the
-   * bash.exe Windows does find is often WSL's launcher, which runs scripts inside Linux.
-   */
-  async resolveBash() {
-    const exists = async file => {
-      try { await fs.access(file); return true; }
-      catch (error) { if (error.code === "ENOENT") return false; throw error; }
-    };
-    const directories = (this.variable("PATH") || "").split(path.delimiter).filter(Boolean);
-    const local = this.variable("LOCALAPPDATA");
-    const launchers = [
-      path.join(this.variable("SystemRoot") || "C:\\Windows", "System32"),
-      ...(local ? [path.join(local, "Microsoft", "WindowsApps")] : []),
-    ].map(directory => path.resolve(directory).toLowerCase());
-    let sawLauncher = false;
-    for (const directory of directories) {
-      const bash = path.join(directory, "bash.exe");
-      if (!await exists(bash)) continue;
-      if (launchers.includes(path.resolve(directory).toLowerCase())) sawLauncher = true;
-      else return bash;
-    }
-    // git.exe lives in Git\cmd, Git\bin or Git\mingw64\bin; Git Bash is always Git\bin\bash.exe.
-    for (const directory of directories) {
-      if (!await exists(path.join(directory, "git.exe"))) continue;
-      const parent = path.dirname(directory);
-      const root = path.basename(parent).toLowerCase() === "mingw64" ? path.dirname(parent) : parent;
-      const bash = path.join(root, "bin", "bash.exe");
-      if (await exists(bash)) return bash;
-    }
-    for (const base of [this.variable("ProgramFiles"), local && path.join(local, "Programs")]) {
-      if (!base) continue;
-      const bash = path.join(base, "Git", "bin", "bash.exe");
-      if (await exists(bash)) return bash;
-    }
-    throw new Error(`Workbench needs Git Bash on Windows.${sawLauncher ? " The bash on PATH is WSL's, which cannot run Workbench." : ""} Install Git for Windows, then retry.`);
-  }
-
-  async run(command, args, { cwd, signal, onOutput, environment = {}, output = this.output, errorOutput = this.errorOutput, interactive = false } = {}) {
-    signal?.throwIfAborted();
-    const [executable, ...prefix] = await this.resolve(command);
-    signal?.throwIfAborted();
-    return await new Promise((resolve, reject) => {
-      const child = spawn(executable, [...prefix, ...args], {
-        cwd,
-        env: { ...this.environment, ...environment },
-        windowsHide: true,
-        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
-        signal,
-      });
-      let failure;
-      const relay = signal => { child.kill(signal); };
-      const interrupt = () => relay("SIGINT");
-      const terminate = () => relay("SIGTERM");
-      const hangup = () => relay("SIGHUP");
-      if (interactive) {
-        process.on("SIGINT", interrupt);
-        process.on("SIGTERM", terminate);
-        process.on("SIGHUP", hangup);
-      }
-      child.on("error", error => { failure = error; });
-      const forward = (stream, output) => {
-        stream.on("data", bytes => {
-          output.write(bytes);
-          if (onOutput) {
-            try { onOutput(bytes.toString()); }
-            catch (error) { failure = error; child.kill(); }
-          }
-        });
-      };
-      if (!interactive) {
-        forward(child.stdout, output);
-        forward(child.stderr, errorOutput);
-      }
-      child.once("close", (code, exitSignal) => {
-        if (interactive) {
-          process.off("SIGINT", interrupt);
-          process.off("SIGTERM", terminate);
-          process.off("SIGHUP", hangup);
-        }
-        if (failure?.code === "ENOENT") {
-          reject(Object.assign(new Error(`Cannot start ${command}: executable not found. Install it and make it available on PATH, then retry.`, { cause: failure }), {
-            code: "ENOENT",
-          }));
-        } else if (failure) reject(failure);
-        else if (code === 0) resolve();
-        else reject(Object.assign(new Error(`${command} failed with ${exitSignal ? `signal ${exitSignal}` : `status ${code ?? "unknown"}`}.`), { exitCode: code ?? 1 }));
-      });
-    });
-  }
-}
+  constructor({ output = process.stdout, errorOutput = process.stderr, environment = process.env } = {}) {
+    this.output = output;
+    this.errorOutput = errorOutput;
+    this.environment = environment;
+  }
+
+  /** Environment variable by name; Windows names are case-insensitive, but copied env objects are not. */
+  variable(name) {
+    if (process.platform !== "win32") return this.environment[name];
+    const key = Object.keys(this.environment).find(candidate => candidate.toLowerCase() === name.toLowerCase());
+    return key === undefined ? undefined : this.environment[key];
+  }
+
+  async resolve(command) {
+    if (process.platform === "win32" && command === "bash") return [await this.resolveBash()];
+    if (process.platform !== "win32" || !["npm", "pnpm"].includes(command)) return [command];
+    const directories = [path.dirname(process.execPath), ...(this.variable("PATH") || "").split(path.delimiter)];
+    for (const directory of directories) {
+      if (!directory) continue;
+      const executable = path.join(directory, `${command}.exe`);
+      try {
+        await fs.access(executable);
+        return [executable];
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      // npm/pnpm's Windows cmd wrappers cannot safely forward arbitrary paths.
+      // Invoke their installed Node entry instead of adding a command-shell layer.
+      const entry = command === "npm" ? "npm/bin/npm-cli.js" : "pnpm/bin/pnpm.cjs";
+      const script = path.join(directory, "node_modules", entry);
+      try {
+        await fs.access(script);
+        return [process.execPath, script];
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    throw new Error(`Cannot locate ${command}'s executable or Node entry. Install ${command} and ensure it is on PATH.`);
+  }
+
+  /**
+   * Windows bash that can run Workbench. Git for Windows usually puts only git on PATH, and the
+   * bash.exe Windows does find is often WSL's launcher, which runs scripts inside Linux.
+   */
+  async resolveBash() {
+    const exists = async file => {
+      try { await fs.access(file); return true; }
+      catch (error) { if (error.code === "ENOENT") return false; throw error; }
+    };
+    const directories = (this.variable("PATH") || "").split(path.delimiter).filter(Boolean);
+    const local = this.variable("LOCALAPPDATA");
+    const launchers = [
+      path.join(this.variable("SystemRoot") || "C:\\Windows", "System32"),
+      ...(local ? [path.join(local, "Microsoft", "WindowsApps")] : []),
+    ].map(directory => path.resolve(directory).toLowerCase());
+    let sawLauncher = false;
+    for (const directory of directories) {
+      const bash = path.join(directory, "bash.exe");
+      if (!await exists(bash)) continue;
+      if (launchers.includes(path.resolve(directory).toLowerCase())) sawLauncher = true;
+      else return bash;
+    }
+    // git.exe lives in Git\cmd, Git\bin or Git\mingw64\bin; Git Bash is always Git\bin\bash.exe.
+    for (const directory of directories) {
+      if (!await exists(path.join(directory, "git.exe"))) continue;
+      const parent = path.dirname(directory);
+      const root = path.basename(parent).toLowerCase() === "mingw64" ? path.dirname(parent) : parent;
+      const bash = path.join(root, "bin", "bash.exe");
+      if (await exists(bash)) return bash;
+    }
+    for (const base of [this.variable("ProgramFiles"), local && path.join(local, "Programs")]) {
+      if (!base) continue;
+      const bash = path.join(base, "Git", "bin", "bash.exe");
+      if (await exists(bash)) return bash;
+    }
+    throw new Error(`Workbench needs Git Bash on Windows.${sawLauncher ? " The bash on PATH is WSL's, which cannot run Workbench." : ""} Install Git for Windows, then retry.`);
+  }
+
+  async run(command, args, { cwd, signal, onOutput, environment = {}, output = this.output, errorOutput = this.errorOutput, interactive = false } = {}) {
+    signal?.throwIfAborted();
+    const [executable, ...prefix] = await this.resolve(command);
+    signal?.throwIfAborted();
+    return await new Promise((resolve, reject) => {
+      const child = spawn(executable, [...prefix, ...args], {
+        cwd,
+        env: { ...this.environment, ...environment },
+        windowsHide: true,
+        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+        signal,
+      });
+      let failure;
+      const relay = signal => { child.kill(signal); };
+      const interrupt = () => relay("SIGINT");
+      const terminate = () => relay("SIGTERM");
+      const hangup = () => relay("SIGHUP");
+      if (interactive) {
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", terminate);
+        process.on("SIGHUP", hangup);
+      }
+      child.on("error", error => { failure = error; });
+      const forward = (stream, output) => {
+        stream.on("data", bytes => {
+          output.write(bytes);
+          if (onOutput) {
+            try { onOutput(bytes.toString()); }
+            catch (error) { failure = error; child.kill(); }
+          }
+        });
+      };
+      if (!interactive) {
+        forward(child.stdout, output);
+        forward(child.stderr, errorOutput);
+      }
+      child.once("close", (code, exitSignal) => {
+        if (interactive) {
+          process.off("SIGINT", interrupt);
+          process.off("SIGTERM", terminate);
+          process.off("SIGHUP", hangup);
+        }
+        if (failure?.code === "ENOENT") {
+          reject(Object.assign(new Error(`Cannot start ${command}: executable not found. Install it and make it available on PATH, then retry.`, { cause: failure }), {
+            code: "ENOENT",
+          }));
+        } else if (failure) reject(failure);
+        else if (code === 0) resolve();
+        else reject(Object.assign(new Error(`${command} failed with ${exitSignal ? `signal ${exitSignal}` : `status ${code ?? "unknown"}`}.`), { exitCode: code ?? 1 }));
+      });
+    });
+  }
+}

package/WorkbenchInstallPrompt.mjs

@@ -0,0 +1,256 @@
+/*
+ * Exports:
+ * - WorkbenchInstallPrompt (default): owns dependency-free installer terminal interaction and the pinned cube header.
+ */
+import path from "node:path";
+import os from "node:os";
+import { emitKeypressEvents } from "node:readline";
+import { INSTALLER_CUBE_ROWS, installerCubeWidth, renderInstallerCube } from "./installer-cube.mjs";
+
+const WORDMARK = "w o r k b e n c h";
+const FRAME_INTERVAL_MS = 80;
+// Install log rows kept below a pinned header; shorter terminals skip pinning.
+const LOG_ROWS = 8;
+
+function scheduleFrames(tick) {
+  const timer = setInterval(tick, FRAME_INTERVAL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+export default class WorkbenchInstallPrompt {
+  constructor({
+    input = process.stdin,
+    output = process.stdout,
+    platform = process.platform,
+    cwd = process.cwd(),
+    home = os.homedir(),
+    schedule = scheduleFrames,
+    now = () => performance.now(),
+  } = {}) {
+    this.input = input;
+    this.output = output;
+    this.schedule = schedule;
+    this.now = now;
+    this.paths = platform === "win32" ? path.win32 : path.posix;
+    this.windows = platform === "win32";
+    this.cwd = cwd;
+    this.home = home;
+    this.active = false;
+  }
+
+  suffix(value) {
+    const name = this.paths.basename(value);
+    const comparable = this.windows ? name.toLowerCase() : name;
+    if (comparable === "wb" || comparable === "workbench") return "";
+    return `${value.endsWith(this.paths.sep) || (this.windows && value.endsWith("/")) ? "" : this.paths.sep}wb`;
+  }
+
+  destination(value) {
+    if (!value.trim()) throw new Error("Choose an installation directory.");
+    if (/[\u0000-\u001f\u007f]/u.test(value)) throw new Error("Installation paths cannot contain control characters.");
+    const expanded = value === "~" ? this.home
+      : value.startsWith("~/") || (this.windows && value.startsWith("~\\"))
+        ? this.paths.join(this.home, value.slice(2)) : value;
+    return this.paths.resolve(this.cwd, `${expanded}${this.suffix(expanded)}`);
+  }
+
+  location(label, initialValue) {
+    let characters = Array.from(initialValue);
+    let cursor = characters.length;
+    return this.interact(
+      () => {
+        const value = characters.join("");
+        const suffix = this.suffix(value);
+        // Keep a bounded one-line viewport so redraw never overwrites earlier setup output.
+        const available = Math.max(8, (this.output.columns || 80) - label.length - suffix.length - 4);
+        const start = Math.max(0, cursor - available + 1);
+        const visible = characters.slice(start, start + available).join("");
+        const prefix = `${label}: `;
+        this.output.write(`\r\u001b[2K${prefix}${visible}\u001b[2m${suffix}\u001b[22m`);
+        this.output.write(`\r\u001b[${prefix.length + characters.slice(start, cursor).join("").length + 1}G`);
+      },
+      (text, key, accept) => {
+        if (key.name === "return") {
+          accept(this.destination(characters.join("")));
+          return;
+        }
+        if (key.name === "left") cursor = Math.max(0, cursor - 1);
+        else if (key.name === "right") cursor = Math.min(characters.length, cursor + 1);
+        else if (key.name === "home" || (key.ctrl && key.name === "a")) cursor = 0;
+        else if (key.name === "end" || (key.ctrl && key.name === "e")) cursor = characters.length;
+        else if (key.name === "backspace" && cursor > 0) characters.splice(--cursor, 1);
+        else if (key.name === "delete") characters.splice(cursor, 1);
+        else if (text && !key.ctrl && !key.meta && !/[\u0000-\u001f\u007f]/u.test(text)) {
+          const added = Array.from(text);
+          characters.splice(cursor, 0, ...added);
+          cursor += added.length;
+        }
+      },
+    );
+  }
+
+  choose(label, choices) {
+    if (!choices.length) return Promise.reject(new Error("A setup choice needs options."));
+    let selected = 0;
+    let rendered = false;
+    return this.interact(
+      () => {
+        if (rendered && choices.length > 1) this.output.write(`\r\u001b[${choices.length - 1}A`);
+        this.output.write(choices.map((choice, index) =>
+          `\r\u001b[2K${index === selected ? `> \u001b[7m${choice}\u001b[27m` : `  ${choice}`}`,
+        ).join("\n"));
+        rendered = true;
+      },
+      (_text, key, accept) => {
+        if (key.name === "up") selected = (selected + choices.length - 1) % choices.length;
+        else if (key.name === "down" || key.name === "tab") selected = (selected + 1) % choices.length;
+        else if (key.name === "return") accept(choices[selected]);
+      },
+      label,
+      choices.length,
+    );
+  }
+
+  /** Cube height that fits above the wordmark, label and prompt without scrolling the screen; 0 for none. */
+  cubeRows(label, promptLines) {
+    const columns = this.output.columns || 80;
+    const rows = this.output.rows || 24;
+    const labelLines = label
+      ? label.split("\n").reduce((total, line) => total + Math.max(1, Math.ceil(line.length / columns)), 0)
+      : 0;
+    // Wordmark, blank line, label, prompt. Scrolling would misplace every home-anchored redraw.
+    let cube = Math.min(INSTALLER_CUBE_ROWS.max, rows - 2 - labelLines - promptLines);
+    while (cube >= INSTALLER_CUBE_ROWS.min && installerCubeWidth(cube) > columns) cube--;
+    return cube >= INSTALLER_CUBE_ROWS.min ? cube : 0;
+  }
+
+  /** Animated cube frames, an in-place redraw and the centred wordmark for a header of `cubeRows` (0 for wordmark only). */
+  header(cubeRows) {
+    const started = this.now();
+    const frame = () => renderInstallerCube((this.now() - started) / 1000, cubeRows).join("\r\n");
+    return {
+      frame,
+      // Save and restore the cursor around each frame so prompts and output below never move.
+      draw: () => this.output.write(`\u001b7\u001b[H${frame()}\u001b8`),
+      wordmark: cubeRows
+        ? WORDMARK.padStart(Math.floor((installerCubeWidth(cubeRows) + WORDMARK.length) / 2))
+        : WORDMARK,
+    };
+  }
+
+  /** Runs `task` with the animated header pinned above a scroll region holding its output. */
+  async withHeader(task) {
+    const cubeRows = this.output.isTTY && !this.active ? this.cubeRows("", LOG_ROWS) : 0;
+    if (!cubeRows) return await task();
+    const rows = this.output.rows || 24;
+    const top = cubeRows + 3;
+    const { frame, draw, wordmark } = this.header(cubeRows);
+    let pinned = true;
+    // Resetting the region homes the cursor; save/restore keeps it where the output left off.
+    const release = () => {
+      if (!pinned) return;
+      pinned = false;
+      this.output.write("\u001b7\u001b[r\u001b8");
+    };
+    // Default SIGINT exits without cleanup and would trap the shell inside the region.
+    const interrupt = () => {
+      release();
+      process.exit(130);
+    };
+    process.once("exit", release);
+    process.once("SIGINT", interrupt);
+    let stopAnimation = () => {};
+    try {
+      // Blank lines push earlier shell output into scrollback instead of erasing it.
+      this.output.write(`${"\r\n".repeat(rows)}\u001b[H${frame()}\r\n${wordmark}\r\n\u001b[${top};${rows}r\u001b[${top};1H`);
+      stopAnimation = this.schedule(() => { if (pinned) draw(); });
+      return await task();
+    } finally {
+      stopAnimation();
+      process.removeListener("exit", release);
+      process.removeListener("SIGINT", interrupt);
+      release();
+    }
+  }
+
+  interact(render, handle, label = "", promptLines = 1) {
+    if (!this.input.isTTY || !this.output.isTTY) {
+      return Promise.reject(new Error("Workbench setup needs an interactive terminal; no changes were accepted."));
+    }
+    if (this.active) return Promise.reject(new Error("Another setup prompt is active."));
+    this.active = true;
+    const wasRaw = this.input.isRaw;
+    // A fresh stdin is neither flowing nor paused; leaving it flowing would let this
+    // process keep reading the console and steal keys from later child prompts.
+    const wasFlowing = this.input.readableFlowing === true;
+    emitKeypressEvents(this.input);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let screenActive = false;
+      let stopAnimation = null;
+      const restoreScreen = () => {
+        if (!screenActive) return;
+        screenActive = false;
+        this.output.write("\u001b[0m\u001b[?1049l");
+      };
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        stopAnimation?.();
+        stopAnimation = null;
+        this.input.removeListener("keypress", onKey);
+        this.input.removeListener("end", onEnd);
+        this.input.removeListener("error", onError);
+        process.removeListener("exit", restoreScreen);
+        try {
+          this.input.setRawMode(Boolean(wasRaw));
+          if (!wasFlowing) this.input.pause();
+        } catch (cleanupError) {
+          error ??= cleanupError;
+        }
+        try { restoreScreen(); }
+        catch (cleanupError) { error ??= cleanupError; }
+        this.active = false;
+        if (error) reject(error);
+        else resolve(value);
+      };
+      const onEnd = () => finish(new DOMException("Setup cancelled.", "AbortError"));
+      const onError = (error) => finish(error);
+      const onKey = (text, key = {}) => {
+        if ((key.ctrl && (key.name === "c" || key.name === "d")) || key.name === "escape") {
+          onEnd();
+          return;
+        }
+        try {
+          handle(text, key, (value) => finish(null, value));
+          if (!settled) render();
+        } catch (error) {
+          finish(error);
+        }
+      };
+      this.input.on("keypress", onKey);
+      this.input.once("end", onEnd);
+      this.input.once("error", onError);
+      try {
+        this.input.setRawMode(true);
+        this.input.resume();
+        screenActive = true;
+        process.once("exit", restoreScreen);
+        const cubeRows = this.cubeRows(label, promptLines);
+        const { frame, draw, wordmark } = this.header(cubeRows);
+        this.output.write(`\u001b[?1049h\u001b[2J\u001b[H${cubeRows ? `${frame()}\r\n` : ""}${wordmark}\r\n\r\n${label ? `${label}\r\n` : ""}`);
+        render();
+        if (cubeRows) {
+          stopAnimation = this.schedule(() => {
+            if (settled) return;
+            try { draw(); }
+            catch (error) { finish(error); }
+          });
+        }
+      } catch (error) {
+        finish(error);
+      }
+    });
+  }
+}

package/installer-cube.mjs

@@ -0,0 +1,113 @@
+/*
+ * Exports:
+ * - INSTALLER_CUBE_ROWS: largest and smallest cube heights worth drawing, in terminal rows.
+ * - installerCubeWidth: terminal columns a cube frame of the given height occupies.
+ * - renderInstallerCube: raycast one antialiased ASCII frame of the spinning installer cube.
+ */
+
+export const INSTALLER_CUBE_ROWS = Object.freeze({ max: 21, min: 11 });
+
+// Terminal cells are roughly twice as tall as they are wide.
+const CELL_ASPECT = 2.05;
+const RAMP = " .:-=+*#%@";
+const SAMPLES = 4;
+const TILT = 0.35;
+const SPIN = 0.8;
+const START = 0.35;
+const CAMERA = 5.2;
+const FOCAL = 2.9;
+const BORDER = 0.1;
+const STROKE = 0.09;
+const DOT = 0.12;
+const TOP_FILL = 0.4;
+
+// Face glyphs live in face space: u to the right and v up when the face is viewed from outside.
+const GLYPHS = {
+  check: { strokes: [[[-0.45, 0], [-0.12, -0.38], [0.48, 0.42]]], dots: [] },
+  x: { strokes: [[[-0.42, -0.42], [0.42, 0.42]], [[-0.42, 0.42], [0.42, -0.42]]], dots: [] },
+  question: {
+    strokes: [[[-0.32, 0.22], [-0.22, 0.42], [0, 0.5], [0.22, 0.42], [0.32, 0.22], [0.22, 0.06], [0, -0.04], [0, -0.18]]],
+    dots: [[0, -0.42]],
+  },
+  dots: { strokes: [], dots: [[-0.42, 0], [0, 0], [0.42, 0]] },
+};
+
+// Indexed by axis then sign: [x-, x+], [y-, y+], [z-, z+]. Each basis satisfies u x v = normal.
+const FACES = [
+  [{ u: [0, 0, 1], v: [0, 1, 0], glyph: GLYPHS.dots }, { u: [0, 0, -1], v: [0, 1, 0], glyph: GLYPHS.question }],
+  [{ u: [1, 0, 0], v: [0, 0, 1], glyph: null }, { u: [1, 0, 0], v: [0, 0, -1], glyph: null, fill: TOP_FILL }],
+  [{ u: [-1, 0, 0], v: [0, 1, 0], glyph: GLYPHS.x }, { u: [1, 0, 0], v: [0, 1, 0], glyph: GLYPHS.check }],
+];
+
+export function installerCubeWidth(rows) {
+  return Math.round(rows * 2.2);
+}
+
+function segmentDistance(px, py, [ax, ay], [bx, by]) {
+  const dx = bx - ax, dy = by - ay;
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)));
+  return Math.hypot(px - ax - t * dx, py - ay - t * dy);
+}
+
+function glyphCovers(glyph, u, v) {
+  for (const stroke of glyph.strokes) {
+    for (let index = 1; index < stroke.length; index++) {
+      if (segmentDistance(u, v, stroke[index - 1], stroke[index]) < STROKE) return true;
+    }
+  }
+  return glyph.dots.some(([x, y]) => Math.hypot(u - x, v - y) < DOT);
+}
+
+/** Brightness 0..1 where a camera ray through (px, py) meets the cube, given world-to-object rotation. */
+function shade(toObject, origin, px, py) {
+  const direction = toObject(px / FOCAL, py / FOCAL, -1);
+  let near = -Infinity, far = Infinity, axis = -1, side = 0;
+  for (let index = 0; index < 3; index++) {
+    let enter = (-1 - origin[index]) / direction[index];
+    let leave = (1 - origin[index]) / direction[index];
+    let entered = 0;
+    if (enter > leave) { [enter, leave] = [leave, enter]; entered = 1; }
+    if (enter > near) { near = enter; axis = index; side = entered; }
+    if (leave < far) far = leave;
+  }
+  if (near > far || far < 0) return 0;
+  const face = FACES[axis][side];
+  const x = origin[0] + direction[0] * near, y = origin[1] + direction[1] * near, z = origin[2] + direction[2] * near;
+  const u = x * face.u[0] + y * face.u[1] + z * face.u[2];
+  const v = x * face.v[0] + y * face.v[1] + z * face.v[2];
+  if (1 - Math.max(Math.abs(u), Math.abs(v)) < BORDER) return 1;
+  if (face.fill) return face.fill;
+  return face.glyph && glyphCovers(face.glyph, u, v) ? 0.95 : 0;
+}
+
+/** One frame: exactly `rows` strings of exactly installerCubeWidth(rows) printable ASCII characters. */
+export function renderInstallerCube(seconds, rows = INSTALLER_CUBE_ROWS.max) {
+  const width = installerCubeWidth(rows);
+  const spin = START + seconds * SPIN;
+  const cs = Math.cos(spin), ss = Math.sin(spin), ct = Math.cos(TILT), st = Math.sin(TILT);
+  // Undo the tilt about X, then the spin about Y.
+  const toObject = (x, y, z) => {
+    const ty = y * ct + z * st, tz = -y * st + z * ct;
+    return [x * cs - tz * ss, ty, x * ss + tz * cs];
+  };
+  const origin = toObject(0, 0, CAMERA);
+  const lines = [];
+  for (let row = 0; row < rows; row++) {
+    let line = "";
+    for (let column = 0; column < width; column++) {
+      let coverage = 0;
+      for (let j = 0; j < SAMPLES; j++) {
+        // Nudge the view up slightly so the cube sits centred rather than low in its box.
+        const py = -(row + (j + 0.5) / SAMPLES - rows / 2) / (rows / 2) - 0.12;
+        for (let i = 0; i < SAMPLES; i++) {
+          const px = (column + (i + 0.5) / SAMPLES - width / 2) / (rows * CELL_ASPECT / 2);
+          coverage += shade(toObject, origin, px, py);
+        }
+      }
+      const level = Math.pow(coverage / (SAMPLES * SAMPLES), 0.75);
+      line += RAMP[Math.min(RAMP.length - 1, Math.round(level * (RAMP.length - 1)))];
+    }
+    lines.push(line);
+  }
+  return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inthedark/wb",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,11 +26,13 @@
     "wb",
     "WorkbenchBootstrap.mjs",
     "WorkbenchBootstrapCommand.mjs",
-    "WorkbenchBootstrapPrompt.mjs",
+    "WorkbenchInstallPrompt.mjs",
+    "installer-cube.mjs",
     "index.mjs",
     "index.d.ts",
     "store-definitions.mjs",
     "StoreCommandRunner.mjs",
+    "wb.schema.json",
     "README.md"
   ],
   "dependencies": {

package/wb.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Editor schema reference; ignored by Workbench.",
+      "type": "string"
+    },
+    "vis": {
+      "type": "object",
+      "properties": {
+        "css": {
+          "description": "Compiles CSS for .html and .svg vis files containing <link rel=\"workbench-css\">.",
+          "type": "object",
+          "properties": {
+            "command": {
+              "minItems": 1,
+              "maxItems": 64,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 4000
+              },
+              "description": "Argument vector run from the project root, inside the calling thread's sandbox. Its stdout is the result. {file}, {root} and {input} are substituted."
+            },
+            "input": {
+              "description": "Written to a temporary file named by {input}, for tools that read an entry file rather than arguments.",
+              "type": "string",
+              "maxLength": 16000
+            }
+          },
+          "required": [
+            "command"
+          ],
+          "additionalProperties": false
+        },
+        "build": {
+          "description": "Builds .tsx and .jsx vis files; prints JSON { document, inputs }.",
+          "type": "object",
+          "properties": {
+            "command": {
+              "minItems": 1,
+              "maxItems": 64,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 4000
+              },
+              "description": "Argument vector run from the project root, inside the calling thread's sandbox. Its stdout is the result. {file}, {root} and {input} are substituted."
+            },
+            "input": {
+              "description": "Written to a temporary file named by {input}, for tools that read an entry file rather than arguments.",
+              "type": "string",
+              "maxLength": 16000
+            }
+          },
+          "required": [
+            "command"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false,
+      "description": "Live visual drafts agents show with wb vis start."
+    }
+  },
+  "additionalProperties": false,
+  "description": "Project-owned Workbench settings, read from .wb.json at the project root."
+}

package/WorkbenchBootstrapPrompt.mjs

@@ -1,71 +0,0 @@
-/*
- * Exports:
- * - WorkbenchBootstrapPrompt (default): owns the stable dependency-free consent and destination prompts used before cloning.
- */
-import os from "node:os";
-import path from "node:path";
-import { createInterface } from "node:readline/promises";
-
-export default class WorkbenchBootstrapPrompt {
-  constructor({
-    input = process.stdin,
-    output = process.stdout,
-    platform = process.platform,
-    cwd = process.cwd(),
-    home = os.homedir(),
-    ask,
-  } = {}) {
-    this.input = input;
-    this.output = output;
-    this.paths = platform === "win32" ? path.win32 : path.posix;
-    this.windows = platform === "win32";
-    this.cwd = cwd;
-    this.home = home;
-    this.ask = ask ?? (question => this.question(question));
-  }
-
-  suffix(value) {
-    const name = this.paths.basename(value);
-    const comparable = this.windows ? name.toLowerCase() : name;
-    if (comparable === "wb" || comparable === "workbench") return "";
-    return `${value.endsWith(this.paths.sep) || (this.windows && value.endsWith("/")) ? "" : this.paths.sep}wb`;
-  }
-
-  destination(value) {
-    if (!value.trim()) throw new Error("Choose an installation directory.");
-    if (/[\u0000-\u001f\u007f]/u.test(value)) throw new Error("Installation paths cannot contain control characters.");
-    const expanded = value === "~" ? this.home
-      : value.startsWith("~/") || (this.windows && value.startsWith("~\\"))
-        ? this.paths.join(this.home, value.slice(2)) : value;
-    return this.paths.resolve(this.cwd, `${expanded}${this.suffix(expanded)}`);
-  }
-
-  async choose(label, choices) {
-    if (!choices.length) throw new Error("A setup choice needs options.");
-    const options = choices.map((choice, index) => `${index + 1}) ${choice}`).join("  ");
-    while (true) {
-      const answer = (await this.ask(`${label}\n${options}\nChoose [1]: `)).trim();
-      const selected = answer === "" ? 0 : Number(answer) - 1;
-      if (Number.isInteger(selected) && selected >= 0 && selected < choices.length) return choices[selected];
-      this.output.write(`Choose a number from 1 to ${choices.length}.\n`);
-    }
-  }
-
-  async location(label, initialValue) {
-    const answer = await this.ask(`${label} [${initialValue}]: `);
-    return this.destination(answer.trim() || initialValue);
-  }
-
-  withHeader(task) {
-    return task();
-  }
-
-  async question(text) {
-    if (!this.input.isTTY || !this.output.isTTY) {
-      throw new Error("Workbench setup needs an interactive terminal; no changes were accepted.");
-    }
-    const terminal = createInterface({ input: this.input, output: this.output });
-    try { return await terminal.question(text); }
-    finally { terminal.close(); }
-  }
-}