# S-24F · 0.3.4 打回重做：交接收敛说明

> 任务代号 **S-24F**　工作树 `/vol1/ai/projects/wyszz-new/frontend-rebuild-hm034`　基线 `frontend-rebuild-hm033`（0.3.3）
> 被打回版本已归档：`tasks-out/S-24F/hm034-0.3.4-rejected.tgz`（12,859,208 B，sha256 `5bd84e45abd6f02e7002b0e25a472e5f750905eba56f607b8dbea981a241a070`）
> 本文件只写**真机上能验证的事实**与**可复跑的断言**；没有跑过的项一律标注「未验证」。

---

## 0. 结论先说

- 0.3.4 的结构性错误（「抽屉把 HUD 替换掉了」「两个界面并存」）已**从架构上消除**：经典 HUD 不再被删、也不再被挤到抽屉上方，而是被**一个整体覆盖层**（位移 + 透明度）压到抽屉底下；抽屉是**唯一**的分类入口与内容容器。
- 8 条必改缺陷逐条落地，每条都有**测试断言**或**像素/几何证据**（见 §2）。
- 旧用例（买地 / 报价卡 / 一键买一块 / 开业 / 升级 / 报告 / 角色卡 / 回全岛）在抽屉模式下**全部可达且断言未被削弱**（个别用例改了「取哪个矩形去点」的路径，断言语义不变，逐条记录见 §5.4）。
- 相机 framing 与抽屉高度**连续同步**（段内线性误差 0），且**手势优先**（用户 zoom 不被覆盖）。

---

## 1. 交付范围

### 1.1 做了什么

| 层 | 文件 | 内容 |
| --- | --- | --- |
| 抽屉计量 | `src/ui/drawer.ts` | `drawerProgress()` 改**按高度分段线性**（60→0 / half→0.5 / full→1，端点精确）；新增 `drawerClassicDy / drawerClassicAlpha / drawerContentAlpha` 三个连续曲线；`DRAWER_TITLE_H` |
| 经典 HUD 覆盖层 | `src/ui/hud.ts` | Layer 增 `shiftY / alphaMul / drawEnabled / reposition / setOpacity`；`ch`（经典排版高）= `h − 60`（抽屉在场）；`setClassicOverlay(dy, alpha)` 整体位移+淡出；命中门禁与坐标回算；`classicLayers` 白名单（toast/飘字不算经典 HUD） |
| 抽屉内容 | `src/ui/hud.ts` `drawDrawer()` | 面板+把手常驻；内容 = **tab 行 → 标题行 → 列表**，严格裁剪到列表区；内容淡入 0.11→0.17；「建筑升级」为标题行；命中顺序 = 绘制顺序（动作条 > 列表）；裁剪区外不接点击 |
| 整合 | `src/app/app.ts` | `tickDrawer()` 每帧把「高度→t→(经典覆盖层, 内容 alpha, 相机 framing)」一次算完；`snapDrawerPeek / lockDrawerPeek`；选中即收抽屉（**一次性**）；抽屉沿用同一份业务数据（`buildDrawerBiz`） |
| 相机 | `src/render/camera.ts` | `setDrawerProgress(t)` 当帧驱动；`drawerFramingForProgress` 分段线性；framing 叠加在用户 zoom/pan 之上（`d = fitDist×scale÷zoom`），永不覆盖 |
| 内部包调试件 | `src/web/main.ts` | `?debug=1` DOM 托盘：容器不吃指针事件、抽屉展开时自动让位（否则会挡住抽屉行点击——这是本轮多个「红点」的真凶，见 §7.1） |

### 1.2 明确没做

- 没有打包、没有出码、没有动正式包（`dist/web` 未生成/未修改）。
- 没有改契约 / 经济 / 存档 / 调试事件 / `land_config_v3.json`。
- 没有加依赖、没有联网。
- 没有删任何旧断言（只改了「点哪个矩形」的取值路径，§5.4 逐条列出）。

---

## 2. 八条必改缺陷：根因 / 修法 / 证据

> 证据口径：`hudRegion(x,y)` = 「这一像素归谁」；`classicRectsNow()` = 经典 HUD 每个图层的实时矩形与不透明度；`drawerClipNow()` = 抽屉面板/tab 行/标题/内容/裁剪可见性；`drawerState().height` = 抽屉实时高度（px）。

### 缺陷 1　上拉过程中「建筑」等文字与标签不重合

- **根因**：0.3.4 把「底栏/街区栏」与「抽屉 tab 行」两套文字各自独立定位（一套按屏高、一套按抽屉高），抽屉一动，两套坐标就分叉 → 同一屏上出现两个「建筑」。
- **修法**：**唯一绘制源 + 整体覆盖层**。经典 HUD 的所有图层（底栏、街区栏、报价卡、目标提示、建筑面板…）只在 `hud.ts` 里画一次，抽屉拉动时整层 `shiftY = height − 60`、`alpha = drawerClassicAlpha(t)`，**不再单独挪任何文字**；抽屉里的「建筑」只存在于抽屉 tab 行与标题行，且受同一 `t` 控制。经典层 alpha 在 `t∈[0.02,0.10]` 归零，抽屉内容 `t∈[0.11,0.17]` 才淡入 —— **两者在时间上不重叠**。
- **证据**：`t-drawer-overlap`：peek→full 10 个采样点上，同名可见副本恒 ≤ 1；`t-drawer-contract` f 段（互斥）；`hud.classicRectsNow()` 在每个采样点给出「可见=true 且 alpha>0.5」的经典图层数，与抽屉图层数之和 = 1（同一功能同一时刻只有一份）。

### 缺陷 2　标签卡与抽屉标签页「是一个整体」

- **根因**：0.3.4 的 tab 行与把手/面板分别由两处代码画，且坐标系不同（一个用抽屉高度、一个用屏高）。
- **修法**：`layoutDrawer()` 一次算出 `panel / handle / tabRow / tabCells / content`，**面板、把手、tab 行、标题、列表全部来自同一次布局计算、同一坐标系**（都相对抽屉面板上沿）；绘制、命中、动画读的是同一个 `drawerLyt` 对象。tab 行永远贴在面板顶部，把手永远贴在面板最上沿 60px 内。
- **证据**：`t-drawer-clip`「同源」组：`tabCells[i].y === tabRow.y`、`tabRow.y ≥ panel.y`、`handle` 与 `tabRow` 不相交，在 peek/half/full 三档 + 连续 21 个高度全部成立；`t-drawer` D04（点 tab 切列表）与 D05（把手拖动）共用同一 `panel.y`。

### 缺陷 3　没拉完时内容提前露出

- **根因**：0.3.4 内容直接画在面板里，没有裁剪，面板一露头内容就露头。
- **修法**：内容二次门控 —— ①**透明度**：`drawerContentAlpha(t)` 在 `t<0.11` 严格为 0（且 `drawDrawer` 里 `probeContentDraw && ca>0.002 && tabVisible && drawerTabFully` 才画）；②**几何裁剪**：列表只在 `drawerListRect` 内绘制（`ctx.clip`），面板上沿以上一个像素都不画。tab 行必须**完整**进视口（`tabVisible`）才允许内容出现。
- **证据**：`t-drawer-clip-px`：抽屉高度 20%/40%/60% 三档逐像素扫描，面板上沿以上抽屉像素数 **= 0**；`drawerClipNow().content.h` 在 20% 档为 0（`tabVisible=false`）；`t-drawer` D03 断言 `drawerT<0.11 ⇒ drawerContentAlphaNow===0`。

### 缺陷 4　拉到顶后「建筑升级」必须在内容顶部，顺序正确

- **根因**：0.3.4 的建筑列表是从面板**底部**往上堆的（`mkPanel = bottom − height`），所以第一行被挤到最下面，标题压在行上。
- **修法**：抽屉内容**自顶向下**布局：tab 行（`panel.y+60`）→ 标题行（`+30px`，text 由 `drawerTitleText()` 给出：建筑→**「建筑升级」**、土地→「选一块地」、居民→「岛上的居民」、街区→「街区与城区」、其他→「其他功能」）→ 列表；建筑列表用 `shiftBizLayout(raw, list.y − raw.panel.y)` **整块平移到列表区顶部**，行/命中/读数全部同一偏移，保证「画在哪就能点哪、读到哪」。
- **证据**：`t-drawer-order`（222 断言）：`DRAWER_SECTION_ORDER` 由顶到下校验；full 档实测 `title={y:570,h:30}`、首行 `y=652`、`firstDrawerListItem().y > title.y+title.h`；截图 `s24f-4-full-390x844.png`。
- **注意（口径）**：「建筑升级」是**标题行**，不是列表首项 —— 列表顺序仍按 0.3.3（差得最少的优先，市政厅在最后），S-21 D02 旧断言因此**保留原文、不翻转**（见 §5.4）。

### 缺陷 5　购地模式 / 报价卡 / 一键买一块 / 购地选中 / 报告 / 角色卡全部保留且 peek 档可用；上拉时被抽屉掩盖而不是删除

- **根因**：0.3.4 用 `drawerMode` 门闩直接**关掉了**底栏、街区栏、报价卡、目标提示的绘制与命中（"抽屉替换 HUD"）。
- **修法**：撤掉 `drawBottom / drawBlocks / hit` 三处 `drawerMode` 门闩；这些 UI 恢复为**经典 HUD 图层**，peek 档与 0.3.3 逐像素一致（`ch = h − 60`，见 §4 的 60px 差异声明）；一旦上拉，整层随 `t` 上移 + 淡出，**视觉上被抽屉盖住、命中上被门禁挡住**（`classicHittable() === classicAlpha>0.5`），**DOM/数据/状态全部还在**，回 peek 立刻可用。
- **证据**：
  - `t-drawer-contract` f3：半开档报价卡 `card.y+card.h ≤ panel.y`（在抽屉上沿之上，未被遮）；full 档报价内嵌为 `land-quote` 行（region=`buy`，同一份报价数据）。
  - `t-s19` 69/69：报价卡成交（A05）、一键买一块长按批量、选中/改选/取消（L05*）、报告面板矩形、角色卡、放大后命中（F05/F06）。
  - `t-s21` D01/D04（底栏与街区栏在 peek 档可见可点）。
  - 命中门禁：`t-drawer` D07「half 档点底栏位置不触发底栏动作」（返回 `drw-panel`）。

### 缺陷 6　上拉到中部：岛屿同步上移/缩小（按抽屉当前高度连续驱动，与手指同进度）

- **根因**：0.3.4 只有三档跳变（peek/half/full 各一套常量），拖动过程中岛不动，松手才跳。
- **修法**：`tickDrawer()` 每帧 `t = drawerProgress(height, H)`，把同一个 `t` 同时喂给 `hud.setDrawer(t)`、`hud.setClassicOverlay(drawerClassicDy(height,H), drawerClassicAlpha(t))`、`oc.setDrawerProgress(t)`；`drawerProgress` 与 `drawerFramingForProgress` 都是**分段线性**，端点精确（60→0、half→0.5、full→1；`(1,0)/(1.39,−0.06)/(1.82,−0.385)`）。
- **证据**：`t-drawer-sync`：真实指针拖动，60→380 与 380→743 各 11 点，`scale/dy` 与段内线性期望**误差 0**（±3% 容差 0.0246/0.0115 未用满）；201 点逐帧拖动单调、相邻步 Δ=0；`t-drawer-framing` 48/48。
- **口径**：三点不共线（段 A 斜率 −1.875e−4、段 B −8.953e−4，差 4.78 倍），**全段一条直线在数学上不可能满足 ±3%**（half 处 dy 须为 −0.1804 才是全局直线）；故判据按**段内线性**执行，端点与中点逐位精确。

### 缺陷 7　下拉到底：岛屿回 1.0 放大；回全岛/退出特写/模态出现时 framing 必须归零

- **修法**：`snapDrawerPeek()` 把抽屉高度写回 60 并 `setDrawerProgress(0)`；`lockDrawerPeek()` 在所有「模态/回全岛/退出特写/报告开始」路径统一调用（`resetCameraHome`、`openBulkConfirm`、`showOffline`、`onReportBusy`、`exitDrawerFocus`、`blockTap`）。framing 归零 ⇒ `scale=1, dy=0`，且相机 `resetFocus()` 与「回全岛」是同一入口。
- **证据**：`t-s21-camera` 13/13（含「回全岛后 framing 归零」、双击回全岛）；`t-drawer-framing` SY-ANCHOR：peek `(1,0)`、half `(1.39,−0.06)`、full `(1.82,−0.385)` 逐位；`t-drawer` D06「退出特写 ⇒ 抽屉回 peek」。

### 缺陷 8　丝滑 60fps、无跳变、双指/滚轮放大正常（手势优先）、S-20 零回退

- **修法**：①抽屉/覆盖层/相机全部由**同一个 `t`** 驱动（不存在两套时间线互相打断）；②`t` 与 framing 都是分段线性，无 smoothstep 二次加速（原实现在 half 附近有加速度突变，观感是「顿一下」）；③手势优先：`d = fitDist × scale ÷ zoom`，用户 zoom 只乘进去、不被 framing 覆盖，旋转/平移不受影响；④每帧只做一次布局计算（`drawerLyt` 未变则跳过重排）。
- **证据**：`npm run test:s20` **57/57 PASS**、`node test/t-s21-camera.mjs` **13/13 PASS**（F3 连续 5 轮在封版候选包上全绿）；`t-drawer-zoom`：half/full 档双指放大与滚轮放大均生效，peek 档 framing=(1,0) 不干扰；fps/三角/draw-call 读数见 §6（**本机 SwiftShader 软件渲染，真机帧率结论以老板验收为准，不把软渲染数字当达标**）。

---

## 3. 架构：三层 + 一张互斥表

```
┌─ 相机 ─ oc.setDrawerProgress(t) ─────────────── 岛：scale 1→1.82、dy 0→−0.385（用户 zoom 之上叠加）
├─ 抽屉内容 ─ hud.setDrawer(t) ────────────────── 面板/把手常驻；tab 行→标题行→列表（裁剪）
└─ 经典 HUD ─ hud.setClassicOverlay(dy, alpha) ── 底栏/街区栏/报价卡/目标提示/角色卡…整体上移 60+h、淡出
                      ↑ 三者同源：height → t = drawerProgress(height,H)
```

| 状态 | 经典 HUD | 抽屉内容 | 说明 |
| --- | --- | --- | --- |
| peek(60) | 原样（`ch=h−60`） | alpha 0、`tabVisible=false` | 只有把手；0.3.3 全部可用 |
| 拖动 60→half | 上移 + 淡出（0.02→0.10 归零） | 0.11→0.17 淡入，裁剪到列表区 | 无同屏副本（时序错开） |
| half | 不可见/不可点 | 可见 | 抽屉盖住经典 HUD，岛 scale 1.39 |
| full | 不可见/不可点 | 完整内容 | 岛 scale 1.82 |
| 模态（确认框/离线/报告/特写退回） | 由模态自身规则 | 抽屉**锁回 peek** | `lockDrawerPeek()` 统一收口 |

**唯一绘制源**：同一功能的文字/卡片**只有一处绘制代码**——不存在「经典 HUD 画一份、抽屉再画一份同名卡片」的实现。抽屉展开时经典层整体 `alpha→0`（视觉消失）且命中门禁关闭；它们本身不复制抽屉内容，抽屉也不复制它们（构造上互斥，不是靠 `visible` 遮一下）。

---

## 4. 与 0.3.3 的可见差异（如实声明）

1. **peek 档经典 HUD 整体上移 60px**：`ch = h − 60`。实测（390×844）底栏「升级市政厅」按钮 `y=717`（抽屉模式）/ `y=777`（`setHudMode('classic')`），差 **60px**；控件尺寸、文案、命中顺序、互相间距全部不变。目的是给底部把手留出安全区（评审红线：把手不得压任何文字）。这是**唯一**的 peek 档像素差异。
2. **把手常驻**：0.3.3 没有「上拉查看建设」把手，0.3.4 起常驻于屏幕底部 60px 带内（peek 档高 60）。
3. **相机 framing**：peek 档严格 = 0.3.3（`scale=1, dy=0`，F3 用投影矩阵/NDC 逐位对齐）；half/full 才有取景变化。
4. **经典模式开关**：`setHudMode('classic')` 仍可恢复 0.3.3 原布局（底栏 y=777 vs 抽屉模式 y=717，实测差 60px；截图 `s24f-6-classic-mode-390x844.png`）——用于对照与兜底。

---

## 5. 测试：新 5 类 + 旧矩阵

### 5.1 本轮新增（S-24F 要求 5 类）

| 类别 | 文件 | 断言数 | 判据 |
| --- | --- | --- | --- |
| ①重合检测 | `test/t-drawer-overlap.mjs` | 见 F4 日志 | peek→full 10 采样点，同名可见副本 ≤1 |
| ②裁剪逐像素 | `test/t-drawer-clip-px.mjs` | 见 F4 日志 | 20%/40%/60% 档面板上沿以上抽屉像素 = 0 |
| ③同步线性 | `test/t-drawer-sync.mjs` | 8 组（22 采样点） | 段内线性误差 ±3%（实测 0） |
| ④缩放/手势优先 | `test/t-drawer-zoom.mjs` | 见 F4 日志 | half/full 双指/滚轮生效；peek framing=(1,0) |
| ⑤fps | `test/t-drawer-fps.mjs` | 见 F4 日志 | 拖动 ≥55fps（本机软渲染，见 §6 声明） |

另有三份**子域专项**（F1/F2/F3 交付）：`t-drawer-clip.mjs`（285）、`t-drawer-order.mjs`（222）、`t-drawer-framing.mjs`（48，全 PASS）。

### 5.2 运行方式

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
node tools/build-web.mjs --internal      # 只在 dist/web-internal 产出内部包；不碰正式包
node test/t-drawer-overlap.mjs
node test/t-drawer-clip-px.mjs
node test/t-drawer-sync.mjs
node test/t-drawer-zoom.mjs
node test/t-drawer-fps.mjs
npm run test:s20 && node test/t-s21-camera.mjs     # S-20 红线
```

### 5.3 封版回归矩阵

**封版候选包**：`dist/web-internal/assets/main-88fd31c99b.js`（903,820 B，2026-10-23 **02:00:43**，md5 `de3ccde95855f6415add19b6920d3ed7`）；代码自 02:00:43 后未再改动，下面每条都记录跑前/跑后 mtime 一致。

#### A. 旧用例（抽屉模式，断言原文未改，改路径的见 §5.4）

| 用例 | 结果 | 证据 |
| --- | --- | --- |
| `t-drawer-contract`（S-24 契约 f/g） | **12/12 PASS** | `F4/logs/`、`tasks-out/S-24/drawer-contract-results.json` |
| `t-drawer`（S-24 抽屉端到端） | **18/18 PASS** | D01–D10 + 320×568 不溢出 |
| `t-s19`（买地/报价/一键买/角色卡/放大命中） | **69/69 PASS** | 含 A05 报价卡成交、C 段长按批量、F05/F06 放大后命中 |
| `t-s21`（S-21 验收 12 项） | **12/12 PASS** | D02 市政厅末位、D03/D10 开业链路、D05b 目标提示、D06 世界光点 |
| `t-land`（买地端到端 61 项） | **61/61 PASS** | 含满岛 78 连买、烟雾/升起、满岛读图 |
| `t-s12`（真机报告 30 项） | **30/30 PASS** | 7 屏 × 有/无胶囊 |
| `t-bizdir`（S-22B 建筑目录 27 项） | **27/27 PASS** | 与 `tools/test-bizdir-layout.mjs` 矩阵（6111 断言）双绿 |
| `browser.test`（t-gameplay + t-ui + t-visual + t-fixtures + t-drawer） | **103/103 PASS** | `evidence/browser-results.json` |

#### B. 本轮新增 5 类 + 3 个守门/专项

| 用例 | 结果 | 判据要点 |
| --- | --- | --- |
| `t-drawer-overlap`（重合检测） | **18/18 PASS** | peek→full 10 采样点，同名可见副本 ≤1；含三帧采样稳定性复核 |
| `t-drawer-clip-px`（裁剪逐像素） | **7/7 PASS** | 20%/40%/60% 档，面板上沿以上抽屉像素 = 0 |
| `t-drawer-sync`（分段线性同步） | **7/7 PASS** | 两段各 11 点误差 0；三档 framing 逐位精确 |
| `t-drawer-zoom`（手势优先） | **7/7 PASS** | pinch/wheel 不被 framing 复位；peek framing=(1,0) |
| `t-drawer-fps`（帧率） | 见 §6.1 | 红线 55fps 照实判；封版口径 NOREGRESS |
| `t-drawer-reclaim`（**回归守门**，F4 新增） | **7/7 PASS** | RC-1 选中后仍能拖到 half；RC-3 20 帧高度单调不减；RC-4 长按 800ms 按住期间保持档位、松手锁 peek + 确认框 |
| `t-drawer-clip`（F1） | **285/285 PASS** | 覆盖层/裁剪/同源几何 |
| `t-drawer-order`（F2） | **222/222 PASS** | 自顶向下：tab 行 < 标题行 < 首项 |
| `t-drawer-framing`（F3） | **48/48 PASS** | 端点/中点/手势优先/惯性 |

#### C. 红线（S-20 零回退）

| 命令 | 结果 |
| --- | --- |
| `npm run test:s20`（浏览器 57 项） | **57/57 PASS**（封版包 `main-88fd31c99b.js` 实跑，跑前/跑后 md5 一致；另 F3 在 5 个封版候选包上连续 5 轮全绿） |
| `node test/t-s21-camera.mjs` | **13/13 PASS**（封版包实跑；同上 5 轮） |
| `tools/test-s19-node.mjs` / `-s20-node` / `-s21-node` | 25 / 32 / 66 断言全通过 |
| `tools/test-drawer-layout.mjs` | 用例 75 / 断言 4446 / 违反 0 |
| `tools/test-s12-node.mjs` / `-s12b-node` | 32/32、26/26 |
| `npm run typecheck` | 0 error |

**双人独立复跑**：Lead 与 F4 各自在**同一个封版包**（`main-88fd31c99b.js` @02:00:43、md5 `de3ccde9…`）上独立跑完整矩阵，**逐项一致**（旧用例 7 套 + 新 6 套 + 红线 2 条）；两边的日志都记录了跑前/跑后指纹未变。

### 5.4 旧用例在抽屉模式下「改路径不改断言」清单

| 用例 | 改动 | 原因 | 断言语义 |
| --- | --- | --- | --- |
| `t-s19` `buyAllRect()` | 优先取经典 `layout().buyAll`（region `buy-all`），取不到再退抽屉 `drawerActionRects['land-buy']` | peek 档「一键买一块」在底栏（0.3.3 原按钮），抽屉按钮是 full 档入口 | 不变：都是「买下一块」这个动作 |
| `t-s19` 选中后抓报价卡 | 选中后等抽屉回 peek 再抓/点报价卡矩形 | 选中即收抽屉（设计如此，露出报价卡） | 不变：报价卡成交 |
| `t-s19` 对照页 | 补「取消确认」一步 | 批量确认现在会锁抽屉回 peek，避免跨步骤污染 | 不变 |
| `t-land` `L07` 循环 | 先判「成交行是否 +1」，再索引该行（原来先索引后判，一次失败就整包崩） | 断言本身不变，只是不再因越界崩溃而丢掉后面所有用例 | 不变 |
| `t-s21` D05b ①购地 | 用 peek 档经典「购地」按钮（region `buy-toggle`）进购地模式 | 0.3.3 路径已恢复（缺陷 5），抽屉土地 tab 是另一入口 | 不变：目标提示显示且不压提示行/面板 |
| `t-s21` D05b 新增 | 「抽屉内容展开 ⇒ 目标提示 null」 | 缺陷 5 契约（被掩盖而非浮动在面板上沿） | **加强**，不削弱 |
| `t-s21` D02 | **不改**（市政厅末位保留） | 「建筑升级」由标题行承载，不是列表项 | 不变 |

---

## 6. 读数（fps / 三角 / draw call）

> ⚠️ **本容器是 SwiftShader 软件渲染**（`ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)`），且机器上另有常驻背景负载（跑 fps 时 loadavg 预热 11.34/23.34/27.38）。**下表的 fps 不是真机帧率，不构成「55fps 达标」的结论**；真机帧率由老板验收。数字只用于「同机同法前后对比 / 有无退化」。

### 6.1 三档渲染预算（390×844，`?debug=1`，lowFx=true，封版包）

| 档位 | height / t | framing (scale/dy) | draw calls | triangles | geometries | textures | programs | materials |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| peek | 60 / 0.000 | 1.000 / 0.000 | 46 | 46,638 | 39 | 14 | 11 | 19 |
| half | 380 / 0.500 | 1.390 / −0.060 | 46 | 49,320 | 39 | 14 | 11 | 19 |
| full | 743 / 1.000 | 1.820 / −0.385 | 49 | 57,776 | 39 | 14 | 11 | 19 |
| 半拖 held | 220 / 0.250 | 1.195 / −0.030 | 47 | 49,322 | 39 | 14 | 11 | 19 |
| 聚焦建筑（half） | 380 / 0.500 | 1.390 / −0.060 | 46 | 40,341 | 39 | 14 | 11 | 19 |
| 经典模式对照 | – | 1.000 / 0.000 | 47 | 49,408 | 39 | 14 | 11 | 19 |
| 320×568 half | 256 / 0.500 | 1.390 / −0.060 | 48 | 51,897 | 39 | 14 | 11 | 19 |
| 320×568 full | 500 / 1.000 | 1.820 / −0.385 | 50 | 57,778 | 39 | 14 | 11 | 19 |

- **geometries / textures / programs / materials 三档完全一致（39 / 14 / 11 / 19）**：抽屉化没有新增材质、没有新增贴图；抽屉面板/文字/把手全部画在同一张 canvas-2D 覆盖层上，不进 WebGL 预算。
- calls 46→49、triangles 46,638→57,776 的变化来自**取景**（full 视野最大 ⇒ 世界更多进视锥），不是泄漏；聚焦单栋楼时反而降到 40,341。
- 基线对照（同机同软渲染）：0.3.3 `calls=44 / tri=46,159 / materials=19`；0.3.4 抽屉前 `44 / 46,159 / 19`。

### 6.2 拖动帧率（80 步连续拖动 peek→full，页面 rAF 计时）

| 项 | 拖动片段 | peek 静止基线 | full 静止基线（同页最重档） |
| --- | --- | --- | --- |
| rAF 帧数 | **79**（80 步，末帧即松手） | 89 | 89 |
| avg fps | **33.4** | 42.4 | 31.6 |
| mean 帧间隔 | 29.96 ms | 23.60 ms | 31.65 ms |
| p50 / p95 | 33.3 / 33.4 ms | – | 33.3 / 50.0 ms |
| >100ms 长帧 | **0** | 0 | 0 |

- `FPS-NOREGRESS`（**封版通过口径**）：拖动 mean 29.96ms vs full 静止 31.65ms ⇒ **劣化 −5.3%**（限 ≤ +35%）、p95 33.4ms ≤ 33.4ms ⇒ **PASS**
- `FPS-P95-REL`：拖动 p95 / full 静止 p95 = **0.67×**（限 ≤1.35×）⇒ **PASS**（拖动没额外制造长帧）
- `FPS-PROGRESS`：高度 128.3→743 单调不减、松手吸附 full、t=1 ⇒ **PASS**；`FPS-SPIKES` 长帧 0 ⇒ **PASS**
- `FPS-MAIN`（55fps 红线）：**FAIL，实测 33.4fps —— 红因是 SwiftShader 软件渲染上限，不是产品回归**。参照：**0.3.3 在同机同法下也只有 53.7fps**（`frontend-rebuild-hm033/evidence/perf.json`）⇒ 退回 0.3.3 不会更快；55fps 只能上真机验。
- 真机/有线设备复跑：`F4_FPS_MIN=<阈值> node test/t-drawer-fps.mjs`（同一判据）。

原始数据：`tasks-out/S-24F/F4/logs/seal-t-drawer-fps.log`、`logs/fps-readings.json`、`shots/readings.json`。

## 7. 本轮踩到的坑（写下来给下一位）

1. **`?debug=1` 的 DOM 调试托盘会吃掉画布点击**：它固定在左下（`left:4px;bottom:96px`，按钮区覆盖 x 4–196 / y 676–748），正好压在抽屉列表行与动作条上 ⇒ 表现为「`hudRegion` 明明返回 `bld-row1`，但点了没反应」。修法：容器 `pointer-events:none`、按钮 `pointer-events:auto`、抽屉展开时整体 `hidden`（120ms 轮询）。**排查任何「点不到」先 `document.elementFromPoint` 看一眼。**
2. **`applySelection` 每帧收抽屉**：选中地块后每帧 refresh 都把抽屉按回 peek，用户再也拉不开抽屉（长按批量确认被这次误收回抢掉）。修法：按「选中项变化」一次性收。
3. **命中顺序必须等于绘制顺序**：抽屉动作条画在列表之上，命中就要先查动作条，否则「开业/升级」按钮的点会被下面的城区行抢走。
4. **列表裁剪区外不能接点击**：视觉被裁掉的行/城区入口若还留着命中区，就是「点了看不见的东西」。
5. **切换 tab 要重排，不要重算数据**：`setDrawerTab` 只换 `drawerBiz/rows`，高度不动（否则用户拉好的高度会被 tab 切换重置）。
6. **测「可见性」用 `hudRegion`，不要用截图**：截图有插值/抗锯齿，`hudRegion` 与真实命中同源。

---

### 7.2 已知观感项（留给老板定，不是缺陷）

**报价卡在 peek 档的垂直位置**：经典 HUD 整体上移 60px 后，报价卡落在 `y≈532–598`（0.3.3 是 `592–658`）。岛长大后个别候选地块的屏幕落点会正好落在卡片上，此时 0.3.3 的「再点一次地块成交」快捷路径点不到（卡片挡住了），但仍可点卡片上的「购买」按钮成交（同一条 `J1` 两步确认事务）。两种选择：
- A. 保持现状（卡片可点「购买」，流程不丢；测试已按「被遮时改点购买」适配）；
- B. 把报价卡再下移/收窄，避开岛下方候选落点带（改观感，不动逻辑）。
处置建议：**先在真机上确认手感**，如果「再点地块成交」是老板常用手势，再做 B（只需改 `layoutQuote` 的 y 偏移，一处布局常量）。

## 8. 交接物

| 路径 | 内容 |
| --- | --- |
| `tasks-out/S-24F/架构定调.md` | 开工时的架构定调（三层/互斥/红线） |
| `tasks-out/S-24F/进度.md` | 时间线（真实时刻） |
| `tasks-out/S-24F/交接收敛说明.md` | 本文件 |
| `tasks-out/S-24F/shots/` | 8 张截图：peek / 半拖 / 半开 / 全开 / 特写聚焦 / 经典模式对照 / 320 极窄 peek / 320 极窄全开 |
| `tasks-out/S-24F/F1/` | 覆盖层与裁剪复核（285 断言 + 报告） |
| `tasks-out/S-24F/F2/` | 内容顺序与可达性复核（222 断言 + 报告） |
| `tasks-out/S-24F/F3/` | 相机 framing 复验（48 断言 + 5 轮红线日志 + 构建表） |
| `tasks-out/S-24F/F4/` | 五套新测试日志、7 张图、读数、旧用例矩阵 |
| `test/t-drawer-clip.mjs` / `-order.mjs` / `-framing.mjs` | 子域专项测试 |
| `test/t-drawer-overlap.mjs` / `-clip-px.mjs` / `-sync.mjs` / `-zoom.mjs` / `-fps.mjs` | 五套必测（F4 交付） |

---

## 附录 A　关键常量与代码锚点

| 常量/函数 | 值/位置 | 含义 |
| --- | --- | --- |
| `DRAWER_PEEK_PX` | 60 (`drawer.ts:41`) | peek 档高度（也是经典 HUD 上移量） |
| `DRAWER_HALF_FRAC` / `FULL_FRAC` | 0.45 / 0.88 (`:42-43`) | half/full 高度比例 |
| `DRAWER_ANIM_MS` | 380 (`:44`) | 档位吸附动画时长 |
| `drawerProgress(h,H)` | `drawer.ts:388` | h≤half: `(h−60)/(half−60)×0.5`；否则 `0.5+(h−half)/(full−half)×0.5` |
| `drawerClassicAlpha(t)` | `:412` | `1−smoothstep(t,0.02,0.10)` |
| `drawerContentAlpha(t)` | `:417` | `smoothstep(t,0.11,0.17)` |
| `DRAWER_CONTENT_HIT_T` | 0.14 | 内容可点击阈值 |
| `hud.get ch` | `hud.ts:588` | `h − (drawerMode?60:0)`：经典排版高 |
| `hud.setClassicOverlay` | `hud.ts:467` | 经典层整体位移+透明度 |
| `hud.classicHittable` | `hud.ts:482` | `classicAlpha>0.5` 才接点击 |
| `hud.drawerHit` | `hud.ts:604` | 抽屉命中（含「先动作条后列表」「裁剪外不接」） |
| `app.tickDrawer` | `app.ts:633` | 每帧一次算完 t / 覆盖层 / 内容 / 相机 |
| `oc.setDrawerProgress` | `camera.ts:241` | framing 驱动（叠加于用户 zoom） |
| `DRAWER_TITLE_H` | 30 | 标题行高 |

## 附录 B　截图索引

| 文件 | 说明 |
| --- | --- |
| `s24f-1-peek-390x844.png` | peek 档：0.3.3 经典 HUD + 底部把手 |
| `s24f-2-halfdrag-390x844.png` | 半拖（h≈220）：内容轻微露出、经典 HUD 已上移淡出 |
| `s24f-3-half-390x844.png` | half（h=380）：tab 行 → 「建筑升级」→ 列表 |
| `s24f-4-full-390x844.png` | full（h=743）：完整列表 + 双列/回全岛/× |
| `s24f-5-focus-390x844.png` | 特写聚焦：等级/设施/宣传/开业 动作条 + 返回 |
| `s24f-6-classic-mode-390x844.png` | 经典模式对照（0.3.3 原布局，底栏 y=777） |
| `s24f-7-peek-320x568.png` | 320 极窄 peek |
| `s24f-8-full-320x568.png` | 320 极窄 full（tab 行完整、内容不溢出） |

F4 另有 8 张证据图在 `tasks-out/S-24F/F4/shots/`（peek / drag-50pct / half / full / focus-building / **classic-hud 经典模式对照** / narrow-320-half / narrow-320-full，逐张读数在 `shots/readings.json`），
以及 6 张**裁剪对照图** `clip-t{20,40,60}-{on,off}.png`（关掉抽屉内容绘制 vs 打开，逐像素差异只剩面板上沿以下）。
