@crossbind/core-app-host 0.0.0-bootstrap.0 → 2.0.0-beta.65

package/cpp/src/windows/com.h

@@ -0,0 +1,57 @@
+#pragma once
+
+// What the Windows host needs of COM without WRL's implementations, which llvm-mingw lacks: WebView2's events as
+// functions, its UTF-16 strings, and the UI thread.
+#include <windows.h>
+
+#include "WebView2.h"
+
+#include <atomic>
+#include <functional>
+#include <string>
+#include <utility>
+
+namespace crossbind::windows {
+
+// One WebView2 event or completion as a function.
+template <typename Interface, typename... Args>
+class Handler final : public Interface {
+public:
+    Handler(REFIID iid, std::function<HRESULT(Args...)> fn) : iid_(iid), fn_(std::move(fn)) {}
+
+    ULONG STDMETHODCALLTYPE AddRef() override { return ++refs_; }
+    ULONG STDMETHODCALLTYPE Release() override {
+        const ULONG left = --refs_;
+        if (left == 0) delete this;
+        return left;
+    }
+    HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void **out) override {
+        if (!out) return E_POINTER;
+        if (!IsEqualIID(riid, IID_IUnknown) && !IsEqualIID(riid, iid_)) {
+            *out = nullptr;
+            return E_NOINTERFACE;
+        }
+        *out = static_cast<Interface *>(this);
+        AddRef();
+        return S_OK;
+    }
+    HRESULT STDMETHODCALLTYPE Invoke(Args... args) override { return fn_(args...); }
+
+private:
+    std::atomic<ULONG> refs_{1};
+    IID iid_;
+    std::function<HRESULT(Args...)> fn_;
+};
+
+std::wstring wide(const std::string &text);
+std::string utf8(const wchar_t *text);
+// A string WebView2 hands out, which the caller owns.
+std::string take(LPWSTR text);
+// A copy WebView2 takes ownership of.
+LPWSTR give(const std::wstring &text);
+// The webview of the controller main() gets from webview.
+ICoreWebView2 *coreWebView(void *controller);
+// Runs fn on the UI thread: at once when the caller is on it, else when the thread's message loop gets to it.
+void onMainThread(std::function<void()> fn);
+
+}  // namespace crossbind::windows

package/cpp/src/windows/navigation.cpp

@@ -0,0 +1,90 @@
+#include "platform.h"
+#include "windows/com.h"
+
+#include <shellapi.h>
+
+#include <algorithm>
+
+using namespace crossbind::windows;
+
+// A page from another origin in any frame would reach the module's channel and its crossbind:// routes, so the webview
+// never loads one. A link the user follows to such a page opens in the default browser instead, and no page opens a
+// window of the app's own.
+namespace {
+
+struct Lock {
+    std::vector<std::string> origins;
+    std::function<void()> newPage;
+};
+
+std::string originOf(const std::string &uri) {
+    const auto scheme = uri.find("://");
+    if (scheme == std::string::npos) return uri;
+    return uri.substr(0, uri.find_first_of("/?#", scheme + 3));
+}
+
+bool allows(const Lock &lock, const std::string &uri) {
+    if (uri.rfind("about:", 0) == 0) return true;
+    // A blob URL carries the origin of the page that made it.
+    if (uri.rfind("blob:", 0) == 0) return allows(lock, uri.substr(5));
+    return std::find(lock.origins.begin(), lock.origins.end(), originOf(uri)) != lock.origins.end();
+}
+
+void openOutside(const std::string &uri) {
+    const std::string scheme = uri.substr(0, uri.find(':'));
+    if (scheme != "http" && scheme != "https" && scheme != "mailto") return;
+    // The URL goes into the command line of its scheme's handler, where a quote or a space would split it.
+    if (std::any_of(uri.begin(), uri.end(), [](unsigned char c) { return c <= ' ' || c == '"' || c == 0x7f; })) return;
+    ShellExecuteW(nullptr, L"open", wide(uri).c_str(), nullptr, nullptr, SW_SHOWNORMAL);
+}
+
+using Starting = Handler<ICoreWebView2NavigationStartingEventHandler, ICoreWebView2 *, ICoreWebView2NavigationStartingEventArgs *>;
+
+Starting *decide(Lock *lock) {
+    return new Starting(IID_ICoreWebView2NavigationStartingEventHandler,
+        [lock](ICoreWebView2 *, ICoreWebView2NavigationStartingEventArgs *args) -> HRESULT {
+            LPWSTR requested = nullptr;
+            args->get_Uri(&requested);
+            const std::string uri = take(requested);
+            if (allows(*lock, uri)) return S_OK;
+            BOOL followed = FALSE;
+            args->get_IsUserInitiated(&followed);
+            if (followed) openOutside(uri);
+            args->put_Cancel(TRUE);
+            return S_OK;
+        });
+}
+
+}  // namespace
+
+void restrictNavigation(void *webView, std::vector<std::string> origins, std::function<void()> newPage) {
+    ICoreWebView2 *core = coreWebView(webView);
+    auto *lock = new Lock{std::move(origins), std::move(newPage)};
+    EventRegistrationToken token;
+    Starting *top = decide(lock);
+    core->add_NavigationStarting(top, &token);
+    top->Release();
+    Starting *frames = decide(lock);
+    core->add_FrameNavigationStarting(frames, &token);
+    frames->Release();
+    auto *windows = new Handler<ICoreWebView2NewWindowRequestedEventHandler, ICoreWebView2 *, ICoreWebView2NewWindowRequestedEventArgs *>(
+        IID_ICoreWebView2NewWindowRequestedEventHandler, [](ICoreWebView2 *, ICoreWebView2NewWindowRequestedEventArgs *args) -> HRESULT {
+            LPWSTR requested = nullptr;
+            args->get_Uri(&requested);
+            const std::string uri = take(requested);
+            BOOL followed = FALSE;
+            args->get_IsUserInitiated(&followed);
+            if (followed) openOutside(uri);
+            args->put_Handled(TRUE);
+            return S_OK;
+        });
+    core->add_NewWindowRequested(windows, &token);
+    windows->Release();
+    auto *loading = new Handler<ICoreWebView2ContentLoadingEventHandler, ICoreWebView2 *, ICoreWebView2ContentLoadingEventArgs *>(
+        IID_ICoreWebView2ContentLoadingEventHandler, [lock](ICoreWebView2 *, ICoreWebView2ContentLoadingEventArgs *) -> HRESULT {
+            lock->newPage();
+            return S_OK;
+        });
+    core->add_ContentLoading(loading, &token);
+    loading->Release();
+}

package/js/codec.js

@@ -0,0 +1,123 @@
+// Tagged JSON for the webview channel: the values structured clone carries and JSON does not.
+const TAG = '\u0001t';
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_INDEX = new Uint8Array(128);
+for (let i = 0; i < 64; i += 1) B64_INDEX[B64.charCodeAt(i)] = i;
+
+const VIEWS = {
+    Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array,
+    Float32Array, Float64Array, BigInt64Array, BigUint64Array, DataView,
+};
+
+// The engine's own base64 where it has one (the page), the host's where it does not (Hermes, which interprets JS).
+export function toBase64(bytes) {
+    if (typeof bytes.toBase64 === 'function') return bytes.toBase64();
+    if (typeof globalThis.__host_b64encode === 'function') return globalThis.__host_b64encode(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const parts = [];
+    const CHUNK = 3 * 4096;
+    for (let start = 0; start < bytes.length; start += CHUNK) {
+        const end = Math.min(start + CHUNK, bytes.length);
+        let out = '';
+        let i = start;
+        for (; i + 2 < end; i += 3) {
+            const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+            out += B64[n >> 18] + B64[(n >> 12) & 63] + B64[(n >> 6) & 63] + B64[n & 63];
+        }
+        if (i < end) {
+            const n = (bytes[i] << 16) | ((i + 1 < end ? bytes[i + 1] : 0) << 8);
+            out += B64[n >> 18] + B64[(n >> 12) & 63] + (i + 1 < end ? B64[(n >> 6) & 63] : '=') + '=';
+        }
+        parts.push(out);
+    }
+    return parts.join('');
+}
+
+export function fromBase64(text) {
+    if (typeof Uint8Array.fromBase64 === 'function') return Uint8Array.fromBase64(text);
+    if (typeof globalThis.__host_b64decode === 'function') return new Uint8Array(globalThis.__host_b64decode(text));
+    const padding = text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0;
+    const length = (text.length / 4) * 3 - padding;
+    const bytes = new Uint8Array(length);
+    let o = 0;
+    for (let i = 0; i < text.length; i += 4) {
+        const n = (B64_INDEX[text.charCodeAt(i)] << 18) | (B64_INDEX[text.charCodeAt(i + 1)] << 12)
+            | (B64_INDEX[text.charCodeAt(i + 2)] << 6) | B64_INDEX[text.charCodeAt(i + 3)];
+        if (o < length) bytes[o++] = n >> 16;
+        if (o < length) bytes[o++] = (n >> 8) & 255;
+        if (o < length) bytes[o++] = n & 255;
+    }
+    return bytes;
+}
+
+export const CODEC_TAG = TAG;
+
+// `hook` sees every value first and may replace it with a tagged one of its own: a handle, an enum, an attachment.
+export function pack(value, hook) {
+    if (hook) {
+        const replaced = hook(value);
+        if (replaced !== undefined) return replaced;
+    }
+    const next = (item) => pack(item, hook);
+    switch (typeof value) {
+    case 'undefined': return { [TAG]: 'u' };
+    case 'bigint': return { [TAG]: 'b', v: value.toString() };
+    case 'number':
+        if (Number.isNaN(value)) return { [TAG]: 'n', v: 'NaN' };
+        if (!Number.isFinite(value)) return { [TAG]: 'n', v: value > 0 ? 'Infinity' : '-Infinity' };
+        if (Object.is(value, -0)) return { [TAG]: 'n', v: '-0' };
+        return value;
+    case 'object': {
+        if (value === null) return null;
+        if (Array.isArray(value)) return value.map(next);
+        if (value instanceof Set) return { [TAG]: 'set', v: [...value].map(next) };
+        if (value instanceof Map) return { [TAG]: 'map', v: [...value].map(([key, item]) => [next(key), next(item)]) };
+        if (value instanceof Date) return { [TAG]: 'date', v: value.getTime() };
+        if (value instanceof ArrayBuffer) return { [TAG]: 'ab', v: toBase64(new Uint8Array(value)) };
+        if (ArrayBuffer.isView(value)) {
+            const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+            return { [TAG]: 'view', k: value.constructor.name, v: toBase64(bytes) };
+        }
+        const out = {};
+        for (const key of Object.keys(value)) out[key] = next(value[key]);
+        return out;
+    }
+    // As structured clone does, which is what a worker-backed web build gives the same values.
+    case 'function':
+    case 'symbol': {
+        const error = new Error(`${String(value)} could not be cloned`);
+        error.name = 'DataCloneError';
+        throw error;
+    }
+    default: return value;
+    }
+}
+
+// `hook` turns the tags it owns back into values; it returns undefined for the codec's own tags.
+export function unpack(value, hook) {
+    if (value === null || typeof value !== 'object') return value;
+    const next = (item) => unpack(item, hook);
+    if (Array.isArray(value)) return value.map(next);
+    const tag = value[TAG];
+    if (tag !== undefined) {
+        if (hook) {
+            const replaced = hook(tag, value);
+            if (replaced !== undefined) return replaced;
+        }
+        if (tag === 'u') return undefined;
+        if (tag === 'b') return BigInt(value.v);
+        if (tag === 'n') return value.v === '-0' ? -0 : Number(value.v);
+        if (tag === 'set') return new Set(value.v.map(next));
+        if (tag === 'map') return new Map(value.v.map(([key, item]) => [next(key), next(item)]));
+        if (tag === 'date') return new Date(value.v);
+        if (tag === 'ab') return fromBase64(value.v).buffer;
+        if (tag === 'view') {
+            const bytes = fromBase64(value.v);
+            const View = VIEWS[value.k] ?? Uint8Array;
+            if (View === DataView) return new DataView(bytes.buffer);
+            return new View(bytes.buffer, 0, bytes.byteLength / (View.BYTES_PER_ELEMENT ?? 1));
+        }
+    }
+    const out = {};
+    for (const key of Object.keys(value)) out[key] = next(value[key]);
+    return out;
+}

package/js/host.js

@@ -0,0 +1,8 @@
+// What runs in Hermes: the embind runtime holding the project's bindings, and the side of the lean protocol that
+// answers the page. The host calls __crossbind_start once every binding is registered.
+import './polyfills.js';
+import Module from '@crossbind/core-embind-jsi';
+import systemConfig from 'crossbind/systemConfig';
+import { installHost } from './lean-host.js';
+
+globalThis.__crossbind_start = () => installHost(Module, systemConfig.env);

package/js/lean-client.js

@@ -0,0 +1,147 @@
+// The lean protocol's page side: the awaitable module a worker-backed web build hands out, over one message per call.
+// Byte arrays from transport.attachBytes up travel as attachments of a frame, a large result comes back on its own, and
+// a frame waits for the messages sent before it, so order holds where the two take different channels.
+import { pack, unpack, CODEC_TAG as TAG } from './codec.js';
+
+const FUNCTION = Symbol('remote function');
+const LOCAL_MEMBERS = {
+    toJSON: () => ({}),
+    [Symbol.toPrimitive]: (hint) => (hint === 'number' ? NaN : '[object Object]'),
+};
+
+function concatenate(views) {
+    const total = views.reduce((sum, view) => sum + view.byteLength, 0);
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const view of views) {
+        body.set(new Uint8Array(view.buffer, view.byteOffset, view.byteLength), offset);
+        offset += view.byteLength;
+    }
+    return body;
+}
+
+function createSession(transport) {
+    const handleIds = new WeakMap();
+    const tokens = new Map();
+    const tokenIds = new WeakMap();
+
+    const pendingRelease = [];
+    const collector = typeof FinalizationRegistry === 'function' ? new FinalizationRegistry((id) => {
+        pendingRelease.push(id);
+        if (pendingRelease.length > 1) return;
+        setTimeout(() => {
+            send(['release', 0, [], [pendingRelease.splice(0)]]).catch(() => {});
+        }, 0);
+    }) : null;
+
+    // Messages wait for a request in flight, and a request for the messages sent before it.
+    const inflight = new Set();
+    let gate = Promise.resolve();
+    const track = (promise) => {
+        inflight.add(promise);
+        promise.then(() => inflight.delete(promise), () => inflight.delete(promise));
+        return promise;
+    };
+    function send(message) {
+        const text = transport.token + JSON.stringify(message);
+        return track(gate.then(() => transport.send(text)));
+    }
+    function sendWithAttachments(message, attachments) {
+        const query = `m=${encodeURIComponent(JSON.stringify([...message, attachments.map((view) => [view.constructor.name, view.byteLength])]))}`;
+        const body = concatenate(attachments);
+        const done = Promise.allSettled([...inflight]).then(() => transport.frame(`${query}&t=${transport.token}`, body));
+        gate = done.then(() => undefined, () => undefined);
+        return track(done);
+    }
+
+    function tokenFor(id, value) {
+        let token = tokens.get(id);
+        if (!token) {
+            token = Object.freeze({ __embindEnumRef: id, value });
+            tokens.set(id, token);
+            tokenIds.set(token, id);
+        }
+        return token;
+    }
+
+    function handleFor(id) {
+        const handle = remote(id, []);
+        handleIds.set(handle, id);
+        collector?.register(handle, id);
+        return handle;
+    }
+
+    function encodeArgs(args, attachments) {
+        return pack(args, (value) => {
+            if (typeof value === 'function') {
+                if (handleIds.has(value)) return { [TAG]: 'h', v: handleIds.get(value) };
+                const error = new Error('A function cannot be passed to the native module');
+                error.name = 'DataCloneError';
+                throw error;
+            }
+            if (value !== null && typeof value === 'object' && tokenIds.has(value)) return { [TAG]: 'e', v: tokenIds.get(value) };
+            if (ArrayBuffer.isView(value) && value.byteLength >= transport.attachBytes) {
+                attachments.push(value);
+                return { [TAG]: 'att', i: attachments.length - 1 };
+            }
+            return undefined;
+        });
+    }
+
+    async function decodeReply(text) {
+        const [failed, value] = JSON.parse(text);
+        if (failed) throw Object.assign(new Error(value.message), value);
+        if (value !== null && typeof value === 'object' && value[TAG] === 'big') {
+            const bytes = await transport.result(`id=${value.v}&t=${transport.token}`);
+            const View = globalThis[value.k] ?? Uint8Array;
+            return new View(bytes, 0, bytes.byteLength / (View.BYTES_PER_ELEMENT ?? 1));
+        }
+        return unpack(value, (tag, item) => {
+            if (tag === 'h') return handleFor(item.v);
+            if (tag === 'e') return tokenFor(item.v, item.n);
+            if (tag === 'fn') return FUNCTION;
+            return undefined;
+        });
+    }
+
+    async function request(op, target, path, args) {
+        const attachments = [];
+        const message = [op, target, path, encodeArgs(args, attachments)];
+        const reply = await (attachments.length ? sendWithAttachments(message, attachments) : send(message));
+        const value = await decodeReply(reply);
+        return value === FUNCTION ? remote(target, path, true) : value;
+    }
+
+    // A path from the module or an object: awaiting it reads the value, calling or constructing it runs on the host.
+    // A function read that way is no longer awaitable, or awaiting it would read it again and again.
+    function remote(target, path, isRead = false) {
+        return new Proxy(function remoteMember() {}, {
+            get(_, prop) {
+                if (prop === 'then') {
+                    if (path.length === 0 || isRead) return undefined;
+                    return (resolve, reject) => request('get', target, path, []).then(resolve, reject);
+                }
+                if (Object.hasOwn(LOCAL_MEMBERS, prop)) return LOCAL_MEMBERS[prop];
+                if (typeof prop === 'symbol') return undefined;
+                return remote(target, [...path, prop]);
+            },
+            set(_, prop, value) {
+                request('set', target, [...path, prop], [value]).catch(() => {});
+                return true;
+            },
+            apply: (_, thisArg, args) => request('call', target, path, args),
+            construct: (_, args) => request('new', target, path, args),
+        });
+    }
+
+    return { request, module: remote(0, []) };
+}
+
+// transport: { send(text) → Promise<reply text>; frame(query, body) → Promise<reply text>, a message whose byte arrays
+// are the body; result(query) → Promise<ArrayBuffer>, a large result; attachBytes; token: what the host gave the page,
+// which every message, frame and result request carries }. A frame or result the host refuses rejects with its answer.
+export async function connect(transport, env) {
+    const session = createSession(transport);
+    if (env && Object.keys(env).length > 0) await session.request('env', 0, [], [env]);
+    return session.module;
+}

package/js/lean-host.js

@@ -0,0 +1,237 @@
+// The lean protocol's host side, with the contract a worker-backed web build has: objects as handles the page releases,
+// enum values with their identity, vectors returned as arrays, plain arrays coerced into vector parameters, errors
+// with their own fields, and large byte arrays as attachments of a crossbind:// request.
+/* global __host_reply */
+import { pack, unpack, CODEC_TAG as TAG } from './codec.js';
+import { setCoercionModule, unwrapCoercionProxy, wrapWithVectorCoercion } from 'crossbind/runtime/adapters/vector-coercion.js';
+import { UNBOUND_MESSAGE } from 'crossbind/runtime/adapters/unboundMessage.js';
+
+// Results holding a typed array at least this large go back as a crossbind:// response body.
+const BIG_RESULT_BYTES = 4096;
+
+const registry = new Map();
+const holders = new WeakMap();
+let nextHandle = 1;
+
+const enumValues = new WeakSet();
+const enumIds = new WeakMap();
+const enumsById = new Map();
+let nextEnum = 1;
+
+const bigResults = new Map();
+let nextBig = 1;
+
+let module = null;
+let root = null;
+
+const isEmbindObject = (value) => typeof value.delete === 'function' && typeof value.isDeleted === 'function';
+const isVector = (value) => isEmbindObject(value) && typeof value.size === 'function' && typeof value.get === 'function';
+// What JavaScript owns, as the worker adapter decides it: a smart pointer or a copy embind marked as owned.
+const ownsObject = (value) => Boolean(value.$$ && (value.$$.smartPtr || value.$$.count?.owned));
+
+// The module's own objects, its globals above all, live as long as the module, so letting go of a handle to one
+// frees nothing.
+const moduleObjects = new WeakSet();
+
+function freeIfOwned(value) {
+    if (ownsObject(value) && !moduleObjects.has(value) && !value.isDeleted()) value.delete();
+}
+
+function register(value) {
+    const id = nextHandle;
+    nextHandle += 1;
+    registry.set(id, value);
+    holders.set(value, (holders.get(value) ?? 0) + 1);
+    return id;
+}
+
+function release(ids) {
+    for (const id of ids) {
+        const value = registry.get(id);
+        if (!registry.delete(id)) continue;
+        const left = holders.get(value) - 1;
+        if (left > 0) {
+            holders.set(value, left);
+        } else {
+            holders.delete(value);
+            freeIfOwned(value);
+        }
+    }
+}
+
+// embind hangs enum values off the enum type; an instance with a numeric value and no lifecycle methods is one.
+function collectEnums() {
+    for (const key of Object.keys(module)) {
+        const holder = module[key];
+        if (holder == null || (typeof holder !== 'object' && typeof holder !== 'function') || ArrayBuffer.isView(holder)) continue;
+        for (const value of Object.values(holder)) {
+            if (value != null && typeof value === 'object' && typeof value.value === 'number'
+                && typeof value.delete !== 'function' && value.constructor && value.constructor !== Object) {
+                enumValues.add(value);
+            }
+        }
+    }
+}
+
+function enumIdOf(value) {
+    let id = enumIds.get(value);
+    if (!id) {
+        id = nextEnum;
+        nextEnum += 1;
+        enumIds.set(value, id);
+        enumsById.set(id, value);
+    }
+    return id;
+}
+
+// The build's env never replaces a variable the process already has; values the page passes to initNative() do.
+function setEnv(env, overwrite) {
+    const dataPath = module.Crossbind.getEnv('CROSSBIND_DATA_PATH');
+    for (const [key, value] of Object.entries(env)) {
+        module.Crossbind.setEnv(key, String(value).replace('_CROSSBIND_DATA_PATH_', dataPath), overwrite);
+    }
+}
+
+function encode(value) {
+    return pack(value, (item) => {
+        if (typeof item === 'function') return { [TAG]: 'fn' };
+        if (item === null || typeof item !== 'object' || ArrayBuffer.isView(item)) return undefined;
+        const raw = unwrapCoercionProxy(item);
+        if (enumValues.has(raw)) return { [TAG]: 'e', v: enumIdOf(raw), n: raw.value };
+        if (isVector(raw)) {
+            const elements = [];
+            for (let i = 0; i < raw.size(); i += 1) elements.push(encode(raw.get(i)));
+            freeIfOwned(raw);
+            return elements;
+        }
+        if (isEmbindObject(raw)) return { [TAG]: 'h', v: register(raw) };
+        return undefined;
+    });
+}
+
+function decode(value, attachments) {
+    return unpack(value, (tag, item) => {
+        if (tag === 'h') {
+            if (!registry.has(item.v)) throw new Error(`crossbind: object ${item.v} was already released`);
+            return registry.get(item.v);
+        }
+        if (tag === 'e') return enumsById.get(item.v);
+        if (tag === 'att') return attachments[item.i];
+        return undefined;
+    });
+}
+
+function encodeResult(op, value) {
+    // What JavaScript constructs stays an object, a vector too, as the worker adapter hands out what `new` makes.
+    if (op === 'new' && value !== null && typeof value === 'object' && isEmbindObject(unwrapCoercionProxy(value))) {
+        return { [TAG]: 'h', v: register(unwrapCoercionProxy(value)) };
+    }
+    if (ArrayBuffer.isView(value) && value.byteLength >= BIG_RESULT_BYTES) {
+        const id = nextBig;
+        nextBig += 1;
+        bigResults.set(id, value);
+        return { [TAG]: 'big', v: id, k: value.constructor.name };
+    }
+    return encode(value);
+}
+
+function encodeError(error) {
+    const fields = { name: error?.name ?? 'Error', message: String(error?.message ?? error) };
+    if (error !== null && typeof error === 'object') {
+        for (const key of Object.keys(error)) {
+            const item = error[key];
+            if (item === null || ['string', 'number', 'boolean'].includes(typeof item)) fields[key] = item;
+        }
+    }
+    return fields;
+}
+
+// An operation on a path from the module, or from an object the page holds a handle to.
+function dispatch(op, target, path, args) {
+    if (op === 'release') {
+        release(args[0]);
+        return null;
+    }
+    if (op === 'env') {
+        setEnv(args[0], true);
+        return null;
+    }
+    const base = target === 0 ? root : wrapWithVectorCoercion(registry.get(target));
+    if (base === undefined) throw new Error(`crossbind: object ${target} was already released`);
+    const parent = path.slice(0, -1).reduce((object, key) => object[key], base);
+    const key = path[path.length - 1];
+    if (op === 'get') return path.length === 0 ? base : parent[key];
+    if (op === 'set') {
+        parent[key] = args[0];
+        return true;
+    }
+    const member = parent[key];
+    if (typeof member !== 'function') throw new Error(`crossbind: ${path.join('.')} ${UNBOUND_MESSAGE}`);
+    if (op === 'new') return new member(...args);
+    return member.apply(parent, args);
+}
+
+function answer(message, attachments) {
+    const [op, target, path, args] = message;
+    try {
+        return JSON.stringify([0, encodeResult(op, dispatch(op, target, path, decode(args, attachments)))]);
+    } catch (error) {
+        return JSON.stringify([1, encodeError(error)]);
+    }
+}
+
+function viewOf(kind, buffer, offset, length) {
+    const View = globalThis[kind] ?? Uint8Array;
+    const bytes = new Uint8Array(buffer, offset, length);
+    if (View === Uint8Array) return bytes;
+    const copy = bytes.slice();
+    return new View(copy.buffer, 0, length / (View.BYTES_PER_ELEMENT ?? 1));
+}
+
+function parseQuery(query) {
+    const params = {};
+    for (const part of query.split('&')) {
+        const at = part.indexOf('=');
+        params[decodeURIComponent(at < 0 ? part : part.slice(0, at))] = at < 0 ? '' : decodeURIComponent(part.slice(at + 1));
+    }
+    return params;
+}
+
+export function installHost(embindModule, env) {
+    module = embindModule;
+    // A plain array passed for a vector parameter becomes one of the module's vector classes.
+    setCoercionModule(module);
+    root = wrapWithVectorCoercion(module);
+    collectEnums();
+    for (const value of Object.values(module)) {
+        if (value !== null && typeof value === 'object' && isEmbindObject(value)) moduleObjects.add(value);
+    }
+    setEnv(env, false);
+
+    globalThis.__crossbind_receive = (call, text) => __host_reply(call, answer(JSON.parse(text), []));
+
+    // A new page replaced the one that held these, and its garbage collector will never release them.
+    globalThis.__crossbind_reset = () => {
+        release([...registry.keys()]);
+        bigResults.clear();
+    };
+
+    // A message in the query, its attachments one after another in the body.
+    globalThis.__crossbind_frame = (query, buffer) => {
+        const message = JSON.parse(parseQuery(query).m);
+        const attachments = [];
+        let offset = 0;
+        for (const [kind, length] of message[4]) {
+            attachments.push(viewOf(kind, buffer, offset, length));
+            offset += length;
+        }
+        return answer(message, attachments);
+    };
+
+    globalThis.__crossbind_result = (query) => {
+        const id = Number(parseQuery(query).id);
+        const value = bigResults.get(id);
+        bigResults.delete(id);
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    };
+}