Мост для столов с расширениями

Некоторые виртуальные столы загружают интеграции как расширения, которые умеют только открыть страницу по адресу — запустить произвольный npm-код внутри них нельзя. Один из примеров такого стола — Owlbear Rodeo. Для них нужен мост: статическая страница, которую вы разворачиваете сами; расширение открывает её, а она уже встраивает лист.

Среда расширений стола
  └── страница-мост  (ваша статика, ваш хостинг)
        └── iframe с листом (longstoryshort.app)
              └── postMessage ──→ мост ──→ вызовы API стола

Если ваш стол — обычное веб- или десктоп-приложение, мост не нужен: ставьте SDK пакетом и работайте с ним прямо в своём коде, как описано во встраивании листа.

Что делает мост

Внутри моста три шага, и все они — обычный код без абстракций:

Встроить iframe с листом.
Подписаться на броски и вызвать API стола — уведомление, чат, рассылка остальным игрокам.
Принять рассылку от других игроков и показать её локально.

source.onRoll((roll) => {
    const message = formatRollMessage(roll);
    const variant = rollVariant(roll);

    myVTT.notification.show(message, variant);
    myVTT.room.broadcast(JSON.stringify({ type: 'dnd:roll', payload: roll }));
});

myVTT.room.onBroadcast((raw) => {
    const event = JSON.parse(raw);
    if (event.type === 'dnd:roll') {
        myVTT.notification.show(formatRollMessage(event.payload), rollVariant(event.payload));
    }
});

С чего начать

В репозитории SDK лежит шаблон bridges/_template/ — минимальный скелет на Vite: пустая страница, встраивание iframe, подписка на броски и комментарии TODO в местах, куда подставляются вызовы вашего стола.

cd bridges/_template
npm install
npm run dev     # локальный сервер
npm run build   # сборка в dist/

Дальше остаётся выложить dist/ на любой статический хостинг и скормить адрес расширению вашего стола.

Готовый мост для Owlbear Rodeo

Наш собственный мост для Owlbear Rodeo лежит в том же репозитории и разворачивается на GitHub Pages. Его манифесты:

https://bridge.longstoryshort.app/dnd/obr/manifest.json
https://bridge.longstoryshort.app/vortex/obr/manifest.json

Это рабочий пример полного цикла — от встраивания до рассылки бросков всем участникам комнаты. Если делаете интеграцию для своего стола, его код — самая полезная отправная точка после шаблона.

Пользователям, которые просто хотят подключить расширение, а не собирать своё, нужна инструкция по Owlbear Rodeo.