@swmansion/popcorn 0.4.0-next.4 → 0.4.0-next.6

package/README.md

@@ -4,7 +4,7 @@ Run Elixir in a browser with OTP/BEAM compiled to WebAssembly.
 This prerelease replaces the AtomVM runtime used by Popcorn 0.3.x.
 
 Start with the
-[versioned Popcorn guide](https://popcorn.hexdocs.pm/0.4.0-next.4/introduction.html).
+[versioned Popcorn guide](https://popcorn.hexdocs.pm/0.4.0-next.6/introduction.html).
 It includes a complete Mix and Vite tutorial.
 
 ## Install
@@ -13,12 +13,12 @@ It includes a complete Mix and Vite tutorial.
 npm install @swmansion/popcorn@next
 ```
 
-Add `{:popcorn, "0.4.0-next.4"}` to your Elixir application's dependencies.
+Add `{:popcorn, "0.4.0-next.6"}` to your Elixir application's dependencies.
 Run `mix deps.get` before building the JavaScript application. The bundler
 plugins invoke Mix locally to compile and package application and
 standard-library code.
 
-Use the toolchain pinned in [mise.toml](https://github.com/software-mansion/popcorn/blob/v0.4.0-next.4/mise.toml).
+Use the toolchain pinned in [mise.toml](https://github.com/software-mansion/popcorn/blob/v0.4.0-next.6/mise.toml).
 The packager checks host OTP compatibility against the selected runtime's manifest.
 
 ## Configure Vite
@@ -37,8 +37,20 @@ export default defineConfig({
 ```
 
 Set `rootDir` to the Mix project directory. The current Mix application is the
-default entrypoint. Set `app` to select another OTP application explicitly.
-Use `app: null` to package the base runtime without starting an application.
+default entrypoint. Configure cooking in the Mix project's `config/config.exs`:
+
+```elixir
+import Config
+
+config :popcorn,
+  extra_apps: [:eex],
+  treeshake: [preserved_apps: [:eex]]
+```
+
+Set `app: :other_app` to select another OTP application, or `app: nil` to
+package the base runtime without starting an application. Cooking settings
+belong exclusively to Elixir config; the JS plugins accept only `rootDir`.
+See `mix help popcorn.cook` for all settings.
 
 The npm package contains two variants:
 
@@ -47,8 +59,8 @@ The npm package contains two variants:
 
 The plugin emits only the selected variant. The browser does not download both.
 Both variants share one JavaScript API and one Hex package.
-The plugin selects `crypto` when the application's dependencies or `extraApps` require it; otherwise it selects `core`.
-Set `runtimeVariant: "core"` or `runtimeVariant: "crypto"` to override this choice.
+The cook task selects `crypto` when the application's dependencies or configured `extra_apps` require it; otherwise it selects `core`.
+Set `runtime_variant: :core` or `runtime_variant: :crypto` in Elixir config to override this choice.
 An explicit `"core"` selection produces a build error if the application requires crypto.
 
 Rollup and esbuild plugins accept the same options through `@swmansion/popcorn/rollup` and `@swmansion/popcorn/esbuild`.
@@ -59,18 +71,18 @@ Use ESM output with those bundlers.
 ```ts
 import { Popcorn } from "@swmansion/popcorn";
 
-const result = await Popcorn.init();
-if (!result.ok) throw result.error;
-
-const vm = result.data;
+const vm = await Popcorn.init();
 // Stop the runtime when the application no longer needs it.
 vm.deinit();
 ```
 
 `Popcorn.init()` waits for the OTP application tree to start. Use
-`popcorn.genserver.call()` to call a supervised GenServer from JavaScript.
+`popcorn.call()` to call a supervised GenServer from JavaScript.
 Use `popcorn.onEvent()` to receive events from BEAM processes.
 
+Methods throw or reject on failure. Only `send`, `call`, and `cast` also have
+`trySend`, `tryCall`, and `tryCast` variants that return `Result` objects.
+
 Each VM starts with 64 MiB of Wasm linear memory and can grow to 256 MiB on
 phones/tablets or 2 GiB on desktop. Device detection uses the browser's user
 agent and touch support. Configure the limits with
@@ -91,7 +103,7 @@ Cross-Origin-Embedder-Policy: require-corp
 
 Vite sets these headers for development and preview. Configure your production server separately.
 Serve `.wasm` as `application/wasm`. Serve compressed `.tar.gz` files with `Content-Encoding: gzip` for `.tar` requests.
-The package also emits uncompressed tar files and Brotli variants. Brotli uses standard effort by default. Set `brotliEffort: "max"` for maximum compression in release builds.
+The package also emits uncompressed tar files and Brotli variants. Brotli uses standard effort by default. Set `config :popcorn, brotli_effort: :max` in `config/config.exs` for maximum compression in release builds.
 
 The JavaScript bridge currently requires a Content Security Policy that permits `unsafe-eval`.
-See the [versioned Elixir API](https://popcorn.hexdocs.pm/0.4.0-next.4/) for interoperability details.
+See the [versioned Elixir API](https://popcorn.hexdocs.pm/0.4.0-next.6/) for interoperability details.

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 /**
  * An operation result. Check `ok` before accessing `data` or `error`.
- * Expected failures use the error branch. Invalid usage can still throw.
+ * Expected failures from `try*` methods use the error branch. Invalid usage can still throw.
  */
 export type Result<T, E extends Tag = Tag> = {
     ok: true;
@@ -99,4 +99,5 @@ export declare class PopcornError<T extends Tag = Tag> extends Error {
     static deserialize(value: unknown): PopcornError;
 }
 export declare function isUnserializableReason(value: unknown): value is UnserializableReason;
+export declare function unwrap<T>(result: Result<T>): T;
 export {};

package/dist/index.mjs

@@ -172,6 +172,11 @@ function check$1(ok, msg) {
         throw err$1("internal:check", { detail: msg });
     }
 }
+function unwrap(result) {
+    if (!result.ok)
+        throw result.error;
+    return result.data;
+}
 
 function base64ToBytes(b64) {
     const binary = atob(b64);
@@ -191,7 +196,7 @@ function unreachable() {
 function objectWithKeys(value, keys) {
     if (value === null || typeof value !== "object")
         return null;
-    if (value.constructor !== Object)
+    if (Object.getPrototypeOf(value) !== Object.prototype)
         return null;
     const hasAllKeys = keys.every((k) => Object.hasOwn(value, k));
     if (!hasAllKeys)
@@ -208,7 +213,9 @@ const LARGE_TUPLE_EXT = 0x69;
 const NIL_EXT = 0x6a;
 const LIST_EXT = 0x6c;
 const BINARY_EXT = 0x6d;
+const BINARY_HEADER_SIZE = 1 + 4;
 const SMALL_BIG_EXT = 0x6e;
+const LARGE_BIG_EXT = 0x6f;
 const MAP_EXT = 0x74;
 const ATOM_UTF8_EXT = 0x76;
 const SMALL_ATOM_UTF8_EXT = 0x77;
@@ -309,6 +316,16 @@ class Encoder {
             case "number":
                 this.number(value);
                 return;
+            case "bigint":
+                this.integer(value);
+                return;
+            case "symbol": {
+                const name = Symbol.keyFor(value) ?? value.description;
+                if (name === undefined)
+                    throw err("unsupported", value);
+                this.atom(name);
+                return;
+            }
             case "object":
                 this.object(value);
                 return;
@@ -328,29 +345,31 @@ class Encoder {
         if (!Number.isSafeInteger(value)) {
             throw err("lossy-int", value);
         }
-        if (value >= 0 && value < 2 ** 8) {
+        this.integer(BigInt(value));
+    }
+    integer(value) {
+        if (value >= 0n && value < 256n) {
             this.byte(SMALL_INTEGER_EXT);
-            this.byte(value);
+            this.byte(Number(value));
             return;
         }
-        if (value >= -2147483648 && value < 2 ** 31) {
+        if (value >= -2147483648n && value < 2147483648n) {
             this.byte(INTEGER_EXT);
-            this.int32(value);
+            this.int32(Number(value));
             return;
         }
-        this.smallBigInt(value);
-    }
-    // https://www.erlang.org/doc/apps/erts/erl_ext_dist.html#small_big_ext
-    smallBigInt(value) {
-        let magnitude = BigInt(Math.abs(value));
+        let magnitude = value < 0n ? -value : value;
         const digits = [];
         while (magnitude > 0n) {
             digits.push(Number(magnitude & 0xffn));
             magnitude >>= 8n;
         }
-        this.byte(SMALL_BIG_EXT);
-        this.byte(digits.length);
-        this.byte(value < 0 ? 1 : 0);
+        this.byte(digits.length < 256 ? SMALL_BIG_EXT : LARGE_BIG_EXT);
+        if (digits.length < 256)
+            this.byte(digits.length);
+        else
+            this.uint32(digits.length);
+        this.byte(value < 0n ? 1 : 0);
         this.bytes(digits);
     }
     object(rawValue) {
@@ -376,12 +395,34 @@ class Encoder {
                 this.array(value);
                 return;
             }
+            if (value instanceof ArrayBuffer) {
+                const bytes = new Uint8Array(value);
+                this.binary(bytes);
+                return;
+            }
+            if (ArrayBuffer.isView(value)) {
+                const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+                this.binary(bytes);
+                return;
+            }
+            if (value instanceof Date) {
+                this.date(value);
+                return;
+            }
+            if (value instanceof Map) {
+                this.entries(value.entries(), value);
+                return;
+            }
+            if (value instanceof Set) {
+                this.set(value);
+                return;
+            }
             const prototype = Object.getPrototypeOf(value);
             const isObject = prototype === Object.prototype || prototype === null;
             if (!isObject) {
                 throw err("non-plain-object", value);
             }
-            this.map(value);
+            this.entries(Object.entries(value), value);
         }
         finally {
             this.ancestors.delete(value);
@@ -412,18 +453,84 @@ class Encoder {
         }
         this.byte(NIL_EXT);
     }
-    map(value) {
-        const keys = Object.keys(value).sort();
+    set(value) {
+        // Elixir 1.20 uses the version-2 Erlang sets map representation.
+        const members = [];
+        for (const member of value)
+            members.push([member, []]);
+        const memberBytes = this.mapBytes(members, value, true);
+        const map = new RawTerm(memberBytes);
+        const fields = [
+            [atom("__struct__"), atom("Elixir.MapSet")],
+            [atom("map"), map],
+        ];
+        this.entries(fields, value);
+    }
+    date(value) {
+        const year = value.getUTCFullYear();
+        const validDate = Number.isFinite(value.getTime());
+        const supportedYear = year >= -9999 && year <= 9999;
+        if (!validDate || !supportedYear) {
+            throw err("unsupported", value);
+        }
+        const fields = {
+            __struct__: atom("Elixir.DateTime"),
+            calendar: atom("Elixir.Calendar.ISO"),
+            year,
+            month: value.getUTCMonth() + 1,
+            day: value.getUTCDate(),
+            hour: value.getUTCHours(),
+            minute: value.getUTCMinutes(),
+            second: value.getUTCSeconds(),
+            microsecond: tuple(value.getUTCMilliseconds() * 1000, 3),
+            time_zone: "Etc/UTC",
+            zone_abbr: "UTC",
+            utc_offset: 0,
+            std_offset: 0,
+        };
+        const entries = [];
+        for (const [key, item] of Object.entries(fields)) {
+            entries.push([atom(key), item]);
+        }
+        this.entries(entries, value);
+    }
+    termBytes(value) {
+        const start = this.output.length;
+        this.value(value);
+        return this.output.splice(start);
+    }
+    mapBytes(entries, source, merge = false) {
+        const encoded = [...entries].map(([key, value]) => ({
+            key: this.termBytes(key),
+            value: this.termBytes(value),
+        }));
+        encoded.sort((left, right) => compareKeys(left.key, right.key));
+        const unique = [];
+        for (const entry of encoded) {
+            const previous = unique.at(-1);
+            const duplicate = previous !== undefined && compareBytes(entry.key, previous.key) === 0;
+            if (duplicate) {
+                if (!merge)
+                    throw err("unsupported", source);
+                continue;
+            }
+            unique.push(entry);
+        }
+        const start = this.output.length;
         this.byte(MAP_EXT);
-        this.uint32(keys.length);
-        for (const key of keys) {
-            this.binary(key);
-            this.value(value[key]);
+        this.uint32(unique.length);
+        for (const entry of unique) {
+            this.bytes(entry.key);
+            this.bytes(entry.value);
         }
+        return new Uint8Array(this.output.splice(start));
+    }
+    entries(entries, source) {
+        this.bytes(this.mapBytes(entries, source));
     }
     atom(atom) {
         const bytes = UTF8$1.encode(atom);
-        if (bytes.length >= 2 ** 16) {
+        if ([...atom].length > 255) {
             throw err("unsupported", atom);
         }
         if (bytes.length < 2 ** 8) {
@@ -437,7 +544,7 @@ class Encoder {
         this.bytes(bytes);
     }
     binary(value) {
-        const bytes = UTF8$1.encode(value);
+        const bytes = typeof value === "string" ? UTF8$1.encode(value) : value;
         this.byte(BINARY_EXT);
         this.uint32(bytes.length);
         this.bytes(bytes);
@@ -470,6 +577,21 @@ class Encoder {
 function err(reason, part) {
     return new TypeError(reason, { cause: part });
 }
+function compareBytes(a, b, start = 0) {
+    const length = Math.min(a.length, b.length);
+    for (let i = start; i < length; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return a.length - b.length;
+}
+function compareKeys(left, right) {
+    const leftTag = left[0];
+    const rightTag = right[0];
+    const binaryKeys = leftTag === BINARY_EXT && rightTag === BINARY_EXT;
+    const offset = binaryKeys ? BINARY_HEADER_SIZE : 0;
+    return compareBytes(left, right, offset);
+}
 
 function readWorkerEvent(value) {
     const data = objectWithKeys(value, ["type", "payload"]);
@@ -544,6 +666,10 @@ function assertRunJsFn(value) {
  * Use {@link Popcorn.init} to create and start an instance.
  **/
 class Popcorn {
+    /** Receives stdout. Can be replaced at any time; `undefined` restores the default output handler. */
+    onStdout;
+    /** Receives stderr. Can be replaced at any time; `undefined` restores the default output handler. */
+    onStderr;
     vmWorker;
     state = { status: "created" };
     opts;
@@ -561,10 +687,14 @@ class Popcorn {
     trackedKeySeq = 0;
     io = createIoState();
     vmReady = false;
-    genserver = {
-        call: (target, request, opts) => this.call(target, request, opts),
-        cast: (target, request, opts) => this.cast(target, request, opts),
-    };
+    /** Calls a GenServer and returns its reply. See {@link tryCall} for a result instead of throwing. */
+    async call(target, request, opts) {
+        return unwrap(await this.tryCall(target, request, opts));
+    }
+    /** Sends a cast through the proxy. See {@link tryCast} for a result instead of throwing. */
+    async cast(target, request, opts) {
+        unwrap(await this.tryCast(target, request, opts));
+    }
     TrackedValue = class {
         value;
         cleanup;
@@ -635,7 +765,11 @@ class Popcorn {
             },
         };
         this.ttySize = { ...ttySize };
-        this.output = resolveOutputHandlers(opts);
+        this.onStdout = opts.onStdout;
+        this.onStderr = opts.onStderr;
+        this.output = resolveOutputHandlers(this.opts, this);
+        if (opts.onEvent)
+            this.onEvent(opts.onEvent);
         this.spawnWorker();
     }
     spawnWorker() {
@@ -650,20 +784,18 @@ class Popcorn {
     /**
      * Creates an instance and waits for {@link boot}.
      *
-     * For startup messages, use the constructor and register {@link onEvent} before boot.
+     * Use `opts.onEvent` to receive messages sent during startup.
+     *
+     * @returns The instance. Rejects on failure.
      *
-     * @returns Ok tuple or `runtime:eval-unavailable` if the page blocks JavaScript evaluation.
+     * @see {@link PopcornOpts}
      */
     static async init(opts = {}) {
         if (!canEval()) {
-            return { ok: false, error: err$1("runtime:eval-unavailable", {}) };
+            throw err$1("runtime:eval-unavailable", {});
         }
         const popcorn = new Popcorn(opts);
-        const result = await popcorn.boot();
-        if (!result.ok) {
-            return result;
-        }
-        return { ok: true, data: popcorn };
+        return await popcorn.boot();
     }
     /**
      * Starts the VM and waits for its bridge and entrypoint application.
@@ -672,37 +804,29 @@ class Popcorn {
      *
      * After shutdown, starts a fresh VM with the original options.
      *
-     * @returns Ok tuple with `this` if boot completes or error tuple.
+     * @returns This instance. Rejects on failure.
      *
      * @example
      * ```ts
      * const popcorn = new Popcorn({});
      * popcorn.onEvent((message) => console.log(message));
-     * const result = await popcorn.boot();
-     * if (!result.ok) throw result.error;
+     * await popcorn.boot();
      * ```
      */
     async boot() {
-        if (this.state.status === "booted") {
-            return { ok: true, data: this };
-        }
-        if (this.state.status === "booting") {
-            // TODO(jgonet): make it easier to construct check() errors without throwing
-            const error = err$1("internal:check", {
-                detail: "Boot already in progress",
-            });
-            return { ok: false, error };
-        }
+        if (this.state.status === "booted")
+            return this;
+        check(this.state.status !== "booting", "Boot already in progress");
         const reboot = this.state.status === "closed";
         if (reboot) {
             this.spawnWorker();
         }
         this.Pid = createPidClass();
         this.io = createIoState();
-        this.output = resolveOutputHandlers(this.opts);
+        this.output = resolveOutputHandlers(this.opts, this);
         check(this.readyWaiters.length === 0);
         this.state = { status: "booting" };
-        return await new Promise((resolve) => {
+        return await new Promise((resolve, reject) => {
             const timeoutsMs = { ...DEFAULT_TIMEOUTS_MS, ...this.opts.timeoutsMs };
             const settle = (result) => {
                 if (this.settleBoot === null)
@@ -712,7 +836,10 @@ class Popcorn {
                 if (!result.ok) {
                     this.deinit();
                 }
-                resolve(result);
+                if (result.ok)
+                    resolve(result.data);
+                else
+                    reject(result.error);
             };
             this.settleBoot = settle;
             const startPhase = (timeoutMs) => setTimeout(() => {
@@ -763,13 +890,12 @@ class Popcorn {
      *
      * Encodes strings as UTF-8 and copies byte arrays. Does not append a newline.
      *
-     * Returns `stdio:overflow` if the chunk exceeds the remaining 64 KiB queue capacity.
+     * Throws `stdio:overflow` if the chunk exceeds the remaining 64 KiB queue capacity.
      * An overflow leaves the queue unchanged.
      */
     writeStdin(chunk) {
-        if (this.state.status === "closed") {
-            return { ok: false, error: this.state.error };
-        }
+        if (this.state.status === "closed")
+            throw this.state.error;
         check(this.state.status === "booted");
         const bytes = toBytes(chunk);
         check(bytes.byteLength > 0);
@@ -779,29 +905,28 @@ class Popcorn {
                 capacityBytes: STDIN_QUEUE_CAPACITY_BYTES,
                 attemptedBytes,
             });
-            return { ok: false, error };
+            throw error;
         }
         this.io.stdin.reservedBytes = attemptedBytes;
         const event = { type: "popcorn:stdin", payload: { chunk: bytes } };
         toVm(this.vmWorker, event, [bytes.buffer]);
-        return { ok: true, data: null };
     }
     /**
      * Sends new terminal dimensions to a booted VM.
      *
      * Each dimension must be between 1 and 65,535.
+     *
+     * Throws on failure.
      */
     resizeTty(columns, rows) {
-        if (this.state.status === "closed") {
-            return { ok: false, error: this.state.error };
-        }
+        if (this.state.status === "closed")
+            throw this.state.error;
         check(this.state.status === "booted");
         check(isValidTtySize({ columns, rows }));
         toVm(this.vmWorker, {
             type: "popcorn:tty-resize",
             payload: { columns, rows },
         });
-        return { ok: true, data: null };
     }
     /**
      * Sends a payload to a registered process name or a {@link Pid} from this VM boot.
@@ -810,21 +935,26 @@ class Popcorn {
      * A send timeout does not cancel delivery.
      * Uses the value conversions in {@link AnyValue}. An omitted, `null`, or `undefined` payload becomes an empty map.
      *
-     * @returns Ok tuple or `bridge:not-started` before boot and `vm:exited` after shutdown.
+     * @returns Rejects on failure.
      *
      * @example
      * Send an Erlang `{ok, <<"value">>}` tuple to a registered `receiver` process.
      *
      * ```ts
-     * const result = await popcorn.send("receiver", tuple(atom("ok"), "value"));
-     * if (!result.ok) throw result.error;
+     * await popcorn.send("receiver", tuple(atom("ok"), "value"));
      * ```
      *
      * @see {@link AnyValue}
      * @see {@link atom}
      * @see {@link tuple}
+     *
+     * @see {@link trySend} for a result instead of throwing on expected failures.
      */
     async send(rawTarget, payload) {
+        unwrap(await this.trySend(rawTarget, payload));
+    }
+    /** See {@link send}. */
+    async trySend(rawTarget, payload) {
         if (this.state.status !== "booted") {
             if (this.state.status === "closed") {
                 return { ok: false, error: this.state.error };
@@ -978,7 +1108,16 @@ class Popcorn {
                 unreachable();
         }
     }
-    async call(rawTarget, request, opts) {
+    /**
+     * Calls a GenServer by registered name or {@link Pid} and waits for its reply.
+     *
+     * @param opts - `timeoutMs` defaults to 5 000 ms. `proxy` allows to select another registered proxy (see `Popcorn.Proxy`).
+     * @returns A {@link Result} with the reply or a bridge, VM, timeout, or GenServer error.
+     *
+     * GenServer failures use `genserver:noproc`, `genserver:exit`, or `genserver:unserializable`.
+     * A call timeout does not cancel server work.
+     */
+    async tryCall(rawTarget, request, opts) {
         if (this.state.status !== "booted") {
             if (this.state.status === "closed") {
                 return { ok: false, error: this.state.error };
@@ -1021,7 +1160,14 @@ class Popcorn {
         }
         return result;
     }
-    async cast(rawTarget, request, opts) {
+    /**
+     * Sends a cast through the proxy.
+     *
+     * Success confirms delivery to the proxy
+     * @see {@link tryCall}
+     * @param opts - `proxy` allows to select another registered proxy.
+     */
+    async tryCast(rawTarget, request, opts) {
         if (this.state.status !== "booted") {
             if (this.state.status === "closed") {
                 return { ok: false, error: this.state.error };
@@ -1050,9 +1196,16 @@ class Popcorn {
             const args = this.reviveHandles(request.args);
             check(this.vmReady);
             const actions = {
-                send: (target, payload) => this.sendBridge(target, payload),
-                call: (target, payload, opts) => this.callBridge(target, payload, opts),
-                cast: (target, payload, opts) => this.castBridge(target, payload, opts),
+                send: async (target, payload) => {
+                    unwrap(await this.sendBridge(target, payload));
+                },
+                call: async (target, payload, opts) => unwrap(await this.callBridge(target, payload, opts)),
+                cast: async (target, payload, opts) => {
+                    unwrap(await this.castBridge(target, payload, opts));
+                },
+                trySend: (target, payload) => this.sendBridge(target, payload),
+                tryCall: (target, payload, opts) => this.callBridge(target, payload, opts),
+                tryCast: (target, payload, opts) => this.castBridge(target, payload, opts),
             };
             const result = await fn(args, actions);
             const value = request.return === "ref" ? this.asRef(result) : result;
@@ -1110,6 +1263,10 @@ class Popcorn {
         return make(this.TrackedValue);
     }
     reviveHandles(value) {
+        const marker = objectWithKeys(value, ["popcorn_value"]);
+        if (marker !== null && Object.keys(marker).length === 1) {
+            return this.reviveValueTag(marker.popcorn_value);
+        }
         const key = trackedRefKey(value);
         if (key !== null) {
             const entry = this.trackedValues.get(key);
@@ -1125,14 +1282,55 @@ class Popcorn {
         }
         const obj = objectWithKeys(value, []);
         if (obj !== null) {
-            const revived = {};
-            for (const [k, v] of Object.entries(obj)) {
-                revived[k] = this.reviveHandles(v);
-            }
-            return revived;
+            const entries = Object.entries(obj).map(([key, item]) => [
+                key,
+                this.reviveHandles(item),
+            ]);
+            return Object.fromEntries(entries);
         }
         return value;
     }
+    reviveValueTag(payload) {
+        check(Array.isArray(payload) && payload.length === 2);
+        const [tag, data] = payload;
+        switch (tag) {
+            case "binary":
+                check(typeof data === "string");
+                return base64ToBytes(data);
+            case "integer": {
+                const integer = readInteger(data);
+                const safe = integer >= BigInt(Number.MIN_SAFE_INTEGER) &&
+                    integer <= BigInt(Number.MAX_SAFE_INTEGER);
+                if (safe)
+                    return Number(integer);
+                return integer;
+            }
+            case "datetime": {
+                const milliseconds = readInteger(data);
+                const inRange = milliseconds >= -377705116800000n && milliseconds <= 253402300799999n;
+                check(inRange);
+                return new Date(Number(milliseconds));
+            }
+            case "set":
+                check(Array.isArray(data));
+                return new Set(data.map((item) => this.reviveHandles(item)));
+            case "object": {
+                check(Array.isArray(data));
+                const entries = [];
+                for (const entry of data) {
+                    check(Array.isArray(entry) && entry.length === 2);
+                    const [key, value] = entry;
+                    check(typeof key === "string");
+                    entries.push([key, this.reviveHandles(value)]);
+                }
+                const object = Object.fromEntries(entries);
+                check(Object.keys(object).length === entries.length);
+                return object;
+            }
+            default:
+                check(false, "unknown popcorn value tag");
+        }
+    }
     /** Maps pids and `TrackedValue`s during encoding, collecting handles into
      * `tracked` for the caller to register once encoding succeeds. */
     handleMapper(tracked) {
@@ -1228,22 +1426,20 @@ function isValidTtySize({ columns, rows }) {
     const rowInRange = 0 < rows && rows <= 0xffff;
     return colInRange && rowInRange;
 }
-function resolveOutputHandlers(opts) {
+function resolveOutputHandlers(opts, callbacks) {
     if (opts.tty?.output === "bytes") {
-        const onStdout = opts.onStdout;
-        const onStderr = opts.onStderr;
         return {
-            stdout: onStdout ?? defaultOnStdoutBytes,
-            stderr: onStderr ?? defaultOnStderrBytes,
+            stdout: (chunk) => (callbacks.onStdout ??
+                defaultOnStdoutBytes)(chunk),
+            stderr: (chunk) => (callbacks.onStderr ??
+                defaultOnStderrBytes)(chunk),
         };
     }
     const stdoutDecoder = new TextDecoder();
     const stderrDecoder = new TextDecoder();
-    const onStdout = opts.onStdout ?? defaultOnStdout;
-    const onStderr = opts.onStderr ?? defaultOnStderr;
     return {
-        stdout: (chunk) => decodeOutput(stdoutDecoder, onStdout, chunk),
-        stderr: (chunk) => decodeOutput(stderrDecoder, onStderr, chunk),
+        stdout: (chunk) => decodeOutput(stdoutDecoder, callbacks.onStdout ?? defaultOnStdout, chunk),
+        stderr: (chunk) => decodeOutput(stderrDecoder, callbacks.onStderr ?? defaultOnStderr, chunk),
     };
 }
 function decodeOutput(decoder, onOutput, chunk) {
@@ -1333,5 +1529,10 @@ function defaultOnError(payload) {
             unreachable();
     }
 }
+function readInteger(value) {
+    check(typeof value === "string");
+    check(/^-?(0|[1-9][0-9]*)$/.test(value));
+    return BigInt(value);
+}
 
 export { Popcorn, PopcornError, a, atom, schedulers, t, tuple };

package/dist/plugins/shared.d.ts

@@ -6,26 +6,8 @@ type RuntimeVariant = "core" | "crypto";
  * compiles the project before packaging it.
  */
 export type Options = {
-    /** Runtime variant override. */
-    runtimeVariant?: RuntimeVariant;
-    /** Mix project directory. */
+    /** Mix project directory. Cooking options belong in its config/config.exs. */
     rootDir: string;
-    /**
-     * OTP application to start after VM boot.
-     * Defaults to the current Mix application.
-     */
-    app?: string | null;
-    /** Additional applications to package with their dependencies. */
-    extraApps?: string[];
-    /** Brotli compression effort. Defaults to `standard`. */
-    brotliEffort?: "standard" | "max";
-    /** Removes nonessential BEAM chunks. Defaults to `true`. */
-    strip?: boolean;
-    /** Controls removal of unreachable modules and functions. Defaults to `none`. */
-    treeshake?: TreeshakeOptions;
-};
-export type TreeshakeOptions = {
-    preservedApps?: string[];
 };
 export type Prepared = {
     dir: string;

package/dist/plugins/shared.mjs

@@ -9,26 +9,6 @@ const execFileAsync = promisify(execFile);
 async function popcorn(options) {
     const dir = await mkdtemp(`${tmpdir()}/popcorn-otp-`);
     const args = ["popcorn.cook", "--out-dir", dir];
-    if (options.app === null)
-        args.push("--no-app");
-    else if (options.app !== undefined)
-        args.push("--app", options.app);
-    for (const app of options.extraApps ?? [])
-        args.push("--extra-app", app);
-    if (options.runtimeVariant !== undefined) {
-        args.push("--runtime-variant", options.runtimeVariant);
-    }
-    if (options.brotliEffort !== undefined) {
-        args.push("--brotli-effort", options.brotliEffort);
-    }
-    if (options.strip === false)
-        args.push("--no-strip");
-    if (options.treeshake !== undefined) {
-        args.push("--treeshake");
-        for (const app of options.treeshake.preservedApps ?? []) {
-            args.push("--preserved-app", app);
-        }
-    }
     try {
         await execFileAsync("mix", args, {
             cwd: resolve(options.rootDir),

package/dist/plugins/vite.mjs

@@ -43,6 +43,7 @@ function popcorn(options) {
     let dirty = false;
     let outDir;
     let assetsDir = "assets";
+    let workerDerivedOtpRoot = `/@fs${distDir}/otp/`;
     // Dev/preview: pack once at server startup, then re-pack lazily after the
     // app's compiled beams change. A single in-flight promise dedupes concurrent
     // requests; a change during a re-pack re-sets `dirty` so it isn't lost.
@@ -78,7 +79,7 @@ function popcorn(options) {
             return;
         }
         const requestPath = decodeURIComponent(new URL(url, "http://localhost").pathname);
-        const requestRoot = [`/${assetsDir}/otp/`, `/@fs${distDir}/otp/`].find((root) => requestPath.startsWith(root));
+        const requestRoot = [`/${assetsDir}/otp/`, workerDerivedOtpRoot].find((root) => requestPath.startsWith(root));
         if (requestRoot === undefined) {
             next();
             return;
@@ -146,6 +147,10 @@ function popcorn(options) {
             config.server.fs.allow.push(distDir);
             outDir = resolve(config.root, config.build.outDir);
             assetsDir = config.build.assetsDir;
+            const servedDistDir = isUnder(config.root, distDir)
+                ? `/${relative(config.root, distDir)}`
+                : `/@fs${distDir}`;
+            workerDerivedOtpRoot = `${servedDistDir}/otp/`;
         },
         async configureServer(server) {
             const rootDir = resolve(options.rootDir);

package/dist/popcorn.d.ts

@@ -54,14 +54,14 @@ export type PopcornOpts<Output extends TtyOutput = "text"> = {
      * Receives stdout.
      *
      * Defaults to `console.log`.
-     * When `tty.output` is "bytes", we pass an `ArrayBuffer` as an argument and `string` otherwise
+     * Receives `Uint8Array` when `tty.output` is "bytes", and `string` otherwise.
      */
     onStdout?: (chunk: OutputChunk<Output>) => void;
     /**
      * Receives stderr.
      *
      * Defaults to `console.error`.
-     * When `tty.output` is "bytes", we pass an `ArrayBuffer` as an argument and `string` otherwise
+     * Receives `Uint8Array` when `tty.output` is "bytes", and `string` otherwise.
      */
     onStderr?: (chunk: OutputChunk<Output>) => void;
     /**
@@ -70,6 +70,8 @@ export type PopcornOpts<Output extends TtyOutput = "text"> = {
      * Defaults to console output.
      */
     onError?: (event: OtpErrorPayload) => void;
+    /** Receives BEAM message payloads, including messages sent during startup. */
+    onEvent?: (event: PopcornEvent) => void;
     /**
      * Module worker URL.
      *
@@ -93,36 +95,17 @@ type CallOpts = {
     timeoutMs?: number;
     proxy?: string;
 };
-export type GenServer = {
-    /**
-     * Calls a GenServer by registered name or {@link Pid} and waits for its reply.
-     *
-     * Requires a running `Popcorn.Proxy`, registered as `popcorn_proxy` by default.
-     *
-     * @param opts - `timeoutMs` defaults to 5 000 ms. `proxy` allows to select another registered proxy.
-     * @returns A {@link Result} with the reply or a bridge, VM, timeout, or GenServer error.
-     *
-     * GenServer failures use `genserver:noproc`, `genserver:exit`, or `genserver:unserializable`.
-     * A call timeout does not cancel server work.
-     */
-    call(target: string | Pid, request?: AnyValue, opts?: CallOpts): Promise<Result<AnyValue>>;
-    /**
-     * Sends a cast through the proxy.
-     *
-     * Success confirms delivery to the proxy
-     * @see {@link call}
-     * @param opts - `proxy` allows to select another registered proxy.
-     */
-    cast(target: string | Pid, request?: AnyValue, opts?: {
-        proxy?: string;
-    }): Promise<Result<null>>;
-};
+export type GenServer = Pick<Popcorn, "call" | "cast" | "tryCall" | "tryCast">;
 /**
  * A BEAM VM in a browser worker.
  *
  * Use {@link Popcorn.init} to create and start an instance.
  **/
 export declare class Popcorn<Output extends TtyOutput = "text"> {
+    /** Receives stdout. Can be replaced at any time; `undefined` restores the default output handler. */
+    onStdout?: (chunk: OutputChunk<Output>) => void;
+    /** Receives stderr. Can be replaced at any time; `undefined` restores the default output handler. */
+    onStderr?: (chunk: OutputChunk<Output>) => void;
     private vmWorker;
     private state;
     private readonly opts;
@@ -140,7 +123,12 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
     private trackedKeySeq;
     private io;
     private vmReady;
-    readonly genserver: GenServer;
+    /** Calls a GenServer and returns its reply. See {@link tryCall} for a result instead of throwing. */
+    call(target: string | Pid, request?: AnyValue, opts?: CallOpts): Promise<AnyValue>;
+    /** Sends a cast through the proxy. See {@link tryCast} for a result instead of throwing. */
+    cast(target: string | Pid, request?: AnyValue, opts?: {
+        proxy?: string;
+    }): Promise<void>;
     private readonly TrackedValue;
     private Pid;
     private readonly onWorkerMessage;
@@ -154,11 +142,13 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
     /**
      * Creates an instance and waits for {@link boot}.
      *
-     * For startup messages, use the constructor and register {@link onEvent} before boot.
+     * Use `opts.onEvent` to receive messages sent during startup.
+     *
+     * @returns The instance. Rejects on failure.
      *
-     * @returns Ok tuple or `runtime:eval-unavailable` if the page blocks JavaScript evaluation.
+     * @see {@link PopcornOpts}
      */
-    static init<Output extends TtyOutput = "text">(opts?: PopcornOpts<Output>): Promise<Result<Popcorn<Output>>>;
+    static init<Output extends TtyOutput = "text">(opts?: PopcornOpts<Output>): Promise<Popcorn<Output>>;
     /**
      * Starts the VM and waits for its bridge and entrypoint application.
      *
@@ -166,32 +156,33 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
      *
      * After shutdown, starts a fresh VM with the original options.
      *
-     * @returns Ok tuple with `this` if boot completes or error tuple.
+     * @returns This instance. Rejects on failure.
      *
      * @example
      * ```ts
      * const popcorn = new Popcorn({});
      * popcorn.onEvent((message) => console.log(message));
-     * const result = await popcorn.boot();
-     * if (!result.ok) throw result.error;
+     * await popcorn.boot();
      * ```
      */
-    boot(): Promise<Result<Popcorn<Output>>>;
+    boot(): Promise<Popcorn<Output>>;
     /**
      * Queues terminal input.
      *
      * Encodes strings as UTF-8 and copies byte arrays. Does not append a newline.
      *
-     * Returns `stdio:overflow` if the chunk exceeds the remaining 64 KiB queue capacity.
+     * Throws `stdio:overflow` if the chunk exceeds the remaining 64 KiB queue capacity.
      * An overflow leaves the queue unchanged.
      */
-    writeStdin(chunk: string | Uint8Array): Result<null>;
+    writeStdin(chunk: string | Uint8Array): void;
     /**
      * Sends new terminal dimensions to a booted VM.
      *
      * Each dimension must be between 1 and 65,535.
+     *
+     * Throws on failure.
      */
-    resizeTty(columns: number, rows: number): Result<null>;
+    resizeTty(columns: number, rows: number): void;
     /**
      * Sends a payload to a registered process name or a {@link Pid} from this VM boot.
      *
@@ -199,21 +190,24 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
      * A send timeout does not cancel delivery.
      * Uses the value conversions in {@link AnyValue}. An omitted, `null`, or `undefined` payload becomes an empty map.
      *
-     * @returns Ok tuple or `bridge:not-started` before boot and `vm:exited` after shutdown.
+     * @returns Rejects on failure.
      *
      * @example
      * Send an Erlang `{ok, <<"value">>}` tuple to a registered `receiver` process.
      *
      * ```ts
-     * const result = await popcorn.send("receiver", tuple(atom("ok"), "value"));
-     * if (!result.ok) throw result.error;
+     * await popcorn.send("receiver", tuple(atom("ok"), "value"));
      * ```
      *
      * @see {@link AnyValue}
      * @see {@link atom}
      * @see {@link tuple}
+     *
+     * @see {@link trySend} for a result instead of throwing on expected failures.
      */
-    send(rawTarget: string | Pid, payload?: AnyValue): Promise<Result<null>>;
+    send(rawTarget: string | Pid, payload?: AnyValue): Promise<void>;
+    /** See {@link send}. */
+    trySend(rawTarget: string | Pid, payload?: AnyValue): Promise<Result<null>>;
     private sendBridge;
     /**
      * Registers a handler for BEAM message payloads.
@@ -235,9 +229,27 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
     private emit;
     private completeCall;
     private parseCallReply;
-    private call;
+    /**
+     * Calls a GenServer by registered name or {@link Pid} and waits for its reply.
+     *
+     * @param opts - `timeoutMs` defaults to 5 000 ms. `proxy` allows to select another registered proxy (see `Popcorn.Proxy`).
+     * @returns A {@link Result} with the reply or a bridge, VM, timeout, or GenServer error.
+     *
+     * GenServer failures use `genserver:noproc`, `genserver:exit`, or `genserver:unserializable`.
+     * A call timeout does not cancel server work.
+     */
+    tryCall(rawTarget: string | Pid, request?: AnyValue, opts?: CallOpts): Promise<Result<AnyValue>>;
     private callBridge;
-    private cast;
+    /**
+     * Sends a cast through the proxy.
+     *
+     * Success confirms delivery to the proxy
+     * @see {@link tryCall}
+     * @param opts - `proxy` allows to select another registered proxy.
+     */
+    tryCast(rawTarget: string | Pid, request?: AnyValue, opts?: {
+        proxy?: string;
+    }): Promise<Result<null>>;
     private castBridge;
     private nextCallId;
     private runJs;
@@ -248,6 +260,7 @@ export declare class Popcorn<Output extends TtyOutput = "text"> {
     private sendBridgeReply;
     private jsWithCurrentEnv;
     private reviveHandles;
+    private reviveValueTag;
     /** Maps pids and `TrackedValue`s during encoding, collecting handles into
      * `tracked` for the caller to register once encoding succeeds. */
     private handleMapper;

package/dist/types.d.ts

@@ -1,15 +1,8 @@
 type CreateModuleFn<Mod> = (overrides?: Partial<Mod>) => Promise<Mod>;
 /**
- * A message value. JavaScript sends use these BEAM conversions:
+ * A value exchanged with BEAM. Containers convert their contents recursively.
  *
- * - Strings become UTF-8 binaries. Booleans become `true` and `false` atoms.
- * - Integers become integers. Other finite numbers become floats.
- * - Arrays become lists.
- * - Plain objects become maps with binary string keys.
- * - `null` and `undefined` become the `nil` atom.
- * - `atom()` and `tuple()` create atoms and tuples. PIDs retain their BEAM identity.
- *
- * Cycles, class instances, functions, symbols, bigints, unsafe integers, and non-finite numbers cause `bridge:unserializable`.
+ * See [Sharing values across languages](values.html) for supported types and conversions.
  */
 export type AnyValue = unknown;
 declare const pidBrand: unique symbol;

package/dist/worker.mjs

@@ -222,7 +222,7 @@ function unreachable() {
 function objectWithKeys(value, keys) {
     if (value === null || typeof value !== "object")
         return null;
-    if (value.constructor !== Object)
+    if (Object.getPrototypeOf(value) !== Object.prototype)
         return null;
     const hasAllKeys = keys.every((k) => Object.hasOwn(value, k));
     if (!hasAllKeys)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/popcorn",
-  "version": "0.4.0-next.4",
+  "version": "0.4.0-next.6",
   "description": "JS bindings for BEAM/OTP in WebAssembly",
   "type": "module",
   "license": "Apache-2.0",