Reference
Arcane.external.open()
Hands a validated URI to the operating system's registered default application. opened: true means only that the OS accepted the handoff, not that a composer opened or a message was sent. Simulation fails explicitly instead of claiming a handoff. Requires external.open.
This focused page is derived from the mechanically checked full member inventory.
Syntax
Arcane.external.open(uri)
Parameters
Exact printable-ASCII URI without whitespace, fragments, backslashes, malformed escapes, or encoded controls; currently mailto: only
Return value
Promise<{opened, uri}>
Description
Hands a validated URI to the operating system's registered default application. opened: true means only that the OS accepted the handoff, not that a composer opened or a message was sent. Simulation fails explicitly instead of claiming a handoff. Requires external.open.
Overview
Arcane.external.open(uri) hands one validated mailto: URI to the operating
system's registered handler. It requires the external.open grant and an
admitted Core or Android host. The call is non-idempotent, emits no Arcane
event, and simulation rejects it instead of pretending to open another app.
The URI may be at most 4096 printable ASCII characters. It must have no leading
or trailing whitespace, raw spaces, fragment, backslash, malformed percent
escape, or raw or percent-encoded control character. Only mailto: is
accepted; percent-encode query values with encodeURIComponent().
Result and side effect
The exact result is { opened: true, uri }, with the scheme canonicalized to
lower-case mailto:. opened: true means only that the host accepted the
operating-system handoff. It does not prove that a composer appeared or that a
message was sent. On Microsoft NT the host uses the system URI handler; Linux
requires xdg-open; Android launches an admitted intent handler.
Errors and recovery
EXTERNAL_SCHEME_NOT_ALLOWED means the URI is not mailto:.
EXTERNAL_OPEN_INVALID identifies malformed input. EXTERNAL_OPEN_SIMULATED
and EXTERNAL_OPEN_UNSUPPORTED require a real host with a configured handler.
EXTERNAL_OPEN_FAILED means the OS did not accept the handoff. Do not retry
blindly after a timeout because the first handoff may already have occurred.
Example
document.querySelector('#open-support-email')?.addEventListener(
'click',
async function handleSupportEmailRequest() {
const subject = encodeURIComponent('Arcane support request');
const uri = `mailto:support@example.com?subject=${subject}`;
const result = await Arcane.external.open(uri);
console.log('Operating-system handoff accepted', result.opened);
}
);