# Compare Two Texts для Google Docs — прототип 0.2.0

Боковая панель в Google Документах: выделить фрагмент → отредактировать → увидеть удалённый и добавленный текст → применить в исходном документе. Скачивать документ и загружать его в расширение не нужно.

Это Apps Script, привязанный к одному документу. Пакет пока не опубликован в Google Workspace Marketplace и не устанавливается как расширение Chrome. В отличие от локального прототипа Writer, серверная часть работает в инфраструктуре Google и требует подключения к интернету. В коде нет обращения к LLM, нашему сайту или сторонним серверам.

## Установка для первого теста

Этот проприетарный прототип можно бесплатно использовать для личных и внутренних рабочих задач. Разрешена установка копированием неизменённых файлов в Apps Script и необходимая настройка проекта. Распространение, продажа и изменение кода требуют разрешения, кроме случаев, предусмотренных применимым законодательством или лицензиями сторонних компонентов. Полные условия приведены в [лицензии](../LICENSE) и включены в ZIP-архив как `LICENSE.txt`.

1. Распакуйте `compare-these-texts-google-docs-0.2.0.zip`.
2. Откройте тестовую копию обычного Google Документа в настольном браузере с правом редактирования. Если файл открыт в режиме редактирования DOCX, сначала преобразуйте копию в формат Google Документов.
3. В документе выберите **Расширения → Apps Script**.
4. В открывшемся проекте замените содержимое стандартного `Code.gs` содержимым одноимённого файла из архива.
5. Нажмите **+ → HTML**, задайте имя **Sidebar**. Замените содержимое файла текстом из `Sidebar.html`.
6. В настройках проекта включите показ файла манифеста `appsscript.json` в редакторе. Вернитесь в редактор и замените его содержимое файлом `appsscript.json` из архива.
7. Сохраните проект, например под именем **Compare Two Texts — prototype**. Вернитесь в документ и обновите страницу.
8. Выделите несколько слов внутри одного обычного абзаца. В появившемся меню **Compare Two Texts** выберите **Edit selected text**. При первом запуске разрешите скрипту доступ к текущему документу и его интерфейсу. Если администратор организации запрещает Apps Script, установка потребует изменения настроек со стороны администратора.
9. Откроется боковая панель. Если выделение не загрузилось, выделите фрагмент снова и нажмите **Load selected text**.

Развёртывание как веб-приложения, API-ключ и OAuth client ID для этого теста не требуются. Скрипт действует только в документе, к которому привязан.

## Использование

- **Your edit** — внесите правку.
- **Preview changes** — посмотрите зачёркнутый удаляемый текст и подчёркнутый добавляемый.
- **Apply to document** — внесите просмотренную правку в документ.
- **Load selected text** — загрузите следующий выделенный фрагмент.
- **Close** — закройте панель.

До нажатия Apply содержимое документа не изменяется. После редактирования черновика старый предпросмотр становится недействительным: нужно снова нажать Preview changes. Пустая правка удаляет выделенный текст, сохраняя сам абзац.

После применения сохранение выполняет Google Docs обычным способом. Обязательно проверьте его индикатор сохранения. Отменить правку можно средствами Google Docs; единый шаг Ctrl+Z для всего применения пока не гарантируется. При необходимости доступна история версий.

## Область первого прототипа

- Один непрерывный фрагмент внутри обычного абзаца основного текста, до 4 000 единиц UTF-16; большинство букв считаются за одну, многие эмодзи — за две.
- Учитывается активная вкладка документа. Таблицы, списки, колонтитулы, сноски, ссылки и абзацы со встроенными объектами не поддерживаются.
- Переносы строк и абзацев вставлять нельзя. Максимальная длина исходного абзаца — 12 000 единиц UTF-16.
- Активная вкладка — до 200 000 единиц UTF-16 и 1 000 элементов основного уровня. Скрипт читает её текст для контрольной суммы, чтобы не перепутать одинаковые абзацы при смещении. Для текста за пределами выбранного абзаца в кэше сохраняется только контрольная сумма; этот текст в панель не передаётся.
- Сравнение выделяет один участок от первого до последнего различия. Неизменённые начало и конец сохраняют оформление. Новый текст получает оформление первого заменяемого символа или соседнего символа при вставке.
- Если участок замены пересекает разные стили, правка отклоняется. В таком случае применяйте изменения к отдельным фрагментам.
- Пользовательский кэш Google Apps Script хранит выделенный текст (до 4 000 единиц UTF-16) и полный текст выбранного абзаца (до 12 000 единиц UTF-16) в открытом виде, его оформление, идентификаторы документа и вкладки, положение выделения и контрольную сумму вкладки. Заданный срок — 15 минут; Google может удалить запись раньше. Это обработка и временное хранение в инфраструктуре Google, а не только на компьютере пользователя. Панель получает выделенный текст и токен; при применении отправляет токен и исправленный текст. Запись кэша удаляется перед записью правки в документ; закрытие панели её не удаляет. При истечении срока выделение нужно загрузить снова.
- Если исходный текст, его оформление, окружающий текст или активная вкладка изменились, применение отклоняется. Во время теста не редактируйте документ параллельно с другим пользователем: блокировка скрипта не блокирует ручные правки соавторов.
- Комментарии, закладки и режим предложений не проверяются исчерпывающе через DocumentApp. Первый тест проводите в режиме редактирования на обычном тексте без таких аннотаций.
- Если Google вернул ошибку после начала записи, могла примениться часть изменений. Панель сохраняет черновик для копирования и просит проверить документ перед повторной загрузкой.

Автоматические проверки используют модель API и DOM: они проверяют привязку выделения, устаревшие данные, форматирование, Unicode, повторное применение и интерфейс. Они не заменяют ручную проверку в реальном Google Docs. Установка в вашем аккаунте и работа интерфейса Google пока не подтверждены.

## Сборка и проверки

Из корня репозитория:

```sh
npm ci --ignore-scripts
node --test google-docs/tests/*.test.mjs
python3 google-docs/build.py
```

Архив появится в `google-docs/dist/`. В CI он прикладывается как артефакт `compare-these-texts-google-docs-prototype`.

## Короткий ручной тест

1. Напишите: «Сегодня мы проверяем редактор текста». Выделите слово «Сегодня», замените на «Завтра» и примените через предпросмотр.
2. Выделите обычный текст рядом с жирным или курсивным фрагментом. Проверьте, что оформление нетронутых частей сохранилось.
3. Загрузите выделение, затем измените исходный абзац прямо в документе. Попытка применить старую правку должна быть отклонена.
4. Проверьте русский текст, эмодзи, вставку и удаление слова.
5. Попробуйте выделение внутри таблицы: панель должна объяснить ограничение, не меняя документ.
6. Проверьте отмену и сохранение результата средствами Google Docs.

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

- https://developers.google.com/apps-script/guides/docs
- https://developers.google.com/apps-script/guides/dialogs
- https://developers.google.com/apps-script/reference/document/document
- https://developers.google.com/apps-script/reference/document/text

## Язык интерфейса

В установочном ZIP встроены 51 языка интерфейса. Боковая панель сначала использует язык браузера; переключатель «Язык» сохраняет выбор в этом браузере, если доступно локальное хранилище. Меню Google Docs использует язык аккаунта Google и обновляется после перезагрузки документа. Исходный текст, правки и предпросмотр различий не переводятся. Сервис перевода и дополнительные разрешения не нужны. Устанавливайте три файла из ZIP: исходники в репозитории используются для сборки локализованного пакета.
