pawplay/web/README.md

PawPlay 网页版

原生 Canvas 2D 实现的鱼池、红点、羽毛触摸游戏。免费、无广告、无账号，不依赖外部字体、图片、音视频文件或第三方 SDK。静态文件可直接部署。

本地运行

在仓库根目录执行：

python3 -m http.server 18731 --bind 127.0.0.1 --directory web

打开 http://127.0.0.1:18731/。正式部署需 HTTPS；通过平板访问局域网明文 HTTP 时，Service Worker 不可用。

玩法

• 轻触或拖动屏幕产生水波、粒子或风。支持多指。
• 长按任一上角爪印两秒打开家长面板；移动过远、释放或切换后台会取消长按。键盘用户可聚焦爪印后按住空格或 Enter 两秒。
• 家长面板切换场景、音效，继续游玩或进入全屏。设置只在当前设备本地保存；存储不可用时仍可玩。
• 首次用户交互解锁音效；切换后台暂停动画和音频。支持时请求屏幕常亮；浏览器拒绝时遵循系统休眠设置。
• 在 iPad Safari 使用“分享 → 添加到主屏幕”可获得更完整的显示区域。系统手势由设备控制，网页无法屏蔽。

离线与更新

家长面板显示“已准备好，可断网重新打开”后，应用壳和三个模式已缓存。没有缓存完成就离线，或系统主动清理网站数据时，需要重新联网加载。

sw.js 一次完整缓存当前版本的所有资源，安装失败时删除本次不完整缓存。新 Worker 不强制替换正在游玩的旧 Worker；关闭旧游戏窗口后，新版本才会激活。导航和静态资源只从同一版本的缓存读取，不做接口或跨站运行时缓存。

发布新资源时同时修改 sw.js 的 VERSION、资源查询版本，以及 index.html 中 JS/CSS 的查询版本。验证新缓存完成后再发布；不要只替换同一版本下的某一个资源。

Docker

docker build -t pawplay-web ./web
docker run --rm -p 18731:8080 pawplay-web

容器监听 8080，健康检查为 /healthz。镜像只复制游戏资源，不含测试截图、源码目录、密钥或运营数据。Nginx 对 JS/CSS/SVG 启用 gzip；首页和 Worker 不使用长期 HTTP 缓存。

浏览器验证

使用已安装的 Playwright 运行（脚本自行启动并关闭临时 HTTP 服务）：

node web/qa.cjs

如 Playwright 未在模块搜索路径内，用 PLAYWRIGHT_MODULE 指向已安装的模块目录；CHROME_BIN、WEBKIT_BIN 可指定兼容的浏览器。模块版本必须匹配浏览器缓存版本。结果和截图保存在被 Git 忽略的 web/.qa/。

脚本验证短按防误触、两秒长按、三模式切换、设置持久化、横竖屏无滚动、关闭 HTTP 源站后关闭页面并重新打开，以及 Chromium 双指输入。检查无外部请求和页面异常，并统计实际资源字节数、gzip 字节数。WebKit 的自动化离线开关可能在 Worker 接管请求之前报内部错误，因此以真实关闭源站验证缓存读取。

本轮验证：Chromium 与 WebKit 均通过上述菜单、横竖屏、设置持久化和源站关闭后重开测试；Chromium 另通过双指输入。完整游戏资源合计 62,166 字节（约 61 KiB），逐文件 gzip 合计约 40 KiB；其中 PNG 在正式 Nginx 中不额外 gzip，实际传输会有少量差异。HTTP 头和 TLS 握手开销不计入此数。

验证范围仅为桌面 Chromium/WebKit 引擎。没有 iPad 真机数据；不能据此声称已通过 iPad Safari、主屏幕模式、真实音频输出、引导式访问、屏幕休眠或真实猫咪试玩验收。

实现边界

场景复用 Android 版的配色和交互规律，以 JavaScript/Canvas 重写绘制与物理逻辑，并非运行 APK。画布像素比最多 2，总像素数最多约 400 万；粒子最多 160、水波最多 35，以限制高分辨率设备开销。不作所有设备稳定 60fps 的承诺。

网页没有应用层行为统计或账号标识。托管服务可能保留常规 HTTP 访问日志，实际部署时应按托管配置说明。