sdk(ui): W_LISTVIEW 虚拟化层 — 固定 item 池 + 多行富 item + 完全自绘 (§5.5)

在既有 W_LISTVIEW (src2 每帧取行) 之上叠加虚拟化层 (API 追加式, 旧 API 一字不改):
- 数据源 count_fn + bind_fn (index, meow_lv_item*, ctx); count 每帧实时查 (任意长度≥65535,
  不常驻 item 对象); bind 仅在行进入视口时被调一次
- 固定 item 池: 视口行数+2 静态槽 (有界 ≤96), 回滚不重绑 (同 index 命中同槽); 整表扫过后
  wrap 回收合法但每次 draw 有界 (≤视口窗口)
- 多行富 item: 主标题/副标题/左图标·缩略图/右尾件; 行高 set_item_h(px) 或 set_item_tier(1→48/2→56);
  默认 renderer 主题语义色绘制; set_item_draw 完全自绘; section 段头占位行(非粘性); 空态占位
- 集成: tap_at→meow_ui_focus_acquire (§6.4); meow_scroll_wrap(lv,1) track+fling+snap(行边界);
  选中/按压态走主题; enabled=0 变淡不响应
- 兼容: src2==NULL 走既有路径; W_LIST/W_LISTVIEW 单行用法零改动

验证(宿主): 新测试 test_meow_ui_listvirt T1-T5 全 44 PASS (10000 项滚动窗口内容正确/hit 映射/
bind 有界=count/回滚不重绑/多行渲染/截断/图标占位/段头/空态/自绘/焦点/fling 吸附);
全量回归 widgets/dispatch/box/anim/scroll/ime/pinyin/overlay/notif/sdk_input_keys/p1p2p3 全 PASS;
交叉 zig-mipsel -Wall -Wextra 全 SDK TU 0 warning; meow_ui.a 新 md5=2a2d8000b95dd211d09dc736d5538ad0

文档: MEOW_APP_SDK.md §5.5 同步虚拟化层(API 一览/池语义/集成/回归).

patch_v2/sdk/include/meow_ui_widgets.h

@@ -293,6 +293,65 @@ void meow_listview_set_on_tap(meow_widget *lv, meow_listview_tap_fn cb, void *ct
 /* 命中行：置选中 + 回调（若设）+ 返回 idx；未命中返回 -1。 */
 int  meow_listview_tap_at(meow_widget *lv, int x, int y);
 
+/* ============================================================ */
+/* §5.5 虚拟化列表（W_LISTVIEW 扩展层，2026-09-02）：固定 item 池 + 多行富 item + 完全自绘
+ * ------------------------------------------------------------
+ * 在既有 W_LISTVIEW（src2 每帧按需取行，行为不变）之上做**虚拟化层**（API 追加式，旧 API 保留）：
+ *   - 数据源：count_fn() 返回总行数（任意长度，≥65535 不常驻 item 对象）；
+ *     bind_fn(index, item, ctx) 仅在行「进入视口」（绑定到固定池槽）时调用一次；
+ *   - 固定 item 池：池容量 = 视口行数 + 2 静态槽（有界，见实现 MEOW_LV_POOL_MAX）；
+ *     行离开视口不销毁，回滚不重绑（同一 index 命中同一槽 → bind 不重调）；
+ *   - 滚动只改 viewport 偏移（复用既有 set_scroll/max_scroll），不重绑未进视口的项；
+ *   - 多行富 item：主标题+副标题（第二行小字）+左图标/缩略图+右尾件（chevron/开关/复选/⋯）；
+ *     行高可配（set_item_h 精确 px / set_item_tier 单/双行档位默认高）；
+ *   - 默认 renderer 用主题语义色绘制富 item；App 也可经 set_item_draw 完全自绘。
+ * 段头：bind 回调把 item->section=1（title=段名）→ 段头占位行（非粘性），默认 renderer 特殊绘制。
+ * 空态：set_empty_text 设置文案，count==0 时视口内居中画出。
+ * 兼容：既有 meow_listview_*（src2 模式）全部保留不动；本层为叠加，src2==NULL 时走既有路径。 */
+
+/* 虚拟化行 item（bind 回调填充；SDK 固定池持有；不常驻 src2 那样的全量行对象）。 */
+typedef struct meow_lv_item {
+    const char     *title;      /* 主标题（必填，NULL 视为空行） */
+    const char     *subtitle;   /* 副标题（第二行小字），可空 */
+    const meow_img *icon;       /* 可选：左图标/缩略图（icon_kind==MEOW_LIST_ICON_IMG 时用） */
+    int             icon_kind;  /* MEOW_LIST_ICON_*（NONE=无图标） */
+    int             right;      /* MEOW_LIST_RIGHT_* 右尾件 */
+    int             on;         /* right==SWITCH 时开关态（0/1） */
+    int             enabled;    /* 1=可交互；0=变淡不响应 */
+    int             section;    /* 1=段头占位行（title=段名；默认 renderer 特殊绘制，非粘性） */
+    void           *user;       /* App 私有（跨 bind 保存业务态/图/index；SDK 不碰） */
+} meow_lv_item;
+
+/* 虚拟化数据源：count 返回当前行数（>=0，任意长）；bind 在行进入视口时被调一次填充 item。
+ * 二者均不常驻 item 对象；count 每帧实时查（支持搜索过滤/懒加载动态长度）。 */
+typedef int  (*meow_listview_count_fn)(void *ctx);
+typedef void (*meow_listview_bind_fn)(int index, meow_lv_item *item, void *ctx);
+
+/* 完全自绘回调（覆盖默认 renderer）：idx=行号；x,y,w,h=行视口矩形（已裁剪到列表视口）；
+ * state=MEOW_LISTVIEW_ST_* 状态位（选中/按压/禁用组合）。App 用 §3 绘制 API 自绘整行。 */
+typedef void (*meow_listview_draw_fn)(int idx, int x, int y, int w, int h,
+                                      int state, void *ctx);
+/* state 位（set_item_draw 的 draw 回调收到；选中/按压/禁用组合，供自绘整行）。 */
+#define MEOW_LISTVIEW_ST_SELECTED (1u<<0)
+#define MEOW_LISTVIEW_ST_PRESSED  (1u<<1)
+#define MEOW_LISTVIEW_ST_DISABLED (1u<<2)
+
+/* 挂虚拟化数据源：切到 pool 模式（count_fn/bind_fn 均非 NULL 才生效；否则回退 src2 模式）。
+ * 返回 0=成功；NULL 回调/无效=负值。挂虚拟源后既有 sel/滚动/命中/焦点照常。 */
+int  meow_listview_set_vsource(meow_widget *lv, meow_listview_count_fn count,
+                               meow_listview_bind_fn bind, void *ctx);
+/* 默认 renderer 配置：lines=1/2（单行/双行档位，影响副标题显示与行高默认）；
+ * show_icon=1 画左图标/缩略图；show_right=1 画右尾件。返回 0=成功。 */
+int  meow_listview_set_item_renderer(meow_widget *lv, int lines, int show_icon,
+                                     int show_right);
+/* 行档位默认行高：lines=1→48（单行）、2→56（双行）；与 set_item_h（精确 px）互补。 */
+int  meow_listview_set_item_tier(meow_widget *lv, int lines);
+/* 完全自绘：设 draw_item 回调（覆盖默认 renderer）；NULL=用默认 renderer。返回 0=成功。 */
+int  meow_listview_set_item_draw(meow_widget *lv, meow_listview_draw_fn draw,
+                                 void *ctx);
+/* 空态占位：count==0 时视口内居中画 empty_text（NULL 不画）。返回 0=成功。 */
+int  meow_listview_set_empty_text(meow_widget *lv, const char *text);
+
 #ifdef __cplusplus
 }
 #endif