REEEL Project

This page has not been translated into English yet. The Russian original is below.

Статус: структура проекта стабильна; синхронизация и сборка реализованы поверх платформы api.reeel.dev (клиент — пакет reeel_platform_client , интеграция в редакторе — PlatformSyncService ). Детали и статус — в sync_and_build.md .

Зачем нужен уровень «проект»

REEEL Project — самодостаточная единица работы: каталог с предсказуемой структурой и манифестом project.json , который перечисляет собираемые конфигурации (iOS, Android, macOS, Windows, Linux, PWA/web, Tizen, …). Манифест явно связывает контент с приложениями, в которые он собирается. По аналогии со схемами сборки в Xcode / Android Studio редактор показывает выпадающий список «вариантов сборки» и предлагает собрать любой из них.

Проект синхронизируется с платформой api.reeel.dev : контент заливается как content-addressed снимок (ревизия), blob'ы лежат в объектном хранилище storage.reeel.dev . Сборку выполняет отдельный build-worker (планируется), который забирает задачу вместе со снимком ревизии, собирает выбранную конфигурацию и возвращает артефакт. Подробнее — sync_and_build.md .

Глоссарий

Структура на диске

my-reeel-project/
├── .reeel/                 # данные редактора — НЕ синхронизируется
│   └── state.json          # открытые вкладки, раскрытые узлы, скролл, выбор
├── reeel/                  # контент — синхронизируется
│   ├── main.reeel          # точка входа (из project.json)
│   ├── 404_notfound.reeel  # страница «не найдено»
│   └── components/         # переиспользуемые компоненты
├── data/                   # данные проекта — синхронизируется
│   ├── theme/              #   data/theme/<mode>.json → ambient $theme.*
│   │   ├── light.json
│   │   └── dark.json
│   ├── strings/               #   data/strings/<locale>.arb → ambient $strings.*
│   │   ├── en.arb
│   │   └── ru.arb
│   ├── images/             #   картинки: Image src:"data/images/logo.png"
│   │   ├── logo.png
│   │   ├── onboarding/     #     вложенность любая — она часть пути
│   │   └── favicon/        #     иконки сайта (kind:website)
│   ├── web/                #   авторские скрипты и HTML для сайта (kind:website)
│   │   ├── scripts/        #     *.js для Script src: и settings.scripts
│   │   └── html/           #     *.html для HtmlEmbed src:
│   └── products.json       #   произвольные данные для JsonData
└── project.json            # манифест — синхронизируется

./reeel/ — единый плоский корень контента , без слоёв дизайна. Точка входа задаётся явным путём в project.json (поле entry , по умолчанию reeel/main.reeel ); каталог этого файла становится корнем, относительно которого резолвятся все маршруты ( AppRoute /home ) и импорты ( components/theme ). Слои platform / design / common в построении пути не участвуют.

./.reeel/ — данные редактора

Каталог используется REEEL-редактором для хранения сессии ( state.json : раскрытые узлы дерева, выбранный файл, открытые вкладки, активная вкладка, позиции скролла).

• Не отправляется на сервер при синхронизации проекта.
• Может коммититься в git по желанию команды (например, чтобы делиться удобными пресетами редактора), но не обязан.
• Содержимое — приватная зона редактора/инструментов; формат может меняться.

./.reeel/generations/ — архив генераций изображений

Всё, что нарисовал агент, — включая отвергнутое. Каталог на сессию:

.reeel/generations/2026-09-01T14-22-08/
  INDEX.md        промпт, модель, размер, время, кредиты — для человека
  session.json    то же машиночитаемо: попытки по порядку, что принято
  01.png 02.png   кандидаты, в порядке появления
  refs/           копии референсов

Размер один, а не пропорция плюс тир разрешения. Так было до 02.09.2026, пока вендор был один: aspectRatio и imageSize — это оси Gemini, а у второго вендора оси другие (пиксели и уровень качества). Архив пишет size вида 1536x1024 — то, что попросили, — и model . Пиксели ТОГО, ЧТО ВЕРНУЛОСЬ, измеряются отдельно из самих байтов: вендор отвечает на пропорцию картинкой своего размера, и эти два числа не совпадают.

Каждая попытка стоила денег, поэтому пишется сразу, а не в конце: редактор, который закрыли или который упал, не должен уносить запись об оплаченной генерации.

Принятая картинка отсюда копируется в data/images/ и только оттуда работает. Путь под .reeel/ — не просто неопубликованный: ReeelAssetRef.parse отвергает любой сегмент с точки, поэтому Image src:".reeel/…" — это невалидная ссылка, которую анализатор помечает ошибкой , а не ненайденным файлом.

Референсы копируются, а не берутся по ссылке: оригиналы переезжают и правятся, а промпт рядом с картинками, которые «где-то там», через месяц не отвечает ни на что.

./reeel/ — контент

REEEL-вёрстка. Единственная «полезная нагрузка», которую сервер хранит и отдаёт клиентам. Это плоский корень контента: точка входа задаётся полем entry в project.json , остальные страницы и компоненты резолвятся относительно неё.

./data/ — данные проекта

Файлы данных, читаемые контентом по путям относительно корня проекта. Помимо произвольных JSON для генератора JsonData ( data/products.json ), здесь живут ambient-данные оформления , которые автоматически наполняют $theme и $strings (без import / JsonData в вёрстке):

• data/theme/<mode>.json → токены темы, режим = имя файла ( dark.json → dark ). Читается как $theme.* .
• data/strings/<locale>.arb (или .json ) → строки локали, локаль = имя файла ( en.arb → en ). Читается как $strings.* .

Картинки — data/images/

Image src:"data/images/logo.png" width:240 height:64
Image src:"data/images/onboarding/hero.webp" fit:cover

Путь всегда от корня проекта , а не относительно файла, где написана строка. Причин три, и каждая уже стоила ошибки:

1. Раскрытие макроса переносит разметку между файлами, так что «текущий файл» на момент резолва — не тот, где строка написана.
2. Ключ файла в ревизии — ровно этот путь от корня; приложение, читая картинку, не знает и не может знать, откуда на неё сослались.
3. Путь с .. не синхронизируется вовсе : он отклоняется и клиентом, и сервером. То есть такая ссылка называет файл, которого в опубликованном проекте быть не может, — при том что в редакторе он открывается с диска. Поэтому это error , а не предупреждение.

Ссылка со схемой ( https://… , data: ) — внешний ресурс, он не проверяется и не синкается.

Форматы. Приложение рисует png , jpg , webp , gif (в том числе анимированные), bmp , wbmp и svg . Браузер рисует ещё .ico и .avif , но приложение их не декодирует: на сайте картинка будет, в приложении — пустое место. Вектор — картинка, но не фон и не аватарка.

Что попадает в сборку. В артефакт собираются reeel/ и data/ целиком. Файлы, лежащие в других каталогах проекта, синхронизируются на платформу, но в приложение не попадают — поэтому картинкам место в data/ , а не рядом с project.json .

Вес. Ни синхронизация, ни сборка не ограничивают размер файла: двадцать мегабайт уедут и в снимок, и в артефакт молча. Инструмент reeel_assets печатает вес каждой картинки — это единственное место, где он виден заранее.

Иконки сайта — data/images/favicon/

Для проекта с kind: website . Всё, что лежит в этом каталоге, объявляется в <head> ; размеры читаются из самих файлов, а не из имён. Файлы favicon.ico и apple-touch-icon.png дополнительно отвечают по корневым адресам — туда браузер ходит сам, независимо от разметки.

Не путать с data/icons/ — там лежат иконочные ШРИФТЫ ( icons.json ), из которых берутся глифы для Icon .

Авторские скрипты и HTML — data/web/

Для проекта с kind: website :

• data/web/scripts/*.js — файлы, на которые ссылаются элемент Script ( src: ) и `settings.scripts` ;
• data/web/html/*.html — файлы для HtmlEmbed ( src: ).

Каталог синкается и отдаётся общим механизмом /data/<path> — отдельного sync-правила и объявления в манифесте нет. Ссылки — полным путём от корня проекта ( Script src:"data/web/scripts/analytics.js" ), как у картинок: голое имя, .. и посторонние схемы компилятор отвергает. Исполняется авторский код на адресах самого сайта — на <slug>.reeel.site и на подключённом домене; под корнем платформы ( *.app.reeel.dev и др.) он в HTML не эмитится вовсе.

Эти каталоги обнаруживаются в runtime (никакого хардкода списков); переключение — theme.set(...) / strings.set(...) , выбор сохраняется. Подробно — Тема и локализация .

./project.json — манифест

Описывает проект и список собираемых конфигураций. Полная схема — в project_json.md .

Что синхронизируется с сервером

Синхронизируется всё содержимое проекта , кроме путей, где любой сегмент начинается с . (единственное исключение — .well-known/ ):

Правило исключения зашито в PlatformSyncService.isSyncablePath и совпадает с серверной проверкой forbidden_path . ⚠️ При выключенном content-gating всё синкнутое публично читаемо — не кладите секреты в синкаемые файлы.

Платформа хранит контент как content-addressed снимок (ревизию) и ставит сборки в очередь; трёхфазный протокол sync и постановка сборки — в sync_and_build.md .

Документы раздела

• project_json.md — схема project.json (минимальная, v1 неявная; без project-level name ), конфигурации, точка входа ( entry ), связь с config.json и таблица миграции с configs/ .
• sync_and_build.md — реальный контракт платформы api.reeel.dev : аутентификация, трёхфазный snapshot-sync, очередь сборок, клиент reeel_platform_client и статус реализации.
• site_assistant.md — ИИ-помощник сайта: каталог assistant/ (база знаний, assistant.json , prompt.md ), лимиты, следующие шаги и что помощник делает сам.