# Вложения в TEXT-сообщениях (`S:att v=1`) Документ фиксирует текущий формат вложений в текстовых блоках SHiNE. ## Область применения Формат применяется к UTF-8 полю `text` в TEXT-блоках: - `TEXT_POST` - `TEXT_REPLY` - `TEXT_EDIT_POST` - `TEXT_EDIT_REPLY` Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста. ## Общий вид Arweave-вложение: ```text ``` Public file на сервере доступа автора: ```text ``` Несколько вложений идут подряд в самом начале текста: ```text Текст сообщения ``` После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение. Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков. ## Поля Обязательные поля: - `v=1` - версия формата attach-блока; - `nm` - имя файла, закодированное через `encodeURIComponent`; - `sz` - размер файла в байтах; - один из идентификаторов файла: `pr` — pieces root BitTorrent v2 (base64url, 43 символа) для новых вложений; `sha256` — hex SHA-256 (64 символа) для совместимости со старыми. Опциональные поля: - `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL; - `mm` - MIME типа `image/jpeg` или `video/mp4`; если отсутствует, UI использует расширение `nm`. Источник определяется следующим образом: - `ar` присутствует -> Arweave; - `ar` отсутствует, но есть `pr` -> публичный Cloudflare R2 (`https://files.shineup.me/`); - `ar` и `pr` отсутствуют, есть `sha256` -> старое файловое хранилище сервера доступа автора. Адрес сервера автора, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока. Старые файлы разрешаются через сервер доступа, новые R2 — по `pr`. ## Preview Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**. Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения. Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`. ## Хранение файла Сам файл всегда находится вне блокчейна. ### Arweave Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`. ### Cloudflare R2 (новые публичные файлы) Если `ar` отсутствует и указан `pr`, клиент использует прямой адрес `https://files.shineup.me/`. Браузер запрашивает исходное медиа напрямую; сервер Java в отдаче файла не участвует. При видео браузер может запрашивать только метаданные и нужные фрагменты через HTTP Range. ### Сервер доступа (старые вложения с SHA-256) Если `ar` и `pr` отсутствуют, клиент: 1. определяет текущий сервер доступа автора сообщения; 2. запрашивает файл по стандартному пути `/files/`; 3. использует прежний формат ссылок для совместимости с существующими сообщениями. URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений. ## Создание вложения в UI UI предлагает два способа хранения публичных вложений: `Cloudflare R2` (через пункт сервера доступа) и `Arweave`. Отдельные preview-файлы не создаются. После загрузки в R2 формируется `S:att v=1` с `pr` и `mm`, без `ar`. Для Arweave используется механизм Arweave/Turbo; дополнительно записывается `ar`. Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна. ## Отображение Клиент при чтении сообщения: 1. читает валидные attach-блоки только из начала текста; 2. скрывает технические attach-строки; 3. определяет источник по наличию `ar`; 4. получает Arweave-файл по `txId`, R2-файл по `pr` либо старый server-файл по `/files/`; 5. определяет тип вложения по `mm` (если указан), иначе по расширению `nm`; 6. изображение отображает из исходного файла; 7. видео отображает из исходного файла и открывает HTML5-плеер; 8. обычный файл показывает как карточку с именем, размером и скачиванием; 9. при перелистывании останавливает воспроизводящееся видео; 10. битый attach-блок игнорирует, не ломая остальное сообщение. ## Редактирование При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`. ## Совместимость и ограничения - полный URL в поле `ar` не используется; - для старых `sha256`-вложений MIME не записывался, тип UI определяется по расширению `nm`; - старые текстовые префиксы `` и `` могут продолжать читаться как совместимые формы; - отдельные preview-поля не входят в текущий протокол; - `width`, `height`, `duration` и `thumbnail` не записываются отдельными полями; новые вложения могут содержать `mm` (MIME). ## MVP R2 (2026-11): новые публичные вложения Для **новых** публичных вложений использовать ``; при загрузке в Arweave добавляется `;ar=TXID`. `pr` — 32-байтный BitTorrent v2 pieces root в base64url без padding (43 символа), а не SHA-256 файла. `mm` необязателен; отсутствие означает `application/octet-stream`. Новое публичное вложение без `ar` скачивается с `https://files.shineup.me/`. `storage=r2` отсутствует. Новые аватары **не изменяются**: SHA-256 и старый API `/files/` остаются. Существующий формат чтения `sha256` оставлен для ранее созданных данных и уже загруженных транзакций Arweave. Публичные изображения и видео показываются внутри сообщения из исходного файла (`` / `