Зеркало в реальном времени: экономное, точное и адресуемое
Когда AI-агент управляет браузером, человеку, который его контролирует, нужно видеть в реальном времени, что делает агент. PhantomStream транслирует сам DOM, а не пиксели. Страница один раз захватывается в виде снимка со встроенными стилями, узлам назначаются стабильные идентификаторы в WeakMap, затем изменения страницы отслеживаются через MutationObserver, а отправляются только небольшие диффы (add, rm, attr, text), привязанные к ID узлов и сгруппированные в такт отрисовки самой страницы.
В итоге пропускная способность зеркала зависит от того, насколько на самом деле меняется страница, а не от частоты кадров. Текст отрисовывается нативно в любом разрешении, а удалённое управление обращается к настоящим элементам по их стабильным ID, не угадывая координаты.
PhantomStream начинался как веха v0.9.9.1 "Phantom Stream" внутри FSB, где он обеспечивает предпросмотр автоматизированных сессий браузера на дашборде в реальном времени. Этот репозиторий превращает его в самостоятельный фреймворк, который подключается без доработок, в SDK, на котором снова работает FSB, и в рабочий репозиторий сопутствующей научной статьи.
Что не так с пикселями
Очевидный инструмент для просмотра в реальном времени — видео. WebRTC, скринкаст через CDP или серия скриншотов — всё это передаёт пиксели. Пиксели тяжеловесны. Каждый кадр расходует пропускную способность независимо от того, менялась ли страница; кодирование и декодирование добавляют задержку, а результат получается с потерями и привязан к разрешению.
Хуже того, пиксели непрозрачны. Зритель не может узнать, с каким элементом работает агент, не может выделить узел, добавить аннотации к изображению или надёжно управлять страницей со своей стороны. Удалённое управление через видеопоток — это клики по пиксельным координатам в кадре, который мог уже устареть, поэтому неточный клик попадает не туда.
Почему трансляция DOM, а не видео
Трансляция структурированного DOM вместо кадров меняет экономику и возможности зеркала по всем параметрам, которые важны для контроля за агентом.
Конвейер из четырёх этапов
Страница захватывается, хост упаковывает каждое сообщение для передачи, ретранслятор рассылает сообщения просмотрщикам, а просмотрщик восстанавливает и применяет их. Удалённое управление проходит тот же путь в обратном направлении.
Страница
Снимок: клонирование, встраивание стилей, присвоение ID узлам, затем диффы с группировкой через rAF
Хост
Конверт LZ-string, метки сессии, сторожевой таймер
Ретранслятор
Рассылка через WebSocket, лимит 1 МиБ, отбрасывание при противодавлении
Просмотрщик
iframe в песочнице, применение диффов по ID, оверлеи, масштабирование под размер
Ключевые механизмы
Стабильная идентификация узлов
Модуль захвата хранит идентификаторы узлов в WeakMap<Element, string> и отправляет сопутствующие данные nodeIds вместе со снимками и операциями добавления, поэтому запоздавший дифф всегда попадает на нужный элемент, а сама страница не изменяется.
Выборочный захват вычисленных стилей
Для каждого элемента встраивается около 85 CSS-свойств, важных для визуальной точности, а не все 300 с лишним, причём значения по умолчанию опускаются. Благодаря этому сериализация страницы YouTube, раньше занимавшая 45 секунд, стала достаточно быстрой для интерактивной работы.
Сравнение в такт отрисовки
Изменения группируются и отправляются в колбэке requestAnimationFrame, поэтому зеркало обновляется в том же ритме, в котором отрисовывается страница.
Идентификация сессий
Каждое сообщение содержит streamSessionId и snapshotId. Просмотрщик отклоняет устаревшие сообщения, поэтому запоздавшие диффы от предыдущей страницы никогда не испортят зеркало.
Что есть из коробки
Ядро захвата — это обычный JavaScript, который внедряется как контент-скрипт, через addInitScript или как букмарклет и не требует этапа сборки. Захват, просмотрщик и ретранслятор общаются через тонкий транспортный слой.
Стабильные ID узлов
Диффы и команды удалённого управления обращаются к узлам по идентификаторам из WeakMap, а не по координатам или ненадёжным селекторам.
Выборочное встраивание стилей
Около 85 критичных для точности CSS-свойств на элемент без значений по умолчанию, поэтому даже тяжёлые страницы остаются интерактивными.
Диффы в такт отрисовки
Одна компактная операция на каждое реальное изменение, отправка в колбэке requestAnimationFrame с частотой обновления самой страницы.
Снимки с ограничением размера
Снимки укладываются в лимит ретранслятора на одно сообщение: поддеревья за пределами экрана отбрасываются целыми элементами.
Два сторожевых таймера
Таймер на стороне захвата и будильник на стороне хоста независимо друг от друга восстанавливают зависшую трансляцию, принудительно отправляя накопленные изменения или новый снимок.
Отрисовка в песочнице
Просмотрщик восстанавливает страницу в iframe, песочница которого разрешает только allow-same-origin (никогда allow-scripts), с защитой CSP и очисткой после парсинга.
Маскирование личных данных
blockSelector, maskTextSelector и функции маскирования скрывают конфиденциальное содержимое до того, как оно покинет страницу. Пароли маскируются всегда.
Медиа по ссылке
Изображения, видео и аудио загружаются по исходному URL прямо в браузере просмотрщика, поэтому медиаданные никогда не проходят через ретранслятор.
Адаптер Playwright
Встройте ядро захвата в страницу Playwright или CDP с помощью готового адаптера — с авторизованным обратным удалённым управлением.
Контракт безопасности для встраивания
PhantomStream отрисовывает HTML, на который мог повлиять злоумышленник, а выполнение скриптов отключено на уровне архитектуры. Сериализация удаляет опасное содержимое только в копии для передачи. Исходная страница остаётся нетронутой.
- Песочница — строго
allow-same-origin, никогдаallow-scripts - Обработчики
on*, опасные URL-схемы,srcdocиobject/embedудаляются - Конфиденциальный текст и значения полей форм маскируются на стороне захвата до передачи
- Загрузка медиа с блокировкой при сбое: только https, запрет частных диапазонов адресов, no-referrer
Гарантии песочницы
Захват, зеркалирование, ретрансляция
PhantomStream предоставляет отдельный путь импорта для каждого этапа. Подключите захват в контексте страницы, просмотрщик — в удалённом контексте, а ретранслятор — на Node, чтобы рассылать сообщения между ними.
import { createCapture } from '@full-self-browsing/phantom-stream/capture';
import { createWebSocketTransport } from '@full-self-browsing/phantom-stream/transport/websocket';
const transport = createWebSocketTransport({
url: 'wss://relay.example.com/ws?room=ROOM&role=source',
role: 'source'
});
const capture = createCapture({
transport,
skipElement: (el) => el.id === 'my-own-overlay' // исключить собственный интерфейс
});
capture.start(); // один снимок, затем поток диффовimport { createViewer } from '@full-self-browsing/phantom-stream/renderer';
import { createWebSocketTransport } from '@full-self-browsing/phantom-stream/transport/websocket';
const transport = createWebSocketTransport({
url: 'wss://relay.example.com/ws?room=ROOM&role=viewer',
role: 'viewer'
});
const viewer = createViewer({
container: document.getElementById('mirror'),
transport
});
viewer.on('state', (e) => console.log('состояние просмотрщика:', e.state));
// connecting | live | stale | disconnectedimport http from 'node:http';
import { createRelay, createWebSocketRelayBackend } from '@full-self-browsing/phantom-stream/relay';
const relay = createRelay(); // лимит 1 МиБ на сообщение, отбрасывание при противодавлении
const server = http.createServer();
createWebSocketRelayBackend({ server, relay, path: '/ws' });
server.listen(8787);
// клиенты подключаются с параметрами ?room=<id>&role=source|viewerМожно запустить и прямо из репозитория: npm run demo зеркалирует исходную вкладку во вкладку просмотрщика, а npm run demo:playwright управляет страницей, пока просмотрщик её зеркалирует.
Документация
Подробное описание лежит рядом с исходным кодом. Каждый документ самодостаточен.
Варианты быстрого старта
Loopback, WebSocket, Playwright/CDP, расширение MV3, букмарклет, режим CSSOM
Архитектура
Сквозной конвейер захвата, передачи, ретрансляции и отрисовки, а также ограничения
Безопасность
Модель угроз, очистка, маскирование, CSP и гарантии песочницы
История проектирования
Как развивалась система, что не сработало и почему победил нынешний подход