crearte-monorepo/docs/specs/2026-10-03-p15b-bootstrap-dark-design.md

# P15-B 设计：bootstrap 加载屏暗色 + 对比度守卫补钉 + 死令牌清理（crearte）

- **日期**：2026-10-03
- **仓**：`crearte`（前端；`package.json` 与全部源码在 **`src/`**，不是仓根）
- **分支**：`feat/p15b-bootstrap-dark-and-guard-pins`（AGENTS.md 只允许 `{feat|fix|docs|chore}/`；本批含用户可感知的暗色改动，故用 `feat/`）
- **base**：`f823195`（master，P13 交付后的 AGENTS.md 不变量 commit）
- **维度**：用户体验 / UI 交互 + 代码优雅（USER.md 六维度循环）
- **并行**：P15-A 在 `crearte-server` 仓，两仓各自单写者 → **可同时派发**（`sdd-parallel-dispatch` §1）

---

## §0 基线（已实测，2026-10-03 13:07）

**vitest**：`Test Files 79 passed (79)` · `Tests 688 passed (688)` · Duration 44.83s。
命令：`cd crearte/src && npx vitest run`。**与 P13 交付时报的 688/79 逐字相同** → P14 未触及前端，且此后无新增测试。这是本批的比对基线。

`bootstrap/host-origin.test.ts (3 tests)` 已在 79 个文件里 → **`bootstrap/` 目录已有测试先例**，新增测试文件不属破例。

**vitest 环境**：`src/vite.config.ts` 的 `test` 段只有 `exclude: [...configDefaults.exclude, 'e2e/**']`，**无 `environment` 键** → 默认 **node**。这是 `contrast.test.ts` / `noHardcodedColor.test.ts` / `themeBootstrap.test.ts` 能用 `fileURLToPath(new URL('../..', import.meta.url))` 读源码文件的前提（**P13 教训：happy-dom 下会抛 `ERR_INVALID_URL_SCHEME`**）。本批新增的守卫**必须沿用同款写法**，不得引入需要 DOM 的断言。

**e2e**：`src/e2e/`，`playwright.config.ts` / `.noauth.` / `.stack.` 三份配置都是 `testDir: './e2e'`。`dark.spec.ts` **10 腿**（P13 交付），其中 `:100` 是 **pre-paint 归因腿**：「Vue 包被拦截时 `data-theme` 仍为 dark（证明是内联脚本而非挂载后设置）」。

---

## §1 三项改动的取证

### 1.1 改动①：bootstrap 游戏加载屏对暗色用户「白闪」

**现象**：`src/bootstrap/index.html`（虚拟模式游戏的加载屏，`<title>游戏加载中…</title>` + 进度条 + 状态行 + 错误区）把整套配色**硬编码为亮色值**，且 `localStorage` / `prefers-color-scheme` / `data-theme` / `@media` **四项全部零命中**。暗色用户启动虚拟游戏时，会在暗色页面里看到一块亮色矩形。

**它确实是用户面**（非死代码）：
- `src/vite.config.ts:21` 把 `bootstrap/index.html` 注册为名为 `bootstrap` 的**第二个 Vite 构建入口**
- `runtime/sw/router.ts:1` `export const BOOTSTRAP_PATH = '/__bootstrap'`；`sw/index.ts:211,218` 有 `redirect-bootstrap` 与离线兜底
- `runtime/host/adapters.ts:38`：`targets.push({ mode: 'virtual', url: \`${origin}/__bootstrap#${hash.toString()}\`, origin })`
- `useGameFrame.test.ts`：virtual 模式 url 形如 `http://demo.localhost:4173/__bootstrap#v=1`
- 游戏跑在**独立子域**：`runtime/host/config.ts:18` `derivePlayOrigin → ${protocol}//${16hex}.${baseDomain}`，由 `GameHost.vue` 以 iframe 嵌入

**根因不是漏改，是 P13 的令牌化只覆盖了单入口**：P13 改的是 `src/index.html`（主应用入口）+ `app/styles/main.css`（12 令牌）+ `app/` 与 `runtime/` 的 `.vue`。`bootstrap/` 是**第二个 HTML 入口**，不在任何一处覆盖范围内。
→ **教训（已入 ROADMAP 挂账）：换肤/令牌化类改动须先 `grep -n 'input' src/vite.config.ts` 枚举所有构建入口，逐个确认覆盖。单入口假设会漏掉多入口应用。**

**跨源约束（决定修法的上限）**：
- **`localStorage` 按源隔离** → bootstrap 跑在游戏子域，**读不到**主应用存在主域 `localStorage['crearte.theme.v1']` 的显式选择。主应用 `src/index.html:15-31` 的 pre-paint 脚本判定序是 `stored → prefers-color-scheme → light`（由 `themeBootstrap.test.ts` 7 腿钉住），**在子域上拿不到 `stored` 那一级**。
- **`prefers-color-scheme` 是浏览器级、不按源隔离** → 可用。
- **hash 通道已存在**：`bootstrap/main.ts:4` 就是 `const params = new URLSearchParams(location.hash.replace(/^#/, ''))`，且 `main.ts:97` 有 `fail('启动参数完整', location.href)` 说明它是必需参数集 → **主题可搭车现有 hash 通道传入，不必新建 postMessage 协议**（P15 账本 §7 原估「完整修法须 postMessage，成本更高」，**这条被证伪**）。

**🔑 架构陷阱（本批最重要的设计约束）**：`GameHost.vue:27-31` 的 `targets` 是 **`computed`**：
```js
const targets = computed<RuntimeTarget[]>(() => resolveRuntimeTargets(props.game, {
  baseDomain: config.baseDomain, protocol: location.protocol, config
}))
```
而 `useTheme.ts:51` 是模块级响应式单例 `const theme: Ref<Theme> = ref(effectiveTheme())`。

| 注入方式 | 响应式追踪 | 后果 |
|---|---|---|
| ❌ `theme: useTheme().theme.value` | **是**（读 `ref` 的 getter → computed 建立依赖） | 用户在游戏页切主题 → `targets` 重算 → **iframe `src` 变化 → 正在运行的游戏被重载**（存档/进度丢失） |
| ✅ `theme: effectiveTheme()` | **否**（`effectiveTheme()` 内部读 `localStorage` 与 `matchMedia`，都不是响应式源） | computed 不依赖主题；iframe 不重载。代价：切主题后已打开的加载屏保持旧主题，直到下次导航 |

→ **裁定用 `effectiveTheme()`**（`useTheme.ts:39` 已导出）。"游戏运行中不重载" 比 "加载屏实时跟随主题切换" 重要得多：加载屏只在**启动瞬间**可见，而重载会毁掉正在进行的游戏。**这条必须有测试钉住**（§5-T1 腿 4），否则下一个贡献者"顺手改成响应式"就会引入静默的游戏重载缺陷。

**色值映射（实测；`bootstrap/index.html` 里 8 个硬编码 hex 的令牌归属）**：

| hex | 令牌归属 | 暗色对应值 |
|---|---|---|
| `#f7f2e7` | 亮 `paper` **且** 暗 `ink`（翻转对称点） | `#17140f`（暗 paper） |
| `#141414` | 亮 `ink` | `#f7f2e7` |
| `#ffffff` | 亮 `surface` | `#221e18` |
| `#5c584d` | 亮 `ink-soft` | `#cbc4b5` |
| `#e8552f` | 亮 `accent` | `#ff7a4d` |
| `#c03a1b` | 亮 `accent-ink` | `#ffb59a` |
| `#a3a3a3` | ❌ **不对应任何令牌** | 见下 |
| `#f87171` | ❌ **不对应任何令牌** | 见下 |

**🔴 同批发现两条 pre-existing WCAG 违规（inline `style` 覆盖了达标的样式表值）**：

| 元素 | 样式表值（`<style>` 块） | inline `style=""` 值 | 谁生效 | 对比度（on `#f7f2e7`） |
|---|---|---|---|---|
| `#status`（`:25`） | `#5c584d` | **`#a3a3a3`** | **inline 胜**（CSS 特异性） | 样式表 **6.3586 ✅** / inline **2.2594 ❌** |
| `#error-message`（`:27`） | `#c03a1b` | **`#f87171`** | **inline 胜** | 样式表 **4.8700 ✅** / inline **2.4776 ❌** |

→ **inline 是冗余重复且用了更低的对比度**：样式表里同元素**已有达标值**，inline 属性把它覆盖成不达标的。**删掉 inline 的 `color` 声明即修复**（保留 `font-size`），达标值自动生效。这是有实测对比度支撑的一行改，**不是设计决策**（与 GameHost 亮色徽标那条不同——那条的显而易见修法已被证伪，属撞色设计决策，仍挂账）。

**暗色候选配色（8 项全部实算通过）**：

| 用途 | 暗色值 | on | 对比度 | 需 | 判定 |
|---|---|---|---|---|---|
| body 正文 | `#f7f2e7`(ink) | `#17140f`(paper) | **16.4507** | 4.5 | ✅ |
| `#status` / `pre` | `#cbc4b5`(ink-soft) | `#17140f` | **10.5847** | 4.5 | ✅ |
| `#error-message` | `#ffb59a`(accent-ink) | `#17140f` | **10.7821** | 4.5 | ✅ |
| 按钮文字 | `#17140f`(paper) | `#f7f2e7`(ink) | **16.4507** | 4.5 | ✅ |
| 进度条值 | `#ff7a4d`(accent) | `#221e18`(surface) | **6.4274** | 3.0 | ✅ |
| 进度条边框/阴影 | `#f7f2e7`(ink) | `#221e18` | **14.8468** | 3.0 | ✅ |

亮色现状（**须逐字保持不变**）：body 正文 16.5010 ✅ · `#status` 样式表 6.3586 ✅ · `#error-message` 样式表 4.8700 ✅ · 按钮 16.5010 ✅ · 进度条值 `#e8552f` on `#ffffff` = 3.6385 ✅（需 3.0）。

### 1.2 改动②：`AA_PAIRS` 补钉 `['ink', 'surface']`

**`AA_PAIRS` 现状**（`app/lib/contrast.test.ts:102`，类型 `Array<[fg: string, bg: string, note: string]>`，**10 对**，断言循环在 `:124`）：
```
['ink','paper','正文全站 亮16.50/暗16.45']            ['paper','accent-ink','badge/按钮/error toast 亮4.87/暗10.78']
['ink-soft','paper','次要文 亮6.36/暗10.58']          ['paper','success','success toast 亮4.76/暗5.81']
['ink-faint','paper','::placeholder+弱文 亮4.83/暗6.99'] ['paper','ink','.btn-ink/markdown th 亮16.50/暗16.45']
['ink-soft','surface','卡片次要文 亮7.10/暗9.55']      ['accent-ink','paper','链接 text-accent-ink 亮4.87/暗10.78']
['ink-faint','surface','卡片弱文 亮5.40/暗6.31']
['ink','highlight','alert×8/strong/选中态/::selection 亮11.30/暗4.81']
```

**缺口**：`ink on surface` **未钉**，而它是**所有未钉配对里使用面最大的**：
- `bg-surface` 全仓 **62 处**（`app/` + `runtime/` 的 `.vue`）
- 其中只有 **4 处**显式写 `text-ink-soft`（已钉）、**2 处**的 `text-paper` 属三元表达式**另一支**（P15 账本 §1 第 19 次错误：把互斥分支当同元素共现，是假阳性）
- **58 处靠继承**：全局文字色源是 `src/index.html:34` `<body class="bg-paper text-ink font-sans antialiased">` → 继承到 **`ink`**
- 实测对比度：亮 **18.4225** / 暗 **14.8468** → **必然通过 4.5**

**为什么值得钉（不是"必然通过就不用钉"）**：已钉配对里使用面最大的是 `paper on accent-ink`（14 处）。`ink on surface` 有 62 处却无守卫 → 若将来调 `--color-surface`（如暗色 `#221e18` 提亮）或 `--color-ink`，**58 处继承文字会静默回归而零拦截**。这正是 P13/P14 反复出现的形态：**守卫钉住了容易想到的，漏了使用面最大的**。

**note 文案**（体例同现有 10 条，须含用途 + 亮/暗实测值）：
```
['ink', 'surface', '卡片/表格/表单底（62 处，58 靠 body 继承）亮18.42/暗14.85'],
```

### 1.3 改动③：`--color-info` 死令牌清理

**定义**：`app/styles/main.css:12`（亮 `#2b62cc`）、`:53`（暗 `#7aa7f0`）。

**零使用**（实测）：全仓 `bg-info` / `text-info` / `border-info` / `ring-info` **零命中**；`color-info` 在整个 `src/` + `e2e/` 里**只有那两行定义**（命中数 = 2，即定义本身）。`main.css` 内 `info` 字样也只出现在那两行。

**矛盾点**：它在 `REQUIRED_KEYS`（`contrast.test.ts:75-88`，**12 项**，`info` 在**第 8 位**）里 → `it(\`${zh} 12 令牌齐备（spec §3.1(b)）\`)`（`:119`）会**在删除时变红**。**守卫在强制一个零使用的令牌存在。**

**连带面（实测清点，5 个文件，不是"顺手删两行"）**：

| 文件 | 行 | 改什么 |
|---|---|---|
| `crearte/src/app/styles/main.css` | 12, 53 | 删两行定义 |
| `crearte/src/app/lib/contrast.test.ts` | 84 | 从 `REQUIRED_KEYS` 删 `'info',` |
| 同上 | 47 | 注释「由「12 令牌齐备」断言明确报「暗色 12 令牌缺失」」→ 改 11 |
| 同上 | 74 | 注释「P13 全量 12 令牌（spec §3.1(b)）」→ 改 11 |
| 同上 | 119 | `it` 标题 `${zh} 12 令牌齐备（spec §3.1(b)）` → 改 11 |
| 同上 | 121 | 断言消息 `${zh} 12 令牌缺失: …` → 改 11 |
| `crearte/docs/CHANGELOG.md` | 14（0.26.0 段） | 「每主题 **12 个设计令牌**」→ 须说明 0.19.0 起为 11（**历史条目不改写**，改为在新条目里说明；见 D-C） |
| `wrapper/docs/specs/2026-10-03-p13-dark-mode-design.md` | 109, 155, 185, 427 | P13 spec 的 D-B「全量 12 令牌」+ 两处 `--color-info` 代码块 + §「暗色块缺失 → 「暗色 12 令牌齐备」红」→ **加 RE-PIN 标注**（同 P14 手法：保留历史决策 + 标注增订），不改写原文 |
| `wrapper/docs/ROADMAP.md` | 42（P13 行） | P13 行的「每主题 **12 个设计令牌**」→ 保留原文（历史记录），挂账里删掉「死令牌 `--color-info`」这一项（已处置） |

**✅ `LEGACY_KEYS` 不受影响**（实测）：`contrast.test.ts:197` 的九键反面钉桩是 `['paper','surface','ink','ink-soft','ink-faint','accent','accent-ink','highlight','success']`，**不含 `info`** → 删令牌**不波及** P13 那条"防后人简化回去"的钉桩。这条必须实测确认过再动手，否则会误改一处刻意保留的历史锚点。

**为什么不选"启用它"**（处置 (b)）：`success` 与 `highlight` 已覆盖 toast 与 alert 的语义需求（`paper on success` 是 success toast、`ink on highlight` 覆盖 alert×8/strong/选中态/`::selection`），`info` **无对应 UI 位置**。启用它需要新造一个 info toast 变体 = 改视觉 + 加功能，超出"代码优雅"范围，且会为一个新的 UI 元素引入新的对比度配对需要钉。**删比造便宜，且删掉的是零使用面。**

---

## §2 设计决策

| # | 决策点 | 裁定 | 依据 |
|---|---|---|---|
| **D-A** | bootstrap 主题来源 | **hash 参数 `theme` 优先 → `prefers-color-scheme` → `light`**（三级，比主应用少 `stored` 一级） | §1.1：`localStorage` 按源隔离读不到；hash 通道已存在（`main.ts:4`）；`prefers-color-scheme` 不受源隔离。**判定序必须与主应用 `useTheme.effectiveTheme()` 的后两级逐字一致**，否则同一用户在主应用与游戏加载屏看到不同主题 |
| **D-B** | 父侧注入方式 | **`effectiveTheme()` 非响应式快照**，**不得**用 `useTheme().theme.value` | §1.1 的架构陷阱：响应式会让主题切换重算 `targets` → iframe `src` 变 → **运行中的游戏被重载**。必须有测试钉住（§5-T1 腿 4） |
| **D-C** | 死令牌清理的历史条目处理 | **不改写 P13 的 CHANGELOG 条目与 spec 原文**，改为：新条目（0.27.0）说明变更 + P13 spec 加 **RE-PIN 标注块** | CHANGELOG 是发布历史，改写会让"当时交付了什么"失真。P14 已建立正确手法：保留历史决策原文 + 紧随带 ⚠️ RE-PIN 标记的增订块（全分支终审判定这是"正确的 re-pin 手法"而非自相矛盾） |
| **D-D** | 新守卫的形态 | **新增 `app/lib/bootstrapTheme.test.ts`**（源码级、node 环境、读文件文本），**不扩展 `noHardcodedColor.test.ts`** | §1.4：`noHardcodedColor` 的 `candidates()` 只收 `.vue`（`if (file.endsWith('.vue'))`），且 `maskNonTemplate()` 把 `<style>` 块整体等长空白掉 → **它从设计上无法覆盖 `bootstrap/index.html`**（HTML 文件 + 颜色全在 `<style>` 里）。扩扫描根不会有任何效果 |
| **D-E** | inline `style` 的两处违规 | **删掉 inline 的 `color` 声明**（保留 `font-size`），让样式表的达标值生效 | §1.1 实测：inline 是冗余重复且对比度更低（2.2594 / 2.4776 vs 样式表 6.3586 / 4.8700）。删 inline 即修复，**同时消除"两处定义同一元素颜色"的分歧源** |
| **D-F** | 暗色实现方式 | 在 `bootstrap/index.html` 的 `<style>` 块里用 **`html[data-theme="dark"]` 覆盖**（同主应用 `main.css:44` 的手法），**不用 `@media (prefers-color-scheme)`** | 主应用用 `data-theme` 属性驱动（`color-scheme` 也由它驱动，D-L），使"显式选择能压过系统偏好"。bootstrap 若用 `@media` 就只能跟随系统、无法接收 hash 传入的显式主题 → **两套机制会让判定序无法一致**（违反 D-A） |
| **D-G** | pre-paint 脚本形态 | **IIFE + 仅 `var`，置于 `<head>` 内、任何 CSS 与 `<body>` 之前**，逐字对齐主应用 `src/index.html:15-31` 的写法 | 主应用该形态由 `themeBootstrap.test.ts` 腿 4（"脚本在 `<head>` 内、`<body>` 之前"）与腿 5（IIFE + var）钉住，理由是 CSP 落地前不能用 module/let。**同款形态让两处可被同一套守卫断言** |
| **D-H** | 派发形态 | **一个实现者子代理**做完 T1→T4（同动 crearte 单一工作树与 git index） | AGENTS.md / `sdd-parallel-dispatch` §1「一仓一写者」；P12/P13/P14 同款 |

### §2.1 被否方案

| 方案 | 否决理由 |
|---|---|
| **A：用 `@media (prefers-color-scheme: dark)` 实现 bootstrap 暗色** | 只跟随系统偏好，**无法接收 hash 传入的用户显式选择** → 显式设了暗色但系统是亮色的用户仍看到亮色加载屏。且与主应用的 `data-theme` 机制分叉，判定序无法逐字一致（违反 D-A）。这是 P15 账本 §7 原估的"廉价修法"，**取证后判定不够** |
| **B：postMessage 传主题** | hash 通道已存在（`main.ts:4`），无需新协议。postMessage 是**异步**的，而加载屏是 pre-paint → 会先绘亮色再翻暗色，**正是要消除的白闪**。`host-origin.ts` 的信令通道用于安装进度上报，时序上不适合主题 |
| **C：给 bootstrap 也读 `localStorage`** | 源隔离，物理上读不到主域的值（`derivePlayOrigin` → 独立子域）。若为绕过而放宽子域隔离，会破坏 P11 的安全模型 |
| **D：扩展 `noHardcodedColor` 的扫描根到 `bootstrap/`** | §1.4：`candidates()` 只收 `.vue`、`maskNonTemplate()` 会空白掉 `<style>` 块 → 扩根**扫不到任何东西**，且会给人"已覆盖"的假信心（P13 审查者 M5 的同族形态：扫描根改坏后"扫 0 文件也报 0 违规"） |
| **E：把 bootstrap 的配色改成引用 `var(--color-*)` 令牌** | 令牌定义在 `app/styles/main.css`，**bootstrap 是独立入口、不加载主应用 CSS**（它只有自己的 `<style>` 块）。要引令牌就得把整个 `@theme` 块复制进 bootstrap = 两处调色板需要同步维护，比硬编码更糟。故 bootstrap **刻意**保持自包含的 hex 值，由新守卫钉住两主题的值与主应用调色板一致 |
| **F：一并修 GameHost 亮色徽标 WCAG 3.26** | 属**设计决策**而非一行改：亮色 `accent` vs `accent-ink` 仅 **1.4943**，徽标与「加载失败」状态点同屏共存于展柜标题栏，改成 `bg-accent-ink` 会把两个语义压成一个视觉信号（已实测证伪显而易见修法，ROADMAP `9965fd7` 已登记约束）。仍需挂账 |

### §1.4 `noHardcodedColor` 为何无法覆盖 bootstrap（D-D 的依据，逐字取证）

```js
// app/lib/noHardcodedColor.test.ts:23-45
const SRC_ROOT = fileURLToPath(new URL('../..', import.meta.url))
// 终审 N4：扫描根必须含 `runtime/`。…实测 runtime/ 当前零硬编码 hex，扩根不会立刻红。
const SCAN_ROOTS = [join(SRC_ROOT, 'app'), join(SRC_ROOT, 'runtime')]

function candidates(): string[] {
  const files: string[] = []
  for (const root of SCAN_ROOTS) {
    for (const file of walk(root)) {
      if (file.endsWith('.test.ts')) continue
      if (file.endsWith('.vue')) files.push(file)     // ← 只收 .vue
    }
  }
  return files
}
function maskNonTemplate(content: string): string {
  const blank = (block: string): string => block.replace(/[^\n]/g, ' ')
  return content
    .replace(/<!--[\s\S]*?-->/g, blank)
    .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, blank)   // ← <style> 块整体空白
    .replace(/<(textarea|title)\b[^>]*>[\s\S]*?<\/\1>/gi, blank)
}
```
→ 两道过滤各自都足以排除 `bootstrap/index.html`：**扩展名不是 `.vue`**，且**颜色全在 `<style>` 块内**（会被 `blank` 掉）。该守卫的设计目标是"禁止在 `.vue` **模板**里用 `bg-[#…]` 形态的硬编码 hex"（文件头注释原文），HTML 入口的 `<style>` 块本就不在其范围内。

---

## §3 实现要求

### 3.1 改动① bootstrap 暗色（`src/bootstrap/index.html` + `src/runtime/host/adapters.ts` + `src/runtime/host/GameHost.vue`）

**(a) `bootstrap/index.html` 的 `<head>`**：在 `<style>` **之前**插入 pre-paint 脚本，逐字对齐主应用形态（D-G）：
```html
<meta name="color-scheme" content="light dark" />
<meta name="theme-color" content="#F7F2E7" />
<!-- P15-B D-A/D-G：加载屏 pre-paint 主题脚本。必须在 <style> 与 <body> 之前，否则暗色用户每次启动游戏都闪白。
     判定序比主应用少 stored 一级（游戏跑在独立子域，localStorage 按源隔离读不到主域的 crearte.theme.v1）：
     hash theme → prefers-color-scheme → light。后两级与 useTheme.effectiveTheme() 逐字一致，
     一致性由 app/lib/bootstrapTheme.test.ts 钉住（改一处必须改另一处）。 -->
<script>
  (function () {
    try {
      var params = new URLSearchParams(location.hash.replace(/^#/, ''))
      var hashTheme = params.get('theme')
      var theme =
        hashTheme === 'light' || hashTheme === 'dark'
          ? hashTheme
          : window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
            ? 'dark'
            : 'light'
      document.documentElement.setAttribute('data-theme', theme)
      var meta = document.querySelector('meta[name="theme-color"]')
      if (meta) meta.setAttribute('content', theme === 'dark' ? '#17140f' : '#f7f2e7')
    } catch (e) {
      document.documentElement.setAttribute('data-theme', 'light')
    }
  })()
</script>
```
⚠️ **白名单校验必须与主应用同款**（`=== 'light' || === 'dark'`），不得放宽成"任意 truthy"——`themeBootstrap.test.ts` 腿 3 正是为此存在（P13 finding #2 / N2：垃圾 `stored=neon` 必须被忽略）。

**(b) `<style>` 块**：加暗色覆盖块（D-F），值取 §1.1 的暗色调色板；`color-scheme: dark` 随块声明一次（同 `main.css:57` 的手法与理由）。**亮色值逐字不变**。

**(c) 两处 inline `style`**（D-E）：`:25` 删 `color:#a3a3a3`、`:27` 删 `color:#f87171`，各保留 `font-size`。删后由 `<style>` 块的 `#status`(`#5c584d`) 与 `#error-message`(`#c03a1b`) 生效 → 对比度 6.3586 / 4.8700 达标。

**(d) `adapters.ts:10,37-38`**：`resolveRuntimeTargets` 的 `opts` 加**可选**键 `theme?: 'light' | 'dark'`；仅当 `opts.theme` 存在时 `fragment.theme = opts.theme`（**不加就不写这个键**，保持 external/hosted 模式的 url 完全不变）。
```ts
export function resolveRuntimeTargets(game: Game, opts: {
  baseDomain: string; protocol: string; config?: ReturnType<typeof runtimeConfig>; theme?: 'light' | 'dark'
}): RuntimeTarget[] {
```
⚠️ **必须可选**：`adapters.test.ts` 有 4 处调用不带 `theme`，且 `useGameFrame.test.ts` 也 import 了 `RuntimeTarget` 类型 → 加必填键会破既有测试（违反"既有测试修改数 = 0"）。

**(e) `GameHost.vue:27-31`**：注入非响应式快照（D-B）：
```js
import { effectiveTheme } from '../../app/composables/useTheme'
const targets = computed<RuntimeTarget[]>(() => resolveRuntimeTargets(props.game, {
  baseDomain: config.baseDomain, protocol: location.protocol, config, theme: effectiveTheme()
}))
```
⚠️ **不得写成 `useTheme().theme.value`**（会让 computed 依赖 theme ref → 主题切换重载 iframe）。注释须写明这个陷阱，否则下一个贡献者会"顺手改成响应式"。

### 3.2 改动② `AA_PAIRS` 补钉（`src/app/lib/contrast.test.ts:102-113`）

在 `['ink','highlight',…]` 之后（或按现有分组习惯置于 `surface` 两对之后）插入：
```ts
  ['ink', 'surface', '卡片/表格/表单底（bg-surface 62 处，58 靠 body 继承 text-ink）亮18.42/暗14.85'],
```
**不得改其它 10 对**（它们的 note 里带实测值，是 P13 交付的一部分）。

### 3.3 改动③ 死令牌清理（5 文件，见 §1.3 连带面表）

- `main.css:12`（亮）与 `:53`（暗）删两行 `--color-info`
- `contrast.test.ts`：`REQUIRED_KEYS` 删 `'info',`（`:84`）+ 四处 "12 令牌" 文案改 "11 令牌"（`:47,74,119,121`）
- ⚠️ **`LEGACY_KEYS`（`:197`）不动**（九键不含 `info`，已实测）
- P13 spec 加 RE-PIN 标注块（D-C，不改写原文）
- crearte CHANGELOG **不改写 0.26.0 条目**，在 0.27.0 新条目里说明

### 3.4 不得触碰

- `themeBootstrap.test.ts`（主应用 pre-paint 守卫，7 腿）——除非某腿因本批变红，那时**停下来报告**
- `noHardcodedColor.test.ts`（D-D：扩它无用）
- `useTheme.ts`（`effectiveTheme()` 已够用，改它会波及主应用 10 腿 e2e）
- `src/index.html`（主应用入口，P13 交付）
- 任何既有 `*.test.ts` / `e2e/*.spec.ts`
- `crearte-server`、`crearte-deploy`、wrapper 的 `docs/`（实现者红线；wrapper 的 spec/CHANGELOG/ROADMAP 由**控制者**记账）

---

## §4 边界

| 项 | 在范围内 | 不在范围内 |
|---|---|---|
| 文件 | `bootstrap/index.html`、`runtime/host/adapters.ts`、`runtime/host/GameHost.vue`、`app/lib/contrast.test.ts`、`app/styles/main.css`、**新增** `app/lib/bootstrapTheme.test.ts` | 其它 `.vue` / `useTheme.ts` / `themeBootstrap.test.ts` / `noHardcodedColor.test.ts` |
| 主题 | bootstrap 加载屏的两态 | GameHost 展柜框架本身（它吃主应用令牌，已正确跟随暗色；其亮色徽标 3.26 属设计决策，挂账） |
| 守卫 | 新增 bootstrap 主题一致性守卫 + `AA_PAIRS` 补一对 | 改既有守卫的断言语义 |
| 令牌 | 删 `--color-info` | 新增任何令牌 |
| 行为 | 加载屏配色 + hash 多一个可选键 | 任何游戏运行时行为、SW 路由、bundle 解密 |

**挂账**（本批发现但刻意不做）：GameHost 亮色徽标 WCAG 3.26（设计决策，撞色约束已登记 ROADMAP `9965fd7`）· 第三态"恢复跟随系统"（P13 spike 3 已证伪：header 在 @320px 最坏格无像素容纳带标签控件）· CSP 落地时 bootstrap 内联脚本也需 `nonce`（与主应用同批处理）· SFC `<style>` 块内硬编码 hex 守卫不覆盖（P13 accepted：`app/` 无 `<style>` 块）。

---

## §5 测试计划

### T1 —— 守卫先行（**RED 先行**）：新增 `app/lib/bootstrapTheme.test.ts`

源码级守卫，**node 环境**（§0：vitest 默认 node，沿用 `fileURLToPath(new URL('../..', import.meta.url))` 读文件，与 `contrast.test.ts` / `themeBootstrap.test.ts` / `noHardcodedColor.test.ts` 同款）。

读三个文件：`bootstrap/index.html`、`app/composables/useTheme.ts`、`app/styles/main.css`。

**腿清单**（每条都要有 mutation 证明有牙）：

| # | 断言 | 钉什么 | mutation（应变红） |
|---|---|---|---|
| 1 | bootstrap 的 `<head>` 内有 pre-paint 脚本，且在 `<style>` 与 `<body>` **之前** | D-G 的 pre-paint 位置（否则暗色用户每次启动闪白） | 把 `<script>` 移到 `<style>` 之后 |
| 2 | bootstrap 判定序 = **hash theme → prefers-color-scheme → light**，且用 `indexOf` 比较三者位置 | D-A 的判定序 | 交换 hash 与 prefers 的先后；或删掉 light 兜底 |
| 3 | bootstrap 用**白名单**校验 hash theme（只接受 `light`/`dark`） | 防"任意 truthy"放宽（P13 finding #2 / N2 的同族） | 改成 `hashTheme ? hashTheme : …` |
| 4 | 脚本是 **IIFE 且只用 `var`**（无 `let`/`const`/箭头函数/`import`） | D-G 的 CSP 前形态 | 把 `var` 改成 `const` |
| 5 | **`GameHost.vue` 注入的是 `effectiveTheme()` 而非 `useTheme().theme.value`** | 🔴 **D-B 的架构陷阱**（响应式会让主题切换重载运行中的游戏） | 改成 `theme.value` → 必须红 |
| 6 | bootstrap 暗色块的 hex 值与 `main.css` 的 `html[data-theme="dark"]` 调色板**逐值一致**（`paper`/`surface`/`ink`/`ink-soft`/`accent`/`accent-ink` 六个） | D-E 方案否决理由：bootstrap 自包含 hex，故须钉"两处调色板不分叉" | 把 bootstrap 暗色 `--paper` 改成别的值 |
| 7 | bootstrap 亮色值**未被改动**（钉 §1.1 表的六个亮色 hex 仍在） | 防"顺手把亮色也改了"（本批只加暗色） | 改一个亮色值 |
| 8 | `bootstrap/index.html` 内**不存在 inline `style` 里的 `color:`**（D-E 的回归钉桩） | 防 inline 违规复发（本批刚删两处 2.2594 / 2.4776） | 加回 `style="color:#a3a3a3"` |
| 9 | **前提检查**：扫描到的文件数 ≥ 3 且 bootstrap html 长度 > 500 | 防"读 0 文件也报 0 违规"的假信心（P13 审查者 M5/M6、P14 终审者 R0 的同族教训） | 把路径改成不存在的文件 |
| 10 | `AA_PAIRS` 含 `['ink','surface']` 且 `REQUIRED_KEYS` **不含** `info`、长度为 **11** | 改动②③ 的回归钉桩 | 删掉补钉的那一对；或把 `info` 加回 |

**RED 相位要求**：T1 在 T2/T3/T4 之前提交时，`npx vitest run app/lib/bootstrapTheme.test.ts` 必须**红**，且**至少腿 1/2/5/6/8/10 红**（bootstrap 还没有脚本、没有暗色块、GameHost 还没注入、AA_PAIRS 还没补、info 还在）。腿 7/9 应当**已绿**（亮色值本来就在、文件本来可读）——**这是有意的**：它们是本批的"不得回退"钉桩，不是新功能的断言。实现者须把 RED 输出**逐字存证**到 `.superpowers/sdd-p15b/impl-evidence/t1-red.txt`，并**逐腿标注红/绿**。

⚠️ **恒真/恒假审视（P13/P14 累计教训，每条腿都要过）**：
- 腿 2 用 `indexOf` 比较位置时，**若某个 `indexOf` 返回 -1（未找到），`-1 < 任何正数` 会让顺序断言恒真** → 必须先断言三者都 `> -1`（`themeBootstrap.test.ts:42-44` 正是这么写的，照抄这个手法）
- 腿 6 的"逐值一致"**不得写成 `max(a,b) ≥ k` 形态**（P13 的恒真高发区：互补两侧有非平凡下界）；应写成**字符串相等**
- 腿 10 的长度断言须是 `toBe(11)` 而非 `toBeGreaterThanOrEqual(…)`（后者在删令牌后仍绿 = 无牙）

### T2 —— 改动②③（守卫腿 10 由红转绿）

按 §3.2 / §3.3 执行。**完成后 `npx vitest run` 必须 79 文件 / 688+N 测试全绿**（N = T1 新增的腿数），且**既有测试文件零修改**。

⚠️ 改动③会让 `contrast.test.ts` 的 `it` 标题从 "12 令牌齐备" 变 "11 令牌齐备" → **测试名变了但文件是"修改"而非"新增"**。这是**唯一被允许的既有测试文件修改**，且必须在报告里显式声明（同 P14 的 `architecture_test.go` 例外处理）。除此之外 `--diff-filter=M -- '*_test.ts'` 必须为空。

### T3 —— 改动①（bootstrap 暗色 + hash 注入）

按 §3.1 执行。完成后：
- `npx vitest run` 全绿
- `npm run typecheck`（`vue-tsc --noEmit`）零错
- `adapters.test.ts` 的既有 4 处调用**零修改**仍绿（验证 `theme` 是可选键）

### T4 —— e2e 与构建产物验证

1. `npm run build`（含 `vue-tsc --noEmit` + `vite build` + `build-runtime.mjs`）exit 0
   ⚠️ **`npm run build` 会类型检查 `e2e/*.spec.ts`**（P13 spike 6 曾因此 `BUILD_EXIT=2`）
2. `npm run e2e` 主套件 **102+1skip** 基线不回退（P13 交付值；`dark.spec.ts` 10 腿须全绿）
3. **新增 e2e 腿**（`dark.spec.ts` 或新文件）：暗色 + 虚拟游戏页 → 断言 iframe 的 `src` hash 含 `theme=dark`。**若 e2e fixture 无虚拟游戏可跑，改为 vitest 腿**（挂 `GameHost` 用 `@vue/test-utils`，断言 `targets[0].url` 含 `theme=dark`）——由实现者按 fixture 实际情况定，但**必须有一腿覆盖 hash 注入**，否则改动①的父侧无守卫。
4. **产物验证**（P13 教训：源码级守卫不等于产物正确）：`dist/` 里 bootstrap 入口的 HTML **含暗色块**、**不含** `#a3a3a3` 与 `#f87171`（已删的 inline 违规值）；主应用 CSS 里 `--color-info` **零命中**、`var(--color-*)` 计数与 P13 交付值（75）比对并解释差异（删一个令牌应使计数变化，须说明）。
   ⚠️ **产物 grep 用 `grep -F` 不手写转义**（P13 教训：`.backdrop\:bg-scrim` 手写反斜杠转义对 minified 产物假阴性；AGENTS.md 已立不变量）

### mutation 自查（实现者必做并附输出，每条测"预期红 + 其余绿 + 恢复证明"）

- (a) 把 bootstrap 的 pre-paint `<script>` 移到 `<style>` 之后 → 腿 1 红
- (b) 交换 hash theme 与 `prefers-color-scheme` 的判定先后 → 腿 2 红
- (c) 把 hash theme 校验放宽成 `hashTheme ? hashTheme : …` → 腿 3 红
- (d) `GameHost.vue` 改用 `useTheme().theme.value` → 腿 5 红（**这条是 D-B 的牙**）
- (e) 改 bootstrap 暗色的一个 hex → 腿 6 红
- (f) 加回 `style="color:#a3a3a3"` → 腿 8 红
- (g) 从 `AA_PAIRS` 删掉补钉的 `['ink','surface']` → 腿 10 红
- (h) 把 `info` 加回 `REQUIRED_KEYS` → 腿 10 红
- (i) **把守卫的文件路径改成不存在的文件** → 腿 9 红（防"读 0 文件报 0 违规"）
- (j) **删掉 `main.css` 的暗色块**（模拟"P13 成果回退"）→ 腿 6 或 `contrast.test.ts` 的暗色腿红

每次 mutation 后**只回滚触及的文件**（`git checkout -- <file>`，**绝不用 `git checkout -- .`**——P14 控制者第 24 次自伤：全量回滚抹掉了未提交的守卫编辑，导致后续各轮全在测没有修复的树），并核 `git diff` 空 + 守卫文件腿数不变。

### 结构指标（交付时须报实测数字）

| 指标 | 基线 | 目标 |
|---|---|---|
| vitest 文件数 / 测试数 | **79 / 688** | **80 / 688+N**（N = T1 腿数，≥10） |
| 既有 `*.test.ts` 修改文件数 | — | **1**（仅 `contrast.test.ts`，且仅因 "12 令牌"→"11 令牌" 文案；须在报告显式声明） |
| `AA_PAIRS` 对数 | 10 | **11** |
| `REQUIRED_KEYS` 项数 | 12 | **11** |
| `LEGACY_KEYS` 项数 | 9 | **9**（不动） |
| `--color-info` 全仓命中 | 2（两处定义） | **0** |
| bootstrap 内 `localStorage`/`prefers-color-scheme`/`data-theme` 命中 | **0 / 0 / 0** | **0 / ≥1 / ≥1**（`localStorage` 仍须为 0：源隔离，D-A） |
| bootstrap 内 inline `style` 的 `color:` 数 | 2 | **0** |
| `typecheck` / `build` | 0 / 0 | **0 / 0** |
| 主 e2e | 102+1skip | **≥102+1skip**（新增腿另计） |

---

## §6 记账

- `crearte/docs/CHANGELOG.md` 新增 **`## [0.27.0] - 2026-10-03`**（插 `## [0.26.0]` 前）。格式：**同条目英文行紧跟中文行、无空行**；不同条目**空一行**；小节标题双语。
- wrapper `docs/CHANGELOG.md` 新增 **`## [0.3.8] - 2026-10-03`**（插 `## [0.3.7]` 前），小节 `### Done / 完成`。**与 P15-A 合并为一条还是分两条由控制者按合并时序定**（若两批同时合并，写一条含两仓的条目更清楚）。
- `docs/ROADMAP.md`：第三波表新增 **P15-B 行** + 文档索引表新增一行。**哈希引 merge commit**。挂账里删掉「死令牌 `--color-info`」（已处置）、新增「bootstrap 内联脚本的 CSP nonce」（与主应用同批）。
- P13 spec 加 **RE-PIN 标注块**（D-C：12→11 令牌），不改写原文。
- **纪律**：显式 `git add <file>`，**禁 `git add -A`**。wrapper 的 `IDENTITY.md`/`SOUL.md`/`USER.md` **绝不 stage**。

---

## §7 风险与缓解

| 风险 | 缓解 |
|---|---|
| **`theme` 键写成必填 → 破既有测试** | §3.1(d) 明令可选；`adapters.test.ts` 4 处调用零修改仍绿是验收项 |
| **🔴 注入改成响应式 → 主题切换重载运行中的游戏** | D-B + §3.1(e) 的 ⚠️ 注释 + **T1 腿 5 与 mutation (d) 专门钉这条**。这是本批最容易"顺手改错"且后果最严重的一处（用户存档丢失），且**症状只在真实使用中显现**（切主题时游戏重启），单元测试不会自然暴露 |
| **判定序与主应用分叉 → 同一用户两处不同主题** | T1 腿 2 钉 bootstrap 内部顺序；**另需一条腿比对 `useTheme.effectiveTheme()` 的后两级顺序**（`themeBootstrap.test.ts` 腿 2 的同款手法：用 `indexOf` 比较，且先断言三者都 `> -1`） |
| **bootstrap 与主应用调色板分叉**（bootstrap 自包含 hex） | T1 腿 6 逐值比对六个暗色 hex + 腿 7 钉亮色值不变。**这是 D-E 方案（引令牌）被否后的必要补偿** |
| **新守卫写成恒真** | §5-T1 的 ⚠️ 三条（`indexOf` 返 -1 时顺序断言恒真、`max(a,b) ≥ k` 形态、`toBeGreaterThanOrEqual` 无牙）+ mutation (i) 腿 9 前提检查 + (a)–(h) 逐条验牙 |
| **inline 违规复发** | T1 腿 8 + mutation (f)。**本批发现的两处是 pre-existing（P13 之前就存在），修完须有钉桩**，否则下一次改 bootstrap 又会加回来 |
| **产物与源码不一致**（源码级守卫绿但产物错） | §5-T4.4 产物验证。P13 教训：`APPLY.toString()` + `new Function` 序列化注入验证构建期烘焙是**无效手法**；必须验真实 `dist/` |
| **e2e fixture 无虚拟游戏 → hash 注入无覆盖** | §5-T4.3 给了退路（改 vitest 腿挂 `GameHost`），但**必须有一腿覆盖**，不接受"fixture 不支持所以不测" |

---

## §8 实现纪律（P11–P14 累计教训，与 P15-A spec §8 同源，前端部分加粗）

1. **不推断，只实测。** P13 控制者在勘查期栽两次（**用运行时注入验证构建期烘焙**、**用 `APPLY.toString()`+`new Function` 序列化注入**），复核期写错断言/grep/锚点 13 次。
2. **断言或 grep 返回意外值时，先怀疑自己的模式，别先宣布缺陷。** P14 任务级审查者的第一版比对脚本误报 `CoverURL` 为 CHANGED（字符串字面量里的 `//` 被当注释起点）；控制者六次因这条纪律避免假指控（含 `bg-surface=0`、`main.css 无全局色`、`七类断言=0`）。
3. **修守卫必须两方向都验**：对合法值不误红 + mutation 下不误绿。P13 控制者只验前者，交付了数学恒真的断言（`max(填充侧,边框侧) ≥ 3`，互补两侧下界 = √cr(paper,ink) = **4.0621 > 3**，50653 采样暴力验证）。
4. **全称声明需要全称范围的证据。** P14 控制者写"断言 5 是唯一能抓遮蔽的手段"被终审推翻（匿名接收者 `func (*ContentService) M()` 绕过）。**写"唯一/全部/任何"之前先枚举形态。**
5. **恒假断言与恒真断言同样无价值，且恒假更容易因"看起来严格"而通过审查。** P14 被否决的 `NumMethod()==0`（嵌入 `*T` 使方法进值+指针两个方法集，合法树上已是 22）。
6. **产物 CSS 选择器用 `grep -F`，不手写转义。** P13：`.backdrop\:bg-scrim` 手写反斜杠转义对 minified 产物假阴性；**带引号的 grep 模式对 minified 产物也假阴性**（`grep 'bg-[#]'` 匹配不到 `bg-[#123456]` 的压缩形态）。已立为 crearte AGENTS.md 不变量。
7. **源码级守卫跑 node 不跑 happy-dom。** `fileURLToPath(new URL('../..', import.meta.url))` 在 happy-dom 下抛 `ERR_INVALID_URL_SCHEME`。已立为 AGENTS.md 不变量；§0 已确认本仓 vitest 无 `environment` 键 → 默认 node。
8. **Tailwind v4 扫描全部源文件含 `.test.ts`/`.spec.ts`**：测试注释里的类名字面量会被当候选、烧死 utility 进产物。P13 实现者用拼接修对一处，控制者八分钟后在自己裁定 commit 里重新引入。已立为 AGENTS.md 不变量 §8-5b。**本批写守卫时，注释里不要出现完整的 `bg-[#…]` / `text-[#…]` 字面量**（用字符串拼接或省略号）。
9. **管道会吞掉真退出码**；**`grep -c` 输出 0 时 exit 1**，放 `&&` 链里会静默中断后续步骤（含 `git commit`）。
10. **`restore()` 只回滚 mutation 触及的文件，绝不用 `git checkout -- .`**；每轮恢复后核验守卫编辑仍在，否则 FATAL 终止。
11. **`|| echo "(zero)"` 这类兜底文本在 glob 失败时会伪装成"测量结果为零"** → 任何"零命中"结论都要先证明扫描范围非空（T1 腿 9 就是这条的机械化）。
12. **测试被迫修改 = 设计失败的信号**，除非 spec 明列例外（本批唯一例外：`contrast.test.ts` 的 "12→11 令牌" 文案）。若发现必须改其它测试，**停下来报告**。