Capabilities and permissions

Request capabilities

Declare the APIs your plugin needs in manifest.json:

{
  "name": "Topic highlighter",
  "version": 1,
  "api": { "data": true, "map": true, "ui": true }
}

Supported keys are ui, kv, theme, app, data, map, and editor. Omit an API to leave it unrequested: the current manifest parser treats a key's presence as a request, so setting it to false does not disable it. Custom note blocks require both editor and ui.

Inside a plugin, this.available('map') reports whether that API was mounted. Host permissions and access are checked separately when calls are made.

Approve and stop

• The user approves the requested APIs before execution.
• Live preview connects windows signed in to the same account. Approval happens in the target window.
• Saved edits reuse the session's existing grants. Adding a capability requires fresh approval.
• Stop removes the plugin's live interface, drawings, subscriptions, and sandbox. Stored key/value state and saved note content remain.
• Changing the target map, losing access, or disconnecting the editor ends the preview session; disconnect cleanup follows its session timeout.

Scope

Plugins are currently private projects. Map data and graphics are limited to the map approved for that preview session. A plugin cannot use the data API to switch to another map.

The data API is read-only. The editor API can save its own custom block data through Emberly's note editor. The kv API stores private state belonging to the current user and plugin; shared-map storage semantics are not implemented.

Plugin interfaces use a restricted virtual DOM. Plugin code does not receive direct access to Emberly's host DOM. Only run code you trust: the current iframe runtime does not provide hard CPU isolation against an infinite loop.

Not available yet

• General topic, resource, and map data mutations
• Cross-map data access
• Shared key/value storage
• Theme subscriptions and overrides
• Full historical rendering APIs, including textures and widgets
• ML APIs

This reference covers the implemented Emberly subset, not every API from the original plugin-system reference.