# Технические вставки внутри plaintext DM v1

## Статус документа

Этот файл описывает внутренний формат технических вставок, которые находятся внутри уже расшифрованного plaintext DM.

Важно:

- это не отдельный серверный DM-envelope;
- это часть plaintext контентного DM после E2EE-расшифровки;
- сервер не обязан знать этот формат;
- клиент может использовать эти вставки для специального UI-рендера.

## 1. Общий принцип

Обычное сообщение по-прежнему остаётся обычным текстом.

Если в начале plaintext стоит один или несколько специальных блоков формата:

```text
<SHiNE:...>
```

то клиент трактует их как технические вставки.

Техническими считаются только блоки, которые:

- стоят строго в начале plaintext;
- начинаются с точного префикса `<SHiNE:`;
- заканчиваются первым символом `>`.

Если текст не начинается с `<SHiNE:`, никакие технические вставки не ищутся.

## 2. Правило скрытия

Все корректно распознанные блоки `<SHiNE:...>` в начале plaintext:

- не показываются пользователю как сырой текст;
- используются клиентом для UI-логики;
- неизвестные будущие типы тоже скрываются, если они распознаны как корректный SHiNE-блок.

Если блок битый и не закрыт символом `>`, он не считается техническим и сообщение показывается как обычный текст целиком.

## 3. Защита от случайного пользовательского ввода

Перед отправкой обычного текстового сообщения клиент обязан проверить:

- если пользовательский текст начинается с `<SHiNE:`

то клиент автоматически превращает начало в:

```text
< SHiNE:
```

Такой текст уже не считается техническим блоком и должен отображаться как обычное сообщение.

## 4. Формат блока

Общий вид:

```text
<SHiNE:kind;key=value;key=value;...>
```

Правила:

- `kind` — ASCII-идентификатор типа вставки;
- параметры отделяются `;`;
- ключ и значение отделяются `=`;
- значения не экранируются в v1;
- формат чувствителен к точному префиксу `<SHiNE:`.

## 5. Тип `reply`

Формат:

```text
<SHiNE:reply;v=1;id=user1|user2|1720612345678|77>Текст ответа
```

Где поле `id` — это логический идентификатор сообщения:

```text
fromLogin|toLogin|timeMs|nonce
```

Правила:

- этот блок должен стоять в начале plaintext;
- после него может идти обычный текст ответа;
- официальный UI формирует такой блок при отправке ответа через пункт `Ответить` в меню сообщения;
- если клиент не находит сообщение, на которое ссылается `reply`, он просто не показывает reply-preview;
- в таком случае само сообщение отображается как обычный текст без блока `<SHiNE:reply...>`.

## 6. Тип `call`

### Успешный звонок

```text
<SHiNE:call;v=1;status=completed;duration=367>
```

Где:

- `duration` — длительность разговора в секундах.

### Неуспешный звонок

```text
<SHiNE:call;v=1;status=failed;reason=offline>
```

Допустимые причины в v1:

- `offline`
- `no_answer`
- `connect_failed`
- `busy`
- `declined`

Правила:

- call-блок в v1 должен содержать только техническую запись звонка;
- пользовательский текст после такого блока в штатной логике не предполагается;
- UI может рисовать такие сообщения отдельным специальным стилем.
- официальный UI не отправляет call-summary, если от старта исходящего звонка до его завершения прошло меньше `5` секунд.

## 7. Поведение официального UI

Официальный UI SHiNE в v1:

- скрывает все корректные `<SHiNE:...>` блоки в начале plaintext;
- для `call` строит специальный человекочитаемый текст:
  - `Звонок: M:SS`
  - `Звонок: H:MM:SS`
  - `Звонил, но недозвонился: ...`
- для `reply` скрывает сам блок и показывает только текст ответа;
- если исходное reply-сообщение не найдено, reply-preview не показывается.

## 8. Совместимость

Так как это часть plaintext, а не часть серверного envelope:

- сервер не обязан понимать этот формат;
- будущие клиенты могут добавлять новые `kind`;
- клиенты, которые распознают SHiNE-вставки, должны скрывать неизвестные блоки целиком, если они стоят в начале и корректно закрыты.