# Требования (по итогам опроса)

Два раунда вопросов. Ниже — зафиксированные решения и что каждое означает для архитектуры.

---

## R1. Форма продукта: визуальный конструктор, но по порядку

> «Работать следует в обычном порядке разработки… сперва разрабатываем основу,
> потом уже пытаемся сделать визуальный редактор». Тема «не горит», делается «на вырост».

**Следствие.** Цель — визуальный конструктор, но строим снизу вверх: сначала движок и
формат пака, редактор — надстройка над уже работающим ядром. Ядро обязано быть
самоценным: паки должны собираться и работать ещё до появления редактора.

## R2. Аудитория: я + пара соведущих, нетехнические

> «не все технически подкованы, например я — полный нуб и гуманитарий»

**Следствие — это главное ограничение проекта:**

* никакого терминала, `npm install`, сборки — ни на одном шаге пользователя;
* никакой правки JSON руками как обязательного пути (только как «для продвинутых»);
* документация человеческим языком, без жаргона;
* разрушительные действия обратимы, ошибки объясняются словами;
* результат должен работать двойным кликом.

## R3. Старые паки: референс + переосмысление

Механики (альфа-дырки, правка кликом, синхронизация сцен, слой помех) забираем.
Визуал и набор сцен делаем заново, не тащим legacy-разметку и не обещаем
байт-в-байт повторение VHS/Cyber/ORDO/SPO.

## R4. Виджеты встраиваются внутрь оверлея, а не расставляются в OBS

> «источники, не являющиеся частью оверлея, я и так буду расставлять руками.
> если есть возможность отдать ссылки встраивания всех виджетов и получать
> на выходе готовые сцены, было бы здорово» + выбор «любые — просто слоты под ссылку»
> + отказ от экспорта сцен-коллекции OBS.

**Решение (уточнено): остаёмся на модели паков.**

> «давай пока без виджетов, поработаем на старом варианте — буду добавлять сцены
> как браузерные источники»

Встраивание виджетов внутрь оверлея (iframe) **из ядра убрано**. Оверлей рисует рамку
и подпись окна, а что окажется внутри — камера или браузерный источник с виджетом —
пользователь ставит в OBS сам, как в нынешних паках.

Типы окон:

| Тип | Что делает | Что в OBS |
|---|---|---|
| `cam` | прорезает альфа-дырку | источник камеры **под** оверлеем |
| `slot` | прорезает дырку, ждёт чужой источник | браузерный источник **поверх** оверлея |
| `panel` | декоративная панель без дырки | — |

Значит, **таблица координат остаётся полноценной рабочей инструкцией** — по ней
расставляются и камеры, и виджеты. Тем важнее, что она генерируется из `layout`
автоматически (в паках её вели руками, и она разъезжалась с кодом).

*Отложено, не отменено.* Слой встраивания — изолированная надстройка: тип окна
`embed` со ссылкой. Когда понадобится, добавляется, не трогая ядро. Оговорка на
будущее: часть сайтов запрещает iframe (`X-Frame-Options`) — виджеты стримерских
сервисов обычно работают, VTT вроде Roll20/Foundry скорее нет.

## R5. Визуал: код рисует обвязку, фоны — свои картинки

Рамки, плашки, помехи, градиенты — CSS/SVG, параметризуются темой.
Фоны сцен — подставляемые файлы (как нынешние `bg_*.jpg`). Генерация ИИ не нужна.

## R6. Сцены: всё из паков + неролевые + разнообразие интро

> «Всё из паков + не ролевые, причём для интро нужно разнообразие анимаций»

Ролевые: `intro` · `start` · `game` · `pause` · `end` · `desk` (стол улик) · `map` (окно под VTT/карту).
Неролевые: одна камера + геймплей · болтовня · подкаст на двоих.
**Интро — не одна заставка, а набор сменных анимаций** (отдельная подсистема, см. план).

## R7. Управление: правка кликом в источнике — приоритет

> «в первую очередь, правка кликом прямо в источнике, а не возня со ссылками»
> Док-панель с настройками — «было бы круто», но не обязательна.

**Следствие.** `data-edit` + `contenteditable` + `localStorage` — основной путь, доводим
до ума (в паках он уже есть). URL-параметры остаются, но как служебный/запасной путь.
Док-панель — отдельная страница-пульт, синхронизируется со сценами; фаза позже.

## R8. Запуск конструктора: Pages если бесплатно, иначе папка

> «если гитхаб пейджес бесплатный, то мне нужен он. если платный — папка устроит»

**Факт:** GitHub Pages бесплатен **для публичных** репозиториев; чтобы публиковать из
**приватного**, нужен платный GitHub Pro. Репозиторий `Abdel-NRLRM/overlay` сейчас
приватный, поэтому бесплатный Pages «из коробки» недоступен.

Варианты (решение за тобой, в плане заложен третий):

1. **Сделать репозиторий публичным** → Pages бесплатно. Код оверлеев виден всем.
2. **Оставить приватным** → Pages требует Pro (~$4/мес). Либо бесплатная альтернатива —
   Cloudflare Pages, он умеет публиковать и из приватных репозиториев.
3. **Не зависеть от хостинга вовсе** ← *принято по умолчанию.*

**Архитектурное следствие (важное).** Делаем всё так, чтобы работало **и там, и там**:
zero-build, никаких ES-модулей и `fetch` локальных файлов, данные пака вшиты в страницу
инлайн-скриптом. Тогда `index.html` открывается двойным кликом с диска (`file://`),
и тот же самый код без изменений разворачивается на Pages/Cloudflare, если захочется.
Решение о хостинге можно принять когда угодно потом — оно ничего не ломает.

---

## Сводка ограничений, которые определяют архитектуру

1. **Zero-build для пользователя** — ни терминала, ни установки.
2. **Работает с `file://`** — без модулей, без `fetch` конфигов.
3. **Виджеты внутри оверлея** (iframe), камеры — альфа-дырки.
4. **Правка кликом** — первичный способ ввода данных.
5. **Тема отделена от разметки** — новый стиль без форка движка.
6. **Раскладка декларативна** — одна таблица → DOM, маска дырок и документация.