# Embedding Unroll

Unroll can live inside any web page as an iframe, fully interactive: visitors can unroll, scrub,
switch layers, open close-ups, use Destroy and every other tool right in the frame.

## The snippet

```html
<iframe src="https://sharpmeow-unroll.static.hf.space/index.html?embed=1"
  title="Unroll: a Herculaneum scroll in 3D" width="100%" height="480"
  style="border:0;max-width:100%" allow="fullscreen; clipboard-write" allowfullscreen loading="lazy"></iframe>
```

The **</>** button in the viewer builds this for the current view, with options for autoplay and hidden controls,
and copies it. `window.unroll.embed.snippet(options)` returns the same `{ url, html }`.
oEmbed consumers can read [`/oembed.json`](../oembed.json); the page links it with `rel="alternate"`.

Use the direct static URL (`sharpmeow-unroll.static.hf.space`), not the huggingface.co Space page. The static host
sends no `X-Frame-Options` or `frame-ancestors` header, so any site can frame it.

## Sizing

The viewer fills its frame and follows it when it resizes. For a responsive embed, give the frame a box and let it fill it:

```html
<div style="position:relative;width:100%;aspect-ratio:16/10">
  <iframe src="https://sharpmeow-unroll.static.hf.space/index.html?embed=1" title="Unroll"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    allow="fullscreen; clipboard-write" allowfullscreen loading="lazy"></iframe>
</div>
```

The layout gets more compact as the frame gets smaller; below 420 px of height the title is hidden.

## URL parameters

| Parameter | Meaning |
| --- | --- |
| `embed=1` | Embed layout: compact header, an **Open full viewer** link, a fullscreen button, click to interact |
| `autoplay=1` | Play the unroll once the scroll is loaded |
| `controls=0` | Hide the controls (the scene stays interactive) |
| `scroll`, `t`, `layer`, `focus`, `view`, `compare`, `panel`, `destroy`, `tool`, `sandbox`, `cam` | Start state, as in the full viewer (see [AGENTS.md](../AGENTS.md)) |

Example: `index.html?embed=1&autoplay=1&layer=overlay&t=0.4`.

## Click to interact

Until the visitor clicks (or taps, or presses Enter on) the "Click to interact" layer, the mouse wheel and touch
scrolling go to the host page, so the frame never traps a reader scrolling past it. After the click the scene takes
drag, pinch and wheel. Clicking anywhere on the host page hands them back. The toolbar, scrubber and chips work
without activating. `embed.activate(true|false)` does the same from code, and `getState().embed.active` reports it.

## postMessage API

Host pages drive the viewer with `postMessage`. It mirrors `window.unroll`: every method in [`/api.json`](../api.json)
is available by its name, with the same arguments and the same `{ ok, ... }` results.

Send to the frame:

```js
frame.contentWindow.postMessage({ unroll: 1, id: 7, method: 'setLayer', args: ['xray'] }, 'https://sharpmeow-unroll.static.hf.space');
```

| Message from the host | Fields |
| --- | --- |
| Call a method | `{ unroll: 1, id, method, args }`. `method` is an API name such as `getState`, `setUnroll`, `camera.orbit`, `destroy.tear`, `bench.run`; `args` is an array |
| Subscribe to an event | `{ unroll: 1, id, method: 'subscribe', args: [eventName] }` |
| Unsubscribe | `{ unroll: 1, id, method: 'unsubscribe', args: [eventName] }` |

| Message from the viewer | Fields |
| --- | --- |
| Ready | `{ unroll: 1, type: 'ready', version: { version, date, sha, api }, methods: [names] }`, sent when the scroll is loaded |
| Result | `{ unroll: 1, type: 'result', id, result }`. `result` is `{ ok: true, ... }` or `{ ok: false, error, code }` |
| Event | `{ unroll: 1, type: 'event', event, payload }` |

Events: `change`, `unroll`, `layer`, `focus`, `panel`, `destroy`, `camera`, `settled`, `scroll`, `extension`, `error`.

Not available over postMessage: `on`, `off` and `register` (use subscribe), and `open.listLocal` and `open.removeLocal`,
which would let a host read or delete scrolls the visitor keeps in their own browser (code `forbidden`).
`listScrolls` leaves out the visitor's local scrolls. Check `event.origin` on your side as usual.

A small client:

```js
const frame = document.querySelector('iframe');
const ORIGIN = 'https://sharpmeow-unroll.static.hf.space';
let seq = 0; const pending = {};
const unroll = (method, ...args) => new Promise((res) => {
  const id = ++seq; pending[id] = res;
  frame.contentWindow.postMessage({ unroll: 1, id, method, args }, ORIGIN);
});
addEventListener('message', (e) => {
  if (e.origin !== ORIGIN || e.data?.unroll !== 1) return;
  if (e.data.type === 'ready') { unroll('subscribe', 'layer'); unroll('setUnroll', 0.5); }
  if (e.data.type === 'result') { pending[e.data.id]?.(e.data.result); delete pending[e.data.id]; }
  if (e.data.type === 'event') console.log(e.data.event, e.data.payload);
});
```

## Test page

[`tests/embed-host.html`](../tests/embed-host.html) frames the viewer next to buttons that drive it with postMessage.
`?src=` points it at another viewer URL. `node tests/embed.mjs <viewer URL> <host URL>` serves both on different
origins and checks click to interact, wheel handling, drag, controls, fullscreen, resizing, autoplay, `controls=0`
and the postMessage API in headless Chrome.