Web Surface: готовый UI и встраивание

Surface — готовая локальная страница редактора поверх того же Rust-процессора. Это самый быстрый способ показать OEM-встраивание: партнёр запускает локальный host и помещает URL в webview или iframe.

cd ~/Desktop/A4-API-first-run
./start-web-demo.sh

# Открыть в браузере
open "http://127.0.0.1:9272/?token=a4-local-demo&locale=ru-RU&theme=light

Дождитесь загрузки документа.

Поставьте курсор в первый абзац и добавьте текст.

Нажмите Save DOCX.

Проверьте файл ~/Desktop/A4-API-first-run/api-demo-web-result.docx.

Остановите локальный сервер сочетанием Control+C в Terminal.

Встраивание

<iframe
  src="http://127.0.0.1:9272/?token=a4-local-demo&locale=ru-RU&theme=light"
  title="A4 document editor"
  style="width:100%;height:720px;border:0"
></iframe>

Surface сообщает состояния ready, dirty, saved, error и unmounted через событие окна fastdoc-host-event. Для полного доступа к модели документа и широкого набора операций используйте параллельно JSONL/WebSocket Rust API.

Известное поведение текущей сборки

во время проверки одно долго простаивавшее соединение разорвалось с Resource temporarily unavailable (os error 35), после чего UI показал A4 surface is not connected. Перезагрузка локальной страницы и немедленное сохранение сработали. Для production-host добавьте health-check, reconnect и явный индикатор статуса.

Рекомендуемый production-контур

Shell запускает Surface на случайном свободном порту, а не на фиксированном публичном порту.

Token генерируется на каждую сессию и не записывается в URL-журналы.

При disconnect shell перезапускает соединение, но не повторяет мутацию без idempotency-проверки.

Файл сохраняется сначала в новую копию; исходник заменяется только по явному решению пользователя.

События хоста и повторное подключение

window.addEventListener("fastdoc-host-event", (event) => {
  const { type, detail } = event;
  if (type === "error" || type === "unmounted") {
    disableSaveAndReconnect(detail);
  }
  if (type === "saved") verifyOutput(detail);
});

После disconnect не повторяйте последнюю мутацию вслепую: сначала прочитайте актуальное состояние документа.

После saved повторно откройте output DOCX через model-docx и проверьте ожидаемое изменение.

Показывайте оператору состояния connecting, ready, dirty, saving, saved и error — это часть OEM-контракта.

ШАГ 6