Overlay apps: the region, the format, and a tool that writes them

The Labs edition runs overlay apps (Tetris, Breakout, Plasma, Cube3D, Beam, Beacon, FoxHunt, BroadcastFM) that upstream UVStudio installs over WebSerial. This page owns the flash image, so the same bytes go to the same offsets with no serial protocol and no browser permission: APP_REGION_BASE 0x102000, APP_SLOT_STRIDE 0x2000, APP_CODE_OFFSET 0x1000, 16 slots, taken from the firmware's own App/apps/app_overlay.h rather than inferred.

tools/uvk5_apps.py parses and validates the 64-byte FAP1 header (zlib CRC-32 over the code, vma 0x20000280, name, version, capabilities), lists, installs and erases slots, and refuses what the firmware would show as APP ERROR. test_uvk5_apps covers those refusals plus install/erase/list round trips, and parses a real upstream Beam.app when one has been downloaded. The header struct was 60 bytes at first -- a missing vma field -- which the real file's bytes showed at once.

AGENTS.zh-CN.md

@@ -444,6 +444,24 @@ matches_uploaded, note}`，页面显示 `device reports: ...`，**只在"设备
 QEMU 之前就开始排空**。**一次既保住你要修的性质、又悄悄丢掉另一种性质的改写，是最贵的那种** ——
 而这次它藏得住，是因为对那条二进制屏幕流来说，日志"看起来还是好的"。
 
+### 叠加应用就是外部 flash 里的一块区域，页面可以直接写
+
+Labs 版能跑小的叠加应用（Tetris、Breakout、Plasma、Cube3D、Beam、Beacon、FoxHunt、
+BroadcastFM）。上游是用 UVStudio 通过 WebSerial 装进去的；在我们这里，它们就是**外部 flash 镜像
+里的字节** —— 而镜像本来就在页面手里，所以既不需要串口协议，也不需要浏览器授权，只是**同样的字节
+写在同样的偏移**。
+
+布局是固件自己的，从它编译的头文件读出（`App/apps/app_overlay.h`），不是猜的：
+`APP_REGION_BASE 0x00102000`（紧跟在两个状态标记之后）、`APP_SLOT_STRIDE 0x2000`、
+`APP_CODE_OFFSET 0x1000`、16 个槽。每个槽放一个 64 字节的 `app_header_t`（magic `FAP1`、
+对代码做 zlib CRC-32、名字、版本、vma 0x20000280、capabilities），代码在**下一个 4 KiB 扇区**。
+`tools/uvk5_apps.py` 负责解析、校验、列出、安装、擦除；`tools/test_uvk5_apps.py` 管各种拒绝。
+
+两点值得知道。**这 64 字节头和多系统槽位是共用的**：`FMB1` 是固件、`FAP1` 是应用 ——
+这就是为什么"把应用装进槽 1"和"把固件放进槽 1"动的是同一块外部 flash，开机菜单也把两者列在一起。
+另外，这块区域和屏幕缓冲一样，是**从固件自己的常量里读出来的**而非猜的：这里头结构的第一版是 60 字节，
+因为漏了一个字段（`vma`），而真实的 `Beam.app` 字节当场就指出了这一点。
+
 ## 键盘：两个真 bug，都已修复
 
 这里原来的笔记写的是"按键到达了固件但界面不反应"，并且归咎于机器模型。结果发现有**两个