trail-mate/docs/UI_SHARED_IDF_PHASE_PLAN.md

UI Shared / IDF Migration Plan

This document is used to explain: how to extract UI logic from each apps/* and deposit it into a reusable shared layer that is compatible with both PlatformIO and ESP-IDF entrances.

---

1. Goal

1.1 Overall goal

1. Concentrate common UI pages, shells, controllers, and runtime interfaces into modules/ui_shared
2. Let apps/esp_pio and apps/esp_idf Only keep the respective platform entrance, startup process and adapter
3. Avoid shared UI directly relying on Arduino or ESP-IDF specific implementation details

1.2 Migration principles

• Page structure, interaction and state logic are first deposited into the shared layer
• Platform differences converge to platform/* and app runtime adapter
• Do not maintain an implementation of the same page in PIO / IDF respectively
• For capabilities that cannot be shared temporarily, use capability-gated fallback to occupy the space

---

2. Layered boundary

2.1 modules/ui_shared

Host:

• page shell
• Page component
• controller / presenter
• Runtime abstract interface
• Universal fallback page

Should not directly depend on:

• <Arduino.h>
• <Preferences.h>
• nvs.h
• Specific board-level API

2.2 apps/esp_pio / apps/esp_idf

Host:

• startup / boot
• menu / app catalog entry
• loop driver
• life cycle management
• facade / runtime adapter assembly

2.3 platform/*

Host:

• Device capability implementation
• Screen/sleep/audio/GPS/storage and other platform APIs
• Arduino and IDF respective contract implementation

---

3. Current status (as of 2026-03-11)

3.1 Shared page skeleton

Has been moved to shared shell + runtime/components/controller page:

• Settings
• Chat
• GPS / Map
• GNSS Sky Plot
• Contacts
• Team
• Tracker
• PC Link
• USB
• SSTV
• Protocol Probe (internal route: energy_sweep)
• Walkie Talkie

3.2 apps side status

apps/esp_pio/src and apps/esp_idf/src have gradually converged to the following responsibilities:

• startup_runtime.cpp
• loop_runtime.cpp
• app_runtime_access.cpp
• app_registry.cpp

Among them esp_idf Also included:

• runtime_config.cpp
• app_facade_runtime.cpp
• idf_entry.cpp
• idf_component_anchor.cpp

3.3 Completed Cleanup

• A batch of old IDF retired stubs have been removed
• ui_common_stub.cpp / ui_status_stub.cpp in modules/ui_shared has been significantly shrunk
• Most of the ui_*.cpp retained under apps/esp_pio/src only have wrapper responsibilities

---

4. Phased plan

Phase 0: Inventory and hemostasis

Goal

• First clarify which pages have been shared and which ones still have app private implementation
• Stop adding duplicate page implementation

Delivery

• Page ownership list
• App private wrapper list
• Shared shell gap list

---

Phase 1: apps entry convergence

Goal

Converge apps/esp_pio and apps/esp_idf into "start + loop + runtime wiring".

Tasks

1. Align app_catalog / menu / startup / loop to shared mode
2. Clean up the historical page wrapper / registry special case in apps/esp_pio
3. Convergence Life cycle and runtime access of app_runtime_access
4. Unify the startup / loop / event driver mode of esp_pio / esp_idf

Complete the standard

• The app directories at both ends no longer carry specific UI logic
• The app entry can stably drive the shared app catalog / shared shell

---

Stage 2: Page sharing completed

Goal

Really unify the page layer to shared:

• shell
• host
• fallback
• components / controller / runtime

Tasks

1. Complete shared shell + components/runtime
2. Remove residual page logic on the app side
3. Unify the wiring between app catalog and shared page shell
4. Use capability-gated fallback for missing capabilities

Complete the standard

• The page structure is only maintained in modules/ui_shared
• The fallback behavior is consistent
• The app side no longer copies the page implementation

---

Phase 3: Platform capability abstraction completed

Goal

Converge all the device capabilities that shared UI depends on into the adapter contract.

Requires the ability to abstract

• restart
• kv / config persistence
• screen sleep
• tone / audio preview
• GPS runtime control
• tracker recording hook
• hostlink / USB capability hook
• walkie / sstv / lora support

Placement

• Arduino is implemented in platform/esp/arduino_common
• IDF is implemented in platform/esp/idf_common and apps/esp_idf/*runtime

Complete the standard

• modules/ui_shared no longer directly contains ESP proprietary header files
• shared only relies on platform contract

---

Phase 4: Configuration and profile convergence

Goal

Unify device profile, visual size, and capability differences into runtime config / page profile.

Key points

• tab5
• tdeck
• pager

Requirements

• Topbar, height, spacing, icon cards, etc. are driven by shared profile
• Board-level differences are not scattered in the page code

---

5. Risk points

• The shared page has completed structural migration, but the runtime hook may still have platform coupling
• PIO / IDF The life cycle rhythms of the two sets of entrances are not completely consistent, and it is easy to have differences in the order of events
• fallback If the design is too weak, it will cover up the real gaps in the short term
• Before the profile is completely unified, layout bifurcation may continue to occur on different devices

---

6. Acceptance criteria

• modules/ui_shared becomes the only source of truth for the page UI
• apps/esp_pio and apps/esp_idf are mainly responsible for startup and assembly
• Platform differences only appear in platform/* and runtime adapter