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:
- Web visitors see a CTA, not the workstation.
/desktop/*routes ship aDesktopBridgeGatethat checks forwindow.grida. If absent (web browser), the route renders<OpenInDesktopCta />. The capability gap is surfaced, not silently degraded. - The bridge is path-scoped. Preload exposes
window.gridaonly 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 inGRIDA-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
| Concern | Where |
|---|---|
| Editor UI, agent pane | editor/scaffolds/desktop/ |
/desktop/* route group | editor/app/desktop/ |
| Typed bridge client | editor/lib/desktop/bridge.ts |
| Desktop chat seam | editor/lib/agent-chat/ |
| Preload + Electron main | desktop/src/ |
ServicesSidecar agent server | packages/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:aimint-and-push handoff is the narrow exception;secrets.getis not in the bridge for a reason. useHost/HostProviderin(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_URLin 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
/svgdemo uses OPFS; that's its scope, not desktop's.
What can change
- Bridge package promotion.
@grida/desktop-bridgeis 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.