@swmansion/popcorn 0.2.2 → 0.3.0-rc1

package/dist/bridge.mjs

@@ -41,10 +41,11 @@ class IframeBridge {
         window.removeEventListener("message", this.handlerRef);
         this.iframe.remove();
     }
-    messageHandler({ data }) {
-        if (isIframeResponse(data)) {
-            this.onMessage(data);
-        }
+    messageHandler(event) {
+        const fromOurIframe = event.source === this.iframe.contentWindow;
+        if (!fromOurIframe || !isIframeResponse(event.data))
+            return;
+        this.onMessage(event.data);
     }
 }
 function isIframeResponse(payload) {

package/dist/errors.d.ts

@@ -6,7 +6,7 @@ export declare class PopcornError extends Error {
     constructor(code: PopcornErrorCode, message?: string);
 }
 /** Error codes for internal errors that indicate bugs or misuse */
-export type PopcornInternalErrorCode = "assert" | "private_constructor" | "bad_call" | "no_acked_call" | "bad_ack" | "already_awaited" | "already_mounted" | "unmounted" | "bad_target" | "bad_status" | "bundle_not_found";
+export type PopcornInternalErrorCode = "assert" | "private_constructor" | "bad_call" | "no_acked_call" | "bad_ack" | "already_mounted" | "unmounted" | "bad_target" | "bad_status" | "app_ready_timeout" | "bundle_not_found";
 /** Non-recoverable error indicating a bug or library misuse (always thrown) */
 export declare class PopcornInternalError extends Error {
     readonly code: PopcornInternalErrorCode;
@@ -23,10 +23,6 @@ type ErrorData = {
     t: "no_acked_call";
 } | {
     t: "bad_ack";
-} | {
-    t: "already_awaited";
-    messageType: string;
-    awaitedMessageType: string;
 } | {
     t: "already_mounted";
 } | {
@@ -37,10 +33,13 @@ type ErrorData = {
     t: "bad_status";
     status: string;
     expectedStatus: string;
+} | {
+    t: "app_ready_timeout";
 } | {
     t: "bundle_not_found";
     primary: string;
     fallback: string;
 };
+export declare function buildError(error: ErrorData): PopcornInternalError;
 export declare function throwError(error: ErrorData): never;
 export {};

package/dist/errors.mjs

@@ -12,6 +12,7 @@ class PopcornError extends Error {
         this.name = "PopcornError";
     }
 }
+const INIT_VM_TIMEOUT_MS = 30_000;
 /** Non-recoverable error indicating a bug or library misuse (always thrown) */
 class PopcornInternalError extends Error {
     code;
@@ -21,31 +22,34 @@ class PopcornInternalError extends Error {
         this.name = "PopcornInternalError";
     }
 }
-function throwError(error) {
+function buildError(error) {
     switch (error.t) {
         case "assert":
-            throw new PopcornInternalError("assert", "Assertion error");
+            return new PopcornInternalError("assert", "Assertion error");
         case "private_constructor":
-            throw new PopcornInternalError("private_constructor", "Don't construct the Popcorn object directly, use Popcorn.init() instead");
+            return new PopcornInternalError("private_constructor", "Don't construct the Popcorn object directly, use Popcorn.init() instead");
         case "bad_call":
-            throw new PopcornInternalError("bad_call", "Response for non-existent call");
+            return new PopcornInternalError("bad_call", "Response for non-existent call");
         case "no_acked_call":
-            throw new PopcornInternalError("no_acked_call", "Response for non-acknowledged call");
+            return new PopcornInternalError("no_acked_call", "Response for non-acknowledged call");
         case "bad_ack":
-            throw new PopcornInternalError("bad_ack", "Ack for non-existent call");
-        case "already_awaited":
-            throw new PopcornInternalError("already_awaited", `Cannot await message "${error.messageType}" when message "${error.awaitedMessageType}" is already awaited`);
+            return new PopcornInternalError("bad_ack", "Ack for non-existent call");
         case "already_mounted":
-            throw new PopcornInternalError("already_mounted", "Iframe already mounted");
+            return new PopcornInternalError("already_mounted", "Iframe already mounted");
         case "unmounted":
-            throw new PopcornInternalError("unmounted", "WASM iframe not mounted");
+            return new PopcornInternalError("unmounted", "WASM iframe not mounted");
         case "bad_target":
-            throw new PopcornInternalError("bad_target", "Unspecified target process");
+            return new PopcornInternalError("bad_target", "Unspecified target process");
         case "bad_status":
-            throw new PopcornInternalError("bad_status", `Operation not allowed: instance in "${error.status}" state, expected "${error.expectedStatus}"`);
+            return new PopcornInternalError("bad_status", `Operation not allowed: instance in "${error.status}" state, expected "${error.expectedStatus}"`);
+        case "app_ready_timeout":
+            return new PopcornInternalError("app_ready_timeout", `Elixir app did not call Popcorn.Wasm.ready() within ${INIT_VM_TIMEOUT_MS}ms`);
         case "bundle_not_found":
-            throw new PopcornInternalError("bundle_not_found", `Could not find a valid .avm bundle at "${error.primary}" or fallback "${error.fallback}"`);
+            return new PopcornInternalError("bundle_not_found", `Could not find a valid .avm bundle at "${error.primary}" or fallback "${error.fallback}"`);
     }
 }
+function throwError(error) {
+    throw buildError(error);
+}
 
-export { PopcornError, PopcornInternalError, throwError };
+export { PopcornError, PopcornInternalError, buildError, throwError };

package/dist/iframe.d.ts

@@ -1 +1 @@
-export declare function runIFrame(): Promise<void>;
+export declare function initVm(): Promise<void>;

package/dist/iframe.mjs

@@ -2,8 +2,7 @@ import init from './AtomVM.mjs';
 
 const HEARTBEAT_INTERVAL_MS = 500;
 const MESSAGES = {
-    INIT: "popcorn-init",
-    START_VM: "popcorn-startVm",
+    EVENT: "popcorn-event",
     CALL: "popcorn-call",
     CAST: "popcorn-cast",
     CALL_ACK: "popcorn-callAck",
@@ -32,7 +31,7 @@ class TrackedValue {
     }
 }
 globalThis.TrackedValue = TrackedValue;
-async function runIFrame() {
+async function initVm() {
     const metaElement = document.querySelector('meta[name="bundle-path"]');
     if (!metaElement) {
         throw new Error("Missing meta[name='bundle-path'] element");
@@ -40,8 +39,7 @@ async function runIFrame() {
     const bundlePath = metaElement.content;
     const bundleBuffer = await fetch(bundlePath).then((resp) => resp.arrayBuffer());
     const bundle = new Int8Array(bundleBuffer);
-    sendIframeResponse(MESSAGES.INIT, null);
-    const initProcess = await startVm(bundle);
+    await startVm(bundle);
     window.addEventListener("message", async ({ data }) => {
         const type = data.type;
         if (type === MESSAGES.CALL) {
@@ -51,14 +49,9 @@ async function runIFrame() {
             handleCast(data.value);
         }
     });
-    sendIframeResponse(MESSAGES.START_VM, initProcess);
     setInterval(() => sendIframeResponse(MESSAGES.HEARTBEAT, null), HEARTBEAT_INTERVAL_MS);
 }
 async function startVm(avmBundle) {
-    let resolveResultPromise = null;
-    const resultPromise = new Promise((resolve) => {
-        resolveResultPromise = resolve;
-    });
     const moduleInstance = await init({
         preRun: [
             function ({ FS }) {
@@ -152,11 +145,9 @@ async function startVm(avmBundle) {
         };
         return keys.map(getTrackedObject);
     };
-    moduleInstance["onElixirReady"] = (initProcess) => {
-        moduleInstance["onElixirReady"] = null;
-        resolveResultPromise?.(initProcess);
+    moduleInstance["sendEvent"] = (eventName, payload) => {
+        sendIframeResponse(MESSAGES.EVENT, { eventName, payload });
     };
-    return resultPromise;
 }
 async function handleCall(request) {
     if (!Module) {
@@ -213,4 +204,4 @@ function deserialize(message) {
     });
 }
 
-export { runIFrame };
+export { initVm };

package/dist/popcorn.d.ts

@@ -49,6 +49,7 @@ type CallResult = {
 };
 type LogType = "stdout" | "stderr";
 type LogListener = (message: string) => void;
+type MessageHandler = (eventName: string, payload: AnySerializable) => void;
 /**
  * Manages Elixir by setting up iframe, WASM module, and event listeners. Used to sent messages to Elixir processes.
  */
@@ -60,17 +61,18 @@ export declare class Popcorn {
     private debug;
     private bundleURL;
     private state;
-    private initProcess;
+    private defaultReceiver;
     private requestId;
     private calls;
     private logListeners;
-    private awaitedMessage;
+    private messageHandlers;
+    private mountResolve;
     private heartbeatTimeout;
     private reloadN;
     private constructor();
     /**
      * Creates an iframe and sets up communication channels.
-     * Returns after Elixir code calls `Popcorn.Wasm.register/1`.
+     * Returns after the Elixir app calls `Popcorn.Wasm.ready/0,1`.
      *
      * @example
      * import { Popcorn } from "@swmansion/popcorn";
@@ -87,7 +89,7 @@ export declare class Popcorn {
      *
      * If Elixir doesn't respond in configured timeout, the returned promise will be rejected with "process timeout" error.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
      * Throws "Unspecified target process" if default process is not set and no process is specified.
      *
      * @example
@@ -102,7 +104,7 @@ export declare class Popcorn {
     /**
      * Sends a message to an Elixir process (default or from options) and returns immediately.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
      * Throws "Unspecified target process" if default process is not set and no process is specified.
      */
     cast(args: AnySerializable, { process }?: CastOptions): void;
@@ -110,6 +112,7 @@ export declare class Popcorn {
      * Destroys an iframe and resets the instance.
      */
     deinit(): void;
+    private teardownBridge;
     /**
      * Registers a log listener that will be called when output of the specified type is received.
      */
@@ -119,12 +122,16 @@ export declare class Popcorn {
      */
     unregisterLogListener(listener: LogListener, type: LogType): void;
     private notifyLogListeners;
+    /**
+     * Registers a catch-all event handler. Returns an unsubscribe function.
+     */
+    onMessage(handler: MessageHandler): () => void;
+    private onEvent;
     private iframeHandler;
     private onCallAck;
     private onCall;
     private onHeartbeat;
     private reloadIframe;
-    private awaitMessage;
     trace(...messages: unknown[]): void;
     private transition;
     private assertStatus;

package/dist/popcorn.mjs

@@ -1,6 +1,6 @@
 import { IframeBridge } from './bridge.mjs';
-import { HEARTBEAT_TIMEOUT_MS, MESSAGES, INIT_VM_TIMEOUT_MS, MAX_RELOAD_N, CALL_TIMEOUT_MS } from './types.mjs';
-import { throwError, PopcornError } from './errors.mjs';
+import { HEARTBEAT_TIMEOUT_MS, INIT_VM_TIMEOUT_MS, MESSAGES, EVENT_NAMES, MAX_RELOAD_N, CALL_TIMEOUT_MS } from './types.mjs';
+import { throwError, buildError, PopcornError } from './errors.mjs';
 export { PopcornInternalError } from './errors.mjs';
 
 const INIT_TOKEN = Symbol();
@@ -16,14 +16,15 @@ class Popcorn {
     debug = false;
     bundleURL;
     state = { status: "uninitialized" };
-    initProcess = null;
+    defaultReceiver = null;
     requestId = 0;
     calls = new Map();
     logListeners = {
         stdout: new Set(),
         stderr: new Set(),
     };
-    awaitedMessage = null;
+    messageHandlers = new Set();
+    mountResolve = null;
     heartbeatTimeout = null;
     reloadN = 0;
     constructor(params, token) {
@@ -36,7 +37,7 @@ class Popcorn {
         this.bundleURL = bundleURL.href;
         this.bridgeConfig = {
             container: params.container,
-            script: { url: IFRAME_URL, entrypoint: "runIFrame" },
+            script: { url: IFRAME_URL, entrypoint: "initVm" },
             config: { "bundle-path": this.bundleURL },
             debug: true,
             onMessage: this.iframeHandler.bind(this),
@@ -47,7 +48,7 @@ class Popcorn {
     }
     /**
      * Creates an iframe and sets up communication channels.
-     * Returns after Elixir code calls `Popcorn.Wasm.register/1`.
+     * Returns after the Elixir app calls `Popcorn.Wasm.ready/0,1`.
      *
      * @example
      * import { Popcorn } from "@swmansion/popcorn";
@@ -76,20 +77,19 @@ class Popcorn {
         this.trace("Main: mount, container: ", this.bridgeConfig.container);
         this.bridge = new IframeBridge(this.bridgeConfig);
         try {
-            await this.awaitMessage(MESSAGES.INIT);
-            this.transition({ status: "await_vm" });
-            this.trace("Main: iframe loaded");
-            const startTime = performance.now();
-            const startVmResult = await withTimeout(this.awaitMessage(MESSAGES.START_VM).then((data) => ({
-                ok: true,
-                data,
-                durationMs: performance.now() - startTime,
-            })), INIT_VM_TIMEOUT_MS);
-            if (!startVmResult.ok)
-                throwError({ t: "assert" });
-            this.initProcess = startVmResult.data;
+            const mountPromise = new Promise((resolve) => {
+                this.mountResolve = resolve;
+            });
+            let initTimeout;
+            await Promise.race([
+                mountPromise,
+                new Promise((_, reject) => {
+                    initTimeout = setTimeout(() => reject(buildError({ t: "app_ready_timeout" })), INIT_VM_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(initTimeout);
             this.transition({ status: "ready" });
-            this.trace("Main: mounted, main process: ", this.initProcess);
+            this.trace("Main: mounted");
             this.onHeartbeat();
         }
         catch (error) {
@@ -102,7 +102,7 @@ class Popcorn {
      *
      * If Elixir doesn't respond in configured timeout, the returned promise will be rejected with "process timeout" error.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
      * Throws "Unspecified target process" if default process is not set and no process is specified.
      *
      * @example
@@ -115,26 +115,20 @@ class Popcorn {
      */
     async call(args, { process, timeoutMs } = {}) {
         this.assertStatus(["ready"]);
-        const targetProcess = process ?? this.initProcess;
-        if (this.bridge === null)
-            throwError({ t: "unmounted" });
+        const targetProcess = process ?? this.defaultReceiver;
         if (targetProcess === null)
             throwError({ t: "bad_target" });
+        if (this.bridge === null)
+            throwError({ t: "unmounted" });
         const requestId = this.requestId++;
         const startTimeMs = performance.now();
         const callPromise = new Promise((resolve) => {
-            if (this.bridge === null)
-                throwError({ t: "unmounted" });
-            this.trace("Main: call: ", { requestId, process, args });
-            this.bridge.sendIframeRequest({
-                type: MESSAGES.CALL,
-                value: { requestId, process: targetProcess, args },
-            });
-            this.calls.set(requestId, {
-                acknowledged: false,
-                startTimeMs,
-                resolve,
-            });
+            this.calls.set(requestId, { acknowledged: false, startTimeMs, resolve });
+        });
+        this.trace("Main: call: ", { requestId, process, args });
+        this.bridge.sendIframeRequest({
+            type: MESSAGES.CALL,
+            value: { requestId, process: targetProcess, args },
         });
         const result = await withTimeout(callPromise, timeoutMs ?? CALL_TIMEOUT_MS);
         this.calls.delete(requestId);
@@ -143,16 +137,16 @@ class Popcorn {
     /**
      * Sends a message to an Elixir process (default or from options) and returns immediately.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
      * Throws "Unspecified target process" if default process is not set and no process is specified.
      */
     cast(args, { process } = {}) {
         this.assertStatus(["ready"]);
-        const targetProcess = process ?? this.initProcess;
-        if (this.bridge === null)
-            throwError({ t: "unmounted" });
+        const targetProcess = process ?? this.defaultReceiver;
         if (targetProcess === null)
             throwError({ t: "bad_target" });
+        if (this.bridge === null)
+            throwError({ t: "unmounted" });
         const requestId = this.requestId++;
         this.trace("Main: cast: ", { requestId, process, args });
         this.bridge.sendIframeRequest({
@@ -168,20 +162,27 @@ class Popcorn {
             throwError({ t: "unmounted" });
         this.trace("Main: deinit");
         this.transition({ status: "deinit" });
-        this.bridge.deinit();
-        this.bridge = null;
-        this.awaitedMessage = null;
+        this.teardownBridge("deinitialized");
+        this.logListeners.stdout.clear();
+        this.logListeners.stderr.clear();
+        this.messageHandlers.clear();
+    }
+    teardownBridge(errorCode) {
+        if (this.bridge) {
+            this.bridge.deinit();
+            this.bridge = null;
+        }
+        this.mountResolve = null;
+        this.defaultReceiver = null;
         if (this.heartbeatTimeout) {
             clearTimeout(this.heartbeatTimeout);
             this.heartbeatTimeout = null;
         }
-        this.logListeners.stdout.clear();
-        this.logListeners.stderr.clear();
         for (const callData of this.calls.values()) {
             const durationMs = performance.now() - callData.startTimeMs;
             callData.resolve({
                 ok: false,
-                error: new PopcornError("deinitialized"),
+                error: new PopcornError(errorCode),
                 durationMs,
             });
         }
@@ -204,14 +205,47 @@ class Popcorn {
             listener(message);
         });
     }
-    iframeHandler(data) {
-        const awaitedMessage = this.awaitedMessage;
-        if (awaitedMessage && data.type == awaitedMessage.type) {
-            this.awaitedMessage = null;
-            awaitedMessage.resolve?.(data.value);
+    /**
+     * Registers a catch-all event handler. Returns an unsubscribe function.
+     */
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => {
+            this.messageHandlers.delete(handler);
+        };
+    }
+    onEvent({ eventName, payload }) {
+        if (eventName.startsWith("popcorn")) {
+            if (eventName === EVENT_NAMES.ELIXIR_READY) {
+                this.trace("Main: elixir VM ready");
+            }
+            else if (eventName === EVENT_NAMES.APP_READY) {
+                this.defaultReceiver = payload.name;
+                this.mountResolve?.();
+                this.mountResolve = null;
+            }
+            else if (eventName === EVENT_NAMES.SET_DEFAULT_RECEIVER) {
+                this.defaultReceiver = payload.name;
+            }
+            else {
+                this.trace("Unknown internal event:", eventName);
+            }
             return;
         }
-        if (data.type === MESSAGES.STDOUT) {
+        this.messageHandlers.forEach((handler) => {
+            try {
+                handler(eventName, payload);
+            }
+            catch (error) {
+                console.error(`Error in onMessage handler for '${eventName}':`, error);
+            }
+        });
+    }
+    iframeHandler(data) {
+        if (data.type === MESSAGES.EVENT) {
+            this.onEvent(data.value);
+        }
+        else if (data.type === MESSAGES.STDOUT) {
             this.notifyLogListeners("stdout", data.value);
         }
         else if (data.type === MESSAGES.STDERR) {
@@ -283,40 +317,10 @@ class Popcorn {
         }
         this.trace("Main: reloading iframe");
         this.transition({ status: "reload" });
-        this.bridge.deinit();
-        this.bridge = null;
-        this.awaitedMessage = null;
-        if (this.heartbeatTimeout) {
-            clearTimeout(this.heartbeatTimeout);
-            this.heartbeatTimeout = null;
-        }
-        for (const callData of this.calls.values()) {
-            const durationMs = performance.now() - callData.startTimeMs;
-            callData.resolve({
-                ok: false,
-                error: new PopcornError("reload"),
-                durationMs,
-            });
-        }
-        this.calls.clear();
+        this.teardownBridge("reload");
         this.onReloadCallback(reason);
         this.mount();
     }
-    awaitMessage(type) {
-        if (this.awaitedMessage) {
-            throwError({
-                t: "already_awaited",
-                messageType: this.awaitedMessage.type,
-                awaitedMessageType: type,
-            });
-        }
-        this.awaitedMessage = { type };
-        return new Promise((resolve) => {
-            if (!this.awaitedMessage)
-                throwError({ t: "assert" });
-            this.awaitedMessage.resolve = resolve;
-        });
-    }
     trace(...messages) {
         if (this.debug) {
             console.debug(...messages);

package/dist/types.d.ts

@@ -4,6 +4,10 @@ export declare const HEARTBEAT_TIMEOUT_MS = 60000;
 export declare const HEARTBEAT_INTERVAL_MS = 500;
 export declare const MAX_RELOAD_N = 3;
 export type AnySerializable = any;
+export type ElixirEvent = {
+    eventName: string;
+    payload: AnySerializable;
+};
 export type CallRequest = {
     requestId: number;
     process: string;
@@ -32,11 +36,8 @@ export type CallAck = {
 };
 /** Messages sent from iframe to parent window */
 export type IframeResponse = {
-    type: "popcorn-init";
-    value: null;
-} | {
-    type: "popcorn-startVm";
-    value: string;
+    type: "popcorn-event";
+    value: ElixirEvent;
 } | {
     type: "popcorn-call";
     value: CallResponse;
@@ -59,8 +60,7 @@ export type IframeResponse = {
 /** Union of all messages (requests and responses) */
 export type Message = IframeRequest | IframeResponse;
 export declare const MESSAGES: {
-    readonly INIT: "popcorn-init";
-    readonly START_VM: "popcorn-startVm";
+    readonly EVENT: "popcorn-event";
     readonly CALL: "popcorn-call";
     readonly CAST: "popcorn-cast";
     readonly CALL_ACK: "popcorn-callAck";
@@ -69,4 +69,9 @@ export declare const MESSAGES: {
     readonly HEARTBEAT: "popcorn-heartbeat";
     readonly RELOAD: "popcorn-reload";
 };
+export declare const EVENT_NAMES: {
+    readonly ELIXIR_READY: "popcorn_elixir_ready";
+    readonly APP_READY: "popcorn_app_ready";
+    readonly SET_DEFAULT_RECEIVER: "popcorn_set_default_receiver";
+};
 export declare function isMessageType(type: string): type is Message["type"];

package/dist/types.mjs

@@ -3,8 +3,7 @@ const CALL_TIMEOUT_MS = 60_000;
 const HEARTBEAT_TIMEOUT_MS = 60_000;
 const MAX_RELOAD_N = 3;
 const MESSAGES = {
-    INIT: "popcorn-init",
-    START_VM: "popcorn-startVm",
+    EVENT: "popcorn-event",
     CALL: "popcorn-call",
     CAST: "popcorn-cast",
     CALL_ACK: "popcorn-callAck",
@@ -13,9 +12,14 @@ const MESSAGES = {
     HEARTBEAT: "popcorn-heartbeat",
     RELOAD: "popcorn-reload",
 };
+const EVENT_NAMES = {
+    ELIXIR_READY: "popcorn_elixir_ready",
+    APP_READY: "popcorn_app_ready",
+    SET_DEFAULT_RECEIVER: "popcorn_set_default_receiver",
+};
 const MESSAGES_TYPES = new Set(Object.values(MESSAGES));
 function isMessageType(type) {
     return MESSAGES_TYPES.has(type);
 }
 
-export { CALL_TIMEOUT_MS, HEARTBEAT_TIMEOUT_MS, INIT_VM_TIMEOUT_MS, MAX_RELOAD_N, MESSAGES, isMessageType };
+export { CALL_TIMEOUT_MS, EVENT_NAMES, HEARTBEAT_TIMEOUT_MS, INIT_VM_TIMEOUT_MS, MAX_RELOAD_N, MESSAGES, isMessageType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/popcorn",
-  "version": "0.2.2",
+  "version": "0.3.0-rc1",
   "description": "JS bindings for Popcorn",
   "type": "module",
   "license": "Apache-2.0",