Skip to content

Package Integration ​

VAssist has two browser packages in its Bun workspace:

  • @vassist/embed for plain JavaScript hosts and non-React frameworks
  • @vassist/react for React hosts

Neither package is published on npm yet. They can currently be used only from the VAssist repository workspace. The package names and install examples below describe the intended public API. They are not installable from npm until a release is announced.

If you are embedding VAssist, the normal decision order is:

  1. Pick the package and shell entry point.
  2. Give the instance a stable hostId if you need multi-instance control.
  3. Decide who owns provider settings in the UI.
  4. Decide who executes AI, TTS, and STT requests, and who handles the Decision API connection check.
  5. Pick the control surface you will call from your host.

Pick A Package ​

Host appPackageUse it when
Plain JS, Vue, Svelte, Angular, server-rendered HTML with a small client script@vassist/embedYou want imperative mount/update/remove helpers and direct element-handle control
React@vassist/reactYou want a component wrapper, reactive config props, and React-only render customizations

Both packages share the same runtime, VAssistEmbedConfig, provider bridge types, storage registry, and resource-loader registry.

Pick An Entry Point ​

Both packages ship the same entry point pattern.

Entry suffixShell you getTypical use
/fullFull assistantChat + settings + history + toolbar + voice + 3D
/chatChat onlyEmbedded assistant panel without the page toolbar
/chat-toolbarChat + toolbarChat UI plus the on-page toolbar
/toolbarToolbar onlySelection or input-field actions without the chat shell
base packageWhatever config.shell.mode saysHosts that want one import and runtime-selected shell mode

Examples:

  • @vassist/embed/full
  • @vassist/react/full
  • @vassist/embed/toolbar
  • @vassist/react

Availability and requirements ​

The packages are not yet available to external projects through npm. Inside this repository, Bun links them through the root workspace. The React package currently declares React 19 and React DOM 19 as peer dependencies.

The packages build the browser embed target. They include the shared browser UI and runtime, but they do not turn desktop-only Electron services or Android-native services into browser capabilities. Features that depend on those services require a reachable service endpoint or a host bridge implementation.

When deploying package build output directly, keep its emitted assets/ directory alongside the JavaScript files. Runtime assets, including WebAssembly files, are resolved relative to the generated package module.

Browser package support ​

CapabilityBrowser package behavior
Shared browser runtime and settingsBrowser packages use the shared chat, toolbar, voice, 3D, and settings runtime. Host config can provide provider defaults and optional UI defaults.
Decision settingsRemote endpoints support the built-in connection check. The "host" provider can delegate that check through transport.bridge.decision. Chat generation does not currently call this bridge. Desktop-local management requires Electron.
Desktop integrationsDesktop app mode, live wallpaper, window controls, and local model management require Electron services.
Android integrationsAndroid AR, native speech engines, and device acceleration require Android services.

Plain JS Quickstart ​

ts
import {
  injectFullVAssistEmbed,
  type VAssistEmbedElementHandle,
} from "@vassist/embed/full";

const hostId = "assistant";

injectFullVAssistEmbed({
  target: document.querySelector("#assistant-slot"),
  hostId,
  config: {
    storage: { mode: "namespaced", namespace: "my-app" },
    shell: { deferSetupUntilStarted: true },
  },
});

const assistant = document.getElementById(
  hostId,
) as VAssistEmbedElementHandle | null;

assistant?.openChat();
assistant?.setDraftInput("Summarize the current page.", { focus: true });

Use updateVAssistEmbedConfig() when you need to change config later without remounting the instance.

React Quickstart ​

tsx
import { FullVAssistEmbed } from "@vassist/react/full";

export function Assistant() {
  return (
    <FullVAssistEmbed
      hostId="assistant"
      config={{
        storage: { mode: "namespaced", namespace: "my-app" },
        shell: { deferSetupUntilStarted: true },
      }}
    />
  );
}

In React, the config prop is reactive. Changing it updates the mounted instance in place.

The Two Decisions That Matter Most ​

The most common integration mistake is mixing up provider ownership with request execution.

ConcernField(s)What it actually changes
Provider UI ownershipproviders.mode, lockProviderSelection, settings.policyWhether users can configure providers inside VAssist
Request executiontransport.mode, transport.bridgeWhether the browser runtime or your host/backend performs AI, TTS, and STT work

This means:

  • providers.mode: "host-managed" locks down the UI model.
  • transport.mode: "host-bridge" moves request execution to your host.
  • You often want both in production.

If browser code must not hold vendor credentials, keep the real keys in your backend or native host and use transport.mode: "host-bridge". The Decision settings "host" provider can delegate its connection check through transport.bridge.decision. This bridge is not part of chat generation.

Common Deployment Patterns ​

PatternTypical configWhen teams actually use it
Browser-managedproviders.mode: "user-configurable" and no transport.bridgeInternal tools, local development, prototypes
Host-managed UI onlyproviders.mode: "host-managed" and no transport.bridgeThe host wants locked settings, but browser-side provider execution is still acceptable
Secure host bridgeproviders.mode: "host-managed" with transport.mode: "host-bridge" and transport.bridgeProduction browser deployments where your host or backend must own secrets and network calls

Secure Host Bridge Pattern ​

Use the same bridge object with either package. The config shape is identical.

ts
import type { VAssistBinaryLike, VAssistProviderBridge } from "@vassist/embed";

function toBytes(input: VAssistBinaryLike): Uint8Array {
  if (input instanceof Uint8Array) {
    return input;
  }
  if (input instanceof ArrayBuffer) {
    return new Uint8Array(input);
  }
  if (Array.isArray(input)) {
    return Uint8Array.from(input);
  }
  throw new Error("Expected ArrayBuffer, Uint8Array, or number[] in this host");
}

const bridge: VAssistProviderBridge = {
  ai: {
    getCurrentProvider: () => "host-backend",
    async sendMessage({ messages, signal, onStream }) {
      const response = await fetch("/api/vassist/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ messages }),
        signal: signal ?? undefined,
      });

      const data = await response.json();
      if (typeof data.text === "string" && onStream) {
        onStream(data.text);
      }

      return {
        success: response.ok,
        response: typeof data.text === "string" ? data.text : null,
        error: response.ok ? null : data,
      };
    },
  },
  tts: {
    getCurrentProvider: () => "host-backend",
    async generateSpeech({ text }) {
      const response = await fetch("/api/vassist/tts", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text }),
      });

      if (!response.ok) {
        return null;
      }

      return {
        audio: await response.arrayBuffer(),
        mimeType: response.headers.get("Content-Type") ?? "audio/mpeg",
      };
    },
  },
  stt: {
    async transcribeAudio({ audio, mimeType }) {
      const response = await fetch("/api/vassist/stt", {
        method: "POST",
        headers: {
          "Content-Type": mimeType ?? "application/octet-stream",
        },
        body: toBytes(audio),
      });

      const data = await response.json();
      return typeof data.text === "string" ? data.text : "";
    },
  },
};

const config = {
  providers: {
    mode: "host-managed",
    lockProviderSelection: true,
  },
  settings: {
    policy: {
      readOnly: ["llm", "tts", "stt"],
    },
  },
  transport: {
    mode: "host-bridge",
    bridge,
  },
};

Runtime ownership in host-bridge mode is still split:

  • Your host owns provider requests and secrets.
  • The VAssist runtime still owns chat UI, selection context, toolbar workflows, panel state, and theme application.
  • TTS playback and queueing still happen in the browser runtime after your host returns audio.
  • STT audio capture still happens in the browser runtime before bytes are passed to stt.transcribeAudio.
  • The Decision API connection check can be delegated through transport.bridge.decision. The browser package does not receive the host's endpoint credentials.

Control Surfaces You Will Actually Use ​

NeedUseNotes
Mount from plain JSinject*VAssistEmbed()Best fit for non-React hosts
Mount from ReactVAssistEmbed or a preset component such as FullVAssistEmbedConfig stays declarative
Update config after mountReact config prop or updateVAssistEmbedConfig()No remount required
Control one specific instanceVAssistEmbedElementHandleBest choice for multi-instance pages
Control only the default hostwindow.VAssistEmbedConvenient, but not a multi-instance API
Control built-in AI toolbar itemsaiToolbar configForce input-focus/image-hover behavior and hide, whitelist, or reorder built-in toolbar items
Provide UI defaultsui configOptional deep partial settings for hosts that supply UI defaults
Lock or hide settingssettings.policyUse tab, section, field, or subtab target IDs
Move popovers or canvas portalsmount.portalContainersMainly useful for shadow DOM hosts and custom overlay stacks
Replace built-in labels or iconsbranding.labelOverrides, branding.iconOverridesNon-React host customization path
Add React-only UI around the assistantcustomizations propHeader actions, footer content, empty state, toolbar actions, settings extension, icon renderers
Swap persistence backendstorage.mode: "host" with storage.adapterUses the storage adapter registry
Swap asset resolutionassets.resourceLoaderUses the resource loader registry

Options Most Hosts Touch Early ​

FieldWhy it matters quickly
mount.hostIdRequired for predictable DOM lookup and multi-instance orchestration
shell.modeDecides whether you are embedding chat, toolbar, or the full assistant
aiToolbarControls where the built-in toolbar appears and which built-in items it shows
settings.policyLets you hide or lock settings without forking UI
providers.modeTells the runtime who owns provider setup
transport.bridgeLets your host own AI, TTS, and STT execution plus Decision API connection checks
theme.fontFamily / theme.monoFontFamilyLets the host pick typography, but the host still loads the fonts
storageControls persistence isolation or host-owned storage
assets.assetBaseUrl / assets.resourceLoaderControls where models, stages, motions, and other assets resolve from
brandingLets the host change app-facing labels and icons

If you are integrating VAssist into a real host app, read the docs in this order:

  1. This page for package choice, control surfaces, and deployment model.
  2. @vassist/embed if your host is imperative or non-React.
  3. @vassist/react if your host is React.
  4. Configuration Reference once you know which fields you need.