Event System (система событий)

Системные и пользовательские события, подписки, стримы. Архитектура без реализации.

Event System — слой поверх Bridge, отвечающий за однонаправленную доставку сообщений (события) и многократную доставку по подписке (стримы) между нативом и JS.

1. Виды событий

Вид	Направление	Примеры
Системные (lifecycle)	native → JS	ready, pause, resume, backbutton, memoryWarning, orientationchange, deeplink, destroy
Обложка (cover)	native → JS	cover:action, cover:active, cover:inactive
Плагинные	native → JS	network:change, keyboard:show/hide, battery:level и т.п.
Стримовые	native → JS	геолокация, сенсоры, прогресс — серия сообщений по одной подписке
Пользовательские	JS → native	приложение эмитит события, на которые подписан натив/плагин

2. API подписки (концептуально)

const off = Aurobore.on("pause", () => { … });   // подписка на событие
off();                                            // отписка

const sub = Aurobore.Geolocation.watch(pos => { … });  // стрим
sub.stop();                                            // остановка стрима

• on(name, handler) возвращает функцию отписки.
• Стрим-подписка возвращает объект с методом остановки (и, опционально, статусом).
• Поддержка одноразовых (once) и постоянных подписок; автоматическая очистка при выгрузке.

3. Модель стримов

Стрим — это invoke с флагом подписки; native шлёт серию сообщений с общим subscriptionId:

JS: watch(cb)  →  invoke(meta.stream=true)  →  subscriptionId
native: source.start()
native → JS: { stream, subscriptionId, phase:"data",     payload }   (многократно)
native → JS: { stream, subscriptionId, phase:"error",    error }     (при ошибке)
native → JS: { stream, subscriptionId, phase:"complete" }            (завершение)
JS: sub.stop()  →  cancel(subscriptionId)  →  native: source.stop()

• Backpressure / батчинг (SHOULD, FR-B8): высокочастотные источники (сенсоры) могут агрегировать/прореживать сообщения, чтобы не перегружать JS-поток.
• Отписка обязательно останавливает источник на native-стороне (экономия батареи/ресурсов).

4. Шина событий и маршрутизация

• На JS-стороне — реестр подписчиков name → Set<handler> и subscriptionId → handler.
• На native-стороне — Plugin Manager/Runtime эмитят события через Bridge.
• Гарантия порядка в пределах одного источника/подписки; между разными источниками порядок не гарантируется.
• Доставка по модели «выстрелил-и-забыл»: без подтверждения и без результата (в отличие от invoke).

5. Жизненный цикл и очистка

• Подписки, созданные приложением, действуют в пределах сессии WebView.
• При pause высокочастотные стримы могут приостанавливаться (политика плагина), возобновляясь при resume.
• При перезагрузке/destroy все подписки и источники гарантированно освобождаются.

6. Ошибки в событиях/стримах

• Ошибка источника доставляется как phase:"error" с структурой ошибки моста (см. bridge.md).
• Исключение в обработчике на JS-стороне не должно ломать доставку другим подписчикам.

7. Связи

• ↔ Bridge — транспорт событий/стримов.
• ↔ Runtime — источник системных событий.
• ↔ Plugin System — плагины как источники событий/стримов.
• ↔ TypeScript SDK — типизированные подписки.