first commit

docs/assets.md

@@ -0,0 +1,6 @@
+# 资源约定与来源
+
+- 所有扑克花色、牌背、人头牌、小丑、行星与塔罗插画由本项目 Canvas 绘图代码生成，位置 src/render/art.ts，无原作拆包或截图裁切。
+- 音效使用 Web Audio 振荡器合成，位置 src/platform/audio.ts。
+- 字体使用设备自带 Georgia、Courier New 及中文宋体/黑体回退，无外部字体或网络素材依赖。
+- 首版无需 public/assets 文件夹；图像纹理在初始化时生成并复用，资源增加时更新此记录。

docs/implementation-plan.md

@@ -0,0 +1,130 @@
+# Web 小丑牌实现方案
+
+日期：2026-09-21。状态：用户已授权，首版已实现。实际规则及范围以 rules.md 为准，验收情况见 verification.md。
+
+## 1. 产品目标与取舍
+
+实现可在浏览器直接游玩的单人扑克构筑游戏。重点是构筑选择、计分链与完整对局，其次是贴近参考图的复古牌桌体验。第一版使用中文，桌面横屏优先，兼容平板及手机横屏；离线本地对局，无账号和服务器依赖。
+
+推荐 TypeScript + Vite + PixiJS 8，使用 HTML Canvas 承载 WebGL 渲染。Canvas 是呈现载体，不限定必须使用 Canvas 2D API。锁定实际安装的小版本；第一版不依赖实验性 Canvas 2D 回退或 WebGPU。
+
+Cocos Creator 可以发布 Web，也适合后续小游戏平台，但目前没有现成场景、Prefab 或跨平台交付需求。此阶段增加编辑器、资源导入和构建链的收益有限。若确认主要目标变成微信/抖音小游戏，再选择 Cocos；独立规则模块可以复用，表现层仍需重做。
+
+不把完整原作内容量作为第一版承诺。规则采用可追踪的 Balatro 基础规则参考，牌面和音效制作独立资产。第一版限制卡池，但包含通关、失败和存档，不停留在可点卡牌的展示页。
+
+## 2. 图片观察与视觉方案
+
+参考图约为 16:9。左侧约四分之一为状态栏，右侧是大面积绿色牌桌；上方放小丑，下方是手牌，中部留给出牌、提示和计分。右上是消耗品，右下是牌堆。
+
+- 深墨绿底色与缓慢流动的同色纹理，低对比，不抢牌面。
+- 深灰状态板、偏暖白纸牌、蓝色筹码与红色倍率；金黄用于金钱和奖励。
+- 卡牌有粗边、轻微歪斜、短硬阴影、像素插画和扇形重叠，像桌上的实体纸牌。
+- 英文数字可用像素字体；中文优先保证辨认，使用许可明确的点阵风格字体，避免极细字形。
+- 微弱扫描线、暗角、少量色差作为可关闭的全屏效果。正文和点数保持清晰，不照搬截图的模糊感。
+- 悬停轻抬与倾斜、选中上移、出牌滑向中央、逐张触发弹跳、倍率脉冲、过关盖章。
+- 点击、发牌、加筹码、加倍率、乘倍率使用不同短音效；触发链越长，音高与节奏有递进。
+
+设计坐标建议 1440×810，按窗口等比布局并重新分配边距，不拉伸卡牌。小屏横屏收紧状态栏；竖屏先提供明确横屏提示。鼠标悬停信息在触屏改为长按；拖拽设置阈值，避免选牌误触。键盘可选牌、出牌、弃牌和取消选择。
+
+美术交付先做一套完整牌桌、扑克花色和人头牌，再制作首批独立小丑插画及牌背。不能仅用 emoji 或文字方框替代最终卡面。最终资源统一调色板、描边和像素密度。
+
+## 3. 核心玩法理解
+
+基本循环：选择盲注 → 抽牌 → 选 1–5 张出牌或弃牌 → 按顺序触发效果并累计分数 → 达标结算或次数耗尽失败 → 商店构筑 → 下一盲注。
+
+每个 Ante 包含小盲、大盲、Boss；传统通关目标为 Ante 8 的最终 Boss。Boss 改变局内约束，小丑改变计分、经济或规则，塔罗修改牌组。这些主结构由官方 FAQ 确认。[S1]
+
+核心公式是最终筹码乘最终倍率，但不能把所有增益先求和再相乘。社区触发指南明确区分 Boss / 出牌前效果、逐张计分牌、留手效果、小丑独立效果等阶段；同阶段的顺序也是策略的一部分。[S2]
+
+实现要区分四个概念：选出的牌、判定的主要牌型、牌型包含关系、真正参与计分的牌。例如“包含对子”的效果不应只在最终牌型名称恰好为对子时生效。
+
+牌型引擎覆盖高牌、对子、两对、三条、顺子、同花、葫芦、四条、同花顺，以及改牌后可出现的五条、同花葫芦、同花五条。皇家同花顺作为同花顺的展示变体，不独立建升级账本。牌型优先级不随升级后的潜在分数改变。[S3]
+
+图片中的 6/6 小丑和 10/10 手牌是局内状态，来源无法仅靠图片确定。第一版拟采用基础配置：52 张牌、8 张手牌、4 次出牌、3 次弃牌、5 个小丑槽、2 个消耗品槽；这些值在规则冻结阶段逐项核实，统一配置，不散落在 UI 内。
+
+## 4. 首版内容边界
+
+以下数量是项目范围建议，不声称是原作内容清单。
+
+| 系统 | 第一版目标 | 后续扩展 |
+| --- | --- | --- |
+| 对局 | 1 个基础牌组、1 个难度、8 个 Ante | 多牌组、多难度、无尽 |
+| 扑克牌 | 52 张初始牌、复制/删除/改点数与花色 | 更多特殊牌规则 |
+| 牌型 | 12 类计分与升级，皇家同花顺展示变体 | 特殊小丑改变判型 |
+| 小丑 | 24 张，覆盖筹码、加倍率、乘倍率、条件、成长、经济、重触发 | 复制效果、复杂规则改写 |
+| Boss | 6 种常规机制、1 种终局机制；重复抽取规则明确 | 完整 Boss 池 |
+| 消耗品 | 对应牌型的行星、9 种塔罗（新增女皇投放多倍强化） | 幻灵与更多塔罗 |
+| 卡牌修饰 | 奖励、多倍、玻璃、钢铁及红色蜡封等分阶段落地 | 全部版本、蜡封与贴纸 |
+| 商店 | 购买/出售/刷新、小丑与消耗品、基础补充包 | 更多优惠券与包型 |
+| 跳盲 | 基础跳过与有限标签池，Boss 不可跳过 | 完整标签池 |
+| 持久化 | 新开局、续局、设置、种子与规则版本 | 收集解锁、成就、挑战 |
+
+24 张小丑必须支持至少四类有不同决策的构筑，例如对子成长、花色逐张触发、留手钢铁、经济转化。不是把同一加分效果复制 24 次。
+
+## 5. 规则与状态架构
+
+依赖方向：内容与纯规则 → 应用协调 → 渲染和浏览器适配。引擎输出状态与事件，渲染不得反向拥有规则。
+
+核心模块：
+- `HandEvaluator`：主要牌型、包含关系、计分牌集合；支持 A 的低位顺子与高位顺子，拒绝跨首尾非法顺子。
+- `ScoringEngine`：按明确阶段计算；返回最终值及逐步 ScoreTrace。
+- `EffectRegistry`：有类型的效果处理器，声明触发阶段、条件、顺序与可重触发性；不建设不必要的通用脚本语言。
+- `RunState`：牌组实例、盲注、回合次数、金钱、槽位、牌型等级与历史。
+- `ShopEngine`：商品池、权重、价格、刷新、购买与出售的原子更新。
+- `SeededRng`：抽牌、商店、概率效果分别使用可保存的随机流。
+- `SaveCodec`：版本号、规则版本、种子、随机状态、内容 ID 和实例状态；损坏存档有明确恢复提示。
+
+流程状态：主菜单 → 盲注选择 → 发牌 → 等待操作 → 计分 → 达标结算 / 继续抽牌 / 失败 → 商店 → 下一盲注；最终 Boss 后进入胜利页。
+
+以 `dispatch(command, state)` 的事务边界验证操作。计分时禁止重复出牌和不合法重排；结算奖励只发一次。动画使用引擎结果播放，快进、后台恢复和刷新不改变得分。
+
+计分事件包含阶段、来源实例、目标、操作类型、前值与后值；例如“某张红桃触发 +3 Mult”。同一份事件支持动画、对局日志和测试诊断。
+
+保留三个顺序：出牌顺序、留手顺序、小丑顺序；排序按钮不应无意改变已确认的计分事务。重触发不是递归调用整轮结算，不可重复触发出牌次数或回合奖励。
+
+随机预览不消耗真实 RNG，也不承诺随机效果的确切最终分数；默认只显示牌型、基础筹码/倍率和确定触发条件。
+
+分数运算集中封装，明确乘数、小数和最终取整规则，规则冻结时核对；不使用 32 位位运算储存得分。首版限制到正常 8 Ante 范围，无尽大数另行设计。
+
+## 6. 规则研究交付
+
+在编码前补齐 `docs/rules.md`，每条规则记录来源、适用版本、输入例子、预期输出、核实状态与本项目差异。
+
+优先核实：牌型基础值和每级增长、包含关系、默认资源、盲注目标曲线、Boss 倍率及抽取条件、奖励/利息/刷新/卖价、补充包选择流程、弃牌补牌与牌库耗尽、失效牌与修饰牌交互、触发及取整顺序。
+
+官方 FAQ 只足以确认主循环；社区资料提供细节但并非官方规范。本次部分 Wiki 页面正文抓取失败，搜索摘要不能替代全部边界验证。已找到的资料不等于已完成全量原作复刻研究。对争议交互采用可重复对局证据；无法核实的内容先不进入首版卡池。
+
+## 7. 分阶段实施与退出条件
+
+| 阶段 | 交付物 | 进入下一阶段的条件 |
+| --- | --- | --- |
+| A 规则冻结 | 规则表、24 张小丑候选效果清单、固定计分用例 | 首版每个效果均有触发阶段与预期例子 |
+| B 纯逻辑 | 牌型、抽弃牌、计分、Boss、商店和对局状态机 | 无界面可运行固定种子流程；计分及状态边界通过 |
+| C 纵向切片 | 1 个 Ante、约 6 张代表性小丑、商店、牌桌和音效 | 从开局到 Boss 的真实循环可玩，可看懂每次加分 |
+| D 完整首版 | 8 Ante、完整首批卡池、消耗品、跳盲、存档 | 至少可复现一局胜利和一局失败，恢复进度正确 |
+| E 打磨验收 | 成套美术、CRT、反馈、触控、性能、构建产物 | 浏览器流程验证和视觉验收完成，限制有记录 |
+
+完整首版比普通单页卡牌演示复杂，应按以上交付门槛推进，不在规则未冻结时给固定工期承诺。
+
+## 8. 验证方法
+
+- 单元测试：牌型识别、A 的两种合法顺子、重复实例、主要牌型与包含关系、非计分牌、手牌等级、Boss 限制。
+- 计分金样：手算预期并记录阶段；加倍率/乘倍率换位必须产生正确差异；逐张与留手重触发范围分别验证。
+- 性质测试：无生成/销毁效果时卡牌守恒、实例不重复占区、非法命令不改状态、同种子同命令同结果。
+- 交易测试：重复点击购买/结算不重复扣钱或发奖；槽位满和余额不足不丢商品。
+- 存档测试：计分期间刷新恢复到已提交状态；随机流恢复一致；旧版本和损坏数据处理明确。
+- 浏览器流程：新局、排序、拖拽、出牌、弃牌、购买、跳盲、消耗品、胜败、刷新续局；Playwright 跑关键流程。
+- 视觉检查：1440×810、1280×720、平板和手机横屏；中文不溢出，提示框不出屏，点击命中跟随变换后牌面。
+- 性能目标：约定桌面设备上的正常场景目标 60 FPS；低性能设备关闭后处理并降低渲染分辨率，结果以实测为准。
+- 平衡测试：固定种子与脚本策略检查明显死局、数值异常和商店供给；自动策略胜率不等于人类体验，仍需人工玩不同流派。
+
+## 9. 来源
+
+- [S1 官方 FAQ](https://www.playbalatro.com/faq)：主循环、Ante 8、Joker 与塔罗的职责。
+- [S2 社区触发顺序指南](https://balatrogame.fandom.com/wiki/Guide:_Activation_Sequence)：计分阶段与顺序，非官方资料。
+- [S3 社区牌型页](https://balatrogame.fandom.com/wiki/Poker_Hands)：本次以搜索摘要取得部分信息，正文未成功获取；完整表待核实。
+- [S4 社区盲注页](https://balatrogame.fandom.com/wiki/Blinds_and_Antes)：本次仅获取搜索摘要，完整数值待核实。
+- [S5 PixiJS Application](https://pixijs.com/8.x/guides/components/application)：Canvas、渲染器与应用初始化。
+- [S6 Cocos Creator Web 发布](https://docs.cocos.com/creator/3.8/manual/en/editor/publish/publish-web.html)：Cocos 的 Web 构建支持。
+
+以上链接访问日期为 2026-09-21。依赖版本及社区规则在实施时固定，不能把网页更新自动当作项目规则变更。

docs/rules.md

@@ -0,0 +1,45 @@
+# 首版冻结规则 · velvet-v1
+
+本作是独立内容的 Balatro 式构筑游戏，不声称完整复刻原作。基础牌型、升级数值和白注目标参考社区资料；以下具体交互以本文件及测试为准。
+
+## 基础与牌型
+- 52 张普通牌，初始 $4，手牌 8、出牌 4、弃牌 3、小丑槽 5、消耗品槽 2。每次选 1–5 张。每轮重新洗整副存活牌；轮内已打出/弃掉的牌不回抽牌堆，牌库耗尽不重洗，仍可打剩余手牌。手牌和牌库都空且未达标则失败。
+- 主要牌型按强弱取最高类别，不以潜在分数选类别。只有组成牌型的牌计分。A 可作 A2345 或 TJQKA，不可绕接。相同牌面可有不同实例。
+- 高牌 5×1 (+10/+1)，对子 10×2 (+15/+1)，两对 20×2 (+20/+1)，三条 30×3 (+20/+2)，顺子 30×4 (+30/+3)，同花 35×4 (+15/+2)，葫芦 40×4 (+25/+2)，四条 60×7 (+30/+3)，同花顺 100×8 (+40/+4)，五条 120×12 (+35/+3)，同花葫芦 140×14 (+40/+4)，同花五条 160×16 (+50/+3)。括号是升级增量。
+- 数字牌按点数，J/Q/K=10，A=11。包含对子定义为至少两个同点数，包含三条为至少三个；两对必须有两个不同的对子点数。
+
+## 结算顺序
+1. 判型、升级值、Boss 基础值修正，成长小丑更新。
+2. 按出牌顺序处理计分牌：点数、强化、逐张小丑；红封和回声分别增加一次完整逐张触发，不递归增生触发。
+3. 留手牌从左到右处理钢铁，再处理月后。
+4. 小丑从左到右处理独立筹码/加倍率/乘倍率。最终向下取整筹码×倍率。
+5. 玻璃牌仅在本次参与计分后各有 1/4 概率销毁一次；轮末经济与奖励各结算一次。
+- 示例：K K 7 为对子，(10+10+10)×2=60；+4 倍率之后 ×2 得 360，交换这两个效果得 240。
+- 基础奖励牌 +30 筹码，多倍牌 +4 倍率，玻璃牌 ×2，钢铁留手 ×1.5；只能有一种强化，红封可叠加。失效牌保留判型但不触发点数/强化/逐张效果。
+
+## 关卡与经济
+- 8 Ante 基础目标为 300/800/2000/5000/11000/20000/35000/50000，小盲 ×1，大盲 ×1.5，Boss 通常 ×2；终局 ×4。
+- 六种常规 Boss：红桃失效、黑桃失效、手牌上限 -1、无弃牌、必须出 5 张、牌型基础筹码/倍率减半（向上取整）；Ante 1–6 不重复，Ante 7 重用随机一种，8 为终局。
+- 奖励依次 $3/$4/$5，加剩余出牌次数，加结算前余额利息 floor(金钱/5) 上限 $5，加经济小丑收入。
+- 商店 3 张商品、2 个包；刷新起价 $5，每次加 $1，只刷新商品。卖价 floor(原价/2)，最低 $1。已持有小丑不再次出现在普通商店。
+- 购买必须同时满足余额/槽位/当前阶段；失败不修改任何状态。
+- 自定义跳盲标签：小盲跳过后下次商店刷新免费一次；大盲跳过后击败 Boss 获得 $15。Boss 不可跳过。
+- 本作小丑均为独立命名与平衡设计，具体效果文本与实现统一定义于 src/content/catalog.ts。
+- 行星：每种牌型升级 1 级，特殊牌型出现前不入随机商品池。
+- 九种塔罗：最多 3 张转红桃；最多 3 张转黑桃；最多 2 张点数 +1（A→2）；复制 1 张；销毁最多 2 张（牌组保留至少 1 张）；强化 1 张玻璃；强化 1 张钢铁；强化 1 张奖励并加红封；最多 2 张强化为多倍牌。相比初始方案增加女皇，确保多倍强化在正常游戏中可获取。
+- 消耗品仅可在等待出牌时使用；行星无需选牌，其余需按说明选牌。包内选 1 张加入库存，可以放弃；不替代已满槽位。
+- 牌组耗尽或删牌后，如果无法满足最低出牌张数，且剩余弃牌/抽牌与复制消耗品都无法恢复到所需张数，则立即失败，避免卡在无法操作的局面。
+
+## 存档与随机
+- 每个成功命令保存已提交状态，动画只播放日志；刷新不会再次结算。
+- 种子分别派生抽牌、商店、效果随机流，动画和预览不消耗随机数。
+- 初始存档版本 1，不兼容或损坏存档需提示并允许新开局；不静默覆盖。
+
+## 来源与适用范围
+- https://www.playbalatro.com/faq （主循环，已查阅）
+- https://balatrogame.fandom.com/wiki/Guide:_Activation_Sequence （社区触发阶段，已查阅；首版不含完整原作例外）
+- https://balatrogame.fandom.com/wiki/Poker_Hands （牌型资料，部分经搜索摘录；本表作为本作明确规则）
+- https://balatrogame.fandom.com/wiki/Planet_Cards （升级资料；本表作为本作明确规则）
+- https://balatrogame.fandom.com/wiki/Blinds_and_Antes （白注基础曲线，已取得表格）
+
+检索日期 2026-09-21。经济、小丑、Boss 池、跳过奖励、商店供给及塔罗范围均按上述首版规则实现，不宣称逐项与原作一致。

docs/verification.md

@@ -0,0 +1,58 @@
+# 首版验收记录
+
+日期：2026-09-21。规则版本：velvet-v1。
+
+## 已完成
+
+- TypeScript 静态检查与 Vite 生产构建通过。
+- 80 个规则/状态/存档用例通过，加 1 个固定种子对局测试，共 81 个测试。
+- 牌型测试覆盖 12 类牌型、A 高低顺子与非法绕接、牌型包含关系、计分牌顺序。
+- 计分金样覆盖加倍率与乘倍率顺序、红封与回声叠加、留手钢铁和月后、Boss 失效与钝刃、成长与牌型升级、经济先后顺序。
+- 事务覆盖重复购买、重复领奖、槽位已满、非法目标、卡包选择、跳盲标签、牌库守恒、无法出牌的死局、存档校验与恢复。
+- Chrome 浏览器交互通过：Canvas 选牌、拖拽、出牌、弃牌、刷新恢复、图鉴、小丑调序、行星使用、领奖、购买、刷新、开包、跳盲。
+- Chrome 模拟触屏通过：点击选牌、长按查看手牌、触摸拖动排序。
+- 1440×900、1280×720、932×430 视口截图检查；左侧状态与操作区域无溢出。
+- 浏览器测试最终运行无页面脚本错误。
+
+## 自然规则流程检查
+
+使用 `tests/balance.test.ts` 中的有限贪心策略，运行种子 VELVET-1 到 VELVET-16。没有修改金钱、牌面、次数或等级，仅通过正常命令操作。
+
+- 11 局通关，5 局失败。
+- VELVET-1 完成全部 24 个盲注，最高单手 72,000。
+- VELVET-5 在 Ante 4 失败；VELVET-12 到达最终 Boss 后失败。
+- 每次成功命令后检查存档结构和实例唯一性。
+
+这只证明正常规则下有可复现的胜败流程，不是人类胜率估计。贪心策略偏好对子与成长组合，不能据此宣称留手、同花等所有流派已平衡。
+
+## 界面截图
+
+- `artifacts/blind-selection.png`：正常新局盲注选择。
+- `artifacts/playing.png`：正常新局出牌界面。
+- `artifacts/joker-table.png`：固定 UI 夹具，用来验证小丑重排和行星效果；牌面经过测试设置，不是自然进程截图。
+- `artifacts/shop.png`：该 UI 夹具的商店流程。
+- `artifacts/desktop-1280.png` / `artifacts/mobile-landscape.png`：相同夹具的尺寸验收。
+
+所有截图均来自实际运行的浏览器，没有绘图替代或后期修改。
+
+## 环境与限制
+
+- Node.js 22.15.1；PixiJS 8.6.6；Vite 6.1.0；TypeScript 5.7.3。
+- 浏览器自动化使用 macOS 系统 Chrome 的独立临时上下文和 SwiftShader 软件 WebGL，不读取个人浏览器资料。
+- Headless Chrome 默认环境未提供可用 WebGL，测试显式启用软件 WebGL；产品在 WebGL 不可用时显示启动提示并保留已有存档。
+- 未测真实手机、Safari、Edge 或硬件帧率；60 FPS 仍为目标，不作为已验证结论。
+- 手机横屏使用等比缩放；文字和按钮比桌面更紧凑。竖屏提示旋转。
+- 本地存档按浏览器来源区分；未实现云同步或安装型离线缓存。
+- 首版未实现原作全部卡池、挑战解锁、无尽大数模式。
+
+## 运行命令
+
+```sh
+npm run build
+npm test
+npm run format:check
+# 先启动 npm run dev，再运行：
+npm run test:browser
+```
+
+浏览器测试采用专用临时上下文，不修改实际预览面板里的用户对局。