# Вложения в TEXT-сообщениях (`SHiNE:attach v=1/v=2`) Документ фиксирует текущий формат вложений в текстовых блоках SHiNE. ## Область применения Формат применяется к UTF-8 полю `text` в TEXT-блоках: - `TEXT_POST` - `TEXT_REPLY` - `TEXT_EDIT_POST` - `TEXT_EDIT_REPLY` Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста. ## Общий вид Один attach-блок: ```text ``` Блок с превью: ```text ``` Несколько вложений идут подряд в самом начале текста: ```text Текст сообщения ``` После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение. Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков в том порядке, в котором пользователь прикрепил файлы. ## Поля Обязательные поля: - `v=1` - версия формата attach-блока; - `name` - имя файла, закодированное через `encodeURIComponent`; - `size` - размер файла в байтах; - `sha256` - SHA-256 исходного файла в hex, 64 символа; - `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL. Дополнительные поля для `v=2`: - `previewAr` - короткий Arweave Transaction ID файла-превью; - `previewSha256` - SHA-256 файла-превью в hex. ## Хранение файла Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки: - имя файла; - размер; - SHA-256; - Arweave `txId`. Опционально для видео или больших изображений может храниться отдельный второй файл-превью. В таком случае основной attach-блок остаётся одним, но дополнительно указывает `previewAr/previewSha256`. ## Создание вложения в UI UI поддерживает три сценария: - загрузить новый файл в Arweave выбранным Arweave-кошельком; - ввести существующий `txId`, скачать файл через Arweave gateway и локально посчитать `size/sha256`; - выбрать файл из журнала файлов, загруженных в текущей браузерной сессии. Для видеофайлов UI может по желанию пользователя автоматически создать превью из первого кадра. Технически клиент загружает два файла: - основной видеофайл; - отдельное изображение-превью. После успешной загрузки в журнале хранится один элемент основного файла, но с полями `previewAr/previewSha256`. В UI такой элемент помечается как файл `С превью`. При ручном добавлении существующего `txId` для видео UI также позволяет вручную указать `txId` файла-превью. Журнал хранится только в `sessionStorage` текущего браузера и не является частью блокчейна. В настройках клиента есть отдельный экран `Загрузка файлов`: пользователь может заранее загрузить файл в Arweave без создания сообщения, увидеть компактную плитку с именем, размером, временем загрузки, `txId` и статусом доступности через gateway, а затем выбрать этот файл из истории при создании сообщения. Если файл загружен заранее, но ещё не был отправлен ни в одном сообщении SHiNE, клиент показывает локальный флаг `Не добавлен в SHiNE`. Флаг снимается после успешной отправки сообщения с этим вложением. Если история очищена, уже созданные сообщения не меняются: в блокчейне остаются attach-блоки с `txId`. ## Отображение Новый клиент при чтении сообщения: 1. читает валидные attach-блоки только из начала текста; 2. скрывает технические attach-строки; 3. отображает вложения над пользовательским текстом; 4. показывает вложения горизонтальной каруселью: одно вложение на экране, переключение свайпом или стрелками, счётчик вида `1 из 3`; 5. определяет тип вложения по расширению имени файла: - изображение показывает как ограниченное по размеру превью; - видео показывает как превью с кнопкой воспроизведения и открывает большой HTML5-плеер по нажатию; - обычный файл показывает как карточку с именем, расширением, размером и скачиванием; 6. если у видео есть `previewAr/previewSha256`, использует отдельный preview-файл как `poster` и как большую превью-плитку в журнале загрузок; 7. при перелистывании останавливает воспроизводящееся видео; 8. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение. Если файл по ссылке Arweave gateway недоступен, клиент показывает диагностический блок: - если сообщение создано менее 20 минут назад: файл, скорее всего, ещё не распространился в Arweave, нужно повторить через несколько минут; - если сообщение старше 20 минут: файл считается недоступным. Старые клиенты без поддержки формата могут показывать attach-блоки как обычный текст. ## Редактирование При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения по-прежнему выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`. ## Совместимость и ограничения - `ar` допускает только короткий Arweave `txId`, полный URL не используется; - MIME type не записывается, поэтому UI определяет image/video/file по расширению имени файла; - старые блоки `v=1` без превью остаются валидными и читаются без изменений; - `previewAr/previewSha256` используются только если присутствуют оба поля и оба валидны; - MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями; - проверка существующего `txId` скачивает файл локально через gateway, поэтому UI ограничивает максимальный размер такой проверки.