Core concepts

Architecture

In-page React: a vanilla-TS core, headless hooks on top, and one styled UI on top of those — all running in the host page's main thread.

Every layer is published as its own package and depends only on the layer below it. There is no iframe and no web worker: the SDK shares the host page’s JavaScript context.

layerstext

┌─ @dialogueai/react-ui ─ one styled, branded Interview (+ shadcn-style registry)
│     └─ built strictly on the hooks below — cannot drift from them
├─ @dialogueai/react ──── headless hooks + unstyled primitives  ← primary contract
│     └─ thin reactive views onto the core; hold no state of their own
└─ @dialogueai/web-sdk-core ─ REST · auth · journey state machine · LiveKit · types
      (framework-agnostic vanilla TypeScript)

The three layers

A non-React host uses the loader (window.Dialogue), which simply mounts the same react-ui tree with its own pinned React into a container you point it at.

The core

@dialogueai/web-sdk-core owns everything non-UI: the typed REST client and data model, the auth lifecycle, the participant-journey state machine and event bus, and the LiveKit connection + AI-agent bridge. It exposes a DialogueCore orchestrator plus pure helpers. Most integrators never touch it directly; it’s there for non-React frameworks and tests.

The headless layer

@dialogueai/react is the primary contract: <DialogueProvider>, the hook surface (useInterview, useScreener, useConnection, …), and a few accessibility-aware primitives. Hooks are thin reactive views onto the core; they hold no state of their own, so the styled layer and your custom UI always see the same source of truth.

The styled layer

@dialogueai/react-ui is the one prebuilt, Dialogue-branded UI. It is implemented strictly on top of the headless hooks, which is the rule that keeps it from drifting. It also ships as a shadcn-style registry so you can copy individual screens into your own codebase. The design tokens and fonts match the Dialogue mobile app.

Host code never imports livekit-client directly; the connection lives behind useConnection(). This keeps the media stack swappable and the contract small.

The trust boundary

Because the SDK runs in the host page’s context, the host page is the trust boundary. Tokens live in main-thread closure memory only, never in cookies, localStorage, or IndexedDB. A compromised host page could read them; that is an accepted, documented constraint, not a bug. Keep your bootstrap-token endpoint server-side and your secret key out of the browser.