Структура документа: как её получить

Архитектура и границы ответственности, путь одного пользовательского действия, смысловая модель и текущий Rust Session API для чтения.

Архитектура и границы ответственности

Путь данных один и тот же — в настольном приложении, в системном окне просмотра веб-страниц и при работе без интерфейса:

Слой	Что делает	Чего не делает
Ваше приложение	Окно, бренд, вход, хранилище, рабочие процессы и их жизненный цикл	Не владеет моделью документа и его вёрсткой
Поверхность редактора (Web Surface)	Полотно, лента, ввод, показ меню, доставка событий	Не правит DOCX напрямую
Адаптер к приложению	Запуск процесса, разбор приветственной строки с адресом, обмен по JSON или WebSocket, события окна	Не разбирает разметку документа
Сеанс документа	Команды, выделение, история, проекции модели и вёрстки, сохранение	Не отдаёт произвольный доступ к разметке страницы
Ядро на Rust	Пакет OOXML, смысл документа, вёрстка, запись обратно в файл	Не зависит от оформления оболочки
Файл DOCX	То, что сохраняется и открывается заново	Не подменяется снимком HTML

Путь одного пользовательского действия

Событие указателя. Поверхность получает координаты щелчка, щелчка правой кнопкой или двойного щелчка.
Определение попадания. Координата сопоставляется со страницей, строкой и позицией курсора, а затем с объектом документа.
Сбор контекста. Собираются сам объект, выделение, его родители в структуре документа, номер ревизии и список разрешённых команд.
Решение интерфейса. A4 и ваша сторона составляют контекстное меню — документ при этом не меняется.
Типизированная команда. Выбранный пункт превращается в команду с указанием ожидаемой ревизии.
Изменение документа. Ядро сверяет ревизию и разрешения, меняет модель и возвращает подтверждение с новой ревизией.
Перерисовка и сохранение. Проекции обновляются; сохранение пишет DOCX, который открывается заново той же моделью.

Как получить структуру документа

Термин «структура документа» неоднозначен. A4 разделяет пять представлений, чтобы вы запрашивали только то, что действительно нужно.

Представление	Команда	Назначение	Пример данных
Смысловая модель	`model`, `model-docx`	Абзацы, участки форматирования, таблицы, ссылки на стили и нумерацию, пометки о поддержке	`body.blocks[]`, `paragraph_index`, `text`, `runs[]`
Вёрстка	`compose`, `paginate`	Разделы, страницы, строки, переносы, геометрия	`page_index`, границы строк, порядок страниц
Сцена	`print`, `print-window`, `print-delta`	Готовые к отрисовке страницы и примитивы рисования	сцены страниц и их отпечатки
Рецензирование и стили	`review`, `style`	Примечания, записанные исправления, разрешение стилей	проекции рецензирования и стилей
Состояние правки	`status`, `set-selection`	Ревизия, наличие несохранённых изменений, отмена и повтор, выделение и состояние вида	`accepted_revision`, `selection_revision`

Пример: смысловая модель

# $CLI — путь к процессору, см. «Установка и проверка»
"$CLI" model-docx /data/contract.docx --format json

{
  "model_version": "fastdoc-d1-document-model-v1",
  "block_count": 1,
  "paragraph_count": 1,
  "body": {"blocks": [{
    "kind": "paragraph",
    "block_index": 0,
    "text": "A4 basic paragraph.",
    "style_ref": null,
    "numbering_ref": null,
    "runs": [{
      "run_index": 0,
      "text": "A4 basic paragraph.",
      "direct_format": {"bold": null, "italic": null}
    }]
  }]}
}

Как запустить сеанс сегодня и прочитать документ

Сеанс JSONL: обмен через стандартный ввод и вывод

Процесс печатает первую строку готовности со схемой fastdoc.session-serve.v1. Дальше каждая строка на входе — запрос в JSON, каждая строка на выходе — ответ на него, связанный по идентификатору.

{"id":"open-1","cmd":"open",
 "path":"/data/contract.docx","document_id":"contract-42"}
{"id":"model-1","cmd":"model"}
{"id":"pages-1","cmd":"paginate"}
{"id":"review-1","cmd":"review"}
{"id":"state-1","cmd":"status"}

{
  "id": "model-1",
  "ok": true,
  "cmd": "model",
  "elapsed_ms": 2,
  "result": { "model_version": "...", "body": { "blocks": [] } }
}

WebSocket на локальном адресе

"$CLI" serve --ws 0
# stdout: {"schema":"fastdoc.session-ws-bootstrap.v1",
#          "host":"127.0.0.1","port":49172,"token":"..."}

Привязка — только 127.0.0.1. Порт 0 выбирается автоматически.
Токен — секрет длиной 256 бит из системного источника случайности. Его нельзя писать в журналы и передавать в аналитику.
Команды одинаковы. Обмен строками JSON и обмен через WebSocket идут через один и тот же сеанс и одну схему запросов.

Дальше

Определение объекта по координате — Попадание по точке.
Что ещё делает процессор — карта возможностей.