@swmansion/popcorn 0.3.2 → 0.4.0-next.0

package/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+Popcorn includes Erlang/OTP compiled to WebAssembly with Emscripten.
+
+Erlang/OTP
+Copyright Ericsson AB and other contributors.
+Licensed under the Apache License, Version 2.0.
+Source: https://github.com/erlang/otp
+Popcorn's runtime includes modifications for WebAssembly and JavaScript interoperability.
+
+Emscripten
+Copyright the Emscripten authors.
+Available under the MIT license and the University of Illinois/NCSA Open Source License.
+Source: https://github.com/emscripten-core/emscripten

package/README.md

@@ -1,3 +1,79 @@
-# @swmansion/popcorn
+# Popcorn OTP
 
-A package exposing Popcorn to the browser.
+Run Elixir in a browser with OTP/BEAM compiled to WebAssembly.
+This prerelease replaces the AtomVM runtime used by Popcorn 0.3.x.
+
+## Install
+
+```sh
+npm install @swmansion/popcorn@next
+```
+
+Add `{:popcorn, "0.4.0-next.0"}` to your Elixir application's dependencies.
+Run `mix deps.get` and `mix compile` before building the JavaScript application.
+The bundler plugins invoke Mix locally to package application and standard-library code.
+
+Use the toolchain pinned in [popcorn/mise.toml](https://github.com/software-mansion/popcorn/blob/v0.4.0-next.0/popcorn/mise.toml).
+The packager checks host OTP compatibility against the selected runtime's manifest.
+
+## Configure Vite
+
+```ts
+import { defineConfig } from "vite";
+import { popcorn } from "@swmansion/popcorn/vite";
+
+export default defineConfig({
+  plugins: [
+    popcorn({
+      rootDir: "../",
+      app: "my_app",
+    }),
+  ],
+});
+```
+
+Set `rootDir` to the compiled Mix project's directory and `app` to its OTP application name.
+Use `app: null` to package the base runtime without starting an application.
+
+The npm package contains two variants:
+
+- `core`: without native crypto support.
+- `crypto`: includes native crypto and ASN.1 support for applications that depend on crypto, public_key, or ssl.
+
+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.
+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`.
+Use ESM output with those bundlers.
+
+## Start the runtime
+
+```ts
+import { Popcorn } from "@swmansion/popcorn";
+
+const result = await Popcorn.init({});
+if (!result.ok) throw result.error;
+
+const vm = result.data;
+// Stop the runtime when the application no longer needs it.
+vm.deinit();
+```
+
+## Serve in production
+
+Serve over HTTPS or localhost. Set these headers on the application and runtime responses:
+
+```text
+Cross-Origin-Opener-Policy: same-origin
+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. Brotli variants require `brotli: true` and the corresponding server configuration.
+
+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.0/) for interoperability details.

package/dist/beam.d.ts

@@ -0,0 +1,10 @@
+import { type Result } from "./errors";
+import type { BeamBootOptions, BeamSendPayload } from "./types";
+export type Beam = {
+    boot: Promise<Result<null>>;
+    vmReady: Promise<void>;
+    send: (message: BeamSendPayload) => Result<null>;
+    writeStdin: (chunk: Uint8Array) => void;
+    resizeTty: (columns: number, rows: number) => void;
+};
+export declare function start(options: BeamBootOptions): Beam;

package/dist/errors.d.ts

@@ -1,45 +1,102 @@
-/** Error codes for recoverable errors returned in CallResult */
-export type PopcornErrorCode = "timeout" | "deinitialized" | "reload";
-/** Recoverable error returned in CallResult (never thrown) */
-export declare class PopcornError extends Error {
-    readonly code: PopcornErrorCode;
-    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_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;
-    constructor(code: PopcornInternalErrorCode, message?: string);
-}
-/** Internal errors - indicate bugs, protocol violations, or library misuse */
-type ErrorData = {
-    t: "assert";
-} | {
-    t: "private_constructor";
-} | {
-    t: "bad_call";
-} | {
-    t: "no_acked_call";
-} | {
-    t: "bad_ack";
+/**
+ * An operation result. Check `ok` before accessing `data` or `error`.
+ * Expected failures use the error branch. Invalid usage can still throw.
+ */
+export type Result<T, E extends Tag = Tag> = {
+    ok: true;
+    data: T;
 } | {
-    t: "already_mounted";
-} | {
-    t: "unmounted";
-} | {
-    t: "bad_target";
+    ok: false;
+    error: PopcornError<E>;
+};
+type Tag = keyof PopcornErrors;
+/** Error tags and their structured details. Match tags instead of message text. */
+export type PopcornErrors = {
+    "timeout:init": {
+        timeoutMs: number;
+    };
+    "timeout:send": {
+        timeoutMs: number;
+    };
+    "timeout:call": {
+        timeoutMs: number;
+    };
+    "worker:load": {
+        message: string;
+    };
+    "vm:exited": VmExitedData;
+    "bridge:not-started": EmptyData;
+    "bridge:invalid-target": EmptyData;
+    "bridge:unserializable": UnserializableData;
+    "bridge:listener-not-found": {
+        targetName: string;
+    };
+    "genserver:noproc": {
+        target: string;
+    };
+    "genserver:exit": {
+        reason: string;
+    };
+    "genserver:unserializable": EmptyData;
+    "stdio:overflow": {
+        capacityBytes: number;
+        attemptedBytes: number;
+    };
+    "beam:missing-boot-script": {
+        url: string;
+    };
+    "beam:missing-manifest": {
+        url: string;
+    };
+    "beam:missing-tarball": {
+        name: string;
+        all: string[];
+    };
+    "internal:check": {
+        detail?: string;
+    };
+    "internal:unreachable": EmptyData;
+    "runtime:eval-unavailable": EmptyData;
+};
+/** Error tag and details without the Error instance or stack. */
+export type SerializedError<T extends Tag = Tag> = {
+    [K in T]: {
+        t: K;
+        data: PopcornErrors[K];
+    };
+}[T];
+type EmptyData = Record<never, never>;
+export type UnserializableReason = "cyclic-object" | "non-plain-object" | "lossy-int" | "non-finite-float" | "unsupported";
+type UnserializableData = {
+    data: unknown;
+    part: unknown;
+    reason: UnserializableReason;
+};
+type VmExitedData = {
+    reason: "deinit";
 } | {
-    t: "bad_status";
-    status: string;
-    expectedStatus: string;
+    reason: "abort";
+    data: string;
 } | {
-    t: "app_ready_timeout";
+    reason: "error";
+    data: string;
 } | {
-    t: "bundle_not_found";
-    primary: string;
-    fallback: string;
+    reason: "exit";
+    data: number;
 };
-export declare function buildError(error: ErrorData): PopcornInternalError;
-export declare function throwError(error: ErrorData): never;
+export declare function err<T extends Tag>(t: T, data: PopcornErrors[T]): PopcornError<T>;
+export declare function isErr<T extends Tag = Tag>(error: unknown, t?: T): error is PopcornError<T>;
+/** @hidden */
+export declare class PopcornError<T extends Tag = Tag> extends Error {
+    readonly cause: SerializedError<T>;
+    private readonly serialized;
+    constructor(cause: SerializedError<T>);
+    get t(): T;
+    get data(): PopcornErrors[T];
+    /** Returns the tag and a shallow copy of its details. */
+    serialize(): SerializedError<T>;
+    /** Restores a serialized error. Throws if validation fails. */
+    static deserialize(value: unknown): PopcornError;
+}
+export declare function isUnserializableReason(value: unknown): value is UnserializableReason;
 export {};

package/dist/etf.d.ts

@@ -0,0 +1,38 @@
+import { type Result } from "./errors";
+declare class AtomTerm {
+    readonly name: string;
+    constructor(name: string);
+}
+declare class TupleTerm {
+    readonly entries: unknown[];
+    constructor(entries: unknown[]);
+}
+/**
+ * Creates a BEAM atom value.
+ *
+ * The atom must already exist in the receiving VM. Plain strings encode as binaries.
+ */
+export declare function atom(name: string): AtomTerm;
+/** Alias for {@link atom}. */
+export declare const a: typeof atom;
+/**
+ * Creates a BEAM tuple.
+ *
+ * Plain arrays encode as lists.
+ */
+export declare function tuple(first: unknown, second: unknown, ...rest: unknown[]): TupleTerm;
+/** Alias for {@link tuple}. */
+export declare const t: typeof tuple;
+/** Pre-encoded ETF sub-term bytes (no version prefix), spliced verbatim. */
+export declare class RawTerm {
+    readonly bytes: Uint8Array;
+    constructor(bytes: Uint8Array);
+    /**
+     * Wraps a full external term (`term_to_binary` output) as a spliceable
+     * sub-term by dropping its leading version byte.
+     */
+    static fromExternal(external: Uint8Array): RawTerm;
+}
+export type Mapper = (value: object) => object;
+export declare function encode(data: unknown, mapper?: Mapper): Result<Uint8Array<ArrayBuffer>, "bridge:unserializable">;
+export {};

package/dist/events.d.ts

@@ -0,0 +1,82 @@
+import { type Result, type SerializedError } from "./errors";
+import { type Mapper } from "./etf";
+import type { AnyValue, BeamBootOptions, BeamEvent, BeamSendPayload, BeamTarget } from "./types";
+type BootEvent = {
+    type: "popcorn:boot";
+    payload: Pick<BeamBootOptions, "emulatorArgs" | "extraArgs" | "env" | "ttySize"> & {
+        otpAssetsRoot?: string;
+    };
+};
+type StdinEvent = {
+    type: "popcorn:stdin";
+    payload: {
+        chunk: Uint8Array;
+    };
+};
+type TtyResizeEvent = {
+    type: "popcorn:tty-resize";
+    payload: {
+        columns: number;
+        rows: number;
+    };
+};
+type SendEvent = {
+    type: "popcorn:send";
+    payload: SendRequestPayload;
+};
+export type RunJsReplyPayload = {
+    message: BeamSendPayload;
+};
+type RunJsReplyEvent = {
+    type: "popcorn:run-js-reply";
+    payload: RunJsReplyPayload;
+};
+export type SendRequestPayload = {
+    id: string;
+    message: BeamSendPayload;
+};
+export type SerializedSendResult = {
+    ok: true;
+    data: null;
+} | {
+    ok: false;
+    error: SerializedError;
+};
+export type SendCompletionPayload = {
+    id: string;
+    result: SerializedSendResult;
+};
+type SendEndEvent = {
+    type: "popcorn:send-end";
+    payload: SendCompletionPayload;
+};
+type BootEndEvent = {
+    type: "popcorn:boot-vm-ready";
+    payload: {};
+} | {
+    type: "popcorn:boot-end";
+    payload: {};
+} | {
+    type: "popcorn:boot-fail";
+    payload: SerializedError;
+};
+export type MainToVmEvent = BootEvent | SendEvent | RunJsReplyEvent | StdinEvent | TtyResizeEvent;
+/**
+ * A decoded BEAM message payload.
+ *
+ * Includes restored PID handles and tracked JavaScript values.
+ */
+export type PopcornEvent = AnyValue;
+type RuntimeEvent = BeamEvent | SendEndEvent;
+export type VmToMainEvent = RuntimeEvent | BootEndEvent;
+export declare function readMainEvent(value: unknown): MainToVmEvent;
+export declare function readWorkerEvent(value: unknown): VmToMainEvent;
+export declare function serializeSendPayload(target: BeamTarget, payload: AnyValue, mapper?: Mapper): Result<BeamSendPayload, "bridge:unserializable">;
+export declare function deserializeBridgeMessage(text: string): Extract<BeamEvent, {
+    type: "otp:message" | "otp:error" | "otp:run_js";
+}> | null;
+/** Usable only from main context. */
+export declare function toVm(worker: Worker, event: MainToVmEvent, transfer?: Transferable[]): void;
+/** Usable only from webworkers. */
+export declare function toMain(event: VmToMainEvent): void;
+export {};

package/dist/index.d.ts

@@ -1,3 +1,7 @@
-export { Popcorn, PopcornError, PopcornInternalError } from "./popcorn";
-export type { PopcornErrorCode, PopcornInternalErrorCode, PopcornInitOptions, CastOptions, CallOptions, } from "./popcorn";
-export type { AnySerializable } from "./types";
+export { PopcornError } from "./errors";
+export { a, atom, t, tuple } from "./etf";
+export { Popcorn, schedulers } from "./popcorn";
+export type { PopcornOpts, SchedulerOptions, GenServer } from "./popcorn";
+export type { PopcornEvent } from "./events";
+export type { AnyValue, Pid, OtpErrorPayload, TtySize } from "./types";
+export type { PopcornErrors, Result, SerializedError } from "./errors";