Embeddable Bridge Architecture

How GoGrab AI is embedded across different host applications, Chrome extensions, and standalone contexts.

Library: @libs-ux/embeddable-bridge Path: libs/libs-ux/embeddable-bridge/ Last updated: Session 105.3 (February 2026)

Table of Contents

1. Overview
2. Architecture Diagram
3. Three Embedding Approaches
4. URL Parameters Reference
5. Workspace Port Derivation
6. Bridge Event Model
7. Authentication Flows
8. Component Reference
9. Comparison Table
10. Troubleshooting

Overview

The Embeddable Bridge library enables the gograb-ai Angular application to be embedded inside other applications as an iframe with structured, type-safe communication. It provides:

• Iframe hosting with sandboxing, loading/error states, and auto-reconnection
• PostMessage bridge with origin validation, message typing, and heartbeat monitoring
• Workspace-aware port derivation so the same code works across editor2 (5xxx), gspace1 (6xxx), and future workspace clones
• Authentication forwarding via both URL parameters and bridge messages
• Drag-and-drop support from the embedded AI panel to the host canvas

The gograb-ai application serves two main routes for embedding:

Architecture Diagram

+---------------------------+       +---------------------------+
|  HOST APPLICATION         |       |  gograb-ai App            |
|  (gograb-space, admin,    |       |  (separate Angular app)   |
|   dev, or extension)      |       |                           |
|                           |       |  Routes:                  |
|  +---------------------+ |       |  /panel   -> Studio       |
|  | GoGrabAiPanelComponent|----+   |  /observatory -> Monitor  |
|  | or                   | |   |   |                           |
|  | GoGrabObservatoryComp| |   |   |  +---------------------+ |
|  +---------------------+ |   |   |  | EmbeddedAdapterSvc   | |
|           |               |   |   |  | - Listens for msgs   | |
|  +---------------------+ |   |   |  | - Sends replies       | |
|  | EmbeddableHostComp   | |   |   |  | - URL param auth      | |
|  | - Creates <iframe>   | |   |   |  +---------------------+ |
|  | - HostAdapterService | |   |   +---------------------------+
|  | - Origin validation  |-----|-->   iframe (sandboxed)
|  | - Heartbeat monitor  | |   |      src="http://localhost:
|  +---------------------+ |   |       6400/panel?embedded=true
|                           |   |       &theme=dark&..."
+---------------------------+   |
                                |
    PostMessage Bridge  <-------+
    (bidirectional, typed)

Three Embedding Approaches

1. Direct Component (Native)

Used when the AI panel lives in the same Angular application as the host.

• Where: gograb-space main layout
• Component: <lib-ai-panel> (from @libs-ai/vitto-hub)
• Communication: Direct Angular inputs/outputs, shared DI tree
• Auth: Shared Angular auth service (same app context)
• No iframe, no bridge, no port concerns

Since Session 105.3, the native panel uses <ai-panel-tabs> which wraps both <lib-ai-panel> (Studio) and <agent-observatory> (Observatory) with a tab switcher.

2. Embeddable Bridge (Cross-App Iframe)

Used when embedding the AI panel from a different Angular application via iframe.

• Where: gograb-admin, gograb-dev, or any Angular host
• Components: <gograb-ai-panel> or <gograb-observatory>
• Communication: PostMessage via HostAdapterService <-> EmbeddedAdapterService
• Auth: Bridge auth (host sends AI_AUTH_INIT after iframe is ready)
• Port: Auto-derived from host port via deriveAiPort()

3. Chrome Extension Iframe

Used when embedding inside the Chrome extension's side panel.

• Where: apps/gograb-ai-extension/sidepanel/
• Communication: Vanilla JS ExtensionBridgeAdapter (implements same protocol)
• Auth: URL parameters (token, userId, userEmail) -- primary path; bridge auth as fallback
• Port: Runtime probing across known ports (5400, 6400, 4200)
• Tab bar: Extension's sidepanel.html provides Studio/Observatory switching via separate iframes

URL Parameters Reference

When gograb-ai is loaded in an iframe, it reads parameters from the URL to configure its behavior.

/panel Route (Studio)

Example URL:

http://localhost:6400/panel?embedded=true&extension=true&theme=dark&userRole=developer

This URL means:

• localhost:6400 -- The gograb-ai app running on the gspace1 workspace (port 6400)
• /panel -- Loading the Studio route
• embedded=true -- Running inside an iframe (hides standalone header)
• extension=true -- Running inside the Chrome extension (uses URL-param auth)
• theme=dark -- Dark theme
• userRole=developer -- Full T1 developer access

/observatory Route

Example URL:

http://localhost:6400/observatory?embedded=true&mode=compact&controls=true&source=embed-component

Workspace Port Derivation

Each development workspace occupies a 1000-port range. The AI app is always at offset +400:

How deriveAiPort() Works

Located in libs/libs-ux/embeddable-bridge/src/lib/utils/workspace-ports.ts:

const AI_PORT_OFFSET = 400;

export function deriveAiPort(fallbackPort = 5400): number {
  if (typeof window === 'undefined') return fallbackPort;

  const hostPort = parseInt(window.location.port, 10);
  if (isNaN(hostPort) || hostPort < 4000 || hostPort > 9999) {
    return fallbackPort;
  }

  const workspaceBase = Math.floor(hostPort / 1000) * 1000;
  return workspaceBase + AI_PORT_OFFSET;
}

Logic:

1. Read the current browser window's port (e.g., 6200)
2. Compute the workspace base: Math.floor(6200 / 1000) * 1000 = 6000
3. Add the AI offset: 6000 + 400 = 6400

Fallback: If running in SSR, or port is outside 4000-9999, returns fallbackPort (default: FRONTEND_PORTS.gograbAi = 5400).

Extension Port Resolution

The Chrome extension cannot use deriveAiPort() because it runs in its own context (no Angular host port). Instead, sidepanel.js probes known ports sequentially:

const KNOWN_AI_PORTS = [5400, 6400, 4200];

async function resolveAiAppUrl() {
  for (const port of KNOWN_AI_PORTS) {
    try {
      const resp = await fetch(`http://localhost:${port}/`, { mode: 'no-cors' });
      return `http://localhost:${port}`;
    } catch { continue; }
  }
}

Bridge Event Model

All communication between host and embedded app uses typed BridgeMessage objects sent via window.postMessage:

interface BridgeMessage<T = unknown> {
  type: BridgeMessageType;
  payload?: T;
  id?: string;
  timestamp: number;
  origin?: string;
  instanceId?: string;
}

Message Categories

Lifecycle

Authentication

Context

Drag and Drop

Prompts and Responses

Streaming

Panel State

Errors

Authentication Flows

Flow A: URL Parameters (Extension)

Used when extension=true is in the URL. This is the primary auth mechanism for the Chrome extension because postMessage auth can be unreliable in the extension context.

Chrome Extension                    gograb-ai App
      |                                   |
      |  iframe src=".../panel?           |
      |    extension=true&                |
      |    token=JWT&userId=X&            |
      |    userEmail=Y"                   |
      |---------------------------------->|
      |                                   |
      |                          initializeFromExtensionParams()
      |                          reads token, userId, userEmail
      |                          from URL, sets auth state
      |                                   |
      |          AI_APP_READY             |
      |<----------------------------------|

Flow B: Bridge PostMessage (Angular Embeds)

Used by GoGrabAiPanelComponent and GoGrabObservatoryComponent when embedding in Angular apps.

Host Angular App                    gograb-ai App (iframe)
      |                                   |
      |  <iframe src=".../panel?          |
      |    embedded=true">                |
      |---------------------------------->|
      |                                   |
      |          AI_APP_READY             |
      |<----------------------------------|
      |                                   |
      |  If autoSendOnReady:              |
      |  AI_AUTH_INIT { token, user }     |
      |---------------------------------->|
      |                          sets auth state from payload
      |                                   |
      |  ...later...                      |
      |  AI_AUTH_REQUEST_REFRESH          |
      |<----------------------------------|
      |                                   |
      |  AI_AUTH_REFRESH { newToken }     |
      |---------------------------------->|

Flow C: Shared Session (Direct Component)

When using <lib-ai-panel> directly in gograb-space, there is no bridge. The panel runs in the same Angular injector tree and shares the same AuthService, HttpClient, and cookie-based session. No special auth wiring needed.

Component Reference

EmbeddableHostComponent

Selector: embeddable-host Library: @libs-ux/embeddable-bridge Role: Creates and manages the iframe, wires up the bridge.

GoGrabAiPanelComponent

Selector: gograb-ai-panel Role: High-level wrapper that builds the /panel URL with workspace-aware port and passes it to EmbeddableHostComponent.

GoGrabObservatoryComponent

Selector: gograb-observatory Role: High-level wrapper that builds the /observatory URL.

AiPanelTabsComponent (Session 105.3)

Selector: ai-panel-tabs Library: @libs-ai/vitto-hub Role: Wraps AIPanelComponent and AgentObservatoryComponent with tab switching for native embedding.

Comparison Table

Troubleshooting

ERR_CONNECTION_REFUSED

Symptom: Iframe shows "localhost refused to connect"

Cause: The gograb-ai app is not running on the expected port.

Fix:

1. Verify the app is running: yarn serve:gograb-ai
2. Check the port in .env.local matches the workspace (e.g., GOGRAB_AI_PORT=6400 for gspace1)
3. Never run npx nx serve gograb-ai directly -- use yarn serve:gograb-ai which reads .env.local via dev-serve.js

Blank Panel (No Content)

Symptom: Iframe loads but shows nothing

Causes:

• Missing Angular providers. Check browser console for NG0201: No provider errors
• Missing provideLogSystem() in app.config.ts (Session 105.3 fix)

Icons Show as Text

Symptom: Mode tabs show "chat", "image", "videocam" as plain text

Cause: Material Icons font not loaded in gograb-ai

Fix: Ensure index.html has:

<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

Chrome PNA Preflight (Private Network Access)

Symptom: 404 Not Found on OPTIONS requests when embedding from extension

Cause: Chrome requires Access-Control-Allow-Private-Network: true header for local network access

Fix: The apps/gograb-ai/proxy.conf.js handles this with a /** catch-all that responds to OPTIONS with PNA headers.

WebSocket 400 Error on Backend

Symptom: Backend WebSocket connections fail with HTTP 400

Cause: --port flag was passed to a backend @nx/js:node executor. This sets the Node.js inspector port, not the app port, causing the inspector to intercept WebSocket upgrade requests.

Fix: Never pass --port to backend serve commands. Use yarn serve:backend-ai which reads the correct port from .env.local.

Observatory "Connected: No"

Symptom: Observatory panel shows "Connected: No" and "Error"

Cause: VittoMonitorService uses EventSource (SSE) which cannot send custom HTTP headers. If the backend requires Authorization, the SSE connection gets 401 Unauthorized.

Fix: Either configure the backend to accept cookie-based auth for SSE, or implement a token-in-URL scheme for the SSE endpoint.

File Reference