@colineapp/app-runtime

The Coline App sandbox bridge — the typed postMessage protocol connecting tier-2 (React) Coline Apps running in a sandboxed iframe to the Coline host.

Most app developers never import this directly: @colineapp/ui's ColineAppProvider wires the guest side for you, and Coline runs the host side. It is a published low-level package for custom hosts and advanced integrations; import it only when you need control below the UI provider.

What it does

• Guest (connectGuestBridge): runs inside the sandbox. Exposes the full coline.* capability API, receives theme tokens and context, and emits navigation/toast/picker intents. The guest holds zero credentials — every call crosses the bridge and is authorized host-side.
• Host (createHostBridge): runs in the Coline web app. Verifies message sources, gate-checks every capability call against the install's grants and the surface's effect ceiling before relaying, and pushes live theme + context updates into the frame.
• Protocol (protocol.ts): zod-validated message schemas shared by both halves — version-checked, so mismatched guest/host fail loudly instead of strangely.

sandboxed iframe (your React app)
  └─ connectGuestBridge()  →  postMessage  →  createHostBridge()
       coline.files.create(...)                gate-check → capability API

Docs

Full guides at coline.app/developers/docs.

MIT © Coline

SDK 0.4 / CLI 2.4 workflow

Run coline-app check before pushing: it checks types, the manifest, hosted logic, and the React bundle without uploading. dev --internal updates one development version; install it in the workspace and reload after changes. The CLI bundles from the app's installed dependencies and preserves imported CSS and inline assets. CLI 2.5 compiles app-specific Tailwind v4 and ordinary CSS automatically. Import UI styles followed by app.css. The scaffold includes experimental UI skills, screen examples, and a credential-free coline-app preview command.

The starter includes a React home and editor, tree mobile fallback, and a tool. Use coline.tools.invoke or actions.invokeTool to run the same declared tool from UI that Kairo runs. Save with expectedVersion to detect concurrent edits. Homes/editors can write within grants; previews and server render handlers cannot. createTestWorkspace(app).client() tests the interactive contract and grantedPermissions simulates revoked consent.

New tasks, calendar, messages, and references capabilities require their explicit manifest permissions and retain the invoking user's workspace access. Use files.list({ scope: "workspace" }) for shared files; document writes stay with the owning app. Collections are install-private. Code integration and a native mobile React runtime are separate work.

Version 0.5 carries the SDK's ai.models, ai.run, ai.images.generate, ai.jobs.get/list/events/cancel and files.readUrl operations through the existing bridge. Long provider work runs in Coline's persistent worker; each bridge call only starts or observes a durable job and keeps the normal timeout.