arm64js 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantin Goncharuk
+
+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

@@ -0,0 +1,286 @@
+# ARM64JS SDK
+
+[![npm](https://img.shields.io/npm/v/arm64js)](https://www.npmjs.com/package/arm64js)
+[![CI](https://github.com/kooler/arm64js-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kooler/arm64js-sdk/actions/workflows/ci.yml)
+
+Arm64js is a WebAssembly-based arm64 emulator running in a web browser and allowing you to boot and control a real Linux (Alpine).
+
+This SDK helps to: create a VM, set it up and interact with it.
+
+The SDK is distributed as an npm package and integrated with the arm64js CDN.
+
+## VM creation lifecycle
+
+### 1. Boot a base image
+
+Similarly to Docker, you need to select a base image to boot the initial state of your VM. At the moment, only base images provided by arm64js can be used as they require some customization to work "quicker" when emulated in a web browser. The list of images and their versions is at [arm64js.com/images](https://arm64js.com/images/). Booting the image creates a VM instance:
+
+```js
+import { Arm64JS } from 'arm64js';
+const vm = await Arm64JS.boot('alpine');
+```
+
+### 2. Set up the VM
+
+You would likely want to install some extra packages or copy files into your VM so that it can do something useful. For managing packages, use `apk` as you would in the native Alpine. To execute a command (any command pretty much), the `vm.exec` method is used:
+
+```js
+const { output, exitCode } = await vm.exec('apk add --no-cache curl');
+```
+
+It returns raw `output` and `exitCode` so that you can verify the result.
+
+The VM _does not_ have access to the Internet except for the apk registry. To give it your own data, you can use one of the two options:
+
+- `vm.writeFile`: copies the specified file into the VM. Changing or deleting the file happens only inside the VM. The file is saved and loaded with the snapshot. Uses VM memory to copy the file, thus is intended mainly for smaller (up to 100 MiB) files.
+- `vm.mount`: read-only, direct mount of the data blob. Doesn't use any VM memory. Not stored in the snapshot. To unmount use `vm.unmount()`.
+
+See example below:
+
+```js
+await vm.writeFile('/root/data.csv', file); // creates a physical file in the VM
+await vm.mount({ 'model.bin': bigFile }, '/data'); // read-only, directly mounted blob, does not copy anything into the VM so it can be a large file
+```
+
+To read any file from the VM, use `readFile`:
+
+```js
+const result = await vm.readFile('/root/result.txt'); // a copy out, as a Blob
+```
+
+### 3. Make a snapshot and save it locally
+
+Once you are done with the VM setup, you would likely want to save it so that you don't need to do the same setup again. For that, make a snapshot of the VM. Snapshots are stored in the [OPFS](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system).
+
+```js
+const snap = await vm.snapshot({ name: 'alpine with curl' });
+console.log(snap.id); // this is the id we'd need to store to load the snapshot later
+```
+
+To load from the snapshot, specify its ID when creating the VM:
+
+```js
+const again = await Arm64JS.boot(snap.id);
+```
+
+## Where the VM runs
+
+The VM needs `SharedArrayBuffer` which browsers only give to cross-origin-isolated pages. If the `Cross-Origin-Opener-Policy` (COOP) header is not specified or not sufficient, the SDK will load the VM inside an iframe on the `cdn.arm64js.com` domain.
+
+The following decision process is being used:
+
+| Your page                                                                                        | What happens                                                                                  |
+| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| sends `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` | the VM runs **inline**, in your page's own workers. Works in all modern browsers.             |
+| sends no COOP headers (likely)                                                                   | the VM runs in a hidden **frame** served from the arm64js CDN. Works in Chrome and Edge 137+. |
+| no COOP header and a browser that doesn't support the iframe fallback (Firefox, Safari)          | `boot()` rejects with `unsupported-browser`.                                                  |
+
+Call `Arm64JS.mode()` to see which mode is being used.
+
+### Setting the headers
+
+To run the VM inline, send these two headers with the page that runs the VM:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+We recommend setting them only on the pages that run the VM, not on the whole site, because they change how the browser treats a page:
+
+- files from other domains (scripts, images, fonts, iframes) load only if their server allows it with a `Cross-Origin-Resource-Policy` or CORS header (arm64js CDN already does).
+- popups the page opens lose their link to it, which can break for example sign-in or payment popups.
+
+Here's an example of how to send them with nginx:
+
+```nginx
+location = /playground.html {
+    add_header Cross-Origin-Opener-Policy same-origin;
+    add_header Cross-Origin-Embedder-Policy require-corp;
+}
+```
+
+To check the setup, run `await Arm64JS.mode()`, it should return `'inline'`.
+
+### Content-Security-Policy
+
+If your page sends a Content-Security-Policy and you would like to use the iframe-based solution, you need to allow the arm64js CDN as an origin: `script-src https://cdn.arm64js.com`, `connect-src https://cdn.arm64js.com`, `worker-src blob:` (the VM's workers are started through a blob), and `frame-src https://cdn.arm64js.com` for the iframe itself.
+
+## Install
+
+```sh
+npm install arm64js
+```
+
+## API
+
+### `Arm64JS.boot(image | snapshotId, { vcpus?, onProgress? })` → `Vm`
+
+A VM can be created either from a base image or your own local snapshot.
+
+- `image`: name of an image on the CDN ([all images](https://arm64js.com/images/)): `'alpine'` is the newest version of it, `'alpine:2'` a fixed one, `'alpine@sha256:<hash>'` an exact snapshot.
+- `snapshotId`: a snapshot id (`snap.id`, 64 hex characters) loads one of your own snapshots made previously.
+
+Additionally, you can specify an `onProgress` callback to track VM loading phases (`resolve → manifest → start → memory (repeats, with counts) → run → done`) and the number of virtual CPUs the VM will have (more is not always better).
+
+### Listener: `vm.onOutput(cb)` → unsubscribe
+
+The raw bytes the guest prints on its console, including escape sequences.
+
+```js
+const decoder = new TextDecoder(); // The output comes as bytes (Uint8Array), TextDecoder turns them into text.
+const stopOutput = vm.onOutput((bytes, info) => {
+  if (info.exec) return; // skip commands that we call ourselves
+  console.log(decoder.decode(bytes, { stream: true }));
+});
+
+// to stop listening:
+stopOutput();
+```
+
+### `vm.onExit(cb)` → unsubscribe
+
+The VM stopped (halted or faulted). Every later call on the VM rejects with `vm-exited`. If the hidden frame running the VM stops answering, `reason` is `'lost'` and later calls reject with `vm-lost`.
+
+If the VM has already stopped, the callback is called right away. It is not called for `vm.dispose()`.
+
+```js
+const stopExit = vm.onExit(({ reason }) => console.log(`VM stopped: ${reason}`));
+
+// later, to stop listening:
+stopExit();
+```
+
+### `vm.exec(command, { timeoutMs? })` → `{ output, exitCode, truncated }`
+
+Runs `command` in the guest's shell (`sh`), and returns what it printed and its exit status. `command` can be one command or several, one per line. The default timeout is two minutes.
+
+It works by typing the command into the guest's serial console and reading the bytes back. There are a few limits:
+
+- stdout and stderr are merged into one stream.
+- Each line of the command must be under 4000 bytes.
+- **`output` is capped at 1 MiB**, and past that the head is dropped and `truncated` is `true`. Write to a file and read it back if you need more.
+- A timeout does its best to terminate the command (sends Ctrl-C to the VM's console), but that does not guarantee that the command will stop -- a program that ignores Ctrl-C (like vim) will keep running.
+
+Whatever the command does runs as **root** in the guest.
+
+### `vm.write(data)`
+
+Send data directly into the VM console, lower level than `vm.exec`, allows sending any keyboard sequences including key presses like Ctrl-C ('\x03') or Enter ('\r').
+
+### `vm.resize(cols, rows)`
+
+Set the terminal console size. Mainly useful if you are writing your own terminal implementation.
+
+If you want to use a terminal with your VM, it's easier to connect xterm (see "Terminal" section below).
+
+### `vm.writeFile(path, data, { mode?, timeoutMs? })`
+
+Copies `data` (a `Blob` or `File`, bytes, or a string) into the VM as the file `path` (an absolute path). An existing file is replaced, a missing folder is created.
+
+- `mode` sets the permission bits, e.g. `0o755` for a script.
+- `timeoutMs` will terminate the operation if it doesn't complete within the specified time (for example, if the VM is very busy). Default is two minutes plus one second per MiB.
+
+The copy is kept in VM memory, so it has to fit there (`alpine` for example has 1 GiB). If you need to use a larger file, use `vm.mount` instead.
+
+**Files become part of the VM, so when a snapshot is taken those files will be present in the snapshot.**
+
+### `vm.readFile(path, { maxBytes?, timeoutMs? })` → `Blob`
+
+Copies a file out of the VM. The copy is kept in VM memory, so the file should fit there (default 1 GiB). If it doesn't, or the path is not a file but a directory, or doesn't exist, the read is refused with `read-failed`.
+
+Here's an example of how a file can be downloaded from the VM:
+
+```js
+const blob = await vm.readFile('/root/report.pdf');
+const a = document.createElement('a');
+a.href = URL.createObjectURL(blob);
+a.download = 'report.pdf';
+a.click();
+```
+
+### `vm.mount(files, path)` → `{ path, unmount() }`
+
+Mounts files in read-only mode into the VM. Files are not copied, so they do not consume memory. `path` is created if missing. `files` is a record of names to Blobs (`{ 'data.bin': blob }`), or a list of Files (`input.files` or `dataTransfer.files`).
+
+A path that is already mounted is refused with `invalid-input`: `unmount` it first, and wait for that to finish.
+
+**Mounts are not part of the VM and are not saved in snapshots.** After you boot a snapshot, mount again.
+
+### `vm.unmount(path)`
+
+Undoes a `mount`. If nothing is mounted at `path` it does nothing. While a program in the VM still uses the files, it rejects with `unmount-failed`.
+
+### `vm.snapshot({ name?, meta? })` → `SnapshotInfo`
+
+Saves the VM in browser storage (OPFS) and keeps it running. Use `meta` to store any extra info you'd like to add to the snapshot (any JSON up to 16 KiB); it is returned in `snapshots.list()`.
+
+### `vm.dispose()`
+
+Stops the VM and frees its workers.
+
+### `Arm64JS.snapshots.list()` / `.get(id)` / `.remove(id, { force? })`
+
+Lists stored snapshots, newest first: `{ id, name, created, base, engine, vcpus, sizeBytes, meta }`. `remove` is refused while a VM runs from that snapshot, unless `force` is specified.
+
+### `Arm64JS.storage.status()`
+
+Returns an object describing the current storage situation: `{ available, reason?, persistent?, quota?, usage?, snapshots, poolBytes }`.
+
+Storage can be unavailable when:
+
+1. a page is not a secure context
+2. a browser without OPFS
+3. in **frame mode when the browser blocks third-party storage** (for example in a private window).
+
+When storage is not available, `snapshot()` rejects with `storage-unavailable`.
+
+### `Arm64JS.engine()` → `'0.4'`
+
+The engine version the SDK has been built with. A VM booted from a snapshot can run on another version (based on the version that was running when the snapshot was made). Use `vm.engine` to check which.
+
+### `Arm64JS.shutdown()`
+
+Disposes every VM and, in frame mode, the frames.
+
+### Errors
+
+Everything rejects with an `Arm64JSError` carrying a `code`: `unsupported-browser`, `protocol-mismatch`, `engine-mismatch`, `image-not-found`, `boot-failed`, `exec-timeout`, `exec-failed`, `vm-exited`, `vm-lost`, `storage-unavailable`, `quota`, `snapshot-failed`, `snapshot-not-found`, `snapshot-in-use`, `snapshot-corrupt`, `invalid-input`, `share-unavailable`, `mount-failed`, `unmount-failed`, `write-failed`, `read-failed`.
+
+## Terminal (optional)
+
+A terminal is based on [xterm.js](https://xtermjs.org) and is not included by default; you need to install and wire it separately.
+
+```sh
+npm install @xterm/xterm @xterm/addon-fit
+```
+
+```js
+import { attachTerminal } from 'arm64js/terminal';
+import '@xterm/xterm/css/xterm.css';
+
+const term = attachTerminal(vm, document.getElementById('term'));
+// term.xterm is the xterm instance; term.dispose() removes it and leaves the VM running.
+```
+
+It shows the VM console, sends what is typed to the VM, and sizes itself to the element (pass `{ fit: false }` to keep a fixed size, and `{ xterm: { … } }` for xterm's own options). `vm.exec` runs on the same console but stays out of the terminal; keys pressed while a `vm.exec` command is running are sent once it finishes.
+
+## Networking
+
+The VM has an emulated network card, DNS, and can install Alpine packages with `apk` through the CDN's package mirror. It has no general internet access.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+`src/version.ts` and `protocol/dist/` are generated. `npm install` creates them; run `npm run stamp` again after changing the version in `package.json`.
+
+`protocol/` is the `@arm64js/protocol` package, which the engine uses too. To change it, bump its version and publish it (tag `protocol-v<version>`), update it in the engine and release the engine, then release this package.
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,32 @@
+import type { BootOptions } from '@arm64js/protocol';
+import { type Arm64JSDeps } from './runtime.js';
+export type { Arm64JSDeps } from './runtime.js';
+/**
+ * Build the API over a runtime. Tests pass `deps`; the package's own
+ * `Arm64JS` is one of these over the real page.
+ */
+export declare function createArm64JS(deps?: Arm64JSDeps): {
+    /** Boot a CDN image (`'alpine'`, `'alpine:2'`) or one of this browser's snapshots by id.
+     *  A snapshot boots on the engine it was saved on when this page's own cannot resume it. */
+    boot: (target: string, opts?: BootOptions) => Promise<import("./vm.js").Vm>;
+    /** `'inline'` when the VM runs in this page, `'frame'` when in the CDN's frame. */
+    mode: () => Promise<import("./hosts.js").HostMode>;
+    /** This page's engine, e.g. `'0.11'`. A VM booted from a snapshot may run on
+     *  another: see `vm.engine`. */
+    engine: () => Promise<string>;
+    snapshots: {
+        list: () => Promise<import("@arm64js/protocol").SnapshotInfo[]>;
+        get: (id: string) => Promise<import("@arm64js/protocol").SnapshotInfo | null>;
+        /** Delete a snapshot. Refused while a VM runs from it, unless `force`. */
+        remove: (id: string, opts?: {
+            force?: boolean;
+        }) => Promise<void>;
+    };
+    storage: {
+        status: () => Promise<import("@arm64js/protocol").StorageStatus>;
+    };
+    /** Dispose every VM and, in frame mode, the frame. */
+    shutdown: () => Promise<void>;
+    version: string;
+};
+export type Arm64JSApi = ReturnType<typeof createArm64JS>;

package/dist/api.js

@@ -0,0 +1,32 @@
+// The object a page calls: `Arm64JS.boot(...)`, `Arm64JS.snapshots.list()`.
+import { Runtime } from './runtime.js';
+import { VERSION } from './version.js';
+/**
+ * Build the API over a runtime. Tests pass `deps`; the package's own
+ * `Arm64JS` is one of these over the real page.
+ */
+export function createArm64JS(deps = {}) {
+    const rt = new Runtime(deps);
+    return {
+        /** Boot a CDN image (`'alpine'`, `'alpine:2'`) or one of this browser's snapshots by id.
+         *  A snapshot boots on the engine it was saved on when this page's own cannot resume it. */
+        boot: async (target, opts) => rt.boot(target, opts),
+        /** `'inline'` when the VM runs in this page, `'frame'` when in the CDN's frame. */
+        mode: async () => rt.mode(),
+        /** This page's engine, e.g. `'0.11'`. A VM booted from a snapshot may run on
+         *  another: see `vm.engine`. */
+        engine: async () => rt.engine(),
+        snapshots: {
+            list: async () => rt.listSnapshots(),
+            get: async (id) => rt.getSnapshot(id),
+            /** Delete a snapshot. Refused while a VM runs from it, unless `force`. */
+            remove: async (id, opts) => rt.removeSnapshot(id, opts),
+        },
+        storage: {
+            status: async () => rt.storageStatus(),
+        },
+        /** Dispose every VM and, in frame mode, the frame. */
+        shutdown: async () => rt.shutdown(),
+        version: VERSION,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+/** Await a host call, re-raising its failure as this package's error class. */
+export declare function withSdkErrors<T>(p: Promise<T>): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,24 @@
+// Errors raised by this package. Every host call a page can reach goes through
+// `withSdkErrors`, so a caller sees one `Arm64JSError` class whichever way the VM runs.
+import { Arm64JSError } from '@arm64js/protocol';
+/** Await a host call, re-raising its failure as this package's error class. */
+export async function withSdkErrors(p) {
+    return p.catch(rethrow);
+}
+/**
+ * Re-raise a host failure as this package's `Arm64JSError`.
+ *
+ * Inline, the rejection carries the CDN runtime's own copy of the class, so an
+ * `instanceof` against the copy this package exports would be false — while in
+ * frame mode, where `RpcClient` rebuilds it locally, it would be true.
+ */
+function rethrow(e) {
+    const code = e?.code;
+    if (e instanceof Arm64JSError) {
+        throw e;
+    }
+    if (code) {
+        throw new Arm64JSError(code, e.message, e.data);
+    }
+    throw new Arm64JSError('boot-failed', String(e?.message ?? e));
+}

package/dist/frame-host.d.ts

@@ -0,0 +1,30 @@
+import { type Host } from '@arm64js/protocol';
+import { RpcClient } from '@arm64js/protocol/rpc-client';
+/**
+ * How long the frame gets to say hello before the page gives up on it: a frame
+ * that never runs a script (blocked third-party frames, a network failure).
+ */
+export declare const FRAME_HANDSHAKE_TIMEOUT_MS = 8000;
+/** The message the developer sees when the browser cannot isolate the frame. */
+export declare const UNSUPPORTED_MESSAGE: string;
+/** Seams for tests: how the iframe is made and how messages arrive. */
+export interface FrameDeps {
+    document?: Pick<Document, 'createElement' | 'body'>;
+    view?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    setTimeout?: (cb: () => void, ms: number) => unknown;
+    clearTimeout?: (h: unknown) => void;
+    makeChannel?: () => {
+        port1: MessagePort;
+        port2: MessagePort;
+    };
+}
+export interface FrameHost {
+    host: Host;
+    client: RpcClient;
+    iframe: HTMLIFrameElement;
+    /** Fires once when the frame stops answering. */
+    onLost(cb: () => void): () => void;
+    dispose(): void;
+}
+/** Mount the frame for `frameUrl`, wait for its handshake, hand it a port. */
+export declare function mountFrameHost(url: string, deps?: FrameDeps): Promise<FrameHost>;

package/dist/frame-host.js

@@ -0,0 +1,89 @@
+// Frame mode: the runtime in a hidden iframe on the CDN, over a MessagePort.
+// The frame document carries Document-Isolation-Policy, so it is cross-origin
+// isolated whatever this page's headers say — the only way a page that cannot
+// set COOP/COEP gets a VM. Its handshake says whether that worked; a browser
+// without the header comes up unisolated and this reports
+// `unsupported-browser` rather than a VM that would never boot.
+import { Arm64JSError, FRAME_MESSAGE_KIND, FRAME_OP_CONNECT, PROTOCOL_VERSION, } from '@arm64js/protocol';
+import { RpcClient } from '@arm64js/protocol/rpc-client';
+/**
+ * How long the frame gets to say hello before the page gives up on it: a frame
+ * that never runs a script (blocked third-party frames, a network failure).
+ */
+export const FRAME_HANDSHAKE_TIMEOUT_MS = 8_000;
+/** The message the developer sees when the browser cannot isolate the frame. */
+export const UNSUPPORTED_MESSAGE = 'arm64js needs SharedArrayBuffer, and this browser cannot isolate the VM frame on its own ' +
+    '(Document-Isolation-Policy is Chrome/Edge 137+). To run here, serve your page with ' +
+    'Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp ' +
+    'so that crossOriginIsolated is true; the SDK then runs inline in every browser.';
+/** Mount the frame for `frameUrl`, wait for its handshake, hand it a port. */
+export async function mountFrameHost(url, deps = {}) {
+    const doc = deps.document ?? document;
+    const view = deps.view ?? window;
+    const later = deps.setTimeout ?? ((cb, ms) => setTimeout(cb, ms));
+    const cancel = deps.clearTimeout ?? ((h) => clearTimeout(h));
+    const origin = new URL(url).origin;
+    const iframe = doc.createElement('iframe');
+    iframe.src = url;
+    iframe.setAttribute('title', 'arm64js');
+    iframe.setAttribute('aria-hidden', 'true');
+    // In the layout and on screen, never display:none: a hidden frame's timers are
+    // throttled by the browser. The VM steps in workers, but the frame's main
+    // thread still relays.
+    iframe.style.cssText = 'position:fixed;bottom:0;right:0;width:1px;height:1px;border:0;opacity:0;pointer-events:none';
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (err, value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cancel(timer);
+            view.removeEventListener('message', onMessage);
+            if (err) {
+                iframe.remove();
+                reject(err);
+            }
+            else {
+                resolve(value);
+            }
+        };
+        const timer = later(() => finish(new Arm64JSError('unsupported-browser', `the VM frame did not answer within ${FRAME_HANDSHAKE_TIMEOUT_MS / 1000}s. ${UNSUPPORTED_MESSAGE}`)), FRAME_HANDSHAKE_TIMEOUT_MS);
+        const onMessage = (e) => {
+            // Only this frame, from the origin we loaded it from, saying the one thing
+            // we expect. Anything else on the page can post to this window.
+            if (e.source !== iframe.contentWindow) {
+                return;
+            }
+            if (e.origin !== origin) {
+                return;
+            }
+            const d = e.data;
+            if (!d || d.kind !== FRAME_MESSAGE_KIND || d.v !== 1 || typeof d.isolated !== 'boolean') {
+                return;
+            }
+            if (!d.isolated) {
+                return finish(new Arm64JSError('unsupported-browser', UNSUPPORTED_MESSAGE));
+            }
+            if (d.protocol !== PROTOCOL_VERSION) {
+                return finish(new Arm64JSError('protocol-mismatch', `this SDK speaks protocol ${PROTOCOL_VERSION} but engine ${String(d.engine)} speaks ${String(d.protocol)}; update the arm64js package`));
+            }
+            const { port1, port2 } = (deps.makeChannel ?? (() => new MessageChannel()))();
+            const connect = { kind: FRAME_MESSAGE_KIND, v: 1, op: FRAME_OP_CONNECT };
+            iframe.contentWindow?.postMessage(connect, origin, [port2]);
+            const client = new RpcClient(port1);
+            finish(null, {
+                host: client,
+                client,
+                iframe,
+                onLost: (cb) => client.onLost(cb),
+                dispose() {
+                    client.close();
+                    iframe.remove();
+                },
+            });
+        };
+        view.addEventListener('message', onMessage);
+        doc.body.appendChild(iframe);
+    });
+}

package/dist/hosts.d.ts

@@ -0,0 +1,27 @@
+import { type Host, type RuntimeModule } from '@arm64js/protocol';
+import { type FrameDeps } from './frame-host.js';
+/** `'inline'` when the VM runs in this page, `'frame'` when in the CDN's frame. */
+export type HostMode = 'inline' | 'frame';
+/** A runtime ready to boot VMs. */
+export interface LoadedHost {
+    host: Host;
+    mode: HostMode;
+    engine: string;
+    dispose(): void;
+}
+/** Seams for tests; a page never passes these. */
+export interface HostDeps {
+    isolated?: boolean;
+    importRuntime?: (url: string) => Promise<RuntimeModule>;
+    mountFrame?: (url: string) => Promise<{
+        host: Host;
+        onLost(cb: () => void): () => void;
+        dispose(): void;
+    }>;
+    frameDeps?: FrameDeps;
+}
+/**
+ * Load `engine` inline when this page is cross-origin isolated, in a frame
+ * otherwise. `onLost` fires if a frame stops answering.
+ */
+export declare function loadHost(engine: string, deps: HostDeps, onLost: () => void): Promise<LoadedHost>;

package/dist/hosts.js

@@ -0,0 +1,46 @@
+// Loads the runtime for one engine, in one of two ways. A cross-origin isolated
+// page imports it from the CDN and runs the VM itself. Any other page gets a
+// hidden CDN frame that runs it.
+import { Arm64JSError, PROTOCOL_VERSION } from '@arm64js/protocol';
+import { mountFrameHost } from './frame-host.js';
+import { frameUrl, runtimeModuleUrl } from './loader.js';
+/**
+ * Load `engine` inline when this page is cross-origin isolated, in a frame
+ * otherwise. `onLost` fires if a frame stops answering.
+ */
+export async function loadHost(engine, deps, onLost) {
+    const isolated = deps.isolated ?? Boolean(globalThis.crossOriginIsolated);
+    return isolated ? loadInlineHost(engine, deps) : loadFrameHost(engine, deps, onLost);
+}
+async function loadInlineHost(engine, deps) {
+    const importer = deps.importRuntime ??
+        (async (url) => import(/* @vite-ignore */ /* webpackIgnore: true */ url));
+    let mod;
+    try {
+        mod = await importer(runtimeModuleUrl(engine));
+    }
+    catch (e) {
+        throw new Arm64JSError('boot-failed', `could not load engine ${engine} from the CDN: ${String(e)}`);
+    }
+    if (mod.protocol !== PROTOCOL_VERSION) {
+        throw new Arm64JSError('protocol-mismatch', `this SDK speaks protocol ${PROTOCOL_VERSION} but engine ${engine} speaks ${String(mod.protocol)}; update the arm64js package`);
+    }
+    return { host: mod.createHost(), mode: 'inline', engine, dispose() { } };
+}
+async function loadFrameHost(engine, deps, onLost) {
+    const mounter = deps.mountFrame ?? (async (url) => mountFrameHost(url, deps.frameDeps));
+    const frame = await mounter(frameUrl(engine));
+    frame.onLost(() => {
+        // The next call builds a new frame. Tear this one down first: only its
+        // main thread stopped answering, and the workers behind it keep stepping
+        // a guest with no handle left.
+        onLost();
+        try {
+            frame.dispose();
+        }
+        catch {
+            // A frame already gone from the document has nothing to remove.
+        }
+    });
+    return { host: frame.host, mode: 'frame', engine, dispose: () => frame.dispose() };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { type Arm64JSApi } from './api.js';
+export type { Arm64JSApi } from './api.js';
+export type { HostMode } from './hosts.js';
+export type { MountSource } from './mount.js';
+export { VERSION as version } from './version.js';
+export { Vm, type FileData, type Mount } from './vm.js';
+export type { Arm64JSErrorCode, BootOptions, BootProgress, ExecOptions, ExecResult, OutputInfo, ReadFileOptions, SnapshotInfo, SnapshotOptions, StorageStatus, VmExit, WriteFileOptions, } from '@arm64js/protocol';
+export { Arm64JSError } from '@arm64js/protocol';
+export declare const Arm64JS: Arm64JSApi;
+export default Arm64JS;

package/dist/index.js

@@ -0,0 +1,6 @@
+import { createArm64JS } from './api.js';
+export { VERSION as version } from './version.js';
+export { Vm } from './vm.js';
+export { Arm64JSError } from '@arm64js/protocol';
+export const Arm64JS = createArm64JS();
+export default Arm64JS;

package/dist/loader.d.ts

@@ -0,0 +1,10 @@
+/** The engine this package runs: its own major.minor. */
+export declare function packageEngine(): string;
+/** `'0.11'` as `[0, 11]`, or `null` for anything that is not an exact engine tag. */
+export declare function engineParts(tag: string): [number, number] | null;
+/** Whether engine `a` is newer than engine `b`. False unless both are exact tags. */
+export declare function isNewerEngine(a: string, b: string): boolean;
+/** The immutable runtime directory for an exact `X.Y`, with its trailing slash. */
+export declare function runtimeDir(version: string): string;
+export declare function runtimeModuleUrl(version: string): string;
+export declare function frameUrl(version: string): string;