From 34e6e73016c38722a42c04f90ab06872ab761539 Mon Sep 17 00:00:00 2001
From: cabinw <cabinw@gmail.com>
Date: Mon, 14 Sep 2026 18:33:05 +0800
Subject: [PATCH] docs: hand-off instructions for publishing the phone bundle

Written to be copied whole into another agent's prompt, so it names the two
failure modes that are silent rather than loud: a bundle published without
--standalone has no viewport meta and renders at 980px on a phone, and a host
serving .js as application/octet-stream leaves a blank page with no clue in the
UI. The acceptance list checks the icons and the tile sheet explicitly, because
a missing asset degrades to the fallback renderer and looks deliberate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/publish-phone.md | 69 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 docs/publish-phone.md

diff --git a/docs/publish-phone.md b/docs/publish-phone.md
new file mode 100644
index 0000000..397fead
--- /dev/null
+++ b/docs/publish-phone.md
@@ -0,0 +1,69 @@
+# 发布手机版 · 交给 agent 执行的说明
+
+整份内容可以直接复制给另一个 agent。
+
+---
+
+**任务：把 HEX TRAILS 的 50 关手机版发布到一个手机能访问的网址。**
+
+仓库：`git@git.zeroplus.fun:Zeroplus/HexTrails.git`，分支 `main`（本地路径 `/Users/wukaibing/Codex/hex-arrow`）。构建脚本 `scripts/build-phone.mjs` 已经写好并测过，你**不需要改游戏代码**。
+
+## 第一步，构建
+
+```bash
+node scripts/build-phone.mjs --standalone --out=build/phone-standalone
+```
+
+产物约 5.2MB：`index.html`（完整 HTML 文档，样式已内联）+ `src/` 22 个 ES module + `assets/` 7 个资源（贴图、图标图集、背景、托盘、两个 woff2 字体）。
+
+如果目标托管平台**自带 `<html>` / `<head>` / `<body>` 外壳**（比如 Claude Artifacts），改用不带 `--standalone` 的默认模式，产出的 `index.html` 只有 body 内容：
+
+```bash
+node scripts/build-phone.mjs
+```
+
+两种模式只差文档外壳，其余完全一样。**别把两者搞混**——给普通静态托管发了片段版，页面会没有 viewport meta，手机上按 980px 宽渲染。
+
+## 第二步，发布
+
+发到任意静态托管都行（Vercel / Netlify / Cloudflare Pages / GitHub Pages / 对象存储）。要求只有三条：
+
+1. **保持目录结构。** `index.html` 里是 `<script type="module" src="src/app.js">`，模块之间用相对路径互相 import，`assets/` 也是相对路径引用。不要扁平化目录，不要给资源加 hash 重命名，除非你同时改写所有引用。
+2. **`.js` 必须以 `text/javascript` 返回。** 用 `application/octet-stream` 返回的话 ES module 会被浏览器拒绝执行，页面白屏。
+3. **全站 HTTPS 或全站 HTTP，别混。**
+
+## 第三步，验收（必做，逐条确认）
+
+用手机宽度（375px）打开发布后的网址，确认：
+
+- [ ] 标题栏是 `LEVEL 01`，`待解棋子 8`
+- [ ] 左上角有九宫格图标、右上角有齿轮图标（**不是空白、不是破图**）
+- [ ] 底部三个圆按钮里有撤销 / 重来 / 灯泡图标
+- [ ] toast 里**没有**「棋子图片加载失败，已切换基础绘制」——出现这句说明 `assets/tiles-matte-clean-v8.png` 没发上去或 404
+- [ ] 棋盘上 8 枚彩色六角棋子带箭头，背景有轨道线
+- [ ] 点一下第 1 关左下角那枚粉色棋子，它应该沿轨道滑出棋盘，计数变成 7
+- [ ] 页面**没有横向滚动条**
+
+浏览器控制台不应有 404 或模块加载错误。有的话先查是不是第 1 条（目录结构）或第 2 条（MIME）。
+
+**已知的、不是 bug 的现象**：375×812 下棋盘只占上半屏，下半屏是空的。这是游戏现有布局，和未打包的原版一模一样，不要去「修」它。
+
+## 背景
+
+这 50 关是 `c50` 版本。构建脚本会把 campaign 注册表换成只含这一版，从而甩掉千关版那个 9.2MB 的 `src/levels-v05.js`——完整静态构建是 10MB+，这里是 645KB 代码 + 4.5MB 图。
+
+进度存在浏览器 localStorage（key `hex-trails-campaign-c50`），通一关自动进下一关。清空进度：
+
+```js
+localStorage.setItem('hex-trails-campaign-c50', JSON.stringify({current:0,completed:[]}))
+```
+
+## 如果只是自己在局域网里玩
+
+不用发布，电脑跑着 `npm run dev`，手机连同一个 Wi-Fi 打开：
+
+```
+http://<电脑的局域网IP>:4173/index.html?campaign=c50
+```
+
+IP 用 `ipconfig getifaddr en0` 查。服务已绑 `0.0.0.0`，不用改配置。