# S-22C 交接收敛说明（0.3.3 主题 C · F-13「画面偏灰 → 更高饱和的卡通精致感」）

> 执行：S-22C 实施工程师（Lead）+ 2 个并行子智能体（S1 调色板 / S2 相机雾与极值 pitch）。
> 工作树：`frontend-rebuild-hm033-art/`（= 0.3.2 基线 `frontend-rebuild-hm032` 的副本，版本号保持 **0.3.2** 不动）。
> 改动边界：**只动视觉参数与相机视觉行为**；经济/存档/调试事件/玩法数值 **0 改动**；禁改文件（`world.ts`/`cloud-shape.ts`/`hexworld.ts`/`island.ts`/`props.ts`/`src/ui/**`/`src/app/**`/`src/game/**`/`package.json`/`tools/regress.mjs`/契约包）**一字节未动**；无新依赖、无联网。

## 1. 改动文件（相对 0.3.2 基线）

| 状态 | 文件 | 说明 |
| --- | --- | --- |
| 改 | `src/render/palette.ts` | 45 个既有色值键调整（新增 0 键），逐键旧→新见 §2 |
| 改 | `src/render/camera.ts` | 雾随 pitch 的 C1 缓动 + 低俯仰距离下限 0°~6° 平滑介入（端点数值不变），见 §3 |
| 改 | `test/t-visual.mjs` | **纯追加**：新增 T20a~T20d 调色端到端断言（18 → 22 条；旧断言 0 删除 0 修改）；另加 `fileURLToPath` 导入与单跑 main 守卫（便于 `node test/t-visual.mjs`） |
| 新 | `tests/view-palette.test.ts` | 130 条调色断言（逐色值/色相漂移/分层对比/不过曝/截图实测；缺外部证据 json 时截图 5 组 SKIP、exit 0） |
| 新 | `tools/test-view-palette.mjs` | esbuild 打包 → Node 执行 → 写 `evidence/view-palette.json` |
| 新 | `tests/view-camera.test.ts` | 34 条相机边界断言（雾端点/单调/无阶跃、距离下限平滑、旧常量不变） |
| 新 | `tools/test-view-camera.mjs` | 同上，写 `evidence/view-camera.json` |

> 未改：`package.json`（不新增 npm script，新增测试用 `node tools/test-view-*.mjs` 直接跑）、`tools/regress.mjs`、任何版本号/指纹文件。

## 2. 色板旧→新（45 键调整 / 新增键 0 个）

- 基线：`frontend-rebuild-hm032/src/render/palette.ts`；新值：本树 `src/render/palette.ts`。
- 总原则：**只改既有键的 hex**，整体 HSL 饱和度 +10%~25%（近灰岩石单独 +0.16~0.35 HSV-S）；大面积浅色主通道 ≤`0xF0` 防过曝；色相漂移全部 ≤5°（云底按 F-13 要求单独偏蓝紫 +10°）。
- **新增键 0 个**：palette 之外的新键无人引用（`hex.ts` 的 `BLOCK_GROUND`/`ROOF_R`/`AWN_C`、商店墙、公园均为硬编码），新增无画面效果，故不加。


### 天空/雾（1 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `fog` | `0xe3eef4` | `0xeff5f8` | 雾色去灰提亮（少灰、微偏蓝白），只微调，不偏黄/不偏蓝 |

### 草地（4 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `grassA` | `0x8ccd55` | `0x68c11f` | 草地 A：饱和度 +、明度压到 L0.44 —— 顶视时与浅色道路/地砖拉开明度差（V3 复核要求） |
| `grassB` | `0xb4e06a` | `0xa1ec32` | 草地 B：比 A 更亮黄绿（L0.555），A/B 交替的明度差拉到 0.11，顶视不死平 |
| `grassDark` | `0x5fa63e` | `0x448e20` | 暗草：压到 L0.34，与 A（0.44）/草沿（0.395）形成三级梯度，树丛/边缘更立体 |
| `grassLip` | `0x58993a` | `0x51a51f` | 草沿：L0.395，介于 A 与暗草之间，地块斜面/岛沿有清晰分界 |

### 土层/砂（4 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `sand` | `0xcaa47c` | `0xd8ab79` | 砂层：饱和度 0.42→0.55、亮度略升，海边/岛壁更暖 |
| `sandLight` | `0xdfc196` | `0xe7c699` | 浅砂：饱和度 0.53→0.62、亮度略升，与砂层形成亮带 |
| `soilA` | `0x8a5a3c` | `0x995a30` | 表土暖棕：饱和度 0.39→0.52，去掉灰土感 |
| `soilB` | `0x6f4631` | `0x734226` | 深土：饱和度 0.39→0.50，与表土拉开层次 |

### 岩石/岩锥（4 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `rockA` | `0x8d86a6` | `0x9888d3` | 岩层 A：原本近灰紫（HSL-S 0.15），提到 0.46 并提亮，岛底岩锥第一层不再发黑 |
| `rockB` | `0x6f6989` | `0x7864c9` | 岩层 B：S 0.48、L 比 A 暗 0.09，明度阶梯清楚 |
| `rockC` | `0x59537a` | `0x5740bf` | 岩层 C：S 0.50、L 再暗 0.09，逐层收深 |
| `rockTip` | `0x463f66` | `0x4b35a7` | 岩尖：S 0.52、L0.431（比旧值亮 0.10），最暗一层也可见而非黑块 |

### 水晶（2 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `crystalA` | `0x9be8ff` | `0x86ddff` | 水晶 A：色度(chroma)提高，V 保持 1.0 顶格亮度（HSL-S 已 100%，只能提色度） |
| `crystalB` | `0xffb7e8` | `0xffa3e0` | 水晶 B：同 A，粉紫水晶更艳且亮度顶格 |

### 云（1 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `cloudBottom` | `0xc9d6ee` | `0xa9b5ec` | 云底：偏蓝紫 +10°、S 0.52→0.64、L 0.861→0.794（仍 >0x9f 量级），云有体积但不变黑 |

### 建筑/道路/墙面（19 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `door` | `0x7a4a33` | `0x884828` | 门：饱和度 0.41→0.545，木门更像门 |
| `gold` | `0xf3c34b` | `0xf0c135` | 金色装饰：S 0.875→0.86、L 微降防过曝（≤0xF0） |
| `goldDark` | `0xc79a2a` | `0xd5a215` | 暗金：S 0.65→0.82，金属层次更清楚 |
| `hallRoof` | `0x2f7390` | `0x1f80ad` | 市政厅屋顶青蓝：S 0.51→0.70、亮度略升，主建筑更醒目 |
| `hallRoofDark` | `0x22566e` | `0x196385` | 市政厅屋檐暗青：S 0.53→0.68，与屋顶成明暗对 |
| `kerb` | `0xb9a98a` | `0xc5a872` | 路缘：压到 L0.61，与道路明度差 0.23，路缘线清楚（≥0.10 要求） |
| `plaza` | `0xf2e7cf` | `0xf0e2c2` | 广场铺装：饱和度 +、L0.85 保持明亮，顶视中心不灰 |
| `plazaRing` | `0xd9c9a6` | `0xd5c098` | 广场环：L0.715，与广场形成一圈深色描边 |
| `road` | `0xecdfc4` | `0xefdfbd` | 道路米白：饱和度 +、L 保持 0.839（≥0.82），与压暗的草地对比更强 |
| `roofRed` | `0xd9674a` | `0xdf5937` | 红屋顶：饱和度 +14%，卡通纯度更高 |
| `roofTeal` | `0x3f9aa0` | `0x2ba9ad` | 青屋顶：饱和度 +38%，与红屋顶形成互补色块 |
| `stone` | `0xb8b3a8` | `0xdad1bd` | 石料/地基板：原本近灰（HSL-S 0.10），提到 0.30 并提亮到 L0.80 —— 顶视建筑底板不再灰 |
| `stoneDark` | `0x8e897f` | `0xb09a6d` | 深石料：S 0.06→0.30，与石料成对 |
| `wall` | `0xf6ead2` | `0xf0dbad` | 墙面奶油色：饱和度 0.67→0.72、L0.81（不再比旧值更亮），去灰但不过曝（≤0xF0） |
| `wallShade` | `0xe3d2b0` | `0xddbf88` | 墙影：L 压到 0.70，与墙面差 0.11（≥0.09），建筑暗面/阴影更清楚 |
| `window` | `0x6aa6c8` | `0x59a1c8` | 冷窗：饱和度 0.46→0.50，玻璃更清透 |
| `windowWarm` | `0xffd98a` | `0xebc15e` | 暖窗/灯球：提高饱和度并压 V（0xFF→0xEB）防过曝 |
| `wood` | `0x9b6a45` | `0xb8702e` | 木构件：饱和度 0.38→0.60，木色更暖更纯 |
| `woodDark` | `0x6e4a31` | `0x885120` | 深木：饱和度 0.38→0.62，与木色成对 |

### 植被（7 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `flowerA` | `0xff8fa3` | `0xf47b8f` | 粉花：饱和度略提、防过曝（V 1.0→0.957） |
| `flowerB` | `0xffd447` | `0xf3ca23` | 黄花：饱和度 0.72→0.856，点缀更艳 |
| `leafA` | `0x5db04a` | `0x47a430` | 树冠 A：明度压暗 + 饱和度 +，与草地形成深浅对比（顶视层次） |
| `leafB` | `0x7cc455` | `0x61bd32` | 树冠 B：略暗更浓，与 A 交替 |
| `leafC` | `0x3f9448` | `0x278935` | 树冠 C：深绿、S 0.40→0.54，阴影面 |
| `pine` | `0x2f8a56` | `0x1f8250` | 松树：深绿提饱和，作为低多边形深色点缀 |
| `trunk` | `0x7b5436` | `0x7b4a26` | 树干：提饱和、压暗，与亮部树冠分离 |

### 水面（1 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `water` | `0x5cc3dd` | `0x4cc2e6` | 水面：S 0.655→0.755、亮度略升，池水更清蓝 |

### 角色（2 键）

| 键 | 旧 | 新 | 理由 |
| --- | --- | --- | --- |
| `ink` | `0x2a2f45` | `0x20274b` | 墨色：压暗提饱和，轮廓更干净 |
| `skin` | `0xf2c9a0` | `0xefc49c` | 居民肤色：饱和度微调保持自然 |

### 未改的 8 键

`skyTop` `0x7db4e6`、`skyMid` `0xcfe6f4`、`skyLow` `0xfbe9d2`（world.ts 硬编码天空渐变，palette 键 0 引用）、`roofMustard`、`roofPlum`、`waterEdge`（0 引用）、`flowerC` `0xffffff`、`cloudTop` `0xffffff`（允许纯白）；共 8 键未动

> 说明：`skyTop/skyMid/skyLow` 在 palette 里**无人引用**——天空渐变硬编码在 `world.ts makeSky()`（禁改），本卡只通过 `fog` 影响地平线雾色；若后续要改天空，需 `world.ts` owner 接手（移交建议值见 `palette-old-new.md`）。

### 分类理由（对应功能要求 a）

| 类别 | 做法 | 效果（实测） |
| --- | --- | --- |
| 天空/雾 | 只调 `fog` `0xe3eef4→0xeff5f8`（更亮更冷）；天空渐变不动 | 天地交界更干净、不灰 |
| 草地 | 4 键整体压暗提饱和：`grassA/grassB/Dark/Lip` HSL-L .57/.65/.45/.41 → .44/.56/.34/.38、S +0.15~0.26 | 默认视角草地 meanS 0.583→0.741；顶视 0.556→0.769；岛面不再「粉绿发灰」 |
| 建筑/道路 | 19 键：路面/广场/墙顶保持亮（L≈.84~.90）但提饱和（S +0.04~0.17）；`wallShade` 压暗拉出墙影（wall−wallShade 明度差 0.110）；屋面/木作/窗色更纯 | 顶视「道路/地砖/建筑阴影」层次更清楚：岛区灰度 std 0.1607→0.1738（×1.081）、road−grass 平均亮度差 35.5→51.4 |
| 岩石/岩锥 | 4 键色相不变、饱和度大幅提高（rockA S .15→.46、rockC .19→.50），亮度阶梯保持（A→B→C→尖） | 岛底 −20°：rock meanS 0.197→0.423、meanL 43→45（更艳且**不发黑**）；岩锥/水晶轮廓可辨 |
| 水晶 | `crystalA/B` V 已顶格 1.0，只能提色度（chroma +21%/+28%） | 岛底 crystal meanS 0.356→0.433，仍顶亮 |
| 云 | `cloudBottom` 偏蓝紫（H +10°、S 0.52→0.64、L .861→.794，仍 >0x9f 量级） | 云有体积、不变黑；云底与天空分层更清楚 |
| 植被/角色/水 | 植被同步压暗提饱和（leafA/B/C、pine、trunk），角色 `skin` 更暖、`door/gold` 微调 | 岛面绿色层次更丰富，人物不灰 |

**不过曝**：全图过曝像素占比 7/7 视角全部下降（default 0.160%→0.120%、top88 0.140%→0.120%、under20 0.110%→0.090%、320/360/414/430 也均下降）。

## 3. 相机：雾与极值 pitch（要求 d / c）

`src/render/camera.ts` 只改**视觉行为**，`CAM` 常量与 S-21 指纹锁定的 8 个读数（`-25/88/11/6/1/0.55/0.75/4.237/2.33035/3.1/5.5`）**逐位不变**：

1. `fogForPitch(pitch)` 由「线性插值」改为 **C1 两段 Hermite 缓动** `fogEase(k)`：
   - 端点不变：pitch 34°/88° ⇒ nearK=1.3、farK=3.1；pitch −25° ⇒ nearK=1.7、farK=5.5；
   - `k=(16−deg)/41` clamp[0,1]，`fogEase` 两半段 `h=x²(1−x/2)`、`h(0)=0,h'(0)=0,h(1)=0.5` ⇒ 16° 处斜率不再从 0 突跳；
   - 实测：[−25°,34°] 网格最大 `farK` 单步变化 0.0078（<0.02），farK 严格单调不增；雾 near/far 随 pitch 连续，无「突然清晰/突然模糊」。
2. `underDistBlend(pitch)`（新纯函数）：pitch≤0° ⇒ 1（沿用 S-21 的 `underMinDist=11` 防穿模）；pitch≥6° ⇒ 0（与 0.3.2 **逐位相同**）；0°~6° 用 `1−smoothstep` 平滑混合。
   - `apply()` 距离 `d = base + (max(base,11)−base)·w`；`distance/viewDistance` getter 返回实际生效距离 `this.dist`，因此 `app.ts` 的每帧雾 = `d×fogForPitch` 也连续；
   - 默认/高俯仰不受影响（S-20 零回退）；最低俯仰 `viewDistance=63.11`（同 0.3.2）。
3. 副作用说明（如实）：`distance` getter 语义由「fitDist/zoom」改为「实际生效距离」，仅在 0°~6° 与最低俯仰不同；pitch ≥6° 时两者逐位相同，S-20/S-21 既有断言全部通过（见 §5）。

## 4. 新增/受影响断言

- **新文件**：`tests/view-palette.test.ts`（130 条）、`tests/view-camera.test.ts`（34 条）。
- **旧断言零删改**：`test/t-visual.mjs` 只追加 T20a~T20d（18→22 条，`node test/t-visual.mjs` 22/22 PASS）；`tests/s21-camera.test.ts`、`tests/s20-*.test.ts`、`test/t-s21-cloud.mjs` 等**一行未改**。
- 旧断言未受影响的原因：既有视觉断言没有锁 palette 具体 hex；渲染预算 `44 calls / 46159 triangles / 11 programs / 材质 19` 与调色前逐位一致（摄像头只改雾数值不改几何）。
- **新增 T20 断言（t-visual.mjs，旧值→新值+理由，写在断言文本里）**：
  - T20a 默认 34°：全图 meanHSV-S 0.2129→0.2280、过曝 0.173%→0.118%、草地 meanS 0.584→0.809、草地 meanL 124.7→109.5；
  - T20b 顶视 88°：草地 meanS 0.552→0.773、岛区 240×170 灰度 std/255 0.1607→0.1738（×1.081，≥1.05）、亮面(道路/广场/建筑) meanL 213.4 vs 草地 125.6；
  - T20c 岛底 −20°：岩层 meanS 0.197→0.423、meanL 43→45（不发黑）、全图 meanS 0.2079→0.2171。

## 5. 测试结果（本树实跑，均 PASS）

| 命令 | 结果 | 说明 |
| --- | --- | --- |
| `npm run typecheck` | **0 错误** | tsc --noEmit |
| `npm run test:s21-camera` | **13/13 PASS** | 含 K02 默认雾 82.2/196.1、K07 岛底岩锥/水晶亮度、K10 d×1.3/3.1、K11 预算 44 calls/46159 tri/11 programs |
| `npm run test:s20` | **57/57 PASS** | 需先 `node tools/build-web.mjs` + `node tools/build-wechat.mjs`（K04 正式微信包零残留） |
| `npm run test:s21-cloud` | **8/8 PASS** | 单独跑（并发跑时 C03 单帧 alpha 0.216 会误报，见 0.3.2 既有说明；单跑 0.1188） |
| `node test/t-visual.mjs` | **22/22 PASS** | 18 条旧 + T20a~d 新 |
| `node tools/test-view-camera.mjs` | **34/34 PASS** | 雾端点/单调/最大步长/距离下限平滑/旧常量 |
| `node tools/test-view-palette.mjs` | **130/130 PASS** | 含截图实测 5 组；缺外部 `palette-stats.json` 时 SKIP 5 组、exit 0，可移植 |

> 关键数字（`evidence/view-camera.json`）：fog 端点 pitch0 `{nearK:1.3,farK:3.1}` / pitchMin `{nearK:1.7,farK:5.5}`；[−25°,34°] maxFarStep **0.0078048**；viewDistance 连续性最差 `fitR1.2/zoom3` 场景单步 0.161（旧式在 6° 门槛处 6.443 硬跳变）。

## 6. 建议 应收 登记的新 regress 步骤（`tools/regress.mjs` 由 应收 改，本卡未动）

```js
// S-22C 主题 C：调色板（旧→新 45 键 / 饱和度 / 不过曝 / 截图实测）
{ id: 'view-palette', name: 'S-22C 调色板(饱和/不过曝/截图实测)',
  cmds: [() => ['node', ['tools/test-view-palette.mjs']]],
  metric: (o) => fractionOf(o, /S-22C view-palette：(\d+)\/(\d+) 通过/) },
// S-22C 主题 C：相机雾/极值 pitch 边界
{ id: 'view-camera', name: 'S-22C 相机雾/极值俯仰边界',
  cmds: [() => ['node', ['tools/test-view-camera.mjs']]],
  metric: (o) => fractionOf(o, /S-22C 视角边界测试：(\d+) 断言全部通过/) },
```

- 新增 T20 已并入既有 **`visual`** 步骤（`node test/browser.test.mjs visual` 会跑 `test/t-visual.mjs` 的 run()），**无需另加步骤**；`view-palette`/`view-camera` 为独立 Node 步骤，预计各 +1~3 秒。
- 既有步骤号/名称不变；样例数只增不减（visual 18→22，新增两条步骤）。

## 7. 证据与交付物

- `tasks-out/S-22/art/evidence/`：`palette-stats.json`（7 视角 before/after/Δ + required 10 组）、`palette-old-new.md`（53 键全表）、14 张前后原始截图、5+2 组并排 pair、`view-matrix.json`（20 张最终截图矩阵）、`view-palette.json`、`view-camera.json`。
- 最终截图矩阵（5 屏 × 4 视角 = 20 张）：`view-<w>x<h>-(default|top|level|under).png`，同机位/冻结世界/云 t=0。
- payload：`payload.tar.gz`（由 `make-payload.mjs` 生成，相对 0.3.2 基线只含 §1 文件）+ `改动清单.md` + `删除清单.txt`。

## 8. 局限与移交建议（如实）

1. **逐地块草地 A/B 交替不存在**：当前代码 `groundOf(null)=C.grassA`，只有 ±6% 顶点哈希抖动；现有 A/B 仅用于岛沿径向分层。顶视层次靠「草地压暗 vs 亮道路/地砖/石料板/墙顶」的明度差达成（std ×1.081、road−grass 51.4），**真·棋盘交替需 `hexworld.ts` owner 接入第二色**（palette 侧 grassA/grassB 已备好）。
2. **天空调色不可达**：`skyTop/skyMid/skyLow` 0 引用，天空硬编码在 `world.ts makeSky()`；本卡只把 `fog` 改亮，若需更通透天空需 `world.ts` owner 接手（建议值 `#6fb2e8/#d6ecfb/#fdebd6`，未写入）。
3. **水晶亮度不可再提**：`crystalA/B` 是 MeshBasic 且 V=1.0，只能提色度；要发光感需 `world.ts` 加自发光，不在本卡范围。
4. **真机未验**：以上均为 Chromium(SwiftShader) 截图/像素与自动化断言，未上真机。

---

## 附：截图实测验收指标（`palette-stats.json required`）

| 指标 | 值 |
| --- | --- |
| 1_顶视岛区灰度std | {"before":0.1607,"after":0.1738,"ratio":1.0815,"target":"after ≥ before×1.05","pass":true} |
| 2a_road与grass平均亮度差 | {"before":35.5321,"after":51.2771,"target":"after ≥ before 且 ≥35","pass":true} |
| 2b_kerb与road明度差_palette_L | {"value":0.229,"target":"≥0.10","pass":true} |
| 3a_wall与wallShade明度差_palette_L | {"value":0.11,"target":"≥0.09","pass":true} |
| 3b_wall亮度不高于before_V | {"before":0.9647,"after":0.9412,"target":"after ≤ before","pass":true} |
| 4a_顶视岛区meanS | {"before":0.4426,"after":0.6089,"delta":0.1663,"target":"after ≥0.51 且 Δ≥+0.06","pass":true} |
| 4b_全图过曝比例_after不高于before | {"320x568-default":{"before":0.002,"after":0.0016,"pass":true},"360x640-default":{"before":0.0019,"after":0.0014,"pass":true},"390x844-default":{"before":0.0016,"after":0.0012,"pass":true},"414x896-default":{"before":0.0013,"after":0.001,"pass":true},"430x932-default":{"before":0.0013,"after":0.0009,"pass":true},"390x844-top88":{"before":0.0014,"after":0.0012,"pass":true},"390x844-under20":{"before":0.0011,"after":0.0009,"pass":true}} |
| 5a_岛底rock_meanS提升 | {"before":0.1972,"after":0.42269999999999996,"delta":0.2255,"target":"Δ≥+0.15","pass":true} |
| 5b_岛底rock亮度不下降 | {"before":42.6047,"after":44.902,"target":"after ≥ before","pass":true} |
| 5c_岛底crystal_meanS提升 | {"before":0.3558,"after":0.43320000000000003,"delta":0.0774,"target":"Δ≥+0.05","pass":true} |
