Skip to main content

Remote Component Host Bridge

The host bridge connects a Remote Component iframe, the Workbench host, and the plugin View Provider. It is not a generic RPC tunnel: business capabilities require their manifest declaration, a host handler and, where applicable, a server implementation. The common context lifecycle event is delivered without a subscription.
The Remote Component sends business intent only. The host resolves the current user, host, tenant, and organization context and validates the view, feature, permissions, and capability declaration before calling the provider.

Three contract layers

The host must reject a capability when any layer is missing.

Message envelope

All messages use a fixed channel and protocol version:
  • The iframe sends ready after loading.
  • The host returns init with the instanceId, runtimeScope, scopeRevision, manifest, initial query, locale, theme and debug configuration.
  • Later messages must carry the matching instanceId.
  • Requests and responses share one requestId.
  • The iframe accepts messages only from window.parent; the host accepts messages only from the current iframe contentWindow.

Supported messages

Host to iframe: Iframe to host:

Capability mapping

Context changes without remounting

For the same authenticated identity, organization and Assistant, changing Project or conversation preserves the iframe. The host reauthorizes the target View and entry, suspends operations while resolving it, then sends view.context.changed to every mounted View, including hidden tabs. No manifest subscription or acknowledgment is required. init.runtimeScope and the event’s data.runtimeScope are complete snapshots. Unbound fields are null; use the target snapshot rather than merging it with old IDs. The current Angular host supplies Project/conversation fields; hosts supporting group routing may also supply groupId.
Revisions increase monotonically within one instance, not necessarily consecutively. Ignore stale revisions, reject pending work, clear selections and refresh or rebind against the new scope. Every subsequent request includes the latest scopeRevision. The host uses its own authorized context, never request-supplied scope, and rotates file sessions. Changing identity, organization, Assistant or entry, explicitly reloading, or closing the View destroys the old instance. Denied entry access removes the previous document. Cancellation or a discarded response does not undo a server mutation already committed.

TypeScript bridge client

Keep the bridge in bridge.ts; business components should not construct wire messages directly. This example targets hosts with context revisions and installs one bridge per iframe. Validate result payloads in typed business wrappers before using them.
In onContextChange, clear scope-dependent state before reloading or rebinding. If a wrapper does asynchronous processing after a response, capture currentScopeRevision() and compare it again before applying the processed result. Repeated init for the same revision may update theme/locale without resetting the selected resource. Build named wrappers such as requestData(), executeAction(), and invokeClientCommand() on top of this boundary. Return stable error codes from the bridge and translate them at the UI boundary.

Query data

XpertViewQuery.parameters accepts only scalar values or scalar arrays. Serialize a complex filter into one explicit JSON string parameter and parse it safely in the provider. Use server-side pagination for large tables. Do not load every record into the iframe.

Execute actions

Use JSON actions for normal business mutations:
The actionKey must exist in manifest.actions, and its transport must match. The provider still validates the target, current user, and tenant/organization scope. Use executeFileAction for uploads; do not put binary or Base64 content in JSON actions. Use requestFileAccess for previews and downloads so the host can issue a time-bounded grant.

Client commands

Client commands perform host-local UI behavior without calling the plugin provider. Examples include sending an Assistant message, setting Assistant context, opening a file, or navigating to another Workbench view. They form a closed three-party contract:
  1. The source manifest allowlists the command key in clientCommands.
  2. The current host registers a handler for the same key.
  3. The Remote Component invokes it through invokeClientCommand and handles a structured failure result.
Do not navigate the top window directly from the iframe.

Current host commands

Declare each command you use, check structured results and surface unavailable handlers or blocked popups. A manifest does not guarantee that every host implements a command. Never add tenant/workspace identity or credentials to these payloads.

Host events

A Remote Component can subscribe to normalized host events, such as a completed Agent middleware tool:
Declarative views normally use refresh. Prefer forward for Remote Components so they can refresh only the affected data. If local edits are dirty, do not silently replace them with remote state.

Initialization, theme, and locale

Treat init.locale as authoritative and normalize it once to a BCP 47 tag such as en-US, zh-Hans, or zh-Hant. Do not select copy with locale branches inside business components. After applying init.theme.tokens, call installShadcnThemeVars() to install semantic theme variables. Gate debug logging with init.debug.enabled; do not infer development mode from URLs, hostnames, or platform identity. Do not rely on localStorage or sessionStorage. Keep ephemeral state in React and persist durable state through the host bridge.

Security checklist

  • Do not pass access tokens, API URLs, Assistant IDs, tenant IDs, or organization IDs into the iframe.
  • Do not let the iframe select hostType or hostId.
  • Reject actions, file capabilities, and client commands that are absent from the manifest.
  • Do not log tokens, file contents, complete business snapshots, or personally sensitive data.
  • Re-run authorization and tenant/organization isolation for every provider read and mutation.
  • Test message source, protocol version, instance ID, request ID and revision boundaries, including a slow response after a context switch.
Return to Workbench Remote Components for the complete development workflow.