gamekit777 0.1.9 → 0.1.12

package/create-game/template/base/test/e2e.test.ts

@@ -4,17 +4,23 @@
    平台来自 gamekit777/dev-host，是泛型的——所有游戏共用同一份。
    服务端也是真平台那条路：浏览器里就地建表、按权重抽行、restore 还原。 */
 import { test, expect, afterEach } from 'vitest';
-import { tick } from 'svelte';
 import { createPlatform, localServer } from 'gamekit777/dev-host';
-import { defineGame } from 'gamekit777/sdk';
-import game from '../src/index.ts';
-import type { CoinFlipConfig as C, CoinFlipOutcome as O } from '../src/rules/types.ts';
+import { composeGame, defineGame } from 'gamekit777/svelte';
+import { EMPTY_ASSETS } from 'gamekit777/svelte/test';
+import def from '../game.ts';
+import zhCN from '../src/locales/zh-CN.json' with { type: 'json' };
+import en from '../src/locales/en.json' with { type: 'json' };
+import type { CoinFlip } from '../src/rules/types.ts';
+
+/* 浏览器入口平时由构建预设生成；测试里同样拼一次，走的是同一个 composeGame */
+/* happy-dom 里没有服务器可 fetch 语言包，直接给字典 */
+const game = composeGame(def, { assets: EMPTY_ASSETS.bundle(), locales: { 'zh-CN': zhCN, en } });
 
 const live: { destroy(): void }[] = [];
 afterEach(() => { while (live.length) { try { live.pop()!.destroy(); } catch { /* 已经拆过了 */ } } });
 
 const boot = async () => {
-  const p = createPlatform<C, O>(game);
+  const p = createPlatform<CoinFlip>(game);
   // 和真实宿主一样先握手：余额、注额区间都在服务端那边
   await p.init();
   const el = document.createElement('div');
@@ -22,7 +28,7 @@ const boot = async () => {
   const inst = await game.mount(p.host(), el);
   live.push(inst);
   inst.status.subscribe(s => p.setGameStatus(s));
-  p.bindGame({ present: r => inst.present(r), status: () => p.game });
+  p.bindGame(inst);
   return { p, el, inst };
 };
 
@@ -31,7 +37,7 @@ test('挂载 → 下注 → 演完 → 余额按 payout 变化', async () => {
   expect(p.game.phase).toBe('idle');
   expect(el.querySelector('.coin')).toBeTruthy();
 
-  p.setView({ reducedMotion: true });
+  p.setSettings({ reducedMotion: true });
   p.setBet(1000);
 
   const before = p.balance;
@@ -42,12 +48,11 @@ test('挂载 → 下注 → 演完 → 余额按 payout 变化', async () => {
 test('平台改配置 → 游戏画布跟着变', async () => {
   const { p, el } = await boot();
   p.requestConfig({ side: 'tails' });
-  await tick();
   expect(el.querySelector('.head b')?.textContent).toBe('反');
 });
 
 test('表模型：还原出的赔付必须等于平台记账，差一分也要拦住', async () => {
-  const srv = localServer<C, O>({ spec: game, sims: 500 });
+  const srv = localServer<CoinFlip>({ spec: def, sims: 500 });
   const before = (await srv.init()).balance;
   const r = await srv.place({ config: { side: 'heads' }, bet: 1000, clientSeed: 'c' });
   expect(r.ok).toBe(true);
@@ -57,23 +62,22 @@ test('表模型：还原出的赔付必须等于平台记账，差一分也要
   expect(r.round.checks.every((c) => c.ok)).toBe(true);
 
   /* 同一份清单，只把 restore 换成会多赔一分的：钱已经按表记了，演出不能演 */
-  const tampered = defineGame<C, O>({ ...game, restore: (i) => { const x = game.restore(i); return { ...x, payout: x.payout + 1 }; } });
-  const bad = localServer<C, O>({ spec: tampered, sims: 500 });
+  const tampered = defineGame<CoinFlip>({ ...def, restore: (i) => { const x = def.restore(i); return { ...x, mult: x.mult + 0.01 }; } });
+  const bad = localServer<CoinFlip>({ spec: tampered, sims: 500 });
   await bad.init();
   const v = await bad.place({ config: { side: 'heads' }, bet: 1000, clientSeed: 'c' });
   expect(v.ok).toBe(false);
-  if (!v.ok) expect(v.error).toMatch(/不符/);
+  if (!v.ok) expect(v.error).toMatch(/分叉|不符/);
 });
 
 test('同页两个实例互不干扰', async () => {
   const a = await boot();
   const b = await boot();
-  a.p.setView({ reducedMotion: true });
-  b.p.setView({ reducedMotion: true });
+  a.p.setSettings({ reducedMotion: true });
+  b.p.setSettings({ reducedMotion: true });
 
   a.p.requestConfig({ side: 'heads' });
   b.p.requestConfig({ side: 'tails' });
-  await tick();
   expect(a.el.querySelector('.head b')?.textContent).toBe('正');
   expect(b.el.querySelector('.head b')?.textContent).toBe('反');
 
@@ -82,3 +86,45 @@ test('同页两个实例互不干扰', async () => {
   expect(b.p.balance).toBe(100_000);          // b 的钱包没被动过
   expect(b.p.game.phase).toBe('idle');
 });
+
+test('游戏声明的设置从 host.settings 进来：关掉弹窗就不弹，开着赢了就有牌子', async () => {
+  const { p, el } = await boot();
+  p.setSettings({ reducedMotion: true, toast: false } as never);
+  p.setBet(1000);
+  for (let i = 0; i < 8; i++) {
+    await p.playOne();
+    expect(el.querySelector('.bigwin:not([hidden])')).toBeNull();
+  }
+  p.setSettings({ toast: true } as never);
+  let won = false;
+  for (let i = 0; i < 12 && !won; i++) {
+    await p.playOne();
+    if ((p.game.lastPayout ?? 0) > 0) {
+      won = true;
+      /* 大奖牌是按需加载的分块（mount 时预取）：测试里第一次要现编译，等它到位 */
+      for (let t = 0; t < 50 && !el.querySelector('[data-gk-layer] .bigwin.t0'); t++) { await new Promise((r) => setTimeout(r, 20)); }
+      expect(el.querySelector('[data-gk-layer] .bigwin.t0')).toBeTruthy();
+    }
+  }
+  expect(won).toBe(true);
+});
+
+test('语言跟着 settings.locale 走', async () => {
+  const { p, el } = await boot();
+  p.setSettings({ locale: 'en' });
+  await new Promise((r) => setTimeout(r, 50));
+  expect(el.querySelector('.foot')?.textContent).toMatch(/Pick a side/);
+});
+
+test('destroy 之后容器干净、没有残留的定时器把状态写回来', async () => {
+  const { p, el, inst } = await boot();
+  p.setSettings({ reducedMotion: true });
+  p.setBet(1000);
+  await p.playOne();
+  inst.destroy();
+  live.pop();
+  expect(el.childNodes.length).toBe(0);
+  expect(el.className).toBe('');
+  await new Promise((r) => setTimeout(r, 1000));
+  expect(el.childNodes.length).toBe(0);
+});

package/create-game/template/base/test/present.test.ts

@@ -0,0 +1,44 @@
+/* 编排的单测：不挂 App、不等时间。结果用清单的 round 按种子出，和平台给的一样；drain 直接看结果把一局演完，断言画面上是什么 */
+import { test, expect } from 'vitest';
+import { defineGame } from 'gamekit777/sdk';
+import { headless, drain } from 'gamekit777/svelte/test';
+import manifest from '../game.ts';
+import { Game } from '../src/game.svelte.ts';
+
+const def = defineGame(manifest);
+const at = (side: 'heads' | 'tails', nonce: number) =>
+  def.round({ config: def.normalize({ side }), bet: 1000, seed: { server: 'present', client: 'c', nonce } });
+/** 找一局赢的 / 输的 */
+const find = (win: boolean) => { for (let n = 0; ; n++) { const r = at('heads', n); if (r.outcome.win === win) return r; } };
+
+test('挂载时：正面朝上、没有上一局', () => {
+  expect(headless(def, Game).state).toEqual({ face: 'heads', last: null });
+});
+
+test('一局之后：硬币停在开出的那面，记下这一局', async () => {
+  const g = headless(def, Game);
+  const r = at('tails', 1);
+  await drain(g, r);
+  expect(g.state).toEqual({ face: r.outcome.landed, last: r.outcome });
+});
+
+test('赢了弹牌子、响赢的音；输了只响输的音', async () => {
+  const win = await drain(headless(def, Game), find(true));
+  expect(win.map((c) => c.name)).toEqual(expect.arrayContaining(['win', 'plate']));
+  const lose = await drain(headless(def, Game), find(false));
+  expect(lose.map((c) => c.name)).toContain('lose');
+  expect(lose.map((c) => c.name)).not.toContain('plate');
+});
+
+test('关掉弹窗设置就不弹牌子', async () => {
+  const fx = await drain(headless(def, Game, { settings: { toast: false } }), find(true));
+  expect(fx.map((c) => c.name)).not.toContain('plate');
+});
+
+test('收掉上一局（作废）：结果不作数，硬币不动', async () => {
+  const g = headless(def, Game);
+  const r = at('tails', 4);
+  await drain(g, r);
+  g.invalidate();
+  expect(g.state).toEqual({ face: r.outcome.landed, last: null });
+});

package/create-game/template/base/vitest.config.ts

@@ -4,7 +4,7 @@ import { svelte } from '@sveltejs/vite-plugin-svelte';
 /* 测试必须走 Vite 管线：gamekit777/runtime 的资源注册表用了 import.meta.glob（Vite 特性，按 root 找 src/assets/），
    组件和 .svelte.ts 里的 runes 也要 Svelte 编译器处理。 */
 export default defineConfig({
-  plugins: [svelte({ hot: false })],
+  plugins: [svelte({ hot: false, compilerOptions: { runes: true } })],
   test: { environment: 'happy-dom', include: ['test/**/*.test.ts'], testTimeout: 30_000 },
   resolve: { conditions: ['browser'] }
 });

package/create-game/template/overlay/AGENTS.md

@@ -0,0 +1,156 @@
+# __TITLE__（`__ID__`）— 写给 AI 的游戏开发指南
+
+<!-- 规则只写在这一份里；CLAUDE.md 只是 `@AGENTS.md` 一行引用。细节按需读 node_modules/gamekit777/docs/ 下的文件（随库的版本走，不在项目里） -->
+
+这是一个 GameKit 游戏目录。平台**不执行游戏代码**：打包时用你的 `round()` 采样出一张权重表，
+运行时平台按权重抽一行、查表赔付，浏览器用你的 `restore()` 把那一行还原成演出。
+
+先读这份文件，再读 `game.ts`。这个目录是平台参考游戏（猜正反面的那个）的**完整拷贝**换了名字——它能跑、能建表、能发布；
+从能跑的东西开始改，不要从零写。源码里带「改成你自己的游戏时」的注释就是给你的路标。
+
+## 一条原则：演出必须能回放
+
+一局的画面只能是「表里那一行」的函数。同一行，在下注当场、在历史列表里点开、从分享链接进来、换一台设备，
+演出来的必须是同一局：同样的牌、同样的连线、同样的赔付、同样的粒子和台词。下面所有约束都是这一条推出来的：
+
+- **`round()` 是纯函数**，随机只来自注入的 rng。作者机器采样、玩家浏览器还原、审计脚本复算，三处逐位一致。
+- **`restore()` 把一行还原成 `RoundResult`**，返回的 `payout` 必须恰好等于 `(bet / 100) × payoutCenti`，对不上就 `throw`、不演出。
+- **`present(result)` 只看 `result`**，不看上一局、不看余额、不看玩家当下的设置。回放是在一个全新的实例里跑，那里什么都没有。
+- **装饰性随机也不许用 `Math.random`**（粒子角度、台词抽签）：编排里 `ctx.rand`——按这一局的种子播种，回放时一模一样；局外（发呆、交互）用 `game.ambient`。
+  构建时扫源码，出现 `Math.random` / `crypto.getRandomValues` 直接构建失败。
+
+「玩家看到连成三条线，余额却没动」「分享出去的一局，别人看到另一副牌」——这类 bug 完全静默、最伤信任，所以每一条都有工具兜着：
+`scripts/verify.ts` 把 `Math.random` / `crypto` 换成会抛的桩，平台在演出前逐分比对 payout，`case_run` 盯任何结果漂移。
+
+## 目录
+
+```
+game.ts              唯一入口：export default { meta, schema, settings, modes, book, paytable, round, restore, view } satisfies GameManifest<CoinFlip>。纯对象、只有类型导入。Node 与浏览器都 import 它，不能碰 DOM / Svelte
+src/rules/           纯逻辑：schema、settings（as const，类型从它们反推）、restore、常量、types.ts（一个接口 CoinFlip 描述整个游戏）。零 DOM、零自取随机
+src/index.ts    演出模块：import 全局样式、把游戏类 Game 作为默认导出，game.ts 的 view 惰性指向它
+src/present.ts  definePresent({ tempo, run, settle, concurrent?, interval? })：一局怎么演。run / settle 是 function*，要等什么就 yield 什么（ctx.delay / tween / 子时间线），只写 game.state 和发效果 ctx.fx.<名字>()
+src/effects.ts  效果表 defineEffects（声音、keyframes、组件、粒子、台词）与关键帧表 defineKeyframes（状态外观）：每样演出只在这里声明一次
+src/use-game.ts      export const useGame: () => Instance<CoinFlip> = useGame（框架的泛型版钉上类型）
+src/game.svelte.ts   游戏类 extends RoundGame<CoinFlip>（多阶段用 StagedGame、带台面用 BoardGame）：App、演出把手、两张表、initial（game.state 的初值）是它的静态字段；类上只放三样：声明（静态字段、锚点把手）；编排和组件都要用的派生与改 state 的方法；玩家在画布上的选择与交互。state / config / settings 的字段不再包 getter（模板直接读 game.state.x），只有组件用的尺寸、颜色、格式化写在组件里。平台状态（game.config / settings / run / stage）直接读，要随它变的用 $derived，生命周期钩子 onMount / onReset / onDestroy 是它上面的方法
+src/components/      画面。子组件一律 useGame()（src/use-game.ts：框架的 useGame 钉上 CoinFlip 类型再导出），不 import 状态对象
+src/locales/         文案：zh-CN.json、en.json，扁平 key-value，组件用 t(key, params)
+src/assets/          图片、声音随意放，import 就进清单。加载、进度、预取见 node_modules/gamekit777/docs/assets.md
+scripts/verify.ts    数学回归：纯度、确定性、RTP、分布
+test/present.test.ts 编排的单测：headless + drain 直接看结果演完一局，断言 game.state 与调过的效果。不挂载、不等时间
+test/e2e.test.ts     happy-dom 里跑完整一局
+test/conformance.test.ts  演出层一致性套件，一行引入；bun run test 强制跑，不要删
+studio/cases.jsonl   case 库（进版本控制），studio 维护
+.studio/             采样缓存与建好的表，按规则指纹分目录，可随手删
+```
+
+`src/index.ts` 是演出模块，不是浏览器入口——入口由构建预设生成（虚拟模块，静态 import 它）。**改名**只改 `game.meta.json` 的 `id`（小写短横线，同时是平台上的 slug、产物目录名、CSS 命名空间）和 `title`。
+`gameId` 是平台第一次发布时分配并写回的身份，不要手改、不要删。已发布过的 slug 不能改——那是另一个游戏。
+
+## 硬约束
+
+- `round({ config, rng })` 同步纯函数、只用注入的 rng、`rng.fork('tag')` 隔开子系统，只回 `{ outcome, mult }`；`mult` 最多两位小数。钱由框架算（`bet / 100 × round(mult × 100)`），游戏不碰。
+- `restore()` 同样只回 `{ outcome, mult }`；框架拿 `mult` 和表里那一行的 `payoutCenti` 核对，对不上抛错不演。
+- 一个接口描述整个游戏：`interface CoinFlip { config; outcome; settings; state; game }`，config / settings 从 `as const satisfies ConfigSchema / SettingsSchema` 的声明用 `InferConfig` / `InferSettings` 反推，不手写。所有泛型只写这一个名字。
+- 影响结果的字段进 `schema`；只影响演出的进 `settings`；影响赔付分布的字段写进 `modes`。三者的键互不重叠。
+- 不写 `normalize` / `validate` / `modeOf`，不加版本号。**已发布过的 mode，发牌逻辑、book 编解码、取整方式都不能再改**，要改就换 slug。
+- **编排是生成器**：`*run(ctx, g, r)`、`*settle`、`*idle`，要等什么就 `yield` 什么——`yield ctx.delay(ms)` / `ctx.tween(…)` / 子时间线；辅助函数也写 `function*`，调用处 `yield* helper(…)`（漏了 `yield*` 它一行都不跑）。不写 `async` / `await` / `setTimeout` / `sleep`：快进要不等、作废要不再往下跑，自己写的等做不到。
+- 装饰随机只用 `rand`（`ctx.rand` / `game.ambient`），`Math.random` 构建期拦。
+- **演出里的每样东西先分类**（跳过它终态会不会错？）：画面上是什么写 `game.state`；状态外观进关键帧表、`class:` 打开；一次性事件进效果表、`ctx.fx.<名字>()`。详见 `node_modules/gamekit777/docs/view.md`「先分清三类东西」。
+- **画面上是什么全在 `game.state`**（结果、翻到一半的那面、在飞的牌的坐标、滚到一半的数字、在落的球），**编排只写它和发效果**：直接给游戏类的字段赋值（`g.shown = 1`）开发期当场抛。
+  一致性套件会拿同一局按正常演完、演到一半快进、直接看结果各演一遍，比最后的 `game.state`，不一样就报字段。所以：结果无条件写（不包在 `if (!ctx.quiet())` 里）；只在动画中途有意义的字段演完回到固定值；画面上的数字照抄 outcome 里现成的值，不在编排里重算；效果的钩子（`effect.data` 的 `end`）不写 state。
+- **演出里触发效果只用 `ctx.fx`**：它过这一局的闸、按这一局派发随机流。`game.fx` 是局外的把手：模板里 `{@attach game.fx.x}` 绑目标、发呆与交互时触发。
+- **一次演几局由 `definePresent({ concurrent, interval })` 定**：默认 1（新局开始时清场）；连着下的游戏（Plinko）写 `concurrent: Infinity, interval: 120`，演出中也能下注。
+  这时每局自己的东西（球、尾迹）放进 `game.state` 里的数组、演完移除，共享的盘面状态（发光的格子）按局合并。详见 `node_modules/gamekit777/docs/view.md`「同时演几局」。
+- **动画先定级别**：有没有别的东西要等它演完？有就是编排，写进演出把手的时间线；没有就是状态外观，演出把手只写状态，过渡交给组件。一排会挪动的格子（开奖历史、历史牌）用框架的 `Queue`，不用 Svelte 的 `animate:` / `transition:`。一个元素的一个属性只有一个主人，两样都要动就拆两层。详见 `node_modules/gamekit777/docs/view.md`「一个动画归哪一级」。
+- 画布里只改演出状态、不经平台的交互（切视图、选面值、翻页）在处理函数里调 `game.touch()`，否则空闲编排可能刚好到点，把玩家刚打开的东西收回去。
+- 声音、动画、粒子、台词只经效果表：不手写 `node.animate`、不自己注 `@keyframes`、不 `new AudioContext`、不碰 `<audio>`。它们因此自动服从快进、追赶、直接看结果、倍率与减弱动效。
+- **效果不用判 `ctx.quiet()`**：快进、从后台回来追赶时框架丢掉非 always 的效果；结算要看到、听到的标 `always`（声明时或调用处）。粒子没有 always。`ctx.quiet()` 只用来跳过游戏自己的装饰（压牌前多停一下），结果不许看它决定写不写。
+- 不为触发动画在状态里养计数器（`shakeToken++`）：模板里 `{@attach game.fx.shake}` 绑目标，present 里 `ctx.fx.shake()` 就播。
+- 要让框架知道一个元素，只有一种写法：`{@attach 把手}`。动画目标挂效果把手（`{@attach game.fx.shake}`、`{@attach game.fx.peg.at(k)}`）；粒子、飘字的位置挂锚点把手（游戏类上 `readonly ticket = this.stage.anchor()` / `cells = this.stage.anchors()`，模板 `{@attach game.ticket}`，present 里 `at: game.ticket.or('center')`，`or` 必填）。不 `querySelector`、不在模块里存元素。
+- 读 DOM 只经锚点把手：为 state 量坐标在协程里直接 `g.x.box()`（舞台逻辑像素）或 `g.x.el`，写完 state 马上量就是新的（框架先刷新），量不到（单测里没有 DOM）是 null 要容忍；装饰写成 `effect.dom`（框架在这一批刷新之后执行）。量出来的值只管画在哪，不决定 state 里有什么：state 里的列表按固定上限裁，一排摆得下几张是组件按量到的宽度决定的（摆不下的藏起来）。框架保证 keyframes / 粒子这类读 DOM 的效果在刷新之后执行，所以先写状态、再 fire 总是对的。
+- 只写 Svelte 5 runes（`$state` / `$props` / `$derived` / `onclick`）：编译器钉了 `runes: true`，`export let`、`$:`、`on:click` 直接编译报错。
+- 所有 import 都写 `gamekit777/svelte`（测试多一个 `gamekit777/svelte/test`）。`game.ts` / `rules/` 在 Node 里跑，那里只能有 `import type`——清单是纯对象，`round` 收到的 `input.config` 已填满、`input.rng` 已播好，不需要任何函数。例外是 `scripts/verify.ts` 与测试（要 `defineGame` / `createRng` 的值），从 `gamekit777/sdk` 拿。`gamekit777/sdk/platform` 与 `gamekit777/runtime` 是平台和工具的面，游戏里不出现。
+- 模块级不留可变状态；**不许直接碰 `window` / `document`，不许裸写 `setTimeout` / `addEventListener` / `new ResizeObserver`**（构建期拦）：要重叠就用子时间线 `ctx.timeline()`、局外的延迟用 `g.scheduler.after`（按实例时钟），监听、观察器用 `g.addEventListener / g.observe`（返回清理句柄），作废或 `destroy` 时框架统一清。平台会在同一个沙箱里装下一个游戏，漏一个就累积。
+  框架的部分 `invalidate()` 已清；自己加的定时器从 `onMount` 返回 cleanup。一致性套件会抓。
+- 两块舞台都要支持：桌面 900×771、手机 450×H；安全区外不放交互。
+- reset 之后画面必须是开局前的样子：框架把 `game.state` 放回开局前、再调 `onReset()` 收掉上一局（只清这一局的结果，跨局要留的——战绩、硬币停在哪面——留着；不写 `onReset` 就整个回到 `initial`）。画面上的东西都在 state 里才归得了位。平台切换、回放、离开都会 reset，`preview_perf` 也按 reset 后的画面量残留。本场战绩这类跨局的 UI 要有上限。
+- 少创建销毁 DOM：固定槽位数组代替 push / shift，状态切换用 class 不用 `{#if}`，`{#each}` 必带稳定 key，一次性效果进效果表（组件型效果挂上不卸，槽位复用）。
+- 资源只经 vite import 引用，不在数据里写路径查表；`() => import()` 只给玩家主动操作才出现的 UI（规则弹窗、二级界面、极少触发的大场面），一局主流程里的东西不拆。
+
+## 演出层（最小示例；三类东西、时间线、效果选项、反例清单见 `node_modules/gamekit777/docs/view.md`）
+
+```ts
+// src/effects.ts —— 每样演出只声明一次
+export const effects = defineEffects({
+  flip:  effect.sound(sound.tone({ f: 880, dur: 0.05 })),                                     // 过程效果：快进、追赶时框架丢掉
+  win:   effect.sound({ src: winMp3, fallback: sound.chord({ notes: [659, 784, 988], step: 0.08, dur: 0.28 }) }, { always: true }),   // 结果效果
+  shake: effect.keyframes({ ms: 320, frames: [...] }),                                         // 元素补间：模板 {@attach g.fx.shake} 绑目标，ctx.fx.shake() 播
+  linein: effect.keyframes({ ms: 160, frames: [{ opacity: 0 }, { opacity: 1 }] }),              // 或 {@attach g.fx.linein.on(token)}：token 变了就播
+  plate: effect.builtin('big-win', { always: true }),                                          // 内置牌子，画在框架的覆盖层上
+  spark: effect.particle('burst', { count: 16 }),                                              // 粒子：纯装饰，没有 always
+  say:   effect.data<string>({ slots: 1, hold: 800 }),                                        // 台词：模板读 game.fx.say.current
+});
+export const keyframes = defineKeyframes({
+  spin: { ms: 420, frames: [{ transform: 'scale(1)' }, { transform: 'scale(1.1)', offset: 0.5 }, { transform: 'scale(1)' }] },   // 状态外观：class:spin
+});
+
+// src/game.svelte.ts —— 画面上是什么在 game.state（形状写在 rules/types.ts 的 state 键），模板直接读；类上只放声明、共用的派生、画布交互
+export class Game extends RoundGame<CoinFlip, typeof effects, typeof keyframes> {
+  static override App = App;                                                 // 演出侧只声明这一个类：App、演出把手、两张表都是静态字段
+  static override presenter = presenter;
+  static override effects = effects;
+  static override keyframes = keyframes;
+  static override initial(): CoinFlip['state'] { return { face: 'heads', last: null }; }   // game.state 的初值
+  readonly coin = this.stage.anchor();                                       // 锚点把手：模板 {@attach game.coin}
+  protected override onReset(): void { this.state.last = null; }            // 收掉上一局：结果不作数了，硬币停在哪面还是哪面
+}
+
+// src/present.ts —— 生成器；辅助协程也写 function*，调用处 yield*
+function* celebrate(ctx: PresentCtx<CoinFlip, T>) {
+  ctx.fx.say(ctx.rand.pick(['漂亮', '到手']));                                                  // ctx.rand 回放一致
+  yield ctx.delay(ctx.T.pause);
+  ctx.fx.plate({ tier: 0, mult: '2.00×', amount: '+2.00' });                                  // 效果表里标了 always：快进也放
+}
+type T = { flip: number; pause: number };
+export const presenter = definePresent<CoinFlip, T>({
+  tempo: { normal: { flip: 100, pause: 90 }, turbo: { flip: 40, pause: 50 }, reduced: { flip: 0, pause: 90 } },
+  *run(ctx, g, r) {
+    for (let i = 0; i < 6; i++) {
+      g.state.face = i % 2 ? 'heads' : 'tails';                  // 翻动中途的那一面也写 state；最后一定落在开出的那面
+      ctx.fx.flip();                                             // 效果：不判 quiet
+      yield ctx.delay(ctx.T.flip);                               // 要等就 yield：按实例时钟、跟随倍率、后台时停住，快进不等，作废不再往下跑
+    }
+    g.state.face = r.outcome.landed;                             // 结果：无条件写
+    g.state.last = r.outcome;
+  },
+  *settle(ctx, g, r) {
+    if (r.outcome.win) {
+      ctx.fx.win();
+      ctx.fx.shake(undefined, { always: true });                           // 播到 {@attach g.fx.shake} 绑的元素上；没绑就不播
+      ctx.fx.spark({ at: g.coin.offset({ offsetY: -20 }).or('center') });       // 锚点：元素不在时退到哪儿，or 必填
+      yield* celebrate(ctx);
+    }
+  },
+});
+```
+
+```svelte
+<!-- src/components/App.svelte -->
+<script lang="ts">const { game } = useGame();</script>
+<div class="coin" class:spin={game.rounds.live} {@attach game.coin} {@attach game.fx.shake}>{game.state.face}</div>
+<p class="line" {@attach game.fx.linein.on(game.fx.say.current)}>{game.fx.say.current ?? ''}</p>
+<style>.coin.spin{animation:var(--a-spin) ease-in-out infinite}</style>
+```
+
+`{@attach}` 只接受 keyframes 效果的把手和锚点把手，挂到别的效果上是类型错误；把手是对象引用，名字写错也是类型错误。
+`test/conformance.test.ts` 已带：`for (const c of conformanceCases(game)) test(c.name, c.run)`。挂了就是用了框架之外的等待 / 随机 / 定时器 / 声音动画，或者某条路演出来的 `game.state` 不一样（报错给出字段），每条用例挂了意味着什么见 `node_modules/gamekit777/docs/view.md`「一致性测试」。
+`test/present.test.ts` 已带：`const g = headless(def, Game); await drain(g, r); expect(g.state)…`，改了编排就改它，写法见 `node_modules/gamekit777/docs/view.md`「编排的单测」。
+
+## 创作时的规则
+
+- **调试只用预览**：`preview_state` / `preview_set` / `preview_play`。没有预览连着它们会自己拉起无头浏览器，不要去开 studio 页面，也不要自己起浏览器。桌面和手机两种布局都要验过。
+- **演出改完跑 `preview_perf`**：默认 CPU 节流 6 倍压测（中低端手机）。泄漏（reset 后节点、监听、堆在后半程还涨）是硬结论，必须修，`publish` 前还会快进复查一遍，不过就发不了；每局增删节点、重排、掉帧只报数，和上一次比，别为数字牺牲演出。
+- **想让作者看效果就给 studio 页面地址**（`game_info` 里有），不要描述画面。作者打开页面后，预览命令会自动改发到页面里的机台，作者看到的就是你在演的。
+- **case 要早存**：规则能跑起来就用 `case_add` 存几条有代表性的局面；遇到问题先存 case 固定住再改。
+- **不主动发布**。`publish` 不可逆，等作者明确说了再用。
+- 遇到不确定的：清单字段与 round 看 `node_modules/gamekit777/docs/contract.md`，能不能打表看 `node_modules/gamekit777/docs/tables.md`，演出、设置、文案、舞台看 `node_modules/gamekit777/docs/view.md`，资源怎么引、什么该动态 import 看 `node_modules/gamekit777/docs/assets.md`，工具怎么用看 `node_modules/gamekit777/docs/workflow.md`。

package/create-game/template/overlay/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md