Embedding Dolly

Dolly is a POSIX-like userspace for wasm64 that runs in a browser tab: a Wasm kernel, programs in private Wasm memories, and host modules that bridge it to the browser. These npm packages put it in a page of your own. Their first use is an agent in place of a web frontend (docs/agent-frontend.md in the repository).

npm install @daugasauron/dolly @daugasauron/dolly-image-default \
  @daugasauron/dolly-host-display @daugasauron/dolly-host-input @daugasauron/dolly-host-save \
  @daugasauron/dolly-host-upload @daugasauron/dolly-host-html

Each host module and image depends on the runtime alone, at its own version, and a package also on the packages it installs. An image or package does not depend on the host modules it declares: install them with it (its README names them), so that all lie side by side under node_modules/@daugasauron/. npm, pnpm and Yarn 1 install them so. Yarn 2 and later need nodeLinker: node-modules in .yarnrc.yml: Plug'n'Play leaves no files to serve.

A page

<!doctype html>
<meta charset="utf-8">
<main id="dolly" style="position:fixed;inset:0"></main>
<script type="module">
  import { boot } from "./node_modules/@daugasauron/dolly/src/browser.mjs";
  import { images, image, modules } from "./node_modules/@daugasauron/dolly-image-default/index.mjs";
  const dolly = await boot(document.querySelector("#dolly"), { images, image, modules });
</script>

boot(element, options) runs an image in element, which the page sizes. It resolves once the image's program starts, to the page's handle on the session (hostModules, visibleTerminalText(), waitForInteractiveTerminal(pattern), then submit(command) at the shell's prompt, and what each module adds), and shows its own failure in the element. What Dolly shows, its modules' buttons, dialogs and indicators among them, stays inside element, and its styles select only there; keys typed outside it, into the page's own controls, are the page's.

The page, not the image, chooses the modules and the policy, before anything of the image runs. A program reaches nothing of the browser but through them.

More host modules

default declares nena@0, so a session can enable a module the page has and the image does not declare. Install its package and add its module.json:

npm install @daugasauron/dolly-host-gpu @daugasauron/dolly-host-microphone @daugasauron/dolly-host-pty

const gpu = new URL("./node_modules/@daugasauron/dolly-host-gpu/module.json", location.href).href;
const dolly = await boot(element, { images, image, modules: [...modules, gpu] });

nena enable gpu then gives a program the GPU, or, where the browser has no WebGPU adapter, a device that fails to open with ENODEV.

Colours

The terminal's colours and the popups' are the page's, not the image's. Set these on the element (or above it) in your style sheet to match your page; unset, they are Dolly's:

#dolly {
  --dolly-background: #262626;          /* the terminal's and the popups' */
  --dolly-color: #e8e3d7;               /* their text */
  --dolly-accent: #f2d45c;              /* the cursor and the selection; the popups' headings, buttons, focus */
  --dolly-display-palette-1: #e8e3d7;   /* -0 to -15: the 16 colours programs name */
}

Unset, of the 16 colours programs name, black (-0) is the background, yellow and bright yellow (-3, -11) the accent, bright black (-8) #77736c and the others the text's colour, so a program's red shows as its text does. A value may be any CSS colour; one that is not counts as unset. The terminal takes them at boot and whenever they change, by any rule or media query; a popup as it opens.

Popups

html@0 shows a program's HTML document in a popup over the terminal, in boot()'s element: a report, or a form whose submitted fields go back to the program (Pi's ask_user and show_html). The popup takes the document's text, headings, lists, tables and forms and nothing else of it; its look is the page's: the colours above and these, unset Dolly's:

#dolly {
  --dolly-html-font: ui-monospace, monospace;
  --dolly-html-color-scheme: dark;       /* the form controls' own colours */
  --dolly-html-font-file: none;          /* or url(…): the font of the first family above */
}

The popup loads nothing itself: the page fetches the font file, once, and hands the popup its bytes; without one, name fonts the system has. The page reads the properties each time a popup opens. Dolly's site sets "Dolly IosevkaTerm SemiBold", monospace and its font file.

Serving

• Serve the installed packages as they lie: the runtime finds its own files beside itself, and dolly-image-default's index.mjs finds the modules in the packages installed beside it under node_modules/@daugasauron/.
• Send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp with the page: Dolly needs shared memory, which a browser gives only to a cross-origin isolated page.
• Serve .wasm as application/wasm, .mjs as text/javascript and .json as application/json: a browser imports a host module's manifest and an image directory's catalog and metadata only with that type.
• No bundler is needed: these are ES modules, Workers and Wasm files.

Your own image

dolly-build builds a Dollyfile (docs/dollyfile.md in the repository) FROM the installed pi-minimal, with the packages whose directories are installed beside it, into a site: a directory that any static host serves as it lies. The build runs in a headless browser, with the installed runtime's own builder, as the catalog's images are built; the command serves the packages to it on 127.0.0.1 and writes what it hands back. Nothing of it, nor of the site, the page or the image, fetches from the network: after npm install, the packages hold every file. The build's browser reaches that server and the URLs of the recipe's own SOURCE rows alone; its own requests (its vendor's updates, clock and autofill) go to a proxy of the command's that refuses them.

npm install @daugasauron/dolly-build @daugasauron/dolly-package-git
npx dolly-build init my-pi git
npx dolly-build Dollyfile-my-pi my-pi

• dolly-build init NAME [PACKAGE…] writes a project where the packages are installed, and refuses to write over a file: Dollyfile-NAME (the host modules of pi-minimal and of each package, FROM pi-minimal and INSTALL of each package at the installed pins, rows for Pi's instructions, a skill, an extension, a tool and the script that starts Pi, and pi-minimal's ENTRY) and public/, the page's files: index.html (the policy, the popups' font, and the files of workspace/ and theme.json for boot()'s files, listed by workspace.json), theme.json (the sandbox's colours: Pi's theme, written over the image's at boot, whose background, text, accent and muted the page sets as the terminal's and the popups') and workspace/README.md; and, unless the project has one, a .gitignore for node_modules/ and the site. It names the host module package to install when a package needs one the page lacks (python's sockets). The repository README's "Pi with npm" says what each file is for.
• The recipe is the one place that declares the sandbox. Add rows before ENTRY: FILE with a body (indented four spaces) for a file, INSTALL of a package whose directory is installed (every package it needs comes with it, so python brings cc), SLOP to run the image's tools at build time. FROM carries the base's files, environment and exports but not its host modules or ENTRY, so the recipe repeats those; a package's REQUIRES HOST rows must be among the recipe's, and the build names a missing one. A recipe is at most 128 KiB; /workspace is never part of an image (boot()'s files writes the project at each boot).
• dolly-build Dollyfile-NAME OUT writes the site OUT, replacing the one it wrote there before: the files of public/, workspace.json (the files under public/workspace/), the runtime (dolly/), the device host modules the recipe declares (dolly-host-NAME/), coi-serviceworker.js and image/, the image's directory as an image package lays it out (its catalog, metadata and packs, the recipes it was built from, its amy-index.txt and an index.mjs). The page imports ./dolly/src/browser.mjs and ./image/index.mjs. An image this recipe built on this runtime is kept, so a change to public/ alone takes seconds. --browser chrome (the default: your Chrome), chromium or firefox (Playwright's, after npx playwright-core install chromium or firefox). Both commands run where the packages are installed: the directory whose node_modules/@daugasauron/ holds them (npm, pnpm and Yarn 1 alike). A row that names an image no installed package holds at that pin fails naming the row.
• Serve OUT with any static file server, python3 -m http.server -d OUT on your machine. Where the host sends the isolation headers ("Serving" above) the page is isolated; where it does not, init's page registers coi-serviceworker.js, which adds them to the site's own responses, and loads again under it.
• A recipe may start FROM another installed image instead, python-data say: its package's README gives the FROM row, and the recipe repeats the image's REQUIRES HOST rows (a FILE of the project's own script and a SLOP that runs it at build time, for example). init writes Pi's project only; the page in public/index.html is then one as in "A page" above that imports ./dolly/src/browser.mjs and ./image/index.mjs, with the lines of init's page that register coi-serviceworker.js for a host without the headers.
• An image is built for the installed versions: after the packages update, the rows' pins are others (init in an empty directory writes the new ones), and it is built again. Packages of two versions in one node_modules fail the build, naming both.

Host modules

A host module is a directory with a module.json; its provider receives what it needs from the runtime through the registry, and a device module imports nothing outside its directory. host/README.md in the repository describes the interface.