babavoss 0.0.1 → 0.0.2

package/src/exec/host.ts

@@ -0,0 +1,177 @@
+// The kernel owns records until OS cleanup finishes, including after the
+// runtime stops listening. References are scoped to one system and generation.
+import { createServer, type Socket } from "node:net";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ServiceError, type Who, type ExecEvent } from "../kernel/context.ts";
+import { roleCommand } from "../runtime/connect.ts";
+import { receive, send, CHUNK, FRAME, type FromRunner, type Command } from "./wire.ts";
+
+const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+const xml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function alive(group: number) { try { process.kill(-group, 0); return true; } catch (e) { if ((e as NodeJS.ErrnoException).code === "ESRCH") return false; if ((e as NodeJS.ErrnoException).code === "EPERM") return true; throw e; } }
+async function launchctl(args: string[]) {
+  const p = Bun.spawn(["/bin/launchctl", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: 10_000 });
+  const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
+  return { code, text: out + err };
+}
+interface Execution { who: Who; signal: AbortSignal; write(input: string | null, signal: AbortSignal): Promise<void> }
+export class ExecutionHost {
+  private records = new Map<string, Execution>();
+  async write(who: Who, ref: string, input: string | null, signal: AbortSignal): Promise<void> {
+    const r = this.records.get(ref);
+    if (!r || r.signal.aborted) throw new ServiceError("notfound", "execution is no longer running");
+    if (r.who.project !== who.project || r.who.system !== who.system || r.who.generation !== who.generation) throw new ServiceError("denied", "execution belongs to another system or generation");
+    if (input !== null && Buffer.byteLength(input) > CHUNK) throw new ServiceError("args", `stdin write exceeds ${CHUNK} bytes`);
+    await r.write(input, signal);
+  }
+  async *stream(who: Who, command: Command, signal: AbortSignal): AsyncGenerator<ExecEvent> {
+    if (signal.aborted) throw new ServiceError("failed", "execution cancelled");
+    if (process.platform !== "darwin") throw new ServiceError("denied", "supervised execution currently requires macOS launchd");
+    if (Buffer.byteLength(JSON.stringify({ type: "start", command: { ...command, input: undefined } })) + 1 > FRAME) throw new ServiceError("args", "execution arguments and environment exceed 128 KiB");
+    const dir = await mkdtemp("/tmp/voss-exec-");
+    const ref = crypto.randomUUID();
+    const token = crypto.randomUUID();
+    const label = `org.babavoss.exec.${ref}`;
+    const domain = `gui/${process.getuid!()}`;
+    const target = `${domain}/${label}`;
+    let socket: Socket | undefined, runner = 0, closed = false, bootstrapped = false;
+    let error: Error | undefined;
+    let wake: (() => void) | undefined;
+    let exit: Extract<FromRunner, { type: "exit" }> | undefined;
+    const queue: ExecEvent[] = [];
+    let outputPending = false;
+    let nextWrite = 0;
+    let initialized = false;
+    const writes = new Map<number, { resolve(): void; reject(e: Error): void }>();
+    const fail = (e: Error) => { error ??= e; wake?.(); };
+    const stop = () => { try { if (socket && !socket.destroyed) send(socket, { type: "stop" }); } catch {} wake?.(); };
+    signal.addEventListener("abort", stop, { once: true });
+    const writeRaw = (input: string | null) => new Promise<void>((resolve, reject) => {
+      const id = ++nextWrite;
+      writes.set(id, { resolve, reject });
+      try { send(socket!, { type: "write", id, input }); }
+      catch (e) { writes.delete(id); reject(e); }
+    });
+    const server = createServer((s) => {
+      if (socket) { s.destroy(); return; }
+      let authenticated = false;
+      receive<FromRunner>(s, (m) => {
+        if (!authenticated) {
+          if (m.type !== "hello" || m.token !== token || !Number.isSafeInteger(m.pid) || m.pid < 2) { s.destroy(); return; }
+          authenticated = true; socket = s; runner = m.pid;
+          if (signal.aborted) stop(); else send(s, { type: "start", command: { ...command, input: undefined } });
+          return;
+        }
+        if (m.type === "started") {
+          initialized = command.interactive && !command.input;
+          queue.push({ type: "started", process: ref, pid: m.pid });
+          // Pump input concurrently with output. Each write is acknowledged;
+          // even large initial input never makes an oversized control frame.
+          void (async () => {
+            const input = command.input ?? "";
+            for (let i = 0; i < input.length;) {
+              let end = Math.min(i + 4096, input.length);
+              const last = input.charCodeAt(end - 1);
+              if (end < input.length && last >= 0xd800 && last <= 0xdbff) end--;
+              await writeRaw(input.slice(i, end)); i = end;
+            }
+            if (!command.interactive) await writeRaw(null);
+            initialized = true;
+          })().catch(() => {
+            // Programs may close stdin without consuming all input (e.g.
+            // `true`). Their exit status remains authoritative. A lost runner
+            // still fails the stream independently if no exit was received.
+            initialized = true;
+          });
+        }
+        else if (m.type === "output") {
+          if (outputPending || m.data.length > CHUNK * 2) { fail(new Error("execution exceeded output credit")); stop(); return; }
+          outputPending = true;
+          queue.push({ type: m.stream, data: new Uint8Array(Buffer.from(m.data, "base64")) });
+        } else if (m.type === "exit") exit = m;
+        else if (m.type === "error") fail(new Error(m.message));
+        else if (m.type === "written") { const w = writes.get(m.id); writes.delete(m.id); if (m.error) w?.reject(new Error(m.error)); else w?.resolve(); }
+        wake?.();
+      }, (e) => {
+        // Once the exit is in hand the runner may close the socket while the
+        // host is still streaming initial input to it (a program like `true`
+        // exits at once): that EPIPE is not the execution's failure.
+        if (exit) { closed = true; wake?.(); } else fail(e);
+      });
+      s.on("close", () => { if (!authenticated) return; closed = true; for (const w of writes.values()) w.reject(new Error("execution closed")); writes.clear(); wake?.(); });
+    });
+    let cleanupError: Error | undefined;
+    try {
+      await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(join(dir, "s"), resolve); });
+      const args = [...roleCommand("--exec"), join(dir, "s"), token];
+      const plist = `<?xml version="1.0"?><plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${args.map((a) => `<string>${xml(a)}</string>`).join("")}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><false/><key>AbandonProcessGroup</key><false/><key>ExitTimeOut</key><integer>1</integer></dict></plist>`;
+      await writeFile(join(dir, "job.plist"), plist, { mode: 0o600 });
+      if (signal.aborted) throw new Error("execution cancelled");
+      const started = await launchctl(["bootstrap", domain, join(dir, "job.plist")]);
+      if (started.code !== 0) throw new Error(`launchd could not supervise execution: ${started.text.trim()}`);
+      bootstrapped = true;
+      const startup = setTimeout(() => { fail(new Error("execution runner did not connect")); stop(); }, 10_000);
+      const write = async (input: string | null, caller: AbortSignal) => {
+        if (!command.interactive) throw new ServiceError("args", "execution stdin is not interactive");
+        if (caller.aborted || signal.aborted || !socket || closed || exit) throw new ServiceError("failed", "stdin write cancelled or execution closed");
+        // One write in flight: systems serialize commands; no hidden unbounded queue.
+        if (!initialized || writes.size) throw new ServiceError("failed", "another stdin write is pending");
+        const id = ++nextWrite;
+        await new Promise<void>((resolve, reject) => {
+          const abort = () => { reject(new Error("stdin write cancelled; delivery may have occurred")); };
+          caller.addEventListener("abort", abort, { once: true });
+          writes.set(id, { resolve: () => { caller.removeEventListener("abort", abort); resolve(); }, reject: (e) => { caller.removeEventListener("abort", abort); reject(e); } });
+          send(socket!, { type: "write", id, input });
+        });
+      };
+      this.records.set(ref, { who, signal, write });
+      try {
+        for (;;) {
+          if (signal.aborted) throw new Error("execution cancelled");
+          if (error) throw error;
+          const event = queue.shift();
+          if (event) {
+            if (event.type === "started") clearTimeout(startup);
+            yield event;
+            if (event.type === "stdout" || event.type === "stderr") { outputPending = false; if (socket && !socket.destroyed) send(socket, { type: "ack" }); }
+            continue;
+          }
+          if (closed) { if (!exit) throw new Error("execution runner exited unexpectedly"); break; }
+          await new Promise<void>((r) => { wake = r; }); wake = undefined;
+        }
+      } finally { clearTimeout(startup); }
+    } finally {
+      this.records.delete(ref);
+      signal.removeEventListener("abort", stop);
+      stop();
+      // The runner/sentinel terminate their own current group. The host only
+      // observes group disappearance; it never signals a saved numeric PID.
+      if (runner) {
+        const until = Date.now() + 15_000;
+        while (alive(runner) && Date.now() < until) await delay(20);
+        if (alive(runner)) cleanupError = new Error(`execution group ${runner} did not stop`);
+      }
+      if (bootstrapped && !cleanupError) {
+        // Boot the job out and confirm it is gone (`print` answers 113 for an
+        // unknown service). launchd can be slow to tear a job down, and a
+        // `bootout` the helper's timeout cut short reports nothing, so the
+        // confirmation is polled for a bounded time, with the bootout retried.
+        let out = await launchctl(["bootout", target]);
+        const until = Date.now() + 15_000;
+        for (;;) {
+          const check = await launchctl(["print", target]);
+          if (check.code === 113) break;
+          if (Date.now() > until) { cleanupError = new Error(`could not confirm launchd deregistration: ${out.text.trim() || `bootout exited ${out.code}, print exited ${check.code}`}`); break; }
+          await delay(250);
+          out = await launchctl(["bootout", target]);
+        }
+      }
+      socket?.destroy();
+      await new Promise<void>((r) => server.close(() => r()));
+      if (!cleanupError) await rm(dir, { recursive: true, force: true });
+      if (cleanupError) { cleanupError.name = "ExecutionCleanupError"; throw cleanupError; }
+    }
+    if (exit) yield { type: "exit", code: exit.code, signal: exit.signal };
+  }
+}

package/src/exec/main.ts

@@ -0,0 +1,98 @@
+// Internal launchd job. Runner and sentinel monitor one another in the
+// workload group; either can kill its own group without saved PID signalling.
+import { connect } from "node:net";
+import { roleCommand } from "../runtime/connect.ts";
+import { CHUNK, receive, send, type ToRunner, type Command } from "./wire.ts";
+
+const [path, token] = process.argv.slice(3);
+if (!path || !token) process.exit(2);
+const socket = connect(path);
+let child: ReturnType<typeof Bun.spawn<"pipe", "pipe", "pipe">> | null = null;
+let stopping = false;
+let credit: (() => void) | null = null;
+let outputTail = Promise.resolve();
+let inputTail = Promise.resolve();
+const startup = setTimeout(() => stop(), 10_000);
+let deadline: ReturnType<typeof setTimeout> | undefined;
+// Stay alive through graceful group termination to relay the outcome.
+process.on("SIGTERM", () => {});
+process.on("SIGINT", () => stop());
+function terminateGroup() { try { process.kill(0, "SIGTERM"); } catch {} }
+function stop() {
+  if (stopping) return;
+  stopping = true;
+  clearTimeout(startup); clearTimeout(deadline);
+  terminateGroup();
+  credit?.(); credit = null;
+  setTimeout(force, 250);
+}
+function force(): never {
+  // Includes runner, sentinel and workload, selected by current membership.
+  try { process.kill(0, "SIGKILL"); } catch {}
+  process.exit(1);
+}
+function fail(e: unknown) {
+  try { send(socket, { type: "error", message: e instanceof Error ? e.message : String(e) }); } catch {}
+  stop();
+}
+socket.on("connect", () => send(socket, { type: "hello", token, pid: process.pid }));
+socket.on("close", stop);
+receive<ToRunner>(socket, (m) => {
+  if (m.type === "ack") { credit?.(); credit = null; }
+  else if (m.type === "stop") stop();
+  else if (m.type === "start") {
+    if (child || stopping) return fail(new Error("execution already started or stopped"));
+    void run(m.command).catch(fail);
+  } else if (m.type === "write") {
+    inputTail = inputTail.then(async () => {
+      try {
+        if (!child || stopping) throw new Error("execution is closed");
+        if (m.input === null) await child.stdin.end();
+        else { child.stdin.write(m.input); await child.stdin.flush(); }
+        send(socket, { type: "written", id: m.id });
+      } catch (e) { send(socket, { type: "written", id: m.id, error: String(e) }); }
+    }).catch(fail);
+  }
+}, fail);
+async function output(stream: "stdout" | "stderr", bytes: ReadableStream<Uint8Array>) {
+  for await (const chunk of bytes) {
+    for (let i = 0; i < chunk.length && !stopping; i += CHUNK) {
+      const data = Buffer.from(chunk.subarray(i, i + CHUNK)).toString("base64");
+      const next = outputTail.then(async () => {
+        if (stopping) return;
+        await new Promise<void>((resolve) => { credit = resolve; send(socket, { type: "output", stream, data }); });
+      });
+      outputTail = next;
+      await next;
+    }
+    if (stopping) break;
+  }
+}
+async function run(c: Command) {
+  const sentinel = Bun.spawn(roleCommand("--exec-watch"), { stdin: "pipe", stdout: "pipe", stderr: "ignore", env: {} });
+  // Do not launch user code until the sentinel ignores group TERM and is
+  // watching the pipe. If it dies at any point, the runner cleans the group.
+  void sentinel.exited.then(stop);
+  const reader = sentinel.stdout.getReader();
+  const ready = await reader.read();
+  if (ready.done || new TextDecoder().decode(ready.value) !== "ready\n" || stopping) throw new Error("execution sentinel did not become ready");
+  reader.releaseLock();
+  child = Bun.spawn([c.program, ...c.args], { cwd: c.cwd, env: c.env, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  clearTimeout(startup);
+  send(socket, { type: "started", pid: child.pid });
+  if (c.timeout !== null) deadline = setTimeout(() => fail(new Error(`execution timed out after ${c.timeout} ms`)), c.timeout);
+  const reads = Promise.all([output("stdout", child.stdout), output("stderr", child.stderr)]);
+  void reads.catch(fail);
+  // Initial input and EOF arrive on the acknowledged stdin channel too.
+  const code = await child.exited;
+  clearTimeout(deadline);
+  // A foreground command owns its descendants; they may not keep pipes or
+  // locks after it exits. Give them a bounded chance to close cleanly.
+  terminateGroup();
+  const drain = setTimeout(() => fail(new Error("execution output did not drain after program exit")), 5000);
+  await reads;
+  clearTimeout(drain);
+  if (stopping) return;
+  send(socket, { type: "exit", code, signal: child.signalCode ?? null });
+  socket.end(force);
+}

package/src/exec/watch.ts

@@ -0,0 +1,7 @@
+// Same-group sentinel. The runner alone holds this pipe's write end. Signal
+// our CURRENT group on EOF, never a persisted PID that could have been reused.
+process.on("SIGTERM", () => {});
+process.on("SIGINT", () => {});
+process.stdout.write("ready\n");
+await Bun.stdin.text();
+process.kill(0, "SIGKILL");

package/src/exec/wire.ts

@@ -0,0 +1,29 @@
+// A bounded, acknowledged channel. One output chunk may be outstanding;
+// control (cancel, stdin, exit) never waits behind output credit.
+import type { Socket } from "node:net";
+export const CHUNK = 16 * 1024;
+export const FRAME = 128 * 1024;
+export interface Command { program: string; args: string[]; cwd: string; env: Record<string, string>; input?: string; interactive: boolean; timeout: number | null }
+export type ToRunner = { type: "start"; command: Command } | { type: "ack" } | { type: "stop" } | { type: "write"; id: number; input: string | null };
+export type FromRunner = { type: "hello"; token: string; pid: number } | { type: "started"; pid: number } | { type: "output"; stream: "stdout" | "stderr"; data: string } | { type: "written"; id: number; error?: string } | { type: "exit"; code: number; signal: string | null } | { type: "error"; message: string };
+export function receive<T>(socket: Socket, onMessage: (m: T) => void, onError: (e: Error) => void): void {
+  let buffer = "";
+  socket.setEncoding("utf8");
+  socket.on("data", (chunk: string) => {
+    buffer += chunk;
+    if (buffer.length > FRAME && !buffer.includes("\n")) { onError(new Error("execution frame exceeds limit")); return; }
+    for (;;) {
+      const end = buffer.indexOf("\n");
+      if (end < 0) break;
+      if (end > FRAME) { onError(new Error("execution frame exceeds limit")); return; }
+      const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+      try { onMessage(JSON.parse(line) as T); } catch (e) { onError(e instanceof Error ? e : new Error(String(e))); return; }
+    }
+  });
+  socket.on("error", onError);
+}
+export function send(socket: Socket, m: ToRunner | FromRunner): void {
+  const line = JSON.stringify(m) + "\n";
+  if (Buffer.byteLength(line) > FRAME) throw new Error("execution frame exceeds limit");
+  socket.write(line);
+}

package/src/generated/build.ts

@@ -0,0 +1,4 @@
+// The commit and the moment a package was built from, stamped by the pack
+// of a release (tools/release/pack.ts) and restored after it. From a
+// checkout both are empty: the tree is the build.
+export const build = {"sha":"5a0a15d","at":"2026-10-08T18:17:26.925Z"};

package/src/gui/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css" {}

package/src/gui/gui.tsx

@@ -0,0 +1,245 @@
+// voss's GUI: voss's shell at every level. At the root, over page state: the
+// babas and the New baba wizard. At /NAME/ over the baba,
+// its apps and voss's own, the Maker, the state, the contract, the
+// promptware and the settings, as windows. One bundle, one React, served by the
+// kernel's server child.
+import "./theme.css";
+import { Component, StrictMode, useEffect, useMemo, useState, type ComponentType, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { ScopeProvider, apiHeaders, formatFailure, Maker, Desktop, useResource, useBaba, type AppProps, type ViewFailure } from "babavoss/web";
+import { isApps, type Interface } from "../web/core.tsx";
+import { desktop, themes, type DesktopSystem } from "../desktop/index.ts";
+import type { AppSpec } from "../ecs/baba.ts";
+import type { Described } from "../baba/node.ts";
+import { Inspector } from "./inspector.tsx";
+import { Runner } from "./runner.tsx";
+import { Promptware } from "./promptware.tsx";
+import { Button } from "../web/ui.tsx";
+import { Root } from "./levels.tsx";
+import type { Voss } from "../server/messages.ts";
+import { tellApart } from "../kernel/names.ts";
+
+const scope = document.querySelector('meta[name="voss-scope"]')?.getAttribute("content") ?? "";
+
+
+async function describe(name: string, since: number, signal?: AbortSignal): Promise<Described> {
+  const r = await fetch(`/api/describe/${encodeURIComponent(name)}${since ? `?since=${since}` : ""}`, { signal, headers: apiHeaders() });
+  const d = await r.json() as Described & { error?: { message: string } };
+  if (!r.ok) throw new Error(d.error?.message ?? r.statusText);
+  return d;
+}
+
+/** Describes the baba, then keeps asking "since the generation I have": the answer comes when it changes. */
+function useDescribed(name: string): { d: Described | null; failed: string | null } {
+  const [d, setD] = useState<Described | null>(null);
+  const [failed, setFailed] = useState<string | null>(null);
+  useEffect(() => {
+    const ctl = new AbortController();
+    (async () => {
+      let since = 0;
+      while (!ctl.signal.aborted) {
+        try {
+          const next = await describe(name, since, ctl.signal);
+          since = next.gen;
+          setD(next);
+          setFailed(null);
+        } catch (e) {
+          if (ctl.signal.aborted) return;
+          setFailed(e instanceof Error ? e.message : String(e));
+          since = 0;
+          await new Promise((r) => setTimeout(r, 2000));
+        }
+      }
+    })();
+    return () => ctl.abort();
+  }, [name]);
+  return { d, failed };
+}
+
+// ---- voss itself -----------------------------------------------------------
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * A newer voss installed: this one is stale and holds every change on disk
+ * until the restart. The bar says so on every page and offers the restart;
+ * after it, the page comes back on the new daemon, whose token is new too.
+ */
+function Stale() {
+  const [b, setB] = useState<Voss | null>(null);
+  const [restarting, setRestarting] = useState(false);
+  useEffect(() => {
+    let live = true;
+    const tick = async () => {
+      try { const r = await fetch("/api/voss", { headers: apiHeaders() }); if (r.ok) { const j = await r.json() as Voss; if (live) setB(j); } } catch { /* asked again */ }
+    };
+    void tick();
+    const t = setInterval(() => void tick(), 10_000);
+    return () => { live = false; clearInterval(t); };
+  }, []);
+  if (!b?.stale || !b.installed) return null;
+  const [installed, running] = tellApart(b.installed, b);
+  const restart = async () => {
+    setRestarting(true);
+    try { await fetch("/api/voss/restart", { method: "POST", headers: { "content-type": "application/json", ...apiHeaders() }, body: "{}" }); } catch { /* it may already be going */ }
+    const until = Date.now() + 90_000;
+    while (Date.now() < until) {
+      await sleep(1000);
+      try {
+        const r = await fetch("/api/voss", { headers: apiHeaders() });
+        if (r.status === 401) { location.reload(); return; }                       // the new daemon, with its new token
+        if (r.ok && (await r.json() as Voss).pid !== b.pid) { location.reload(); return; }
+      } catch { /* down for the moment */ }
+    }
+    setRestarting(false);
+  };
+  return (
+    <div className="gui-stale" role="status">
+      {restarting ? <span>Restarting voss…</span> : <>
+        <span>voss <b>{installed}</b> is installed; this page runs on <b>{running}</b>. Changes on disk wait for the restart.</span>
+        <Button onClick={() => void restart()}>Restart to update</Button>
+      </>}
+    </div>
+  );
+}
+
+// ---- the baba's page -----------------------------------------------------
+
+/** voss's pages before they were apps, and the app each is now. */
+const moved: Record<string, string> = { inspect: "state", world: "state", run: "contract", proofs: "maker" };
+
+/** A baba's page is voss's shell over it, always: its apps, or its one view, then voss's own. Its address is `/NAME/APP/PATH`. */
+function Host() {
+  const { d, failed } = useDescribed(scope);
+  const parts = location.pathname.split("/").filter(Boolean);
+  // An old page's address opens the app it is now, unless the baba has an app by that name.
+  const to = d && parts.length === 2 && !(d.manifest?.apps ?? []).some((a) => a.key === parts[1]) ? moved[parts[1]!] : undefined;
+  const [, moveOn] = useState(0);
+  useEffect(() => { if (to) { history.replaceState(null, "", `/${encodeURIComponent(scope)}/${to}${location.search}${location.hash}`); moveOn((n) => n + 1); } }, [to]);
+  if (to) return null;
+  if (!d) return <div className="gui-page"><p className="bv-muted">{failed ? `${scope} did not answer: ${failed}` : "…"}</p></div>;
+  if (!d.manifest) return <div className="gui-page"><p className="bv-error">{d.title} is not running.{d.error ? ` ${d.error}` : ""}</p></div>;
+  return <ShellPage d={d} />;
+}
+
+function Failure({ f }: { f: ViewFailure }) {
+  return <div className="gui-notice" role="alert"><strong>The interface did not {f.stage === "build" ? "build" : f.stage === "load" ? "load" : "render"}.</strong><pre className="gui-failure">{formatFailure(f)}</pre></div>;
+}
+
+/** The interface module at a generation: a component per app, or the old way a shell of its own; the stylesheets its build produced. */
+interface LoadedView { View: ComponentType | null; apps: Record<string, ComponentType<AppProps>>; css: string[] }
+const loaded = new Map<number, LoadedView>();
+
+async function loadView(name: string, v: number): Promise<LoadedView> {
+  const have = loaded.get(v);
+  if (have) return have;
+  const base = `/view/${encodeURIComponent(name)}/${v}/`;
+  const res = await fetch(base, { headers: apiHeaders() });
+  const index = await res.json() as { entry?: string; css?: string[]; error?: { message: string } };
+  if (!res.ok || !index.entry) throw new Error(index.error?.message ?? res.statusText);
+  const mod = await import(/* @vite-ignore */ base + index.entry);
+  const def = (mod.default ?? mod.view) as Interface | undefined;
+  if (!def || (!isApps(def) && typeof def.shell !== "function")) throw new Error("interface.tsx has no default export made by compose()");
+  const css = (index.css ?? []).map((p) => base + p);
+  const l: LoadedView = isApps(def) ? { View: null, apps: def.apps, css } : { View: def.shell, apps: {}, css };
+  loaded.set(v, l);
+  return l;
+}
+
+/** The interface at the baba's current generation, swapped only once the new one has loaded; its failure, if it has one. */
+function useInterface(d: Described): { view: LoadedView | null; failure: ViewFailure | null } {
+  const v = d.view && !d.view.error ? d.view.v : undefined;
+  const [view, setView] = useState<LoadedView | null>(() => (v !== undefined ? loaded.get(v) ?? null : null));
+  const [failure, setFailure] = useState<ViewFailure | null>(null);
+  useEffect(() => {
+    if (v === undefined) return;
+    let live = true;
+    loadView(d.name, v).then((l) => { if (live) { setView(l); setFailure(null); } }, (e) => { if (live) setFailure({ stage: "load", message: e instanceof Error ? e.message : String(e) }); });
+    return () => { live = false; };
+  }, [d.name, v]);
+  // The interface's stylesheets, as links.
+  useEffect(() => {
+    if (!view) return;
+    const links = view.css.map((href) => { const l = document.createElement("link"); l.rel = "stylesheet"; l.href = href; document.head.appendChild(l); return l; });
+    return () => { for (const l of links) l.remove(); };
+  }, [view]);
+  return { view, failure: d.view?.error ?? failure };
+}
+
+/** The shell's system as this baba runs it, from its manifest: the same apps. */
+const useShellSystem = (apps: readonly AppSpec[] | undefined) => {
+  const key = JSON.stringify(apps ?? []);
+  return useMemo(() => desktop({ apps: apps ?? [] }), [key]);
+};
+
+/**
+ * voss's shell over a baba: a window per app opened. An app draws the component the interface gave it,
+ * the one view draws an old interface whole, and voss's own apps draw voss's, unless the interface gave
+ * one of them its own. While the interface fails, each of the baba's apps says why; voss's still work.
+ */
+function ShellPage({ d }: { d: Described }) {
+  const { view, failure } = useInterface(d);
+  const system = useShellSystem(d.manifest?.apps);
+  const manifest = d.manifest!;
+  const components = useMemo(() => {
+    const pending = () => failure ? <Failure f={failure} /> : <p className="desktop-empty bv-muted">…</p>;
+    const out: Record<string, ComponentType<AppProps>> = {
+      // The Maker with no specs: the interface gives voss's maker app its own component, with the baba's specs and its apps, to replace this.
+      maker: ({ path, navigate, setTitle }) => <Maker specs={[]} title={d.title} path={path} navigate={navigate} setTitle={setTitle} />,
+      state: () => <section className="gui-app">{d.error && <p className="bv-error">The code did not load; the last generation serves: {d.error}</p>}<Inspector manifest={manifest} /></section>,
+      contract: () => <section className="gui-app"><Runner manifest={manifest} /></section>,
+      promptware: () => <section className="gui-app"><Promptware manifest={manifest} /></section>,
+      settings: Settings,
+    };
+    for (const sc of manifest.apps ?? []) {
+      if (sc.key in out) continue;
+      out[sc.key] = sc.key === "view" && !view?.apps[sc.key]
+        ? (view?.View ? (view.View as ComponentType<AppProps>) : !d.view ? () => <p className="desktop-empty bv-muted">This baba has no interface.tsx yet: its apps are voss's.</p> : pending)
+        : pending;
+    }
+    for (const [k, v] of Object.entries(view?.apps ?? {})) out[k] = v;
+    return out;
+  }, [view, failure, system, manifest, d.error, d.view, d.title]);
+  return (
+    <div className="gui-view" key={view ? "loaded" : "loading"}>
+      <ViewBoundary fallback={(f) => <div className="gui-page"><Failure f={f} /></div>}>
+        <Desktop system={system} apps={components} title={d.title} root={{ label: "voss", href: "/" }} />
+      </ViewBoundary>
+    </div>
+  );
+}
+
+/** voss's settings for this baba: the theme its pages share, in its state. */
+function Settings() {
+  const system = useMemo(() => desktop({}), []);
+  const current = useResource(system.desktopSettings)?.theme ?? "system";
+  const { fire } = useBaba<DesktopSystem>();
+  return (
+    <section className="gui-app">
+      <h2>Theme</h2>
+      <p className="bv-muted">The theme every page of this baba shows, kept in its state.</p>
+      <div className="gui-choices" role="radiogroup" aria-label="Theme">
+        {themes.map((t) => <Button key={t} variant={t === current ? "default" : "quiet"} role="radio" aria-checked={t === current} onClick={() => void fire("desktop-settings", { theme: t })}>{t}</Button>)}
+      </div>
+      <h2>voss</h2>
+      <p><a href="/">All babas</a></p>
+    </section>
+  );
+}
+
+class ViewBoundary extends Component<{ children: ReactNode; fallback: (f: ViewFailure) => ReactNode }, { failure: ViewFailure | null }> {
+  override state = { failure: null as ViewFailure | null };
+  static getDerivedStateFromError(err: unknown) {
+    return { failure: { stage: "render" as const, message: err instanceof Error ? err.message : String(err), detail: err instanceof Error ? err.stack : undefined } };
+  }
+  override render() {
+    return this.state.failure ? this.props.fallback(this.state.failure) : this.props.children;
+  }
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    {scope ? <ScopeProvider value={scope}><Host /></ScopeProvider> : <Root />}
+    <Stale />
+  </StrictMode>,
+);

package/src/gui/index.ts

@@ -0,0 +1,51 @@
+// voss's GUI: its page, its build with the shared modules. The picker at
+// the root, a baba's page at /NAME/ with its view, and voss's inspector and
+// runner over any baba.
+import { dirname, join } from "node:path";
+import { rm, rename } from "node:fs/promises";
+import { early } from "./theme.ts";
+import { shared, names, resolver } from "../build/views.ts";
+
+const here = dirname(Bun.fileURLToPath(import.meta.url));
+
+/** Builds the GUI and the shared modules into outdir. One React on the page. */
+export async function buildGui(outdir: string): Promise<void> {
+  await rm(outdir, { recursive: true, force: true });
+  // Each shared module gets an entry that names every export, written in
+  // memory: a CommonJS package like React cannot be re-exported with `export *`.
+  const files: Record<string, string> = {};
+  for (const [name, file] of Object.entries(shared)) {
+    const mod = await import(names[name] ?? name);
+    const keys = Object.keys(mod).filter((k) => k !== "default" && /^[A-Za-z_$][\w$]*$/.test(k));
+    files[join(here, "shared", file.replace(/\.js$/, ".ts"))] =
+      `import * as m from ${JSON.stringify(name)};\nexport default m.default ?? m;\n` +
+      keys.map((k) => `export const ${k} = m.${k};`).join("\n") + "\n";
+  }
+  const r = await Bun.build({
+    entrypoints: [join(here, "gui.tsx"), ...Object.keys(files)], files,
+    outdir, target: "browser", format: "esm", splitting: true,
+    naming: "[name].[ext]", plugins: [resolver],
+    jsx: { development: false },
+    define: { "process.env.NODE_ENV": '"production"' },
+  });
+  if (!r.success) throw new Error(r.logs.map(String).join("\n"));
+  const css = r.outputs.filter((o) => o.path.endsWith(".css"));
+  if (css.length !== 1) throw new Error(`the GUI build emitted ${css.length} stylesheets, expected one`);
+  await rename(css[0]!.path, join(outdir, "theme.css"));
+}
+
+/** The import map, as the page carries it: the shared names to the modules built with the GUI. */
+export const importMap = () => JSON.stringify({ imports: Object.fromEntries(Object.entries(shared).map(([n, f]) => [n, `/assets/${f}`])) });
+
+/** The page of a scope: the theme before the first paint, the import map, the GUI. */
+export function page(scope: string | null): string {
+  const meta = scope ? `<meta name="voss-scope" content="${escape(scope)}">` : "";
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${scope ? escape(scope) : "voss"}</title>${meta}<script>${early}</script><link rel="stylesheet" href="/assets/theme.css">
+<script type="importmap">${importMap()}</script></head>
+<body><div id="root"></div><script type="module" src="/assets/gui.js"></script></body></html>`;
+}
+
+function escape(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}