@uzuhq/code-sdk 0.7.6 → 0.8.0

package/dist/dev-hooks-D6CbhPDP.d.ts

@@ -0,0 +1,715 @@
+//#region src/dev-state-patch.d.ts
+/**
+ * @docs
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
+ *
+ * `__uzu_dev.mergeRawState` / `__uzu_dev.patchRawState` の中身。
+ * scenario state を「object 階層の部分更新 (RFC 7396)」と「array 要素単体の書換
+ * 含む path-based ops (RFC 6902)」で書き換えるための utility。
+ */
+/**
+ * RFC 7396 風 Merge Patch。
+ *
+ * RFC 7396 strict との差分:
+ * - `null` は target 側の **削除ではなく** null をセットする (`timerEndsAt: null`
+ *   のような nullable field を狙い撃ちするユースケースを優先)
+ * - 値を削除したいときは {@link JsonPatchOp} の `remove` を使う
+ *
+ * Generic は使い手側の type を残すための shape ヒントで、ランタイム上は
+ * `Record<string, unknown>` と等価。
+ */
+type JsonMergePatch<S = unknown> = Partial<{ [K in keyof S]: S[K] extends unknown[] ? S[K] : S[K] extends object ? JsonMergePatch<S[K]> : S[K] | null; }> & Record<string, unknown>;
+/**
+ * RFC 6902 JSON Patch operation。
+ *
+ * - `add` / `replace` / `test`: `value` 必須
+ * - `remove`: `value` / `from` 不要
+ * - `move` / `copy`: `from` 必須 (JSON Pointer)
+ * - `path` は JSON Pointer (例: `/board/1/4`、root は空文字)
+ */
+type JsonPatchOp = {
+  op: 'add';
+  path: string;
+  value: unknown;
+} | {
+  op: 'remove';
+  path: string;
+} | {
+  op: 'replace';
+  path: string;
+  value: unknown;
+} | {
+  op: 'move';
+  path: string;
+  from: string;
+} | {
+  op: 'copy';
+  path: string;
+  from: string;
+} | {
+  op: 'test';
+  path: string;
+  value: unknown;
+};
+/**
+ * RFC 7396 (Merge Patch) を target に in-place 適用する。
+ *
+ * 規則:
+ * - `undefined` は no-op (key 自体を patch から落としたのと同じ)
+ * - `null` は **null をセット** (RFC 7396 strict と異なる、deletion はしない)
+ * - patch が object かつ target も object → 再帰 merge
+ * - patch が array → atomic replace (要素単位 merge なし、RFC 7396 spec 通り)
+ * - patch が primitive → overwrite
+ * - **target が array で patch が non-array object** → throw (silent な
+ *   `[..., ...]` → `{ "0": ..., "1": ... }` 化を防ぐ)
+ *
+ * 型 mismatch (例: object → primitive) は overwrite で許可する。
+ */
+declare function applyJsonMergePatch(target: Record<string, unknown>, patch: JsonMergePatch): void;
+/**
+ * RFC 6902 (JSON Patch) operations を target に in-place 適用する。
+ *
+ * 1 op でも失敗したら **その時点で throw** する (RFC 6902 spec: operations は
+ * sequentially evaluate、失敗時の rollback は規定なし)。caller が atomic に
+ * したいなら state を事前に snapshot しておく。
+ *
+ * root pointer (`''`) は本実装では `add` / `replace` のみ許可し、
+ * doc のフィールドを丸ごと差し替える形で動く (= 結局 `setRawState` で十分な
+ * ケースなので、わざわざ `patchRawState` で使うことはほぼない)。
+ */
+declare function applyJsonPatch(target: Record<string, unknown>, ops: JsonPatchOp[]): void;
+//#endregion
+//#region ../engine-core/src/game-time.d.ts
+/**
+ * @docs
+ * - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
+ *
+ * ゲーム内時刻。ゲーム開始からの ms で、停止中は進まない。**Unix epoch ではない。**
+ *
+ * 実行時はただの number。brand はコンパイル時だけの区別なので、state は素の JSON の
+ * まま保たれる (structuredClone / json-patch / JSON.stringify がそのまま通る)。
+ * 値を作れるのは `ctx.after` / `plus` だけになるので、`Date.now()` を混ぜると型で落ちる。
+ *
+ * 型が効くのは TypeScript を書いているシナリオだけだが、JS のシナリオでも epoch が
+ * 違うぶんは残る (`Date.now()` を混ぜれば締切が 56,000 日後になって初回で気付く)。
+ */
+declare const gameTimeBrand: unique symbol;
+/** ゲーム内時刻 (ゲーム開始からの ms)。停止中は進まない。 */
+type GameTime = number & {
+  readonly [gameTimeBrand]: 'GameTime';
+};
+/** 長さ (ms)。差や間隔はこちら。 */
+type Duration = number;
+/**
+ * `GameTime` に長さを足す。
+ *
+ * 算術をすると brand が落ちる (`number + number = number`) ので、`GameTime` を
+ * 作り直す道はこの関数と `ctx.after` に限られる。
+ */
+declare const plus: (t: GameTime, d: Duration) => GameTime;
+/** 2 つの `GameTime` の差 (ms)。 */
+declare const minus: (a: GameTime, b: GameTime) => Duration;
+//#endregion
+//#region ../engine-core/src/types.d.ts
+/**
+ * roster に載る席。
+ *
+ * roster は配役を受け取る参加者だけで構成される。観測者 (GM 席・観戦席) は roster に
+ * 載らないまま接続してくるので、シナリオは「roster に居ない = 観測者」で判別する。
+ * 席種別は roster エントリではなく自分の `SeatKind` として渡る。
+ */
+interface Seat {
+  id: string;
+  nickname: string;
+  iconUrl: string;
+  /** ホスト（mobile / emulator）から渡される、選択済みキャラクターの ID。未選択時は undefined。 */
+  characterId?: string;
+}
+type Emit = (eventName: string, data?: Record<string, unknown>) => void;
+/** dev harness で観測される 1 件の emit。`data` は `emit(name)` 省略時に空 object になる。 */
+interface ServerEvent {
+  name: string;
+  data: Record<string, unknown>;
+}
+interface SeededRandom {
+  float(): number;
+  int(max: number): number;
+  pick<T>(array: T[]): T;
+  shuffle<T>(array: T[]): T[];
+}
+/**
+ * 素の action handler の実行文脈。空なのは意図的。
+ *
+ * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
+ * 再現できない値 (tick / 乱数) をここで配ると、サーバー・ソロ・dev では本物が入るのに
+ * オンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
+ * そういう値が要る処理は `serverActions` 側に書く。
+ */
+interface ActionContext {
+  /**
+   * 現在のゲーム内時刻。先読みではクロックオフセットからの推定値。
+   *
+   * 推定なのでサーバーとは数十 ms ずれる。時刻での分岐に使うと境界で判定が割れるので、
+   * 分岐は `update()` / `deadlines` (サーバー専用) へ寄せる。
+   *
+   * 同じ action を再適用しても値は変わらない (初回予測時の値を使い回す)。
+   */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。締切を state へ置くときに使う。 */
+  after(d: Duration): GameTime;
+  emit: Emit;
+}
+/** `deadlines` handler の実行文脈。サーバーでしか走らないので tick 以外を渡せる。 */
+interface DeadlineContext {
+  /** 発火時点のゲーム内時刻。サーバー専用なので常に正確。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。次の締切を state へ置き直すときに使う。 */
+  after(d: Duration): GameTime;
+  random: SeededRandom;
+  emit: Emit;
+}
+/** `deadlines` handler の引数。 */
+interface DeadlineArgs<S> {
+  state: S;
+  ctx: DeadlineContext;
+}
+/**
+ * サーバー権威の締切。
+ *
+ * 「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが `at` の最も早いものに
+ * 合わせて自分で起き、過ぎた締切の `handler` を呼ぶ。`tickRate` で毎秒ポーリングする
+ * 必要が無くなり、その間 Durable Object は hibernate できる。
+ *
+ * 締切は state から導出するので、予約を張り替える処理を書かなくてよい。action が
+ * throw して state が巻き戻れば、締切も一緒に巻き戻る。
+ */
+interface Deadline<S> {
+  /**
+   * 締切のゲーム内時刻。締切が無いときは null / undefined。
+   *
+   * `state.timer?.endsAt` のような optional chain の結果をそのまま返せるよう
+   * undefined も受ける。数値以外は「締切なし」として同じに扱う。
+   *
+   * 戻り値が `GameTime` なのは強制点。`Date.now() + 尺` も素の number も返せないので、
+   * 値を得る道が `ctx.after()` / `plus()` に限られ、state の時刻フィールドを
+   * `GameTime` で持つ動機が自動的に生まれる。
+   *
+   * state が変わるたびに呼ばれるので、state だけから決まる軽い純関数にすること。
+   * ここで実時刻や乱数を読むと、呼ばれるたびに答えが変わって予約が暴れる。
+   */
+  at(args: {
+    state: S;
+  }): GameTime | null | undefined;
+  /**
+   * `at` の時刻を過ぎたときにサーバーで呼ばれる。
+   *
+   * 発火は at-least-once だが、SDK が発火直前に `at` を評価し直して過ぎているものだけを
+   * 呼ぶので、handler 側で二重発火を弾く必要は無い。
+   */
+  handler(args: DeadlineArgs<S>): void;
+}
+/** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
+interface ServerActionContext {
+  tick: number;
+  random: SeededRandom;
+  /** 現在のゲーム内時刻。同じ dispatch の `actions` に渡る `ctx.time` と同一値。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。 */
+  after(d: Duration): GameTime;
+  emit: Emit;
+}
+/** @deprecated `ServerActionContext` を使う。 */
+type ServerOnlyActionContext = ServerActionContext;
+/**
+ * action handler の引数。
+ *
+ * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
+ * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
+ */
+interface ActionArgs<S, P = any> {
+  state: S;
+  payload: P;
+  playerId: string;
+  ctx: ActionContext;
+}
+/**
+ * `P` は既定が `any` なので、 注釈のない handler はそのまま動く。 payload の形を
+ * 書いた handler だけが検査され、 送信側もその型で縛られる。 全部に注釈しないと
+ * 恩恵が無い、 という移行にならないようにするための既定値。
+ */
+type ActionHandler<S, P = any> = (args: ActionArgs<S, P>) => void;
+/** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
+interface ServerActionArgs<S, P = any> {
+  state: S;
+  payload: P;
+  playerId: string;
+  ctx: ServerActionContext;
+}
+type ServerActionHandler<S, P = any> = (args: ServerActionArgs<S, P>) => Promise<void> | void;
+/** @deprecated `ServerActionHandler` を使う。 */
+type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
+/**
+ * @deprecated `serverActions` フィールドに直接書く。
+ * `serverOnly()` で wrap された handler。`__serverOnly` brand で識別する。
+ */
+type ServerOnlyAction<S> = ServerActionHandler<S> & {
+  readonly __serverOnly: true;
+};
+/** `update()` の ctx。サーバーでしか走らないので tick / random / playerInputs を持つ。 */
+interface UpdateContext {
+  random: SeededRandom;
+  tick: number;
+  /** 現在のゲーム内時刻。update はサーバーでしか走らないので常に正確。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。 */
+  after(d: Duration): GameTime;
+  emit: Emit;
+  playerInputs: Record<string, Record<string, any>>;
+}
+interface UpdateArgs<S> {
+  state: S;
+  ctx: UpdateContext;
+}
+/**
+ * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
+ *
+ * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
+ */
+interface SetupContext {
+  random: SeededRandom;
+  /** ゲーム内時刻。setup は時計の起点なので必ず `0`。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。setup では `d` そのものになる。 */
+  after(d: Duration): GameTime;
+}
+/** `setup()` の引数。 */
+interface SetupArgs {
+  /** 配役を受け取る参加者。観測者は含まれない。 */
+  players: Seat[];
+  ctx: SetupContext;
+}
+/**
+ * `actions` の形だけを見る緩い制約。
+ *
+ * `Record<string, ActionHandler<S>>` (payload: any) を制約に使うと、 推論時に
+ * handler 型がそちらへ広げられ payload の型が取り出せなくなる。 payload を
+ * `any` のままにしてキーと引数の形だけ縛る。
+ */
+type ActionMap<S> = Record<string, (args: ActionArgs<S, any>) => void>;
+/** `serverActions` 用。 ActionMap と同じ理由で payload は any のままにする。 */
+type ServerActionMap<S> = Record<string, (args: ServerActionArgs<S, any>) => Promise<void> | void>;
+interface GameLogic<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> {
+  setup(args: SetupArgs): S;
+  /**
+   * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
+   *
+   * `serverActions` に同名のキーを置くと、同じ action の「サーバーだけで走る続き」に
+   * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
+   * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
+   */
+  actions: A;
+  /**
+   * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
+   * 再現できない処理をここに書く。async 可。
+   *
+   * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
+   * (旧 `serverOnly()` 相当) になる。
+   */
+  serverActions?: SA;
+  update(args: UpdateArgs<S>): void;
+  /**
+   * state 由来の締切。サーバーが `at` の時刻に自分で起きて `handler` を呼ぶ。
+   *
+   * 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
+   * ポーリング中は Durable Object が hibernate できない。
+   */
+  deadlines?: Record<string, Deadline<S>>;
+  tickRate?: number;
+}
+/** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
+declare const SERVER_TIME: "__SERVER_TIME__";
+/** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */
+declare const DEFAULT_ICON_URLS: readonly ["https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/4d0da24d-bcf2-4f7b-d1a0-f1bb8c747300/original", "https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/8c75fccb-41d6-429d-e943-06c728a72a00/original", "https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/43f45d11-da38-4d6e-637d-3df78e583500/original"];
+//#endregion
+//#region ../engine-core/src/json-patch.d.ts
+/**
+ * @docs
+ * - SyncRoom仕様: docs/docs/uzu_code/sync-room.md
+ *
+ * state 差分同期用の JSON Patch。RFC 6902 の全 op は実装せず、
+ * `compare` が生成する replace / add / remove だけを扱う。
+ */
+interface Operation {
+  op: 'replace' | 'add' | 'remove';
+  path: string;
+  value?: unknown;
+}
+//#endregion
+//#region src/types.d.ts
+/** @deprecated 旧フラット形式。新コードでは BridgeMessage を使用 */
+type PlayScreenMessage = {
+  type: string;
+  [key: string]: unknown;
+};
+/** ブリッジメッセージのチャンネル */
+type BridgeChannel = 'sdk' | 'game';
+/** ワイヤーフォーマット: { channel, type, payload, playerId? } */
+interface BridgeMessage {
+  channel: BridgeChannel;
+  type: string;
+  payload: Record<string, unknown>;
+  /**
+   * 送信元プレイヤーの ID（ゲーム → ホスト方向のみ）。
+   * Web エミュレータでは複数プレイヤーの iframe が同一オリジンになり
+   * postMessage の送信元 iframe を区別できないため、ホストはこの値で
+   * 自分宛メッセージかを判定する。
+   *
+   * Flutter ホスト（QueryParamsBuilder）と dev ハーネスは URL に必ず
+   * playerId を付与するため、ゲーム → ホスト方向では常に存在する。
+   * optional なのはホスト → ゲーム方向のメッセージが持たないため
+   * （受信側は playerId 無し = 旧 SDK ビルドとして扱う）。
+   */
+  playerId?: string;
+}
+/**
+ * 自分の席種別。ホストが iframe URL の `?seatKind=` で伝える。
+ *
+ * roster に載るのは `player` だけ。観測者 (`spectator` / `admin`) は roster 外の接続として
+ * 開くので、「player か観測者か」は `state.players` の空振りで分かる。一方 **`spectator` と
+ * `admin` の区別は state から導けない**ため、この値で分ける。seatId の命名規約
+ * (`admin_0` 等) をシナリオに見せると、規約が変わった瞬間に静かに壊れる。
+ *
+ * 自己申告なので権限の根拠にはならない。表示の分岐にだけ使うこと。
+ */
+type SeatKind = 'player' | 'spectator' | 'admin';
+/** プレイヤーごとのリアルタイム状態 */
+interface PlayerVoiceState {
+  /** 音声状態。音声通話に未接続の場合は null */
+  audioStatus: 'speaking' | 'listening' | 'muted' | 'unstable' | null;
+}
+/** @deprecated 旧形式。新コードでは onPlayersChanged() と PlayerVoiceState を使用 */
+interface PlayersChangedMessage {
+  players: Record<string, PlayerVoiceState>;
+}
+/**
+ * events handler。
+ *
+ * `emit(name, data)` の `data` をそのまま受け取る。先読み中か確定後かは渡さない
+ * (どちらで呼ばれても同じ処理をする前提。 `predict` で宣言済みなので分岐の必要がない)。
+ */
+type EventHandler = (data: Record<string, unknown>) => void;
+/**
+ * events の購読宣言。
+ *
+ * 先読みは外れることがあり、実行してしまったものは取り消せない。取り消せない副作用
+ * (analytics / 実績解除 / 長い演出) は必ず `predict: false` にすること。
+ */
+interface EventSubscription {
+  /** 先読み時点で実行してよいか。宣言必須。 */
+  predict: boolean;
+  handler: EventHandler;
+}
+/** action 名から payload 型を引く表。 注釈のない handler は `any` になる。 */
+type PayloadMap<A> = { [K in keyof A]: A[K] extends ((args: infer G) => any) ? G extends {
+  payload: infer P;
+} ? P : never : never; };
+/**
+ * `inputs` が受け取る送信関数。 action 名と payload の両方が型で縛られる。
+ *
+ * payload を一律 optional にすると、 形が必須の action でも省略が通ってしまう。
+ * payload 型が undefined を含むとき (= 注釈なしの any や明示的に optional) だけ
+ * 省略できるようにする。
+ */
+type SendAction<A> = <K extends keyof A & string>(...args: undefined extends PayloadMap<A>[K] ? [type: K, payload?: PayloadMap<A>[K]] : [type: K, payload: PayloadMap<A>[K]]) => void;
+interface GameConfig<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> extends ConnectionCallbacks {
+  logic: GameLogic<S, A, SA>;
+  /**
+   * `mySeatKind` は自分の席種別。roster に自分が居ない (= 観測者) ときに、GM ビューと
+   * 観戦ビューを出し分けるために使う。他プレイヤーの席種別は渡らない。
+   */
+  onState: (state: S, myPlayerId: string, mySeatKind: SeatKind) => void;
+  inputs: (sendAction: SendAction<A & SA>) => void;
+  /**
+   * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
+   *
+   * 同じ出来事が二重に実行されないよう、SDK は「先読みで実行した記録」を持ち、
+   * サーバーから同一の event (name と data が完全一致) が届いたら実行を抑止する。
+   * したがって `data` には**クライアントとサーバーで必ず同じ値になるもの**だけを
+   * 入れること。`ctx.now` や乱数 ID を混ぜると一致せず二重実行になる。
+   */
+  events?: Record<string, EventSubscription>;
+  playerCount: number;
+  /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
+  orientation?: 'portrait' | 'landscape';
+  /**
+   * Dev harness で各 iframe inner viewport 短辺の下限 (CSS px)。
+   * default 360。狭い viewport では親 frame に `body { zoom: N }` を当てて
+   * iframe 内部の `window.innerWidth/Height` を保証する。
+   */
+  devMinIframeShortEdge?: number;
+}
+type PatchFn = (ops: Operation[]) => void;
+type SetFn = (path: string, value: unknown) => void;
+interface SyncConfig<S = any> extends ConnectionCallbacks {
+  initialState: (players: Seat[]) => S;
+  onState: (state: S, myPlayerId: string, serverTime: number) => void;
+  inputs: (patch: PatchFn, set: SetFn) => void;
+  events?: Record<string, (data: Record<string, unknown>) => void>;
+  playerCount: number;
+  /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
+  orientation?: 'portrait' | 'landscape';
+  /**
+   * Dev harness で各 iframe inner viewport 短辺の下限 (CSS px)。
+   * default 360。狭い viewport では親 frame に `body { zoom: N }` を当てて
+   * iframe 内部の `window.innerWidth/Height` を保証する。
+   */
+  devMinIframeShortEdge?: number;
+}
+type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+interface ConnectionCallbacks {
+  /** WebSocket 接続状態が変化した時に呼ばれる */
+  onConnectionStateChange?: (state: ConnectionState) => void;
+  /** サーバーで patch 適用が失敗した時に呼ばれる (sync モード専用) */
+  onPatchFailed?: (reason: string) => void;
+}
+//#endregion
+//#region src/host-globals.d.ts
+declare global {
+  interface Window {
+    __ps?: {
+      onMessage: (msg: BridgeMessage) => void;
+    };
+    FlutterHost?: {
+      postMessage: (message: string) => void;
+    };
+  }
+}
+//#endregion
+//#region src/dev-prediction-traps.d.ts
+interface PredictionWarning {
+  /** 呼び出した action 名。描画経路では `'(render)'`。 */
+  action: string;
+  /** 呼ばれた API 名 (`'Date.now()'` など) */
+  api: string;
+}
+/** 検出済みの警告一覧。`__uzu_dev.getPredictionWarnings()` から E2E で assert する用。 */
+declare const getPredictionWarnings: () => readonly PredictionWarning[];
+//#endregion
+//#region src/dev-hooks.d.ts
+interface UzuDevHooks<S = unknown> {
+  /** 現在の per-player 視点 snapshot (onState コールバックの最新値)。未初期化なら null。 */
+  getSnapshot(): unknown;
+  /** 生 server-side state (dev/local mode のみ。online ServerAction では null)。 */
+  getRawState(): S | null;
+  playerId(): string | null;
+  /**
+   * 親 frame で virtual server を実体化した時の seed。
+   * 親 frame の `runDevHarness({ server })` 経由でしか attach されず、子 iframe の
+   * dev hooks 側では undefined。bug report 用に `?__dev_seed=<value>` として
+   * 貼り付けやすい uint32 を返す。
+   */
+  getSeed?(): number;
+  /**
+   * 素の action handler が先読み実行中に実時刻 / 乱数を読んだ記録。
+   *
+   * 先読みはサーバーと同じ結果を再現できることが前提なので、ここに何か入っていたら
+   * そのシナリオはオンラインでだけ予測がズレる。E2E で `[]` を assert すると回帰を防げる。
+   */
+  getPredictionWarnings(): readonly PredictionWarning[];
+  /**
+   * Server-side で action を直接 dispatch する。
+   *
+   * **run devHarness の親 frame のみ** で attach される。それ以外 (runLocal /
+   * sync / online) では `undefined`。
+   * 非 parent モードで action を投げたい時は scenario 側の bridge
+   * (`window.__uzu.sendAction`) や実 UI 操作を使う。
+   *
+   * `args.as` は **必須**。server-side dispatch の `from` をこの値で指定する
+   * (バリデーションはしないので、未登録 ID で投げて action handler に弾かせる
+   * 運用も可)。turn-based の E2E (将棋・人狼・カードゲーム) で「先手 → 後手」
+   * を 1 frame から打ち分けたい時に使う。
+   */
+  send?(args: {
+    as: string;
+    type: string;
+    payload?: Record<string, unknown>;
+  }): Promise<void>;
+  /**
+   * 生 state を **全置換** する。state owner の frame (= dev/local) のみ。
+   *
+   * `setup` 後の任意の構造を流し込めるので、`getRawState()` の dump を読み込んで
+   * バグ再現する用途や、scenario の途中 state を JSON で復元する用途に使う。
+   * 部分更新は {@link mergeRawState} を、array 要素単体の書換は
+   * {@link patchRawState} を使うこと。
+   */
+  setRawState?(state: S): Promise<void>;
+  /**
+   * RFC 7396 風 JSON Merge Patch で生 state を部分更新する (dev/local のみ)。
+   *
+   * - object 階層は recursive merge
+   * - **array field は atomic replace のみ** (要素単位の merge 不可、RFC 7396 仕様)
+   * - `undefined` は no-op、`null` は明示セット (RFC 7396 strict と異なる)
+   * - array 内の cell 単体を書き換えたい場合は {@link patchRawState} を使う
+   *
+   * array が pure object に化ける silent な破壊を防ぐため、`array に
+   * non-array object patch を当てる`と **throw** する。
+   */
+  mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
+  /**
+   * RFC 6902 JSON Patch (path-based ops) で生 state を更新する (dev/local のみ)。
+   *
+   * - JSON Pointer (`/board/1/4`) で array index 単体の書換が可能
+   * - サポートする op: `add` / `remove` / `replace` / `move` / `copy` / `test`
+   * - 1 op でも失敗するとその場で throw する (atomic ではない)
+   *
+   * 局面の部分更新 (将棋の一手・盤面の cell 単体書換など) に使う。
+   */
+  patchRawState?(ops: JsonPatchOp[]): Promise<void>;
+  /**
+   * snapshot 更新を event-driven に listen する。返り値は unsubscribe 関数。
+   *
+   * `waitForSnapshot` が「特定条件まで待つ」のに対し、こちらは「state 変化を全部
+   * 取って trace test を書く」「deterministic record を作る」「sequence assert」
+   * のような用途で使う canonical な listener。
+   *
+   * cb には authoritative state の生参照 (run devHarness 親では `getRawState()` と
+   * 同一) が渡るので mutate しない。
+   */
+  subscribeSnapshot(cb: (snapshot: unknown) => void): () => void;
+  /** snapshot が predicate を満たすまで待つ。default 10 秒 timeout。 */
+  waitForSnapshot(predicate: (snapshot: unknown) => boolean, options?: {
+    timeoutMs?: number;
+  }): Promise<unknown>;
+  /**
+   * action handler / `logic.update` の `emit` を listen する。callback には 1 回の
+   * dispatch / tick 内で発火した event を batch でまとめて渡す。**run devHarness 親
+   * frame のみ** で attach され、それ以外 (runLocal ソロ /
+   * sync / online) では `undefined`。
+   *
+   * `getSnapshot()` に乗らない raw payload (`gameover` の `reason` 等) を assert
+   * したい場合に使う。`config.events` callback とは独立経路で、scenario callback の
+   * throw も subscriber 通知を止めない。unsubscribe 関数を返す。
+   */
+  subscribeEvents?(cb: (events: readonly ServerEvent[]) => void): () => void;
+  /**
+   * tick loop を pause する (run() devHarness 親 frame のみ)。
+   * 時間駆動の `logic.update` が走らなくなり、shogi の持ち時間減算等の自動進行を
+   * 止められる。pause 中も `send` (action dispatch) と state 書換 API は通る。
+   * tick loop を持たない frame (子 iframe / sync 単独 frame / online) と
+   * `tickRate <= 0` の scenario では undefined / no-op。
+   */
+  pauseTick?(): void;
+  /** pauseTick を解除する。 */
+  resumeTick?(): void;
+  /** 手動で n tick 進める。default n = 1。 */
+  stepTick?(n?: number): void;
+  /** 現在の tick 値を返す。tick loop を持たない frame では undefined。 */
+  getCurrentTick?(): number;
+  /** pauseTick で止まっているかどうか。 */
+  isTickPaused?(): boolean;
+  /**
+   * `logic.setup` を再実行して virtual server を fresh start させる。
+   * run() devHarness の親 frame のみ attach される (state owner でしか reset 不可)。
+   *
+   * - `seed` 省略時は現在の seed を再利用 (= 決定論的同一初期化)
+   * - 数値を渡すとその seed で再初期化、`getSeed()` の戻り値も更新
+   * - `'random'` で新 seed (uint32) を生成
+   *
+   * pause 状態は維持される。`logic.setup` が副作用を持つ場合は再呼出で副作用が再発火する。
+   */
+  reset?(opts?: {
+    seed?: number | 'random';
+  }): void;
+}
+declare global {
+  interface Window {
+    __uzu_dev?: UzuDevHooks;
+  }
+}
+/**
+ * run/* モジュール (run/local-server-action / run/dev-server-action) が
+ * dev hooks に state を expose するための handle。
+ * online (server-action) モードでは handle 自体を返さない。
+ *
+ * state 書き換え API は state owner frame のみ提供する。
+ */
+interface RunHandle<S = unknown> {
+  /** 内部 state の getter (dev hooks 用)。host iframe を持たない側では undefined */
+  getRawState?(): S | null;
+  /** 生 state 全置換。host iframe を持たない側では undefined */
+  setRawState?(state: S): Promise<void>;
+  /** RFC 7396 風 Merge Patch。host iframe を持たない側では undefined */
+  mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
+  /** RFC 6902 JSON Patch。host iframe を持たない側では undefined */
+  patchRawState?(ops: JsonPatchOp[]): Promise<void>;
+  /** 既存 inputs と同等の action 送信 (dev hooks 用) */
+  sendAction(type: string, payload?: Record<string, unknown>): void;
+}
+/**
+ * sync/* モジュール (sync/dev / sync/local) が dev hooks に state を expose
+ * するための handle。online sync では handle 自体を返さない。
+ */
+interface SyncHandle<S = unknown> {
+  /** 内部 state の getter (dev hooks 用) */
+  getRawState?(): S | null;
+  /** 生 state 全置換 */
+  setRawState?(state: S): Promise<void>;
+  /** RFC 7396 風 Merge Patch */
+  mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
+  /** RFC 6902 JSON Patch */
+  patchRawState?(ops: JsonPatchOp[]): Promise<void>;
+}
+/**
+ * dev-hooks.ts から見た「SDK 内部のコンテキスト」。
+ * 各 run/* / sync/* モジュールがこの形の handle を組み立てて attachDevHooks に渡す。
+ */
+interface DevHooksCtx<S = unknown> {
+  /** 最新 snapshot (per-player view)。未初期化なら null。 */
+  getSnapshot(): unknown;
+  /** 生 state getter (dev/local mode のみ)。 */
+  getRawState?: () => S | null;
+  /** 生 state 全置換 (dev/local mode のみ)。 */
+  setRawState?: (state: S) => Promise<void>;
+  /** RFC 7396 風 Merge Patch (dev/local mode のみ)。 */
+  mergeRawState?: (patch: JsonMergePatch<S>) => Promise<void>;
+  /** RFC 6902 JSON Patch (dev/local mode のみ)。 */
+  patchRawState?: (ops: JsonPatchOp[]) => Promise<void>;
+  /** 現在の player ID (URL クエリ or runtime 解決)。 */
+  playerId(): string | null;
+  /**
+   * Action 送信。run devHarness 親 frame の `DevHostHandle` のみが
+   * 提供する。それ以外のモードでは省略 (= `__uzu_dev.send` も生えない)。
+   * `args.as` で server-side dispatch の `from` を指定する (必須)。
+   */
+  sendAction?(args: {
+    as: string;
+    type: string;
+    payload?: Record<string, unknown>;
+  }): Promise<void>;
+  /** snapshot 更新を listen する。unsubscribe 関数を返す。 */
+  subscribeSnapshot(cb: (snapshot: unknown) => void): () => void;
+  /**
+   * action handler / `logic.update` 由来の emit を listen する。run devHarness 親
+   * frame の `DevHostHandle` のみが提供する。それ以外のモードでは省略
+   * (= `__uzu_dev.subscribeEvents` も生えない)。
+   */
+  subscribeEvents?(cb: (events: readonly ServerEvent[]) => void): () => void;
+  /** dev harness 親 frame の virtual server seed。親 attach 経路のみ。 */
+  getSeed?: () => number;
+  pauseTick?: () => void;
+  resumeTick?: () => void;
+  stepTick?: (n?: number) => void;
+  getCurrentTick?: () => number;
+  isTickPaused?: () => boolean;
+  /**
+   * run() devHarness 親 frame の `DevHostHandle.reset` を expose する。
+   * state owner でしか fresh start できないので、それ以外の mode では undefined。
+   */
+  reset?: (opts?: {
+    seed?: number | 'random';
+  }) => void;
+}
+declare function createDevHooks<S>(ctx: DevHooksCtx<S>): UzuDevHooks<S>;
+declare function attachDevHooks<S>(ctx: DevHooksCtx<S>): void;
+//#endregion
+export { minus as $, DEFAULT_ICON_URLS as A, ServerActionContext as B, SetFn as C, ActionContext as D, ActionArgs as E, GameLogic as F, ServerOnlyActionContext as G, ServerActionMap as H, SERVER_TIME as I, SetupContext as J, ServerOnlyActionHandlerFn as K, Seat as L, DeadlineArgs as M, DeadlineContext as N, ActionHandler as O, Emit as P, GameTime as Q, SeededRandom as R, SendAction as S, Operation as T, ServerEvent as U, ServerActionHandler as V, ServerOnlyAction as W, UpdateContext as X, UpdateArgs as Y, Duration as Z, PayloadMap as _, attachDevHooks as a, PlayersChangedMessage as b, getPredictionWarnings as c, ConnectionCallbacks as d, plus as et, ConnectionState as f, PatchFn as g, GameConfig as h, UzuDevHooks as i, applyJsonPatch as it, Deadline as j, ActionMap as k, BridgeChannel as l, EventSubscription as m, RunHandle as n, JsonPatchOp as nt, createDevHooks as o, EventHandler as p, SetupArgs as q, SyncHandle as r, applyJsonMergePatch as rt, PredictionWarning as s, DevHooksCtx as t, JsonMergePatch as tt, BridgeMessage as u, PlayScreenMessage as v, SyncConfig as w, SeatKind as x, PlayerVoiceState as y, ServerActionArgs as z };