JavaScript objects

Mango injects window.grove at document start in packaged extension pages. You can use the global grove directly without an import or SDK. This reference describes the current Grove API 1 preview in Mango 3.1; additive members may be absent in older preview builds.

Global objects

WebKit is a browser runtime: Node.js objects such as process, Buffer, require, and filesystem modules are unavailable. Bundle dependencies for the browser. WebRTC entry points are disabled. There is no raw IRC send, ambient filesystem, native notification, or general native-code API. Standard browser availability depends on the OS WebKit version.

Settings pages receive the facade but have application scope, no IRC routing, and no network host permissions. A packaged page opened by grove.webPane.open receives no Grove facade. See Storage and settings and Security model.

Grove object

The facade, its namespaces, and its context objects are frozen. The presence of a function does not mean the user granted it. Mango checks permissions and scope natively on each operation.

Every callable has its own page in the API Reference navigation. Names beginning with __, including native delivery/resolution hooks and window.__groveFilter / window.__groveUpload, are host internals and are not extension APIs.

Function index

grove.info

interface GroveInfo {
  readonly id: string
  readonly api: 1
  readonly networkID: string
  readonly scope: {
    readonly kind: 'application' | 'server' | 'channel' | 'query'
    readonly target: string | null
  }
}

Context is available synchronously; there is no ready Promise. Register listeners during initial script execution. Application Roots may have multiple mirrored runtimes: globals are local to one runtime, even when storage is shared.

Calling conventions

Signatures in this reference use TypeScript notation to explain JavaScript values; no TypeScript declarations or constructors are installed by Mango. Optional parameters use ?. Supply the documented types even where the facade happens to coerce numbers or strings.

Most methods return undefined immediately. await grove.send(...) does not wait for delivery and cannot catch a native refusal. Promise APIs explicitly document their resolved values and rejections; secret writes and deletes resolve to null, not undefined. Error messages are diagnostic text rather than stable machine-readable codes.

Calls are tied to the current document. Reload, stop, crash, or suspension can interrupt pending work; no API promises durable execution across a restart. Validate inputs before calling, handle Promise failures, and use the Grove Console when a fire-and-forget operation is refused.

Some facade validation throws synchronously, notably composer binary uploads and overlong web-pane values. Malformed values can also be dropped at the native bridge; do not assume every malformed Promise request will settle.

Current request-decoding limitations

An unsupported mode for Blowfish encryption or decryption, or a non-integer offset/length for file.read(), can fail native decoding without rejecting the JavaScript Promise. A catch handler cannot recover from a Promise that never settles. Validate these inputs before calling: use only the literal modes ‘ecb’ or ‘cbc’, and use Number.isSafeInteger for byte offsets and lengths in addition to the documented range checks. The examples on those pages use valid literal modes or integer chunk sizes.

These are current API 1 implementation limitations, not intended guarantees for future versions. A JavaScript timeout may release your UI from waiting, but it does not cancel native work; do not automatically retry a timed-out side effect.

Objects passed to callbacks or returned

Upload handlers receive a frozen file object and context object. Their methods are documented as file.read and context.progress. Native network requests return a frozen response with synchronous text() and json() methods; it is not a browser Response. Events and filter messages are ordinary payload objects; their shapes are documented in the event and filter reference.