# ForFilm · Ark 网页操作

沿用 ForFilm 的连接、Frame、Film、动画和设置布局，新增“通行证”入口。Ark 连接后的品牌统一为 ARKNIGHTS / RHODES ISLAND，保持原有网页结构；其他机型保留原页面。

Ark 专属主题只在 Ark 蓝牙连接及通知初始化成功后启用。每次新连接显示浅灰登录入口：线框描绘与徽标显现、标题淡入；点击“开始唤醒”播放终端几何动效，再淡出至深色 PRTS 工作台。这里的“唤醒”仅进入网页，不发送设备唤醒指令；状态文字只描述界面过渡，不冒充蓝牙或文件上传进度。可跳过或按 Esc，系统减少动态效果时直接切换。

同一连接内的状态刷新和主题开关不重复播放；连接状态下可在设置中重看。断开会立即取消全部登录动画与延迟回调，恢复原 ForFilm 外观，重连后开始新的引导会话。Logo 保留 SVG 矢量形状，登录页使用纯黑、深色页头使用纯白，不叠加透明度或混色。

工作台使用炭灰直角面板、黑白对比标题、细边框和冷蓝活动状态。连接页、制作工具、设置及嵌入的通行证编辑器共享外观规范；设备预览画布仍保持实际黑白像素。主题开关可恢复原 ForFilm 外观，切换不丢弃通行证草稿。

主题入口脚本使用 `prts-3`，主题样式使用 `prts-6`、加载页和编辑器样式使用 `prts-4`、卡包脚本使用 `nfc-9` 资源标识，避免浏览器继续使用旧资源。此标识只用于网页资源更新，与固件版本无关。页面底部显示 ForFilm 网页版本号 `v1.0.0` 与提交号：版本号发布时在 `js/main.js` 的 `APP_VERSION` 手动递增；提交号优先由 GitHub API 读取 main 的最新提交，离线或接口受限时用 `APP_COMMIT_FALLBACK`。

加载页适配手机安全区和矮横屏，空间不足时可滚动；背景与内容同步淡出。主界面与通行证编辑器统一按钮反馈和键盘焦点提示，手机端文本输入使用 16px 字号。

Frame、Film、动画和设置页共用同一套表单、滑杆、状态标签与消息提示；展开的网络面板和键盘弹窗也跟随主题。动画的播放、放大、应用到所有帧等选中状态使用冷蓝底深色文字。照片预览、绘图画布及实际调色板保持内容原色。

正常入口为 `http://127.0.0.1:8768/ForFilm/`。旧 `?theme=ark` 参数不再启用主题；未连接时始终保持原网页。

## 本地使用

从仓库根目录启动静态服务（服务根必须是 `tools`，以提供通行证编辑器和共享资源）：

```powershell
python -m http.server 8768 --bind 127.0.0.1 --directory tools
```

在支持 Web Bluetooth 的浏览器打开 `http://127.0.0.1:8768/ForFilm/`。首次点击“蓝牙扫描”并选择 Ark；同一页面中断开后可“重连上次”。蓝牙选择窗口须由用户操作。USB 连接入口用于 Dock，Ark 的 CH343 用于供电和固件调试。

## 页面与操作

```text
设备连接 → 扫描 / 已授权设备重连 / 当前任务取消
Frame / Film / 动画 → 保留现有制作工具
Film → Ark 蓝牙上传进度 / 取消 / 同文件从头重试
通行证 → 编辑与预览 / JSON 导入导出 / 设备读取 / 双文件发送
设置 → Ark 系统页入口 / 遥控 / 改名 / WiFi 直传状态与取消 / OTA
```

- Ark 仍按 `FRAMEFILMARK` 前缀识别，兼容默认唯一名称与中文后缀。屏幕参数不能把 Ark 改判成 Pro。改名后重启广播才生效，自定义名称不做全局查重。
- 通行证编辑器在同源页面内复用 `ArkDevice` 的同一条 BLE 连接，不再单独配对。资料保存在 SD 卡，网页保留本地草稿。读取前会确认，完整校验通过后才替换草稿；失败或取消不覆盖编辑内容。发送顺序为 `profile.bin`、`profile.json`，发送后通过 `0x53` 回读 `profile.json` 比对，部分完成会明确提示；不是双文件原子事务。
- Ark 普通图片上传可以取消，取消后断开以触发设备撤销未完成文件。重连后“从头重试”重新发送整份文件，不做断点续传。发送过程中锁定冲突操作；每 32 包及文件结束后等待设备处理查询，避免连续发送挤满队列。固件没有保存 ACK，网页报告“已发送，待设备确认保存”，不将 GATT 成功等同于 SD 保存成功。
- 语言、开机画面和启动应用尚无 BLE 读写接口。网页提供“打开设备系统设置”和遥控，在设备屏幕上修改。Ark 不再显示或发送已废弃的 `0x20/0x21` 照片模式控制。
- WiFi 直传状态经 `0x51` 查询，取消经 `0x52` 请求并等到终态；恢复网络中的 100% 不代表完成。浏览器不创建手机 WiFi Direct 网络，也不提供手机侧临时 HTTP 文件服务；网页图片发送仍为 BLE。
- **设备控制 → 固件升级**：连接 Ark、选择正式版或 CI 通道，点击「开始升级」。网页自动读取硬件规格、OTA 槽容量和 ELF 构建指纹，再下载并校验匹配的 OTA 镜像。旧固件若不支持硬件身份，请按实物选择规格。重启后重连并点击「检查更新」，网页会核对新的构建指纹。
- **串口烧录 · 完整固件**：选择「联网获取」、设备机型（Ark / 经典 Pro）和硬件规格（N4R2 / N16R8）。Ark 可选发布通道，经典 Pro 须选屏幕面板。点击「开始烧录」并在浏览器弹窗中选择串口。网页下载完整镜像，校验 SHA-256 和镜像布局后显示确认。确认后才复位并检测芯片与 Flash 容量，通过后从 `0x0` 写入。
- GitHub Pages 的发布来源设为 **GitHub Actions** 后，`ForFilm Pages` 工作流会将固件目录和镜像与网页一起部署。目录包含 Ark 正式版、Ark CI 和经典 Pro 正式版，网页从当前部署同步获取对应镜像。本地文件入口也可用于离线更新。
- 当 GitHub 附件的跨域设置限制网页直接读取时，点击页面上的附件链接下载，再用旁边的「导入已下载」按钮校验并准备文件。两条入口均保留本地文件选择。

## 最小验证

```powershell
node --test tools/ForFilm/tests/ark-device.test.cjs
# 需先启动上述静态服务，安装/提供 Playwright，并可启动 Edge
node tools/ForFilm/tests/ark-browser.test.cjs
node tools/ForFilm/tests/ark-upload-ui.test.cjs
# 仅检查主题连接/断开、开关、编辑器同步和移动端布局
node tools/ForFilm/tests/ark-theme.test.cjs
# 仅检查连接门槛、登录动画播放/中断、重连与减少动态效果
node tools/ForFilm/tests/ark-intro.test.cjs
# 仅检查布局精修、淡出、按钮对比与编辑器焦点
node tools/ForFilm/tests/ark-polish.test.cjs
# 仅检查 Frame 子页面、Film、动画与设置的主题覆盖
node tools/ForFilm/tests/ark-pages.test.cjs
# 异步图片完成与 busy 锁、直传状态的断连/重连归属
node tools/ForFilm/tests/ark-state.test.cjs
```

浏览器用模拟 BLE 验证共享连接、读失败保留草稿、取消/重连/发送、直传状态与取消、OTA 文件拦截及移动端布局，不写入真实设备。真实蓝牙和 SD 保存行为需要单独验收。

## 后续 App

网页完成本轮主题和状态收敛后，App 进入 **Flutter 原生界面重构研究**，不使用 WebView 包装网页。可切换的两套视觉为 **明日方舟／罗德岛风格**与**原 ForFilm UI 风格**；复用协议、操作语义和资料格式。具体迁移边界与实施顺序见 [Android README](../../app/android/README.md)。Flutter 工程与实机验收尚未开始。