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

    #Proton Native

    justjavac/proton/native is the direct MoonBit FFI binding for the standalone Proton native dynamic library.

    The public API uses Proton-owned Runtime and Window values. Raw native handles are intentionally not part of the public surface.

    ///|
    test "native ABI is loaded" {
    inspect(abi_version(), content="1")
    let info = runtime_info()
    inspect(info.abi_version, content="1")
    assert_true(info.build_mode == "abi-only" || info.build_mode == "runtime")
    assert_true(info.runtime_available == (info.build_mode == "runtime"))
    assert_true(info.features.contains("event_polling"))
    assert_true(info.features.contains("bridge_polling"))
    }

    Runtime configuration is typed on the MoonBit side and serialized to the stable proton_* C ABI JSON format.

    ///|
    test "typed runtime config JSON" {
    let config = RuntimeConfig::new(
    runtime_root="app-runtime",
    helper_path="cef_process.exe",
    cache_dir="cache",
    )
    let json = config.to_json_string()
    assert_true(json.contains("\"abi_version\":1"))
    assert_true(json.contains("\"runtime_root\":\"app-runtime\""))
    assert_true(json.contains("\"helper_path\":\"cef_process.exe\""))
    assert_true(json.contains("\"cache_dir\":\"cache\""))
    }

    For packaged Proton runtimes, prefer RuntimeConfig::bundled(). It asks proton.dll to use the install layout beside the loaded DLL, including bin/cef_process.exe, instead of requiring application code to hard-code paths.

    ///|
    test "bundled runtime config JSON" {
    let json = RuntimeConfig::bundled(cache_dir="cache").to_json_string()
    assert_true(json.contains("\"use_bundled\":true"))
    assert_true(json.contains("\"cache_dir\":\"cache\""))
    }

    The default no-engine build supports fake runtime/window handles for ABI and binding validation. Real runtime configs that include runtime_root or helper_path, or use RuntimeConfig::bundled(), are treated as engine configs and must pass RuntimeConfig::probe.

    ///|
    test "runtime and window lifecycle" {
    let runtime = Runtime::new()
    let window = Window::new(
    runtime,
    config=WindowConfig::new(
    title="Proton",
    width=320,
    height=240,
    initial_url="about:blank",
    ),
    )
    match runtime.poll_event() {
    Some(event) => inspect(event.event_type(), content="window_created")
    _ => fail("expected window_created")
    }
    window.load_html("<p>Hello Proton</p>", "proton://app/")
    window.destroy()
    runtime.destroy()
    }

    Runtime::wait is a low-level primitive for hosts that own the external message pump. It reports which kinds of work may be ready, and the caller still drains events or bridge requests through the poll APIs. The root facade does not use it on macOS: run_app owns CEF's native message loop and wakes the MoonBit application thread through Runtime::set_wakeup_fd.

    ///|
    test "runtime wait event readiness" {
    let runtime = Runtime::new()
    let empty = runtime.wait(interest_mask=runtime_wait_event, timeout_ms=0)

    inspect(empty.is_timeout(), content="true")
    let window = Window::new(runtime)
    let ready = runtime.wait(interest_mask=runtime_wait_event, timeout_ms=0)

    inspect(ready.has_event(), content="true")
    match runtime.poll_event() {
    Some(event) => inspect(event.event_type(), content="window_created")
    _ => fail("expected window_created")
    }
    window.destroy()
    runtime.destroy()
    }

    NativeError

    pub(all) suberror NativeError {
    Status(status~ : Int, message~ : String)
    InvalidArgument(message~ : String)
    InvalidPayload(context~ : String, message~ : String)
    } derive(Eq,
    Debug
    )

    Failures at the MoonBit/native runtime boundary.

    NativeError::is_stale_bridge_response

    fn NativeError::is_stale_bridge_response(self : NativeError) -> Bool

    Reports whether a bridge response lost its renderer request while an asynchronous handler was still completing.

    NativeError::message

    fn NativeError::message(self : NativeError) -> String

    NativeError::status

    fn NativeError::status(self : NativeError) -> Int

    BridgeConfig

    pub(all) struct BridgeConfig {
    raw_json : String?
    ops : Array[String]
    max_payload_bytes : Int
    request_timeout_ms : Int
    dev_origins : Array[String]
    extensions : Array[BridgeExtensionConfig]
    initialization_units : Array[BridgeInitializationUnit]
    } derive(Eq,
    Debug
    )

    BridgeConfig::new

    fn BridgeConfig::new(ops~ : Array[String], max_payload_bytes? : Int, request_timeout_ms? : Int, dev_origins? : Array[String], extensions? : Array[BridgeExtensionConfig], initialization_units? : Array[BridgeInitializationUnit]) -> BridgeConfig

    BridgeConfig::to_json_string

    fn BridgeConfig::to_json_string(self : BridgeConfig) -> String

    BridgeConfig::unsafe_from_json

    fn BridgeConfig::unsafe_from_json(raw_json : String) -> BridgeConfig

    BridgeDiagnostic

    pub(all) struct BridgeDiagnostic {
    abi_version : Int
    stage : String
    code : String
    message : String
    page_instance : String
    url : String
    owner : String?
    source_url : String?
    source_line : String?
    line : Int?
    column : Int?
    stack : String?
    additional_failure_count : Int?
    details_truncated : Bool
    } derive(Eq,
    Debug
    ,
    FromJson
    )

    BridgeExtensionConfig

    pub(all) struct BridgeExtensionConfig {
    js_namespace : String
    apis : Array[String]
    } derive(Eq,
    Debug
    )

    One JavaScript namespace installed by the renderer bootstrap.

    BridgeExtensionConfig::new

    fn BridgeExtensionConfig::new(js_namespace : String, apis~ : Array[String]) -> BridgeExtensionConfig

    BridgeInitializationUnit

    pub(all) struct BridgeInitializationUnit {
    owner : String
    name : String
    source : String
    } derive(Eq,
    Debug
    )

    One ordered JavaScript initialization unit owned by an extension.

    BridgeInitializationUnit::new

    fn BridgeInitializationUnit::new(owner : String, name : String, source : String) -> BridgeInitializationUnit

    BridgeLifecycleState

    pub(all) struct BridgeLifecycleState {
    abi_version : Int
    revision : String
    outcome : String
    page_instance : String
    url : String
    failure_pending : Bool
    } derive(Eq,
    Debug
    ,
    FromJson
    )

    BridgeRequest

    pub(all) struct BridgeRequest {
    request_id : Int64
    window : Int64
    op : String
    payload : Json
    page_instance : String?
    } derive(
    Debug
    )

    BridgeRequest::op

    fn BridgeRequest::op(self : BridgeRequest) -> String

    BridgeRequest::page_instance

    fn BridgeRequest::page_instance(self : BridgeRequest) -> String?

    BridgeRequest::payload

    fn BridgeRequest::payload(self : BridgeRequest) -> Json

    BridgeRequest::request_id

    fn BridgeRequest::request_id(self : BridgeRequest) -> Int64

    BridgeRequest::window

    fn BridgeRequest::window(self : BridgeRequest) -> Int64

    BridgeResponse

    pub(all) enum BridgeResponse {
    Ok(request_id~ : Int64, payload~ : Json)
    Err(request_id~ : Int64, code~ : String, message~ : String)
    } derive(
    Debug
    )

    BridgeResponse::to_json_string

    fn BridgeResponse::to_json_string(self : BridgeResponse) -> String

    DialogLevel

    pub(all) enum DialogLevel {
    Info
    Warning
    Error
    } derive(Eq,
    Debug
    )

    DialogPollResult

    pub(all) enum DialogPollResult {
    Pending
    Ready(String)
    } derive(Eq,
    Debug
    )

    A top-level native menu and its items.
    fn Menu::new(label : String, items~ : Array[MenuItem]) -> Menu

    Creates a top-level menu.

    An application-level native menu bar.
    fn MenuBar::new(menus~ : Array[Menu]) -> MenuBar

    Creates an application-level menu bar.
    fn MenuBar::to_json_string(self : MenuBar) -> String

    Encodes this menu bar for the native ABI.
    fn MenuBar::unsafe_from_json(raw_json : String) -> MenuBar

    Creates a menu bar from unchecked native ABI JSON.
    type MenuItem derive(Eq,
    Debug
    )

    A command, separator, or platform role in a native menu.
    fn MenuItem::command(id : String, label : String, key? : String) -> MenuItem

    Creates an app command item. Activating it emits menu_command.
    fn MenuItem::role(role : String, label? : String, key? : String) -> MenuItem

    Creates an item backed by a platform menu role such as close or quit.
    fn MenuItem::separator() -> MenuItem

    Creates a menu separator.

    NativeNotificationClick

    pub(all) struct NativeNotificationClick {
    payload : String?
    } derive(Eq,
    Debug
    )

    A native notification activation, optionally carrying its application payload.

    NativeNotificationResult

    pub(all) enum NativeNotificationResult {
    Delivered
    Failed(String)
    } derive(Eq,
    Debug
    )

    ProcessResult

    pub(all) enum ProcessResult {
    MainProcess
    SubprocessHandled(Int)
    } derive(Eq,
    Debug
    )

    Runtime

    type Runtime

    Runtime::activate_wakeup_source

    fn Runtime::activate_wakeup_source(self : Runtime) -> Unit raise NativeError

    Activates a prepared wakeup source after its reader is connected.

    Runtime::begin_message_dialog

    fn Runtime::begin_message_dialog(self : Runtime, title : String?, message : String, level : DialogLevel) -> Int64 raise NativeError

    Runtime::destroy

    fn Runtime::destroy(self : Runtime) -> Unit raise NativeError

    Runtime::do_message_loop_work

    fn Runtime::do_message_loop_work(self : Runtime) -> Unit raise NativeError

    Advances one external-message-pump iteration for a low-level host.

    Managed application runners own the native message loop and reject this operation.

    Runtime::new

    fn Runtime::new(config? : RuntimeConfig) -> Runtime raise NativeError

    Runtime::next_wakeup_delay_ms

    fn Runtime::next_wakeup_delay_ms(self : Runtime) -> Int? raise NativeError

    Returns the delay until CEF next needs its external message pump serviced, or None when no delayed pump is scheduled.

    Managed application runners own the native message loop and reject this operation.

    Runtime::poll_bridge_request

    fn Runtime::poll_bridge_request(self : Runtime) -> BridgeRequest? raise NativeError

    Runtime::poll_bridge_request_json

    fn Runtime::poll_bridge_request_json(self : Runtime) -> String? raise NativeError

    Runtime::poll_event

    fn Runtime::poll_event(self : Runtime) -> RuntimeEvent? raise NativeError

    Runtime::poll_event_json

    fn Runtime::poll_event_json(self : Runtime) -> String? raise NativeError

    Runtime::poll_message_dialog

    fn Runtime::poll_message_dialog(self : Runtime, dialog : Int64) -> Bool raise NativeError

    Runtime::prepare_wakeup_source

    fn Runtime::prepare_wakeup_source(self : Runtime) -> String raise NativeError

    Prepares a platform-owned wakeup source and returns its locator.

    Call activate_wakeup_source after opening the locator for reading.

    Runtime::quit

    fn Runtime::quit(self : Runtime) -> Unit raise NativeError

    Requests that a low-level host's CEF message loop stop.

    Managed application runners own the native message loop and reject this operation. Destroy the runtime to finish a managed application.

    Runtime::respond_bridge_request

    fn Runtime::respond_bridge_request(self : Runtime, response : BridgeResponse) -> Unit raise NativeError

    Runtime::run

    fn Runtime::run(self : Runtime) -> Unit raise NativeError

    Runs CEF's message loop for a low-level host.

    Managed application runners own this loop and reject this operation.

    Runtime::set_menu

    fn Runtime::set_menu(self : Runtime, menu : MenuBar) -> Unit raise NativeError

    Replaces the application-level native menu bar for this runtime.

    Runtime::set_wakeup_fd

    fn Runtime::set_wakeup_fd(self : Runtime, wakeup_fd : Int) -> Unit raise NativeError

    Installs the write end of a non-blocking pipe used to wake the host async runtime. The native runtime duplicates the descriptor and does not borrow the caller's ownership.

    Runtime::wait

    fn Runtime::wait(self : Runtime, interest_mask~ : Int, timeout_ms~ : Int) -> RuntimeWaitReady raise NativeError

    Waits for low-level external-pump work.

    Managed application runners use set_wakeup_fd instead and reject this operation.

    RuntimeConfig

    type RuntimeConfig derive(Eq,
    Debug
    )

    RuntimeConfig::bundled

    fn RuntimeConfig::bundled(helper_path? : String, cache_dir? : String, remote_debugging_port? : Int, headless? : Bool) -> RuntimeConfig

    helper_path, when set, overrides the subprocess executable the bundled runtime launches. On macOS the helper must run from a nested .app so Chromium's outer-bundle walk yields the same base bundle id as the browser; otherwise the MachPort rendezvous service names mismatch and every child process terminates. Framework and resource discovery still run relative to the loaded libproton, so only the helper needs an explicit path. Set headless to enable CEF off-screen rendering for every window.

    RuntimeConfig::new

    fn RuntimeConfig::new(runtime_root? : String, helper_path? : String, resources_dir? : String, locales_dir? : String, cache_dir? : String, remote_debugging_port? : Int, headless? : Bool) -> RuntimeConfig

    Builds an explicit native runtime configuration.

    Set headless to enable CEF off-screen rendering for every window created by this runtime. Remote debugging remains independently configurable.

    RuntimeConfig::probe

    fn RuntimeConfig::probe(self : RuntimeConfig) -> Unit raise NativeError

    RuntimeConfig::to_json_string

    fn RuntimeConfig::to_json_string(self : RuntimeConfig) -> String

    RuntimeConfig::unsafe_from_json

    fn RuntimeConfig::unsafe_from_json(raw_json : String) -> RuntimeConfig

    RuntimeEvent

    type RuntimeEvent derive(Eq,
    Debug
    )

    RuntimeEvent::event_type

    fn RuntimeEvent::event_type(self : RuntimeEvent) -> String

    RuntimeEvent::has_window

    fn RuntimeEvent::has_window(self : RuntimeEvent) -> Bool

    RuntimeEvent::is_bridge_lifecycle_changed

    fn RuntimeEvent::is_bridge_lifecycle_changed(self : RuntimeEvent) -> Bool

    RuntimeEvent::is_window_closed

    fn RuntimeEvent::is_window_closed(self : RuntimeEvent) -> Bool

    RuntimeEvent::is_window_created

    fn RuntimeEvent::is_window_created(self : RuntimeEvent) -> Bool

    RuntimeEvent::launch_input

    fn RuntimeEvent::launch_input(self : RuntimeEvent) -> RuntimeLaunchInput?

    Returns the typed application launch input carried by this event.

    RuntimeEvent::menu_command_id

    fn RuntimeEvent::menu_command_id(self : RuntimeEvent) -> String?

    The command id for an app-menu command item click, or None for every other event kind.

    RuntimeEvent::notification_result

    fn RuntimeEvent::notification_result(self : RuntimeEvent) -> NativeNotificationResult?

    RuntimeEvent::window_id

    fn RuntimeEvent::window_id(self : RuntimeEvent) -> Int64?

    Returns the window associated with this event when one exists. For an app menu command this is the focused window at click time.

    RuntimeInfo

    pub(all) struct RuntimeInfo {
    abi_version : Int
    runtime_available : Bool
    build_mode : String
    platform : String
    features : Array[String]
    } derive(Eq,
    Debug
    ,
    FromJson
    )

    RuntimeLaunchInput

    pub(all) enum RuntimeLaunchInput {
    OpenUrls(Array[String])
    OpenFiles(Array[String])
    Reopen
    } derive(Eq,
    Debug
    )

    A macOS application activation delivered by Launch Services or the Dock.

    RuntimeWaitReady

    pub(all) struct RuntimeWaitReady {
    mask : Int
    } derive(Eq,
    Debug
    )

    RuntimeWaitReady::has_bridge

    fn RuntimeWaitReady::has_bridge(self : RuntimeWaitReady) -> Bool

    RuntimeWaitReady::has_event

    fn RuntimeWaitReady::has_event(self : RuntimeWaitReady) -> Bool

    RuntimeWaitReady::has_platform

    fn RuntimeWaitReady::has_platform(self : RuntimeWaitReady) -> Bool

    RuntimeWaitReady::is_timeout

    fn RuntimeWaitReady::is_timeout(self : RuntimeWaitReady) -> Bool

    RuntimeWaitReady::mask

    fn RuntimeWaitReady::mask(self : RuntimeWaitReady) -> Int

    TitlebarStyle

    pub(all) enum TitlebarStyle {
    Default
    Overlay
    } derive(Eq,
    Debug
    )

    Window

    type Window

    Window::as_ref

    fn Window::as_ref(self : Window) -> WindowRef

    Borrows this owning window handle for APIs that must not destroy it.

    Window::bridge_lifecycle_state

    fn Window::bridge_lifecycle_state(self : Window) -> BridgeLifecycleState raise NativeError

    Window::close

    fn Window::close(self : Window) -> Unit raise NativeError

    Window::destroy

    fn Window::destroy(self : Window) -> Unit raise NativeError

    Window::emit_bridge_event_json

    fn Window::emit_bridge_event_json(self : Window, event_json : String) -> Unit raise NativeError

    Window::eval

    fn Window::eval(self : Window, script : String) -> Unit raise NativeError

    Window::focus

    fn Window::focus(self : Window) -> Unit raise NativeError

    Window::hide

    fn Window::hide(self : Window) -> Unit raise NativeError

    Window::id

    fn Window::id(self : Window) -> Int64

    Returns the stable native handle used to correlate runtime events.

    Window::load_html

    fn Window::load_html(self : Window, html : String, base_url : String) -> Unit raise NativeError

    Window::load_url

    fn Window::load_url(self : Window, url : String) -> Unit raise NativeError

    Window::new

    fn Window::new(runtime : Runtime, config? : WindowConfig) -> Window raise NativeError

    Window::set_size

    fn Window::set_size(self : Window, width : Int, height : Int) -> Unit raise NativeError

    Window::set_title

    fn Window::set_title(self : Window, title : String) -> Unit raise NativeError

    Window::show

    fn Window::show(self : Window) -> Unit raise NativeError

    Window::take_bridge_failure

    fn Window::take_bridge_failure(self : Window) -> BridgeDiagnostic? raise NativeError

    WindowConfig

    type WindowConfig derive(Eq,
    Debug
    )

    WindowConfig::new

    fn WindowConfig::new(title? : String, width? : Int, height? : Int, initial_url? : String, size_hint? : WindowSizeHint, titlebar_style? : TitlebarStyle, bridge? : BridgeConfig) -> WindowConfig

    WindowConfig::to_json_string

    fn WindowConfig::to_json_string(self : WindowConfig) -> String

    WindowConfig::unsafe_from_json

    fn WindowConfig::unsafe_from_json(raw_json : String) -> WindowConfig

    WindowRef

    type WindowRef derive(Eq,
    Debug
    )

    WindowRef::begin_choose_directory_dialog

    fn WindowRef::begin_choose_directory_dialog(self : WindowRef, title : String?, path : String?) -> Int64 raise NativeError

    WindowRef::begin_confirm_dialog

    fn WindowRef::begin_confirm_dialog(self : WindowRef, title : String?, message : String, level : DialogLevel) -> Int64 raise NativeError

    WindowRef::begin_message_dialog

    fn WindowRef::begin_message_dialog(self : WindowRef, title : String?, message : String, level : DialogLevel) -> Int64 raise NativeError

    WindowRef::begin_open_file_dialog

    fn WindowRef::begin_open_file_dialog(self : WindowRef, title : String?, path : String?) -> Int64 raise NativeError

    WindowRef::begin_save_file_dialog

    fn WindowRef::begin_save_file_dialog(self : WindowRef, title : String?, path : String?) -> Int64 raise NativeError

    WindowRef::poll_dialog_result

    fn WindowRef::poll_dialog_result(self : WindowRef, dialog : Int64) -> DialogPollResult raise NativeError

    WindowRef::unsafe_from_handle

    fn WindowRef::unsafe_from_handle(handle : Int64) -> WindowRef

    WindowSizeHint

    pub(all) enum WindowSizeHint {
    Unconstrained
    Fixed
    Min
    Max
    } derive(Eq,
    Debug
    )

    Controls how the configured width and height constrain native resizing.

    abi_version

    fn abi_version() -> Int

    execute_process

    fn execute_process(config? : RuntimeConfig) -> ProcessResult raise NativeError

    last_error_message

    fn last_error_message() -> String

    notification_cleanup

    fn notification_cleanup() -> Unit raise NativeError

    Releases process-level notification hooks installed by Proton.

    notification_poll_click

    fn notification_poll_click() -> NativeNotificationClick? raise NativeError

    Removes and returns the oldest pending notification activation.

    notification_show

    fn notification_show(title : String, body : String, payload? : String) -> Unit raise NativeError

    Schedules a native notification with an optional activation payload.

    notification_supported

    fn notification_supported() -> Bool raise NativeError

    Reports whether native notifications are available in the current process.

    probe_runtime

    fn probe_runtime(config? : RuntimeConfig) -> Unit raise NativeError

    run_app

    fn run_app(entry : FuncRef[() -> Unit]) -> Unit raise NativeError

    Runs entry on Proton's application thread while the caller owns the platform UI loop on runtimes that advertise managed_app_runner. Other platforms may execute entry inline.

    runtime_info

    fn runtime_info() -> RuntimeInfo raise NativeError

    runtime_info_json

    fn runtime_info_json() -> String raise NativeError

    runtime_wait_all

    let runtime_wait_all : Int

    runtime_wait_bridge

    let runtime_wait_bridge : Int

    runtime_wait_event

    let runtime_wait_event : Int

    runtime_wait_none

    let runtime_wait_none : Int

    runtime_wait_platform

    let runtime_wait_platform : Int