This version of the module is deprecated: This package is deprecated. moonbit-community/proton should be preferred.

    #proton/core

    justjavac/proton/core owns the bridge between native MoonBit code and page JavaScript.

    It provides:

    • extension specs and installation
    • op registration and dispatch
    • resource tables
    • window.__MoonBit__ bridge setup
    • extension events

    Application lifecycle belongs in runtime; app composition belongs in the root proton facade.

    AppCommandHost

    type AppCommandHost

    Command host for user app code.

    The framework decides how this host is connected to the window runtime. App authors register commands and run the host without depending on the underlying IPC implementation.

    AppCommandHost::close

    fn AppCommandHost::close(self : AppCommandHost) -> Unit

    Closes this command host and rejects future dispatches.

    AppCommandHost::dispatch_ipc

    Dispatches one IPC request on the current async loop.

    AppCommandHost::emit_extension

    async fn[Payload : ToJson] AppCommandHost::emit_extension(self : AppCommandHost, extension_namespace : String, event_name : String, payload : Payload) -> Unit

    Emits one extension event through the installed IPC event sender.

    AppCommandHost::new

    Creates an empty app command host.

    AppCommandHost::op

    fn[Payload :
    FromJson
    , Reply : ToJson] AppCommandHost::op(self : AppCommandHost, name : String, callback : (Payload) -> Reply) -> Unit

    Registers a synchronous app command.

    AppCommandHost::op_async

    fn[Payload :
    FromJson
    , Reply : ToJson] AppCommandHost::op_async(self : AppCommandHost, name : String, callback : async (Payload) -> Reply) -> Unit

    Registers an async app command.

    AppCommandHost::op_async_result

    fn[Payload :
    FromJson
    , Reply : ToJson] AppCommandHost::op_async_result(self : AppCommandHost, name : String, callback : async (Payload) -> Result[Reply, String]) -> Unit

    Registers an async app command that can return a string error.

    AppCommandHost::op_result

    fn[Payload :
    FromJson
    , Reply : ToJson] AppCommandHost::op_result(self : AppCommandHost, name : String, callback : (Payload) -> Result[Reply, String]) -> Unit

    Registers a synchronous app command that can return a string error.

    AppCommandHost::registered_ops

    fn AppCommandHost::registered_ops(self : AppCommandHost) -> Array[String]

    Returns registered command names in registration order.

    AppCommandHost::seal_registrations

    fn AppCommandHost::seal_registrations(self : AppCommandHost) -> Unit

    Prevents later command registration while keeping existing commands usable.

    AppCommandHost::set_event_sender

    fn AppCommandHost::set_event_sender(self : AppCommandHost, emit : async (
    IpcExtensionEvent
    ) -> Unit) -> Unit

    Installs the process-level event sender used by command extensions.

    The sender is intentionally not request-scoped: extension events are broadcast notifications and may be emitted after the triggering op returns.

    Extension

    type Extension

    Preferred top-level runtime abstraction for extending a @webview.Webview.

    Extension::id

    fn Extension::id(self : Extension) -> String

    Returns the stable extension id. This id is used for manifest selection, generated registries, and duplicate detection during installation.

    Extension::js_namespace

    fn Extension::js_namespace(self : Extension) -> String

    Returns the JavaScript namespace exposed by this extension. Runtime op names and window.__MoonBit__.<namespace> both use this value.

    Extension::new

    fn Extension::new(id : String, js_namespace : String, register : (ExtensionContext) -> Unit, on_install? : (ExtensionContext) -> Unit, on_destroy? : (ExtensionContext) -> Unit, scripts? : Array[String]) -> Extension

    Builds an extension value that can later be installed on a @webview.Webview or ExtensionHost.

    ExtensionBuildContext

    type ExtensionBuildContext

    Build-time context passed to an extension spec when constructing one runtime extension.

    ExtensionBuildContext::base_dir

    fn ExtensionBuildContext::base_dir(self : ExtensionBuildContext) -> String?

    Returns the manifest base directory, when app creation came from a file. Extensions typically use this to resolve relative file paths from declarative configuration.

    ExtensionBuildContext::new

    fn ExtensionBuildContext::new(options? : Json?, base_dir? : String?) -> ExtensionBuildContext

    Creates an extension build context. Specs receive this value when they need manifest-provided options or a base directory while constructing one runtime extension instance.

    ExtensionBuildContext::options

    Returns the JSON options configured for this extension. Specs can read this to interpret manifest-time configuration before constructing their runtime behavior.

    ExtensionContext

    type ExtensionContext

    Registration context handed to an extension during installation.

    ExtensionContext::emit

    fn[Payload : ToJson] ExtensionContext::emit(self : ExtensionContext, event_name : String, payload : Payload) -> Unit

    Emits an extension-scoped event to JavaScript. Listeners receive the event under this extension's namespace on the shared window.__MoonBit__.events channel.

    ExtensionContext::id

    fn ExtensionContext::id(self : ExtensionContext) -> String

    Returns the stable extension id currently being installed. Extension callbacks can use this when they need to surface manifest- or tooling-facing identities.

    ExtensionContext::js_namespace

    fn ExtensionContext::js_namespace(self : ExtensionContext) -> String

    Returns the JavaScript namespace currently being installed. Extension callbacks should use this when emitting events or deriving runtime op names.

    ExtensionContext::op

    fn[Payload :
    FromJson
    , Reply : ToJson] ExtensionContext::op(self : ExtensionContext, api_name : String, callback : (Payload) -> Reply) -> Unit

    Registers a typed extension op exposed through window.__MoonBit__. The callback input is decoded from JSON and the reply is re-encoded before being returned to JavaScript callers.

    ExtensionContext::op_result

    fn[Payload :
    FromJson
    , Reply : ToJson] ExtensionContext::op_result(self : ExtensionContext, api_name : String, callback : (Payload) -> Result[Reply, String]) -> Unit

    Registers a typed extension op that can return explicit errors. Returning Err(message) surfaces a structured failure back to JavaScript instead of forcing the callback to abort.

    ExtensionContext::webview

    Returns the underlying webview that owns this extension host. Drop down to this accessor when an extension needs raw webview APIs or native handles.

    ExtensionHost

    type ExtensionHost

    Primary host wrapper for registering ops-backed extensions.

    ExtensionHost::destroy

    fn ExtensionHost::destroy(self : ExtensionHost) -> Unit

    Drops all registered extension metadata. Registered destroy hooks run before caches are cleared so extensions can release native resources in a predictable order.

    ExtensionHost::emit

    fn[Payload : ToJson] ExtensionHost::emit(self : ExtensionHost, extension_namespace : String, event_name : String, payload : Payload) -> Unit

    Emits an extension-scoped event from the host to JavaScript. The payload is converted to JSON and dispatched on the owning webview's main event loop so JavaScript observers receive it safely.

    ExtensionHost::install

    fn ExtensionHost::install(self : ExtensionHost, extension : Extension) -> Unit

    Installs an extension into the host. Reserved namespaces plus duplicate ids or namespaces are rejected before JavaScript helpers, ops, and lifecycle hooks are registered.

    ExtensionHost::new

    Creates an extension host for a webview. Most callers should prefer extension_host(webview) so the default cached host is reused across helper layers.

    ExtensionHost::run

    fn ExtensionHost::run(self : ExtensionHost) -> Unit

    Runs the underlying webview loop. This is a convenience passthrough for code that already holds an ExtensionHost rather than the raw webview.

    ExtensionSpec

    type ExtensionSpec

    Declarative extension spec registered in application code.

    ExtensionSpec::build_default

    fn ExtensionSpec::build_default(self : ExtensionSpec) -> Result[Extension, String]

    Builds the runtime extension with default options and no base directory. It is useful for direct installation paths that do not need manifest-derived context.

    ExtensionSpec::build_extension

    fn ExtensionSpec::build_extension(self : ExtensionSpec, context : ExtensionBuildContext) -> Result[Extension, String]

    Builds the runtime extension using the provided build context. This is the low-level execution step behind app planning, generated registries, and declarative extension composition.

    ExtensionSpec::dependencies

    fn ExtensionSpec::dependencies(self : ExtensionSpec) -> Array[String]

    Returns the extension ids that must be resolved before this spec. App planning and tooling use this metadata to expand transitive dependencies deterministically.

    ExtensionSpec::id

    fn ExtensionSpec::id(self : ExtensionSpec) -> String

    Returns the extension spec id. This id is the stable manifest and tooling key used to select the extension.

    ExtensionSpec::js_namespace

    fn ExtensionSpec::js_namespace(self : ExtensionSpec) -> String

    Returns the JavaScript namespace exposed by the built runtime extension. This namespace is independent from the stable manifest/catalog id.

    ExtensionSpec::new

    fn ExtensionSpec::new(id : String, js_namespace : String, build : (ExtensionBuildContext) -> Result[Extension, String], dependencies? : Array[String]) -> ExtensionSpec

    Creates a declarative extension spec. Application code registers specs up front so app composition can stay explicit and build-time link plans remain reviewable.

    MbtProcessHost

    type MbtProcessHost

    Command host intended to run in the MBT process.

    The host is independent from @webview.Webview, so application code can use normal MoonBit syntax, state, and async handlers without living in the GUI process.

    MbtProcessHost::close

    fn MbtProcessHost::close(self : MbtProcessHost) -> Unit

    Closes this host and rejects future dispatches.

    MbtProcessHost::dispatch

    Dispatches one decoded IPC request.

    Async handlers complete later through complete; synchronous handlers call it before this function returns.

    MbtProcessHost::dispatch_async

    Dispatches one decoded IPC request on the current async loop.

    User command hosts use this path so async ops run inside the user process event loop instead of creating a nested event loop elsewhere.

    MbtProcessHost::dispatch_json

    fn MbtProcessHost::dispatch_json(self : MbtProcessHost, raw : String, complete : (
    IpcOpResponse
    ) -> Unit) -> Unit

    Parses and dispatches one JSON IPC request payload.

    MbtProcessHost::dispatch_json_async

    async fn MbtProcessHost::dispatch_json_async(self : MbtProcessHost, raw : String) ->
    IpcOpResponse

    Parses and dispatches one JSON IPC request payload on the current async loop.

    MbtProcessHost::new

    Creates an empty MBT-side command host.

    MbtProcessHost::op

    fn[Payload :
    FromJson
    , Reply : ToJson] MbtProcessHost::op(self : MbtProcessHost, name : String, callback : (Payload) -> Reply) -> Unit

    Registers a synchronous MBT-side op.

    MbtProcessHost::op_async

    fn[Payload :
    FromJson
    , Reply : ToJson] MbtProcessHost::op_async(self : MbtProcessHost, name : String, callback : async (Payload) -> Reply) -> Unit

    Registers an async MBT-side op.

    MbtProcessHost::op_async_result

    fn[Payload :
    FromJson
    , Reply : ToJson] MbtProcessHost::op_async_result(self : MbtProcessHost, name : String, callback : async (Payload) -> Result[Reply, String]) -> Unit

    Registers an async MBT-side op that can return a string error.

    MbtProcessHost::op_result

    fn[Payload :
    FromJson
    , Reply : ToJson] MbtProcessHost::op_result(self : MbtProcessHost, name : String, callback : (Payload) -> Result[Reply, String]) -> Unit

    Registers a synchronous MBT-side op that can return a string error.

    MbtProcessHost::registered_ops

    fn MbtProcessHost::registered_ops(self : MbtProcessHost) -> Array[String]

    Returns registered op names in registration order.

    ResourceTable

    type ResourceTable[T]

    Generic resource table for long-lived native handles exposed to JavaScript.

    ResourceTable::add

    fn[T] ResourceTable::add(self : ResourceTable[T], value : T) -> Int

    Stores one value and returns its new resource id. Resource ids grow monotonically for the lifetime of the table so callers can hand them to JavaScript or native code safely.

    ResourceTable::contains

    fn[T] ResourceTable::contains(self : ResourceTable[T], rid : Int) -> Bool

    Returns whether one resource id is currently registered. Use this for validation when incoming ids may have been released already.

    ResourceTable::get

    fn[T] ResourceTable::get(self : ResourceTable[T], rid : Int) -> T?

    Returns one resource by id when it is still registered. None means the id was never issued or has already been released.

    ResourceTable::new

    fn[T] ResourceTable::new() -> ResourceTable[T]

    Creates an empty resource table. Resource ids start at 1 so 0 can remain available as a sentinel in external protocols.

    ResourceTable::remove

    fn[T] ResourceTable::remove(self : ResourceTable[T], rid : Int) -> T?

    Removes one resource and returns its previous value when present. This is the normal release path for long-lived native handles exposed to JavaScript.

    ResourceTable::rids

    fn[T] ResourceTable::rids(self : ResourceTable[T]) -> Array[Int]

    Returns every currently registered resource id. The result is useful for bulk cleanup, diagnostics, or leak detection.

    TemplateReplacement

    type TemplateReplacement

    emit_extension

    fn[Payload : ToJson] emit_extension(webview :
    Webview
    , extension_namespace : String, event_name : String, payload : Payload) -> Unit

    Emits an extension-scoped event from the webview's default extension host. The event is serialized once and forwarded to JavaScript listeners under the extension's namespace and event name.

    emit_ipc_extension_event

    Emits one remote extension event into JavaScript.

    ensure_core_runtime

    fn ensure_core_runtime(webview :
    Webview
    ) -> Unit

    Ensures the core JavaScript bridge and native op binding are installed. Calling this repeatedly is safe because the default runtime is cached per webview identity.

    extension_host

    Returns the default extension host attached to this webview. The host is created lazily and cached with the default op runtime so later extension installs share one consistent bridge.

    install_core_bridge

    fn install_core_bridge(webview :
    Webview
    ) -> Unit

    Installs the core JavaScript bridge without creating a local op runtime.

    App windows use this as their baseline so they can later choose either the local op runtime or the multiprocess IPC runtime.

    install_extension

    fn install_extension(webview :
    Webview
    , extension : Extension) -> Unit

    Installs an extension into the webview's default extension host. This is the simplest way to expose one extension on a raw @webview.Webview without manually managing host lifetime.

    install_ipc_bridge_runtime

    fn install_ipc_bridge_runtime(webview :
    Webview
    , bridge_script : String, op_names : Array[String], extensions? : Array[
    IpcExtensionDescriptor
    ]) -> Unit

    Installs a remote-op bridge script on one webview.

    core only knows how to expose the JavaScript runtime surface. The concrete IPC transport is supplied as script text by another module, for example justjavac/proton/ipc/ws.

    install_ipc_extension

    Installs JavaScript metadata for one remote extension.

    The actual command handlers live in the user process; this function only exposes window.__MoonBit__.<namespace>.* helper methods in the webview.

    moonbit_global_name

    fn moonbit_global_name() -> String

    Returns the root JavaScript namespace used by Proton runtime helpers. JavaScript bridges and generated helper scripts should agree on this value when exposing Proton functionality on window.

    moonbit_op_binding_name

    fn moonbit_op_binding_name() -> String

    Returns the native/webview binding name used by the op bridge. Native dispatch glue and injected runtime scripts both use this name to route op calls through the same binding.

    render_js_template

    fn render_js_template(template : String, replacements : Array[TemplateReplacement]) -> String

    Applies a sequence of token replacements to a JavaScript template string. Replacements are processed in order, which allows later entries to build on earlier substitutions when generating runtime helper scripts.

    replacement

    fn replacement(token : String, value : String) -> TemplateReplacement

    Creates a single token replacement entry for render_js_template. This keeps call sites readable when several template tokens need to be substituted together.