js: events api

Author: jgonet

examples/eval-in-wasm/lib/eval_in_wasm.ex

@@ -11,7 +11,7 @@ defmodule EvalInWasm do
 
   @impl GenServer
   def init(_args) do
-    Wasm.register(@process_name)
+    Wasm.set_default_receiver(@process_name)
     {:ok, nil}
   end
 

examples/game-of-life/lib/game_of_life.ex

@@ -4,8 +4,6 @@ defmodule GameOfLife do
   executing `run/0` when the app is ready.
   """
 
-  alias Popcorn.Wasm
-
   @doc false
   def child_spec(_arg) do
     %{
@@ -20,7 +18,6 @@ defmodule GameOfLife do
   """
   def run() do
     IO.puts("Running...\n")
-    Wasm.register("noop")
     :ignore
   end
 end

examples/hello-popcorn/lib/hello_popcorn.ex

@@ -9,7 +9,6 @@ defmodule HelloPopcorn do
 
   @impl true
   def init(_init_arg) do
-    Popcorn.Wasm.register(@process_name)
     IO.puts("Hello console!")
 
     Popcorn.Wasm.run_js("""

examples/hello-react/ex_app/lib/ex_app.ex

@@ -9,7 +9,7 @@ defmodule ExApp do
 
   @impl true
   def init(_init_arg) do
-    Popcorn.Wasm.register(@process_name)
+    Popcorn.Wasm.set_default_receiver(@process_name)
     IO.puts("Hello console!")
 
     # Popcorn.Wasm.run_js("""

examples/iex-wasm/lib/iex_wasm.ex

@@ -13,7 +13,7 @@ defmodule IexWasm do
 
   @impl GenServer
   def init(_args) do
-    Wasm.register(@process_name)
+    Wasm.set_default_receiver(@process_name)
     type = :elixir
     Shell.start_link(type: type)
     :ok = ExTTY.send_text(:"#{type}_tty", ":ok\n")

language-tour/elixir_tour/lib/elixir_tour.ex

@@ -21,7 +21,7 @@ defmodule ElixirTour do
 
   @impl GenServer
   def init(_init_arg) do
-    Wasm.register(@process_name)
+    Wasm.set_default_receiver(@process_name)
     :application.set_env(:elixir, :ansi_enabled, false)
     {:ok, %{editor_order: [], bindings: %{}}}
   end

local-live-view/lib/local_live_view/dispatcher.ex

@@ -21,7 +21,7 @@ defmodule LocalLiveView.Dispatcher do
 
   @impl true
   def init(_init_arg) do
-    Popcorn.Wasm.register(@process_name)
+    Popcorn.Wasm.set_default_receiver(@process_name)
     {:ok, %{views: []}}
   end
 

popcorn/elixir/lib/popcorn.ex

@@ -181,7 +181,7 @@ defmodule Popcorn do
         end
       end
 
-    no_warn_undefined = [:atomvm | List.wrap(start_module)]
+    no_warn_undefined = [:atomvm, Popcorn.Wasm | List.wrap(start_module)]
 
     # The module below tries to mimic BEAMs boot script, then start user's app
     contents =
@@ -208,6 +208,8 @@ defmodule Popcorn do
 
           {:ok, _apps} = Application.ensure_all_started(unquote(app), :permanent)
 
+          Popcorn.Wasm.send_event("popcorn_elixir_ready")
+
           unquote(run)
         end
       end

popcorn/elixir/lib/popcorn/api/wasm.ex

@@ -240,19 +240,37 @@ defmodule Popcorn.Wasm do
   end
 
   @doc """
-  Notifies JS that Elixir side finished initializing. Can be called only once.
+  Sends an event to JS side. Fire-and-forget.
   """
-  def register(main_process_name) do
+  @spec send_event(String.t()) :: :ok
+  @spec send_event(String.t(), term()) :: :ok
+  def send_event(event_name, payload \\ nil) when is_binary(event_name) do
     """
     ({ wasm, args }) => {
-      wasm.onElixirReady?.(args.main);
+      wasm.sendEvent(args.eventName, args.payload)
     }
     """
-    |> run_js(%{main: to_string(main_process_name)})
+    |> run_js(%{eventName: event_name, payload: payload}, return: :ref)
 
     :ok
   end
 
+  @doc """
+  Sets the default receiver process for JS calls/casts.
+  Registers the calling process under `name` if not already registered.
+  """
+  @spec set_default_receiver(atom()) :: :ok
+  def set_default_receiver(name) when is_atom(name) do
+    case Process.whereis(name) do
+      nil -> Process.register(self(), name)
+      pid when pid == self() -> :ok
+      _other -> raise "Name #{name} already registered to another process"
+    end
+
+    send_event("popcorn_set_default_receiver", %{name: to_string(name)})
+    :ok
+  end
+
   @doc """
   Registers event listener for element with given `selector`. Events will be sent to the process registered under `target` name.
   To get event data, specify needed keys in `event_keys` list.

popcorn/elixir/pages/elixir-api.md

@@ -13,20 +13,38 @@ Represents opaque reference to JS value. Automatically cleaned up when garbage c
 
 ## Core Functions
 
-### `register(main_process_name)`
+### `send_event(event_name, payload \\ nil)`
 
-Notifies JS that Elixir side finished initializing. Can be called only once.
+Sends an event to the JS side. Fire-and-forget.
 
 **Parameters:**
 
-- `main_process_name` (atom or string) - Name of the main process that will receive JS messages by default.
+- `event_name` (string) - Name of the event.
+- `payload` (any, optional) - Event payload. Default: `nil`.
 
 **Returns:** `:ok`.
 
 **Example:**
 
 ```elixir
-Popcorn.Wasm.register(:main)
+Popcorn.Wasm.send_event("processing_finished", %{id: 123})
+Popcorn.Wasm.send_event("simple_event")
+```
+
+### `set_default_receiver(name)`
+
+Sets the default receiver process for JS calls/casts. Registers the calling process under `name` if not already registered.
+
+**Parameters:**
+
+- `name` (atom) - Process name to register as default receiver.
+
+**Returns:** `:ok`.
+
+**Example:**
+
+```elixir
+Popcorn.Wasm.set_default_receiver(:main)
 ```
 
 ### `handle_message!(raw_message, handler)`