# Вложения в 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` - размер файла в байтах; - `sha256` - SHA-256 исходного файла в hex, 64 символа. Опциональное поле: - `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL. Источник определяется только наличием `ar`: - `ar` присутствует -> Arweave; - `ar` отсутствует -> public file текущего сервера доступа автора. Адрес сервера доступа, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока, а актуальный сервер доступа определяется отдельно. ## Preview Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**. Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения. Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`. ## Хранение файла Сам файл всегда находится вне блокчейна. ### Arweave Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`. ### Сервер доступа Если `ar` отсутствует, клиент: 1. определяет текущий сервер доступа автора сообщения; 2. запрашивает файл по стандартному пути `/files/`; 3. при необходимости проверяет полученные байты по `sha256` из блока. Физическое хранилище сервера является content-addressed: один и тот же SHA-256 должен соответствовать одному набору байтов. Это позволяет дедуплицировать одинаковые файлы разных пользователей. URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений. ## Создание вложения в UI UI предлагает два способа хранения: `Сервер доступа` и `Arweave`. По умолчанию выбран сервер доступа. Отдельные preview-файлы не создаются. После успешной загрузки на сервер доступа формируется тот же `S:att v=1`, но без поля `ar`. Для Arweave используется существующий механизм Arweave/Turbo и добавляется `ar`. Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна. ## Отображение Клиент при чтении сообщения: 1. читает валидные attach-блоки только из начала текста; 2. скрывает технические attach-строки; 3. определяет источник по наличию `ar`; 4. получает Arweave-файл по `txId` либо server-файл по `/files/` текущего сервера доступа автора; 5. определяет тип вложения по расширению `nm`; 6. изображение отображает из исходного файла; 7. видео отображает из исходного файла и открывает HTML5-плеер; 8. обычный файл показывает как карточку с именем, размером и скачиванием; 9. при перелистывании останавливает воспроизводящееся видео; 10. битый attach-блок игнорирует, не ломая остальное сообщение. ## Редактирование При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`. ## Совместимость и ограничения - полный URL в поле `ar` не используется; - MIME type не записывается, тип UI определяется по расширению `nm`; - старые текстовые префиксы `` и `` могут продолжать читаться как совместимые формы; - отдельные preview-поля не входят в текущий протокол; - MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями. ## 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. Предпросмотр изображений и видео **публичных вложений** в MVP отключён (файловая карточка); UI личных зашифрованных файлов не изменяется.