Merge remote-tracking branch 'origin/master' into feat/game-fork

# Conflicts: # deploy/container/nginx.conf # deploy/nginx/genarrative-dev-http.conf # deploy/nginx/genarrative.conf # server-rs/crates/api-server/src/modules/game_distribution.rs # src/components/game-distribution/GameDetailPage.tsx # src/components/game-distribution/GameDistributionPages.test.tsx # src/components/platform-entry/PlatformEntryActiveFlowShell.tsx
2026-10-06 00:19:40 +08:00
parent 126fb7bc06 51cb05f418
commit bdcefe91d1
131 changed files with 15727 additions and 5835 deletions
@@ -0,0 +1,77 @@
+# 【实施计划】AGC 运行画面点选识别 Phaser 4 与 three.js 画面上的已登记素材
+
+| 字段      | 值                                                                      |
+| --------- | ----------------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md` |
+| Status    | in-progress                                                              |
+| Owner     | omp agent（issue #612）                                                   |
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`（新增）：现有预览桥脚本（尺寸上报 + DOM 点选）整体迁入，并新增 canvas 分支与两个引擎适配器。
+- `apps/ai-game-creator-shell/src-tauri/src/preview.rs`：`PREVIEW_FIT_BRIDGE_SCRIPT` 改为 `include_str!` 引用上面的文件；注入、去重扫描、`/__genarrative/local-preview-fit.js` 路由与响应逻辑不变。
+- `apps/ai-game-creator-shell/src/features/project-workspace/runtimeInspectResourceMatch.ts`（新增）：把宿主侧「点选结果 → manifest 素材 id」的匹配抽成纯函数。
+- `apps/ai-game-creator-shell/src/view/project-development/index.tsx`：`handleRuntimeInspectSelection` 改为调用该纯函数，派发载荷结构不变。
+- `apps/ai-game-creator-shell/tests/runtimeInspectEngines.test.ts`、`apps/ai-game-creator-shell/tests/runtimeInspectResourceMatch.test.ts`（新增）。
+- `apps/ai-game-creator-shell/src-tauri/src/main.rs`：`DEFAULT_GAME_SCRIPT_JS` 补引擎句柄发布。
+- `apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/game.js`、`.../threejs-3d-starter/project/game/main.js`：补引擎句柄发布（只改本地模板源，不重新发布 zip）。
+- 文档收口：`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`（「当前已完成」清单与本里程碑证据表）、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` §3.4（如行为与草案有出入）。
+
+明确不修改：
+
+- `runtime-region` 引用契约、`genarrative.local-preview-inspect.v1` 消息版本号、`LocalGamePreviewFrame.tsx` 的解析与净化、Rust `direct_codex_user_item` 的校验口径（不新增字段；若实测必须加字段，单独评审）。
+- `packages/shared`、manifest / 版本绑定 / 素材替换链路、Runtime Prompt 文案、模板 zip 发布与线上索引（AGC 玩法 Skill 的生成期契约属阶段二，见下 `## 阶段二进展`）。
+- DOM 点选语义与 `enabled / disabled / cancelled` 协议。
+
+## 实现顺序
+
+1. **搬运桥脚本（行为零变化）**：把 `PREVIEW_FIT_BRIDGE_SCRIPT` 的字符串体原样落到 `resources/preview/local-preview-fit.js`，`preview.rs` 改 `include_str!`。跑 Rust 定向测试 + 一次真机 DOM 点选，确认尺寸上报与 DOM 点选完全不变。
+2. **拆出命中解析**：桥内把 `handleInspectMove` / `handleInspectClick` 共同的部分抽成 `resolveInspectTarget(clientX, clientY)`，返回 `{ selection, rect }`；DOM 分支逻辑等价搬运。
+3. **引擎句柄契约**：桥惰性读取 `window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game }` 或 `{ engine: 'three', THREE, scene, camera, renderer }`（`THREE` 命名空间要求见下「风险」第 2 条）；只认显式句柄，不做鸭子类型猜引擎。缺句柄或 `engine` 未知 → 走第 6 步退化。
+4. **Phaser 4 适配**：`game.input.activePointer` 取指针 → `scene.input.hitTestPointer(pointer)` 优先；无命中对当前激活场景的 `scene.children.list` 逆序（含 `depth`）用 `getBounds()` 与指针世界坐标求交兜底。素材身份：`getData('genarrativeResourceId' | 'genarrativeResourcePath')` 优先，其次 `texture.getSourceImage()` / `texture.source[].image` 的 `currentSrc || src` 与 `texture.key` + `frame.name`。矩形：`getBounds()` 世界矩形按相机换算屏幕矩形。多场景只取激活场景；全程 try/catch，任何一步抛错按"未命中"处理。
+5. **three.js 适配**：`renderer.domElement` 矩形归一化出 NDC → `new THREE.Raycaster()` + `setFromCamera` → `intersectObjects(scene.children, true)` 取最近命中。素材身份：`object.userData.genarrativeResourceId | genarrativeResourcePath` 优先，其次沿 `object.material` 的贴图槽取 `texture.image.currentSrc || texture.source.data.currentSrc`。矩形：命中对象 `Box3` 八角投影取 min/max。
+6. **退化路径**：以上任一步拿不到结果时，按现状输出（`label` = 元素/画面可得的名字，`sourcePath` / `resourceIds` 为空，矩形 = 现状 DOM 语义），不报错、不伪造 id。
+7. **宿主匹配抽纯函数**：`runtimeInspectResourceMatch.ts` 实现优先级——显式 `resourceIds`（已按 manifest 过滤）→ `sourcePath` 与 `localPath` 的精确后缀匹配 → 文件名匹配（现有口径）；序列帧 `imageSequenceFrames[].imageSrc` 参与后两档；结果去重且只保留 manifest 现有素材 id。`index.tsx` 改为调用它。
+8. **脚手架与模板句柄**：`main.rs` 默认脚本与两个模板源补发布句柄（Phaser 在 `new Phaser.Game(...)` 处持有实例；three.js 在场景装配后发布）。
+9. **真机与文档收口**：两条 smoke（见下），补「当前已完成」清单与证据表。
+
+## 验证命令
+
+1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --offline -- preview`
+2. `npx vitest run apps/ai-game-creator-shell/tests/runtimeInspectEngines.test.ts apps/ai-game-creator-shell/tests/runtimeInspectResourceMatch.test.ts apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx`
+3. `npm run agc:typecheck`（含 `check:tests:types`、`tsc`、skill-pack 指纹、包布局声明、`check-config`）
+4. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+5. 真机：`npm run agc` 拉起客户端 → 新建 Phaser 4 项目（默认脚手架）与 three.js 项目各点一次已登记素材，核对引用芯片名与载荷 `resourceIds`，并各点一次空白与 DOM HUD 确认退化与不回归。
+
+## 风险与回滚点
+
+1. **桥脚本迁移**（顺序 1）：纯搬运，但桥同时承载尺寸上报（`resolveLocalGamePreviewFitLayout` 依赖它），任何字符差异都可能表现为画面适配回归。回滚点：该步单独一次提交，红了就 revert 该提交再重做。
+2. **three.js 需要 `THREE` 命名空间**：Raycaster / Vector2 / Box3 都是模块内类，桥拿不到；从 `camera.constructor` 只能拿到相机类，因此句柄契约要求同时暴露 `THREE`。若实测希望避免暴露命名空间，退路是要求玩法暴露少量构造器（`Raycaster`）——需要改契约，先评审再动手。
+3. **Phaser 4 相机换算**：世界↔屏幕矩形依赖 4.2.1 的相机字段与缩放行为；实测不稳定时降级为"命中对象但只给点标记矩形"，不阻塞引用插入（主规范第 5 条的退化分支）。
+4. **`hitTestPointer` 只覆盖 `setInteractive()` 对象**：几何兜底必须存在，否则未开交互的精灵点不中。
+5. **three.js 递归 raycast 成本**：只在点选模式下按需执行（move 节流），不做常驻监听。
+6. **three.js 真机验收的模板来源**：本里程碑只改本地模板源，不重新发布 `template.zip`；three.js smoke 用模板工程 + 手工补一行句柄进行（句柄就是对外契约），正式"开箱可用"由下一个里程碑的模板发布覆盖。这条限制必须写进交付记录。
+7. **净化为不可绕过**：引擎档取到的 id / 路径先过既有 `sanitizeInspectResourceId` / `sanitizeInspectSourcePath` 再进载荷；宿主匹配只保留 manifest 现有 id，未知值一律丢弃（Rust 拒绝口径不变）。
+
+## 已完成
+
+- 桥脚本搬运 + 引擎档落地：桥脚本落到 `resources/preview/local-preview-fit.js`，`preview.rs` 改 `include_str!`，DOM 点选语义与协议不变，新增 canvas 引擎档。
+- 宿主匹配抽成纯函数 `runtimeInspectResourceMatch.ts`，`index.tsx` 改为调用它，派发载荷结构不变。
+- 脚手架与三个起步模板发布只读引擎句柄：`DEFAULT_GAME_SCRIPT_JS`、`phaser-2d-starter`、`threejs-3d-starter`、`blank-3d-scene`。
+- 自动化验证通过：五个前端用例文件（`runtimeInspectEngines` / `runtimeInspectResourceMatch` / `localGamePreviewFrame` / `resourceReferenceInput` / `appSurface`）292 passed / 9 skipped（301 项）；`npm run agc:typecheck` 通过；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --offline -- preview` 通过（43 passed）。
+- 分四个提交落盘：6c6850352（桥与引擎档）、6264fed6b（宿主匹配）、ab518ea57（脚手架与模板）、f729203c6（规范与踩坑）；验收证据见里程碑文档。
+
+## 阶段二进展
+
+阶段一让点选能识别素材，但可用性依赖玩法满足三条约定（发布句柄、Phaser 用 Image 装载、对象标注素材身份）；阶段二把这几条写进**生成期契约**，新生成的 Phaser 4 / three.js 项目不改代码即可点出素材。同一 PR 续推，`template.zip` 与线上索引仍未重新发布。
+
+- 主源（唯一写全契约处）：`resources/agc-skills/agc-web-game-development/SKILL.md` 新增「运行画面点选契约（运行态素材身份）」四条——发布只读引擎句柄（`{ engine:'phaser', game }` / `{ engine:'three', three: { Raycaster, Vector2, Vector3, Box3 }, scene, camera, renderer }`，three 瘦身形态见下条）、Phaser 固定 `loader: { imageLoadType: 'HTMLImageElement' }`、给素材渲染对象标注 manifest 身份（Phaser `setData('genarrativeResourceId' | 'genarrativeResourcePath', …)`，three.js `mesh.userData.…`，值只取 `agc_list_registered_assets` 的 `localAssetId` / `localPath`）、素材进 dist 走与 `localPath` 对齐的稳定路径（`public/` 原样拷贝，不用 `import` 的 hash 产物名）；并写明不满足时不报错、不伪造 id、退化为不带素材的区域引用（= 验收面）。
+- 派生副本只补指针，不复制契约：`agc-web-game-development/references/game-quality-checklist.md` 增加一条勾选项；`agc-game-production-workflow/SKILL.md` 第 4 步（Game implementation）指向该契约（新游戏编排必读）。
+- 指纹同步：`npm run agc:skill-pack:sync` 更新 `resources/agc-skills/manifest.json` 的 `version` 与两个 skill 的 `sha256`；`skill_pack.rs` 逐文件 `include_bytes!`，因此**未新增 skill 文件、未改任何 Rust**。
+- 验证：`npm run agc:typecheck`（含 skill-pack 指纹校验）、`node scripts/check-doc-index.mjs`、`npm run check:encoding`、`git diff --check` 全部通过（退出码与结论行见 PR 评论）。
+- 冻结面不变：`preview.rs`、`resources/preview/local-preview-fit.js`（sha256 仍为 `6276ac48…917a`）、宿主匹配、脚手架与模板源均未改；未合并主线。
+- 可见性补强 + 句柄瘦身：桥端 three 句柄改推荐瘦身形态 `three: { Raycaster, Vector2, Vector3, Box3 }`（旧 `THREE` 命名空间仍兼容读取，缺任一构造器按未命中退化），并补 label 兜底——three `object.name` → `geometry.type` → `object.type`、Phaser `texture.key` → `name` → `type`，命中对象但取不到素材身份时芯片不再一律是 `@canvas`；契约文本、`threejs-3d-starter` 与 `blank-3d-scene` 模板同步瘦身（整命名空间实测把 517,682 B 的构建撑到 730,831 B，+41%）。
+- 该轮验证：`tests/runtimeInspectEngines.test.ts` 33 例（新增 6 例：瘦身句柄、旧命名空间兼容、name / geometry.type / object.type 兜底、缺构造器退化）；真实 Chromium + 真实 three 0.184 + 真实桥脚本实测 slim 句柄命中、`Crate` / `SphereGeometry` / `LegacyMesh` 三种芯片名与对象区域矩形；`agc:typecheck`、`check-doc-index`、`check:encoding`、`git diff --check` 通过。
+- 真机复验（待执行）：环境已就绪——客户端从本分支源码编译启动（`npm run agc` → `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`，Vite `127.0.0.1:3080`）、exe 内已核实内嵌新桥（6 处新代码标记：`handle.three || handle.THREE`、`inspectObjectLabel` 及其 4 个调用点）、CDP `http://127.0.0.1:9222` 可用（`Edg/154.0.4258.53`，page target 为 `陶泥儿 @ 127.0.0.1:3080`）。**点选复验待执行**：客户端登录态已过期（localStorage 里唯一 access token `exp=2026-10-01T08:24:51Z`），UI 停在登录页，需人工登录后才能打开 `gameagent-73ab2832` 进「运行」页挑选；未取得芯片文本 / 高亮矩形 / iframe 内句柄，不写"已完成"。
@@ -0,0 +1,61 @@
+# 【里程碑】AGC 运行画面点选识别 Phaser 4 与 three.js 画面上的已登记素材
+
+| 字段        | 值                                                       |
+| ----------- | -------------------------------------------------------- |
+| Version     | 1.0                                                       |
+| Status      | in-progress                                               |
+| Date        | 2026-10-04                                                |
+| Parent Spec | `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`「运行画面素材点选」、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` §3.4 |
+
+## 目标
+
+- 运行画面点选在 Phaser 4 与 three.js 玩法上，能识别点中对象用的是哪一张已登记素材，并让引用载荷带上该素材的稳定 id。
+- 识别不出来时不伪造、不报错，按主规范退化为不带素材的区域引用。
+- HTML 区域点选语义、预览消息协议、引用发送链路与 Rust 校验口径逐字不变。
+- 新建 Phaser 4 项目与 three.js 起步工程开箱即具备点选所需的引擎句柄。
+
+## 范围
+
+- 运行画面点选的引擎档识别：命中对象解析、素材身份来源与优先级、命中矩形高亮。
+- 宿主侧把识别结果映射成 manifest 素材 id（含"精确优先于文件名"的口径）。
+- 起步工程与新建项目默认脚手架的引擎句柄发布。
+- 上述行为的自动化证据与真机 smoke 证据。
+
+## 不在范围内
+
+- 生成期契约落位：把句柄发布与对象素材标注写进 AGC 玩法 Skill（**同一 PR 的阶段二**，见实施计划 `## 阶段二进展`）；重新发布模板产物（`template.zip` 与线上索引）仍不在本次范围内。
+- 运行期资源使用关系持久化（不记录"某素材在某位置被用过"，不注入代码、不写侧车）。
+- Cocos Creator / Godot / Unity 的点选；纯 2D canvas 引擎与 Babylon.js。
+- `runtime-region` 引用契约、预览消息版本号、Rust `resourceIds` 校验、资源选中与信息栏判据的任何变化。
+- 旧项目自动获得能力（不写迁移、不做兼容分支；限制如实写进能力说明）。
+
+## 依赖与前置条件
+
+- 主规范（`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`）与本节里程碑评审通过。
+- 可拉起的 AGC 真机客户端（`npm run agc`，端口与栈规约按 `genarrative-dev-stack-port-routing`），以及一份可复现的 Phaser 4 / three.js 起步工程。
+- 一张已登记到 manifest 的项目素材（图片；three.js 侧另需一张贴图）。
+- 不依赖后端服务、Provider 或登录态。
+
+## 验收标准
+
+- [x] Phaser 4 起步工程：点中由已登记素材渲染的精灵 / 图集帧，引用芯片显示该素材名，载荷 `resourceIds` 命中该素材 id。（浏览器实测：`loader.imageLoadType='HTMLImageElement'` 下自动档 `@hero` + `["hero"]`；默认 XHR 装载贴图为 blob，须由玩法显式标注，见主规范边界）
+- [x] three.js 起步工程：点中贴了已登记贴图的 Mesh（含 GLB 内嵌纹理的模型走显式标注路径），结果同上。（浏览器实测：贴图 Mesh `@hero` + `["hero"]`；`userData.genarrativeResourcePath` 档 `@enemy` + `["enemy-tag"]`）
+- [x] 同一对象同时存在显式素材标注与贴图地址推断时，取显式标注。（`tests/runtimeInspectEngines.test.ts` 33 例；浏览器重叠位取最上层且显式 id 胜出 `["enemy-tag"]`）
+- [x] 无引擎句柄 / 点中空白 / 程序化绘制三种情况：退化为不带素材的区域引用，零报错、零伪造 id，引用可插入可发送。（`runtimeInspectEngines.test.ts` 33 例；浏览器点空白 `@canvas` + `[]` 零报错）
+- [x] 命中对象时高亮为该对象在画面上的区域；取不到对象矩形时高亮范围与 DOM 档一致。（矩形换算改用 `camera.matrixCombined`；浏览器实测与期望逐值相减 Phaser 差 0px、three 最大差 ≈0.0006px，DOM 档为元素矩形）
+- [x] DOM 点选（HTML HUD、媒体 `src`、资源标识属性）行为与现有用例逐字不变。（`localGamePreviewFrame` 14、`resourceReferenceInput` 43、`appSurface` 197 passed / 9 skipped；浏览器实测 HUD 芯片名 `@HUD 区域` 未被素材名改写）
+- [x] 起步工程与新建项目默认脚手架发布引擎句柄；新建 Phaser 4 项目不额外改代码即可点选。（`DEFAULT_GAME_SCRIPT_JS` 与三个起步模板源已发布句柄；`cargo test -- scaffold` 4 passed / 1 既有 ignore。开箱即用未跑真机链路）
+
+## 证据要求
+
+- 自动化：引擎档识别的 JS 单元用例（jsdom 中加载真实桥脚本 + 假引擎对象）、宿主素材映射纯函数用例、桥注入与协议回归用例、`npm run agc:typecheck`。
+- 运行时：Phaser 4 与 three.js 各一条真机点选 smoke（截图或录制，含引用芯片与载荷证据）。
+- 边界：三种退化情况各一条、净化与数量上限不回归、`resourceIds` 只取 manifest 现有素材。
+
+## 验收证据（2026-10-04）
+
+- 命令：`npm run agc:typecheck` 通过（`check:tests:types` / `tsc` / skill-pack 指纹 / 包布局声明 / `check-config` 全过）。
+- 前端用例：`runtimeInspectEngines.test.ts`（33）+ `runtimeInspectResourceMatch.test.ts`（11）+ `localGamePreviewFrame.test.ts`（14）+ `resourceReferenceInput.test.tsx`（43）= 101 passed；`appSurface.test.ts` 197 passed / 9 skipped。
+- Rust：`cargo test … -- preview` 43 passed / 0 failed；`cargo test … -- scaffold` 4 passed / 1 既有 `#[ignore]`（需 npm 装依赖 + Provider）。
+- 真实浏览器冒烟（真实 Phaser 4.2.1 / three 0.184 + 真实桥脚本 `local-preview-fit.js`，被测 sha256 `6276ac48…917a`）：已登记贴图对象得 `["hero"]`、显式标注对象得 `["enemy-tag"]`、非交互精灵经几何兜底命中；点空白 `@canvas` + `[]` 零报错；DOM 档芯片名不被改写；高亮矩形与期望逐值相减，Phaser 差 0px、three 最大差 ≈0.0006px。
+- 未覆盖：Tauri 真机链路（预览服务器注入与路由由 Rust 定向测试覆盖）、多场景叠加、非默认相机（scroll/zoom/rotation）、高亮真机目视。
@@ -49,3 +49,10 @@
 - 自动化：admin-web 详情/动作测试、api-server 预览会话和权限测试、DTO/类型检查、编码和 diff 检查。
 - 运行时：本地管理员打开待审版本，确认资料、封面/截图和待审包试玩；确认旧公开版本不会被误播。
 - 边界：过期 Token、错误 versionId、Cookie、越权管理员、缺入口、资源 404、CAS 冲突和幂等重放。
+
+## 本轮核对（2026-10-05，试玩加载体验与超时收口）
+
+- 「试玩当前待审版本」原先只渲染 `<iframe class="admin-game-review-preview">`：加载期是一块 `min-height: 42rem` 的空白，没有加载文案、没有超时、没有失败提示（会话过期或资源 404 会永远停在空白）。2026-10-05 起与网页游玩页共用共享加载面 `PlatformGameLoadingSurface`（`packages/shared`）：加载期显示游戏标题/封面/动效进度与阶段文案，iframe `onLoad` 后才让位给画面。
+- 加载上限与网页游玩页统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒）：超时后加载面换成「试玩版本加载超时」并给出「重新创建试玩会话」入口；新建会话会重置加载态，不会沿用上一个会话的 ready。
+- 用例：`apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx` 新增两条（加载面在画面载入后让位、超过上限后给出超时说明与重建入口，重建后新会话 URL 生效且回到加载态）。
+- 仍未变化：预览会话 token 与 `no-store`、`sandbox="allow-scripts"`、Cookie 拒绝、版本绑定与审核 CAS 口径都不动。
@@ -333,3 +333,9 @@
 - **详情页返回按来源回到上一页**：`GameDetailPage` 左上角原来是写死的「返回游戏广场」，并且直接 `setSelectionStage('games')`（等于 push 一条新的 `/games`）。从「我的游戏」点进详情再返回就落到广场，从广场进详情返回也会多压一条重复历史。现在文案简化为「返回」，行为改成优先 `window.history.back()`，由 `ActiveApp` 已有的 `popstate` 同步把舞台还原成真正的来源页（我的游戏 / 广场）；游玩页的返回同样处理，避免详情↔游玩互相 push。协议侧给应用写入的历史条目补了 `__genarrativeAppHistoryDepth`，新增 `hasAppHistoryBackEntry()` 判断「当前条目是应用内导航写入的且存在上一页」；直接打开详情深链、或原生壳里没有可回退条目时，才 `replaceAppHistoryPath` 兜底到广场（游玩页兜底到自己的详情）。回归用例 `activeAppPageRoutes.test.ts` 锁定深度标记语义，`PlatformEntryActiveFlowShell.test.tsx`「游戏详情返回」两条锁定原生返回与深链兜底。
 - **游戏分发的返回文案统一成「返回」**：`GameDetailPage`、`GamePlayPage`（含超时面板里的按钮）、`MyGamesPage`、`GamePublishPage` 四处原本是「返回游戏广场 / 返回详情」，同一套流程里出现三种写法；现在统一成「返回」，目标页仍由各自的 `onBack`（广场 / 我的游戏 / 详情）决定，按钮不再承诺一个可能不对的目的地。`GameDistributionPages.test.tsx` 的断言同步改为 `/^返回$/u`。游玩页工具栏上那个按钮展示的是游戏名（退出开始面板后就靠它认游戏），不属于「返回 xx」文案，保持不动。
 - 验证：`npx vitest run src/components/game-distribution/GameDistributionPages.test.tsx`（21 passed）、`npx vitest run src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx`（22 passed）、`npx vitest run src/routing/activeAppPageRoutes.test.ts`、`npm run typecheck`、`npx eslint`（五个改动文件）、`npm run check:encoding`、`git diff --check` 全部通过；启动面板的溢出可达性、「我的游戏」移动端横向溢出都用真实 Chromium 静态夹具量过（见 pitfalls 同日条目），详情返回链在真实 Chromium（dev 栈 390x844）实测 `/games`→详情→返回=`/games`、深链直开详情→返回=`/games`、详情→立即玩→返回详情=`/games/detail?id=…`。视觉与真机横竖屏走查仍需人工/截图评审（沿用阶段 C 第 8 条未取证口径）。
+
+## 本轮核对（2026-10-05，游玩页加载体验与发行资源传输）
+
+- 游玩页此前在 `onLoad` 前只盖一行 `游戏正在启动…`（近黑壳上），用户反馈「一直黑屏」。现在加载期显示共享加载面 `PlatformGameLoadingSurface`（`packages/shared`，封面/标题 + 动效进度 + 按时长推进的阶段文案），`onLoad` 后淡入画面；超时面板与重试/返回不变，上限仍与后台试玩统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒）。
+- 发行网关（`api-server`）对文本类发行资源下发 `Content-Encoding: gzip` + `Vary: Accept-Encoding`，并下发强 `ETag`：`If-None-Match` 命中返回 304。`max-age=60, must-revalidate` 与撤销窗口不变，差别只是 60 秒之后重复游玩不再重下整包。后台试玩会话仍是 `no-store` 且无 ETag。
+- 证据：真实栈 4 Mbps/100 ms 模拟链路对照（改前 3298 ms / 4587 ms 才出画面，且期间无有效加载反馈），发行网关字节数对照见 PR；`cargo test -p api-server --bin api-server -- game_distribution` 与三条前端用例（共享加载面、游玩页、后台试玩）为回归门禁。