# Вложения в TEXT-сообщениях (`SHiNE:attach v=1`)

Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.

## Область применения

Формат применяется к UTF-8 полю `text` в TEXT-блоках:

- `TEXT_POST`
- `TEXT_REPLY`
- `TEXT_EDIT_POST`
- `TEXT_EDIT_REPLY`

Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста.

## Общий вид

Один attach-блок:

```text
<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
```

Несколько вложений идут подряд в самом начале текста:

```text
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;ar=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB>
<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc;ar=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD>
Текст сообщения
```

После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение.

## Поля

Обязательные поля:

- `v=1` - версия формата attach-блока;
- `name` - имя файла, закодированное через `encodeURIComponent`;
- `size` - размер файла в байтах;
- `sha256` - SHA-256 исходного файла в hex, 64 символа;
- `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL.

## Хранение файла

Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки:

- имя файла;
- размер;
- SHA-256;
- Arweave `txId`.

## Создание вложения в UI

UI поддерживает три сценария:

- загрузить новый файл в Arweave выбранным Arweave-кошельком;
- ввести существующий `txId`, скачать файл через Arweave gateway и локально посчитать `size/sha256`;
- выбрать файл из журнала файлов, загруженных в текущей браузерной сессии.

Журнал хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.

## Отображение

Новый клиент при чтении сообщения:

1. читает валидные attach-блоки только из начала текста;
2. скрывает технические attach-строки;
3. отображает вложения над пользовательским текстом;
4. каждое вложение показывает как карточку/ссылку на Arweave gateway;
5. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.

Старые клиенты без поддержки формата могут показывать attach-блоки как обычный текст.

## Редактирование

При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения по-прежнему выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`.

## Ограничения v1

- `ar` допускает только короткий Arweave `txId`, полный URL не используется;
- превью типа image/video/audio не входит в формат v1;
- MIME type, width, height, duration и thumbnail не записываются в блокчейн;
- проверка существующего `txId` скачивает файл локально через gateway, поэтому UI ограничивает максимальный размер такой проверки.