@uzuhq/code-sdk 0.3.8

package/dist/dev-hooks.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @docs
+ * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ *
+ * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
+ * state を決定論的に読み書きするための window.__uzu_dev API。
+ *
+ * Flutter native ホスト (window.FlutterHost あり) では一切 attach されない。
+ * dev harness の子 iframe / Playwright iframe / 単独 page では attach される。
+ *
+ * state 書き換え API:
+ * - `setRawState(fullState)`        : 全置換
+ * - `mergeRawState(patch)`          : RFC 7396 風 JSON Merge Patch (object 階層の部分更新)
+ * - `patchRawState(ops)`            : RFC 6902 JSON Patch (path-based ops、array index 単体書換可)
+ *
+ * online ServerAction では state が Worker DO 側にあるため 3 つとも undefined。
+ *
+ * SDK は state shape に依存しない generic primitive だけを提供する。
+ * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
+ * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
+ */
+import type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
+import type { ServerEvent } from './types.js';
+export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
+export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
+export 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;
+    /**
+     * 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 のみ提供する。
+ */
+export 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 自体を返さない。
+ */
+export 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 に渡す。
+ */
+export 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;
+}
+export declare function createDevHooks<S>(ctx: DevHooksCtx<S>): UzuDevHooks<S>;
+export declare function attachDevHooks<S>(ctx: DevHooksCtx<S>): void;

package/dist/dev-hooks.js

@@ -0,0 +1,130 @@
+/**
+ * @docs
+ * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ *
+ * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
+ * state を決定論的に読み書きするための window.__uzu_dev API。
+ *
+ * Flutter native ホスト (window.FlutterHost あり) では一切 attach されない。
+ * dev harness の子 iframe / Playwright iframe / 単独 page では attach される。
+ *
+ * state 書き換え API:
+ * - `setRawState(fullState)`        : 全置換
+ * - `mergeRawState(patch)`          : RFC 7396 風 JSON Merge Patch (object 階層の部分更新)
+ * - `patchRawState(ops)`            : RFC 6902 JSON Patch (path-based ops、array index 単体書換可)
+ *
+ * online ServerAction では state が Worker DO 側にあるため 3 つとも undefined。
+ *
+ * SDK は state shape に依存しない generic primitive だけを提供する。
+ * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
+ * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
+ */
+export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
+export function createDevHooks(ctx) {
+    const getRawState = () => (ctx.getRawState ? ctx.getRawState() : null);
+    const waitForSnapshot = (predicate, options) => {
+        const timeoutMs = options?.timeoutMs ?? 10000;
+        return new Promise((resolve, reject) => {
+            const current = ctx.getSnapshot();
+            if (current != null) {
+                let ok = false;
+                try {
+                    ok = predicate(current);
+                }
+                catch (err) {
+                    reject(err);
+                    return;
+                }
+                if (ok) {
+                    resolve(current);
+                    return;
+                }
+            }
+            const timer = setTimeout(() => {
+                unsubscribe();
+                reject(new Error(`[uzu_dev] waitForSnapshot timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const unsubscribe = ctx.subscribeSnapshot((snap) => {
+                let ok;
+                try {
+                    ok = predicate(snap);
+                }
+                catch (err) {
+                    clearTimeout(timer);
+                    unsubscribe();
+                    reject(err);
+                    return;
+                }
+                if (ok) {
+                    clearTimeout(timer);
+                    unsubscribe();
+                    resolve(snap);
+                }
+            });
+        });
+    };
+    const hooks = {
+        getSnapshot: () => ctx.getSnapshot(),
+        getRawState,
+        playerId: () => ctx.playerId(),
+        subscribeSnapshot: (cb) => ctx.subscribeSnapshot(cb),
+        waitForSnapshot,
+    };
+    if (ctx.sendAction) {
+        const sendAction = ctx.sendAction;
+        hooks.send = (args) => sendAction(args);
+    }
+    if (ctx.setRawState) {
+        const setRawState = ctx.setRawState;
+        hooks.setRawState = (state) => setRawState(state);
+    }
+    if (ctx.mergeRawState) {
+        const mergeRawState = ctx.mergeRawState;
+        hooks.mergeRawState = (patch) => mergeRawState(patch);
+    }
+    if (ctx.patchRawState) {
+        const patchRawState = ctx.patchRawState;
+        hooks.patchRawState = (ops) => patchRawState(ops);
+    }
+    if (ctx.getSeed) {
+        const getSeed = ctx.getSeed;
+        hooks.getSeed = () => getSeed();
+    }
+    // Tick 制御: ctx 側で提供されている時だけ wire する。子 iframe / sync /
+    // online 等 tick loop を持たない frame では undefined のままなので、scenario 側で
+    // `__uzu_dev.pauseTick?.()` の optional chain で safe に呼べる。
+    if (ctx.pauseTick) {
+        const pauseTick = ctx.pauseTick;
+        hooks.pauseTick = () => pauseTick();
+    }
+    if (ctx.resumeTick) {
+        const resumeTick = ctx.resumeTick;
+        hooks.resumeTick = () => resumeTick();
+    }
+    if (ctx.stepTick) {
+        const stepTick = ctx.stepTick;
+        hooks.stepTick = (n) => stepTick(n);
+    }
+    if (ctx.getCurrentTick) {
+        const getCurrentTick = ctx.getCurrentTick;
+        hooks.getCurrentTick = () => getCurrentTick();
+    }
+    if (ctx.isTickPaused) {
+        const isTickPaused = ctx.isTickPaused;
+        hooks.isTickPaused = () => isTickPaused();
+    }
+    if (ctx.reset) {
+        const reset = ctx.reset;
+        hooks.reset = (opts) => reset(opts);
+    }
+    if (ctx.subscribeEvents) {
+        const subscribeEvents = ctx.subscribeEvents;
+        hooks.subscribeEvents = (cb) => subscribeEvents(cb);
+    }
+    return hooks;
+}
+export function attachDevHooks(ctx) {
+    // `init()` → `run()` の順で 2 回 attach されるのは正常フロー (run/sync 経由なら 1 回のみ)。
+    // silently 上書きする。
+    window.__uzu_dev = createDevHooks(ctx);
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/dev-hooks.test.js

@@ -0,0 +1,294 @@
+/**
+ * dev-hooks.ts の unit test。
+ *
+ * カバー対象:
+ * - createDevHooks: read / send / setRawState / mergeRawState / patchRawState /
+ *   waitForSnapshot の API contract
+ * - attachDevHooks: window.__uzu_dev への代入と上書き
+ *
+ * applyJsonMergePatch / applyJsonPatch そのものの単体テストは
+ * `dev-state-patch.test.ts` に分離。
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { attachDevHooks, createDevHooks } from './dev-hooks.js';
+import { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
+function makeState() {
+    return {
+        game: { currentPhaseId: 'phase_a', timerEndsAt: 1000 },
+        players: {
+            p1: { ready: false, name: 'Alice' },
+            p2: { ready: false, name: 'Bob' },
+        },
+        scenario: { id: 'scenario_1' },
+        tags: ['initial'],
+    };
+}
+describe('createDevHooks', () => {
+    function makeCtx(overrides = {}) {
+        // setRawState で参照ごと差し替えられるよう wrap する。test 側の expect は
+        // box.current 経由で常に最新参照を読む。
+        const box = { current: makeState() };
+        const listeners = new Set();
+        const sendAction = vi.fn();
+        const notify = (snap) => {
+            listeners.forEach((cb) => cb(snap));
+        };
+        const ctx = {
+            getSnapshot: () => box.current,
+            getRawState: () => box.current,
+            setRawState: async (next) => {
+                box.current = next;
+            },
+            mergeRawState: async (patch) => {
+                applyJsonMergePatch(box.current, patch);
+            },
+            patchRawState: async (ops) => {
+                applyJsonPatch(box.current, ops);
+            },
+            playerId: () => 'p1',
+            sendAction,
+            subscribeSnapshot: (cb) => {
+                listeners.add(cb);
+                return () => {
+                    listeners.delete(cb);
+                };
+            },
+            ...overrides,
+        };
+        return { ctx, state: box, notify, sendAction };
+    }
+    it('Read API: getSnapshot / getRawState / playerId を返す', () => {
+        const { ctx, state } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.getSnapshot()).toBe(state.current);
+        expect(hooks.getRawState()).toBe(state.current);
+        expect(hooks.playerId()).toBe('p1');
+    });
+    it('send() は ctx.sendAction に args オブジェクトをそのまま渡す', () => {
+        const { ctx, sendAction } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.send).toBeDefined();
+        hooks.send({ as: 'p2', type: 'vote', payload: { target: 'p1' } });
+        expect(sendAction).toHaveBeenCalledWith({
+            as: 'p2',
+            type: 'vote',
+            payload: { target: 'p1' },
+        });
+    });
+    it('ctx.sendAction 未提供だと hooks.send は undefined', () => {
+        const { ctx } = makeCtx({ sendAction: undefined });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.send).toBeUndefined();
+    });
+    it('send() は ctx.sendAction の rejection をそのまま伝搬する', async () => {
+        const sendActionReject = vi.fn(() => Promise.reject(new Error('Not your turn')));
+        const { ctx } = makeCtx({ sendAction: sendActionReject });
+        const hooks = createDevHooks(ctx);
+        await expect(hooks.send({ as: 'p1', type: 't' })).rejects.toThrow('Not your turn');
+    });
+    // ─── setRawState (全置換) ─────────────────────────
+    it('setRawState() は Promise を返し state を全置換する', async () => {
+        const { ctx, state } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        const next = {
+            game: { currentPhaseId: 'phase_z', timerEndsAt: 999 },
+            players: { px: { ready: true, name: 'X' } },
+            scenario: null,
+        };
+        await expect(hooks.setRawState(next)).resolves.toBeUndefined();
+        expect(state.current).toBe(next);
+        // 旧 state にあった players.p1 は新 state に含まれないので消える (= 全置換意味)
+        expect(state.current.players.p1).toBeUndefined();
+    });
+    it('ctx.setRawState 未提供だと hooks.setRawState は undefined', () => {
+        const { ctx } = makeCtx({ setRawState: undefined });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.setRawState).toBeUndefined();
+    });
+    // ─── mergeRawState (RFC 7396 風 merge patch) ─────
+    it('mergeRawState() は object 階層を recursive merge する', async () => {
+        const { ctx, state } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.mergeRawState).toBeDefined();
+        await hooks.mergeRawState({ players: { p1: { ready: true } } });
+        expect(state.current.players.p1.ready).toBe(true);
+        expect(state.current.players.p1.name).toBe('Alice');
+        expect(state.current.players.p2.ready).toBe(false);
+    });
+    it('mergeRawState() で array に object patch を当てると rejection になる', async () => {
+        const { ctx } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        await expect(hooks.mergeRawState({ tags: { 0: 'oops' } })).rejects.toThrow(/refusing to merge a plain object into array field/);
+    });
+    it('ctx.mergeRawState 未提供だと hooks.mergeRawState は undefined', () => {
+        const { ctx } = makeCtx({ mergeRawState: undefined });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.mergeRawState).toBeUndefined();
+    });
+    // ─── patchRawState (RFC 6902 json patch) ─────────
+    it('patchRawState() は path-based ops を順に適用する', async () => {
+        const { ctx, state } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.patchRawState).toBeDefined();
+        await hooks.patchRawState([
+            { op: 'replace', path: '/game/currentPhaseId', value: 'phase_b' },
+            { op: 'replace', path: '/players/p1/ready', value: true },
+            { op: 'add', path: '/tags/-', value: 'extra' },
+        ]);
+        expect(state.current.game.currentPhaseId).toBe('phase_b');
+        expect(state.current.players.p1.ready).toBe(true);
+        expect(state.current.tags).toEqual(['initial', 'extra']);
+    });
+    it('ctx.patchRawState 未提供だと hooks.patchRawState は undefined', () => {
+        const { ctx } = makeCtx({ patchRawState: undefined });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.patchRawState).toBeUndefined();
+    });
+    it('tick 制御: ctx で提供されると hooks に wire される', () => {
+        const pauseTick = vi.fn();
+        const resumeTick = vi.fn();
+        const stepTick = vi.fn();
+        const { ctx } = makeCtx({
+            pauseTick,
+            resumeTick,
+            stepTick,
+            getCurrentTick: () => 42,
+            isTickPaused: () => true,
+        });
+        const hooks = createDevHooks(ctx);
+        hooks.pauseTick();
+        hooks.resumeTick();
+        hooks.stepTick(3);
+        expect(pauseTick).toHaveBeenCalledOnce();
+        expect(resumeTick).toHaveBeenCalledOnce();
+        expect(stepTick).toHaveBeenCalledWith(3);
+        expect(hooks.getCurrentTick()).toBe(42);
+        expect(hooks.isTickPaused()).toBe(true);
+    });
+    it('tick 制御: ctx 未提供だと hooks 側でも undefined のまま', () => {
+        const { ctx } = makeCtx(); // pauseTick 等を渡さない
+        const hooks = createDevHooks(ctx);
+        expect(hooks.pauseTick).toBeUndefined();
+        expect(hooks.resumeTick).toBeUndefined();
+        expect(hooks.stepTick).toBeUndefined();
+        expect(hooks.getCurrentTick).toBeUndefined();
+        expect(hooks.isTickPaused).toBeUndefined();
+    });
+    it('reset: ctx で提供されると hooks に wire され opts がそのまま渡る', () => {
+        const reset = vi.fn();
+        const { ctx } = makeCtx({ reset });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.reset).toBeDefined();
+        hooks.reset();
+        expect(reset).toHaveBeenCalledWith(undefined);
+        hooks.reset({ seed: 7 });
+        expect(reset).toHaveBeenLastCalledWith({ seed: 7 });
+        hooks.reset({ seed: 'random' });
+        expect(reset).toHaveBeenLastCalledWith({ seed: 'random' });
+    });
+    it('reset: ctx 未提供だと hooks.reset は undefined', () => {
+        const { ctx } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.reset).toBeUndefined();
+    });
+    it('subscribeSnapshot: notify を listen し unsubscribe 後は呼ばれない', () => {
+        const { ctx, state, notify } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        const trace = [];
+        const unsub = hooks.subscribeSnapshot((s) => {
+            trace.push(s.game.currentPhaseId);
+        });
+        state.current.game.currentPhaseId = 'phase_b';
+        notify(state.current);
+        state.current.game.currentPhaseId = 'phase_c';
+        notify(state.current);
+        expect(trace).toEqual(['phase_b', 'phase_c']);
+        unsub();
+        state.current.game.currentPhaseId = 'phase_d';
+        notify(state.current);
+        expect(trace).toEqual(['phase_b', 'phase_c']);
+    });
+    it('subscribeEvents: ctx で提供されると hooks に wire される', () => {
+        const subscribeEvents = vi.fn(() => () => { });
+        const { ctx } = makeCtx({ subscribeEvents });
+        const hooks = createDevHooks(ctx);
+        expect(hooks.subscribeEvents).toBeDefined();
+        const cb = (_evts) => { };
+        hooks.subscribeEvents(cb);
+        expect(subscribeEvents).toHaveBeenCalledWith(cb);
+    });
+    it('subscribeEvents: ctx 未提供だと hooks.subscribeEvents は undefined', () => {
+        const { ctx } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        expect(hooks.subscribeEvents).toBeUndefined();
+    });
+    it('subscribeEvents: unsubscribe 関数がそのまま戻る', () => {
+        const unsubscribe = vi.fn();
+        const subscribeEvents = vi.fn(() => unsubscribe);
+        const { ctx } = makeCtx({ subscribeEvents });
+        const hooks = createDevHooks(ctx);
+        const off = hooks.subscribeEvents(() => { });
+        off();
+        expect(unsubscribe).toHaveBeenCalledOnce();
+    });
+    it('waitForSnapshot: predicate が即時 true なら現在 snapshot で resolve', async () => {
+        const { ctx } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        const result = await hooks.waitForSnapshot((s) => s.game.currentPhaseId === 'phase_a');
+        expect(result.game.currentPhaseId).toBe('phase_a');
+    });
+    it('waitForSnapshot: predicate が false なら subscribe で待ち、notify で resolve', async () => {
+        const { ctx, state, notify } = makeCtx();
+        const hooks = createDevHooks(ctx);
+        const promise = hooks.waitForSnapshot((s) => s.game.currentPhaseId === 'phase_b');
+        state.current.game.currentPhaseId = 'phase_b';
+        notify(state.current);
+        const result = await promise;
+        expect(result.game.currentPhaseId).toBe('phase_b');
+    });
+    it('waitForSnapshot: timeoutMs 経過で reject する', async () => {
+        const { ctx, state } = makeCtx();
+        // 初期 snapshot は phase_a なので、phase_b 待ちはタイムアウトする
+        state.current.game.currentPhaseId = 'phase_a';
+        const hooks = createDevHooks(ctx);
+        await expect(hooks.waitForSnapshot((s) => s.game.currentPhaseId === 'phase_b', {
+            timeoutMs: 50,
+        })).rejects.toThrow(/timed out/);
+    });
+});
+describe('attachDevHooks', () => {
+    afterEach(() => {
+        delete window.__uzu_dev;
+    });
+    it('window.__uzu_dev に hooks を attach する', () => {
+        const state = makeState();
+        attachDevHooks({
+            getSnapshot: () => state,
+            playerId: () => 'p1',
+            sendAction: vi.fn(),
+            subscribeSnapshot: () => () => { },
+        });
+        expect(window.__uzu_dev).toBeDefined();
+        expect(window.__uzu_dev.playerId()).toBe('p1');
+    });
+    it('複数回 attach すると最後のものに置き換わる (silently, no warn)', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        attachDevHooks({
+            getSnapshot: () => 'first',
+            playerId: () => 'first_id',
+            sendAction: vi.fn(),
+            subscribeSnapshot: () => () => { },
+        });
+        attachDevHooks({
+            getSnapshot: () => 'second',
+            playerId: () => 'second_id',
+            sendAction: vi.fn(),
+            subscribeSnapshot: () => () => { },
+        });
+        expect(window.__uzu_dev.playerId()).toBe('second_id');
+        expect(window.__uzu_dev.getSnapshot()).toBe('second');
+        // init() -> run() の順で 2 回 attach されるのは正常フローなので warn を出さない契約
+        expect(warnSpy).not.toHaveBeenCalled();
+        warnSpy.mockRestore();
+    });
+});