/* meow_ui_nav.h — App 侧 M3 导航上报封装（SDK 公共件）。
 *
 * App 用它把「应用内页面栈深/顶层 activity」经 IPC 报给 launcher（MSG_NAV REPORT），
 * 以及在根屏按返回时请求退出（MSG_NAV EXIT）；launcher 据此维护每 app 导航栈（纯上报，
 * 回退边界由 launcher 统一决定）。App 不渲染系统 UI（FRAMEWORK_DESIGN §3 / MEOW_APP_SDK §6.1）。
 *
 * 命名：launcher 侧已占用 meow_nav_*（app_launcher.c），SDK 侧统一 meow_ui_nav_* 前缀，
 * 避免两态同符号在 launcher（链 meow_ui.a + app_launcher.c）出现重复定义。
 *
 * 冷启动链路：launcher 经 MEOW_ACTIVITY=<top> / MEOW_CHAIN=<id0>;<id1>;...;<top> 注入；
 * meow_ui_nav_init() 读之初始化栈深/顶层。App 自行 push/pop 页面后经 meow_ui_nav_report()
 * 上报新深度/顶层。
 */
#ifndef MEOW_UI_NAV_H
#define MEOW_UI_NAV_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* 从 env 初始化（幂等）：MEOW_CHAIN 段数→栈深；MEOW_ACTIVITY→顶层 activity_id。
 * 未注入（裸启动）→ 深度 0、顶层空串。app_id 取 env MEOW_LOG_APP（缺省 "app"）。
 * 返回当前逻辑深度（0=未注入/裸启动）。 */
int  meow_ui_nav_init(void);

/* 当前栈深 / 顶层 activity_id（meow_ui_nav_init 后为其初值；App 上报后更新）。 */
int  meow_ui_nav_depth(void);
const char *meow_ui_nav_top(void);

/* 上报 MEOW_NAV_REPORT：App 弹/推自己的屏后调用（depth=当前逻辑深度 1..16，top=顶层）。
 * best-effort：launcher 不在/无 socket 静默降级，不崩。 */
void meow_ui_nav_report(uint32_t depth, const char *top);

/* 上报 MEOW_NAV_EXIT：App 在根屏按返回，请求 launcher 终止应用回主屏。best-effort。 */
void meow_ui_nav_request_exit(void);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_NAV_H */