gamekit777 0.1.2 → 0.1.5

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';
+}

package/protocol/errors.ts

@@ -19,6 +19,9 @@ export const ErrorCode = z.enum([
   'RTP_MISMATCH',
   'RTP_OUT_OF_BOUNDS',
   'PAYLOAD_TOO_LARGE',
+  'BUNDLE_MISSING',
+  'BUNDLE_INVALID',
+  'SLUG_TAKEN',
   'RATE_LIMITED',
   'INTERNAL',
 ]);
@@ -53,6 +56,9 @@ export const HTTP_STATUS: Record<ErrorCode, number> = {
   RTP_MISMATCH: 422,
   RTP_OUT_OF_BOUNDS: 422,
   PAYLOAD_TOO_LARGE: 413,
+  BUNDLE_MISSING: 409,
+  BUNDLE_INVALID: 422,
+  SLUG_TAKEN: 409,
   RATE_LIMITED: 429,
   INTERNAL: 500,
 };

package/protocol/games.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { BundleRef } from './bundles.ts';
 import { Cents, MAX_BET_CENTS, PayoutCenti, Ppm, RtpPpm, Sha256Hex } from './money.ts';
 
 export const GameStatus = z.enum([
@@ -63,6 +64,8 @@ export const CreateGame = z.object({
 export type CreateGame = z.infer<typeof CreateGame>;
 
 export const UpdateGame = z.object({
+  /** 只有草稿能改：已发布的 slug 是站点 URL 和历史局的一部分 */
+  slug: CreateGame.shape.slug.optional(),
   title: z.string().min(1).max(80).optional(),
   description: z.string().max(2000).nullable().optional(),
   declaredRtpPpm: RtpPpm.optional(),
@@ -105,6 +108,8 @@ export const Game = z.object({
   configHash: Sha256Hex,
   gameHash: Sha256Hex.nullable(),
   activeTableId: z.uuid().nullable(),
+  /** 站点从这里加载游戏代码。null = 还没上传包，大厅不列、进不去 */
+  bundle: BundleRef.nullable(),
   publishedAt: z.int().nullable(),
   createdAt: z.int(),
   updatedAt: z.int(),

package/protocol/index.ts

@@ -8,3 +8,5 @@ export * from './seeds.ts';
 export * from './session.ts';
 export * from './verify.ts';
 export * from './pair.ts';
+export * from './bundles.ts';
+export * from './assets.ts';

package/publish/upload-core.ts

@@ -8,7 +8,7 @@ import {
 } from '../protocol/index.ts';
 import type { GameKitClient } from '../client/index.ts';
 import { HEADER_BYTES, ROW_BYTES, decodeHeader, readRow, type Verdict } from '../lut/index.ts';
-import type { GameDefinition } from '../sdk/index.ts';
+import type { GameDefinition, Paytable } from '../sdk/index.ts';
 
 /** 上传只需要 BuiltTable 的这几个字段。studio 从产物文件里拼出来的也能过 */
 export interface UploadTable {
@@ -19,10 +19,33 @@ export interface UploadTable {
   betCostCenti: number;
   books: { simId: number; frames: string }[] | null;
   verdict: Pick<Verdict, 'computedRtpPpm'>;
+  /** 这张表对应配置的赔率行。不给就用 spec.paytableFor(spec.configOf(mode)) 算——studio 的主进程没有游戏代码，只能预先算好带进来 */
+  paytable?: Paytable;
 }
 
+/**
+ * 上传只需要清单里的这几项。GameDefinition 直接满足；studio 主进程从 worker 拿回的纯数据快照也满足
+ * （它没有 paytableFor / configOf，所以每张表要自带 paytable）
+ */
+export type UploadSpec<C = unknown, O = unknown> =
+  Pick<GameDefinition<C, O>, 'slug' | 'title' | 'description' | 'rtp' | 'autoplay'>
+  & Partial<Pick<GameDefinition<C, O>, 'paytableFor' | 'configOf'>>;
+
+export interface BundleFileInput { path: string; bytes: Uint8Array }
+
 export interface UploadOptions {
   client: GameKitClient;
+  /**
+   * 平台分配的游戏 id（game.meta.json 的 gameId）。给了就只认它：slug 只是它的一个属性，草稿阶段可以改。
+   * 不给就新建一个游戏——**不会**按 slug 去找旧的：同一台机器上两个目录都叫 my-game 时，按名字找会把
+   * 这个项目的表传进那个项目的游戏里。返回的 game.id 由调用方写回 game.meta.json，下次就是同一个游戏
+   */
+  gameId?: string | null;
+  /**
+   * 游戏包（vite build 的产物）。发布前必须有——没有包的游戏站点加载不了，服务端会拒绝发布。
+   * 不给就假定这个游戏已经传过包（只换表 / 新增 mode）
+   */
+  bundle?: readonly BundleFileInput[];
   /** 只发布这些 mode。不给就全发 */
   publishModes?: readonly string[];
   chunkRows?: number;
@@ -59,9 +82,11 @@ function histogramOf(bytes: Uint8Array): { weights: Map<number, number>; total:
  * betModes 和表的 mode 不是一回事：前者是「花多少钱买一注」，后者是「用哪张表」。
  * coco 的 22 个 mode 成本完全相同，塞进 betModes 只会撑爆它的 8 个上限。
  */
-export function describeConfig<C, O>(spec: GameDefinition<C, O>, tables: readonly UploadTable[]): GameConfig {
+export function describeConfig<C, O>(spec: UploadSpec<C, O>, tables: readonly UploadTable[]): GameConfig {
   const paytables = tables.map((t) => {
-    const rows = spec.paytableFor(spec.configOf(t.mode));
+    const rows = t.paytable ?? (spec.paytableFor && spec.configOf
+      ? spec.paytableFor(spec.configOf(t.mode))
+      : (() => { throw new GameKitError('VALIDATION_FAILED', `表 ${t.mode} 没带赔率行，清单也没有 paytableFor`); })());
     const { weights, total } = histogramOf(t.bytes);
     return {
       mode: t.mode,
@@ -80,7 +105,7 @@ export function describeConfig<C, O>(spec: GameDefinition<C, O>, tables: readonl
 }
 
 /** 注额区间是运营侧的事，不在游戏清单里——后端按默认值建，之后由 games.update 调 */
-const gameFields = <C, O>(spec: GameDefinition<C, O>): Omit<CreateGame, 'slug' | 'config'> => ({
+const gameFields = <C, O>(spec: UploadSpec<C, O>): Omit<CreateGame, 'slug' | 'config'> => ({
   title: spec.title,
   description: spec.description,
   declaredRtpPpm: Math.round(spec.rtp * 1e6),
@@ -99,28 +124,83 @@ async function findBySlug(api: GameKitClient, slug: string): Promise<Game | null
   }
 }
 
+/** 按 gameId 取回自己的游戏，把三种「不是你想的那个」都翻成能照着做的话 */
+async function resolveGame<C, O>(api: GameKitClient, spec: UploadSpec<C, O>, gameId: string, config: GameConfig, say: (m: string) => void): Promise<Game> {
+  const me = await api.session.me().catch(() => {
+    throw new GameKitError('UNAUTHENTICATED', '没有身份。先在 studio 页面连接一次站点身份');
+  });
+  let game: Game;
+  try {
+    game = await api.games.get(gameId);
+  } catch (e) {
+    if (e instanceof GameKitError && e.code === 'NOT_FOUND') {
+      throw new GameKitError('NOT_FOUND',
+        `game.meta.json 里的 gameId ${gameId} 在这个平台上不存在（换了平台或库？）。删掉 gameId 字段会新建一个游戏`);
+    }
+    throw e;
+  }
+  if (game.ownerId !== me.user.id) {
+    throw new GameKitError('FORBIDDEN',
+      `游戏 ${gameId}（${game.slug}）归另一个账号。换回那个身份，或删掉 game.meta.json 的 gameId 用当前身份新建`);
+  }
+  if (game.status === 'published') {
+    if (game.slug !== spec.slug) {
+      throw new GameKitError('GAME_IMMUTABLE',
+        `游戏 ${gameId} 已发布为 "${game.slug}"，slug 不能改成 "${spec.slug}"——那是站点 URL 和历史局的一部分。要改名就删掉 gameId 另建一个`);
+    }
+    say(`${spec.slug} 已发布（${game.id.slice(0, 8)}…）：已生效的 mode 不动`);
+    return game;
+  }
+  game = await api.games.update(game.id, { slug: spec.slug, ...gameFields(spec), config });
+  say(`更新草稿 ${game.id.slice(0, 8)}…`);
+  return game;
+}
+
 export async function uploadTables<C, O>(
-  spec: GameDefinition<C, O>, tables: readonly UploadTable[], opts: UploadOptions,
+  spec: UploadSpec<C, O>, tables: readonly UploadTable[], opts: UploadOptions,
 ): Promise<UploadResult> {
   const api = opts.client;
   const say = opts.onProgress ?? (() => {});
   const config = describeConfig(spec, tables);
 
-  let game = await findBySlug(api, spec.slug);
-  if (game?.status === 'published') {
-    throw new GameKitError('GAME_IMMUTABLE',
-      `slug "${spec.slug}" 已经发布过了。已发布的游戏不能换表——改个 slug 发一个新版本`);
-  }
-  if (game) {
-    game = await api.games.update(game.id, { ...gameFields(spec), config });
-    say(`复用草稿 ${game.id.slice(0, 8)}…`);
+  let game: Game;
+  if (opts.gameId) {
+    game = await resolveGame(api, spec, opts.gameId, config, say);
   } else {
+    /* 不按 slug 复用。但撞了要说清楚是哪种情况：同一个项目忘了写 gameId，还是另一个项目起了同样的名字 */
+    const dup = await findBySlug(api, spec.slug);
+    if (dup) {
+      throw new GameKitError('VALIDATION_FAILED',
+        `你已经有一个 slug 为 "${spec.slug}" 的游戏（${dup.id}，${dup.status}）。` +
+        `如果就是这个项目，把 "gameId": "${dup.id}" 写进 game.meta.json；如果是另一个项目，改 game.meta.json 的 id`);
+    }
     game = await api.games.create({ slug: spec.slug, config, ...gameFields(spec) });
-    say(`新建游戏 ${game.id.slice(0, 8)}…`);
+    say(`新建游戏 ${game.id}（写进 game.meta.json 的 gameId，之后都认它）`);
+  }
+
+  if (opts.bundle) {
+    say(`上传游戏包：${opts.bundle.length} 个文件`);
+    await api.bundles.upload(game.id, opts.bundle, say);
+  } else if (!game.bundle) {
+    throw new GameKitError('BUNDLE_MISSING', `游戏 ${spec.slug} 还没有客户端包，发布会被拒。先 vite build，把 dist/ 一起传`);
+  }
+
+  /* 表按 mode 不可变：已经生效的 mode 一律跳过，只传新的。
+     于是同一条命令既是首发也是「加 mode」也是「只换包」，不用调用方自己分辨游戏处在哪个状态 */
+  const live = new Set((await api.games.get(game.id)).modes.map((m) => m.mode));
+  const fresh = tables.filter((t) => !live.has(t.mode));
+  for (const t of tables) if (live.has(t.mode)) say(`[${t.mode}] 已生效，跳过（表不可变；要改就换 slug）`);
+  if (fresh.length === 0) {
+    if (!opts.bundle) {
+      throw new GameKitError('GAME_IMMUTABLE',
+        `slug "${spec.slug}" 的 ${tables.length} 个 mode 都已发布，没有新表也没有新包，无事可做。改表就换 slug；只想换包就把 dist/ 一起传`);
+    }
+    say(`只更新了客户端包`);
+    return { game: await api.games.get(game.id), tables: [], published: true };
   }
 
   const uploaded: GameTable[] = [];
-  for (const t of tables) {
+  for (const t of fresh) {
     const { table, resumed } = await api.tables.declare(game.id, {
       mode: t.mode, format: 'GKLT1', rowCount: t.rowCount,
       byteLength: t.bytes.length, contentHash: t.contentHash, betCostCenti: t.betCostCenti,

package/publish/upload.ts

@@ -4,13 +4,29 @@
  * 而 games 的唯一约束是 (owner_id, slug)——同一个 slug 会在库里堆出很多份，
  * `findBySlug` 也永远找不到上次传的那个草稿。
  * 纯逻辑在 upload-core.ts，浏览器里的 studio 直接用那一份。 */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
 import { createClient } from '../client/index.ts';
 import { fileCookieStore } from '../client/node.ts';
 import type { BuiltTable } from './build.ts';
 import type { PublishSpec } from './spec.ts';
 import { uploadTables as uploadCore, type UploadOptions as CoreOptions, type UploadResult } from './upload-core.ts';
 
-export { describeConfig, type UploadResult, type UploadTable } from './upload-core.ts';
+export { describeConfig, type BundleFileInput, type UploadResult, type UploadTable } from './upload-core.ts';
+
+/** 把 vite build 出来的 dist/ 读成上传用的文件列表。路径用 /，和平台上的对象键一致 */
+export function bundleFromDir(dir: string): { path: string; bytes: Uint8Array }[] {
+  const out: { path: string; bytes: Uint8Array }[] = [];
+  const walk = (d: string): void => {
+    for (const n of readdirSync(d).sort()) {
+      const p = join(d, n);
+      if (statSync(p).isDirectory()) walk(p);
+      else out.push({ path: relative(dir, p).split('\\').join('/'), bytes: new Uint8Array(readFileSync(p)) });
+    }
+  };
+  walk(dir);
+  return out;
+}
 
 export interface UploadOptions extends Omit<CoreOptions, 'client'> {
   baseUrl?: string;

package/runtime/assets.ts

@@ -5,15 +5,15 @@
    1. 用固定并发池，不用裸 Promise.all。五十张图同时 decode 会把主线程压死，
       进度条反而不动——看起来更慢。
    2. 进度按**字节**加权而不是按个数。按个数会出现「99% 卡住等那张 2MB 的图」。
+      开发环境不知道字节数（bytes 为 null），退化成按个数。
    3. 所有图片都设 crossOrigin='anonymous'。游戏文件夹可能放在 CDN 上，
       而特效层迟早会把图画进 canvas；没有这一条，那时候画布会被污染，
       而且报错离原因很远。 */
-import type { AssetEntry, GameManifest, LoadProgress, LoadedAssets } from './types.ts';
+import type { AssetBundle, AssetEntry } from '../sdk/index.ts';
+import type { LoadProgress, LoadedAssets } from './types.ts';
 
 export interface LoadOptions {
-  manifest: GameManifest;
-  /** registry 给出的 key → 运行时 URL（已经过 import.meta.url 解析） */
-  urls: Record<string, string>;
+  bundle: AssetBundle;
   onProgress?(p: LoadProgress): void;
   signal?: AbortSignal;
   audioContext?: AudioContext;
@@ -23,21 +23,24 @@ export interface LoadOptions {
   priority?: 'critical' | 'lazy';
 }
 
+/* 有一个条目不知道大小，整组就按个数算：混着算会让那一个「零字节」瞬间完成，进度失真 */
+const weightOf = (entries: AssetEntry[]): ((a: AssetEntry) => number) =>
+  entries.every(a => a.bytes !== null && a.bytes > 0) ? a => a.bytes! : () => 1;
+
 export async function loadAssets(opts: LoadOptions): Promise<LoadedAssets> {
-  const { manifest, urls, onProgress, signal, concurrency = 6, priority = 'critical' } = opts;
-  const entries = manifest.assets.filter(a => a.priority === priority);
+  const { bundle, onProgress, signal, concurrency = 6, priority = 'critical' } = opts;
+  const entries = bundle.entries.filter(a => a.priority === priority);
+  const weight = weightOf(entries);
 
   const images = new Map<string, HTMLImageElement>();
   const audios = new Map<string, AudioBuffer>();
   const failed: string[] = [];
 
-  const total = entries.reduce((s, a) => s + a.bytes, 0) || 1;
+  const total = entries.reduce((s, a) => s + weight(a), 0) || 1;
   let loaded = 0, done = 0;
 
-  const resolve = (a: AssetEntry): string => urls[a.key] ?? new URL(a.path, location.href).href;
-
   const bump = (a: AssetEntry): void => {
-    loaded += a.bytes; done++;
+    loaded += weight(a); done++;
     onProgress?.({
       ratio: Math.min(1, loaded / total), loaded, total,
       done, count: entries.length, current: a.key
@@ -45,7 +48,7 @@ export async function loadAssets(opts: LoadOptions): Promise<LoadedAssets> {
   };
 
   async function one(a: AssetEntry): Promise<void> {
-    const url = resolve(a);
+    const url = a.url;
     try {
       if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
 
@@ -99,19 +102,20 @@ export async function loadAssets(opts: LoadOptions): Promise<LoadedAssets> {
   return {
     image: k => images.get(k) ?? null,
     audio: k => audios.get(k) ?? null,
-    url: k => urls[k] ?? k,
+    url: k => bundle.entries.find(a => a.key === k)?.url ?? k,
     failed
   };
 }
 
 /** 后台预取 lazy 资源。不阻塞、不报错、不影响开场 */
-export function prefetchLazy(manifest: GameManifest, urls: Record<string, string>): void {
+export function prefetchLazy(bundle: AssetBundle): void {
+  if (!bundle.entries.some(a => a.priority === 'lazy')) return;
   const run = (): void => {
-    for (const a of manifest.assets) {
+    for (const a of bundle.entries) {
       if (a.priority !== 'lazy') continue;
       const l = document.createElement('link');
       l.rel = 'prefetch';
-      l.href = urls[a.key] ?? a.path;
+      l.href = a.url;
       l.as = a.type === 'image' ? 'image' : a.type === 'audio' ? 'audio' : 'fetch';
       l.crossOrigin = 'anonymous';
       document.head.appendChild(l);

package/runtime/fonts.ts

@@ -6,6 +6,7 @@
 const injected = new Set<string>();
 
 export function ensureFonts(hrefs: readonly string[]): Promise<unknown> {
+  if (hrefs.length === 0) return Promise.resolve();
   for (const href of hrefs) {
     if (injected.has(href)) continue;
     injected.add(href);

package/runtime/index.ts

@@ -1,3 +1,5 @@
 export * from './assets.ts';
 export * from './fonts.ts';
+export * from './preload.ts';
+export * from './registry.ts';
 export * from './types.ts';

package/runtime/preload.ts

@@ -0,0 +1,38 @@
+/* 平台侧的预加载：拿到游戏模块之后、mount 之前调一次。
+
+   玩家站点的 iframe、dev-host、studio 预览三处共用这一份——进度条的分母、字体的等待、
+   lazy 资源的预取时机，只在这里定义一次。游戏对此无感：它的 mount 假定 critical 资源已经到齐。 */
+import type { AssetBundle } from '../sdk/index.ts';
+import { loadAssets, prefetchLazy } from './assets.ts';
+import { ensureFonts } from './fonts.ts';
+import type { LoadProgress, LoadedAssets } from './types.ts';
+
+export interface PreloadOptions {
+  onProgress?(p: LoadProgress): void;
+  signal?: AbortSignal;
+}
+
+export interface Preloaded {
+  assets: LoadedAssets;
+  /** mount 之后调：lazy 资源不该和开场抢带宽 */
+  prefetchLazy(): void;
+}
+
+const EMPTY: LoadedAssets = { image: () => null, audio: () => null, url: k => k, failed: [] };
+
+export async function preloadGame(bundle: AssetBundle | undefined, opts: PreloadOptions = {}): Promise<Preloaded> {
+  // 老包或者没有资源的游戏：没有清单就没有可等的
+  if (!bundle) return { assets: EMPTY, prefetchLazy() {} };
+
+  const [assets] = await Promise.all([
+    loadAssets({ bundle, signal: opts.signal, onProgress: opts.onProgress }),
+    ensureFonts(bundle.fonts)
+  ]);
+  /* 字体和资源并行，谁后到都可能让最后一帧进度停在 <100%；
+     收尾补一条满格，平台的条能走到底再切到画面 */
+  const count = bundle.entries.filter(a => a.priority === 'critical').length;
+  opts.onProgress?.({ ratio: 1, loaded: 1, total: 1, done: count, count });
+
+  // 图片句柄要活到游戏卸载：opaque origin 下 Chrome 不落盘缓存，内存里的这份就是唯一一份
+  return { assets, prefetchLazy: () => prefetchLazy(bundle) };
+}

package/runtime/registry.ts

@@ -0,0 +1,74 @@
+/* 资源注册表。目录即清单：
+     src/assets/critical/  首屏必需，平台开场前加载完
+     src/assets/lazy/      按需，挂载后后台预取
+
+   游戏不写任何加载代码：组件用 assets.url(key) 取地址，index.ts 把 assets.bundle() 交给平台，
+   平台在 mount 之前按清单预加载并画进度条。谁去加载、进度怎么算，游戏不知道也不该知道。
+
+   glob 写在这个库文件里而不是每个游戏一份：以 / 开头的模式按 vite 的 root 解析，
+   而游戏的 vite root 就是游戏目录，所以从任何位置 import 这个模块看到的都是该游戏的 src/assets。
+   代价是 root 不是游戏目录时（比如玩家站点自己 import 了 runtime）清单为空——那里也没人调 bundle()。
+
+   ?no-inline 不是可选项。Vite 的 lib 模式会**无条件**把资源 base64 内联进 JS
+   （见 vite/dist/node/chunks/config.js 的 shouldInline：build.lib 为真时直接
+   return true，assetsInlineLimit 完全失效），唯一的逃生口就是这个 query。
+   漏掉的话构建照样成功，只是资源悄悄胖进 index.js、不在 manifest 里、
+   平台预加载不到——所以 manifest 插件里还有一道 base64 告警兜底。 */
+/// <reference types="vite/client" />
+import type { AssetBundle, AssetEntry, AssetType } from '../sdk/index.ts';
+
+const critical = import.meta.glob('/src/assets/critical/**/*', {
+  eager: true, query: '?no-inline', import: 'default'
+}) as Record<string, string>;
+
+const lazy = import.meta.glob('/src/assets/lazy/**/*', {
+  eager: true, query: '?no-inline', import: 'default'
+}) as Record<string, string>;
+
+/** key 形如 'critical/coco-classic.jpg'，value 是带 hash 的运行时 URL */
+const table: Record<string, string> = {};
+for (const [k, v] of Object.entries({ ...critical, ...lazy })) {
+  table[k.replace(/^\/src\/assets\//, '')] = v;
+}
+
+/* 两个构建期才知道的值。
+   字体列表由 vite-config 用 define 注入（dev 和 build 都有）；
+   字节数只有 generateBundle 之后才知道，manifest 插件把它替换进这个字符串字面量——
+   开发环境没人替换，字面量原样留着，进度退化成按个数走 */
+declare const __GAMEKIT_FONTS__: readonly string[] | undefined;
+const BYTES_PLACEHOLDER = '__GAMEKIT_ASSET_BYTES__';
+const bytesOf: Record<string, number> | null = BYTES_PLACEHOLDER.startsWith('{') ? JSON.parse(BYTES_PLACEHOLDER) as Record<string, number> : null;
+const fonts: readonly string[] = typeof __GAMEKIT_FONTS__ !== 'undefined' ? __GAMEKIT_FONTS__ : [];
+
+const TYPE_BY_EXT: Record<string, AssetType> = {
+  jpg: 'image', jpeg: 'image', png: 'image', webp: 'image', avif: 'image', svg: 'image', gif: 'image',
+  mp3: 'audio', ogg: 'audio', wav: 'audio', m4a: 'audio',
+  woff: 'font', woff2: 'font', ttf: 'font', otf: 'font',
+  json: 'json', mp4: 'video', webm: 'video'
+};
+
+const entryOf = (key: string): AssetEntry => ({
+  key,
+  url: table[key],
+  type: TYPE_BY_EXT[key.split('.').pop()!.toLowerCase()] ?? 'binary',
+  priority: key.startsWith('lazy/') ? 'lazy' : 'critical',
+  bytes: bytesOf?.[key] ?? null
+});
+
+export const assets = {
+  url(key: string): string {
+    const u = table[key];
+    if (!u) throw new Error(`[assets] 未知资源: ${key}（现有: ${Object.keys(table).join(', ')}）`);
+    return u;
+  },
+  has: (key: string): boolean => key in table,
+  keys: Object.keys(table),
+  all: table as Readonly<Record<string, string>>,
+  /** 交给平台的清单。critical 在前，同优先级按名字排，和 manifest.json 一致 */
+  bundle(): AssetBundle {
+    const entries = Object.keys(table).map(entryOf);
+    entries.sort((x, y) =>
+      x.priority === y.priority ? x.key.localeCompare(y.key) : x.priority === 'critical' ? -1 : 1);
+    return { fonts: [...fonts], entries };
+  }
+};