/*
 * meow_ui_activity.h — SDK 控件生命周期与归属（§6.1）：Activity 栈 + 三层控件模型。
 *
 * 原 meow_ui.h 拆分的一部分（activity 模块）。根治「跨页面控件残留」：控件命中/绘制必须严格
 * 绑定其所属页面。三层职责（App→系统）：①页面控件（绑定 owner Activity）；②App 跨 Activity
 * 控件（SDK 托管骨架）；③系统级控件（状态栏/通知中心/返回滑条/电源菜单，仅框架内部，无公共 API）。
 */
#ifndef MEOW_UI_ACTIVITY_H
#define MEOW_UI_ACTIVITY_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §6.1 控件生命周期与归属（Activity 栈 + 三层控件模型） [源:2026-08-30] */
/* ============================================================ */
/* 根治「跨页面控件残留」：控件命中/绘制必须严格绑定其所属页面，否则会出现
 * "按钮已不可见但仍被触摸命中"（如全屏页触摸到主页按钮位置闪现 accent 底）。
 *
 * 三层职责（从 App 到系统，风险从低到高）：
 *   ① 页面控件：归属唯一 owner Activity；命中/实时按压只在「当前 active Activity
 *      的控件集」里生效。对象不销毁（同 Activity 内复用），弹栈回来自动恢复 →
 *      回页面零重建。
 *   ② App 跨 Activity 控件（SDK 托管）：钉在 App 的 Activity 栈之上、跨 Activity 常驻，
 *      逻辑/渲染由 SDK 调度。本轮为「可用骨架」（见上 API 注释），待 B2 细化。
 *   ③ 系统级控件（状态栏/通知中心/返回滑条/电源菜单）：仅框架内部，无公共 API（不开放）。
 *
 * 触摸命中分流顺序：③ 系统全局 → ② App 全局 → ① 当前 active Activity 页面控件；
 * 某层命中即消费，否则落到下一层。 */

/* ① Activity 栈。控件创建时绑定「当前 active Activity」为 owner；弹栈回来自动恢复。
 * 栈空时 active() 返回 0（根/default Activity），故未显式管理栈的 App 默认所有控件
 * 归属根 Activity 0。push 新 Activity（进子页/全屏）、pop 回上级（回根）。 */
void meow_ui_activity_push(int id);
void meow_ui_activity_pop(void);
int  meow_ui_activity_active(void);            /* 当前 active activity id（栈空=0） */
int  meow_ui_activity_depth(void);             /* 当前栈深（push/pop 页数；供 M3 导航上报用） */

/* ② App 跨 Activity 控件（SDK 托管，骨架）。SDK 维护全局控件列表：
 *   - 渲染：每帧（有脏区需上屏时，meow_ui_gfx present()）在 active activity 内容之上、
 *     全局状态栏之下调用 render_cb（跨 Activity 常驻）；
 *   - 触摸：TAP 先给 global hit_cb（返回 1=消费），否则落到 active activity 页面控件。
 * 逻辑/渲染由 SDK 调度，App 只需声明。注：骨架，待 B2 细化。 */
typedef void (*meow_global_render_fn)(void *ctx);   /* 每次渲染帧回调（SDK 调用） */
typedef int  (*meow_global_hit_fn)(void *ctx, int x, int y); /* 命中返回1=消费 */
void meow_ui_global_add(int id, meow_global_render_fn r, meow_global_hit_fn h, void *ctx);
void meow_ui_global_remove(int id);

/* ③ 系统级控件：状态栏/通知中心/左缘返回滑条/电源菜单等全局叠加层——仅 SDK 内部接口，
 * 不向用户 App 开放任何公共悬浮/叠加层 API。既有状态栏/返回滑条逻辑（§3.1）不动。 */

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_ACTIVITY_H */