@uzuhq/code-sdk 0.3.9 → 0.4.0

package/README.md

@@ -566,7 +566,7 @@ scenario の `test/*.ts` / `tools/*.ts` で SDK を import せず `window.__uzu_
 
 これで `(window as any).__uzu_dev` で殴らずに `window.__uzu_dev?.send({ as: 'dev_0', type: '...', payload: ... })` が補完 + 型チェックされる。SDK を直接 import するモジュールでは `dev-hooks.ts` 側の `declare global` で既に型が見えているため、本 entry を `types` に足す必要はない。
 
-詳細は `docs/play_screen_v3/sdk-guide/dev-hooks.md` を参照。
+詳細は `docs/uzu_code/sdk-guide/dev-hooks.md` を参照。
 
 ## License
 

package/dist/dev-hooks.d.ts

@@ -1,6 +1,6 @@
 /**
  * @docs
- * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
  *
  * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
  * state を決定論的に読み書きするための window.__uzu_dev API。
@@ -20,6 +20,7 @@
  * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
  */
 import type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
+import type { PredictionWarning } from './dev-prediction-traps.js';
 import type { ServerEvent } from './types.js';
 export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
@@ -36,6 +37,13 @@ export interface UzuDevHooks<S = unknown> {
      * 貼り付けやすい uint32 を返す。
      */
     getSeed?(): number;
+    /**
+     * 素の action handler が先読み実行中に実時刻 / 乱数を読んだ記録。
+     *
+     * 先読みはサーバーと同じ結果を再現できることが前提なので、ここに何か入っていたら
+     * そのシナリオはオンラインでだけ予測がズレる。E2E で `[]` を assert すると回帰を防げる。
+     */
+    getPredictionWarnings(): readonly PredictionWarning[];
     /**
      * Server-side で action を直接 dispatch する。
      *

package/dist/dev-hooks.js

@@ -1,6 +1,6 @@
 /**
  * @docs
- * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
  *
  * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
  * state を決定論的に読み書きするための window.__uzu_dev API。
@@ -19,6 +19,7 @@
  * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
  * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
  */
+import { getPredictionWarnings } from './dev-prediction-traps.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export function createDevHooks(ctx) {
     const getRawState = () => (ctx.getRawState ? ctx.getRawState() : null);
@@ -69,6 +70,7 @@ export function createDevHooks(ctx) {
         playerId: () => ctx.playerId(),
         subscribeSnapshot: (cb) => ctx.subscribeSnapshot(cb),
         waitForSnapshot,
+        getPredictionWarnings: () => getPredictionWarnings(),
     };
     if (ctx.sendAction) {
         const sendAction = ctx.sendAction;

package/dist/dev-prediction-traps.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
+ *
+ * 素の action handler のクライアント先読み実行中に、サーバーと結果が一致しない API
+ * (実時刻 / 乱数) が呼ばれたら警告する。
+ *
+ * 先読みは「サーバーと同じコードを同じ入力で走らせれば同じ結果になる」ことが前提で、
+ * 実時刻や乱数を読むとその前提が崩れる。ズレた state は一瞬表示されたあと ack で
+ * 上書きされ、画面が飛ぶ。
+ *
+ * 静的解析ではなく実行時に差し替えるのは、handler がヘルパー関数を何段挟んでいても
+ * 捕まえたいから。同じ理由で、演出用途 (描画ループの `Math.sin(Date.now() / 400)` など)
+ * は先読み経路を通らないので原理的に誤検知しない。
+ */
+export interface PredictionWarning {
+    /** 呼び出した action 名 */
+    action: string;
+    /** 呼ばれた API 名 (`'Date.now()'` など) */
+    api: string;
+}
+/**
+ * 素の action handler の先読み実行を計装して走らせる。
+ *
+ * Flutter native ホスト (本番) では計装せず素通しする。判定基準は dev hooks と同じ。
+ */
+export declare const runPredicted: (action: string, run: () => void) => void;
+/** 検出済みの警告一覧。`__uzu_dev.getPredictionWarnings()` から E2E で assert する用。 */
+export declare const getPredictionWarnings: () => readonly PredictionWarning[];
+/** 検出結果をリセットする (テスト用)。 */
+export declare const clearPredictionWarnings: () => void;

package/dist/dev-prediction-traps.test.d.ts

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

package/dist/dev-prediction-traps.test.js

@@ -0,0 +1,178 @@
+/**
+ * dev-prediction-traps.ts の unit test。
+ *
+ * 素の action handler をクライアント先読みで実行する間だけグローバルを差し替え、
+ * サーバーと結果が一致しない API (実時刻 / 乱数) の呼び出しを検出する仕組みを検証する。
+ *
+ * カバー対象:
+ * - 検出対象 API それぞれが記録されること
+ * - ヘルパー関数を経由した呼び出しも捕まえること (静的解析では追えない経路)
+ * - 同じ action / API の重複を 1 件に畳むこと
+ * - 実行後にグローバルが必ず元へ戻ること (例外時も含む)
+ * - 先読みの外では計装されていないこと
+ * - 本番 (Flutter native ホスト) では計装しないこと
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { clearPredictionWarnings, getPredictionWarnings, runPredicted, } from './dev-prediction-traps.js';
+beforeEach(() => {
+    clearPredictionWarnings();
+    // 警告本文は console に出るので、テスト出力を汚さないよう黙らせる。
+    vi.spyOn(console, 'groupCollapsed').mockImplementation(() => { });
+    vi.spyOn(console, 'log').mockImplementation(() => { });
+    vi.spyOn(console, 'groupEnd').mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete window.FlutterHost;
+});
+describe('runPredicted', () => {
+    /** 検出対象 API を先読み中に呼ぶと、action 名とセットで記録される。 */
+    describe('非決定的な API の検出', () => {
+        it('Date.now() を記録する', () => {
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'gm.timer.set', api: 'Date.now()' }]);
+        });
+        it('引数なしの new Date() を記録する', () => {
+            runPredicted('startPresentation', () => {
+                new Date();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'startPresentation', api: 'new Date()' }]);
+        });
+        /**
+         * 引数付きの new Date() は与えられた値から決まるので、サーバーと結果がズレない。
+         * 誤検知を避けるため記録しない。
+         */
+        it('引数付きの new Date(...) は記録しない', () => {
+            runPredicted('setDeadline', () => {
+                new Date(1700000000000);
+            });
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+        it('Math.random() を記録する', () => {
+            runPredicted('restart', () => {
+                Math.random();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'restart', api: 'Math.random()' }]);
+        });
+        it('performance.now() を記録する', () => {
+            runPredicted('tickLocal', () => {
+                performance.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'tickLocal', api: 'performance.now()' }]);
+        });
+        /**
+         * 静的解析が最も苦手とする経路。handler 本体に API が現れず、ヘルパー関数の中で
+         * 呼ばれていても捕まえられることを保証する (kikaidochu の setLine が実際にこの形)。
+         */
+        it('ヘルパー関数を経由した呼び出しも記録する', () => {
+            const setDeadlineViaHelper = () => Date.now() + 60000;
+            runPredicted('setLine', () => {
+                setDeadlineViaHelper();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'setLine', api: 'Date.now()' }]);
+        });
+        /** 元の API の戻り値はそのまま通す (計装で挙動を変えない)。 */
+        it('元の API の戻り値を変えない', () => {
+            let observed = 0;
+            runPredicted('noop', () => {
+                observed = Date.now();
+            });
+            expect(observed).toBeGreaterThan(0);
+        });
+    });
+    describe('重複の抑制', () => {
+        /** 同じ action で同じ API を何度呼んでも記録は 1 件。連打でログが溢れない。 */
+        it('同一 action / 同一 API は 1 件に畳む', () => {
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+                Date.now();
+            });
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'gm.timer.set', api: 'Date.now()' }]);
+        });
+        /** action が違えば別件として記録する。どの action を直すべきか分かる必要がある。 */
+        it('action が違えば別件として記録する', () => {
+            runPredicted('a', () => {
+                Date.now();
+            });
+            runPredicted('b', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([
+                { action: 'a', api: 'Date.now()' },
+                { action: 'b', api: 'Date.now()' },
+            ]);
+        });
+        /** 同じ action でも API が違えば別件。両方直す必要があるため。 */
+        it('API が違えば別件として記録する', () => {
+            runPredicted('restart', () => {
+                Date.now();
+                Math.random();
+            });
+            expect(getPredictionWarnings()).toEqual([
+                { action: 'restart', api: 'Date.now()' },
+                { action: 'restart', api: 'Math.random()' },
+            ]);
+        });
+    });
+    describe('グローバルの復元', () => {
+        /** 先読みの外で呼ばれる API は計装されていない (描画ループが誤検知しない前提)。 */
+        it('実行後にグローバルが元へ戻る', () => {
+            const beforeNow = Date.now;
+            const beforeRandom = Math.random;
+            const beforeDate = Date;
+            runPredicted('a', () => {
+                Date.now();
+            });
+            expect(Date.now).toBe(beforeNow);
+            expect(Math.random).toBe(beforeRandom);
+            expect(Date).toBe(beforeDate);
+        });
+        /**
+         * handler が throw しても復元する。楽観実行は throw を握りつぶして
+         * サーバー送信だけ続ける経路があるので、ここで漏れるとグローバルが汚染されたまま残る。
+         */
+        it('handler が例外を投げてもグローバルが元へ戻る', () => {
+            const beforeNow = Date.now;
+            const beforeDate = Date;
+            expect(() => {
+                runPredicted('a', () => {
+                    Date.now();
+                    throw new Error('handler failed');
+                });
+            }).toThrow('handler failed');
+            expect(Date.now).toBe(beforeNow);
+            expect(Date).toBe(beforeDate);
+            // 例外で中断しても、そこまでに呼ばれた API は記録されている。
+            expect(getPredictionWarnings()).toEqual([{ action: 'a', api: 'Date.now()' }]);
+        });
+        /** 先読みの外の呼び出しは記録されない。描画コードの Date.now() を拾わない保証。 */
+        it('先読みの外で呼んだ API は記録しない', () => {
+            Date.now();
+            Math.random();
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+    });
+    describe('本番での無効化', () => {
+        /**
+         * Flutter native ホストでは計装しない。判定基準は dev hooks の attach と同じく
+         * `window.FlutterHost` の有無。
+         */
+        it('window.FlutterHost があるときは計装せず素通しする', () => {
+            window.FlutterHost = { postMessage: () => { } };
+            const beforeNow = Date.now;
+            let ran = false;
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+                ran = true;
+            });
+            expect(ran).toBe(true);
+            expect(Date.now).toBe(beforeNow);
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+    });
+});

package/dist/dev-state-patch.d.ts

@@ -1,6 +1,6 @@
 /**
  * @docs
- * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
  *
  * `__uzu_dev.mergeRawState` / `__uzu_dev.patchRawState` の中身。
  * scenario state を「object 階層の部分更新 (RFC 7396)」と「array 要素単体の書換

package/dist/dev-state-patch.js

@@ -1,6 +1,6 @@
 /**
  * @docs
- * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
  *
  * `__uzu_dev.mergeRawState` / `__uzu_dev.patchRawState` の中身。
  * scenario state を「object 階層の部分更新 (RFC 7396)」と「array 要素単体の書換

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
  * @docs
- * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
- * - ブリッジ仕様: docs/docs/play_screen_v3/bridge.md
- * - Relay仕様: docs/docs/play_screen_v3/relay.md
- * - SyncRoom仕様: docs/docs/play_screen_v3/sync-room.md
- * - ゲーム仕様: docs/docs/play_screen_v3/games.md
- * - システム全体像: docs/docs/play_screen_v3/overview.md
- * - AI用APIリファレンス (README): javascript/play_screen_v3/uzuhq-sdk/README.md
+ * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+ * - ブリッジ仕様: docs/docs/uzu_code/bridge.md
+ * - Relay仕様: docs/docs/uzu_code/relay.md
+ * - SyncRoom仕様: docs/docs/uzu_code/sync-room.md
+ * - ゲーム仕様: docs/docs/uzu_code/games.md
+ * - システム全体像: docs/docs/uzu_code/overview.md
+ * - AI用APIリファレンス (README): javascript/uzu_code/sdk/README.md
  *
  * SDK は runtime のみ。 dev harness の DOM 描画 (iframe grid / HUD / state
  * inspector) と in-memory サーバー (Node ws による GameRoom / SyncRoom / RelayRoom) は
@@ -15,7 +15,7 @@
  * scenario ディレクトリで `uzu dev` を実行するだけで良い。 子 iframe は既存 online mode
  * (`?server=ws://localhost:<port>` 経路) で dev-server に接続する。
  */
-export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionHandler, ServerOnlyAction, ServerOnlyActionHandlerFn, } from './types.js';
+export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionContext, ActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
 export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { Room } from './room.js';
@@ -27,6 +27,8 @@ export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
 export { attachDevHooks, createDevHooks } from './dev-hooks.js';
 export type { UzuDevHooks, DevHooksCtx, RunHandle, SyncHandle } from './dev-hooks.js';
+export { getPredictionWarnings } from './dev-prediction-traps.js';
+export type { PredictionWarning } from './dev-prediction-traps.js';
 import type { BridgeMessage, GameConfig, SyncConfig, PlayerVoiceState } from './types.js';
 import type { RoomLike } from './room.js';
 type GameMessageHandler = (payload: Record<string, unknown>) => void;

package/dist/index.js

@@ -5,6 +5,7 @@ export { ReconnectableWebSocket } from './reconnectable-ws.js';
 export { SeededRandomImpl } from './random.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export { attachDevHooks, createDevHooks } from './dev-hooks.js';
+export { getPredictionWarnings } from './dev-prediction-traps.js';
 import { Room } from './room.js';
 import { ReconnectableWebSocket } from './reconnectable-ws.js';
 import { runOnlineServerAction } from './run/server-action.js';

package/dist/run/local-server-action.d.ts

@@ -1,7 +1,7 @@
 /**
  * @docs
- * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
- * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
  *
  * ブラウザ内 LocalGameRoom — GameRoom DO の動作をサーバーレスで再現する。
  * server_url がない場合に vite dev だけで ServerAction シナリオをローカル実行する。

package/dist/run/local-server-action.js

@@ -49,7 +49,7 @@ export function runLocalServerAction(config) {
             return;
         }
         try {
-            handler(state, payload ?? {}, myId, actionEmit, { tick });
+            handler(state, payload ?? {}, myId, actionEmit, {});
         }
         catch (err) {
             console.warn('[SDK LocalServerAction] Action error:', err);

package/dist/run/optimistic-action-client.d.ts

@@ -1,7 +1,7 @@
 /**
  * @docs
- * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
- * - 開発パターン: docs/docs/play_screen_v3/sdk-guide/patterns.md
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
  *
  * ServerAction の楽観的更新クライアント — online / emulator 共通ロジック。
  *

package/dist/run/optimistic-action-client.js

@@ -1,5 +1,6 @@
 import { applyPatch } from '../json-patch.js';
 import { isServerOnlyAction } from '../server-only.js';
+import { runPredicted } from '../dev-prediction-traps.js';
 export function createOptimisticActionClient(config) {
     const { logic, playerId, onState, events, sendAction } = config;
     /** サーバー確定 state (楽観的更新のベース) */
@@ -32,13 +33,14 @@ export function createOptimisticActionClient(config) {
         while (i < pendingActions.length) {
             const { action, payload } = pendingActions[i];
             const handler = logic.actions[action];
-            if (!handler) {
+            // serverOnly handler は send 時点で pending に積まれないので、ここに来るのは
+            // 素の handler だけ。型を絞るためにも明示的に弾く。
+            if (!handler || isServerOnlyAction(handler)) {
                 pendingActions.splice(i, 1);
                 continue;
             }
             try {
-                // tick はサーバー側でのみ正確に管理される。再適用ではサーバー tick が不明のため 0 を使う。
-                handler(displayState, payload, playerId, noopEmit, { tick: 0 });
+                runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {}));
                 i++;
             }
             catch {
@@ -69,11 +71,13 @@ export function createOptimisticActionClient(config) {
             // serverOnly handler は先行実行を skip。pending にも積まないので、ack 受信時の
             // isMyAck 判定で false となり、サーバー発の events が普通に emit される。
             const handler = logic.actions[type];
-            if (handler && !isServerOnlyAction(handler) && displayState !== null) {
+            // callback 内では displayState の narrowing が効かないので const に退避する。
+            const target = displayState;
+            if (handler && !isServerOnlyAction(handler) && target !== null) {
                 try {
-                    handler(displayState, payload ?? {}, playerId, emit, { tick: 0 });
+                    runPredicted(type, () => handler(target, payload ?? {}, playerId, emit, {}));
                     pendingActions.push({ seq, action: type, payload: payload ?? {} });
-                    onState(displayState, playerId);
+                    onState(target, playerId);
                 }
                 catch {
                     // ローカル実行失敗 → 楽観的更新せずサーバーに送るだけ

package/dist/run/server-action.d.ts

@@ -1,7 +1,7 @@
 /**
  * @docs
- * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
- * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
  *
  * ServerAction モードのオンライン接続 (WebSocket トランスポート)。
  *

package/dist/server-only.d.ts

@@ -1,7 +1,7 @@
 /**
  * @docs
- * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
- * - 開発パターン: docs/docs/play_screen_v3/sdk-guide/patterns.md
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
  *
  * serverOnly() で wrap した handler はクライアント側の楽観的更新（先行実行）を
  * スキップし、サーバー側でだけ実行される。fetch などの副作用付き処理を安全に

package/dist/sync/local.d.ts

@@ -1,7 +1,7 @@
 /**
  * @docs
- * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
- * - 開発パターン: docs/docs/play_screen_v3/sdk-guide/patterns.md
+ * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
  */
 import type { SyncConfig } from '../types.js';
 import type { SyncHandle } from '../dev-hooks.js';

package/dist/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * @docs
- * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
- * - APIリファレンス: docs/docs/play_screen_v3/sdk-guide/api-reference.md
- * - 開発パターン: docs/docs/play_screen_v3/sdk-guide/patterns.md
- * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+ * - APIリファレンス: docs/docs/uzu_code/sdk-guide/api-reference.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
+ * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
  */
 /** @deprecated 旧フラット形式。新コードでは BridgeMessage を使用 */
 export type PlayScreenMessage = {
@@ -67,12 +67,21 @@ export interface SeededRandom {
     pick<T>(array: T[]): T;
     shuffle<T>(array: T[]): T[];
 }
-export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: {
-    tick: number;
-}) => void;
-export type ServerOnlyActionHandlerFn<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: {
+/**
+ * 素の action handler の実行文脈。空なのは意図的。
+ *
+ * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
+ * 再現できない値 (tick / 実時刻 / 乱数) をここで配ると、サーバー・ソロ・dev では
+ * 本物が入るのにオンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
+ * そういう値が要る action は serverOnly() にして先読みの対象から外す。
+ */
+export type ActionContext = Record<never, never>;
+/** serverOnly() handler の実行文脈。サーバーでしか走らないので tick を渡せる。 */
+export interface ServerOnlyActionContext {
     tick: number;
-}) => Promise<void> | void;
+}
+export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ActionContext) => void;
+export type ServerOnlyActionHandlerFn<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerOnlyActionContext) => Promise<void> | void;
 /** serverOnly() で wrap された handler。`__serverOnly` brand で識別する。 */
 export type ServerOnlyAction<S> = ServerOnlyActionHandlerFn<S> & {
     readonly __serverOnly: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzuhq/code-sdk",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {