gamekit777 0.1.12 → 0.1.14

package/create-game/template/base/src/components/App.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   /* 游戏的根组件。平台化之后它只有画面——
      注额、押哪一面、音效、极速都是平台该渲染的 UI。
+     抛出中硬币一鼓一缩是循环表的 spin（src/effects.ts），挂在 .coin 上、在演时播；不写 CSS animation，减弱动效时框架自己停。
 
      实例经 context 往下传（gamekit777/svelte 的 composeGame 设好），子组件一律 useGame()，
      不 import 任何状态对象，这样同页挂两个实例才不会互相污染。
@@ -16,7 +17,7 @@
 <div class="game">
   <p class="head">{@html t('head', { side: `<b>${label(game.config.side)}</b>`, mult: MULT.toFixed(2) })}</p>
 
-  <div class="coin" class:spin={game.rounds.live} aria-live="polite">
+  <div class="coin" {@attach game.loops.spin.when(game.rounds.live)} aria-live="polite">
     <span>{label(game.state.face)}</span>
   </div>
 
@@ -44,11 +45,7 @@
   .coin{display:grid;place-items:center;width:104px;height:104px;border-radius:50%;
     background:var(--mark);color:#241A00;font-family:var(--num);font-size:38px;font-weight:700;
     box-shadow:inset 0 -6px 0 rgba(0,0,0,.18)}
-  /* 时长与关键帧来自关键帧表（src/effects.ts 的 spin），框架注入成 --a-spin */
-  .coin.spin{animation:var(--a-spin) ease-in-out infinite}
   .foot{margin:0;min-height:1.5em;font-size:13px;color:var(--dim)}
   .foot.win{color:var(--win);font-weight:700}
   .foot.lose{color:var(--lose)}
-
-  @media (prefers-reduced-motion:reduce){.coin.spin{animation:none}}
 </style>

package/create-game/template/base/src/effects.ts

@@ -1,16 +1,21 @@
-/* 效果表与关键帧表。翻动音是过程效果；输赢音与赢面牌子标 always，快进后也要听到、看到。
+/* 效果表与循环表。翻动音是过程效果；输赢音与赢面牌子标 always，快进后也要听到、看到。
+   动画不要用 JS 逐帧驱动（跨源 iframe 里 iOS 会把 rAF 限到 30fps），都交给 WAAPI：
+     发生一次的（弹一下、翻开、飞过去）→ 效果表里的 effect.keyframes，位置演出时才知道就把 frames 写成 payload 的函数；
+     处在某个状态期间一直循环的（呼吸、旋转、闪烁）→ 循环表 defineLoops，模板里 {@attach game.loops.x.when(条件)}；
+     只有数字读数、必须进 state 的量才用 ctx.tween。
    改成你自己的游戏时：哪些东西该进哪张表、always 怎么定，见 node_modules/gamekit777/docs/view.md「先分清三类东西」。 */
-import { sound, effect, defineEffects, defineKeyframes } from 'gamekit777/svelte';
+import { sound, effect, defineEffects, defineLoops } from 'gamekit777/svelte';
+import { T } from './tempo.ts';
 
 export const effects = defineEffects({
   flip: effect.sound(sound.tone({ f: 880, dur: 0.05, type: 'triangle', gain: 0.08 })),
   win: effect.sound(sound.chord({ notes: [659, 784, 988], step: 0.08, dur: 0.28, gain: 0.12 }), { always: true }),
   lose: effect.sound(sound.tone({ f: 220, dur: 0.18, type: 'sine', gain: 0.1, slide: 140 }), { always: true }),
   /** 赢了弹一下就走。tier 0 只有牌子，不遮画面、不用点；自动模式连赢也只是连弹两次 */
-  plate: effect.builtin('big-win', { always: true }),
+  plate: effect.builtin('big-win', { always: true, ms: T.linger }),
 });
 
-export const keyframes = defineKeyframes({
-  /** 抛出中：硬币一鼓一缩。状态驱动（class:spin） */
-  spin: { ms: 420, frames: [{ transform: 'scale(1)' }, { transform: 'scale(1.1)', offset: 0.5 }, { transform: 'scale(1)' }] },
+export const loops = defineLoops({
+  /** 抛出中：硬币一鼓一缩（App 里 {@attach game.loops.spin.when(game.rounds.live)}） */
+  spin: { ms: 420, easing: 'ease-in-out', frames: [{ transform: 'scale(1)' }, { transform: 'scale(1.1)', offset: 0.5 }, { transform: 'scale(1)' }] },
 });

package/create-game/template/base/src/game.svelte.ts

@@ -5,16 +5,16 @@
    做成可实例化的类而不是模块级单例：同页挂两个实例时各自一套状态。 */
 import { RoundGame } from 'gamekit777/svelte';
 import type { CoinFlip, CoinFlipState } from './rules/types.ts';
-import { effects, keyframes } from './effects.ts';
+import { effects, loops } from './effects.ts';
 import App from './components/App.svelte';
 import { presenter } from './present.ts';
 
-export class Game extends RoundGame<CoinFlip, typeof effects, typeof keyframes> {
-  /* 效果表与关键帧表交给基类：写成静态字段，不用写构造函数（框架每次 mount new 一个） */
+export class Game extends RoundGame<CoinFlip, typeof effects, typeof loops> {
+  /* 效果表与循环表交给基类：写成静态字段，不用写构造函数（框架每次 mount new 一个） */
   static override App = App;
   static override presenter = presenter;
   static override effects = effects;
-  static override keyframes = keyframes;
+  static override loops = loops;
 
   /** 挂载时的画面：正面朝上、没有上一局 */
   static override initial(): CoinFlipState { return { face: 'heads', last: null }; }

package/create-game/template/base/src/index.ts

@@ -1,5 +1,5 @@
 /* 演出模块：game.ts 的 view 惰性指向这里，浏览器入口由构建预设生成、经 gamekit777/svelte 的 composeGame 挂起来。
-   一个游戏在演出侧只声明一个类（game.svelte.ts）：App、演出把手、效果表、关键帧表都是它的静态字段。
+   一个游戏在演出侧只声明一个类（game.svelte.ts）：App、演出把手、效果表、循环表都是它的静态字段。
    这个文件 import 了样式、间接 import 了 Svelte 组件，Node 侧永远不会执行它。 */
 import './styles/global.css';
 export { Game as default } from './game.svelte.ts';

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

@@ -1,32 +1,28 @@
 /* 演出：把已经算好的结果播出来。
 
-   判定一行都不在这里——outcome 是传进来的。turbo / reducedMotion 只换节拍表，改不了结果，
+   判定一行都不在这里——outcome 是传进来的；极速、减弱动效由框架施加在演出上，改不了结果，
    因为它们根本不在 round() 的入参里。
-   run 是生成器：yield 出去的是「要等什么」，什么时候接着跑由框架定——快进、直接看结果时不等，局被作废时不再往下跑。
+   run 是生成器：yield 出去的是「要等什么」，什么时候接着跑由框架定——快进、直接看结果、减弱动效时不等，局被作废时不再往下跑。
    只写 g.state 和发效果。翻动中途的那一面也写在 state 里，演完一定落在开出的那面：正常演、快进、直接看结果，最后的 state 一样（一致性套件验）。
+   节拍是 tempo.ts 里的常数，这里不看 turbo / reducedMotion。
    装饰性随机只能来自 ctx.rand（按这一局的种子播种，回放一模一样）；这个游戏暂时没用到。 */
 import { definePresent } from 'gamekit777/svelte';
 import type { CoinFlip } from './rules/types.ts';
+import { T } from './tempo.ts';
 
 const money = (minor: number): string => (minor / 100).toFixed(2);
 
-export const presenter = definePresent<CoinFlip, { flip: number; total: number; linger: number }>({
-  /* flip：翻一下多久；total：翻动多久再定格；linger：赢面牌子停多久。reduced 下不翻动，牌子只是出现再消失 */
-  tempo: {
-    normal:  { flip: 90, total: 800, linger: 1600 },
-    turbo:   { flip: 90, total: 320, linger: 1000 },
-    reduced: { flip: 90, total: 0,   linger: 900 },
-  },
+/* 翻动几下再定格。次数只是节奏（总时长 / 翻一下多久），不占用可复现的随机数 */
+const STEPS = Math.max(2, Math.round(T.total / T.flip));
+
+export const presenter = definePresent<CoinFlip>({
   *run(ctx, g, r) {
     const o = r.outcome;
-    /* 翻动几下再定格。翻动次数只是节奏（总时长 / 翻一下多久），不占用可复现的随机数 */
-    const steps = Math.max(2, Math.round(ctx.T.total / ctx.T.flip));
-    if (ctx.T.total > 0) {
-      for (let i = 0; i < steps; i++) {
-        g.state.face = i % 2 === 0 ? 'tails' : 'heads';
-        ctx.fx.flip();
-        yield ctx.delay(ctx.T.total / steps);
-      }
+    /* 翻面是离散的几下（每 90ms 换一次字），不是逐帧驱动的动画；硬币一鼓一缩是循环表的 spin（WAAPI） */
+    for (let i = 0; i < STEPS; i++) {
+      g.state.face = i % 2 === 0 ? 'tails' : 'heads';
+      ctx.fx.flip();
+      yield ctx.delay(T.total / STEPS);
     }
     g.state.face = o.landed;
     g.state.last = o;
@@ -34,8 +30,8 @@ export const presenter = definePresent<CoinFlip, { flip: number; total: number;
   settle(ctx, g, r) {
     const o = r.outcome;
     (o.win ? ctx.fx.win : ctx.fx.lose)();
-    /* 牌子是余韵，present 不等它——弹窗不该拖慢下一注（自动模式尤其）；下一局开始时框架会清掉 */
-    /* 游戏自己声明的设置在 g.settings 里（和平台内置的 turbo / sound 合在一起） */
-    if (o.win && g.settings.toast) ctx.fx.plate({ tier: 0, mult: `${r.multiplier.toFixed(2)}×`, amount: `+${money(r.payout)}` }, { ms: ctx.T.linger });
+    /* 牌子是余韵，present 不等它——弹窗不该拖慢下一注（自动模式尤其）；停多久写在效果表里，下一局开始时框架会清掉 */
+    /* 游戏自己声明的设置在 g.settings 里（和平台内置的 sound / locale 合在一起） */
+    if (o.win && g.settings.toast) ctx.fx.plate({ tier: 0, mult: `${r.multiplier.toFixed(2)}×`, amount: `+${money(r.payout)}` });
   },
 });

package/create-game/template/base/src/styles/global.css

@@ -1,8 +1,8 @@
 /* 游戏自己的设计变量和 reset。
 
    构建时 @gamekit/vite-config 的 namespace-css 插件会把这里的 :root / html / body
-   收敛到游戏根元素 .gk-<id>，@keyframes 也会改名。原因是同页可能挂着两个游戏，
-   而 @keyframes 是全局命名空间、后定义覆盖先定义——撞名不报错，只是动画播成别人的。
+   收敛到游戏根元素 .gk-<id>：同页可能挂着两个游戏，变量不能互相覆盖。
+   这里不写 @keyframes（构建直接报错）：一次性的动画进效果表 effect.keyframes，循环的进 defineLoops。
 
    页面外框（body 的底色、外边距）不放这里：那是平台的地盘。 */
 :root{

package/create-game/template/base/src/tempo.ts

@@ -0,0 +1,4 @@
+/* 节拍（毫秒）：效果表的时长和演出的时间线都读这一份，两边的数字对得上。
+   只写一套：极速、减弱动效由框架统一处理（极速时这一局的等待与效果按平台给的倍率加速，减弱动效时每一段直接落到终态），游戏不读 turbo、不判 reducedMotion。
+   flip：翻一下多久；total：翻动多久再定格；linger：赢面牌子停多久 */
+export const T = { flip: 90, total: 800, linger: 1600 } as const;

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

@@ -28,10 +28,11 @@
 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/present.ts  definePresent({ run, settle, concurrent?, interval? })：一局怎么演。run / settle 是 function*，要等什么就 yield 什么（ctx.delay / tween / 子时间线），只写 game.state 和发效果 ctx.fx.<名字>()
+src/effects.ts  效果表 defineEffects（声音、keyframes、组件、粒子、台词）与循环表 defineLoops（处在某个状态期间一直循环的动画）：每样演出只在这里声明一次
+src/tempo.ts    节拍：export const T = { … } as const，效果表的 ms 和时间线都读它，两边的数字对得上
 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/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
@@ -55,18 +56,25 @@ studio/cases.jsonl   case 库（进版本控制），studio 维护
 - 不写 `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`；处在某个状态期间一直循环的进循环表、模板 `{@attach game.loops.x.when(条件)}`；一次性事件进效果表、`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`「一个动画归哪一级」。
+- **动画先定级别**：有没有别的东西要等它演完？有就是编排，写进演出把手的时间线；没有就是状态外观，演出把手只写状态，循环交给循环表。一排会挪动的格子（开奖历史、历史牌）用框架的 `Queue`，不用 Svelte 的 `animate:` / `transition:`。一个元素的一个属性只有一个主人，两样都要动就拆两层。详见 `node_modules/gamekit777/docs/view.md`「一个动画归哪一级」。
+- **动画不要用 JS 逐帧驱动，除非确实做不到。** 游戏跑在跨源的沙箱 iframe 里，玩家没在 iframe 里点过时 iOS 把 rAF 限到 30fps：逐帧 JS 的动画在 iPhone 上只有 30fps，主线程一卡它也跟着卡。WAAPI 在合成线程上播，不受这些影响。按这个顺序选：
+  1. **发生一次的**（弹一下、翻开、飞过去、抖一下）→ 效果表里的 `effect.keyframes`。位置要演出时才知道的，把 `frames` 写成 payload 的函数，触发 `ctx.fx.x(k, payload)`。state 里直接写终态，效果只播过程。
+  2. **处在某个状态期间一直循环的**（呼吸、旋转、闪烁）→ `defineLoops`，模板里 `{@attach game.loops.x.when(条件)}`（一直播就 `{@attach game.loops.x}`）。
+  3. **框架表达不了的** → `effect.dom` 的 `commit` 里用 `x.animate(el, frames, timing)` 手写 WAAPI（倍率、极速、减弱动效、作废框架替你管）。别的地方不裸调 `el.animate`。
+  4. **只有数字读数、或由逻辑逐帧决定且必须进 state 的量**，才用 `ctx.tween` / 时间线 `.to()`。
+  不写全局 `@keyframes`（独立 .css 里的、组件里 `-global-` / `:global` 的，dev 与 build 直接报错；组件作用域的只在组件型效果内部用），不用 CSS `animation` / `transition` 做演出。
 - 画布里只改演出状态、不经平台的交互（切视图、选面值、翻页）在处理函数里调 `game.touch()`，否则空闲编排可能刚好到点，把玩家刚打开的东西收回去。
-- 声音、动画、粒子、台词只经效果表：不手写 `node.animate`、不自己注 `@keyframes`、不 `new AudioContext`、不碰 `<audio>`。它们因此自动服从快进、追赶、直接看结果、倍率与减弱动效。
+- 声音、动画、粒子、台词只经效果表与循环表：不 `new AudioContext`、不碰 `<audio>`，手写 WAAPI 只用上面第 3 档的 `x.animate`。它们因此自动服从快进、追赶、直接看结果、倍率、极速与减弱动效。
+- **节拍是游戏自己的一组常数**（`src/tempo.ts` 的 `T`），不按设置换数字。极速、减弱动效由框架统一处理：极速时这一局的等待与效果按平台给的倍率加速，减弱动效时每一段直接落到终态、只放 always 的效果，keyframes 与循环不播。编排里不读 `turbo`，也不写 `prefers-reduced-motion`。
 - **效果不用判 `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`、不在模块里存元素。
+- 要让框架知道一个元素，只有一种写法：`{@attach 把手}`。动画目标挂效果把手（`{@attach game.fx.shake}`、`{@attach game.fx.peg.at(k)}`），循环挂循环把手（`{@attach game.loops.x.when(条件)}`）；粒子、飘字的位置挂锚点把手（游戏类上 `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` 是平台和工具的面，游戏里不出现。
@@ -80,45 +88,47 @@ studio/cases.jsonl   case 库（进版本控制），studio 维护
 ## 演出层（最小示例；三类东西、时间线、效果选项、反例清单见 `node_modules/gamekit777/docs/view.md`）
 
 ```ts
+// src/tempo.ts —— 节拍只有这一份，效果表和时间线都读它
+export const T = { flip: 100, pause: 90, spin: 420 } as const;
+
 // 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() 播
+  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 变了就播
+  fly:   effect.keyframes({ ms: 300, frames: (p: { dx: number; dy: number }) => [{ transform: `translate(${p.dx}px, ${p.dy}px)` }, { transform: 'none' }] }),   // 动态的：state 已写在终点，从原处播过来；ctx.fx.fly(undefined, { dx, dy })
   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
+export const loops = defineLoops({
+  spin: { ms: T.spin, frames: [{ transform: 'scale(1)' }, { transform: 'scale(1.1)', offset: 0.5 }, { transform: 'scale(1)' }] },   // 处在某个状态期间一直循环
 });
 
 // src/game.svelte.ts —— 画面上是什么在 game.state（形状写在 rules/types.ts 的 state 键），模板直接读；类上只放声明、共用的派生、画布交互
-export class Game extends RoundGame<CoinFlip, typeof effects, typeof keyframes> {
+export class Game extends RoundGame<CoinFlip, typeof effects, typeof loops> {
   static override App = App;                                                 // 演出侧只声明这一个类：App、演出把手、两张表都是静态字段
   static override presenter = presenter;
   static override effects = effects;
-  static override keyframes = keyframes;
+  static override loops = loops;
   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>) {
+function* celebrate(ctx: PresentCtx<CoinFlip>) {
   ctx.fx.say(ctx.rand.pick(['漂亮', '到手']));                                                  // ctx.rand 回放一致
-  yield ctx.delay(ctx.T.pause);
+  yield ctx.delay(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 } },
+export const presenter = definePresent<CoinFlip>({
   *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：按实例时钟、跟随倍率、后台时停住，快进不等，作废不再往下跑
+      yield ctx.delay(T.flip);                                   // 要等就 yield：按实例时钟、跟随倍率与极速、后台时停住，快进不等，作废不再往下跑
     }
     g.state.face = r.outcome.landed;                             // 结果：无条件写
     g.state.last = r.outcome;
@@ -135,14 +145,13 @@ export const presenter = definePresent<CoinFlip, T>({
 ```
 
 ```svelte
-<!-- src/components/App.svelte -->
+<!-- src/components/App.svelte：抖动和循环都动 transform，拆两层 -->
 <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>
+<div {@attach game.fx.shake}><div class="coin" {@attach game.loops.spin.when(game.rounds.live)} {@attach game.coin}>{game.state.face}</div></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 效果的把手和锚点把手，挂到别的效果上是类型错误；把手是对象引用，名字写错也是类型错误。
+`{@attach}` 只接受 keyframes 效果的把手、循环把手（`game.loops.x` / `.when(条件)`）和锚点把手，挂到别的效果上是类型错误；动态 keyframes 没有 `.on`；把手是对象引用，名字写错也是类型错误。
 `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`「编排的单测」。
 

package/dev-host/DevShell.svelte

@@ -336,8 +336,8 @@
 {/snippet}
 
 {#snippet toggles()}
-  <button type="button" aria-pressed={p.settings.turbo}
-          onclick={() => p.setSettings({ turbo: !p.settings.turbo })}>
+  <button type="button" aria-pressed={p.turbo}
+          onclick={() => p.setTurbo(!p.turbo)}>
     <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M13 2 4 14h7l-1 8 9-12h-7z" /></svg>
     快速模式
   </button>

package/dev-host/controls/Hud.svelte

@@ -6,8 +6,8 @@
      底栏是一个定高的槽，里面最多一样东西，谁进谁出、谁都不在，HUD 高度都不变，安全区不抖：
        自动中            → 停止键（每发出一注闪一下还剩几局）
        多阶段一局开着     → 动作栏（槽按它加高到 116px）
-       空闲               → 下注条：假输入框（点开注额抽屉）/ 下注键 / 设置齿轮
-     自动停下时最后一局往往还在演，那段两边都不显示，演完下注条才进来——不然它会先冒出来再被「下注中」赶走。
+       其余               → 下注条：假输入框（点开注额抽屉）/ 下注键 / 设置齿轮；
+                            一局在演时下注键换成「直接看结果」，注额和齿轮禁用（同时演多局的游戏照旧能下）
      错误提示绝对定位贴在底栏上方，不进文档流 */
   import { untrack, type Snippet } from 'svelte';
   import type { CoverPx } from '../../sdk/platform.ts';
@@ -47,7 +47,8 @@
   let sheetTab = $state('settings');
   const closeMenu = (): void => { menuOpen = false; };
 
-  const showBar = $derived(!betOpen && !menuOpen && !m.run.auto && (m.multi || (!m.placing && !m.game.busy)));
+  const showBar = $derived(!betOpen && !menuOpen);
+  const running = $derived(!m.multi && (m.placing || m.game.busy));
   const motion = $derived({ duration: m.settings.reducedMotion ? 0 : 160 });
 
   /* 自动模式下每发出一注，停止键先淡成剩余局数、停一下再淡回停止图标。
@@ -93,7 +94,7 @@
 <i class="sysprobe" bind:this={probe} aria-hidden="true"></i>
 <div class="hud hud-top" bind:this={hudTop} style:padding-top={pad ? `${pad.top + 8}px` : undefined}>
   <span class="grow"></span>
-  <Balance cents={m.balance} bigFrom={m.bet * 10 || undefined} reducedMotion={m.settings.reducedMotion} turbo={m.settings.turbo} {money} />
+  <Balance cents={m.balance} bigFrom={m.bet * 10 || undefined} reducedMotion={m.settings.reducedMotion} turbo={m.turbo} {money} />
   {@render topEnd?.()}
 </div>
 <div class="hud hud-bottom" bind:this={hudBottom} style:padding-bottom={pad ? `${pad.bottom + 12}px` : undefined}>
@@ -118,13 +119,17 @@
         <div class="hud-acts" transition:lineIn={motion}><StageActions {m} {st} /></div>
       {:else if showBar}
         <div class="hud-bar" transition:lineIn={motion}>
-          <button type="button" class="fakeinp" aria-label={m.board ? '总注' : '注额'} disabled={m.board} onclick={() => (betOpen = true)}>
+          <button type="button" class="fakeinp" aria-label={m.board ? '总注' : '注额'} disabled={m.board || running} onclick={() => (betOpen = true)}>
             <span class="coin" aria-hidden="true"></span>
             <b>{money(m.cost)}</b>
             {#if !m.board}<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h4L18 10l-4-4L4 16z" /></svg>{/if}
           </button>
-          <button type="button" class="playbtn" aria-label="下注" disabled={!m.canBet} onclick={() => void m.place()}><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z" /></svg></button>
-          <button type="button" class="gearbtn" aria-label="设置" onclick={() => (menuOpen = true)}>
+          {#if running && m.skip}
+            <button type="button" class="playbtn" aria-label="直接看结果" disabled={!m.game.canSkip} onclick={() => m.skip?.()}><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 6v12l8-6zM12 6v12l8-6z" /></svg></button>
+          {:else}
+            <button type="button" class="playbtn" aria-label="下注" disabled={running || !m.canBet} onclick={() => void m.place()}><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z" /></svg></button>
+          {/if}
+          <button type="button" class="gearbtn" aria-label="设置" disabled={running} onclick={() => (menuOpen = true)}>
             <svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="3" /><path d="M12 2v3M12 19v3M2 12h3M19 12h3M4.9 4.9l2.1 2.1M17 17l2.1 2.1M4.9 19.1L7 17M17 7l2.1-2.1" /></svg>
           </button>
         </div>

package/dev-host/controls/model.ts

@@ -37,6 +37,8 @@ export interface ControlsModel {
   readonly game: GameStatus;
   readonly run: RunState;
   readonly settings: PlatformSettings;
+  /** 极速开关（平台侧的；游戏看的是 run.turbo 倍率） */
+  readonly turbo: boolean;
   readonly canBet: boolean;
   /** 注发出去了、还没开演 */
   readonly placing: boolean;

package/dev-host/platform.svelte.ts

@@ -5,7 +5,7 @@
 
    状态用 runes 写（这是个 Svelte 宿主），交给游戏的是框架中立的 Readable。
    换成 React 宿主时这一层换成 useSyncExternalStore，游戏侧零改动。 */
-import { DESKTOP_STAGE, defaultsOf, writable,
+import { DESKTOP_STAGE, TURBO_RATE, defaultsOf, writable,
   type GameDefinition, type GameStatus, type Host, type Readable, type RoundResult, type RunState, type Settings, type StageInfo, type StageLayout,
   type WalletView, type GameTypes, type GameTypesOf, type ConfigOf, type OutcomeOf, type SettingsOf, type PlatformSettings,
   type GameInstance, type RoundInstance, type StageEnd, type BoardView, type Stakes, type StakeOp, stakesTotal } from '../sdk/platform.ts';
@@ -67,7 +67,7 @@ export function createPlatform<T extends GameTypes>(
   const cfgStore = writable<{ v: C }>({ v: defaults });
   /* 偏好（平台内置 + 游戏声明的，游戏那部分按 slug 存本机）和运行态分开：自动模式不是玩家的偏好 */
   const settingsStore = writable<Settings<S>>({ ...platformDefaults(), ...(loadGameSettings(spec.slug, spec.settings) as object) } as Settings<S>);
-  const runStore = writable<RunState>({ auto: false, replay: false, rate: 1 });
+  const runStore = writable<RunState>({ auto: false, replay: false, rate: 1, turbo: 1 });
   const walletStore = writable<WalletView>({ balance: 0, currency: 'CNY', decimals: 2 });
   const stageStore = writable<StageInfo>(DESKTOP_STAGE);
   const boardStore = writable<BoardView>({ stakes: {}, total: 0, limits: DEFAULT_LIMITS, undo: 0 });
@@ -76,6 +76,8 @@ export function createPlatform<T extends GameTypes>(
     config = $state<C>(defaults);
     settings = $state<Settings<S>>(settingsStore.get());
     run = $state<RunState>(runStore.get());
+    /** 极速开关。只在平台这边：游戏拿到的是 run.turbo 倍率 */
+    turbo = $state(false);
     balance = $state(0);
     startBalance = $state(0);
     currency = $state('CNY');
@@ -247,6 +249,11 @@ export function createPlatform<T extends GameTypes>(
       saveGameSettings(spec.slug, spec.settings, next);
     }
 
+    setTurbo(on: boolean): void {
+      this.turbo = on;
+      this.setRun({ turbo: on ? TURBO_RATE : 1 });
+    }
+
     setRun(patch: Partial<RunState>): void {
       const next = { ...runStore.get(), ...patch };
       runStore.set(next);
@@ -506,7 +513,7 @@ export function createPlatform<T extends GameTypes>(
         if (this.round) break;
         left--;
         this.autoLeft = isFinite(left) ? left : 0;
-        if (this.run.auto) await sleep(this.settings.turbo ? 220 : 600);
+        if (this.run.auto) await sleep(this.turbo ? 220 : 600);
       }
     }
 
@@ -533,7 +540,7 @@ export function createPlatform<T extends GameTypes>(
         /* 下一注等游戏说还能下：同时演多局的游戏演出中就放行（节奏由它的 interval 定）；
            一次只演一局的等这一局演完，再停一口气 */
         await until(() => !this.run.auto || this.game.canBet);
-        if (this.run.auto && !this.game.busy) await sleep(this.settings.turbo ? 220 : 600);
+        if (this.run.auto && !this.game.busy) await sleep(this.turbo ? 220 : 600);
       }
 
       this.setRun({ auto: false });

package/dev-host/settings.ts

@@ -14,7 +14,7 @@ const defaultStorage = (): SettingsStorage | null => {
 export function platformDefaults(): PlatformSettings {
   let reducedMotion = false;
   try { reducedMotion = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches; } catch { /* 无头环境没有 */ }
-  return { sound: true, volume: 1, turbo: false, reducedMotion, locale: 'zh-CN' };
+  return { sound: true, volume: 1, reducedMotion, locale: 'zh-CN' };
 }
 
 /** 游戏声明的那部分：默认值盖上本机存过的值。存过的值按字段 kind 再夹一遍——它可能来自旧版 schema */
@@ -36,12 +36,15 @@ export function saveGameSettings<S>(slug: string, schema: SettingsSchema<S>, val
   try { store.setItem(settingsKey(slug), JSON.stringify(out)); } catch { /* 配额满、隐私模式：不存就不存 */ }
 }
 
-/** 合并一份改动：平台键原样收下，游戏键按 schema 夹取，不认识的键丢掉 */
+/** 下发给游戏的平台键。turbo 这个键归平台但不下发：开关留在平台，游戏只看 host.run.turbo 倍率 */
+export const SENT_PLATFORM_KEYS: readonly string[] = PLATFORM_SETTING_KEYS.filter((k) => k !== 'turbo');
+
+/** 合并一份改动：平台键原样收下，游戏键按 schema 夹取，不认识的键（含 turbo）丢掉 */
 export function applySettingsPatch<S>(schema: SettingsSchema<S>, prev: Settings<S>, patch: Partial<Settings<S>>): Settings<S> {
   const next = { ...prev } as Record<string, unknown>;
   const gamePatch: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(patch as Record<string, unknown>)) {
-    if ((PLATFORM_SETTING_KEYS as readonly string[]).includes(k)) next[k] = v;
+    if (SENT_PLATFORM_KEYS.includes(k)) next[k] = v;
     else if (k in schema) gamePatch[k] = v;
   }
   if (Object.keys(gamePatch).length > 0) {

package/dev-host/theme.css

@@ -228,6 +228,11 @@ h3 { font-size: 13px; font-weight: 700; margin: 0 0 8px; }
   background: var(--stage);
   position: relative;
 }
+/* iOS 26 的主屏幕 web app（viewport-fit=cover + black-translucent）里 100dvh / 100svh / 100% 都少算一个顶部安全区，
+   机台底下露出一条空带；只有 100lvh 是整屏。standalone 没有会伸缩的地址栏，lvh 就是屏幕高 */
+@media (display-mode: standalone) {
+  .cab.mobile { height: 100lvh; }
+}
 .cab.mobile .stage { aspect-ratio: auto; justify-self: center; align-self: center; }
 /* 系统安全区的探针：机台读它的 computed padding 拿到 env() 的数值（JS 读不到 env）。
    顶层文档里才有值，iframe 里恒为 0——所以只有平台量得到，再连同 HUD 的遮挡一起下发给游戏 */
@@ -264,6 +269,8 @@ h3 { font-size: 13px; font-weight: 700; margin: 0 0 8px; }
 }
 .cab.mobile .hud-bottom > * { pointer-events: auto; }
 .cab.mobile .hud-bottom .ghostbtn { color: var(--s-ink); border-color: rgba(255, 255, 255, .35); }
+/* 舞台上字是 --s-ink，通用的 hover 底色 --field 在亮色主题是白的，会把字吃掉 */
+.cab.mobile .hud-bottom .ghostbtn:hover:not(:disabled) { background: rgba(255, 255, 255, .14); }
 .hud-row { display: flex; gap: 8px; align-items: stretch; }
 .hud-row > .tabs { flex: 1; min-width: 0; }
 .hud-row > .inp { flex: 1; min-width: 0; }
@@ -304,6 +311,7 @@ h3 { font-size: 13px; font-weight: 700; margin: 0 0 8px; }
   filter: drop-shadow(0 1px 2px rgba(0, 0, 0, .6));
 }
 .gearbtn svg { width: 26px; height: 26px; fill: none; stroke: currentColor; stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
+.gearbtn:disabled { opacity: .5; }
 
 /* ---------- 按钮 ---------- */
 .cta {