Добавить Turbo-загрузку и превью для вложений

docs/Blockchain/15_TEXT_Attachments.md

@@ -1,4 +1,4 @@
-# Вложения в TEXT-сообщениях (`SHiNE:attach v=1`)
+# Вложения в TEXT-сообщениях (`SHiNE:attach v=1/v=2`)
 
 Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.
 
@@ -21,6 +21,12 @@
 <SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
 ```
 
+Блок с превью:
+
+```text
+<SHiNE:attach;v=2;name=video.mp4;size=5820193;sha256=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;previewAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;previewSha256=eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee>
+```
+
 Несколько вложений идут подряд в самом начале текста:
 
 ```text
@@ -43,6 +49,11 @@
 - `sha256` - SHA-256 исходного файла в hex, 64 символа;
 - `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL.
 
+Дополнительные поля для `v=2`:
+
+- `previewAr` - короткий Arweave Transaction ID файла-превью;
+- `previewSha256` - SHA-256 файла-превью в hex.
+
 ## Хранение файла
 
 Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки:
@@ -52,6 +63,8 @@
 - SHA-256;
 - Arweave `txId`.
 
+Опционально для видео или больших изображений может храниться отдельный второй файл-превью. В таком случае основной attach-блок остаётся одним, но дополнительно указывает `previewAr/previewSha256`.
+
 ## Создание вложения в UI
 
 UI поддерживает три сценария:
@@ -60,6 +73,15 @@ UI поддерживает три сценария:
 - ввести существующий `txId`, скачать файл через Arweave gateway и локально посчитать `size/sha256`;
 - выбрать файл из журнала файлов, загруженных в текущей браузерной сессии.
 
+Для видеофайлов UI может по желанию пользователя автоматически создать превью из первого кадра. Технически клиент загружает два файла:
+
+- основной видеофайл;
+- отдельное изображение-превью.
+
+После успешной загрузки в журнале хранится один элемент основного файла, но с полями `previewAr/previewSha256`. В UI такой элемент помечается как файл `С превью`.
+
+При ручном добавлении существующего `txId` для видео UI также позволяет вручную указать `txId` файла-превью.
+
 Журнал хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
 В настройках клиента есть отдельный экран `Загрузка файлов`: пользователь может заранее загрузить файл в Arweave без создания сообщения, увидеть компактную плитку с именем, размером, временем загрузки, `txId` и статусом доступности через gateway, а затем выбрать этот файл из истории при создании сообщения.
 Если файл загружен заранее, но ещё не был отправлен ни в одном сообщении SHiNE, клиент показывает локальный флаг `Не добавлен в SHiNE`. Флаг снимается после успешной отправки сообщения с этим вложением.
@@ -77,8 +99,9 @@ UI поддерживает три сценария:
    - изображение показывает как ограниченное по размеру превью;
    - видео показывает как превью с кнопкой воспроизведения и открывает большой HTML5-плеер по нажатию;
    - обычный файл показывает как карточку с именем, расширением, размером и скачиванием;
-6. при перелистывании останавливает воспроизводящееся видео;
-7. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.
+6. если у видео есть `previewAr/previewSha256`, использует отдельный preview-файл как `poster` и как большую превью-плитку в журнале загрузок;
+7. при перелистывании останавливает воспроизводящееся видео;
+8. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.
 
 Если файл по ссылке Arweave gateway недоступен, клиент показывает диагностический блок:
 
@@ -91,9 +114,11 @@ UI поддерживает три сценария:
 
 При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения по-прежнему выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`.
 
-## Ограничения v1
+## Совместимость и ограничения
 
 - `ar` допускает только короткий Arweave `txId`, полный URL не используется;
 - MIME type не записывается, поэтому UI определяет image/video/file по расширению имени файла;
-- MIME type, width, height, duration и thumbnail не записываются в блокчейн;
+- старые блоки `v=1` без превью остаются валидными и читаются без изменений;
+- `previewAr/previewSha256` используются только если присутствуют оба поля и оба валидны;
+- MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями;
 - проверка существующего `txId` скачивает файл локально через gateway, поэтому UI ограничивает максимальный размер такой проверки.