# The web component and postMessage API

`/embed.js` defines a `<vid2context-embed>` element. It puts the widget in an iframe from the same server the script came from, resizes it to its content, and turns the widget's messages into DOM events. It is a single small script with no dependencies.

## Try it

This is the element running on this page. The buttons call its methods, and every event it fires is logged under it.

```html
<script src="https://vid2context.com/embed.js" async></script>

<vid2context-embed id="demo" sample="gwagon" max-height="420"></vid2context-embed>

<script>
  const demo = document.getElementById('demo');
  demo.addEventListener('vid2context:loaded', (e) => console.log(e.detail.title, e.detail.segments));
  demo.addEventListener('vid2context:segment', (e) => console.log(e.detail.startSec, e.detail.text));
  demo.seek('2:30');          // scroll to 2:30
  demo.search('engine');      // filter the transcript
  demo.setAttribute('theme', 'light');
</script>
```
## Attributes

Every [embed parameter](https://vid2context.com/docs/embed/parameters.md) is an attribute with the same name, plus three that only the element has:

- `height`: a fixed height in pixels. Without it the element follows the widget's size.
- `max-height`: the tallest the element grows for the transcript and chapters views, which scroll inside it. Default 640.
- `loading`: `lazy` (the default) waits until the element is near the screen; `eager` loads at once.

Changing an attribute reloads the widget with the new options, except `theme`, which switches in place.

## Events

The element fires these as `CustomEvent`s that bubble, with the fields in `event.detail`:

| Message `type` | DOM event | Fields | When |
|---|---|---|---|
| `ready` | `vid2context:ready` | `{ version }` | The widget started and is loading its context. |
| `loaded` | `vid2context:loaded` | `{ title, url, durationSec, segments, chapters, language, origin }` | The context is shown. |
| `resize` | `vid2context:resize` | `{ height }` | The content height changed. The loader uses it to size the iframe. |
| `segment` | `vid2context:segment` | `{ startSec, endSec, text }` | The reader clicked a line or a chapter. |
| `seek` | `vid2context:seek` | `{ sec, index }` | With the player on, playback reached a new line. |
| `search` | `vid2context:search` | `{ query, matches }` | The search box changed. |
| `error` | `vid2context:error` | `{ code, message, hint }` | The context could not be loaded or a parameter was wrong. |

```js
const el = document.querySelector('vid2context-embed');
el.addEventListener('vid2context:loaded', (e) => {
  console.log(`${e.detail.title}: ${e.detail.segments} lines, ${e.detail.chapters} chapters`);
});
el.addEventListener('vid2context:segment', (e) => {
  // The reader clicked a line: send it to your own player, notes or chat box.
  console.log(e.detail.startSec, e.detail.text);
});
el.addEventListener('vid2context:error', (e) => console.warn(e.detail.code, e.detail.hint));
```

## Methods

- `el.seek(sec)`: scroll to the line at this time and highlight it. Takes seconds or a string like `"2:30"`. With `player="1"`, the video seeks too.
- `el.search(query)`: set the search box. An empty string clears it.
- `el.setTheme('auto' | 'light' | 'dark')`: same as setting the `theme` attribute.
- `el.load({ url })`, `el.load({ sample })` or `el.load({ src })`: show another video without rebuilding the element.

## From JavaScript

`Vid2Context.embed(target, options)` creates the element inside `target` (an element or a CSS selector) and returns it. Option names are the parameters; camelCase names become kebab-case attributes (`maxHeight` becomes `max-height`), and `true` and `false` become `1` and `0`.

```html
<div id="talk"></div>
<script src="https://vid2context.com/embed.js"></script>
<script>
  const widget = Vid2Context.embed('#talk', {
    url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
    theme: 'light',
    player: true,
    maxHeight: 520,
  });
  widget.addEventListener('vid2context:loaded', (e) => console.log(e.detail.title));
</script>
```

`Vid2Context.origin` is the server the script came from, and `Vid2Context.params` lists every parameter name.

## Without the script: postMessage

A plain iframe speaks the same protocol. The widget posts every event to its parent as an object with `source: "vid2context"` and a `type`; the fields are the ones in the table above.

```js
const frame = document.querySelector('iframe[src*="/embed/"]');
window.addEventListener('message', (e) => {
  if (e.source !== frame.contentWindow || e.origin !== 'https://vid2context.com') return;
  if (e.data?.source !== 'vid2context') return;
  if (e.data.type === 'resize') frame.style.height = `${Math.min(e.data.height, 640)}px`;
  if (e.data.type === 'segment') console.log(e.data.startSec, e.data.text);
});
```

To send a command, post an object with `target: "vid2context"` to the iframe:

| `type` | Fields | What it does |
|---|---|---|
| `seek` | `{ sec }` | Scroll to the line at this time (and seek the player when it is on). |
| `search` | `{ query }` | Set the search box. |
| `theme` | `{ theme: "auto" \| "light" \| "dark" }` | Switch theme without reloading. |
| `load` | `{ url }`, `{ sample }` or `{ src }` | Load another video, sample or JSON file. |

```js
frame.contentWindow.postMessage({ target: 'vid2context', type: 'seek', sec: 75 }, 'https://vid2context.com');
frame.contentWindow.postMessage({ target: 'vid2context', type: 'search', query: 'engine' }, 'https://vid2context.com');
```

The widget only accepts commands from the page that embeds it (its `window.parent`), and it posts nothing it does not show: the messages carry the same public transcript the widget displays.
