docs: 仓库文档同步 M6.4(0.8.4)——README 版本行+新能力(SDK 演进批次/锁屏 PIN/面板批2+overview 自校验)；SPEC_REF 补 SDK §3.5 扩展模块速查+system.pin 锁屏键+面板 batch2/UTF-8 加固

docs/MEOWOS_SPEC_REF.md

@@ -13,7 +13,8 @@
 - **主机名**：设置键 `system.hostname`（SET_STR，默认 `meowos`；RFC1035 首标签），`S89meow_svcd` 开机读 settings `sethostname`；供自研 mDNS 应答器公布 `<host>.local` `[SYSTEM_SETTINGS §1][mips-repo/bins/meow_mdns]`
 - `/etc/meowos_version`：版本唯一来源（launcher 运行时 `load_meowos_version` 读；`MEOWOS_VERSION` 宏仅作 dev 占位兜底）`[DEV_NOTES #4]`
 - **`/data/meow_boot_default`：开机默认权威标记（O_TRUNC 单值：`0`=MeowOS / `1`=HiByOS）**。由 launcher `meow_settings_save()` 在保存 `boot.default` 时同步写；bootmenu `set_boot_default_meow()`（写 0）/ launcher `set_boot_default_hiby()`（写 1）同文件同语义；bootmenu 开机读它定默认；init 读入不触发、不反向覆盖；`meow.conf` 不再承担 boot_default `[M2.61 同步修复][README][meow_settings.c][meow_bootmenu.c]`
-- `/tmp`：tmpfs，开机清空；开机模式标记 `/tmp/meow_boot_mode`、电源菜单 `/tmp/meow_power_menu{,_active}`、app 沉浸 `/tmp/meowapp_state` `[BOOT_SELECTOR §1][KEY_CONTROL §9][APPS §3.5]`
+- `/tmp`：tmpfs，开机清空；开机模式标记 `/tmp/meow_boot_mode`、电源菜单 `/tmp/meow_power_menu{,_active}`、app 沉浸 `/tmp/meowapp_state`、**锁屏** `/tmp/meow_pin_unlock_once`（一次性解锁恢复口，launcher 锁屏页消费放行一次、重启自消）/`/tmp/meow_pin_locked`（电源菜单「主动锁」标志，重启消失）`[BOOT_SELECTOR §1][KEY_CONTROL §9][APPS §3.5][WORK_STATE 2026-09-02]`
+- **锁屏 PIN（M6.2 起，与面板同源 `system.pin`，规范 `SYSTEM_SETTINGS` 锁屏小节）**：设置键 `system.pin`=`<salt_hex>:<sha256_hex(salt||pin)>`（sha256+salt，格式与面板 `panel.pin` 全等，**绝无明文**；空=未设=锁屏关；`panel.pin` 已设时锁屏接受并首次验证成功后并入本键）+`system.pin_lock_on_wake`（息屏唤醒后锁屏，int 0/1，默认 1=开；开机不锁）+`system.pin_lock_until`（错 PIN 锁定的 epoch 截止戳，持久化防 launcher 重启清零）+`system.pin_fails`（连续错 PIN 计数 0-4，达 5 触发锁定并清零，持久化）。清/改：设置「安全→锁屏 PIN」页——设/改需旧 PIN 一次、**清除免旧 PIN**（物理持机即授权，仅二次确认）、`system.pin_lock_on_wake` 开关；**兜底**：SSH root 删 `system.pin` 键即解锁（无其它后门）。`[SYSTEM_SETTINGS §1][WORK_STATE 2026-09-02]`
 - 日志启动缓冲 `/tmp/meow_boot.log`（256KB 滚动，卡出现后自动迁卡）`[APPS §4.5]`
 - IPC socket：`/usr/data/meow_ipc.sock`（AF_UNIX SOCK_STREAM，0666，backlog 4）`[FRAMEWORK_DESIGN §1][WORK_STATE]`
 - 专项服务 IPC socket：`/usr/data/meow_perf.sock`（meow_svc_perf，收 `MSG_PERF_QUERY→RESULT`）与 `/usr/data/meow_power.sock`（meow_svc_power，收 `MSG_POWER_ACTION→STATUS`），均 0666、可 `--sock`/`MEOW_IPC_{PERF,POWER}_SOCK` 覆盖；power 服务端以 `SO_PEERCRED uid==0` 基础鉴权 `[meow_svc_perf.c][meow_svc_power.c][meow_ipc.h]`
@@ -126,6 +127,18 @@
 - **兼容**：既有 `meow_btn/slider/switch/list_create` 签名一字不改（Options/状态机走新增挂载器）；`meow_ui_theme`/`meow_widget` 结构变化 = **`meow_ui.a` ABI 变化** → 需同步重编 hello（§5.8.8）。
 - **主题增强（§8.1）**：主题 = **顶级风格族 `ui.style`（md3/miuix）× 明暗 `display.theme`（dark/light）** 共同决定「整套配色+控件形态+背景底」；`display.background` 为「style×mode」派生的**可选背景底选项集**（非独立维度）；状态栏图标随 `ui.style` 换集。⚠️ **`miui`/`miuix` 命名待定案（保留，勿拍板）**：`MEOW_APP_SDK §8.1` 用 `miuix`；`SYSTEM_SETTINGS §1` 注明 `meow_settings.c g_defs` 现值 `"md3,miui"`（label "Material You,MIUI"），实现时把 `g_defs` 的 `miui` 对齐为 `miuix`（**MIUIx 未实现，当前仅 md3 生效**）。
 
+### 3.5 SDK 扩展模块速查（构造/滚动/动画/i18n/图标库/事件分发/ListView 虚拟化/图片降采样）
+> 权威签名 = `patch_v2/sdk/include/meow_ui_{box,anim,scroll,str,input,widgets,image}.h`；蓝本 `MEOW_APP_SDK.md` §5.5/§6.4/§12/§13。**本批全部追加式 API**——既有 App/签名零改动，`meow_ui.a` 变化需重链四 App（hello/files/ncm/reader）。
+
+- **§12.1 线性布局 `meow_box`（292，纯布局计算器非控件，opt-in `meow_view_set_layout`）**：`meow_box_new(dir)`（`MEOW_BOX_H/V`）/`_free`/`_set_rect`/`_set_padding`/`_set_gap`/`_set_align(main_align,cross_align)`；子项 `meow_box_add(b,w,size,weight)`/`_add_ex`（WRAP 用 min/preferred+measure 回调）/`_add_sub`（嵌套）；`size`=`MEOW_BOX_FIXED/WEIGHT/WRAP`；`align`=`START/CENTER/END/SPACE_BETWEEN/AROUND/EVENLY`、`cross`=`START/CENTER/END/STRETCH`；求解 `meow_box_arrange(b)` 把子控件 x/y/w/h 写进 `meow_widget`（`meow_widget_set_rect`）。定长 items（≤`MEOW_BOX_MAX_CHILD=24`）+嵌套深度 ≤16 静态栈，arrange 零 malloc。
+- **§12.2 动画基座 `meow_anim`（292）**：`meow_anim_start(const meow_anim_desc*)`（desc：`from/to/duration_ms/ease/update/done/ctx`；start 即 value=from+回调一次 update(0)）/`_cancel`（回调 done(canceled=1)）/`_active`/`_value`/`_set_region(x,y,w,h)`（动画每 tick 只 flush 影响区，不整屏）；`meow_ease`=`LINEAR/OUT/IN_OUT/OVERSHOOT`+`meow_ease_apply(e,t)`；节拍 `meow_anim_tick()`（挂 on_tick / `meow_ui_feed_tick`，无动画零开销）+`meow_anim_count()`；静态池 ≤`MEOW_ANIM_MAX=16`。
+- **§12.3 滚动物理 `meow_scroll`（292）**：`meow_scroll_create(set,max,get,redraw,ctx)`/`meow_scroll_wrap(list,is_listview)`（is_listview：1=W_LISTVIEW /0=W_LIST|LazyColumn|LazyRow，redraw 只 flush 控件视口区）/`_free`/`_track(dy,t_ms)`（跟手+速度采样，内部 set_scroll clamp）+`_fling()`（加权初速+ease-out 推进+边界回弹）/`_stop`/`_velocity`/`_active`/`_offset`/`_set_snap(step)`/`_set_friction(tau_ms，默认180)`。拖动态保持现状不变，fling 由 §12.2 驱动。
+- **§13 字符串资源 / i18n `meow_str_*`（299）**：`meow_str(id)` 按当前 locale 取串（返回静态、**永不 NULL**、未知 id 原样返回 id）/`meow_strf(out,outsz,id,...)`（snprintf 语义）/`meow_str_set_locale(locale)`（切 `"zh_cn"|"en_us"`，即时生效+重载 TF 覆盖表+best-effort 持久化 `ui.locale`）/`meow_str_locale()`。四层取值：TF 覆盖表（`<pkg>/strings/<locale>.txt`）> 内嵌当前语言 > 内嵌内置默认(zh_cn) > 原样 id。热路径零 malloc；id 形如 `域.名`（common.ok / player.pause）。不做复数/BiDi/RTL/动态字回退（当前为「按 locale 取整串」雏形）。
+- **§6.4 事件分发形式化（293，单一仲裁者）**：模态作用域 `meow_ui_modal_begin/end/active/depth`（作用域存在时下层收不到触摸，未命中面板的事件由背板消费恒返回哨兵）；自上而下命中 `meow_ui_hit_topdown(x,y)`/`meow_ui_widget_hit`；手势捕获 `meow_ui_gesture_begin/owner/end`（down 命中即捕获到 up，move/up 只发捕获目标）；唯一焦点 `meow_ui_focus_acquire/release/owner/tap/set_lost_cb`（点外释放+回调+滚动容器转移）。传播矩阵：模态>z 序自顶向下；命中即消费；向下穿透仅当未命中。
+- **§5.5 ListView 虚拟化（295，W_LISTVIEW 扩展层，API 追加式）**：`meow_listview_set_vsource(lv,count_fn,bind_fn,ctx)`（count 每帧实时查、bind 仅在行进视口时调一次；count_fn/bind_fn 均非 NULL 才切 pool 模式，否则回退 src2）；`meow_lv_item{title,subtitle,icon,icon_kind,right,on,enabled,section,user}`；`meow_listview_set_item_renderer(lv,lines,show_icon,show_right)`/`_set_item_tier`（单行 48/双行 56）/`_set_item_draw`（完全自绘覆盖默认 renderer，state=`MEOW_LISTVIEW_ST_{SELECTED,PRESSED,DISABLED}`）；固定池=视口+2 槽，行离开视口不销毁、同 index 命中同槽不重绑；段头 `item->section=1`。
+- **图标库 `sb_icons`（307，Material Symbols Rounded / MD3，单通道 alpha 32×32，生成 `tools/gen_action_icons.py`）**：索引只追加——状态栏 `MEOW_SB_ICON_WIFI=0..BATT_CHG=14` 原样保留；**动作** `MEOW_ICON_SETTINGS=15..MEOW_ICON_HEART=29`（设置/刷新/搜索/播放/暂停/上下曲/返回/关闭/添加/勾选/歌词/列表/下载/收藏），经 `meow_topappbar_set_item_icon(w,idx,MEOW_ICON_*)` 使 W_TOPAPPBAR 动作项画位图（`layout 见 meow_ui_widgets.h`）。
+- **图片降采样 `meow_img_downscale(img,maxdim)`（308）**：把解码图降到 ≤maxdim 边长以省内存（ncm 封面 1448² RGBA 8.28MB→cap≤480px→0.78MB，-7.65MB），返回新 `meow_img*`。
+
 ---
 
 ## 4. SDK 之外系统组件
@@ -150,6 +163,7 @@
   - **M2.73 悬垂指针修复（md5 `da6ebc66`）**：`scan_and_reconcile` 用 `*s=tmp` 整体拷贝后，`s->argv[]` 仍指向已销毁的 `tmp` 栈帧 → `execv`/`/proc/pid/cmdline` 错乱。修法：新增 `svc_rebuild_argv(s)`，赋值/`memmove` 左移后把 `s->argv[]` 重定位到 `s->exec`/`s->argbuf` 自身成员（删除一个服务后同 tick 内被拉起不再用错位 argv）。`[meow_svcd.c]`
 - **卡上外部工具 = `MeowOS/opt/`**（`{bin,nyai,sources.list}, lib/, tools/`）：MeowOS 启动时从卡加载，拔卡降级不崩。**`MeowOpt` 已废弃并入此处**；mDNS 已改为自研 `meow_mdns`（固件 `/usr/bin`），不再放卡。`[DEV_NOTES][meow_svcd.md]`。**MeowPanel 本体 = `MeowOS/opt/MeowPanel/`**（后端+前端，svcd 托管 `MeowOS/services.d/meowpanel.conf`，无卡跳过、系统核心不依赖，不进固件；md5 `8108852f`（nyai 路径修复）→ 阶段C 后 新 md5（见 `patch_v2/meowpanel/README.md`），详见 `patch_v2/meowpanel/README.md`）。
 - **MeowPanel（外置 TF 卡 Web 面板，M2.73 已落地，阶段 C 实时画面+遥控已落地）**：单进程 HTTP/JSON 后端（8080）+ 静态托管（`/`→index.html、`/assets/*`）+ `meow_svc_perf`/`meow_svc_power` IPC 客户端（读侧透传 perf 聚合、动作侧经 power）+ `settings.conf` 设置镜像（`key = value` 带空格 + 精确匹配）+ 文件白名单（`MeowOS/Music/MeowData/MeowAPPs/book`，`..` 逃逸→403）+ 应用（`nyai install/export/remove`，包名=`app.json.package`，`nyai` 固件内置 `/usr/bin/nyai` 优先+卡上回退）+ 按键注入（evdev，只音量/电源/播放/上下曲，**禁返回158/主页172/确认28/退出96**）+ 日志（`MeowOS/logs`）。M2.73：系统页「以太网」→「**蓝牙**」栏（无网口有蓝牙）；**OTA 检查升级 bug 已修**（改读 `GET /api/system` 的 `ota`，不再误触 `POST /api/system/ota` 升级）。**M2.78+ 新增**：可选密码鉴权（agent-196，默认关）、通知中心后端 `/api/notifications`（TF 归档环形 200 条）、文件域 4 bug 修复 + 上传 8MB 上限 + 双重白名单（agent-182）**。**M2.84-88 阶段 C**（agent-224）：`/api/screen.jpeg`（fb0 活动帧→自研 JPEG 编码器）+ `/api/input/tap`（坐标注入，本机触摸优先 5s 仲裁）+ 屏幕增量帧 `?delta=1`（8x8 块比对，近静态 27KB→804B，agent-234）+ `/api/notifications` 实时化（优先 IPC 读 launcher 活跃集 source:ipc，agent-234）。**252 新增（2026-09-01）**：`/api/audio`（audiod MSG_AUDIO_QUERY→STATE 只读透传，不在时 available:false）+ 前端「音频」页（5s 轮询只读）与「字体」页（列表/上传进度/导出/409 冲突确认 force 重试）。**⚠️ 鉴权默认关**（内网信任模型；`reboot/shutdown/ota/apps/删除/上传` 危险端点勿暴露公网，power 侧有 `SO_PEERCRED uid==0` 基础校验）。`[patch_v2/meowpanel/][devdocs/plan/MEOWPANEL_PROTOCOL.md]`
+- **面板批2 + 加固（2026-09-02）**：崩溃/日志中心 + 音频路由页 + 音量写经 clamp `vol_max` + 后端补 `reboot_reason`；**JSON 输出 UTF-8 加固**（`sA_str_n` 单遍校验、非法序列换 `?`、IPC 原始 JSON 门禁降级，防任一上游坏字节拖垮整页，d7bf62f）。**overview 自校验纪律**：`/api/overview` 服务端发出前先自查（jv_parse）+ 与浏览器口径对齐的**严格平衡检查**，坏则 dump `/tmp/overview_bad.json` + 500（908fc53/67aa5fc/54e737a）；前端非 JSON 自动回传原始字节到 `/api/debug/report_bad_json`（落 `/tmp/overview_client_bad.txt`，7a40586/524e5d6）；**教训**：后端 `jv_parse` **容忍尾随垃圾**，浏览器 `JSON.parse` **不容忍**——net 块多写一个 `}` 即「Extra data」破页（批2 DNS 并入事故），故自校验必须严格括号/闭合平衡。`[patch_v2/meowpanel/][devdocs/plan/MEOWPANEL_PROTOCOL.md][WORK_STATE 2026-09-02]`
 - **mDNS 应答器 = `meow_mdns`（自研，已拍板替代完整 mdnsd）**：`mips-repo/bins/meow_mdns/`，**IPv4-only**（内核无 IPv6，完整 mDNSResponder/SAResponder 均 `socket(AF_INET6)` 失败），mipsel 静态 ~79KB（md5 b23de7ce）。**进固件 `/usr/bin/meow_mdns`**（不入卡），由 meow_svcd 托管（板载 `/usr/data/meow/services.d/meow_mdns.conf`，`trigger=boot`、root 即可绑 5353/组播，`cap=` 空）。功能：join `224.0.0.251:5353`，应答 `<host>.local` A（wlan0 IPv4）/`_ssh._tcp` PTR/SRV/TXT/`_services._dns-sd` PTR；支持 `MEOW_MDNS_HOST`/`_ADDR`/`_PORT`/`_TTL`/`_CF`/`_QD`/`_MCAST`/`_MIF`/`_DBG`。⚠️ **手机热点隔离**：设备→主机组播被热点丢弃，avahi 只收组播应答 → 该热点下 `avahi-resolve <host>.local` 超时（网络层限制，非应答器缺陷），主机需 DNS 兜底 `[mips-repo/bins/meow_mdns/manifest.md][meow_svcd.md]`。
 - `meow_settings_*`（设置后端，已定）/`meowcli`/`meow_sys_devattr`/`meow_devattr_set` `[MEOWOS_API]`
 - **独占音频守护 `meow_audiod`（M2.90 已落地，规范 `devdocs/plan/AUDIOD_DESIGN.md`）**：板载 `/usr/bin/meow_audiod`，svcd 托管（板载 `services.d/meow_audiod.conf`，trigger=manual；launcher 确认 MeowOS 模式后拉起；**启动门控：mode≠meow → exit(0)，HibyOS 下不存在**）。IPC `/usr/data/meow_audio.sock`（帧层复用 meow_ipc.h，号段 0x00C0-0x00CA：OPEN/OPEN_ACK/WRITE/PAUSE/RESUME/STOP/PREEMPTED/QUERY/STATE/ROUTE/VOLUME）。**独占+抢占**（后开赢，旧流收 PREEMPTED；socket EOF=回收；软混音已否决，留接口位）。**DAC 原生率跟随不做 SRC**；格式归一 S16 直通/S32 升位/mono 复制；切率 mute-重配-恢复。**meow_route 已并入为路由线程并退役独立服务**（⚠️ 退役服务要清板载+TF 双源 conf，否则旧 conf 会双写路由）。**CLI `meow_audio`**（root 免鉴权）：`status`/`tone [freq] [ms] [rate]`（正弦测试音，排查无声不开 App）/`route <0|2|3>`/`vol [0-100]`。SDK 客户端 `meow_audio_open/write/pause/close/query/on_preempt`（`meow_ui_audio.c`，懒连接+EPIPE 标死；无 audiod → -ENOENT 不隐式直开，`MEOW_AUDIO_DIRECT=1` 仅调试）。**M2.91-97 加固批**：①**开机武装 hbc3000 FPGA**（M2.91：路由线程启动无条件写 Output Port Switch 4.4→3/3.5→2/无→4，同值先写 5 强制重烧——根治「未烧 FPGA 时 PCM 第二次 `hbc3000_start` 内核硬挂死」，调查底稿 `devdocs/plan/AUDIO_HANG_INVESTIGATION.md`）②**长流护栏**（M2.93：ring 有界等待/cond timedwait/popen 有界收割/O_NONBLOCK+poll 写/wedge 自救/心跳 watchdog）+**几何收窄 period=1024×4**（M2.94：驱动默认巨 buffer 致桥周期中断稀缺 wedge、播 ~12s 停摆；tonepcm2 矩阵 60s 零 stall 实证）③**音量反转**（M2.95：CS43198 音量寄存器=衰减量，四路统一 `dac=255-pct*255/100`）④**炸耳安全**（M2.96：`dac_vol_mute` 写 255 真静音，旧写 0=最大响度）⑤**电平监控**（261，待 M2.97 固件化：播放线程 ~100ms 窗口整数 RMS/peak dBFS（deci-dB，逐帧判边界，-990=-inf）、`MSG_AUDIO_STATE` 追加 `rms=/peak=/lvlseq=`（ABI 兼容）、流活跃时 1s 节拍写 TF `MeowOS/logs/audio_monitor_<bootts>.log`、CLI `meow_audio monitor [秒]` 文本电平条）。`[patch_v2/meow_audiod/]`