# S-32 / 0.3.5F · D3 取景与特写实测（前后数字表）

> 任务：`tasks-out/S-32/架构定调.md` §4「相机 / 取景定稿」+ 任务书 `53-0.3.5F抽屉打磨任务书.md` §四
> 工作树：`frontend-rebuild-hm035`（版本串 `0.3.5-dev`，未改）
> 实测脚本：`tools/s32-measure.mjs`（headless，跑 `dist/web-internal`，`islandBoxScreen()` 口径）
> 原始读数：`/tmp/s32/d3-measure.json`（改后）、`/tmp/s32/d3-measure-baseline.json`（改前）
> 相机纯逻辑：`node test/t-s32-camera.mjs` → `/tmp/s32/d3-camera.json`（51/51 PASS）
> 实测时间：2026-10-23 12:59（北京时间）；构建 `dist/web-internal/assets/main-66d61fcfe2.js`（12:58:13，`src/app/app.ts` 12:55:27）

---

## 0 结论摘要（一句话版）

- **特写放大已落地**：`focusOn()` 缺省 zoom = `CAM.focusZoomMax = 5.0`，四尺寸实测 `zoom/zoomTarget = 5.000`，app 在特写稳定后自动解 `focusCompose`，目标楼中心与「抽屉顶边以上可见区中心」偏差 **−0.17 / −0.20 / −0.17 / −0.17 %H**（判据 ≤8%H，全 PASS）。
- **用户手势零回退**：`zoomMax` 仍 3.0、`CAM_SMOOTH` 一字节未改；`t-s32-camera` 51 条里 8 条专测「setZoom(5)/zoomBy 被夹回 3.0」「焦点 5 后用户缩小手势回 ≤3」。
- **岛景上移已生效**：half 档岛包围盒下沿与抽屉顶边间隙从 **+2.2 / −17.9 / +2.8px**（改前 3 尺寸）改善到 **17.24 / 17.14 / 17.20 / 16.80px**（四尺寸，判据 ≥16px 全 PASS）；街区 tab（候选地块可见）half 间隙 **16.79 / 16.81 / 16.92 / 16.93px** 同样 PASS；peek 下沿 **62.84 / 62.82 / 62.81 / 62.76%H**（全 PASS 60~66%）。
- **0 偏移 = 0.3.3 逐位一致**：`setFocusCompose(0)` / `setBaseLift(0)` 后投影矩阵与「从未调用」实例 `Object.is` 逐位相等（8 条断言）；退出特写后 `focusCompose=0`、`zoomTarget=1`、抽屉回 peek（三尺寸 PASS）。
- **half 档任务书矛盾已按裁决实测记录两条数**：half 下沿 49.98~51.63%H（永远不可能 60~66%，抽屉顶边就在 55%H），第一优先级「不被 HUD 遮挡」= 间隙 ≥16px，实测 28.1~31.8px（见 §4）。

---

## 1 相机 API 变更（唯一改动的 src 文件：`src/render/camera.ts`）

| 新增 | 语义 | 兼容性 |
|---|---|---|
| `CAM.focusZoomMax = 5.0` | **只给 `focusOn()` 用**的特写距离上限 | `CAM.zoomMax` 仍 `3.0`；`zoomBy / setZoom / panBy / drag` 的 clamp 一律不看它 |
| `focusOn(x, z, zoom = CAM.focusZoomMax)` | clamp 到 `[zoomMin, focusZoomMax]`；平移夹取用 `focusPanLimit(fitR, zoom)` | 老调用显式传 3 仍是 3（`app.ts` 原有 `focusOn(...,3)` 不受影响） |
| `focusPanLimit(fitR, zoom)`（纯函数） | 焦点态平移半径：`fitR × (1 + 0.15×max(0, zoom−1))` ⇒ zoom=1 为 `fitR`、zoom=5 为 `1.6×fitR`；异常输入恒有限 | `panLimit / clampPan / panBy / setPan` **逐位未动**（`S32C-D06/D07` 断言锁住） |
| `setFocusCompose(frac)` + `get focusCompose` | 焦点构图偏移（屏高比例，正 = 内容上移），写进 `syncViewOffset` 的 `offsetY` | 默认 0；0 时**不做加法**（连 `−0` 都不改写）⇒ 投影矩阵逐位等于 0.3.3 |
| `setBaseLift(frac)` + `get baseLift` | peek/half 基础取景偏移（屏高比例，正 = 内容上移） | 同上；`setDrawerProgress(0)` 后与「从未调用」实例逐字段一致 |
| `solveFit()` | 两个偏移在求解期间**临时归零**、结束后 restore；`resize()` 经 `syncViewOffset` 重算 | 求解结果与「无取景偏移」实例 `Object.is` 相等 |

未动：`CAM_SMOOTH`（tau 14 / fitTau 14 / dtMax 1/30 / inertiaDecay 0.02 / inertiaZoomOff 2）、`zoomMax=3.0`、`panLimit/clampPan` 语义、`update()` 平滑系数、`underDistBlend` 距离公式（焦点 zoom 5 时 `distance = max(fitDist/zoom, underMinDist)`，pitch −25° 实测 12.64 ≥ 11 不穿模）。

> 静态签名/接口（`get focusCompose()` 等）见 `src/render/camera.ts` 行内注释；纯逻辑断言 51 条全部在 `test/t-s32-camera.mjs`。

---

## 2 口径（任务书 §四 + 架构定调 §4）

- 岛包围盒 = `__wyszzDebug.islandBoxScreen()` = `Box3().setFromObject(world.land.group)` 的 **8 个角投影后的屏幕 AABB**（含岩壁最底点，实测世界 `min.y ≈ −1.714`）；比真实顶点轮廓略保守（底部多约 0.2px）。
- 屏幕坐标：CSS px、左上原点、`y=0` 为顶；`H` = 屏高；`topH` = 顶部 HUD 底边（实测 84 / 81 / 93）。
- peek 底部 HUD 顶边 = `H − 60`；half 抽屉顶边 = `H − round(0.45H)`（844→380、568→256、932→419，与实测抽屉高度一致）。
- 焦点态「可见区中心」= `(H − 实际抽屉高度) / 2`（焦点态抽屉为 half）。
- 判定：peek 下沿 ∈ [60%, 66%]H、岛顶 ≥ topH+8、与底部 HUD 间隙 ≥16px；half 按裁决（§4）；焦点偏差 ≤8%H。

---

## 3 前 / 后数字表（三尺寸逐行）

「改前」= 12:37 实测（相机 `baseLift/focusCompose` 均为 0 的接线前状态；此时相机侧与 0.3.3 逐位一致，`focusOn` 走旧 `zoom=3` 列表特写路径）。
「改后」= 12:50 构建（`baseLift` 已按抽屉进度驱动；焦点走 S-32 行点击特写 = `focusOn` 缺省 5.0）。

### 3.1 peek 档（无抽屉/抽屉 peek）

| 尺寸 | 岛下沿/H 改前 → 改后 | 岛顶−topH 改前 → 改后 | 与底部 HUD 间隙 改前 → 改后 | 判据 | 结果 |
|---|---|---|---|---|---|
| 390×844 | 62.85% → **62.84%** | 302.9 → 302.8 px | 253.6 → 253.7 px | 60~66% + ≥16px | PASS |
| 320×568 | 66.69% → **62.82%** | 181.9 → 159.9 px | 129.2 → 151.2 px | 同上 | PASS |
| 414×896 | —（改前未量） | — | — | 同上 | PASS（62.81%） |
| 430×932 | 62.88% → **62.76%** | 334.2 → 333.1 px | 286.0 → 287.0 px | 同上 | PASS |

- `topH`（改后）：390=84、320=81、414=90、430=93；岛顶均远高于 `topH+8`。
- 改后 peek 的 `baseLift` 实测：0 / 0.0387 / 0.00112 / 0.00107（屏高比例；390 本就在 63% 靶心，无需推）。
- 320×568 由 66.69%（超上限 0.69pp）修到 62.82%：Lead 的 `computeBaseLifts()` 分「候选地块隐藏 / 可见」两套 peek 解（默认建筑 tab 用隐藏解，街区购地模式用可见解）。
- 414×896 是 Lead 12:56 追加的验收尺寸，改前基线只量了 3 尺寸（无该档「改前」数），故只列改后。

### 3.2 half 档（抽屉半开）

**建筑 tab（候选地块隐藏，默认 peek→half 路径）**

| 尺寸 | 岛下沿/H 改前 → 改后 | 岛顶−topH 改前 → 改后 | 与抽屉顶边间隙 改前 → 改后 | 判据（裁决后） | 结果 |
|---|---|---|---|---|---|
| 390×844 | 54.71% → **52.93%** | 274.3 → 259.3 px | **+2.2 → +17.24 px** | ≥16px + 岛顶 ≥topH+8 | PASS |
| 320×568 | 58.08% → **51.91%** | 165.3 → 130.3 px | **−17.9 → +17.14 px** | 同上 | PASS |
| 414×896 | —（改前未量） | — | — | 同上 | PASS（+17.20px） |
| 430×932 | 54.74% → **53.24%** | 302.7 → 288.7 px | **+2.8 → +16.80 px** | 同上 | PASS |

**街区 tab（购地模式候选地块可见，最坏情况）**

| 尺寸 | 岛下沿/H | 岛顶−topH | 与抽屉顶边间隙 | 判据 | 结果 |
|---|---|---|---|---|---|
| 390×844 | 52.99% | 220.0 px | **+16.79 px** | ≥16px | PASS |
| 320×568 | 51.97% | 98.3 px | **+16.81 px** | ≥16px | PASS |
| 414×896 | 53.13% | 233.6 px | **+16.92 px** | ≥16px | PASS |
| 430×932 | 53.23% | 244.4 px | **+16.93 px** | ≥16px | PASS |

- 「改前」half 在 320×568 上岛下沿已经**钻到抽屉顶边下面 17.9px**（被压住）；改后四尺寸全部 ≥16.8px。
- 改后 half 的 `baseLift` 实测：0.01777 / 0.06162 / 0.01674 / 0.01502（建筑 tab）；0.03436 / 0.08275 / 0.03348 / 0.03219（街区 tab）。
- half 档 framing 仍严格 `{scale: 1.39, dy: −0.06}`（S-24F 三档数值未动，`t-drawer-framing` 48/48）。
- Lead 把 `targetHalf` 收到 `drawerTopHalf − 17`（+1px 安全量）后，早前 430×932 的 0.18px 缺口已消除（15.82→16.80px）。

### 3.3 焦点态（特写）

| 尺寸 | 目标楼 | 目标楼中心屏幕 y | 可见区中心 y | 偏差/H | zoom / zoomTarget 改前 → 改后 | 自动解出的 compose | 判据 | 结果 |
|---|---|---|---|---|---|---|---|---|
| 390×844 | index 2（公园） | 230.6 | 232.0 | **−0.17%** | 3.0 → **5.000** | +0.04385 | ≤8%H | PASS |
| 320×568 | index 2（公园） | 154.9 | 156.0 | **−0.20%** | 3.0 → **5.000** | −0.01156 | ≤8%H | PASS |
| 414×896 | index 2（公园） | 245.0 | 246.5 | **−0.17%** | 3.0 → **5.000** | +0.04472 | ≤8%H | PASS |
| 430×932 | index 2（公园） | 254.9 | 256.5 | **−0.17%** | 3.0 → **5.000** | +0.04600 | ≤8%H | PASS |

- 320×568 的 half 抽屉只有前 1~2 行完整可见（列表在滚动区），实测走「真实点击行」路径点的是该行可见的建筑；四尺寸目标楼均取「离原点最远」的外圈楼。
- **`focusCompose` 已由 app 自动求解**（特写稳定后一次性量目标楼 y → `dev/H` 写入），故偏差全部收敛到 ≤0.2%H（<1.5px）；`setFocusCompose` 本身仍是纯几何 API，探针交叉验证：若 compose 归零，偏差将回到 **+4.22 / −1.36 / +4.30 / +4.43%H**，即自动解把偏差精确抵消（探针 PASS）。
- 焦点压暗/高亮不属于本表（D4 截图验收）；本表只量几何与 zoom。

### 3.4 退出特写（回全岛）

| 尺寸 | zoomTarget | focusCompose | defaultView | 抽屉档位 | baseLift（回档位） | 判据 | 结果 |
|---|---|---|---|---|---|---|---|
| 390×844 | 1 | 0 | true | peek | 0 | 全归零 + 回 peek | PASS |
| 320×568 | 1 | 0 | true | peek | 0.03873 | 同上 | PASS |
| 414×896 | 1 | 0 | true | peek | 0.00112 | 同上 | PASS |
| 430×932 | 1 | 0 | true | peek | 0.00107 | 同上 | PASS |

> 退出路径走生产「返回」按钮（`drawerFocusExitNow` hook 内部与生产路径同一函数），`focusCompose` 归零、`zoomTarget` 回 1、抽屉回 peek、`defaultView=true`；`baseLift` 回到当前档位值（只有 320/414/430 的 peek 有微小基础偏移）——即「基础偏移只由抽屉进度决定，不残留焦点态值」。

---

## 4 任务书 half 档矛盾的裁决与数字（必读）

任务书 §四同时要求：
1. peek **与半开态**：岛包围盒下沿 60%~66%H；
2. 与底部 HUD 顶边间隙 ≥16px；
   
而 half 档抽屉顶边 = `H − round(0.45H) = 55%H`。**岛下沿要落在 60~66%H 就必然在抽屉区里面**（60%H > 55%H），两条要求在几何上互斥。

按《架构定调》§4 裁决：**peek 档取 63%±3%（主判据）；half 档以「不被 HUD 遮挡」为第一优先**（岛下沿 ≤ 抽屉顶边 −16px），同时保证岛顶 ≥ topH+8。两条数字都实测记录：

| 尺寸 | half 岛下沿/H（实测·建筑 tab） | 与抽屉顶边间隙（实测） | 60~66% 目标是否可达 | 裁决判据 | 裁决结果 |
|---|---|---|---|---|---|
| 390×844 | 52.93% | +17.24px | 不可达（55% < 60%） | ≥16px | PASS |
| 320×568 | 51.91% | +17.14px | 不可达 | ≥16px | PASS |
| 414×896 | 53.10% | +17.20px | 不可达 | ≥16px | PASS |
| 430×932 | 53.24% | +16.80px | 不可达 | ≥16px | PASS |

结论：half 档**不追求** 60~66%（物理上不可能），只用「间隙 ≥16px + 岛顶不压顶栏」验收；peek 档才是 60~66%（目标 63%）的落点。实测 half 间隙 16.80~17.24px（建筑 tab）/ 16.79~16.93px（街区 tab）= 按「候选地块可见」最坏情况 + 1px 安全量求解，两条都稳在 16px 以上。

---

## 5 遗留 / 风险（如实登记）

1. **已解决（12:56 构建）**：
   - peek 320×568 曾 66.69%（超上限 0.69pp）/ 一度 59.30%（候选地块最坏情况过度上推）→ Lead 改为「候选隐藏 / 可见」两套 peek 解，现 62.76~62.84% 全 PASS；
   - half 430×932 曾差 0.18px（求解用真实顶点轮廓、验收用 Box3 AABB）→ Lead 把 `targetHalf` 收到 `drawerTopHalf − 17`，现 16.80~17.24px 全 PASS；
   - 焦点偏差曾 +4.3%H（compose=0）→ app 特写稳定后自动解 `focusCompose`，现 ≤0.2%H。
2. **本任务外、需 D4 / Lead 处理**：
   - `tests/s19-camera.test.ts §5`「focusOn 超远目标被夹到 panMax」——`focusOn` 现按 `focusPanLimit` 夹取（zoom=3 时 11.596 ≠ 旧 panMax 5.649），需 D4 更新口径（`node tools/test-s19-node.mjs` 现 24/25）；
   - `test/t-s20-camera.mjs` 56/57：唯一 FAIL = `S20-K01 内部包版本 0.3.4`（本树构建 `VERSION=0.3.5-dev`，树级既有、与相机无关；K02 指纹三组 OK、A~J 全 PASS）；版本串不许改 ⇒ 需 D4/Lead 裁决把 K01 改新口径（或接受 56/57 并注明旧值）。
3. **口径备注**：`islandBoxScreen()` 的 AABB 比真实轮廓保守（底部约 0.2px），half 间隙按保守值验收，实际观感只会更松；`focusCompose` 自动求解发生在特写稳定后一次性执行，若以后加「特写中切换目标楼」需重新触发。

## 6 证据与复现命令

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm035
node tools/build-web.mjs --internal          # 改了 src 必须重建（本表实测基于 12:50:14 构建）
node test/t-s32-camera.mjs                   # 51/51 相机纯逻辑（另有 exit code）
node tools/s32-measure.mjs --label final --out /tmp/s32/d3-measure.json   # 四尺寸 headless 实测（默认 390/320/414/430，含街区 tab half）
node test/t-drawer-framing.mjs               # 48/48（framing 三档未被取景偏移污染）
node tools/test-s20-node.mjs                 # 32/32（S-20 相机纯逻辑）
node test/t-s20-camera.mjs                   # 56/57（唯一 K01 版本号，见 §5.4）
npm run typecheck                            # exit 0
```

产出文件：
- `src/render/camera.ts`（唯一 src 改动）
- `test/t-s32-camera.mjs`（51 断言，JSON：`/tmp/s32/d3-camera.json`）
- `tools/s32-measure.mjs`（四尺寸 headless 实测 + 街区 tab half + compose 交叉探针，JSON：`/tmp/s32/d3-measure.json`）
- 本文件 `tasks-out/S-32/取景实测.md`
