gamekit777 0.1.0

package/runtime/assets.ts

@@ -0,0 +1,122 @@
+/* 资源并发预加载。
+
+   三个不太显然但很要紧的决定：
+
+   1. 用固定并发池，不用裸 Promise.all。五十张图同时 decode 会把主线程压死，
+      进度条反而不动——看起来更慢。
+   2. 进度按**字节**加权而不是按个数。按个数会出现「99% 卡住等那张 2MB 的图」。
+   3. 所有图片都设 crossOrigin='anonymous'。游戏文件夹可能放在 CDN 上，
+      而特效层迟早会把图画进 canvas；没有这一条，那时候画布会被污染，
+      而且报错离原因很远。 */
+import type { AssetEntry, GameManifest, LoadProgress, LoadedAssets } from './types.ts';
+
+export interface LoadOptions {
+  manifest: GameManifest;
+  /** registry 给出的 key → 运行时 URL（已经过 import.meta.url 解析） */
+  urls: Record<string, string>;
+  onProgress?(p: LoadProgress): void;
+  signal?: AbortSignal;
+  audioContext?: AudioContext;
+  /** 并发上限。HTTP/2 下网络不是瓶颈，解码才是，6~8 合适 */
+  concurrency?: number;
+  /** 只加载这个优先级，默认 critical */
+  priority?: 'critical' | 'lazy';
+}
+
+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 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;
+  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++;
+    onProgress?.({
+      ratio: Math.min(1, loaded / total), loaded, total,
+      done, count: entries.length, current: a.key
+    });
+  };
+
+  async function one(a: AssetEntry): Promise<void> {
+    const url = resolve(a);
+    try {
+      if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
+
+      if (a.type === 'image') {
+        const img = new Image();
+        img.crossOrigin = 'anonymous';
+        img.decoding = 'async';
+        img.src = url;
+        /* decode() 把解码也提前做掉，首帧不会因为解码抖一下。
+           部分 Safari 版本的 decode() 有坑，回落到 onload */
+        await img.decode().catch(() => new Promise<void>((res, rej) => {
+          if (img.complete && img.naturalWidth) return res();
+          img.onload = () => res();
+          img.onerror = () => rej(new Error('image load failed'));
+        }));
+        images.set(a.key, img);
+
+      } else if (a.type === 'audio') {
+        const buf = await fetch(url, { signal, mode: 'cors' }).then(r => {
+          if (!r.ok) throw new Error(`HTTP ${r.status}`);
+          return r.arrayBuffer();
+        });
+        if (opts.audioContext) audios.set(a.key, await opts.audioContext.decodeAudioData(buf));
+
+      } else {
+        // font / json / binary：进了 HTTP 缓存，之后同步用就不会闪
+        const r = await fetch(url, { signal, mode: 'cors' });
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        await r.arrayBuffer();
+      }
+    } catch (e) {
+      if ((e as Error).name === 'AbortError') throw e;
+      // 单个资源失败不炸整局：记下来让游戏自己降级
+      console.warn(`[assets] ${a.key} 加载失败，降级处理`, e);
+      failed.push(a.key);
+    } finally {
+      bump(a);
+    }
+  }
+
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, entries.length) }, async () => {
+      while (cursor < entries.length) {
+        if (signal?.aborted) return;
+        await one(entries[cursor++]);
+      }
+    })
+  );
+
+  return {
+    image: k => images.get(k) ?? null,
+    audio: k => audios.get(k) ?? null,
+    url: k => urls[k] ?? k,
+    failed
+  };
+}
+
+/** 后台预取 lazy 资源。不阻塞、不报错、不影响开场 */
+export function prefetchLazy(manifest: GameManifest, urls: Record<string, string>): void {
+  const run = (): void => {
+    for (const a of manifest.assets) {
+      if (a.priority !== 'lazy') continue;
+      const l = document.createElement('link');
+      l.rel = 'prefetch';
+      l.href = urls[a.key] ?? a.path;
+      l.as = a.type === 'image' ? 'image' : a.type === 'audio' ? 'audio' : 'fetch';
+      l.crossOrigin = 'anonymous';
+      document.head.appendChild(l);
+    }
+  };
+  if ('requestIdleCallback' in window) requestIdleCallback(run);
+  else setTimeout(run, 1500);
+}

package/runtime/fonts.ts

@@ -0,0 +1,21 @@
+/* 字体注入。
+
+   必须挂到主文档的 head，不能挂进游戏容器：@font-face 在 shadow root 里
+   会被规范性忽略，在普通容器里虽然能生效但没有去重。
+   幂等——同页两个游戏用同一份字体只会注入一次。 */
+const injected = new Set<string>();
+
+export function ensureFonts(hrefs: readonly string[]): Promise<unknown> {
+  for (const href of hrefs) {
+    if (injected.has(href)) continue;
+    injected.add(href);
+    const l = document.createElement('link');
+    l.rel = 'stylesheet';
+    l.href = href;
+    l.crossOrigin = 'anonymous';
+    document.head.appendChild(l);
+  }
+  /* 等字体真的可用再开场，否则开场动画会被 FOUT 打断。
+     document.fonts 不存在（老 WebView）就直接放行 */
+  return document.fonts?.ready ?? Promise.resolve();
+}

package/runtime/index.ts

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

package/runtime/types.ts

@@ -0,0 +1,42 @@
+/* 与 @gamekit/vite-config 的 manifest 插件产出的 manifest.json 对应。
+   两边各自声明而不是互相 import：runtime 会被打进游戏产物，
+   不该为了一个类型把构建期的包拖进运行时依赖图。 */
+export type AssetType = 'image' | 'audio' | 'font' | 'json' | 'video' | 'binary';
+
+export interface AssetEntry {
+  key: string;
+  path: string;
+  type: AssetType;
+  bytes: number;
+  priority: 'critical' | 'lazy';
+}
+
+export interface GameManifest {
+  id: string;
+  version: string;
+  generatedAt: string;
+  entry: string;
+  css: string | null;
+  totalBytes: number;
+  criticalBytes: number;
+  assets: AssetEntry[];
+}
+
+export interface LoadProgress {
+  /** 已加载字节 / 总字节 */
+  ratio: number;
+  loaded: number;
+  total: number;
+  /** 已完成个数 / 总个数 */
+  done: number;
+  count: number;
+  current?: string;
+}
+
+export interface LoadedAssets {
+  image(key: string): HTMLImageElement | null;
+  audio(key: string): AudioBuffer | null;
+  url(key: string): string;
+  /** 加载失败的 key。调用方自己决定怎么降级，不要让一张图炸掉整局 */
+  failed: string[];
+}

package/sdk/contract.ts

@@ -0,0 +1,51 @@
+/* 一局的输入与输出。清单本身见 spec.ts。 */
+import type { RngSeed } from './rng.ts';
+
+export interface RoundInput<C> {
+  /** 完整的 config。采样时是 mode 冻结出来的那份 */
+  config: C;
+  /** 最小货币单位的整数（分）。不要传浮点 */
+  bet: number;
+  seed: RngSeed;
+}
+
+export interface RoundResult<O> {
+  /** 这一局的注额，最小货币单位整数。payout 脱离 bet 没有意义，所以带上 */
+  bet: number;
+  /** 玩家拿回的总额，最小货币单位整数。输 = 0。净输赢 = payout - bet */
+  payout: number;
+  multiplier: number;
+  /** 可序列化的结果快照，足以重建整条动画 */
+  outcome: O;
+  /** 默认速度下这局演多久、演完该停多久。平台排自动模式的间隔用 */
+  pacing: { durationMs: number; postDelayMs: number };
+}
+
+/**
+ * 表模型下，服务端返回的一行。
+ *
+ * 平台按权重抽中一行就把它原样发回来——它不执行游戏代码，所以这一行里
+ * 没有 outcome，只有赔付和游戏自己编码的那点字节。
+ */
+export interface RestoreInput<C> {
+  /** 下注那一刻的完整 config（回放时是那一局存下来的）。平台已保证它和 mode 一致 */
+  config: C;
+  /** 注额，最小货币单位整数 */
+  bet: number;
+  /** 相对单注的赔付 ×100。平台已据此记账，客户端不得改写 */
+  payoutCenti: number;
+  /** 演出载荷。游戏自己 encode / decode，平台一个字节都不看。整表没传时为 null */
+  frames: Uint8Array | null;
+  /** 抽中的是哪张表 */
+  mode: string;
+  /** 平台抽行用的种子。只是随行带着，'seed' codec 用的是 frames 里的采样种子，不是它 */
+  seed: RngSeed;
+}
+
+/**
+ * 把服务端抽中的一行还原成可演出的结果。
+ *
+ * 契约：返回的 payout 必须恰好等于 (bet / 100) × payoutCenti。
+ * 对不上就是客户端演出与平台记账分叉，宁可抛错也不要演。
+ */
+export type Restore<C, O> = (input: RestoreInput<C>) => RoundResult<O>;

package/sdk/hash.ts

@@ -0,0 +1,184 @@
+/* 同步的 SHA-256 / HMAC-SHA256。
+
+   为什么不用 crypto.subtle：它是异步的，而 round() 必须是同步纯函数——
+   服务端、客户端、验证页、蒙特卡洛脚本都要能直接调用它拿返回值。
+   为什么不用 node:crypto：浏览器里没有。
+   所以这里是唯一的选择：一份两边都跑得动的纯 JS 实现。 */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+const INIT = [
+  0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19
+] as const;
+
+/** 压缩一个 64 字节块，就地更新 H。w 是复用的调度数组 */
+function compress(H: Uint32Array, dv: DataView, off: number, w: Uint32Array): void {
+  for (let i = 0; i < 16; i++) w[i] = dv.getUint32(off + i * 4);
+  for (let i = 16; i < 64; i++) {
+    const x = w[i - 15], y = w[i - 2];
+    const s0 = rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3);
+    const s1 = rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10);
+    w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+  }
+  let a = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
+  for (let i = 0; i < 64; i++) {
+    const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+    const t1 = (h + S1 + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+    const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+    const t2 = (S0 + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+    h = g; g = f; f = e; e = (d + t1) >>> 0;
+    d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+  }
+  H[0] = (H[0] + a) >>> 0; H[1] = (H[1] + b) >>> 0; H[2] = (H[2] + c) >>> 0; H[3] = (H[3] + d) >>> 0;
+  H[4] = (H[4] + e) >>> 0; H[5] = (H[5] + f) >>> 0; H[6] = (H[6] + g) >>> 0; H[7] = (H[7] + h) >>> 0;
+}
+
+export function sha256(msg: Uint8Array): Uint8Array {
+  const H = new Uint32Array(INIT);
+  const len = msg.length, total = (((len + 9) + 63) & ~63);
+  const buf = new Uint8Array(total);
+  buf.set(msg);
+  buf[len] = 0x80;
+  const dv = new DataView(buf.buffer);
+  const bits = len * 8;
+  dv.setUint32(total - 8, Math.floor(bits / 0x100000000));
+  dv.setUint32(total - 4, bits >>> 0);
+
+  const w = new Uint32Array(64);
+  for (let off = 0; off < total; off += 64) compress(H, dv, off, w);
+
+  const out = new Uint8Array(32), odv = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) odv.setUint32(i * 4, H[i]);
+  return out;
+}
+
+export function hmacSha256(key: Uint8Array, msg: Uint8Array): Uint8Array {
+  const BLOCK = 64;
+  const k = new Uint8Array(BLOCK);
+  k.set(key.length > BLOCK ? sha256(key) : key);
+
+  const inner = new Uint8Array(BLOCK + msg.length);
+  const outer = new Uint8Array(BLOCK + 32);
+  for (let i = 0; i < BLOCK; i++) { inner[i] = k[i] ^ 0x36; outer[i] = k[i] ^ 0x5c; }
+  inner.set(msg, BLOCK);
+  outer.set(sha256(inner), BLOCK);
+  return sha256(outer);
+}
+
+const enc = new TextEncoder();
+export const utf8 = (s: string): Uint8Array => enc.encode(s);
+export const toHex = (b: Uint8Array): string =>
+  Array.from(b, x => x.toString(16).padStart(2, '0')).join('');
+
+/** 公平证里事前公布的服务端种子指纹 */
+export const seedHash = (serverSeed: string): string => toHex(sha256(utf8(serverSeed)));
+
+/**
+ * 可续算的流式 SHA-256。
+ *
+ * 分块上传要跨多个 HTTP 请求对同一串字节算一个哈希，中间状态得存进数据库。
+ * crypto.subtle 做不到这件事——它不暴露内部 H 状态。手写实现在这里是刚需，
+ * 不是历史包袱。
+ */
+export class Sha256 {
+  #H = new Uint32Array(INIT);
+  #buf = new Uint8Array(64);
+  #dv = new DataView(this.#buf.buffer);
+  #w = new Uint32Array(64);
+  #total = 0;
+
+  /** 已吃进的总字节数 */
+  get byteLength(): number { return this.#total; }
+
+  update(bytes: Uint8Array): this {
+    let i = 0;
+    const pending = this.#total % 64;
+
+    if (pending > 0) {
+      const need = 64 - pending;
+      if (bytes.length < need) {
+        this.#buf.set(bytes, pending);
+        this.#total += bytes.length;
+        return this;
+      }
+      this.#buf.set(bytes.subarray(0, need), pending);
+      compress(this.#H, this.#dv, 0, this.#w);
+      i = need;
+    }
+
+    // 对齐的整块直接在入参上压缩，不拷贝
+    const aligned = bytes.byteOffset % 4 === 0;
+    const view = aligned
+      ? new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+      : null;
+    for (; i + 64 <= bytes.length; i += 64) {
+      if (view) {
+        compress(this.#H, view, i, this.#w);
+      } else {
+        this.#buf.set(bytes.subarray(i, i + 64));
+        compress(this.#H, this.#dv, 0, this.#w);
+      }
+    }
+
+    if (i < bytes.length) this.#buf.set(bytes.subarray(i), 0);
+    this.#total += bytes.length;
+    return this;
+  }
+
+  /** 不终结：算完仍可继续 update，所以可以中途取快照 */
+  digest(): Uint8Array {
+    const H = new Uint32Array(this.#H);
+    const pending = this.#total % 64;
+    const tailLen = pending + 9 <= 64 ? 64 : 128;
+    const tail = new Uint8Array(tailLen);
+    tail.set(this.#buf.subarray(0, pending));
+    tail[pending] = 0x80;
+    const dv = new DataView(tail.buffer);
+    const bits = this.#total * 8;
+    dv.setUint32(tailLen - 8, Math.floor(bits / 0x100000000));
+    dv.setUint32(tailLen - 4, bits >>> 0);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < tailLen; off += 64) compress(H, dv, off, w);
+
+    const out = new Uint8Array(32), odv = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++) odv.setUint32(i * 4, H[i]);
+    return out;
+  }
+
+  hex(): string { return toHex(this.digest()); }
+
+  /** 十六进制串：H(64) + 总字节数(16) + 未满一块的余料。余料长度 = total % 64，自描述 */
+  exportState(): string {
+    const h = Array.from(this.#H, (x) => x.toString(16).padStart(8, '0')).join('');
+    const total = this.#total.toString(16).padStart(16, '0');
+    const pending = this.#total % 64;
+    return h + total + toHex(this.#buf.subarray(0, pending));
+  }
+
+  static importState(state: string): Sha256 {
+    if (state.length < 80 || !/^[0-9a-f]*$/.test(state)) {
+      throw new RangeError('Sha256 状态串非法');
+    }
+    const s = new Sha256();
+    for (let i = 0; i < 8; i++) s.#H[i] = parseInt(state.slice(i * 8, i * 8 + 8), 16) >>> 0;
+    s.#total = Number.parseInt(state.slice(64, 80), 16);
+    if (!Number.isSafeInteger(s.#total)) throw new RangeError('Sha256 状态的字节数越界');
+    const pending = s.#total % 64;
+    if (state.length !== 80 + pending * 2) throw new RangeError('Sha256 状态串长度与字节数不符');
+    for (let i = 0; i < pending; i++) {
+      s.#buf[i] = parseInt(state.slice(80 + i * 2, 82 + i * 2), 16);
+    }
+    return s;
+  }
+}

package/sdk/host.ts

@@ -0,0 +1,96 @@
+/* 平台注入给游戏的东西，以及游戏交还给平台的把手。
+
+   方向是单向的：平台 → 游戏全是 Readable，游戏想改值要走 requestConfig 申请，
+   平台有否决权。不做双向读写的共享 store，原因有三条：
+     1. 夹取逻辑会重复实现，或者产生回声循环（游戏写回 clamp 值 → 平台更新 → 再推回游戏）
+     2. 局中、自动模式中、余额不足、服务端已锁参数——这些只有平台知道
+     3. 跨框架的双向绑定在 React StrictMode 下会出微妙的 bug */
+import type { Readable } from './store.ts';
+import type { RoundResult } from './contract.ts';
+
+/** 不影响结果的表现参数。每个游戏都有，所以是固定字段，不进 schema */
+export interface ViewSettings {
+  sound: boolean;
+  volume: number;
+  turbo: boolean;
+  reducedMotion: boolean;
+  /** 造型/皮肤。只是贴图，不参与结果计算 */
+  skin: string;
+  locale: string;
+  /**
+   * 平台正在跑自动模式。自动循环归平台（它才知道余额够不够、还剩几局），
+   * 但游戏要据此禁用画布内的设置控件——否则玩家能在自动跑的中途改图纸。
+   * 配合 schema 的 lock: 'inRoundOrAuto' 使用。
+   */
+  autoActive: boolean;
+}
+
+export interface WalletView {
+  balance: number;
+  currency: string;
+  /** 最小货币单位到显示单位的位数，人民币/美元是 2 */
+  decimals: number;
+}
+
+export interface Host<C> {
+  /** 影响结果的参数。游戏只读 */
+  config: Readable<C>;
+  view: Readable<ViewSettings>;
+  /** 只读展示。游戏不碰钱 */
+  wallet: Readable<WalletView>;
+  jackpot: Readable<number | null>;
+  /** 由平台统一创建和解锁（iOS 要用户手势），游戏不要自己 new AudioContext */
+  audio: { context(): AudioContext | null; volume(): number };
+  locale: string;
+  /**
+   * 画布内控件的写入申请。平台校验后写回 config，游戏订阅到新值再重渲染。
+   * 只有声明了 ui: 'stage' 字段的游戏才需要它。
+   */
+  requestConfig?(patch: Partial<C>): void;
+  emit(e: GameEvent): void;
+  log(level: 'debug' | 'info' | 'warn' | 'error', msg: string, data?: unknown): void;
+}
+
+export interface GameStatus {
+  phase: 'loading' | 'idle' | 'playing' | 'settling' | 'error';
+  /** 正在演出，平台的下注按钮该禁用 */
+  busy: boolean;
+  canBet: boolean;
+  canSkip: boolean;
+  /** 现在能不能改影响结果的参数。平台据此把设置控件变灰——
+      和游戏画布内的控件用的是同一个判断，两边不会打架 */
+  canEditConfig: boolean;
+  /** 资源加载进度 0..1，phase === 'loading' 时有意义 */
+  progress?: number;
+  lastPayout?: number;
+  /** validate() 的结果，平台显示在设置面板上 */
+  issues?: import('./schema.ts').ConfigIssue[];
+}
+
+export interface PresentOptions {
+  /** 播放倍率。1 = 正常，Infinity = 直接看结果。只影响演出，不影响结果 */
+  rate?: number;
+  silent?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface GameInstance<O> {
+  status: Readable<GameStatus>;
+  /** 演一局已经算好的结果。resolve 于演出结束（含结算特效）。不碰钱 */
+  present(r: RoundResult<O>, o?: PresentOptions): Promise<void>;
+  /** 只演不结账：回看别人的大奖用。不发 present:end */
+  preview(r: RoundResult<O>, o?: PresentOptions): Promise<void>;
+  /** 快进到结果 */
+  skip(): void;
+  reset(): void;
+  resize(): void;
+  destroy(): void;
+}
+
+export type GameEvent =
+  | { type: 'ready' }
+  | { type: 'present:start' }
+  | { type: 'present:end'; payout: number }
+  | { type: 'milestone'; kind: 'bigwin' | 'jackpot' | 'nearmiss'; tier?: number }
+  | { type: 'config:request'; patch: Record<string, unknown> }
+  | { type: 'error'; code: string; message: string };

package/sdk/index.ts

@@ -0,0 +1,9 @@
+export * from './contract.ts';
+export * from './spec.ts';
+export * from './host.ts';
+export * from './rng.ts';
+export * from './schema.ts';
+export * from './store.ts';
+export { sha256, hmacSha256, utf8, toHex, Sha256 } from './hash.ts';
+export * from './sample.ts';
+export * from './stage.ts';

package/sdk/rng.ts

@@ -0,0 +1,109 @@
+/* 确定性随机数。
+
+   平台给一个种子三元组，游戏内展开成一条流。同一个种子 + 同一份代码
+   必然得到同一个结果——这是「服务端算钱、客户端演出」能对上账的前提。
+
+   算法：HMAC-SHA256(server, `${client}:${nonce}:${tag}`) 取前 128 位播种 xoshiro128**。
+   不采用「每个字都由 HMAC 直出」的做法：一局可能要抽成百上千个字（洗一副牌就是 51 次），
+   带重洗分支的游戏更多。播种一次再用快速 PRNG 展开，同样完全确定、
+   同样可验证（验证就是跑这份公开算法），成本却可以忽略。
+
+   全流程只有 uint32 的位运算和 Math.imul，不碰浮点，任何 JS 引擎结果一致。 */
+import { hmacSha256, utf8 } from './hash.ts';
+
+export interface RngSeed {
+  /** 服务端种子。下注前平台只公布它的 sha256，局后 reveal */
+  server: string;
+  /** 客户端种子，玩家可改 */
+  client: string;
+  /** 该 client 种子下的局序号，单调递增 */
+  nonce: number;
+}
+
+export interface Rng {
+  u32(): number;
+  /** 无偏整数 [0, n)。用拒绝采样，不要自己写 % n */
+  below(n: number): number;
+  /** [0, 1) */
+  float(): number;
+  /** 洗牌，返回新数组，不改入参 */
+  shuffle<T>(a: readonly T[]): T[];
+  /** 已消耗的 u32 个数（含被拒绝采样丢掉的）。写进公平证供审计对账 */
+  readonly draws: number;
+  /**
+   * 派生一条域分隔的独立子流，不动当前游标。
+   *
+   * 两个用途：一是把演出用的随机（台词、粒子）与结果隔离，这样加一句新台词
+   * 不会改变牌序；二是把子系统分开，将来改发牌逻辑不会让金牌位置跟着漂。
+   */
+  fork(tag: string): Rng;
+}
+
+const rotl = (x: number, k: number): number => (x << k) | (x >>> (32 - k));
+
+class Xoshiro implements Rng {
+  #s0: number; #s1: number; #s2: number; #s3: number;
+  #draws = 0;
+  #seed: RngSeed;
+  #tag: string;
+
+  constructor(seed: RngSeed, tag: string) {
+    this.#seed = seed;
+    this.#tag = tag;
+    const h = hmacSha256(utf8(seed.server), utf8(`${seed.client}:${seed.nonce}:${tag}`));
+    const dv = new DataView(h.buffer, h.byteOffset, h.byteLength);
+    this.#s0 = dv.getUint32(0); this.#s1 = dv.getUint32(4);
+    this.#s2 = dv.getUint32(8); this.#s3 = dv.getUint32(12);
+    // 全零状态会让 xoshiro 永远输出 0。HMAC 撞出全零的概率是 2^-128，但便宜
+    if (!(this.#s0 | this.#s1 | this.#s2 | this.#s3)) this.#s0 = 1;
+  }
+
+  get draws(): number { return this.#draws; }
+
+  u32(): number {
+    const result = Math.imul(rotl(Math.imul(this.#s1, 5), 7), 9) >>> 0;
+    const t = this.#s1 << 9;
+    this.#s2 ^= this.#s0;
+    this.#s3 ^= this.#s1;
+    this.#s1 ^= this.#s2;
+    this.#s0 ^= this.#s3;
+    this.#s2 ^= t;
+    this.#s3 = rotl(this.#s3, 11);
+    this.#draws++;
+    return result;
+  }
+
+  below(n: number): number {
+    if (!Number.isInteger(n) || n <= 0) throw new RangeError(`below(${n})：要正整数`);
+    if (n === 1) return 0;
+    /* 4294967296 不是 n 的整数倍时，直接取模会让小余数偏多。
+       把超出最大整数倍的那一段丢掉再取模，分布才是均匀的 */
+    const lim = Math.floor(0x100000000 / n) * n;
+    let x: number;
+    do { x = this.u32(); } while (x >= lim);
+    return x % n;
+  }
+
+  float(): number { return this.u32() / 0x100000000; }
+
+  shuffle<T>(a: readonly T[]): T[] {
+    const out = a.slice();
+    for (let i = out.length - 1; i > 0; i--) {
+      const j = this.below(i + 1);
+      [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+  }
+
+  fork(tag: string): Rng {
+    return new Xoshiro(this.#seed, this.#tag ? `${this.#tag}/${tag}` : tag);
+  }
+}
+
+export const createRng = (seed: RngSeed, tag = ''): Rng => new Xoshiro(seed, tag);
+
+/** 平台侧用：生成一个新的服务端种子。这是全流程唯一的真随机来源 */
+export const randomSeed = (bytes = 32): string =>
+  Array.from(crypto.getRandomValues(new Uint8Array(bytes)), b => b.toString(16).padStart(2, '0')).join('');
+
+export { seedHash } from './hash.ts';