gamekit777 0.1.5 → 0.1.7

package/README.md

@@ -14,7 +14,7 @@
 ## 开始
 
 ```sh
-bunx gamekit777 new                        # 一个能跑的抛硬币（my-game）+ bun install；名字改 game.meta.json
+bunx gamekit777 new [名字]                 # 一个能跑的抛硬币 + bun install：不给名字就地用当前空目录，给名字生成到子目录
 cd my-game
 bun run dev                                # 起 studio：http://127.0.0.1:4301/ ，预览 / 调参 / 建表 / Case / 发布
 ```

package/create-game/scaffold.ts

@@ -1,21 +1,37 @@
 /* 新游戏脚手架的库函数面。
  *
- * 模板不是空壳，是一个跑得通的最小游戏（抛硬币）：装完就能 bun run dev、
- * bun run verify、bun run test、bun run build 全绿。
- * 从一个能跑的东西开始改，比对着一堆 TODO 填空可靠得多。
+ * 模板不是空壳，而是仓库里那个跑得通的最小游戏 games/coin-flip：脚手架把它整个复制出去、
+ * 换掉名字，装完就能 bun run dev、verify、test、build 全绿。从一个能跑的东西开始改，
+ * 比对着一堆 TODO 填空可靠得多；只维护一份也就不会再出现「模板和 coin-flip 漂开了」。
+ *
+ * 复制时剔掉仓库专属的东西（remote-e2e、平台分配的 gameId、缓存），再叠上只有新项目才需要的
+ * overlay/（给创作者 AI 的 CLAUDE.md、.gitignore）。
  *
  * 抽成库函数是因为有三个调用方：CLI、studio 的 scaffold 工具、以及
  * npm 打包脚本的产物自验——最后一个尤其要紧，它生成的项目就是创作者的真实起点，
  * 用别的东西代替就验不到「模板能不能脱离仓库跑」。 */
 import { cpSync, existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-/* 仓库内是 packages/create-game/{src,template}，压平进 npm 包后是 create-game/{scaffold.ts,template}——
-   两种布局都要找得到 */
-export const TEMPLATE_DIR = [join(HERE, '..', 'template'), join(HERE, 'template')].find(existsSync)
-  ?? join(HERE, '..', 'template');
+/* 仓库内：底是 games/coin-flip，叠层是 packages/create-game/overlay；
+   压平进 npm 包后：create-game/template/{base,overlay}（build-npm 把两处一起搬过去） */
+export const BASE_DIR = [join(HERE, '..', '..', '..', 'games', 'coin-flip'), join(HERE, 'template', 'base')].find(existsSync)
+  ?? join(HERE, 'template', 'base');
+export const OVERLAY_DIR = [join(HERE, '..', 'overlay'), join(HERE, 'template', 'overlay')].find(existsSync)
+  ?? join(HERE, 'template', 'overlay');
+
+/** 底里不该带进新项目的：装出来的、算出来的、只对仓库有意义的 */
+export const BASE_SKIP = ['node_modules', 'dist', '.studio', 'studio', 'scripts/remote-e2e.ts'];
+export const isSkipped = (rel: string): boolean => {
+  const posix = rel.split(sep).join('/');
+  return posix === '' ? false : BASE_SKIP.some((s) => posix === s || posix.startsWith(`${s}/`)) || posix.endsWith('.log');
+};
+
+/** 底那个游戏的名字，脚手架把它们换成新游戏的 */
+const BASE_ID = 'coin-flip';
+const BASE_TITLE = '抛硬币';
 
 export const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 
@@ -40,29 +56,78 @@ const walk = (dir: string): string[] =>
   });
 
 /** 驼峰化：coin-flip → CoinFlip，用作类型名前缀 */
-const pascal = (id: string): string =>
+export const pascal = (id: string): string =>
   id.split('-').map((w) => w[0]!.toUpperCase() + w.slice(1)).join('');
 
+/** 存在也不算「非空」的东西：新建仓库时常见的那几样 */
+const IGNORABLE = new Set(['README.md', 'LICENSE', 'CLAUDE.md']);
+
+/* 仓库内的 games/<id> 和仓库外的创作者项目要的不一样：
+   仓库内 tsconfig 继承根的 tsconfig.base.json、dev 脚本指到本地 8787/5180；
+   仓库外没有这两样——tsconfig 写全、dev 脚本不带参数指平台 */
+const inRepo = (dest: string): boolean =>
+  basename(dirname(dest)) === 'games' && existsSync(join(dest, '..', '..', 'tsconfig.base.json'));
+
+/** 和根 tsconfig.base.json 同一组选项。仓库外没有那个文件可继承，只能抄一份进项目 */
+const STANDALONE_TSCONFIG = {
+  extends: '@tsconfig/svelte/tsconfig.json',
+  compilerOptions: {
+    target: 'ES2022', lib: ['ES2022', 'DOM', 'DOM.Iterable'], module: 'ESNext', moduleResolution: 'bundler',
+    strict: true, noUnusedLocals: true, noUnusedParameters: true, noImplicitOverride: true, noFallthroughCasesInSwitch: true,
+    noEmit: true, isolatedModules: true, verbatimModuleSyntax: true, skipLibCheck: true, forceConsistentCasingInFileNames: true,
+    allowImportingTsExtensions: true, types: [],
+  },
+  include: ['game.ts', 'src', 'scripts', 'test'],
+};
+
 export function scaffoldGame(o: ScaffoldOptions): ScaffoldResult {
   if (!ID_PATTERN.test(o.id)) {
     throw new Error(`id "${o.id}" 要是小写短横线形式——它同时是包名、输出目录名和 CSS 命名空间`);
   }
-  if (existsSync(o.dest)) throw new Error(`${o.dest} 已经存在`);
+  if (!existsSync(BASE_DIR)) throw new Error(`脚手架的底 ${BASE_DIR} 不存在`);
+  /* 目标目录可以已存在，但必须是「空」的：只有 .git、README、编辑器配置这类不算内容。
+     有 package.json / game.ts / src 就是别的项目，往里铺模板会把它搅成两个项目的混合物 */
+  if (existsSync(o.dest)) {
+    const left = readdirSync(o.dest).filter((f) => !IGNORABLE.has(f) && !f.startsWith('.'));
+    if (left.length) throw new Error(`${o.dest} 不是空目录（有 ${left.slice(0, 5).join('、')}${left.length > 5 ? '…' : ''}）`);
+  }
 
-  cpSync(TEMPLATE_DIR, o.dest, { recursive: true });
+  cpSync(BASE_DIR, o.dest, { recursive: true, filter: (src) => !isSkipped(relative(BASE_DIR, src)) });
+  if (existsSync(OVERLAY_DIR)) cpSync(OVERLAY_DIR, o.dest, { recursive: true });
 
+  const title = o.title ?? o.id;
+  const repo = inRepo(o.dest);
   const files: string[] = [];
   for (const file of walk(o.dest)) {
     if (/\.(png|jpe?g|gif|webp|ico|woff2?)$/i.test(file)) { files.push(file); continue; }
     let out = readFileSync(file, 'utf8')
+      // overlay 里的占位符
       .replaceAll('__ID__', o.id)
-      .replaceAll('__TITLE__', o.title ?? o.id)
-      .replaceAll('__PASCAL__', pascal(o.id));
-    if (o.gamekitSpec && /package\.json(\.tmpl)?$/.test(file)) {
-      out = out.replace(/("gamekit777"\s*:\s*)"[^"]*"/, `$1${JSON.stringify(o.gamekitSpec)}`);
+      .replaceAll('__TITLE__', title)
+      .replaceAll('__PASCAL__', pascal(o.id))
+      // 底里 coin-flip 自己的名字：包名、slug、类型前缀、标题
+      .replaceAll(pascal(BASE_ID), pascal(o.id))
+      .replaceAll(BASE_ID, o.id)
+      .replaceAll(BASE_TITLE, title);
+    const name = relative(o.dest, file).split(sep).join('/');
+    if (name === 'package.json') {
+      const pkg = JSON.parse(out) as { name: string; exports?: unknown; scripts: Record<string, string>; dependencies: Record<string, string> };
+      pkg.name = `@game/${o.id}`;
+      delete pkg.exports;                 // 只有仓库内的测试会 import 别的游戏
+      delete pkg.scripts.remote;          // remote-e2e.ts 没复制
+      if (!repo) pkg.scripts.dev = 'gamekit777 studio --no-mcp';
+      if (o.gamekitSpec) pkg.dependencies.gamekit777 = o.gamekitSpec;
+      out = `${JSON.stringify(pkg, null, 2)}\n`;
+    } else if (name === 'game.meta.json') {
+      const meta = JSON.parse(out) as Record<string, unknown>;
+      delete meta.gameId;                 // 平台第一次发布时才分配，不是底的那个
+      meta.id = o.id; meta.title = title;
+      out = `${JSON.stringify(meta, null, 2)}\n`;
+    } else if (name === 'tsconfig.json' && !repo) {
+      out = `${JSON.stringify(STANDALONE_TSCONFIG, null, 2)}\n`;
     }
     writeFileSync(file, out);
-    // 模板文件带 .tmpl 后缀，免得脚手架自己的 lint / 构建去处理它们；
+    // overlay 里带 .tmpl 后缀，免得脚手架自己的 lint / 构建去处理它们；
     // .gitignore 叫 _gitignore，因为 npm 打包会把包里的 .gitignore 改名或丢掉
     let final = file.endsWith('.tmpl') ? file.slice(0, -5) : file;
     if (final.endsWith('/_gitignore')) final = `${final.slice(0, -'_gitignore'.length)}.gitignore`;

package/create-game/template/base/game.meta.json

@@ -0,0 +1,9 @@
+{
+  "id": "coin-flip",
+  "title": "抛硬币",
+  "gameId": "95d28dcf-fe8f-45f0-a03b-f68523efd865",
+  "version": "1.0.0",
+  "aspect": "16:9",
+  "orientation": "any",
+  "fonts": []
+}

package/create-game/template/{game.ts.tmpl → base/game.ts}

@@ -1,23 +1,27 @@
-/* __TITLE__ 的清单。只依赖 gamekit777/sdk 和自己的 rules/，Node 和浏览器都能 import：
-   studio 用它探测和建表、打包流水线用它采样、浏览器入口把它和 mount 拼在一起。
-
-   模板是抛硬币：两面对称，**只有一种赔付分布**，所以一张表就够。
-   `side` 不改变分布，只改变某一局落在哪面——服务端不需要知道它，玩家运行时自由选。
-   book 因此可以完全不传：payout > 0 就说明硬币落在你押的那面（见 rules/restore.ts）。
+/* 抛硬币的清单。只依赖 gamekit777/sdk 和自己的 rules/，Node 和浏览器都能 import：
+   打包流水线用它采样、studio 用它探测和建表、浏览器入口把它和 mount 拼在一起。
 
+   这个游戏同时是脚手架的底：`gamekit777 new` 把整个目录复制出去再换名字。
    改成你自己的游戏时，先用 studio 的 probe_table 看看：
      哪些字段改变赔付分布 → 写进 modes（一张表 = 一种分布），只写那几个字段
      哪些字段只改变这一局 → 保持自由，用 book 编码演出（参考 coco 的 book.ts）
      赔付必须是 centi 精度、必须是注额的线性函数——这两条 probe 会替你查
    逻辑侧三个必填：schema 说有哪些参数，round 说结果怎么算，paytable 说赔多少。
-   normalize / validate / modeOf 不用写——它们由 schema 和 modes 推导。 */
+   normalize / validate / modeOf 不用写——它们由 schema 和 modes 推导。
+
+   两面对称，只有一种赔付分布，所以一张表就够。`side` 不改变分布，只改变某一局落在哪面——
+   服务端不需要知道它，玩家运行时自由选。book 因此可以完全不传：payout > 0 就说明
+   硬币落在你押的那面（见 rules/restore.ts）。
+
+   纯度由 scripts/verify.ts 的运行时桩保证：把 Math.random 和 crypto 换成会抛的假实现
+   再调 round()，查的是实际执行路径含全部传递依赖。 */
 import { createRng, defineGame, normalizeBySchema, type RoundInput, type RoundResult } from 'gamekit777/sdk';
 import meta from './game.meta.json' with { type: 'json' };
 import { HOUSE_EDGE, MULT } from './src/rules/const.ts';
 import { restore } from './src/rules/restore.ts';
 import { schema } from './src/rules/schema.ts';
 import { simulate } from './src/rules/simulate.ts';
-import type { __PASCAL__Config, __PASCAL__Outcome } from './src/rules/types.ts';
+import type { CoinFlipConfig, CoinFlipOutcome } from './src/rules/types.ts';
 
 export { schema, simulate, restore };
 export * from './src/rules/types.ts';
@@ -28,7 +32,7 @@ export * from './src/rules/types.ts';
  * 随机数的抽取顺序是契约的一部分：flip 子流 below(2) 一次。
  * 已发布 mode 的这段逻辑不能改——历史局的 book 要靠它解；要改就换 slug。
  */
-export function round(input: RoundInput<__PASCAL__Config>): RoundResult<__PASCAL__Outcome> {
+export function round(input: RoundInput<CoinFlipConfig>): RoundResult<CoinFlipOutcome> {
   const cfg = normalizeBySchema(schema, input.config);
   const flip = createRng(input.seed).fork('flip').below(2);
   const outcome = simulate(flip, cfg);
@@ -44,11 +48,11 @@ export function round(input: RoundInput<__PASCAL__Config>): RoundResult<__PASCAL
   };
 }
 
-export default defineGame<__PASCAL__Config, __PASCAL__Outcome>({
+export default defineGame<CoinFlipConfig, CoinFlipOutcome>({
   // 名字只在 game.meta.json 里改：slug 同时是大厅里的 id、产物目录名和 CSS 命名空间
   slug: meta.id,
   title: meta.title,
-  description: '押正面还是反面。',
+  description: '押正面还是反面。猜中赔 1.96 倍，RTP 98%。',
   rtp: HOUSE_EDGE,
   sims: 100_000,
   schema,

package/create-game/template/{package.json.tmpl → base/package.json}

@@ -1,14 +1,18 @@
 {
-  "name": "@game/__ID__",
+  "name": "@game/coin-flip",
   "private": true,
   "version": "1.0.0",
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "scripts": {
-    "dev": "gamekit777 studio --no-mcp",
+    "dev": "GAMEKIT_BASE_URL=http://127.0.0.1:8787 GAMEKIT_SITE_URL=http://localhost:5180 gamekit777 studio --no-mcp",
     "build": "svelte-check --tsconfig ./tsconfig.json && vite build",
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
-    "verify": "bun scripts/verify.ts"
+    "verify": "bun scripts/verify.ts",
+    "remote": "bun scripts/remote-e2e.ts"
   },
   "dependencies": {
     "gamekit777": "workspace:*"

package/create-game/template/{src/components/App.svelte.tmpl → base/src/components/App.svelte}

@@ -31,6 +31,8 @@
       {game.last.win ? '猜中了' : '没猜中'}
     {:else if game.live}
       抛出中…
+    {:else if game.layout === 'mobile'}
+      在参数里选一面，下注开始
     {:else}
       在左边选一面，下注开始
     {/if}
@@ -47,9 +49,12 @@
 </div>
 
 <style>
-  /* 不写 border-radius：外框和裁切归平台容器，游戏只管自己那块内容 */
+  /* 不写 border-radius：外框和裁切归平台容器，游戏只管自己那块内容。
+     上下内边距加上平台给的安全区（--gk-safe-*，容器上由平台写，手机 HUD 盖住的那几段）：
+     硬币和文案落在没被盖住的那块里，被盖住的边只剩底色 */
   .game{position:relative;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:16px;
-    height:100%;min-height:240px;padding:28px;
+    height:100%;min-height:240px;
+    padding:calc(28px + var(--gk-safe-top,0px)) calc(28px + var(--gk-safe-right,0px)) calc(28px + var(--gk-safe-bottom,0px)) calc(28px + var(--gk-safe-left,0px));
     background:var(--bg);color:var(--ink);font-family:var(--txt)}
   .head{margin:0;font-size:13px;color:var(--dim)}
   .head b{color:var(--ink);font-size:16px}
@@ -61,7 +66,7 @@
   .foot.win{color:var(--win);font-weight:700}
   .foot.lose{color:var(--lose)}
 
-  .toast{position:absolute;left:50%;top:22%;transform:translate(-50%,0);pointer-events:none;
+  .toast{position:absolute;left:50%;top:calc(var(--gk-safe-top,0px) + 22%);transform:translate(-50%,0);pointer-events:none;
     display:flex;align-items:baseline;gap:10px;padding:10px 22px 12px;border-radius:18px;
     background:var(--panel);color:var(--ink);box-shadow:0 0 0 3px var(--win),0 10px 30px rgba(0,0,0,.45);
     animation:toast 1400ms ease-out forwards}

package/create-game/template/{src/context.svelte.ts.tmpl → base/src/context.svelte.ts}

@@ -1,22 +1,22 @@
 import { getContext, setContext } from 'svelte';
 import type { Host } from 'gamekit777/sdk';
-import type { __PASCAL__Config } from './rules/types.ts';
+import type { CoinFlipConfig } from './rules/types.ts';
 import { Game } from './state/game.svelte';
 
-const KEY = Symbol('__ID__');
+const KEY = Symbol('coin-flip');
 
 /** 一个游戏实例的全部状态。模块级不留任何可变状态，同页挂两个实例是安全的 */
 export interface Instance {
   game: Game;
-  host: Host<__PASCAL__Config>;
+  host: Host<CoinFlipConfig>;
 }
 
-export const createInstance = (host: Host<__PASCAL__Config>): Instance => ({ game: new Game(), host });
+export const createInstance = (host: Host<CoinFlipConfig>): Instance => ({ game: new Game(), host });
 
 /* 用 context 而不是模块级单例：组件一律 getInstance()，不 import 任何状态对象 */
 export const setInstance = (i: Instance): void => { setContext(KEY, i); };
 export const getInstance = (): Instance => {
   const i = getContext<Instance>(KEY);
-  if (!i) throw new Error('[__ID__] 组件不在 <App> 之下，拿不到游戏实例');
+  if (!i) throw new Error('[coin-flip] 组件不在 <App> 之下，拿不到游戏实例');
   return i;
 };

package/create-game/template/{src → base/src}/rules/const.ts

@@ -5,5 +5,6 @@ export const HOUSE_EDGE = 0.98;
 /** 中奖概率：抛硬币就是一半 */
 export const WIN_CHANCE = 0.5;
 export const MULT = HOUSE_EDGE / WIN_CHANCE;
-/** 倍率 ×100 = payoutCenti。平台只存整数 payoutCenti，restore 按它反推 */
+
+/** 倍率的定点尺度。平台按 winCents = betCents/100 × payoutCenti 赔付，两边必须是同一个 100 */
 export const PAYOUT_SCALE = 100;

package/create-game/template/{src/rules/restore.ts.tmpl → base/src/rules/restore.ts}

@@ -1,8 +1,10 @@
 /* 表模型下的还原：把平台抽中的那一行变回一局可演出的结果。
  *
- * 抛硬币是最省的那一档——**不需要任何演出数据**。
+ * coin-flip 是最省的那一档——**不需要任何演出数据**。
  * 猜中了硬币就落在你押的那面，猜错了就落在另一面，payout 已经把这件事说完了。
- * 所以这张表只有两行，book 一个字节都不传（game.ts 里 book: 'none'）。
+ * 所以这张表只有两行，book 一个字节都不传。
+ *
+ * 押哪一面（side）因此可以保持玩家自由选：它不改变赔付分布，服务端也不需要知道。
  *
  * 改成你自己的游戏时：
  *   所有影响结果的字段都在 modes 里 → 删掉这个文件，game.ts 里不写 book 和 restore，
@@ -13,14 +15,14 @@
 import { normalizeBySchema, type Restore } from 'gamekit777/sdk';
 import { PAYOUT_SCALE } from './const.ts';
 import { schema } from './schema.ts';
-import type { __PASCAL__Config, __PASCAL__Outcome } from './types.ts';
+import type { CoinFlipConfig, CoinFlipOutcome } from './types.ts';
 
-export const restore: Restore<__PASCAL__Config, __PASCAL__Outcome> = (input) => {
+export const restore: Restore<CoinFlipConfig, CoinFlipOutcome> = (input) => {
   const { side } = normalizeBySchema(schema, input.config);
   const win = input.payoutCenti > 0;
   const mult = input.payoutCenti / PAYOUT_SCALE;
 
-  const outcome: __PASCAL__Outcome = {
+  const outcome: CoinFlipOutcome = {
     side,
     landed: win ? side : side === 'heads' ? 'tails' : 'heads',
     win,

package/create-game/template/{src/rules/schema.ts.tmpl → base/src/rules/schema.ts}

@@ -1,11 +1,11 @@
 import type { ConfigSchema } from 'gamekit777/sdk';
-import type { __PASCAL__Config } from './types.ts';
+import type { CoinFlipConfig } from './types.ts';
 
 /* 平台按这份声明自动渲染设置控件，它不认识这个游戏。
      affectsOutcome  影响结果 → 下注时冻结、随 RoundInput 上送、进 proof
      lock            什么时候不许改
      ui              谁渲染：'host' 平台的表单，'stage' 游戏画布内（仍然受控） */
-export const schema: ConfigSchema<__PASCAL__Config> = {
+export const schema: ConfigSchema<CoinFlipConfig> = {
   side: {
     kind: 'enum',
     options: [

package/create-game/template/{src/rules/simulate.ts.tmpl → base/src/rules/simulate.ts}

@@ -1,8 +1,8 @@
 /* 判定。纯函数：不碰 DOM、不碰时间、不碰全局状态、不自取随机数。 */
 import { MULT } from './const.ts';
-import type { __PASCAL__Config, __PASCAL__Outcome } from './types.ts';
+import type { CoinFlipConfig, CoinFlipOutcome } from './types.ts';
 
-export function simulate(flip: number, c: __PASCAL__Config): __PASCAL__Outcome {
+export function simulate(flip: number, c: CoinFlipConfig): CoinFlipOutcome {
   const landed = flip === 0 ? 'heads' : 'tails';
   const win = landed === c.side;
   return {side: c.side, landed, win, mult: win ? MULT : 0};

package/create-game/template/{src/rules/types.ts.tmpl → base/src/rules/types.ts}

@@ -1,11 +1,11 @@
 /** 影响结果的参数。平台在下注这一刻冻结一份传进 round() */
-export interface __PASCAL__Config {
+export interface CoinFlipConfig {
   /** 押正面还是反面 */
   side: 'heads' | 'tails';
 }
 
 /** 一局的完整结果快照。演出层只读它，不做任何判定 */
-export interface __PASCAL__Outcome {
+export interface CoinFlipOutcome {
   side: 'heads' | 'tails';
   landed: 'heads' | 'tails';
   win: boolean;

package/create-game/template/{src/state/game.svelte.ts.tmpl → base/src/state/game.svelte.ts}

@@ -2,24 +2,25 @@
 
    设置来自平台（只读投影），结果来自 round()，这里只放「演到哪一步了」。
    做成可实例化的类而不是模块级单例：同页挂两个实例时各自一套状态。 */
-import type { ViewSettings } from 'gamekit777/sdk';
-import type { __PASCAL__Config, __PASCAL__Outcome } from '../rules/types.ts';
+import { DESKTOP_STAGE, type SafeInsets, type StageInfo, type StageLayout, type ViewSettings } from 'gamekit777/sdk';
+import type { CoinFlipConfig, CoinFlipOutcome } from '../rules/types.ts';
 import { schema } from '../rules/schema.ts';
 
 export type Phase = 'idle' | 'playing' | 'over';
 
-const DEFAULT_CONFIG: __PASCAL__Config = { side: schema.side.default };
+const DEFAULT_CONFIG: CoinFlipConfig = { side: schema.side.default };
 const DEFAULT_VIEW: ViewSettings = {
   sound: true, volume: 1, turbo: false, reducedMotion: false,
   skin: 'default', locale: 'zh-CN', autoActive: false
 };
 
 export class Game {
-  #config = $state<__PASCAL__Config>(DEFAULT_CONFIG);
+  #config = $state<CoinFlipConfig>(DEFAULT_CONFIG);
   #view = $state<ViewSettings>(DEFAULT_VIEW);
+  #stage = $state<StageInfo>(DESKTOP_STAGE);
 
   /* 影响结果的参数，来自 host.config */
-  get side(): __PASCAL__Config['side'] { return this.#config.side; }
+  get side(): CoinFlipConfig['side'] { return this.#config.side; }
 
   /* 不影响结果的表现参数，来自 host.view */
   get turbo(): boolean { return this.#view.turbo; }
@@ -27,12 +28,17 @@ export class Game {
   get reducedMotion(): boolean { return this.#view.reducedMotion; }
   get autoActive(): boolean { return this.#view.autoActive; }
 
+  /* 所在的舞台，来自 host.stage：桌面还是手机、被平台 HUD 盖住的边。
+     CSS 侧同一份数据是容器上的 --gk-safe-*；这里给需要按布局换文案/换组件的地方 */
+  get layout(): StageLayout { return this.#stage.layout; }
+  get safe(): SafeInsets { return this.#stage.safe; }
+
   phase = $state<Phase>('idle');
   /** 作废令牌：开新局时 +1，旧的演出协程醒来发现对不上号就退出 */
   rid = $state(0);
   /** 演出过程中翻动的那一面 */
   face = $state<'heads' | 'tails'>('heads');
-  last = $state<__PASCAL__Outcome | null>(null);
+  last = $state<CoinFlipOutcome | null>(null);
   lastPayout = $state(0);
   /** 赢面小弹窗。id 让连赢两局弹两次；ms 是它的存活时间，到点自己清空 */
   toast = $state<{ id: number; mult: number; payout: number; ms: number } | null>(null);
@@ -40,8 +46,9 @@ export class Game {
   live = $derived(this.phase === 'playing');
 
   /* 只有 view/mount 的订阅回调会调这两个 */
-  applyConfig(c: __PASCAL__Config): void { this.#config = c; }
+  applyConfig(c: CoinFlipConfig): void { this.#config = c; }
   applyView(v: ViewSettings): void { this.#view = v; }
+  applyStage(s: StageInfo): void { this.#stage = s; }
 
   invalidate(): void { this.rid++; this.phase = 'idle'; }
 }

package/create-game/template/{src/view/mount.svelte.ts.tmpl → base/src/view/mount.svelte.ts}

@@ -7,13 +7,13 @@ import type { GameInstance, GameStatus, Host, PresentOptions, Readable, RoundRes
 import App from '../components/App.svelte';
 import buildMeta from '../../game.meta.json' with { type: 'json' };
 import { createInstance } from '../context.svelte.ts';
-import type { __PASCAL__Config, __PASCAL__Outcome } from '../rules/types.ts';
+import type { CoinFlipConfig, CoinFlipOutcome } from '../rules/types.ts';
 import { present } from './present.ts';
 import { toStore } from './bridge.svelte.ts';
 
 export async function mountGame(
-  host: Host<__PASCAL__Config>, el: HTMLElement
-): Promise<GameInstance<__PASCAL__Outcome>> {
+  host: Host<CoinFlipConfig>, el: HTMLElement
+): Promise<GameInstance<CoinFlipOutcome>> {
   /* 每次 mount 造一棵全新的状态树，同页挂两个实例是安全的 */
   const inst = createInstance(host);
   const { game } = inst;
@@ -25,6 +25,7 @@ export async function mountGame(
   const teardown: Array<() => void> = [];
   teardown.push(host.config.subscribe(c => game.applyConfig(c)));
   teardown.push(host.view.subscribe(v => game.applyView(v)));
+  teardown.push(host.stage.subscribe(s => game.applyStage(s)));
 
   const status = toStore<GameStatus>(() => ({
     phase: game.phase === 'playing' ? 'playing' : game.phase === 'over' ? 'settling' : 'idle',
@@ -40,7 +41,7 @@ export async function mountGame(
   const app = svelteMount(App, { target: el, props: { instance: inst } });
   host.emit({ type: 'ready' });
 
-  const play = async (r: RoundResult<__PASCAL__Outcome>, o?: PresentOptions): Promise<void> => {
+  const play = async (r: RoundResult<CoinFlipOutcome>, o?: PresentOptions): Promise<void> => {
     host.emit({ type: 'present:start' });
     await present(game, r.outcome, r.payout, o?.rate ?? 1);
     host.emit({ type: 'present:end', payout: r.payout });
@@ -53,6 +54,7 @@ export async function mountGame(
     preview: play,
     skip() { if (game.live) game.rid++; },
     reset() { game.invalidate(); game.last = null; },
+    /* 舞台是 CSS 排的（flex + 容器上的 --gk-safe-*），换布局不需要额外处理 */
     resize() {},
     destroy() {
       game.invalidate();

package/create-game/template/{src/view/present.ts.tmpl → base/src/view/present.ts}

@@ -3,12 +3,12 @@
    判定一行都不在这里——outcome 是传进来的。turbo / reducedMotion 只改这段的
    时长，改不了结果，因为它们根本不在 round() 的入参里。 */
 import type { Game } from '../state/game.svelte';
-import type { __PASCAL__Outcome } from '../rules/types.ts';
+import type { CoinFlipOutcome } from '../rules/types.ts';
 
 const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
 
 export async function present(
-  game: Game, o: __PASCAL__Outcome, payout: number, rate = 1
+  game: Game, o: CoinFlipOutcome, payout: number, rate = 1
 ): Promise<void> {
   const id = ++game.rid;
   game.phase = 'playing';

package/create-game/template/{test/e2e.test.ts.tmpl → base/test/e2e.test.ts}

@@ -8,13 +8,14 @@ import { tick } from 'svelte';
 import { createPlatform, localServer } from 'gamekit777/dev-host';
 import { defineGame } from 'gamekit777/sdk';
 import game from '../src/index.ts';
-import type { __PASCAL__Config as C, __PASCAL__Outcome as O } from '../src/rules/types.ts';
+import type { CoinFlipConfig as C, CoinFlipOutcome as O } from '../src/rules/types.ts';
 
 const live: { destroy(): void }[] = [];
 afterEach(() => { while (live.length) { try { live.pop()!.destroy(); } catch { /* 已经拆过了 */ } } });
 
 const boot = async () => {
   const p = createPlatform<C, O>(game);
+  // 和真实宿主一样先握手：余额、注额区间都在服务端那边
   await p.init();
   const el = document.createElement('div');
   document.body.appendChild(el);
@@ -53,7 +54,9 @@ test('表模型：还原出的赔付必须等于平台记账，差一分也要
   if (!r.ok) return;
   expect(r.round.result!.payout).toBe((1000 / 100) * r.round.row!.payoutCenti);
   expect(r.round.wallet.balance).toBe(before - 1000 + r.round.result!.payout);
+  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 });
   await bad.init();

package/create-game/template/base/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["@tsconfig/svelte/tsconfig.json", "../../tsconfig.base.json"],
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"]
+  },
+  "include": ["src", "test", "scripts", "*.ts"]
+}

package/create-game/template/{CLAUDE.md.tmpl → overlay/CLAUDE.md.tmpl}

@@ -3,7 +3,8 @@
 这是一个 GameKit 游戏目录。平台**不执行游戏代码**：打包时用你的 `round()` 采样出一张权重表，
 运行时平台按权重抽一行、查表赔付，浏览器用你的 `restore()` 把那一行还原成演出。
 
-先读这份文件，再读 `game.ts`。模板是一个**能跑的抛硬币**——从能跑的东西开始改，不要从零写。
+先读这份文件，再读 `game.ts`。这个目录是平台参考游戏 **coin-flip（抛硬币）的完整拷贝**换了名字——它能跑、能建表、能发布；
+从能跑的东西开始改，不要从零写。源码里带「改成你自己的游戏时」的注释就是给你的路标。
 
 ## 一条原则：演出必须能回放
 
@@ -145,7 +146,15 @@ mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
 - **模块级不留可变状态**。`createInstance(host)` 造一棵状态树经 Svelte context 下传，组件 `getInstance()`。同页会有两个实例（主实例 + 回放），`test/e2e.test.ts` 会验。
 - `turbo` / `reducedMotion` 只改演出时长，改不了结果——它们根本不在 `round()` 的入参里。
 - CSS 命名空间挂在容器 `el` 上（`gk-__ID__`），不写 `document.documentElement`。
-- 画布是固定 900×771 的逻辑画面，平台整体缩放；按这个尺寸排版。
+- **两块舞台都要支持**：桌面 900×771（横版机台）和手机 450×H（竖屏全屏，H 在 800–1000 之间按 50 分档）。
+  平台整体缩放，游戏里看到的宽度永远是这两个数之一；用 flex / 百分比排高度，不要写死 771。
+  当前在哪块由三处同一份数据告诉你：`host.stage`（`Readable<StageInfo>`，`layout` / `width` / `height` / `safe`）、
+  容器 `el` 上的 `data-layout="desktop|mobile"`、以及 CSS 变量 `--gk-safe-top/right/bottom/left`。
+  **安全区**：手机上平台的操作 UI（余额、注额、下注、参数）叠在画布上下两端，`safe` 就是被盖住的边（逻辑像素）。
+  安全区外可以渲染（底色、氛围），但**不要放交互和关键信息**——它们会被挡住。最简单的做法是给根元素
+  `padding: var(--gk-safe-top) … var(--gk-safe-bottom)`。舞台变化时平台会调 `resize()`，CSS 排版的游戏留空实现即可。
+  按尺寸分档用 `@container gk-stage (max-width: 500px)` 或 `[data-layout="mobile"]`，**不要用 `@media` / `vw`**：
+  iframe 里视口是逻辑分辨率，studio 预览里是整页，两处含义不同。
 - **演出先查资源库**：`asset_list` 看有哪些。**animation** 是自足的小组件（赢面弹窗、分档大奖、揭示翻动、上飘文字…），`asset_use <name>` 复制进 `src/animations/` 再按需改；
   **pattern** 是一套机制加接线清单（荷官说话…），`asset_show <name>` 先读 NOTES 里的接线表和台词写作指南，`asset_use <name>` 复制进 `src/patterns/<name>/` 后把调用按表穿进你的时间轴，
   文案按这个游戏的角色重写。库是参考实现，复制进来就是你的代码；不要从零写一个库里已有的演出。
@@ -157,6 +166,7 @@ mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
   → run_task check / verify / test         类型、数学回归、端到端
   → probe_table                            能不能打表、modes 该写哪些键、book 怎么选
   → preview_play { rounds, seed?, simId? } 在预览里演几局（本地表模型：就地建表 → 抽行 → restore）
+  → preview_set { layout: 'mobile' }        切到手机机台看一眼：安全区对不对、画面有没有被 HUD 盖住；preview_state 报回 stage.safe
   → case_add                               把值得盯的局面存进 studio/cases.jsonl
   → build_table                            采样 → 求解 → 编码 → 本地终验 → .studio/build/<指纹>/
   → publish_dry_run → publish              一键：vite build → 传包 → 传表 → 发布，不用人确认，不可逆。身份是作者在 studio 页面连过的站点身份；报「没有身份」就让作者打开页面连一次
@@ -166,4 +176,4 @@ mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
 - 长任务返回 `jobId` 就用 `job_status` 轮询。
 - `case_run` 任何结果变化都是 `fail`。是有意改的规则且这个 mode 没发布过，`case_bless` 接受。**已发布过的 mode，发牌逻辑、book 编解码、取整方式都不能再改**——历史局靠它们回放，要改就换 slug。
 - `preview_set` 被否决会在 `rejected` 里说明——那是平台的否决权在起作用，不是 bug。
-- 手动：`bun run dev` 起 studio（页面 `http://127.0.0.1:4301/`，左边是预览机台，右边是状态 / 调参 / 建表 / Case / 发布 / 日志）；`bun run verify`、`bun run test`、`bun run build`。
+- 手动：`bun run dev` 起 studio（地址看终端输出，默认 `http://127.0.0.1:4301/`，被占会换；左边是预览机台，上方可切桌面 / 手机并选设备，右边是状态 / 调参 / 建表 / Case / 发布 / 日志）；`bun run verify`、`bun run test`、`bun run build`。