@daugasauron/dolly 0.0.0-stage → 0.1.4-rc.0

package/host/snapshot/ui.mjs

@@ -0,0 +1,207 @@
+import { DOLLY_BUILD_ID } from "../../dist/dolly-build-id.mjs";
+import { DOLLY_IMAGES } from "../../src/images.mjs";
+import {
+  DOLLY_SESSION_FORMAT_VERSION,
+  customSessionIdentity,
+  encodeSessionStream,
+  loadStoredSession,
+  saveStoredSession,
+  sessionImageIdentity,
+  sessionLoadUrl,
+  validSessionName,
+} from "../../src/session-store.mjs";
+
+const markup = `<style>
+  #session-open { position: fixed; right: 0.5rem; bottom: 0.35rem; z-index: 6;
+    padding: 0.15rem 0.45rem; color: inherit; background: #262626;
+    border: 1px solid #77736c; font: inherit; font-size: 13px; cursor: pointer; }
+  #session-open[data-failed] { border-color: #e98773; }
+  #session-dialog { width: min(420px, calc(100vw - 2rem)); padding: 1.2rem;
+    background: #262626; color: inherit; border: 1px solid #77736c; font: inherit; }
+  #session-dialog::backdrop { background: #0008; }
+  #session-dialog h2 { margin: 0 0 1rem; font-size: 20px; }
+  #session-dialog p { font-size: 14px; line-height: 1.5; }
+  #session-dialog label { display: block; margin: 1rem 0 0.4rem; }
+  #session-dialog input { width: 100%; padding: 0.4rem; font: inherit;
+    color: inherit; background: #191919; border: 1px solid #77736c; }
+  #session-dialog button { padding: 0.35rem 0.65rem; font: inherit;
+    color: inherit; background: #333; border: 1px solid #77736c; cursor: pointer; }
+  #session-dialog a { color: #f2d45c; }
+  #session-dialog nav { display: flex; gap: 0.6rem; align-items: center; margin-top: 1rem; }
+  #session-dialog nav a { margin-right: auto; font-size: 14px; }
+</style>
+<button id="session-open" class="page-indicator" type="button" aria-label="Save session" title="Save session (Ctrl+Shift+S)" hidden>Save</button>
+<dialog id="session-dialog" aria-labelledby="session-title">
+  <form id="session-form">
+    <h2 id="session-title">Save session</h2>
+    <p id="session-detail" role="status"></p>
+    <p>Keep the program’s latest checkpoint, files and agent history in this browser.
+      Save again to keep later changes.</p>
+    <label for="session-name">Session name</label>
+    <input id="session-name" name="name" required minlength="1" maxlength="64"
+      pattern="[A-Za-z0-9._\\-]+" autocomplete="off" spellcheck="false">
+    <nav>
+      <a id="session-list" target="_blank" rel="noopener">Saved sessions ↗</a>
+      <button id="session-close" type="button">Close</button>
+      <button id="session-save" type="submit">Save</button>
+    </nav>
+  </form>
+</dialog>`;
+
+// The Save button, its dialog and Ctrl+Shift+S. A save captures the session
+// delta through the snapshot mailbox and keeps it in this browser. The page
+// describes the running image once its ENTRY starts; restored names the
+// session this page booted from, if any. On a page with a site, a save names
+// itself in the tab's URL and the dialog links the site's list of saves.
+export function mountSessionSave({ keyboard, showStatus, site, indicators }, transport, restored) {
+  document.body.insertAdjacentHTML("beforeend", markup);
+  const button = document.querySelector("#session-open");
+  const dialog = document.querySelector("#session-dialog");
+  const nameField = document.querySelector("#session-name");
+  const detail = document.querySelector("#session-detail");
+  const saveButton = document.querySelector("#session-save");
+  const dataset = document.documentElement.dataset;
+  let base, sessionName = null, lastSave = null, saveError = "";
+  let saving = null, controller = null;
+
+  function update(message) {
+    const failed = dataset.sessionStatus === "failed";
+    button.toggleAttribute("data-failed", failed);
+    button.textContent = failed ? "Save failed" : lastSave
+      ? `Save · ${lastSave.toLocaleTimeString([], {hour:"2-digit",minute:"2-digit"})}`
+      : sessionName ? "Save · restored" : "Save · not saved";
+    button.title = message ?? (lastSave
+      ? `Last saved ${lastSave.toLocaleTimeString()} · Ctrl+Shift+S saves again`
+      : sessionName ? `Restored ${sessionName} · Ctrl+Shift+S saves changes`
+      : "Not saved yet · Ctrl+Shift+S saves this session");
+    detail.textContent = message ?? (lastSave
+      ? `${sessionName} · Last saved ${lastSave.toLocaleTimeString()}.`
+      : sessionName ? `Restored ${sessionName}. Later changes need another save.`
+      : "Not saved yet. Refreshing or closing this tab loses its changes.");
+  }
+
+  function open() {
+    if (document.pointerLockElement) document.exitPointerLock();
+    nameField.value = sessionName ?? base?.image ?? "session";
+    update(dataset.sessionStatus === "failed" ? `Save failed: ${saveError}` : undefined);
+    dialog.showModal();
+    nameField.focus();
+    nameField.select();
+  }
+
+  button.addEventListener("click", open);
+  document.querySelector("#session-close").addEventListener("click", () => dialog.close());
+  dialog.addEventListener("close", () => keyboard.focus({ preventScroll: true }));
+  const list = document.querySelector("#session-list");
+  if (site) list.href = new URL("sessions/", site).href; else list.remove();
+  document.querySelector("#session-form").addEventListener("submit", event => {
+    event.preventDefault();
+    void save(nameField.value.trim()).catch(() => {});
+  });
+
+  async function save(requestedName) {
+    if (saving) return saving;
+    saving = (async () => {
+      if (!base) throw new Error("Dolly is not ready to save a session");
+      await base.verifyBase?.();
+      let name = requestedName ?? sessionName;
+      if (name === null) {
+        name = window.prompt("Save Dolly session as:", "");
+        if (name === null) return null;
+        name = name.trim();
+      }
+      if (!validSessionName(name)) {
+        throw new Error("Session names use 1-64 letters, numbers, '.', '_' or '-'");
+      }
+      if (name !== sessionName && await loadStoredSession(name) !== null &&
+          !window.confirm(`Replace the saved session '${name}'?`)) return null;
+      showStatus(`Saving ${name}…`, true);
+      dataset.sessionStatus = "capturing";
+      indicators.hold("session", true);
+      update(`Saving ${name}…`);
+      button.disabled = nameField.disabled = saveButton.disabled = true;
+      controller = new AbortController();
+      const capture = async onChunk => {
+        const result = await transport().capture(name, { signal: controller.signal, onChunk });
+        dataset.sessionUncompressedBytes = String(onChunk ? result : result.byteLength);
+        dataset.sessionStatus = "compressing";
+        return result;
+      };
+      const encoded = await encodeSessionStream(capture);
+      dataset.sessionStatus = "storing";
+      const encodedSize = encoded.bytes.byteLength;
+      try {
+        await saveStoredSession({
+          name,
+          formatVersion: DOLLY_SESSION_FORMAT_VERSION,
+          buildId: DOLLY_BUILD_ID,
+          image: base.image,
+          imageIdentity: base.identity,
+          ...(base.custom ? { customImage: base.custom } : {}),
+          updatedAt: Date.now(),
+          encoding: encoded.encoding,
+          bytes: encoded.bytes,
+        });
+      } finally { encoded.bytes.transfer(0); }
+      sessionName = name;
+      lastSave = new Date();
+      dataset.session = name;
+      dataset.sessionBytes = String(encodedSize);
+      dataset.sessionStatus = "saved";
+      if (site) history.replaceState(null, "", sessionLoadUrl(name, site));
+      showStatus(`Saved ${name} locally${site ? " · /sessions lists your saves" : ""}`);
+      indicators.hold("session", false);
+      update();
+      return name;
+    })().catch((error) => {
+      dataset.sessionStatus = "failed";
+      saveError = error instanceof Error ? error.message : String(error);
+      showStatus(`Save failed: ${saveError}`, true);
+      indicators.hold("session", true);
+      update(`Save failed: ${saveError}`);
+      throw error;
+    }).finally(() => {
+      saving = null;
+      controller = null;
+      button.disabled = nameField.disabled = saveButton.disabled = false;
+    });
+    return saving;
+  }
+
+  return {
+    get name() { return sessionName; },
+    save,
+    // The dialog and the Save button keep their keys; Ctrl+Shift+S saves, the
+    // first time through the dialog.
+    claimsKey(event) {
+      if (dialog.open || button.contains(event.target)) return true;
+      if (!base || !event.ctrlKey || !event.shiftKey || event.altKey || event.metaKey || event.code !== "KeyS") return false;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      if (event.type === "keydown" && !event.repeat) {
+        if (sessionName === null) open();
+        else void save().catch(() => {});
+      }
+      return true;
+    },
+    // custom is the running custom image record (Dollyfile, artifact and
+    // what the tab inherited); verifyBase, given, checks before a save that
+    // the base is still the one the session restores onto (the site's routes,
+    // src/site.mjs). The identity names that base.
+    entryStarted({ image, custom, verifyBase }) {
+      base = { image, custom, verifyBase,
+        identity: custom ? customSessionIdentity(custom) : sessionImageIdentity(DOLLY_IMAGES, image) };
+      if (restored?.recovering) {
+        dataset.sessionStatus = "recovered";
+        showStatus(`Recovered files in /workspace/recovered-${restored.name}. Ctrl+Shift+S saves this as a new session.`, true);
+      } else if (restored) {
+        sessionName = restored.name;
+        dataset.session = restored.name;
+        dataset.sessionStatus = "restored";
+      }
+      button.hidden = false;
+      update();
+    },
+    abort() { controller?.abort(new Error("The runtime stopped; the previous save is unchanged")); },
+  };
+}

package/host/stack/abi.mjs

@@ -0,0 +1,5 @@
+// Generated from host/stack/dolly-stack-0.wat, include/dolly/process.h.
+export const DOLLY_STACK_CONTINUE = 116;
+export const DOLLY_STACK_CHECK_SLOTS = 16384;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
+export const DOLLY_STACK_ABI_DIGEST = "60e29cb49bedc7e2b891c2837343939cab882a4ca32d03672f9e362cfcd8c1b3";

package/host/stack/module.json

@@ -0,0 +1,17 @@
+{
+  "name": "stack",
+  "version": 0,
+  "gives": "recursion deeper than one browser stack",
+  "dependencies": ["runtime@0"],
+  "phase": "kernel",
+  "imports": [],
+  "host": "stack.mjs",
+  "processWorker": "process.mjs",
+  "contracts": [],
+  "process": ["dolly-stack-0.wat"],
+  "headers": ["stack-abi.h"],
+  "kernel": [],
+  "client": [],
+  "package": "stack-wrap",
+  "tools": ["stack-wrap.c"]
+}

package/host/stack/stack.mjs

@@ -0,0 +1,19 @@
+export { DOLLY_STACK_ABI_DIGEST as digest } from "./abi.mjs";
+
+// The provider (process.mjs) runs inside the process Worker of an executable
+// that records stack@0. This side fetches its bundle once, as the supervisor
+// fetches the process Worker: starting a program makes no request.
+export function worker({ get, runtimeBase }) {
+  return {
+    async start() {
+      const response = await fetch(new URL("dist/dolly-process-stack.mjs", runtimeBase), {
+        cache: "no-store", credentials: "same-origin", redirect: "error",
+      });
+      if (!response.ok) throw new Error(`Dolly dolly-process-stack.mjs returned HTTP ${response.status}`);
+      // threads: it serves each thread's Worker of a program using threads@0.
+      get("runtime").serveInProcess("stack@0", {
+        bundle: new Blob([await response.arrayBuffer()], { type: "text/javascript" }), configuration: {}, threads: true });
+    },
+    disabled() { get("runtime").serveInProcess("stack@0"); },
+  };
+}

package/host/threads/abi.mjs

@@ -0,0 +1,8 @@
+// Generated from host/threads/dolly-threads-supervisor-0.wat, host/threads/dolly-threads-0.wat, host/threads/threads.h, include/dolly/process.h.
+export const DOLLY_THREAD_SPAWN = 144;
+export const DOLLY_THREAD_SELF = 145;
+export const DOLLY_THREAD_EXIT = 146;
+export const DOLLY_THREAD_WAIT = 147;
+export const DOLLY_THREAD_WAIT_NONBLOCK = 1;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
+export const DOLLY_THREADS_ABI_DIGEST = "fcbd4fc02150731c9a351445157d854916d5c3fd84faf9933bbcdcc16bf146af";

package/host/threads/module.json

@@ -0,0 +1,13 @@
+{
+  "name": "threads",
+  "version": 0,
+  "gives": "threads, a Worker each: 32 a process, 64 in all",
+  "dependencies": ["runtime@0"],
+  "imports": [],
+  "host": "threads.mjs",
+  "contracts": ["dolly-threads-supervisor-0.wat"],
+  "process": ["dolly-threads-0.wat"],
+  "headers": ["threads.h", "threads-abi.h"],
+  "kernel": ["kernel.c"],
+  "client": ["client.c"]
+}

package/host/threads/threads.mjs

@@ -0,0 +1,36 @@
+import { sameWasmType } from "../../src/wasm-interface.mjs";
+export { DOLLY_THREADS_ABI_DIGEST as digest } from "./abi.mjs";
+
+// An executable that links the threads client (every -pthread program) is
+// threaded; its requirement's digest is checked with the others.
+export function validateThreadProfile(parsed, requirements, schema) {
+  if (!requirements.has("threads@0")) return false;
+  const expected = schema.exports.find(entry => entry.name === "dolly_thread_start");
+  const actual = parsed.exports.find(entry => entry.name === expected.name);
+  if (!actual || !sameWasmType(actual.type, expected.type))
+    throw new TypeError("a program using threads@0 must export dolly_thread_start(i32, i64) -> i64; build C and C++ with -pthread");
+  return true;
+}
+
+export function worker({ get }) {
+  // Trusted resource limits, independent of kernel bookkeeping or guest claims.
+  // Retired threads retain their join result in Wasm, not a Worker or host slot.
+  const workers = new Map();
+  const provider = {
+    available(pid) {
+      return workers.size < 64 && [...workers.values()].filter(owner => owner === pid).length < 32;
+    },
+    create(pid, url, name) {
+      if (!provider.available(pid)) return null;
+      const worker = new Worker(url, { type: "module", name });
+      workers.set(worker, pid);
+      return worker;
+    },
+    release(worker) { worker.terminate(); workers.delete(worker); },
+    dispose() { for (const worker of workers.keys()) worker.terminate(); workers.clear(); },
+    // The runtime goes on without the module: the programs on its Workers end.
+    disabled() { get("runtime").setThreadProvider(undefined); },
+  };
+  get("runtime").setThreadProvider(provider);
+  return provider;
+}

package/package.json

@@ -1,6 +1,14 @@
 {
+  "version": "0.1.4-rc.0",
+  "type": "module",
   "name": "@daugasauron/dolly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "license": "MIT",
+  "exports": {
+    ".": "./src/browser.mjs"
+  },
+  "description": "Dolly's runtime: a POSIX-like userspace for wasm64 in a browser tab. Run images with boot().",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daugasauron/dolly.git"
+  }
+}

package/src/alphabetical.mjs

@@ -0,0 +1,4 @@
+// The one order of every list a visitor reads on the site's pages: by the
+// visible name, ignoring case. Names that differ only in case keep one order.
+const collator = new Intl.Collator("en", { sensitivity: "base" });
+export const alphabetical = (left, right) => collator.compare(left, right) || (left < right ? -1 : left > right ? 1 : 0);

package/src/browser.mjs

@@ -0,0 +1,237 @@
+import { buildLog } from "./build-log.mjs";
+import { holdIndicators, showIndicators } from "./page-indicators.mjs";
+import { hostRegistry } from "../host/modules.mjs";
+import { pageChords } from "./page-chords.mjs";
+import { terminalText } from "./terminal-text.mjs";
+import { DOLLY_IMAGES, DOLLY_STATIC_SOURCES, imageBase, loadImages } from "./images.mjs";
+import * as processConstants from "./process-constants.mjs";
+
+// The terminal's own look: its canvas, the hidden keyboard, the boot log and
+// the status line. A host module brings the look of what it adds; the page, the
+// boot log's font (the site's is Iosevka, dist/IosevkaTerm-SemiBold.woff2).
+const style = `
+  .dolly-terminal { position: relative; overflow: hidden; outline: none; caret-color: transparent; }
+  #display { display: block; width: 100%; height: 100%; cursor: text; touch-action: none; }
+  #display[hidden] { display: none; }
+  #keyboard { position: fixed; left: -10000px; top: 0; width: 1px; height: 1px; opacity: 0; caret-color: transparent; }
+  #bootstrap-log { position: absolute; inset: 0; z-index: 1; margin: 0; padding: 1rem 1.15rem; overflow: auto;
+    white-space: pre-wrap; color: #e8e3d7; background: #262626; font: 600 20px/1.35 "Dolly IosevkaTerm SemiBold", monospace;
+    scrollbar-width: thin; scrollbar-color: #f2d45c #262626; }
+  #bootstrap-log[hidden] { display: none; }
+  #session-status { position: fixed; right: 1rem; top: 1rem; z-index: 5; max-width: calc(100vw - 2rem);
+    padding: 0.5rem 0.75rem; color: #e8e3d7; background: #262626; border: 1px solid #77736c; font-size: 14px; }
+  #session-status[hidden] { display: none; }
+  html[data-indicators="hidden"] .page-indicator { display: none; }
+  @media (max-width: 640px) { #bootstrap-log { padding: 0.65rem 0.75rem; } }
+`;
+
+function element(tag, properties, attributes = {}) {
+  const node = Object.assign(document.createElement(tag), properties);
+  for (const [name, value] of Object.entries(attributes)) node.setAttribute(name, value);
+  return node;
+}
+
+// Runs an image in `mount`, an element the embedding sizes, from the image
+// directory `images` (images.mjs). The embedding, trusted page code, names the
+// host modules the page has (`modules`, the URLs of their manifests) and sets
+// the HTTP broker's policy (`http`: { policy, relays }), both before anything
+// of the guest runs. `site`, given, is the root of the routes a module may link
+// to (session/, sessions/, docs/). It resolves to the page's API (window.__dolly
+// on the site) once the image's ENTRY runs.
+export function boot(mount, { images, image, modules, site, http = {} } = {}) {
+  return run(mount, { images, modules, site, http }, async () => {
+    const definition = DOLLY_IMAGES.find(candidate => candidate.image === image);
+    if (!definition) throw new Error("invalid Dolly boot options");
+    if (definition.entry === null) throw new Error(`${image} has no ENTRY; it only builds`);
+    return { image, label: "PRECOMPILED SYSTEM", required: definition.hostRequirements ?? [] };
+  });
+}
+
+// What boot() does, for the routes of the site too (site.mjs), which build and
+// restore images of their own. `route(registry)` selects what runs:
+// - image, label: the route's image ("custom" for none) and its boot log line;
+// - required, enabled: the host modules the image requires, and those the page
+//   enables (by default the required ones), which a build alone may set;
+// - configuration, inherited: the modules' configuration, and what http@0
+//   inherits from the tab that opened this one;
+// - worker: the runtime Worker's URL, by default runtime-worker.mjs;
+// - start(host, report): before the Worker starts, the fields it adds to the
+//   configure message ({ message, transfers }), or null once an image without
+//   ENTRY is built;
+// - message(message): each message of the Worker;
+// - running(ready, host): the context host modules' entryStarted is given
+//   beside `image`, and members of the page's handle.
+export async function run(mount, { images, modules, site, http }, route) {
+  if (!document.querySelector("style[data-dolly]")) {
+    document.head.append(element("style", { textContent: style }, { "data-dolly": "" }));
+  }
+  const canvas = element("canvas", { id: "display", hidden: true }, { "aria-label": "Dolly sandbox framebuffer" });
+  const keyboard = element("textarea", { id: "keyboard" }, { "aria-label": "Dolly keyboard input",
+    autocomplete: "off", autocapitalize: "off", spellcheck: "false" });
+  const bootstrapLog = element("pre", { id: "bootstrap-log" }, { "aria-live": "polite" });
+  const status = element("div", { id: "session-status", hidden: true }, { role: "status" });
+  mount.classList.add("dolly-terminal");
+  mount.replaceChildren(canvas, keyboard, bootstrapLog, status);
+  const bootstrapOutput = buildLog(bootstrapLog);
+  bootstrapOutput.clear();
+  const appendBootstrap = text => bootstrapOutput.append(text);
+  pageChords(keyboard);
+  const bootstrapDecoder = new TextDecoder();
+
+  let runtimeWorker;
+  let host;
+  let rejectReady = null;
+  let runtimeReady = false;
+  let statusTimer;
+
+  // The runtime stopped: its host modules let go of the page, and the bootstrap
+  // log shows the reason over whatever a module drew.
+  function fatal(message) {
+    rejectReady?.(new Error(message));
+    host?.dispose();
+    runtimeWorker?.terminate();
+    bootstrapLog.hidden = false;
+    appendBootstrap(`\nFATAL\n${message}\n`);
+    document.documentElement.dataset.dollyStatus = "failed";
+  }
+
+  // The image is over when its ENTRY process is. The page says how in its own
+  // text below the display, which keeps the last frame and gives up that strip:
+  // a program can draw a lookalike while it runs, but nothing of the guest can
+  // cover, change or remove this notice. A module may offer a link beside
+  // "start again".
+  function ended({ status: code, signal, failure }) {
+    const offers = host.ended();
+    host.dispose();
+    runtimeWorker.terminate();
+    const signalName = Object.keys(processConstants).find(name =>
+      /^DOLLY_PROCESS_SIG(?!NAL)/.test(name) && processConstants[name] === signal)?.slice("DOLLY_PROCESS_".length);
+    const how = failure ? `failed: ${failure}` : signal ? `was ended by ${signalName ?? `signal ${signal}`}`
+      : `exited with status ${code}`;
+    const notice = mount.appendChild(element("div", { id: "image-ended" }, { role: "alert" }));
+    notice.style.cssText = "position:fixed;left:0;right:0;bottom:0;z-index:9;padding:0.6rem 1rem;" +
+      "color:#e8e3d7;background:#262626;border-top:1px solid #f2d45c;font-size:16px";
+    const links = [{ text: "Reload to start again", href: location.href }, ...offers].map(({ text, href }) =>
+      Object.assign(document.createElement("a"), { textContent: text, href, style: "color:#f2d45c;margin-left:1.5ch" }));
+    notice.append(`This image has ended: its program ${how}.`, ...links);
+    mount.style.height = `calc(100% - ${notice.offsetHeight}px)`;
+    Object.assign(canvas.style, { objectFit: "contain", objectPosition: "left top" });
+    links[0].focus();
+    document.documentElement.dataset.dollyStatus = "exited";
+  }
+
+  function showStatus(message, persistent = false) {
+    clearTimeout(statusTimer);
+    status.textContent = message;
+    status.hidden = false;
+    if (!persistent) statusTimer = setTimeout(() => { status.hidden = true; }, 6000);
+  }
+
+  addEventListener("pagehide", () => { host?.dispose(); runtimeWorker?.terminate(); });
+  try {
+    document.documentElement.dataset.dollyStatus = "loading";
+    await loadImages(images);
+    if (!Array.isArray(modules) || !modules.length || !(site === undefined || typeof site === "string")) {
+      throw new Error("invalid Dolly boot options");
+    }
+    const registry = await hostRegistry(modules);
+    const selected = await route(registry);
+    const { image } = selected;
+    const bootstrapSources = [
+      ...DOLLY_IMAGES.map((definition) => ({
+        path: `/${definition.dollyfile}`,
+        byteLength: definition.byteLength,
+      })),
+      ...DOLLY_STATIC_SOURCES,
+    ];
+    appendBootstrap(`DOLLY / ${image.toUpperCase()} / ${selected.label}\n\n`);
+    host = await registry.createHost("browser", selected.enabled ?? selected.required, {
+      send: (message, transfers = []) => runtimeWorker.postMessage(message, transfers),
+      resources: { mount, canvas, keyboard, applicationBase: imageBase, site: site && new URL(site), showStatus, fatal,
+        indicators: { hold: holdIndicators, show: showIndicators } },
+      configuration: { ...selected.configuration, http: { ...selected.configuration?.http, embedding: http,
+        sources: bootstrapSources, inherited: selected.inherited } },
+    });
+    host.require(selected.required);
+    const started = selected.start ? await selected.start(host, appendBootstrap) : { message: {}, transfers: [] };
+    if (started === null) {
+      document.documentElement.dataset.dollyStatus = "built";
+      host.dispose();
+      return null;
+    }
+
+    runtimeWorker = new Worker(selected.worker ?? new URL("./runtime-worker.mjs", import.meta.url), {
+      type: "module",
+      name: "dolly-runtime",
+    });
+    // An uncaught failure in the Worker, a kernel trap outside a system call
+    // among them, is the runtime's end: the page says so.
+    runtimeWorker.addEventListener("error", event => {
+      const message = event.message || "the runtime Worker failed";
+      if (rejectReady) rejectReady(new Error(message)); else fatal(message);
+    });
+    runtimeWorker.addEventListener("message", (event) => {
+      const message = event.data;
+      void host.handle(message).catch(error => fatal(error.message));
+      selected.message?.(message);
+      if (message.type === "bootstrap") {
+        appendBootstrap(message.text);
+      } else if (message.type === "bootstrap-bytes") {
+        appendBootstrap(bootstrapDecoder.decode(message.bytes, { stream: true }));
+      } else if (message.type === "exited") {
+        ended(message);
+      } else if (message.type === "error" && runtimeReady) {
+        fatal(message.stack ? `${message.message}\n${message.stack}` : message.message);
+      }
+    });
+    runtimeWorker.postMessage({
+      type: "configure",
+      image,
+      mode: "snapshot",
+      images: imageBase.href,
+      modules: registry.urls,
+      hostModules: host.enabled,
+      hostConfiguration: host.configuration,
+      ...started.message,
+    }, [...host.transfers, ...started.transfers]);
+
+    const ready = await new Promise((resolve, reject) => {
+      rejectReady = reject;
+      runtimeWorker.addEventListener("message", function onMessage(event) {
+        if (event.data.type === "ready") {
+          runtimeWorker.removeEventListener("message", onMessage);
+          resolve(event.data);
+        } else if (event.data.type === "error") {
+          runtimeWorker.removeEventListener("message", onMessage);
+          const error = new Error(event.data.message);
+          if (event.data.stack) error.stack = event.data.stack;
+          reject(error);
+        }
+      });
+    }).finally(() => { rejectReady = null; });
+    appendBootstrap(bootstrapDecoder.decode());
+    runtimeReady = true;
+    if (ready.routeImage !== image || (image !== "custom" && ready.image !== image)) {
+      throw new Error("runtime image mismatch");
+    }
+    document.documentElement.dataset.image = ready.image;
+    const { context, page } = await selected.running?.(ready, host) ?? {};
+    await host.entryStarted({ image, ...context });
+    runtimeWorker.postMessage({ type: "entry-ready-ack" });
+    // A module that shows the canvas replaces the bootstrap log.
+    bootstrapLog.hidden = !canvas.hidden;
+
+    keyboard.focus({ preventScroll: true });
+    document.documentElement.dataset.dollyStatus = "ready";
+    showIndicators();
+
+    return Object.create(host.page, {
+      ...Object.getOwnPropertyDescriptors({ ...terminalText(host.page), get hostModules() { return host.enabled; } }),
+      ...Object.getOwnPropertyDescriptors(page ?? {}),
+    });
+  } catch (error) {
+    runtimeReady = false;
+    fatal(error instanceof Error ? error.message : String(error));
+    throw error;
+  }
+}

package/src/build-log.mjs

@@ -0,0 +1,30 @@
+// Keep compiler output as text, bounded even when a guest floods stdout.
+export function buildLog(element) {
+  const maximum = 1024 * 1024;
+  let length = 0, escape = "", carriageReturn = false;
+  return {
+    clear() { element.replaceChildren(); length = 0; escape = ""; carriageReturn = false; },
+    append(text) {
+      const follow = element.scrollHeight - element.scrollTop - element.clientHeight < 24;
+      text = escape + String(text);
+      escape = /\x1b(?:\[[0-9;:]{0,128})?$/.exec(text)?.[0] ?? "";
+      if (escape) text = text.slice(0, -escape.length);
+      text = text.replace(/\x1b\[[0-9;:]*m/g, "");
+      if (!text) return;
+      if (carriageReturn && text.startsWith("\n")) text = text.slice(1);
+      carriageReturn = text.endsWith("\r");
+      text = text.replace(/\r\n?/g, "\n").slice(-maximum);
+      if (!text) return;
+      if (element.lastChild && element.lastChild.length + text.length <= 4096) {
+        element.lastChild.appendData(text);
+      } else element.append(element.ownerDocument.createTextNode(text));
+      length += text.length;
+      while (length > maximum) {
+        const first = element.firstChild, excess = length - maximum;
+        if (first.length <= excess) { length -= first.length; first.remove(); }
+        else { first.deleteData(0, excess); length -= excess; }
+      }
+      if (follow) element.scrollTop = element.scrollHeight;
+    },
+  };
+}

package/src/image-entry.mjs

@@ -0,0 +1,29 @@
+// Shared by packaging and browser admission; empty arguments are valid.
+export function decodeImageEntry(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength < 16 || bytes.byteLength > 64 * 1024) {
+    throw new TypeError("invalid image ENTRY record");
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (decoder.decode(bytes.subarray(0, 8)) !== "DOLLYENT" || view.getUint32(8, true) !== 1) {
+    throw new TypeError("invalid image ENTRY version");
+  }
+  const count = view.getUint32(12, true);
+  if (count === 0 || count > 256) throw new TypeError("invalid image ENTRY count");
+  let offset = 16;
+  const arguments_ = [];
+  for (let index = 0; index < count; ++index) {
+    if (offset > bytes.byteLength - 4) throw new TypeError("truncated image ENTRY");
+    const size = view.getUint32(offset, true);
+    offset += 4;
+    if (size > 4096 || offset > bytes.byteLength - size) throw new TypeError("invalid image ENTRY argument");
+    const value = decoder.decode(bytes.subarray(offset, offset + size));
+    if (value.includes("\0")) throw new TypeError("image ENTRY has a NUL argument");
+    arguments_.push(value);
+    offset += size;
+  }
+  if (offset !== bytes.byteLength || !arguments_[0].startsWith("/")) {
+    throw new TypeError("invalid image ENTRY payload");
+  }
+  return arguments_;
+}

package/src/image-inputs.mjs

@@ -0,0 +1,20 @@
+// Recipe pins identify instructions; artifact digests identify their results.
+export function imageInputs(artifacts = []) {
+  if (!Array.isArray(artifacts) || artifacts.length > 256) throw new Error("invalid image inputs");
+  const inputs = new Map();
+  for (const artifact of artifacts) {
+    const { recipeSha256, sha256 } = artifact ?? {};
+    if (!/^[0-9a-f]{64}$/.test(recipeSha256) || !/^[0-9a-f]{64}$/.test(sha256)) {
+      throw new Error("invalid image input digest");
+    }
+    if (inputs.has(recipeSha256) && inputs.get(recipeSha256).sha256 !== sha256) {
+      throw new Error("conflicting image inputs");
+    }
+    inputs.set(recipeSha256, { recipeSha256, sha256 });
+  }
+  return [...inputs.values()].sort((a, b) => a.recipeSha256.localeCompare(b.recipeSha256));
+}
+
+export function imageInputsMatch(actual, expected) {
+  return JSON.stringify(imageInputs(actual)) === JSON.stringify(imageInputs(expected));
+}