Developer Guide

Runtime

The extension runtime is the contract between your JS module and the app. The public docs now split that contract into focused reference pages so you can jump straight to the part you need without scanning one long article.

⚠

JS extensions run with normal browser privileges. The app validates the manifest and loader shape, but it does not sandbox arbitrary code.

What Lives Here

The source material for these pages is the extension authoring markdown used in the repo. This hub keeps the overview and versioning notes, then hands off the detailed field-by-field and API-by-API reference work to dedicated pages.

Reference Pages

Use the manifest page when you are shaping the module, the exports page when you are wiring behavior, the prompt page when you are tuning instruction policy, and the runtime API page when you need a concrete method reference.

Manifest fields

Required identity fields, optional UI surface fields, and capability flags.

Runtime exports

Core exports, lifecycle hooks, and the emergency stop hook.

Prompt contributions

Contribution shape, placement rules, request-time mutations, and usage patterns.

Runtime APIs

Artifacts, prompt helpers, variables, memories, chat, persona, media, and UI APIs.

API versioning

New extensions should target API v5. Older versions still load only while they remain within the runtime's minimum supported version window.

Initial JS runtime with manifest metadata, useExtension(), and browser-side tools.

Added extension-owned promptState for current toys and player information.

Added prompt contributions, lifecycle hooks, memories, chat, persona, media, and artifacts.

Added the chat footer drawer with manifest.chatFooter and optional FooterComponent support.

Added runtime.emergencyStop() so integration extensions can dispatch the same toy emergency stop the top-bar e-stop button uses, synchronously.

Added manifest.overlay and the OverlayComponent slot for stackable fullscreen extension overlays (hypnosis effects, sensor HUDs, and similar) mounted at the app root via React portal and z-ordered by overlay.order. Also adds runtime.chat.sendMessage() and runtime.chat.runTurn() for posting transcript messages and advancing the conversation from extensions, plus runtime.ui.toast() for transient non-blocking notifications.