Overview

@vol/embed builds two files:

File	Format	Use
`embed.js`	IIFE (~8 kB gzip)	Classic `<script>` + the `Vol(...)` command queue
`embed.mjs`	ES module	`<script type="module">` or `import "@vol/embed"` in a bundler

Both register the <vol-chat> custom element and install window.Vol. No React, no framework, styles fully encapsulated in Shadow DOM using VOL’s design tokens.

Install

<script>
  (function (w, d, src) {
    w.Vol = w.Vol || function () { (w.Vol.q = w.Vol.q || []).push(arguments); };
    var s = d.createElement("script"); s.async = true; s.src = src; d.head.appendChild(s);
  })(window, document, "https://vol.example.com/embed/embed.js");
  Vol("init", { apiKey: "vol_live_…", case: "papers" });
</script>

Commands

Command	Description
`Vol("init", config)`	Set defaults for every widget.
`Vol("inline", options)`	Render a chat inside an element. See Inline.
`Vol("floatingButton", options)`	Add a launcher + modal. See Floating button.
`Vol("open")` / `Vol("close")`	Open/close the floating modal programmatically.
`Vol("on", event, handler)`	Listen to `vol:*` events (see below).

`init` config

Option	Type	Default	Description
`apiKey`	`string`	—	Integration key (`X-API-Key`).
`baseUrl`	`string`	`<script origin>/api`	API base without `/v1`.
`case`	`CaseId`	—	Corpus to chat with.
`origin`	`string`	script origin	VOL app origin (iframe mode and “open in map”).
`theme`	`"light" \| "dark"`	`"light"`
`title`	`string`	`"Ask VOL"`	Chat header.
`placeholder`	`string`	—	Input placeholder.

Every command option object accepts the same keys to override init per widget.

Events

Events bubble from <vol-chat> (they are composed, so they cross Shadow DOM) and can be observed with Vol("on", …) or addEventListener:

Event	`detail`	Notes
`vol:answer`	`ChatResponse`	Stream finished.
`vol:citation`	`{ citation, index }`	Cancelable. Default: opens `/app/explore/{case}?node={nodeIndex}` in a new tab.
`vol:cluster`	`{ cluster }`	Click on a cluster pill.
`vol:error`	`{ message }`	HTTP or stream error.

Security

The API key is public once embedded: use one key per site and revoke it when needed.
In iframe mode the key is never placed in the URL; it is sent to the VOL origin with postMessage.
All answer text is inserted as text nodes, never as HTML.