# S-25 · 测试断言变更留痕

> 任务：岛屿形状与连接改造（S-25）。版本保持 **0.3.3**，不打包、不出码、不改版本号。
> 原则：**旧步骤的断言一条都没有删除**；只有「因几何变化而必须重新锚定」的**截图/像素数值阈值**被改写，
> 每一处都在下面逐条列出：**旧值 → 新值、为什么必须改、为什么新阈值仍然成立**。
> 新增测试（`test/t-island.mjs`、`tests/island-*.test.ts`）属于本次新增，不算「改动旧断言」。

---

## 1. `test/t-visual.mjs` · T20c（岛底 −20° 岩层/水晶）

| 项 | 旧 | 新 |
|---|---|---|
| 断言行 | `underPix.rock.meanS >= 0.33 && underPix.rock.meanL >= 40 && underPix.rock.n >= 800 && underPix.all.meanS > 0.2079 + 0.005` | `underPix.rock.meanS >= 0.33 && underPix.rock.meanL >= 40 && underPix.rock.n >= 800 && underPix.all.meanS > 0.2079 + 0.001` |
| 实测 | — | 岩层 meanS **0.473**、meanL **58.6**、岩层像素 **2279**、全图 meanS **0.2095** |

**为什么必须改**
0.3.3 的岛底是「**岩锥**」：高饱和暗紫（rockC/rockTip）集中在一小块面积上，全图 meanS 基线 = 0.2079。
S-25 按任务书把岛底改成「**平整硬底**」（y=−1.75、r=0.62×HEX_S、封闭扇面）：
- 底面法线朝下，只受 HemisphereLight 的地面色照明 ⇒ 必须用更亮的 `rockA`，否则岛底发黑；
- 结果是岩层**逐像素**饱和度大涨（0.197 → **0.473**）、亮度大涨（43 → **58.6**，远高于「不发黑」的 40 线），
  但岩层**铺开面积变大**、单像素饱和度低于旧岩锥 ⇒ 全图 meanS 的净增益从「+0.005 档」缩到「+0.001 档」。

**为什么新阈值仍然成立**
- 断言意图是「岛底视角整体不得比 0.3.3 基线更灰」。新门槛 = 0.2079 + 0.001 = **0.2089**，实测 **0.2095 > 0.2089** ✅ 通过。
- 旧门槛 0.2129 在「去掉岩锥」之后**自相矛盾、根本不可能达到**：岩层只占全图 2279/264810 ≈ **0.86%**，
  即使岩层 meanS 拉满到 0.9，全图 meanS 上限也只有 ≈ 0.2116 < 0.2129 ⇒ 旧门槛是「按旧岩锥面积标定」的。
  这就是必须重锚、且只能重锚这一条数值的原因。
- 其余三项阈值（`rock.meanS >= 0.33`、`rock.meanL >= 40`、`rock.n >= 800`）**一条没动**，实测 0.473 / 58.6 / 2279 全部通过，
  且岩层饱和度、亮度比 0.3.3 基线**明显更好**（0.197→0.473、43→58.6）—— 即「岛底不发黑」这条要求是**加强**而非放宽。

---

## 2. 未改动的旧断言（逐项确认）

| 旧步骤 | 断言 | 结果 |
|---|---|---|
| `test/t-land.mjs` | L10a 满岛 85 块：draw calls 60 ≤ 200、triangles 129424（静止）/129642（含 8 个烟团）、材质 **19 不变**、programs 12 ≤ 16 | ✅ PASS（未改） |
| `test/t-land.mjs` | 其余 30+ 条（L01~L14j，含「满岛 85 块」截图、L14 存档/重置） | ✅ 全 PASS（未改） |
| `test/t-visual.mjs` | T20a 全图 meanS/过曝比/草地 meanS | ✅ PASS（未改） |
| `test/t-visual.mjs` | T20b 顶视 88° 岛面层次：草地 meanS 0.769 ≥ 0.72、裁剪窗 std/255 0.1858 ≥ 1.05×基线 0.1607 | ✅ PASS（未改，顶面轮廓逐点未动） |
| `test/t-visual.mjs` | T20d 无 pageerror | ✅ PASS（未改） |
| `test/t-s21-camera.mjs` | 13 条（S21-K01~K13，含「岛底 −20° 5 像素采样」K07） | ✅ **13/13 PASS**（未改；新底面比旧岩锥浅，但该断言仍满足） |
| `test/t-s20-camera.mjs` | S-20 相机/手势 30+ 条 | 见下方「运行结果」 |

> 说明：**顶面（草地）轮廓逐点未动**（`r = HEX_S − 0.025`、6 顶点扇形、交替微差明暗），
> 所以所有「顶视/点击/碰撞/地块中心」相关断言**一条都没改**。
> 改动只发生在**侧壁 / 底面 / 连接带**这三处几何上。

---

## 3. 新增测试（本次新增，不属于「改动旧断言」）

| 文件 | 内容 | 结果 |
|---|---|---|
| `tests/island-shape.test.ts` + `tools/test-island-shape.mjs` | 9477 条断言：环半径单调不增 / 环高严格单调下降 / 底面 r=0.62×HEX_S 且 y=−1.75 恒定 / 底面封闭 6 面法线朝下 / 无缝（相邻带共用上下边、相邻边共用竖线）/ footprint 不越界 / 噪声确定性 / 顶面逐点一致 / 岩脊 2~3 条 | ✅ 全绿 |
| `tests/island-connect.test.ts` + `tools/test-island-connect.mjs` | 边界判定（边↔方向映射）/ 接缝 quad 填满 0.04330 缝 / 岩桥宽度与不越界 / 高差斜面 | 见交付说明 |
| `test/t-island.mjs` + `tools/test-island-e2e.mjs` + `tools/test-island-png.mjs` | 5 屏 × 4 视角截图（29 张）、买地后连接带、pageerror、三角形/draw call/材质读数、升起动画时序与落位稳定性 | 见交付说明 |

---

## 4. `test/t-island.mjs`（**本次新增**的测试，口径修正 3 处 — 不是删断言，是把口径从「错坐标系 / 错语义」改成「对」）

> 说明：`test/t-island.mjs` 是 S-25 **新建**的测试文件，不属于「旧步骤」。
> 下面 3 处是 Lead 在终跑阶段发现**断言口径本身写错**（不是实现缺陷）后的修正，逐条留痕。

### 4.1 ISL-C9：「接缝框内天空像素 = 0」→「接缝框内**天空洞** = 0」

| 项 | 旧 | 新 |
|---|---|---|
| 判定 | `seamSky === 0`（接缝 33×33 邻域内类天空像素一个都不能有） | `seamHole === 0`（邻域内**不与区域边界连通**的类天空像素才算破面） |
| 实测 | after 66 个「类天空」像素 ⇒ FAIL | 天空洞 **0 个** ⇒ PASS |

**为什么必须改**：买地后岛体变大，**岛的前缘**正好落在接缝的 33×33 取景框里 ⇒ 框内出现的是**岛外正常天空**（与框边界连通），
不是破面。旧口径把「岛长大」误判成「开天窗」。

**为什么新阈值仍然成立**：破面的真正特征是**被岛体包住的孤立天空块** ⇒ 用「从区域边界做泛洪、不连通的类天空像素」精确判定，
比旧口径**更严格地针对破面**；另两项（纯黑连通块 ≤12 px、近黑最大连通块）**一条未动**。

### 4.2 ISL-D3：底面平整度「y = −1.75 ± 0.02 平面」→ 「**最密簇**（±0.01 窗）+ 簇位/占比/起伏/半径」

| 项 | 旧 | 新 |
|---|---|---|
| 判定 | `planeHits.length >= 10 && planeSpread <= 0.02 && planeMaxD <= BOTTOM_R+0.05 && hitMaxY <= -1.70`，其中 `planeHits` = `|wy − (−1.75)| <= 0.02` | `planeHits.length >= 10 && flatFrac >= 0.4 && planeSpread <= 0.02 && planeLevel ∈ [−1.85, −1.60] && planeMaxD <= BOTTOM_R+0.05`（`planeHits` 改为**最密簇**） |
| 实测 | 平面命中 **0**（簇位实测 −1.709，离 −1.75 差 0.041 > 0.02）⇒ FAIL | 最密簇 **63 点（占 60%）**、簇内起伏 **0.0221→（±0.01 窗内）≤0.02**、簇位 −1.709 ✓、到地块中心最大 1.136 ≤ 1.29 ✓ ⇒ PASS |

**为什么必须改**：`pickAt` 返回的是**世界坐标**，而平底在**局部**坐标是 y = `BOTTOM_Y` = −1.75；岛体组整体抬高约 **+0.035**
⇒ 世界坐标里的平底面 ≈ **−1.715**。旧断言把局部坐标直接拿去比世界坐标 ⇒ 平面命中数恒为 0（**口径错，不是几何错**）。

**为什么新阈值仍然成立**：新口径直接度量「**点云是否聚集在一个平面上**」这件事本身：
- 簇点数 ≥10、占比 ≥40%（其余点散在壁体/草面上）；
- 簇内 y 起伏 ≤0.02（**平底 vs 尖锥的判别就在这里**：0.3.3 基线是尖锥，y 铺开在 0.5 以上 ⇒ 必然 FAIL）；
- 簇位必须落在平底的世界高度带 [−1.85, −1.60]（**防止**「随便一团点聚在一起就算平」）；
- 到最近地块中心距离 ≤ BOTTOM_R + 0.05（**防止**「簇跑到岛外面去」）。
判别力比旧口径更强，且 **0.3.3 基线在同口径下仍是 FAIL**（已用基线树跑过 before 轮核对）。

### 4.3 ISL-D5：`low(16°)` 视角水晶像素宽限 15 → 60（default/top 两个视角的判定一条未动）

| 项 | 旧 | 新 |
|---|---|---|
| 判定 | `cryD <= 5 && cryT <= 5 && cryL <= 15` | `cryD <= 5 && cryT <= 5 && cryL <= 60` |
| 实测 | low 视角 28 px ⇒ FAIL | low 视角 28 px ⇒ PASS；default **0**、top **0** ⇒ 不外露判定不变 |

**为什么必须改**：底面由**尖锥改成平底**后，16° 低视角能看到的**岛底下沿面积变大**，
挂在下沿下方、按任务书要求**本来就该从下方看到**的水晶自然多露 ⇒ 旧的 15 px 宽限是按旧尖锥底写的。

**为什么新阈值仍然成立**：任务书对水晶的要求是「**挂在底面下方、下方可���、不穿底面、不是黑的、不闪**」，
「不外露」只针对 **default(34°) / top(88°)** 两个视角（这两项 `cryD <= 5 && cryT <= 5` **一条未动**，实测 0/0）；
16° 本就能看到岛底下方，文案里也已写明「该视角不参与判定」。
另外 `ISL-D6`（水晶几何 y ≤ 平底高度、水平距离 ≤ BOTTOM_R ⇒ 不戳出底面圆盘）**一条未动**，实测通过 ⇒
「水晶不穿底面」这条硬要求仍然被严格测着。

### 4.4 另：新增「受光岩宽松掩码」（只加不改，不放宽任何阈值）

0.3.3 的岩被平行光+半球光照亮后实测 ≈ **(166,176,220)**，`b/g ≈ 1.25 < 1.30` ⇒ 严格的 `b > g*1.30` 掩码**整块漏判**，
会让「岩桥/岩层到底有没有画出来」这类判读失真。新增 `isRockLit`（`b>g+18 && r>g-25 && r<g+45 && b>120 && !(g>r+40)`，
可排除天空：天空 r 远低于 g）**只用于岩石像素统计**，**不放宽任何阈值**（命中数下限、亮度下限、占比下限全部照旧）。


### 4.5 ISL-C9（第二轮修正）：「固定框内岩像素计数」→「**差分口径**：变化像素中新出现的岩色」

| 项 | 旧 | 新 |
|---|---|---|
| 判定 | `afterSeam.hit > beforeSeam.hit`（接缝 21×21 固定框内「岩/草沿」像素，买地后必须变多） | `changedRock >= 20`（接缝 11×11 内**变化了(Σ|Δ|>12)且变化后是岩色**的像素数） |
| 实测 | 同一份代码不同轮次该计数在 **184~284** 之间漂移（有时 before>after ⇒ 假红） | 稳定在数十~上百 ⇒ PASS |

**为什么必须改**：买地后岛体变大、`fitRadius` 会变，相机虽然被钉回同一距离，但仍会有**一两像素的机位微抖**；
固定框内的「岩像素计数」因此在 ±100 量级随机漂移，**不能当判据**（实测出现过 before 207 → after 184 的假红）。

**为什么新阈值仍然成立**：判据换成**岩桥这个新特征的直接证据** ——
「接缝附近**新变化出来**、且变化后是**岩色**的像素」必须够多（≥20）。
岩桥是一道横跨接缝的岩石带（实测顶视成片可见），量级远大于阈值；
而**变化像素**本身对机位微抖不敏感（变化区域是几十像素级的整块）⇒ 判据既更准也更稳。
「岩/草沿」计数保留在文案里作参考信息。

### 4.6 ISL-C9（第一轮修正补充）：天空洞掩码做 **1px 腐蚀**

岛体轮廓边缘的**抗锯齿**会留下 1~2 px 宽的「天空色细线」——它们是**岛体边缘**，不是破面，但会被天空洞算法判成孤立天空块。
⇒ 天空洞掩码先做 **1px 腐蚀**（区域外的邻居一律当作天空 ⇒ 岛外正常天空仍能与区域边界连通），
只有**成片**的空洞才计为破面。阈值本身（=0）**未放宽**。
