Состав и архитектура LeCodes

Инженерное описание среды разработки LeCodes: из чего состоит среда выполнения (LeCodes Runtime) и компилятор lecodes-cli, как они взаимодействуют, на каких платформах работают и какие компоненты входят в поставку. Документ подготовлен как техническое описание программного обеспечения.

1. Что такое LeCodes

LeCodes — среда разработки кроссплатформенных приложений на языке TypeScript. Разработчик описывает интерфейс и логику приложения с помощью LeCodes SDK (декларативный UI, 2D- и 3D-сцены, анимации, физика), компилятор собирает проект в единый переносимый JS-бандл, а среда выполнения (Runtime) исполняет этот бандл нативно на каждой из поддерживаемых платформ — без встроенного браузера (WebView) и без установки Node.js на устройство пользователя.

Конвейер целиком:

Исходники проекта (TypeScript)
        │
        ▼
Компилятор lecodes-cli  ──►  app.js (единый бандл приложения)
        │
        ▼
LeCodes Runtime (Windows / Linux / Astra Linux / macOS / iOS / Android / Web)

Один и тот же скомпилированный бандл исполняется на всех платформах: платформенно-зависимая часть полностью инкапсулирована в Runtime.

2. LeCodes Runtime

Runtime — это нативная (C++) среда исполнения приложений LeCodes. Она состоит из платформенно-независимого ядра и тонких платформенных «хостов», которые предоставляют ядру окно, графический контекст, ввод, звук и сеть.

2.1. Ядро исполнения — creator-pkg

Связывает JavaScript-код приложения с нативными подсистемами. Включает:

• Движок JavaScript — QuickJS. Встраиваемый интерпретатор ECMAScript (поставляется в составе исходников, с собственными патчами обработки очереди микрозадач). Каждое приложение исполняется в изолированном JS-контексте; доступ к системе возможен только через API, явно предоставленные средой.
• Мост JS ↔ натив. Биндинги нативных подсистем в JS-контекст (_creator — 3D, _creatorUI — интерфейс, _creator2d — 2D, _creatorUtils — служебные), диспетчеризация вызовов между потоками (JsDispatch / DispatchBridge).
• Подсистема времени и анимаций. Таймеры (setTimeout/setInterval), покадровый планировщик, менеджер анимаций (твины, кривые сглаживания).
• Загрузчик 3D-ресурсов. Разбор и загрузка моделей формата glTF/GLB.
• Навигация и экраны. Стек экранов приложения, жизненный цикл, обработка касаний/указателя и передача событий в UI-подсистему.

2.2. UI-подсистема — creator-ui

Платформенно-независимое ядро пользовательского интерфейса:

• раскладка элементов по модели flexbox;
• стили: цвета, границы, скругления, градиенты, тени, трансформации;
• анимируемые переходы свойств (transitions);
• виртуализированные списки (отрисовка только видимых элементов);
• вывод результата в виде списка команд отрисовки, которые исполняет платформенный рендерер (см. 2.4).

2.3. Графические движки

• 3D — creator-gl. Построен на движке рендеринга Google Filament (физически корректный рендеринг, PBR): сцены, камеры, освещение, материалы, скелетная анимация и морфинг, текстуры (PNG/JPEG/KTX2), окружение (IBL). Графические API: OpenGL / OpenGL ES / WebGL (через WebAssembly-сборку), Metal (iOS/macOS). Опционально подключается физический движок Jolt Physics (твёрдые тела, коллизии, контроллер персонажа).
• 2D — creator-2d. Лёгкий 2D-движок на графической библиотеке sokol (спрайты, атласы, слои) с 2D-физикой Box2D.

2.4. Платформенные хосты

Десктоп-хост дополнительно содержит:

• запуск приложения из локального файла (creator-desktop app.js) или по URL опубликованного проекта (creator-desktop https://le.codes/qr/<id>);
• WebSocket-клиент для режима разработки: горячая перезагрузка приложения при изменении исходников (lecodes dev), без перезапуска процесса;
• подсистемы ввода-вывода: файлы приложения, сеть (fetch), медиа (аудио/видео).

2.5. Формат исполняемого приложения

Приложение LeCodes — один JS-файл (бандл), содержащий весь код проекта и ссылки на ресурсы (модели, изображения, шрифты, звуки). Бандл не содержит нативного кода и одинаков для всех платформ; исполняется интерпретатором QuickJS внутри Runtime.

3. Компилятор lecodes-cli

lecodes-cli — консольная утилита разработчика: компилятор проектов и инструмент работы с платформой le.codes. Распространяется как автономный исполняемый файл (windows-x64, linux-x64 — статическая musl-сборка, один бинарник на все дистрибутивы Linux), не требует установленного Node.js, а также публикуется как npm-пакет lecodes-cli.

3.1. Компиляция

• Сборщик chisel (собственная разработка, язык Rust) — пакетирование проекта с гранулярностью до отдельных методов: в итоговый бандл попадает только реально используемый код SDK и проекта (агрессивное удаление мёртвого кода).
• Компилятор SDK — трансляция TypeScript-исходников проекта, разрешение модулей без внешних импортов, встраивание ресурсов (например, SVG-иконки разворачиваются в инлайн-источники на этапе сборки).
• Результат — app.js, готовый к исполнению любым LeCodes Runtime (lecodes preview -o app.js).

3.2. Команды

3.3. Режим разработки (lecodes dev)

CLI поднимает локальный сервер, следит за исходниками, пересобирает бандл при изменениях и по WebSocket отправляет обновление подключённым Runtime (десктоп-приложение или мобильное устройство, подключённое по QR-коду). Обновление применяется без перезапуска: Runtime создаёт новый изолированный JS-контекст и сцену, освобождая ресурсы предыдущей версии.

4. Сборка и распространение

• Версия Desktop-приложения фиксируется в файле VERSION, версия CLI — в пакете lecodes-cli; изменения ведутся в CHANGELOG.md.
• Релизные сборки: Windows (MSVC + clang-cl для QuickJS), Ubuntu (GCC), Astra Linux (сборка в Docker-окружении целевой ОС).
• Артефакты публикуются в неизменяемое хранилище releases/<продукт>/<версия>/<архив>; для каждого файла фиксируются размер и контрольная сумма SHA-256. Публичный манифест всех версий — versions.json.

5. Состав разработки и сторонние компоненты

Собственная разработка: ядро исполнения creator-pkg, UI-ядро creator-ui, 3D-обвязка creator-gl, 2D-движок creator-2d, десктоп-хосты Windows/Linux, мобильные хосты, LeCodes SDK, компилятор/сборщик chisel, lecodes-cli, серверная платформа le.codes.

Сторонние компоненты встроены в поставку в виде исходного кода или статических библиотек (внешних загрузок во время работы не происходит) и распространяются под свободными разрешительными лицензиями:

Инструменты сборки (в поставку конечных продуктов не входят): CMake, clang/GCC/MSVC, Emscripten (WebAssembly-сборки), Bun (упаковка автономного бинарника CLI).

6. Поддерживаемые платформы (сводно)