Merge branch 'feat/files-hello-row-height-followup'

patch_v2/files_app/README.md

@@ -22,7 +22,8 @@ patch_v2/files_app/
 │   ├── fsx.h              # 纯业务接口（不依赖 meow_ui）
 │   └── fsx.c              # 路径安全/格式化/枚举排序/虚拟化区间/写操作（可宿主测）
 └── test/
-    └── test_fsx.c         # 宿主单元自测（gcc 直接编，指向临时卡根）
+    ├── test_fsx.c         # 宿主单元自测（gcc 直接编，指向临时卡根）
+    └── test_row_text_fit.c # 宿主几何断言：列表行高 ≥ 双行文本块（M17）
 ```
 
 ## 构建
@@ -55,12 +56,20 @@ v1 无需持久化，暂未使用（启动恒进卡根 `/usr/data/mnt/sd_0/`）
 cd patch_v2/files_app
 gcc -O2 -Wall -Wextra -DFSX_SD_ROOT='"/tmp/meowfsx_fsx_test"' -Ilogic \
     test/test_fsx.c logic/fsx.c -o /tmp/test_fsx && /tmp/test_fsx
+
+# 列表行高几何（无需 meow_ui.a；Termux 下产物落 $TMPDIR）
+gcc -O2 -Wall -Wextra -I. -I../sdk test/test_row_text_fit.c \
+    -o "$TMPDIR/test_row_text_fit" && "$TMPDIR/test_row_text_fit"
 ```
 
 覆盖：路径安全（`within_sd`/`join`/`sanitize`/`dirname`/`basename`）、展示格式化（`fmt_size`/`fmt_time`）、
 目录枚举排序（`scan_dir`/`sort`）、虚拟化区间（`visible_range`/`max_scroll`）、写操作（`mkdir`/`rename`/
 `delete`，含卡外/越界拒绝）、非文本写拒绝。宿主全 PASS。
 
+`test_row_text_fit` 是 M17 行高回归：目录列表行恒为双行档位，行高必须 ≥ 文本块
+`2*meow_ui_text_height(font_body) + 2`（真机 20px 字库行高 30 → 62），否则 SDK 居中后首行标题
+`ty < 视口顶` 被裁剪守卫整条跳过。断言矩阵覆盖真机五种字库行高 + 旧固定 56 的 bug 形态。
+
 ## 交互
 
 - 触摸：行 body=进目录/开文本预览；右侧 `⋯` 或长按→BottomSheet（删除[确认弹窗]/重命名[IME]/新建目录[IME]/属性[大小·mtime]）；
@@ -78,6 +87,10 @@ gcc -O2 -Wall -Wextra -DFSX_SD_ROOT='"/tmp/meowfsx_fsx_test"' -Ilogic \
      位移 ≤ 容忍」→ 经 `meow_ui_set_long_press_cb` 注册的回调带坐标交给本页；`browser_on_long_press`
      用 `meow_listview_hit` 行命中打开 BottomSheet。App 层长按计时（`browser_tick`/`g_press_ms`）已删除，
      其抬手 TAP 由 SDK 抑制（长按不再触发点击）。
+   - **行高按字体行高派生（M17）**：`files_row_h()` = `max(APP_ROW_H, 2*行高 + 2)`（当前主题正文
+     `font_body` 的 `meow_ui_text_height`）。目录行是双行档位，行高小于双行文本块时 SDK 居中后首行
+     标题落在视口顶之上被裁剪（20px 字库行高 30 → 块 62，旧的显式 56 首行名称空白）。滚动/命中/
+     最大滚动量由 SDK 按同一行高换算，页脚几何独立（`r_list` 单独扣 `APP_FOOTER_H`）。
 2. **中文字形**：SDK 默认 `common` 字库（≈4k）不含 CJK 全量；exFAT 中文文件名/中文文本预览在 common 档会显示缺字豆腐。
    预览页不声明 `fonts`（app.json 未加 `"fonts":"full"`/`"gbk"`），如需中文预览可在 app.json 声明大字号档。
 3. **预览仅文本**：按扩展名白名单 + 首 512 字节 NUL 嗅探判文本；二进制/图片无预览（提示「not a text file」）。
@@ -88,7 +101,7 @@ gcc -O2 -Wall -Wextra -DFSX_SD_ROOT='"/tmp/meowfsx_fsx_test"' -Ilogic \
 ## 验证状态
 
 - 编译：`-Wall -Wextra` 0 warning/0 error，产物 `files`（MIPS32r2 静态 ELF）。
-- 宿主：`test/test_fsx.c` 全 PASS。
+- 宿主：`test/test_fsx.c` 全 PASS；`test/test_row_text_fit.c` 32 断言全 PASS（M17 行高几何）。
 - qemu-mipsel（无 /dev/fb0 → SDK 离屏 480×720）：正常运行到事件循环，导出离屏帧，
   确认 init/建页/topbar（返回+NEW）/空态（NO STORAGE CARD）渲染正确、SIGTERM 干净退出。
 - 实机目录列表渲染（有真实 TF 卡目录）需刷机/设备挂载验证——宿主模拟无法造出 `/usr/data/mnt/sd_0`。

patch_v2/files_app/files_internal.h

@@ -37,13 +37,38 @@ void       picker_cancel(void);                    /* 取消：发 code=MEOW_ERR
 #define APP_W       480
 #define APP_H       720
 #define APP_TOPBAR_H 56
-#define APP_ROW_H   56      /* 列表行高 */
+#define APP_ROW_H   56      /* 列表行高下限（旧固定值；实际按字体行高派生，见 files_row_h） */
 #define APP_PAD     16
 #define APP_ICON_W  26      /* 图标占宽 */
 #define APP_OP_W    52      /* 右侧操作钮占宽（触达区） */
 #define APP_FOOTER_H 26     /* 底部信息行高（列表/文本内容在其之上滚动） */
 #define APP_READ_MAX (256 * 1024)   /* 文本预览读取上限 */
 
+/* ---- 列表行高：按字体行高派生（M17，首行标题不显示根因修复）----
+ * SDK meow_listview 的双行渲染把「标题+副标题」文本块
+ *      block = 2 * meow_ui_text_height(font_body) + MEOW_LISTV_SUB_GAP(2)
+ * 在行内垂直居中（ty = 行顶 + (item - block) / 2），标题只在 ty >= 视口顶时才画。
+ * item < block 时 ty = 行顶 - Δ：第一行（行顶 == 视口顶）标题被整条跳过、只剩副标题。
+ * 真机 source_han_serif 20px（ascent 24 + descent 6）行高 30 → block 62，旧的显式 56 → Δ=3。
+ * 故行高按当前主题正文行高派生：max(APP_ROW_H, 2*line_h + 2)（行高 30 → 62）。
+ * 本页行恒为双行档位（browser_src2 填 title + subtitle）→ 用 lines=2 公式。
+ * 行几何（draw / hit / max_scroll）全由 SDK 按传入的这一个值换算，故滚动与命中天然同步；
+ * 页脚几何与行高无关（r_list 单独扣 APP_FOOTER_H）。 */
+#define FILES_ROW_SUB_GAP 2   /* 与 SDK MEOW_LISTV_SUB_GAP 同口径（标题/副标题行距） */
+
+static inline int files_row_h_for_line_h(int line_h)
+{
+    if (line_h < 1) line_h = 1;                        /* 字体未就绪 → 退回下限 */
+    int h = 2 * line_h + FILES_ROW_SUB_GAP;
+    return (h > APP_ROW_H) ? h : APP_ROW_H;
+}
+/* 当前主题正文行高下的两行列表行高（页面 create 时取一次；字体档位切换走页面重建）。 */
+static inline int files_row_h(void)
+{
+    const meow_theme *th = meow_theme_get();
+    return files_row_h_for_line_h(th ? meow_ui_text_height(th->font_body) : 0);
+}
+
 /* ---- App 级复用矩形/几何 ---- */
 typedef struct { int x, y, w, h; } app_rect_t;
 #define AR(x,y,w,h) ((app_rect_t){ (x),(y),(w),(h) })

patch_v2/files_app/test/test_row_text_fit.c

@@ -0,0 +1,86 @@
+/* test/test_row_text_fit.c — 宿主回归（M17）：目录列表行高必须容纳双行文本块。
+ *
+ * 背景（真机根因，承接 M12/M15）：SDK meow_listview 的双行渲染把
+ *      block = 2 * meow_ui_text_height(font_body) + 2      （标题行 + 2px 行距 + 副标题行）
+ * 在行内垂直居中：ty = 行顶 + (item - block) / 2；且标题只在 `ty >= 视口顶` 时才画（越界钳制）。
+ * 行高 item < block 时 ty < 行顶 → **第一行（行顶 == 视口顶）标题被整条跳过**、副标题仍在。
+ * 真机字库实测（source_han_serif 20px：ascent 24 + descent 6 → 行高 30）block = 62，旧的
+ * 显式 set_item_h(56) → ty = 行顶 - 3（本 App 目录列表首行名称空白）。
+ *
+ * 本测试只验 app 侧行高派生（files_row_h_for_line_h，纯整数、不链 SDK）：
+ *   行高 = max(APP_ROW_H, 2*行高 + FILES_ROW_SUB_GAP) → block ≤ item，首行标题不被钳掉。
+ *
+ * 编译/运行（宿主 gcc，只需 SDK 头，不需要 meow_ui.a）：
+ *   cd patch_v2/files_app
+ *   gcc -O2 -Wall -Wextra -I. -I../sdk test/test_row_text_fit.c -o "$TMPDIR/test_row_text_fit" \
+ *       && "$TMPDIR/test_row_text_fit"
+ *
+ * 断言矩阵 = 真机已装字库 20px 面实测行高：source_han_serif 30（当前生效）、
+ *   misans/default 27、google_sans/meslo 26、source_han_sans 21；14 = 宿主 5x7 回退。
+ *   ① block ≤ item（否则居中偏移为负）
+ *   ② 首行 ty ≥ 0 → 绝对 ty_abs ≥ 视口顶（标题不被裁剪守卫跳过）
+ *   ③ 副标题底边 ty + block ≤ item（两行都不越行）
+ *   ④ item ≥ APP_ROW_H 下限（小字库/字体未就绪不缩回固定小值）
+ *   ⑤ 旧固定 56 在行高 30 下 ty < 0（bug 形态复现，防止再写死 56）
+ */
+#include "../files_internal.h"
+#include <stdio.h>
+
+static int g_checks, g_fail;
+
+static void chk(int cond, int line_h, const char *what)
+{
+    g_checks++;
+    if (!cond) {
+        g_fail++;
+        printf("  FAIL  lh=%d: %s\n", line_h, what);
+    }
+}
+
+int main(void)
+{
+    static const int lh_all[] = { 14, 21, 26, 27, 30 };
+    const int n = (int)(sizeof lh_all / sizeof lh_all[0]);
+    const int list_y = 120;   /* 任意列表顶（只验相对几何） */
+
+    for (int k = 0; k < n; k++) {
+        int lh    = lh_all[k];
+        int item  = files_row_h_for_line_h(lh);
+        int block = 2 * lh + FILES_ROW_SUB_GAP;
+        int ty    = (item - block) / 2;              /* SDK 双行文本块居中偏移 */
+
+        printf("lh=%2d item=%3d block=%3d ty=%d\n", lh, item, block, ty);
+
+        chk(block <= item, lh, "文本块必须 <= 行高（否则首行标题被视口顶裁剪）");
+        chk(ty >= 0, lh, "首行标题 y 不得高于行顶/视口顶");
+        chk(ty + block <= item, lh, "副标题底边仍在行内");
+        chk(item >= APP_ROW_H, lh, "行高不得小于 APP_ROW_H 下限");
+
+        /* 首行（scroll=0 → 行顶 == 视口顶）的绝对坐标 */
+        chk(list_y + ty >= list_y, lh, "首行标题绝对 y 不得被视口顶裁掉");
+    }
+
+    /* 行高随字体行高单调不减 */
+    chk(files_row_h_for_line_h(30) >= files_row_h_for_line_h(26), 30, "行高随字体行高单调不减");
+
+    /* 真机当前生效字库（source_han_serif 20px，行高 30）：block 62 → item 62 */
+    chk(files_row_h_for_line_h(30) == 62, 30, "行高 30 → 派生行高 62");
+    chk(2 * 30 + FILES_ROW_SUB_GAP <= files_row_h_for_line_h(30), 30, "派生行高容纳 62px 文本块");
+
+    /* 下限：小字库 / 字体未就绪（line_h=0）仍不缩回固定小值 */
+    chk(files_row_h_for_line_h(14) == APP_ROW_H, 14, "小字库退回 APP_ROW_H 下限");
+    chk(files_row_h_for_line_h(0) == APP_ROW_H, 0, "字体未就绪（行高 0）退回下限");
+
+    /* 回归哨兵：旧固定行高 56 + 当前默认字体（行高 30）就是 bug 形态 */
+    {
+        const int lh = 30;
+        int block = 2 * lh + FILES_ROW_SUB_GAP;          /* 62 */
+        int ty_legacy = (APP_ROW_H - block) / 2;         /* -3 */
+        chk(ty_legacy < 0, lh, "旧行高 56 + 行高 30 → ty<0（首行标题被跳过，bug 复现）");
+        chk(files_row_h_for_line_h(lh) > APP_ROW_H, lh, "默认字体下行高必须大于旧值 56");
+    }
+
+    printf("%s: %d checks, %d fail (font line-height matrix: %d)\n",
+           g_fail ? "FAIL" : "PASS", g_checks, g_fail, n);
+    return g_fail ? 1 : 0;
+}

patch_v2/files_app/ui/browser.c

@@ -421,7 +421,7 @@ static void browser_page_create(meow_view *v, void *ctx)
     /* 结构化列表：行数据源 browser_src2；单选模式（行高亮用 selected，§5.8.3） */
     g_list = meow_listview_create(r_list.x, r_list.y, r_list.w, r_list.h, 0,
                                   browser_src2, NULL, MEOW_LIST_SEL_SINGLE);
-    meow_listview_set_item_h(g_list, APP_ROW_H);
+    meow_listview_set_item_h(g_list, files_row_h());   /* M17：按字体行高派生，容纳双行文本块 */
     /* 空态/页脚注册为非控件绘制物（列表视口不含页脚；invalidate/paint_full 自动重画） */
     g_empty_id  = meow_draw_custom_register(1, r_list.x, r_list.y, r_list.w, r_list.h,
                                             browser_draw_empty, NULL);

patch_v2/hello_app/hello_internal.h

@@ -33,6 +33,31 @@ extern meow_sheet  *g_sheet;         /* BottomSheet（阻塞模态；main 创建
 typedef struct { int x, y, w, h; } rect_t;
 #define RX(x,y,w,h) ((rect_t){ (x), (y), (w), (h) })
 
+/* ---- 两行列表行高：按字体行高派生（M17，首行标题不显示根因修复）----
+ * SDK meow_listview 的双行渲染把「标题+副标题」文本块
+ *      block = 2 * meow_ui_text_height(font_body) + MEOW_LISTV_SUB_GAP(2)
+ * 在行内垂直居中（ty = 行顶 + (item - block) / 2），标题只在 ty >= 视口顶时才画。
+ * item < block 时 ty = 行顶 - Δ：第一行（行顶 == 视口顶）标题被整条跳过、只剩副标题。
+ * 真机 source_han_serif 20px（ascent 24 + descent 6）行高 30 → block 62；demo 的 swipe 列表
+ * 是双行档位（set_item_renderer(2,...)），旧的显式 48 比 block 小 14 → 首行标题必丢。
+ * 故行高按当前主题正文行高派生：max(HELLO_ROW_H_MIN, 2*line_h + 2)（行高 30 → 62）。
+ * 行几何（draw / hit / max_scroll）全由 SDK 按传入的这一个值换算，滚动与命中天然同步。 */
+#define HELLO_ROW_H_MIN   56
+#define HELLO_ROW_SUB_GAP 2   /* 与 SDK MEOW_LISTV_SUB_GAP 同口径（标题/副标题行距） */
+
+static inline int hello_row_h_for_line_h(int line_h)
+{
+    if (line_h < 1) line_h = 1;                        /* 字体未就绪 → 退回下限 */
+    int h = 2 * line_h + HELLO_ROW_SUB_GAP;
+    return (h > HELLO_ROW_H_MIN) ? h : HELLO_ROW_H_MIN;
+}
+/* 当前主题正文行高下的两行列表行高（建列表时取一次；字体档位切换走内容重建）。 */
+static inline int hello_row_h(void)
+{
+    const meow_theme *th = meow_theme_get();
+    return hello_row_h_for_line_h(th ? meow_ui_text_height(th->font_body) : 0);
+}
+
 /* ---- 视图控制器（ctx = biz-UI 绑定点）----
  * 本批控制器为薄壳：持 meow_view 回指针；页面细粒度视图态（g_ds/g_drag_* /scroll 等）留在各页
  * 模块作用域全局（设计定案 B：demo 视图态不迁 logic）。控制器未来可吸收这些状态。 */

patch_v2/hello_app/test/test_row_text_fit.c

@@ -0,0 +1,87 @@
+/* test/test_row_text_fit.c — 宿主回归（M17）：demo 的 swipe 列表行高必须容纳双行文本块。
+ *
+ * 背景（真机根因，承接 M12/M15）：SDK meow_listview 的双行渲染把
+ *      block = 2 * meow_ui_text_height(font_body) + 2      （标题行 + 2px 行距 + 副标题行）
+ * 在行内垂直居中：ty = 行顶 + (item - block) / 2；且标题只在 `ty >= 视口顶` 时才画（越界钳制）。
+ * 行高 item < block 时 ty < 行顶 → **第一行（行顶 == 视口顶）标题被整条跳过**、副标题仍在。
+ * 真机字库实测（source_han_serif 20px：ascent 24 + descent 6 → 行高 30）block = 62；
+ * demo 的 swipe 列表是双行档位（set_item_renderer(2,...)）却显式 set_item_h(48) → ty = 行顶 - 7，
+ * 「notif 0」首行标题在真机上必然空白。
+ *
+ * 本测试只验 app 侧行高派生（hello_row_h_for_line_h，纯整数、不链 SDK）：
+ *   行高 = max(HELLO_ROW_H_MIN, 2*行高 + HELLO_ROW_SUB_GAP) → block ≤ item，首行标题不被钳掉。
+ *
+ * 编译/运行（宿主 gcc，只需 SDK 头，不需要 meow_ui.a）：
+ *   cd patch_v2/hello_app
+ *   gcc -O2 -Wall -Wextra -I. -I../sdk test/test_row_text_fit.c -o "$TMPDIR/test_row_text_fit" \
+ *       && "$TMPDIR/test_row_text_fit"
+ *
+ * 断言矩阵 = 真机已装字库 20px 面实测行高：source_han_serif 30（当前生效）、
+ *   misans/default 27、google_sans/meslo 26、source_han_sans 21；14 = 宿主 5x7 回退。
+ *   ① block ≤ item（否则居中偏移为负）
+ *   ② 首行 ty ≥ 0 → 绝对 ty_abs ≥ 视口顶（标题不被裁剪守卫跳过）
+ *   ③ 副标题底边 ty + block ≤ item（两行都不越行）
+ *   ④ item ≥ HELLO_ROW_H_MIN 下限（小字库/字体未就绪不缩回固定小值）
+ *   ⑤ 旧固定 48 在行高 30 下 ty < 0（bug 形态复现，防止再写死 48）
+ */
+#include "../hello_internal.h"
+#include <stdio.h>
+
+static int g_checks, g_fail;
+
+static void chk(int cond, int line_h, const char *what)
+{
+    g_checks++;
+    if (!cond) {
+        g_fail++;
+        printf("  FAIL  lh=%d: %s\n", line_h, what);
+    }
+}
+
+int main(void)
+{
+    static const int lh_all[] = { 14, 21, 26, 27, 30 };
+    const int n = (int)(sizeof lh_all / sizeof lh_all[0]);
+    const int list_y = 400;   /* 任意列表顶（只验相对几何） */
+
+    for (int k = 0; k < n; k++) {
+        int lh    = lh_all[k];
+        int item  = hello_row_h_for_line_h(lh);
+        int block = 2 * lh + HELLO_ROW_SUB_GAP;
+        int ty    = (item - block) / 2;              /* SDK 双行文本块居中偏移 */
+
+        printf("lh=%2d item=%3d block=%3d ty=%d\n", lh, item, block, ty);
+
+        chk(block <= item, lh, "文本块必须 <= 行高（否则首行标题被视口顶裁剪）");
+        chk(ty >= 0, lh, "首行标题 y 不得高于行顶/视口顶");
+        chk(ty + block <= item, lh, "副标题底边仍在行内");
+        chk(item >= HELLO_ROW_H_MIN, lh, "行高不得小于 HELLO_ROW_H_MIN 下限");
+
+        /* 首行（scroll=0 → 行顶 == 视口顶）的绝对坐标 */
+        chk(list_y + ty >= list_y, lh, "首行标题绝对 y 不得被视口顶裁掉");
+    }
+
+    /* 行高随字体行高单调不减 */
+    chk(hello_row_h_for_line_h(30) >= hello_row_h_for_line_h(26), 30, "行高随字体行高单调不减");
+
+    /* 真机当前生效字库（source_han_serif 20px，行高 30）：block 62 → item 62 */
+    chk(hello_row_h_for_line_h(30) == 62, 30, "行高 30 → 派生行高 62");
+    chk(2 * 30 + HELLO_ROW_SUB_GAP <= hello_row_h_for_line_h(30), 30, "派生行高容纳 62px 文本块");
+
+    /* 下限：小字库 / 字体未就绪（line_h=0）仍不缩回固定小值 */
+    chk(hello_row_h_for_line_h(14) == HELLO_ROW_H_MIN, 14, "小字库退回 HELLO_ROW_H_MIN 下限");
+    chk(hello_row_h_for_line_h(0) == HELLO_ROW_H_MIN, 0, "字体未就绪（行高 0）退回下限");
+
+    /* 回归哨兵：旧固定行高 48 + 当前默认字体（行高 30）就是 bug 形态 */
+    {
+        const int lh = 30;
+        int block = 2 * lh + HELLO_ROW_SUB_GAP;          /* 62 */
+        int ty_legacy = (48 - block) / 2;                /* -7 */
+        chk(ty_legacy < 0, lh, "旧行高 48 + 行高 30 → ty<0（首行标题被跳过，bug 复现）");
+        chk(hello_row_h_for_line_h(lh) > 48, lh, "默认字体下行高必须大于旧值 48");
+    }
+
+    printf("%s: %d checks, %d fail (font line-height matrix: %d)\n",
+           g_fail ? "FAIL" : "PASS", g_checks, g_fail, n);
+    return g_fail ? 1 : 0;
+}

patch_v2/hello_app/ui/demo/sdk2/sdk2.c

@@ -266,7 +266,7 @@ int sdk2_build_at(int yb_base, int ct, int scroll)
     g_lv = meow_listview_create(r_lv.x, r_lv.y, r_lv.w, r_lv.h, 0,
                                 NULL, NULL, MEOW_LIST_SEL_NONE);
     if (g_lv) {
-        meow_listview_set_item_h(g_lv, 48);
+        meow_listview_set_item_h(g_lv, hello_row_h());   /* M17：双行文本块按字体行高派生 */
         meow_listview_set_vsource(g_lv, lv_count, lv_bind, NULL);
         meow_listview_set_item_renderer(g_lv, 2, 1, 0);   /* 双行、左图标、无右尾件 */
         meow_listview_set_empty_text(g_lv, "All rows deleted");