メインコンテンツへスキップ

Renderer bridge

Status: V1 architecture in place. Load model is committed; routes under /desktop/* will keep growing.

Grida Desktop's renderer doesn't bundle the editor. It does loadURL('https://grida.co/desktop/...') (or http://localhost:3000/desktop/... in dev) and runs the same Next.js app the web visitor runs. The bridge (window.grida) is exposed only when location.pathname.startsWith('/desktop/').

This is the "one editor codebase, two hosts" doctrine. Web visitors get the canvas demo at /svg; the desktop host gets the workstation surface at /desktop/svg. Same React tree, same components, different capability boundary.

Why URL-load instead of bundle​

Bundling the editor's compiled output into the Electron build has costs we're not willing to pay:

  • Two release trains. Every editor change would require an Electron rebuild, signing, notarization (macOS), and update propagation. The web is next deploy; bundled desktop would lag by days.
  • Update friction. A bundled editor would make Desktop users wait for a native release and an app update to receive editor fixes.
  • Codebase drift. "Same source, different bundle" rots fast. The web side grows web-only deps (analytics, dynamic Next features) and the bundled desktop accrues a permanent porting tax.

Compatible editor improvements ship to both surfaces when they deploy. Changes to native capabilities and OS integration ship with the shell.

The capability boundary​

Two routing rules make the boundary visible:

  1. Web visitors see a CTA, not the workstation. /desktop/* routes ship a DesktopBridgeGate that checks for window.grida. If absent (web browser), the route renders <OpenInDesktopCta />. The capability gap is surfaced, not silently degraded.
  2. The bridge is path-scoped. Preload exposes window.grida only when the renderer is under /desktop/*, with preload history guards and main-process navigation guards covering same-document navigation. XSS on any other grida.co page cannot reach the agent server. This is the path-scoped bridge control in GRIDA-SEC-004; see security for the complete defense-in-depth boundary.
grida.co (one Next.js app)
│
├── / /pricing /dashboard ... ← web: no window.grida
│
└── /desktop/* ← desktop: window.grida exposed
├── /desktop/welcome (signed-in landing)
├── /desktop/svg?docId=... (one URL per doc window)
├── /desktop/workspace (local workspace)
└── /desktop/settings (BYOK providers)

What lives where​

ConcernWhere
Editor UI, agent paneeditor/scaffolds/desktop/
/desktop/* route groupeditor/app/desktop/
Typed bridge clienteditor/lib/desktop/bridge.ts
Desktop chat seameditor/lib/agent-chat/
Preload + Electron maindesktop/src/
ServicesSidecar agent serverpackages/grida-ai-host/ (@grida/ai-host)
window.grida shape@grida/desktop-bridge

The bridge type shape lives in @grida/desktop-bridge. Desktop preload and the editor-side typed client both consume that contract. The package also describes the published Desktop version read by the shell and the hosted editor. Electron IPC channel names stay in Desktop source, and daemon HTTP stays in @grida/daemon/transport + @grida/ai-host/media-transport.

window.grida.protocol is currently 1. /desktop/* routes must distinguish a missing bridge from an unsupported protocol before rendering agent UI. Native capabilities live under bridge.caps.native; daemon route capabilities come from bridge.handshake() so they are the real server capabilities, not a static Desktop guess.

Version compatibility​

The hosted editor publishes the Desktop release version paired with its build. Shells on older major and minor version lines need an update. Shells on the same or a newer line pass the version check. Patch releases stay optional within the same line. The shell checks the hosted version before it loads the editor and owns update checks, installation, and restart. A bundled recovery screen keeps these controls available when the hosted UI cannot load. The hosted layout checks the version so older shells can reach an installer. Protocol and capability checks govern the native actions the editor can use after the version check passes.

The release runbook covers staging the editor until Desktop installers are available and restoring a compatible editor deployment during rollback. Desktop release runbook

Division of responsibility​

Web codebase. The hosted editor under /desktop/*, its bridge and version gate, and the browser fallback. A CSP-strict layout for the route group (no third-party scripts, no analytics, no Sentry). An ESLint boundary rule restricting (desktop) and scaffolds/desktop/ imports to bridge clients + UI primitives + @grida/* packages. Without the rule, the layering rots silently.

Electron host. Load the workstation from EDITOR_BASE_URL + /desktop/.... Block workstation navigation elsewhere via preload history guards plus main-process will-navigate / did-navigate-in-page; route external links through shell.openExternal. Expose window.grida exclusively when the renderer is under /desktop/*, never leaking agent server credentials onto window. Main handles native operations such as dialogs, file paths, and deep links. It also owns the application menu and the bundled update screen.

ServicesSidecar. See process-model. Short version: secrets, settings and media; chat runs in the native host. Desktop preload delegates daemon HTTP calls to the chat-free MediaTransport.Client; it does not duplicate daemon route strings. The shell holds no business logic. The renderer holds no durable credential: for hosted AI it may transiently receive a short-lived, purpose-scoped gg:ai token from the same-origin mint and immediately push it across the authenticated bridge to the daemon. It never persists, logs, or returns that token. See Hosted AI.

Anti-patterns​

  • Renderer retaining credentials. No OAuth access/refresh tokens, no BYOK API keys, and no persisted hosted-AI token. The transient gg:ai mint-and-push handoff is the narrow exception; secrets.get is not in the bridge for a reason.
  • useHost / HostProvider in (desktop). That's the web-side "am I in the wrapper" hook. The desktop bridge is a typed client, not a React context.
  • EDITOR_BASE_URL in renderer code. The renderer is served from that base; it should never need to know its own URL.
  • Third-party scripts in /desktop/*. Analytics, Sentry, marketing tags ship a network boundary the user didn't opt into and a CSP exception we don't want.
  • OPFS / IndexedDB for documents. The agent server owns document persistence. The web /svg demo uses OPFS; that's its scope, not desktop's.

What can change​

  • Bridge package promotion. @grida/desktop-bridge is private today; make it publishable only when a second host or separately versioned renderer needs it.
  • More /desktop/* route kinds. V1: welcome, svg, workspace, settings. V2 modules (.grida, forms, db) plug in by registering an extension → renderer URL mapping in the Electron-main menu registry.
  • Always-on-top AI window (Recipe 6). A new window kind loading /desktop/ai, same bridge, no editor mounted. V2.x.

See also​

  • Resource loading — the sibling renderer↔host channel: streaming host-owned resource bytes into media elements, not invoking capabilities.
  • Process model — the agent server the bridge talks to.
  • Security — the five GRIDA-SEC-004 layers.
  • GRIDA-SEC-004 — the trust boundary the bridge enforces.
  • Desktop agent authority — defense in depth for the contained host and raw runtime workers.