gamekit777 0.1.3 → 0.1.5

package/README.md

@@ -36,7 +36,7 @@ studio 同时是 MCP server、创作页面（预览 / 调参 / 建表 / Case /
 | import | 内容 |
 |---|---|
 | `gamekit777/sdk` | `defineGame`、契约类型、可证明公平的 RNG、SHA-256 / HMAC、加权抽样原语 |
-| `gamekit777/runtime` | 资源加载、字体预取 |
+| `gamekit777/runtime` | 资源注册表（目录即清单）、平台侧预加载器、字体注入 |
 | `gamekit777/vite-config` | `defineGameConfig`：一个游戏的 `vite.config.ts` 只要三行 |
 | `gamekit777/dev-host` | 参考平台与本地表模型服务端；`createRemotePlatform` 接真平台 |
 | `gamekit777/protocol` · `client` | 平台 REST 契约（zod）与类型化客户端 |

package/client/http.ts

@@ -193,7 +193,7 @@ export class Http {
       headers['content-type'] = 'application/json';
       body = JSON.stringify(spec.json);
     } else if (spec.body) {
-      headers['content-type'] = 'application/octet-stream';
+      headers['content-type'] ??= 'application/octet-stream';   // 调用方指定了就尊重（游戏包按扩展名给）
       // 传 ArrayBuffer 而不是视图：subarray 出来的视图带 byteOffset，
       // 有些 fetch 实现会连整个底层 buffer 一起发出去
       body = spec.body.slice().buffer as ArrayBuffer;

package/client/index.ts

@@ -16,6 +16,9 @@ import {
   GameKitError,
   type ListGamesQuery, type ListRoundsQuery,
   PAIR_CLAIM_PATH, PAIR_START_PATH,
+  type BundleCommitResult as TBundleCommitResult, BundleCommitResult,
+  type BundleFileResult as TBundleFileResult, BundleFileResult,
+  type BundleRef, bundleContentType, bundleManifestText,
   type PairClaimResult as TPairClaimResult, PairClaimResult,
   type PairStartResult as TPairStartResult, PairStartResult,
   MAX_BOOKS_PER_CHUNK,
@@ -156,6 +159,29 @@ export function createClient(opts: ClientOptions) {
         http.request({ method: 'GET', path: '/v1/me', schema: SessionView }),
     },
 
+    /** 游戏包：vite build 的产物按内容寻址传到平台。upload 一把包完：算哈希 → 逐个 PUT → commit */
+    bundles: {
+      putFile: (gameId: string, hash: string, path: string, bytes: Uint8Array): Promise<TBundleFileResult> =>
+        http.request({
+          method: 'PUT', path: `/v1/games/${gameId}/bundle/${hash}/files/${path}`,
+          body: bytes, headers: { 'content-type': bundleContentType(path) }, schema: BundleFileResult,
+        }),
+      commit: (gameId: string, hash: string, files: { path: string; sha256: string; bytes: number }[]): Promise<TBundleCommitResult> =>
+        http.request({ method: 'POST', path: `/v1/games/${gameId}/bundle/${hash}/commit`, json: { files }, schema: BundleCommitResult }),
+      async upload(gameId: string, files: readonly { path: string; bytes: Uint8Array }[], onProgress?: (msg: string) => void): Promise<BundleRef> {
+        const manifest = files.map((f) => ({ path: f.path, sha256: new Sha256().update(f.bytes).hex(), bytes: f.bytes.length }));
+        const hash = new Sha256().update(new TextEncoder().encode(bundleManifestText(manifest))).hex();
+        for (const [i, f] of files.entries()) {
+          const r = await this.putFile(gameId, hash, f.path, f.bytes);
+          if (r.sha256 !== manifest[i]!.sha256) throw new GameKitError('BUNDLE_INVALID', `${f.path} 传过去的字节和本地不一致`);
+          onProgress?.(`[包] ${i + 1}/${files.length} ${f.path}（${f.bytes.length} 字节）`);
+        }
+        const { bundle } = await this.commit(gameId, hash, manifest);
+        onProgress?.(`[包] 已登记 ${bundle.hash.slice(0, 12)}…，${bundle.files} 个文件 ${bundle.bytes} 字节`);
+        return bundle;
+      },
+    },
+
     /** studio 配对：站点签 code，studio 拿 code 换一个同一用户的会话（cookie 落在 studio 的 origin） */
     pair: {
       start: (): Promise<TPairStartResult> =>

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

@@ -2,30 +2,40 @@
 
 这是一个 GameKit 游戏目录。平台**不执行游戏代码**：打包时用你的 `round()` 采样出一张权重表，
 运行时平台按权重抽一行、查表赔付，浏览器用你的 `restore()` 把那一行还原成演出。
-所以你写的每一行逻辑都要满足「三处逐位一致」：作者机器采样、玩家浏览器还原、审计脚本复算。
 
 先读这份文件，再读 `game.ts`。模板是一个**能跑的抛硬币**——从能跑的东西开始改，不要从零写。
 
+## 一条原则：演出必须能回放
+
+一局的画面只能是「表里那一行」的函数。同一行，在下注当场、在历史列表里点开、从分享链接进来、换一台设备，
+演出来的必须是同一局：同样的牌、同样的连线、同样的赔付。下面所有约束都是这一条推出来的：
+
+- **`round()` 是纯函数**，随机只来自注入的 rng。作者机器采样、玩家浏览器还原、审计脚本复算，三处逐位一致。
+- **`restore()` 把一行还原成 `RoundResult`**，返回的 `payout` 必须恰好等于 `(bet / 100) × payoutCenti`，对不上就 `throw`、不演出。
+- **`present(result)` 只看 `result`**，不看上一局、不看余额、不看玩家当下的设置。回放是在一个全新的实例里跑 `preview(result)`，那里什么都没有。
+- **装饰性随机**（粒子角度、台词抽签）用 `Math.random()`，放在 `src/view` / 组件里，绝不进 `round()`：否则加一句台词就会改变牌序，历史局就回放不出来了。
+
+「玩家看到连成三条线，余额却没动」「分享出去的一局，别人看到另一副牌」——这类 bug 完全静默、最伤信任，所以每一条都有工具兜着：
+`scripts/verify.ts` 把 `Math.random` / `crypto` 换成会抛的桩，平台在演出前逐分比对 payout，`case_run` 盯任何结果漂移。
+
 ## 目录
 
 ```
 game.ts              清单：defineGame({...})。Node 与浏览器都 import 它，不能碰 DOM / Svelte
 src/rules/           纯逻辑：schema、simulate、restore、常量、类型。零 DOM、零自取随机
-src/index.ts         浏览器入口 = { ...game, mount }。平台加载的是它
+src/index.ts         浏览器入口 = { ...game, mount, assets }。平台加载的是它
 src/state/           单局状态（Svelte runes 类），只放「演到哪一步了」
 src/view/            mount（接平台）与 present（把结果播出来）
 src/components/      画面。子组件一律 getInstance()，不 import 状态对象
-src/assets/          资源清单与注册表；critical/ 首屏必需，lazy/ 后台预取
+src/assets/          只放文件：critical/ 首屏必需，lazy/ 后台预取。runtime 按目录生成清单，平台负责加载和进度
 scripts/verify.ts    数学回归：纯度、确定性、RTP、分布
 test/e2e.test.ts     happy-dom 里跑完整一局
 studio/cases.jsonl   case 库（进版本控制），studio 维护
 .studio/             采样缓存与建好的表，按规则指纹分目录，可随手删
 ```
 
-**没有** `publish.ts`、`src/rules/index.ts`、`meta`、版本号。看到教程里有这些就是旧结构，忽略。
-
-**改名**：只改 `game.meta.json` 的 `id`（小写短横线，同时是平台上的 slug、产物目录名、CSS 命名空间）和 `title`，
-`game.ts` 从那里读。`package.json` 的 `name` 随意。已经发布过的 slug 不能改——那是另一个游戏。
+**改名**只改 `game.meta.json` 的 `id`（小写短横线，同时是平台上的 slug、产物目录名、CSS 命名空间）和 `title`。
+`gameId` 是平台第一次发布时分配并写回的身份，不要手改、不要删。已发布过的 slug 不能改——那是另一个游戏。
 
 ## 清单：`game.ts`
 
@@ -46,8 +56,8 @@ export default defineGame<Config, Outcome>({
 });
 ```
 
-`normalize` / `validate` / `modeOf` / `configOf` **不要写**，`defineGame` 按 schema 和 modes 推导后挂在返回值上。
-清单里也**没有注额区间**——那是平台的事。
+`defineGame` 按 schema 和 modes 推导出 `normalize` / `validate` / `modeOf` / `configOf` 挂在返回值上；
+自己要规整 config 时用 `normalizeBySchema(schema, config)`。注额区间是平台的事，清单里没有。
 
 ### `round(input)`
 
@@ -57,16 +67,12 @@ function round(input: RoundInput<Config>): RoundResult<Outcome>
 // RoundResult = { bet, payout, multiplier, outcome, pacing: { durationMs, postDelayMs } }
 ```
 
-硬约束，每一条违反都会让表里的 payout 和客户端演出来的对不上，而且是概率性的：
-
-1. **同步纯函数**。不碰 DOM、时间、全局状态；随机只来自 `createRng(input.seed)`。`Math.random` / `crypto` 一次都不能碰——`scripts/verify.ts` 会把它们换成会抛的桩。
+1. **同步纯函数**。不碰 DOM、时间、全局状态；随机只来自 `createRng(input.seed)`。
 2. **随机数抽取顺序是契约**。用 `rng.fork('tag')` 把子系统分开（发牌一条、金牌一条），将来改一处不会让另一处跟着漂。`below(n)` 是无偏整数，不要自己写 `% n`。
-3. **金额是最小货币单位的整数**。`payout` 是整数分；`multiplier` 最多两位小数（平台按 centi = ×100 存）；`payout` 必须是 `bet` 的精确线性函数（bet 恒为 100 的倍数，`payout = bet * mult` 或 `(bet / 100) * payoutCenti` 都行，取整方式不能随 bet 变）。
+3. **金额是整数分**。`multiplier` 最多两位小数（平台按 centi 存）；`payout` 是 `bet` 的精确线性函数，取整方式不能随 bet 变（bet 恒为 100 的倍数）。
 4. 先 `normalizeBySchema(schema, input.config)` 再用 config——调用方给的可能是部分或越界的值。
 5. 平台有最大倍数上限，超过就进不了表。
 
-装饰性随机（粒子角度、台词抽签）用 `Math.random()`，**放在 `src/view` / 组件里**，绝不进 `round()`：它们不该占用可复现的随机数，否则加一句台词就会改变牌序。
-
 ### `schema`
 
 `ConfigSchema<Config>`，每个字段 = 一种 kind + 元数据 + `default`：
@@ -78,11 +84,11 @@ function round(input: RoundInput<Config>): RoundResult<Outcome>
 | `enum` | `{ options: [{ value, label }] }` | 押哪一面 |
 | `pick` | `{ of: Option[], count, exact?, ordered? }` | 13 选 4 个点数 |
 
-元数据：`label`（`{'zh-CN': …}` 这种 I18n 记录）、`hint?`、`affectsOutcome`（影响结果的字段才进 schema；不影响的放 `ViewSettings`，别写进来）、
+元数据：`label`（`{'zh-CN': …}` 这种 I18n 记录）、`hint?`、`affectsOutcome`（影响结果的字段才进 schema；不影响的放 `ViewSettings`），
 `lock`（`'never' | 'inRound' | 'inRoundOrAuto'`）、`ui`（`'host'` 平台的设置面板渲染 / `'stage'` 你在画布里渲染，但值仍归平台）、
 `devOnly?`（只在开发环境允许，生产被服务端拒绝）、`control?` / `group?` / `order?`（渲染建议）。
 
-平台不认识你的游戏，它只认识 kind——设置 UI 是按 schema 自动渲染的。
+平台不认识你的游戏，只认识 kind——设置 UI 是按 schema 自动渲染的。
 
 ## 能不能打表：`modes` 与 `book`
 
@@ -95,7 +101,7 @@ function round(input: RoundInput<Config>): RoundResult<Outcome>
 modes: [{ name: 'n16g0', config: { N: 16, goldOn: false } }, ...]   // 只写影响分布的字段，每个 mode 写同一组键
 ```
 
-出现在 `mode.config` 里的键就是 `modeKeys`；`modeOf(config)` 按它匹配，匹配不到就抛——那是你的 modes 声明不完整。
+出现在 `mode.config` 里的键就是 `modeKeys`；`modeOf(config)` 按它匹配，匹配不到就抛——那是 modes 声明不完整。
 表数 = modes 数，超过几十张就该把连续参数冻结成几档，或改成从有限档位里选。
 
 `book` 按 probe 的建议选：
@@ -106,40 +112,43 @@ modes: [{ name: 'n16g0', config: { N: 16, goldOn: false } }, ...]   // 只写影
 | 所有影响结果的字段都在 modes 里 | `'seed'`（默认） | 不写。SDK 存采样种子、还原时重跑 `round()` |
 | 有字段只影响这一局（`side`、`ranks` 这类） | `{ encode(s) => Uint8Array }` | 自己写：解码时用玩家**当下**的自由字段。参考 coco 的 `rules/book.ts`：把 ranks 当重标记，存「命中第 k 格」而不是牌 id |
 
-`'seed'` 用错的后果：表里写 0x，客户端按玩家当下选的值算出 4.64x。`restoreFromSeed` 会在还原时抛出来，但那已经是运行时了——先跑 probe。
+`'seed'` 用在有自由字段的游戏上，后果是表里写 0x、客户端按玩家当下选的值算出 4.64x。`restoreFromSeed` 会在还原时抛，但那已经是运行时了——先跑 probe。
 
-### `restore(input)` 的硬契约
+### `restore(input)`
 
 ```ts
 // RestoreInput = { config, bet, payoutCenti, frames: Uint8Array | null, mode, seed }
 ```
 
-**返回的 `payout` 必须恰好等于 `(input.bet / 100) * input.payoutCenti`**，对不上就 `throw`、不演出。
-「玩家看到连成三条线，余额却没动」这类 bug 完全静默，最伤信任。能多验一道就多验：解码出的局面算出的倍数应当等于 `payoutCenti`。
+`payout` 必须恰好等于 `(input.bet / 100) * input.payoutCenti`，对不上就 `throw`，不要「修正」。能多验一道就多验：解码出的局面算出的倍数应当等于 `payoutCenti`。
 `input.config` 是玩家当下的配置（回放时是下注那一刻存下的），先 `normalizeBySchema` 再用。
 
 ## 演出侧：`src/index.ts` 与 `mount`
 
 ```ts
-export default { ...game, mount: mountGame, skins?: Skin[] };
+export default { ...game, mount: mountGame, skins?: Skin[], assets: assets.bundle() };   // assets 来自 gamekit777/runtime
 mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
 ```
 
+`mount` 被调用时 critical 资源已由平台按 `assets` 清单预加载完，进度条也是平台画的；`mount` 里不写加载逻辑。
+资源放 `src/assets/critical|lazy`，组件用 `assets.url(key)` 取地址；字体在 `game.meta.json` 的 `fonts` 里声明。
+
 `Host` 是平台给你的，**全是只读**：`config` / `view` / `wallet` / `jackpot` 四个 `Readable`（`get()` + `subscribe()`），
 `audio.context()`（不要自己 new AudioContext）、`locale`、`emit(event)`、`log()`。
 想改参数只能 `host.requestConfig(patch)` 申请——平台校验、可能否决（局中、自动中）、批了才会从 `host.config` 推回来。
 画布内的控件因此也是受控组件：渲染平台的值，改动走申请。`ViewSettings.autoActive` 为真时禁用画布内的设置控件。
 
 `GameInstance`：`status`（`Readable<GameStatus>`，平台据 `busy` / `canBet` / `canSkip` / `canEditConfig` 控制自己的按钮）、
-`present(result, { rate? })`（演一局，resolve 于演完；`rate: Infinity` 直接看结果）、`preview()`（只演不结账，回放用）、`skip()` / `reset()` / `resize()` / `destroy()`。
+`present(result, { rate? })`（演一局，resolve 于演完；`rate: Infinity` 直接看结果）、`preview(result)`（只演不结账，回放用）、`skip()` / `reset()` / `resize()` / `destroy()`。
 演出开始/结束发 `host.emit({ type: 'present:start' })` / `{ type: 'present:end', payout }`。
 
-约定：
-- **模块级不留可变状态**。`createInstance(host)` 造一棵状态树经 Svelte context 下传，组件 `getInstance()`。同页两个实例互不干扰，`test/e2e.test.ts` 会验。
+- **模块级不留可变状态**。`createInstance(host)` 造一棵状态树经 Svelte context 下传，组件 `getInstance()`。同页会有两个实例（主实例 + 回放），`test/e2e.test.ts` 会验。
 - `turbo` / `reducedMotion` 只改演出时长，改不了结果——它们根本不在 `round()` 的入参里。
 - CSS 命名空间挂在容器 `el` 上（`gk-__ID__`），不写 `document.documentElement`。
 - 画布是固定 900×771 的逻辑画面，平台整体缩放；按这个尺寸排版。
-- 资源放 `src/assets/critical|lazy`，走 `registry.ts` 注册；`game.meta.json` 的 `fonts` 声明字体。
+- **演出先查资源库**：`asset_list` 看有哪些。**animation** 是自足的小组件（赢面弹窗、分档大奖、揭示翻动、上飘文字…），`asset_use <name>` 复制进 `src/animations/` 再按需改；
+  **pattern** 是一套机制加接线清单（荷官说话…），`asset_show <name>` 先读 NOTES 里的接线表和台词写作指南，`asset_use <name>` 复制进 `src/patterns/<name>/` 后把调用按表穿进你的时间轴，
+  文案按这个游戏的角色重写。库是参考实现，复制进来就是你的代码；不要从零写一个库里已有的演出。
 
 ## 工作流（studio 的 MCP 工具）
 
@@ -150,21 +159,11 @@ mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
   → preview_play { rounds, seed?, simId? } 在预览里演几局（本地表模型：就地建表 → 抽行 → restore）
   → case_add                               把值得盯的局面存进 studio/cases.jsonl
   → build_table                            采样 → 求解 → 编码 → 本地终验 → .studio/build/<指纹>/
-  → publish_dry_run → publish              发布要作者在页面上点确认，不可逆
+  → publish_dry_run → publish              一键：vite build → 传包 → 传表 → 发布，不用人确认，不可逆。身份是作者在 studio 页面连过的站点身份；报「没有身份」就让作者打开页面连一次
 ```
 
 - `game_info` 是第一跳：清单、schema、指纹、已建的表、预览连没连。
 - 长任务返回 `jobId` 就用 `job_status` 轮询。
-- `case_run` 任何结果变化都是 `fail`。是有意改的规则且这个 mode 没发布过，`case_bless` 接受；已发布过的 mode 解码逻辑**不能改**，要改就换 slug。
+- `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`。
-
-## 不要做的事
-
-- 不写 `normalize` / `validate` / `modeOf`；不加 `meta`、版本号；不在清单里写注额区间。
-- 不在 `round()` 或 `rules/` 里 import Svelte、DOM、`gamekit777/runtime`。
-- 不用 `Math.random` 决定任何影响赔付的事；不用 `% n` 取整数随机。
-- 不让 `payout` 出现小数或随 bet 变化的取整；`multiplier` 不超过两位小数。
-- 不在 `restore` 里「修正」对不上的 payout——对不上就抛。
-- 不把 `'seed'` 用在有自由字段的游戏上。
-- 不改已发布 mode 的发牌逻辑 / book 编解码 / 取整方式。

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

@@ -1,17 +1,19 @@
 /* 游戏包的浏览器入口 = 清单 + view。平台加载这个文件：
 
-     import game from './dist/games/__ID__/index.js'
+     import game from '/g/<gameId>/<bundleHash>/index.js'   // 平台从 R2 流出的包
      const inst = await game.mount(host, el)
      await inst.present(result)
 
-   清单在根目录的 game.ts，Node 侧（采样、studio）import 的是它；这里只是把 mount 拼上去。 */
+   清单在根目录的 game.ts，Node 侧（采样、studio）import 的是它；这里只是把 mount 拼上去。
+   assets 是 src/assets/ 目录的清单（runtime 按目录生成），平台在 mount 之前按它预加载、画进度条——游戏自己不加载。 */
 import './styles/global.css';
 import './styles/animations.css';
 
+import { assets } from 'gamekit777/runtime';
 import game from '../game.ts';
 import { mountGame } from './view/mount.svelte.ts';
 
 export * from '../game.ts';
 export { mountGame as mount };
 
-export default { ...game, mount: mountGame };
+export default { ...game, mount: mountGame, assets: assets.bundle() };

package/create-game/template/src/view/mount.svelte.ts.tmpl

@@ -3,25 +3,16 @@
    放在 .svelte.ts 里是因为要用 $effect.root——status 是从 runes 派生出来
    推给平台的。 */
 import { mount as svelteMount, unmount } from 'svelte';
-import { ensureFonts, loadAssets, prefetchLazy, type LoadProgress } from 'gamekit777/runtime';
 import type { GameInstance, GameStatus, Host, PresentOptions, Readable, RoundResult } from 'gamekit777/sdk';
 import App from '../components/App.svelte';
 import buildMeta from '../../game.meta.json' with { type: 'json' };
-import { assets } from '../assets/registry.ts';
-import { loadManifest } from '../assets/manifest.ts';
 import { createInstance } from '../context.svelte.ts';
 import type { __PASCAL__Config, __PASCAL__Outcome } from '../rules/types.ts';
 import { present } from './present.ts';
 import { toStore } from './bridge.svelte.ts';
 
-export interface MountOptions {
-  /** 资源加载进度。平台拿它渲染自己的加载条 */
-  onProgress?(p: LoadProgress): void;
-  signal?: AbortSignal;
-}
-
 export async function mountGame(
-  host: Host<__PASCAL__Config>, el: HTMLElement, opts: MountOptions = {}
+  host: Host<__PASCAL__Config>, el: HTMLElement
 ): Promise<GameInstance<__PASCAL__Outcome>> {
   /* 每次 mount 造一棵全新的状态树，同页挂两个实例是安全的 */
   const inst = createInstance(host);
@@ -35,16 +26,6 @@ export async function mountGame(
   teardown.push(host.config.subscribe(c => game.applyConfig(c)));
   teardown.push(host.view.subscribe(v => game.applyView(v)));
 
-  const manifest = await loadManifest(opts.signal);
-  const urls = Object.fromEntries(assets.keys.map(k => [k, assets.url(k)]));
-  let progress = 0;
-  await Promise.all([
-    ensureFonts(buildMeta.fonts ?? []),
-    loadAssets({ manifest, urls, signal: opts.signal,
-                 onProgress: p => { progress = p.ratio; opts.onProgress?.(p); } })
-  ]);
-  progress = 1;
-
   const status = toStore<GameStatus>(() => ({
     phase: game.phase === 'playing' ? 'playing' : game.phase === 'over' ? 'settling' : 'idle',
     busy: game.live,
@@ -52,13 +33,11 @@ export async function mountGame(
     canSkip: game.live,
     /* 和游戏画布内的控件用同一个判断，两边不会打架 */
     canEditConfig: !game.live && !game.autoActive,
-    progress,
     lastPayout: game.lastPayout
   }));
   teardown.push(status.dispose);
 
   const app = svelteMount(App, { target: el, props: { instance: inst } });
-  prefetchLazy(manifest, urls);
   host.emit({ type: 'ready' });
 
   const play = async (r: RoundResult<__PASCAL__Outcome>, o?: PresentOptions): Promise<void> => {

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

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

package/dev-host/DevShell.svelte

@@ -12,6 +12,7 @@
      开发专用的东西（历史、校验、公平证、赔率、定点复现）放在机台下面，不挤进机台里。 */
   import { onMount } from 'svelte';
   import { STAGE_H, STAGE_W, type GameInstance, type GameModule } from '../sdk/index.ts';
+  import { preloadGame } from '../runtime/index.ts';
   import { createPlatform, type HistoryEntry, type PlatformOf } from './platform.svelte.ts';
   import type { PlatformServer } from './platform-server.ts';
   import type { LocalServer } from './local.ts';
@@ -78,9 +79,14 @@
     void (async () => {
       // 先和服务端握手：余额、种子承诺、注额区间都在那边
       await p.init();
+      /* 资源在平台这一侧预加载：进度画在机台上，游戏的 mount 假定 critical 已到齐。
+         图片句柄挂在 pre 上活到卸载——opaque origin 下没有落盘缓存，这份就是唯一一份 */
+      const pre = await preloadGame(game.assets, { onProgress: (x) => p.setLoadProgress(x.ratio) });
+      if (!live) return;
       const i = await game.mount(p.host(), frame!);
       if (!live) { i.destroy(); return; }
       handle = i; inst = i;
+      pre.prefetchLazy();
       off = i.status.subscribe(s => p.setGameStatus(s));
       p.bindGame({ present: (r, rate) => i.present(r, rate ? { rate } : undefined), status: () => p.game });
     })();
@@ -156,7 +162,7 @@
         <Field hint={`区间 ${money(p.limits.min)}–${money(p.limits.max)}，步长 ${money(p.limits.step)}`}>
           {#snippet label()}<label for="bet">注额</label>{/snippet}
           {#snippet accent()}
-            <span>本场 <b class="acc" class:win={p.pnl > 0} class:bad={p.pnl < 0}>{signed(p.pnl)}</b></span>
+            <span>本场 <b class="num" class:win={p.pnl > 0} class:bad={p.pnl < 0}>{signed(p.pnl)}</b></span>
           {/snippet}
           <span class="coin" aria-hidden="true"></span>
           <input id="bet" inputmode="decimal" bind:value={betText} onchange={commitBet} disabled={!p.canBet} />
@@ -207,7 +213,10 @@
     <section class="stage" style="--ratio:{STAGE_W}/{STAGE_H}" bind:this={stage}>
       <div class="gameframe" bind:this={frame} style="width:{STAGE_W}px;height:{STAGE_H}px"></div>
       {#if p.game.phase === 'loading'}
-        <p class="loading">加载资源… {Math.round((p.game.progress ?? 0) * 100)}%</p>
+        <div class="loading">
+          <p>{p.loadProgress === null ? '正在装载游戏…' : `加载资源… ${Math.round(p.loadProgress * 100)}%`}</p>
+          {#if p.loadProgress !== null}<span class="loadbar"><i style="width:{p.loadProgress * 100}%"></i></span>{/if}
+        </div>
       {/if}
     </section>
 
@@ -324,6 +333,18 @@
   .shell { width: min(1200px, calc(100% - 32px)); margin: 0 auto; padding-bottom: 48px; }
   /* 嵌在 studio 里：外面已经决定了这一栏多宽，这里顶满、不留白 */
   .shell.embedded { width: 100%; padding-bottom: 16px; }
+  /* 嵌入时 iframe 的视口就是机台那一栏的宽度，studio 把它缩到 1000 以下很常见（1440 的屏就会），
+     但机台不该因此切成窄屏的上下堆叠——它在 studio 里始终是一台横着的机器。
+     把 theme.css 里窄屏媒体查询改掉的那几条按宽屏写回来 */
+  .shell.embedded .cab { grid-template-columns: 304px minmax(0, 1fr); grid-template-areas: "panel stage" "bar bar"; }
+  .shell.embedded .panel-col { min-height: 0; }
+  .shell.embedded .panel-inner { position: absolute; overflow: hidden; }
+  .shell.embedded .params { flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; }
+  /* 和玩家站点的 game.html 一样：游戏根元素撑满整块逻辑画面，由游戏自己在里面排版。
+     不撑的话根元素按内容高度长，超出 771 的那一截会被舞台裁掉，而且很不显眼 */
+  /* 写成 .stage > .gameframe 是为了压过 theme.css 里同名的 display:block */
+  .stage > .gameframe { display: flex; }
+  .stage > .gameframe > :global(*) { flex: 1; min-width: 0; }
   .top { display: flex; align-items: center; gap: 12px; padding: 14px 4px 0; }
   .top .big { font-size: 22px; color: var(--ink); }
   .intro { display: flex; align-items: baseline; gap: 16px; flex-wrap: wrap; margin: 0 4px 14px; }

package/dev-host/platform.svelte.ts

@@ -94,7 +94,9 @@ export function createPlatform<C, O>(
     err = $state<string | null>(null);
     clientSeed = $state('player-local');
     /** 游戏交回来的状态 */
-    game = $state<GameStatus>({ phase: 'loading', busy: false, canBet: false, canSkip: false, canEditConfig: false, progress: 0 });
+    game = $state<GameStatus>({ phase: 'loading', busy: false, canBet: false, canSkip: false, canEditConfig: false });
+    /** 资源预加载进度 0..1。平台侧的加载器写，游戏不知道有这回事；null = 代码还没下完 */
+    loadProgress = $state<number | null>(null);
     /** 本地服务端已加载的表（mode 名） */
     tableModes = $state<string[]>([]);
 
@@ -136,6 +138,7 @@ export function createPlatform<C, O>(
 
     bindGame(a: GameApi<O>): void { api = a; }
     setGameStatus(s: GameStatus): void { this.game = s; }
+    setLoadProgress(ratio: number): void { this.loadProgress = ratio; }
 
     host(): Host<C> {
       return {

package/dev-host/theme.css

@@ -19,7 +19,6 @@
 
   /* 舞台：游戏画面所在的那块深色区域 */
   --stage: #1A0B11;
-  --tile: #2C161F;
   --s-ink: #FFF1DC;
   --s-dim: #A3858C;
 
@@ -27,7 +26,6 @@
   --coco-d: #A8231A;
   --banana: #FFD21F;
   --banana-d: #B98F00;
-  --cream: #FFF1DC;
   --ok: #2E9E5B;
 
   --num: "Lilita One", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif;
@@ -165,8 +163,12 @@ h3 { font-size: 13px; font-weight: 700; margin: 0 0 8px; }
 }
 .stage .loading {
   position: absolute; inset: 0; margin: 0;
-  display: grid; place-items: center; color: var(--s-dim); font-family: var(--fun); font-size: 18px;
+  display: grid; place-content: center; justify-items: center; gap: 12px;
+  color: var(--s-dim); font-family: var(--fun); font-size: 18px;
 }
+.stage .loading p { margin: 0; }
+.stage .loadbar { display: block; width: 220px; height: 6px; border-radius: 99px; background: rgba(255, 255, 255, .12); overflow: hidden; }
+.stage .loadbar i { display: block; height: 100%; border-radius: 99px; background: var(--banana); transition: width .15s; }
 
 .bar {
   grid-area: bar; display: flex; align-items: center; justify-content: space-between;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamekit777",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "bin": {
     "gamekit777": "./studio/cli.ts"

package/protocol/assets.ts

@@ -0,0 +1,108 @@
+/* 资源库：历史演出经验的归档，两种条目共用一套索引、同步与发布。
+ *
+ *   animation  一个自足的 .svelte 组件，契约只有一条：挂载即播放一次。复制进游戏的 src/animations/
+ *   pattern    一套机制（若干 .ts / .svelte）+ 一个 Demo.svelte（可点的场景，预览用）+ 范例文件（*.example.*）。
+ *              复制进游戏的 src/patterns/<name>/，Demo 和范例不复制；NOTES 里有接线清单，接线要 AI 照着穿进游戏的时间轴
+ *
+ * 内容不进 npm 包：源码在仓库 packages/assets/src/{animations,patterns}/，`bun run assets:push` 按内容寻址传到 R2，
+ * `/a/index.json` 是目录、`/a/<hash>/<file>` 是文件（immutable）。studio 启动后在后台拉，AI 用 MCP 查、看、复制进游戏。 */
+import { z } from 'zod';
+import { BundleFile, BundlePath, bundleManifestText } from './bundles.ts';
+import { Sha256Hex } from './money.ts';
+
+export const AssetKind = z.enum(['animation', 'pattern']);
+export type AssetKind = z.infer<typeof AssetKind>;
+
+export const AssetName = z.string().min(2).max(48).regex(/^[a-z0-9][a-z0-9-]*$/);
+const SvelteFile = z.string().regex(/^[A-Z][A-Za-z0-9]*\.svelte$/);
+
+/** 预览页按它生成旋钮（animation 给组件，pattern 给 Demo）；也是 AI 看「能调什么」的说明 */
+export const AssetProp = z.object({
+  kind: z.enum(['number', 'boolean', 'string', 'enum']),
+  label: z.string().max(40).optional(),
+  default: z.union([z.number(), z.boolean(), z.string()]),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  step: z.number().optional(),
+  /** kind = enum 时的取值 */
+  options: z.array(z.string().max(40)).max(24).optional(),
+}).strict();
+export type AssetProp = z.infer<typeof AssetProp>;
+
+const base = {
+  name: AssetName,
+  title: z.string().min(1).max(60),
+  summary: z.string().min(1).max(200),
+  tags: z.array(z.string().min(1).max(24)).max(12),
+  props: z.record(z.string().regex(/^[a-z][A-Za-z0-9]*$/), AssetProp).default({}),
+  /** 预览舞台的逻辑尺寸，屏幕不够时整体缩放；不填就是 450×385 深色底 */
+  stage: z.object({
+    width: z.int().min(100).max(900).optional(),
+    height: z.int().min(100).max(771).optional(),
+    background: z.string().max(60).optional(),
+  }).strict().optional(),
+};
+
+export const AnimationMeta = z.object({
+  kind: z.literal('animation'),
+  ...base,
+  /** 组件文件名，PascalCase.svelte；复制进游戏时也用这个名 */
+  component: SvelteFile,
+}).strict();
+export type AnimationMeta = z.infer<typeof AnimationMeta>;
+
+export const PatternMeta = z.object({
+  kind: z.literal('pattern'),
+  ...base,
+  /** 预览用的场景组件，只在 studio 里跑，不复制进游戏 */
+  demo: SvelteFile,
+}).strict();
+export type PatternMeta = z.infer<typeof PatternMeta>;
+
+/** asset.json 的形状 */
+export const AssetMeta = z.discriminatedUnion('kind', [AnimationMeta, PatternMeta]);
+export type AssetMeta = z.infer<typeof AssetMeta>;
+
+export const ASSET_REQUIRED = ['asset.json', 'NOTES.md'] as const;
+export const MAX_ASSET_FILE_BYTES = 512 * 1024;
+
+const indexed = { hash: Sha256Hex, files: z.array(BundleFile).min(3) };
+export const AnimationIndexEntry = AnimationMeta.extend(indexed);
+export const PatternIndexEntry = PatternMeta.extend(indexed);
+export const AssetIndexEntry = z.discriminatedUnion('kind', [AnimationIndexEntry, PatternIndexEntry]);
+export type AnimationIndexEntry = z.infer<typeof AnimationIndexEntry>;
+export type PatternIndexEntry = z.infer<typeof PatternIndexEntry>;
+export type AssetIndexEntry = z.infer<typeof AssetIndexEntry>;
+
+export const AssetIndex = z.object({
+  version: z.literal(1),
+  entries: z.array(AssetIndexEntry),
+});
+export type AssetIndex = z.infer<typeof AssetIndex>;
+
+/* /assets 让给了站点的静态产物（vite 的 dist/assets/*），库走短前缀 /a，和游戏包的 /g 同一副样子 */
+export const ASSET_INDEX_PATH = '/a/index.json';
+export const assetFilePath = (hash: string, path: string): string => `/a/${hash}/${path}`;
+export const AssetFilePath = BundlePath;
+/** 条目哈希 = 文件清单文本（path sha256 按 path 排序）的 sha256。内容一字不改哈希就不变 */
+export const assetManifestText = bundleManifestText;
+
+/** 预览时挂的那个组件：animation 是它自己，pattern 是 Demo */
+export const assetPreviewFile = (m: AssetMeta): string => (m.kind === 'animation' ? m.component : m.demo);
+
+/** 复制进游戏时落在哪：animation 一个文件，pattern 一个目录 */
+export const assetTargetDir = (kind: AssetKind): string => (kind === 'animation' ? 'src/animations' : 'src/patterns');
+
+/** 复制进游戏的文件。元数据、NOTES、Demo、范例（*.example.*）都是给人和 AI 看的，不进游戏 */
+export function assetCopyFiles(m: AssetMeta, files: readonly string[]): string[] {
+  if (m.kind === 'animation') return [m.component];
+  return files.filter((f) => f !== 'asset.json' && f !== 'NOTES.md' && f !== m.demo && !/\.example\./.test(f));
+}
+
+export function assetContentType(path: string): string {
+  if (path.endsWith('.svelte') || path.endsWith('.ts')) return 'text/plain; charset=utf-8';
+  if (path.endsWith('.css')) return 'text/css; charset=utf-8';
+  if (path.endsWith('.md')) return 'text/markdown; charset=utf-8';
+  if (path.endsWith('.json')) return 'application/json; charset=utf-8';
+  return 'application/octet-stream';
+}

package/protocol/bundles.ts

@@ -0,0 +1,74 @@
+/* 游戏包：vite build 出来的 index.js / manifest.json / meta.json / assets，按内容寻址存进 R2。
+ *
+ * 包不是审计对象——公平性的审计对象是表。包只是演出，所以已发布的游戏允许换包（修 UI、改演出），
+ * 表照旧不可变。「已发布 mode 的解码逻辑不能改」这条由 case 库和 restore 契约守，与包是否更新无关。
+ *
+ * 寻址：bundles/<gameId>/<bundleHash>/<path>。bundleHash 是文件清单（路径 + 各文件 sha256）的 sha256，
+ * 内容不变哈希就不变，所以对象永远不覆盖、可以 Cache-Control: immutable。 */
+import { z } from 'zod';
+import { Sha256Hex } from './money.ts';
+
+/** 平台加载游戏时必须有的三个文件；其余（assets/…）随意 */
+export const BUNDLE_REQUIRED = ['index.js', 'manifest.json', 'meta.json'] as const;
+export const MAX_BUNDLE_FILE_BYTES = 20 * 1024 * 1024;
+export const MAX_BUNDLE_FILES = 400;
+export const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+
+/** 相对路径：每一段以字母数字开头（挡掉 . 和 ..），只允许字母数字 . _ - 和 / */
+export const BundlePath = z.string().min(1).max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/, '路径只能是 a-z 0-9 . _ - 和 /，每段以字母数字开头');
+export type BundlePath = z.infer<typeof BundlePath>;
+
+export const BundleFile = z.object({
+  path: BundlePath,
+  sha256: Sha256Hex,
+  bytes: z.int().min(0).max(MAX_BUNDLE_FILE_BYTES),
+});
+export type BundleFile = z.infer<typeof BundleFile>;
+
+export const BundleCommit = z.object({
+  files: z.array(BundleFile).min(1).max(MAX_BUNDLE_FILES),
+});
+export type BundleCommit = z.infer<typeof BundleCommit>;
+
+/** 站点加载游戏要的全部信息：包哈希和入口 URL（同源相对路径，由平台流出） */
+export const BundleRef = z.object({
+  hash: Sha256Hex,
+  /** game.meta.json 的 version，给人看的。缓存键是 hash：内容变了地址一定变，没变一定不变 */
+  version: z.string(),
+  entry: z.string(),
+  files: z.int(),
+  bytes: z.int(),
+  createdAt: z.int(),
+});
+export type BundleRef = z.infer<typeof BundleRef>;
+
+export const BundleFileResult = z.object({ path: BundlePath, bytes: z.int(), sha256: Sha256Hex });
+export type BundleFileResult = z.infer<typeof BundleFileResult>;
+
+export const BundleCommitResult = z.object({ bundle: BundleRef });
+export type BundleCommitResult = z.infer<typeof BundleCommitResult>;
+
+/**
+ * 清单的规范文本：按路径排序，一行一个 `path sha256`。两端（上传方、服务端）都对它算 sha256 得到 bundleHash。
+ * 放在协议里而不是各写一份，是因为一个空格的差别就是两个哈希、永远对不上。
+ */
+export function bundleManifestText(files: readonly { path: string; sha256: string }[]): string {
+  return [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .map((f) => `${f.path} ${f.sha256}`).join('\n') + '\n';
+}
+
+export const bundleEntryPath = (gameId: string, hash: string): string => `/g/${gameId}/${hash}/index.js`;
+
+/** R2 对象的 content-type 按扩展名给：模块脚本没有 JS 的 MIME 浏览器会拒绝 import */
+export function bundleContentType(path: string): string {
+  const ext = path.split('.').pop()?.toLowerCase() ?? '';
+  return ({
+    js: 'text/javascript; charset=utf-8', mjs: 'text/javascript; charset=utf-8', json: 'application/json; charset=utf-8',
+    css: 'text/css; charset=utf-8', html: 'text/html; charset=utf-8', txt: 'text/plain; charset=utf-8', map: 'application/json',
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif',
+    woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', otf: 'font/otf',
+    mp3: 'audio/mpeg', ogg: 'audio/ogg', wav: 'audio/wav', m4a: 'audio/mp4', webm: 'video/webm', mp4: 'video/mp4',
+    wasm: 'application/wasm',
+  } as Record<string, string>)[ext] ?? 'application/octet-stream';
+}