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.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
readyafter loading. - The host returns
initwith theinstanceId,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 iframecontentWindow.
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 sendsview.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.
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 inbridge.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.
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: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:- The source manifest allowlists the command key in
clientCommands. - The current host registers a handler for the same key.
- The Remote Component invokes it through
invokeClientCommandand handles a structured failure result.
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: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
Treatinit.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
hostTypeorhostId. - 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.