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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dolly contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Embedding Dolly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).
+
+| Package | What it holds |
+| --- | --- |
+| `@daugasauron/dolly` | The runtime: `boot()`, the kernel, the process runtime, and the host modules that are its own machinery (`runtime`, `http`, `threads`, `dso`, `stack`, `nena`, `snapshot`, `packages`). Building images stays with Dolly's site |
+| `@daugasauron/dolly-host-NAME` | One device host module each: `display` (Ghostty's terminal and programs' frames), `input`, `gpu`, `audio`, `microphone`, `touch`, `download`, `upload`, `sockets`, `pty` |
+| `@daugasauron/dolly-image-default` | The `default` image alone: a shell, its text tools, the terminal, curl, `amy`, `nena`, `ps`. `amy` lists what is installed and has nothing more to install |
+
+```sh
+npm install @daugasauron/dolly @daugasauron/dolly-image-default \
+  @daugasauron/dolly-host-display @daugasauron/dolly-host-input @daugasauron/dolly-host-audio \
+  @daugasauron/dolly-host-touch @daugasauron/dolly-host-download @daugasauron/dolly-host-upload \
+  @daugasauron/dolly-host-sockets
+```
+
+Each host module and image depends on the runtime alone, at its own version. An
+image 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
+
+```html
+<!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.
+
+| Option | Meaning |
+| --- | --- |
+| `images` | URL of an image directory: `dist/dolly-images.mjs`, the images' metadata and packs, their recipes. `@daugasauron/dolly-image-default`'s `index.mjs` exports its own. A page has one image directory |
+| `image` | The image to run, by name |
+| `modules` | URLs of the `module.json` of each host module the page has. The registry loads these and no other; an image's `REQUIRES HOST` must be among them |
+| `site` | Optional: the URL of a site that serves Dolly's own pages (`session/`, `sessions/`, `docs/`), as Dolly's site does. Given, a saved session names itself in the tab's URL and modules link to those pages |
+| `http` | Optional `{ policy, relays }` for the HTTP broker, the page's one network edge (docs/http.md). Without a policy a program may fetch any HTTPS URL |
+
+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`:
+
+```sh
+npm install @daugasauron/dolly-host-gpu @daugasauron/dolly-host-microphone @daugasauron/dolly-host-pty
+```
+
+```js
+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`.
+
+## 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` and `.mjs` as `text/javascript`.
+- No bundler is needed: these are ES modules, Workers and Wasm files.
+
+## 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.

package/dist/dolly-build-id.mjs

@@ -0,0 +1 @@
+export const DOLLY_BUILD_ID = "sha256:3642f6397575530c5410de65927a733ad526c2d55d239715800baac568572ec1";

package/dist/dolly-image-build-id.mjs

@@ -0,0 +1 @@
+export const DOLLY_IMAGE_BUILD_ID = "sha256:45d43ca59eeecb6128c23b546cd9c0d41be3cd7f67ce0c5ff78dfba4b94ef721";

package/dist/dolly-kernel-plugin-abi.mjs

@@ -0,0 +1,2 @@
+export const DOLLY_KERNEL_PLUGIN_ABI_DIGEST = "fdd2fac4029dad9bfdbdc053a1d5d0d72308f66ca1ce31404b3b4d354b2ee8ec";
+export const DOLLY_KERNEL_PLUGIN_IMPORTS = Object.freeze(["fopen","fseek","fclose","ftell","malloc","fread","free","dolly_assert_fail","realloc","strcmp","strncmp","strlen","memcmp","bcmp","write","__errno_location","lseek","preadv","close","fstat","unlinkat","openat","realpath","readv","dolly_input_decoder_install"]);

package/dist/dolly-process-abi.mjs

@@ -0,0 +1 @@
+export const DOLLY_PROCESS_ABI_DIGEST = "8002d2ac9e15e7d366e3eae77fdb1c61ac7650239792dc0c1ca64b7a1c3f4730";