Исследования · @full-self-browsing

PhantomStream.

Нативное для DOM зеркалирование браузера в реальном времени. Настоящая вкладка транслируется как структурированный DOM, а не как пиксели.

PhantomStream отправляет один снимок со встроенными стилями, а затем — небольшие диффы MutationObserver с адресацией по стабильным ID узлов. Просмотрщик получает копию страницы в реальном времени с семантической адресацией и удалённым управлением, а пропускной способности для этого нужно в разы меньше, чем для трансляции экрана.

npm install @full-self-browsing/phantom-stream
v0.9.9.1Plain JS · ESMNode >=18 MIT
Обзор

Зеркало в реальном времени: экономное, точное и адресуемое

Когда 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 вместо кадров меняет экономику и возможности зеркала по всем параметрам, которые важны для контроля за агентом.

Видео / скриншоты
PhantomStream
Пропускная способность
Непрерывные кадры независимо от содержимого страницы
Один снимок, затем небольшие диффы — только при изменениях страницы
Задержка
Кодирование, передача и декодирование каждого кадра
Изменение текста — одна небольшая JSON-операция
Точность воспроизведения
С потерями и привязкой к разрешению
Точный DOM, нативная отрисовка текста, независимость от разрешения
Удалённое управление
Пиксельные координаты в кадре, который мог устареть
Настоящие элементы с адресацией по стабильным ID узлов
Прозрачность
Непрозрачные пиксели
Зеркало — это 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

Гарантии песочницы

Только iframe sandbox = allow-same-origin
Метатег CSP + очистка после парсинга
Очистка копии для передачи на стороне захвата
Проверка на уровне строк перед парсингом srcdoc
Политика no-referrer на уровне документа
Быстрый старт

Захват, зеркалирование, ретрансляция

PhantomStream предоставляет отдельный путь импорта для каждого этапа. Подключите захват в контексте страницы, просмотрщик — в удалённом контексте, а ретранслятор — на Node, чтобы рассылать сообщения между ними.

capture.js
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 | disconnected
import 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 управляет страницей, пока просмотрщик её зеркалирует.

Справочник

Документация

Подробное описание лежит рядом с исходным кодом. Каждый документ самодостаточен.