App Extension SDK

@zeloscloud/app-extension-sdk is the typed bridge package for Zelos app-hosted extensions.

It provides:

• connectBridgeTransport() for embedded or standalone bridge setup
• MockBridge for standalone development and tests
• React helpers under @zeloscloud/app-extension-sdk/react

Install

npm install @zeloscloud/app-extension-sdk

React is an optional peer dependency. The root entry works without React, and the ./react entry adds the provider and hooks.

Quick Start

Use connectBridgeTransport() to connect to the host bridge. When your extension is running inside Zelos, the bridge connects to the Zelos app. When you open the same extension in a normal browser tab during local development, it automatically falls back to MockBridge.

import { connectBridgeTransport } from "@zeloscloud/app-extension-sdk";

const bridge = await connectBridgeTransport();
const snapshot = bridge.getSnapshot();

console.log(snapshot.info.name, snapshot.theme.preference);

const offTheme = bridge.on("theme.changed", (nextTheme) => {
  console.log("Theme updated:", nextTheme.preference);
});

window.addEventListener("beforeunload", () => {
  offTheme();
  bridge.destroy();
});

Bridge Model

The v1 bridge is intentionally small:

• the host replies to the initial handshake with handshake-ack.snapshot
• the snapshot contains info, theme (including design tokens), and workspace
• after connect, the host only pushes theme.changed and workspace.changed
• there is no request/response or host-command API in v1
• embedded extensions cannot make external network requests (connect-src, form-action restricted by CSP); standalone mode via MockBridge has no such restriction

MockBridge

MockBridge is useful when you want to run the extension outside the desktop app or write focused tests around theme and workspace behavior.

import { MockBridge } from "@zeloscloud/app-extension-sdk";

const bridge = MockBridge.connect(
  {
    currentWindow: window,
    parentWindow: window,
    locationHref: window.location.href,
    matchMedia: window.matchMedia.bind(window),
  },
  {
    extensionId: "local.dev-extension",
    version: "0.1.0",
    name: "Development Extension",
  },
);

bridge.setThemePreference("DARK");

React

The React entrypoint wraps bridge setup and exposes the current extension, theme, and workspace snapshots through hooks.

ZelosBridgeProvider also applies Zelos light/dark theme classes and a minimal set of design tokens to the iframe document automatically, so starter extensions can match the host app without reimplementing the theme system.

import {
  ZelosBridgeProvider,
  useExtensionInfo,
  useTheme,
  useZelosBridge,
} from "@zeloscloud/app-extension-sdk/react";

function ExtensionPanel() {
  const bridge = useZelosBridge();
  const info = useExtensionInfo();
  const theme = useTheme();

  if (bridge.status === "error") {
    return <div>Bridge error: {bridge.error.message}</div>;
  }

  if (bridge.status === "loading") {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>{info.name}</h1>
      <p>Theme: {theme.preference}</p>
    </div>
  );
}

export function App() {
  return (
    <ZelosBridgeProvider>
      <ExtensionPanel />
    </ZelosBridgeProvider>
  );
}

Embedded app extensions boot from handshake-ack.snapshot. After the bridge is connected, the host pushes theme.changed and workspace.changed events whenever those values change. workspace can be null without putting the bridge into an error state.

Exports

• @zeloscloud/app-extension-sdk — connectBridgeTransport(), MockBridge, and public bridge types/constants
• @zeloscloud/app-extension-sdk/react — ZelosBridgeProvider and hooks (useZelosBridge, useExtensionInfo, useTheme, useWorkspace)

Only the root entrypoint and ./react are supported public npm APIs. Low-level bridge internals are implementation details and are not part of the npm contract.