灯路回环（Lantern Loop）

一款无需联网、单局约 2–5 分钟的浏览器光路解谜游戏。玩家旋转 5×5 刻纸瓦片，让左上角火种沿着双向相接的道路，点亮全部瓦片与三座灯塔。

它适合想做短暂专注休息的玩家，也适合作为原生 JavaScript 状态管理、确定性随机生成和无障碍网格交互的轻量示例。

项目价值

• 即开即玩：没有框架、依赖、账号、广告或网络请求。
• 谜题可分享：相同“谜题暗号”始终生成相同棋盘。
• 规则可验证：生成、旋转与连通判定和 DOM 完全解耦，并配有自动化测试。
• 输入方式完整：支持鼠标、触屏、方向键、回车/空格及 Shift 逆向旋转。
• 视觉有辨识度：以纸雕夜灯盒和民间版画为方向，不依赖外部字体或图片。

快速开始

需要 Node.js 20 或更新版本。项目没有第三方依赖，无需执行 npm install。

npm start

浏览器访问 http://127.0.0.1:4173。ES modules 通常不能通过直接双击 HTML 稳定加载，因此推荐使用随项目提供的本地静态服务器。

玩法

1. 点击瓦片或聚焦后按回车/空格，使其顺时针旋转 90°。
2. 按住 Shift 再操作，可逆时针旋转。
3. 使用方向键在棋盘中移动键盘焦点。
4. 当所有 25 块瓦片都能通过相互吻合的出口连接到火种时获胜。
5. “借一缕光”会把一块瓦片转到正确方向，并把所需旋转计入步数。

开发与测试

npm test
npm run check

测试使用 Node.js 内建 test runner，覆盖：

• seeded puzzle 的确定性与不同种子的差异；
• 生成谜面的未完成状态和标准答案的全连通状态；
• 顺/逆时针旋转及四次旋转循环；
• 双向光路和胜利判定；
• 暗号、尺寸、掩码、旋转次数与棋盘状态的非法输入。

目录结构

lantern-loop/
├── index.html           # 语义化页面与胜利对话框
├── styles.css           # 纸雕夜灯视觉、响应式与减少动态效果
├── src/
│   ├── puzzle.js        # 纯函数谜题引擎
│   └── game.js          # DOM、计步、计时和输入控制
├── tests/
│   └── puzzle.test.js   # 核心规则测试
└── scripts/
    └── serve.mjs        # 零依赖本地静态服务器

谜题模型

每个瓦片用四位 bitmask 表示北、东、南、西出口。生成器使用暗号派生的伪随机序列，通过深度优先遍历构造一棵覆盖全部格子的树，再独立旋转每块瓦片。解答时只允许沿“当前瓦片有出口且相邻瓦片有反向出口”的边传播灯火。

无障碍与隐私

• 棋盘作为原生按钮组公开，每块瓦片都描述行列、点亮状态、地标和出口方向。
• 状态变化通过 aria-live 通知；焦点具有高对比描边。
• 遵循 prefers-reduced-motion，关闭非必要过渡和完成动画。
• 游戏不使用 Cookie、分析工具、本地存储和远程接口。

已知边界

• 当前固定为 5×5 棋盘，核心引擎本身支持 3×3 到 8×8。
• 暗号生成算法面向娱乐复现，不属于密码学随机。
• “提示”以标准生成树为准；某些谜面理论上可能存在视觉等价解。
• 没有跨设备战绩、排行榜或存档，这是刻意保持离线与轻量的取舍。

参与贡献

请先阅读 CONTRIBUTING.md。漏洞请按 SECURITY.md 中的方式私下报告。

许可证

本项目使用 MIT License。