@uzuhq/code-sdk 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -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, ActionContext, ActionHandler, ServerOnlyAction, ServerOnlyActionContext, 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, ServerActionContext, ServerActionHandler, 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';

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

@@ -6,9 +6,10 @@
  * ブラウザ内 LocalGameRoom — GameRoom DO の動作をサーバーレスで再現する。
  * server_url がない場合に vite dev だけで ServerAction シナリオをローカル実行する。
  *
- * online (`runOnlineServerAction`) と挙動を揃えるため、standard handler は同期で実行し
+ * online (`runOnlineServerAction`) と挙動を揃えるため、`logic.actions` は同期で実行し
  * `sendAction()` 直後に `onState()` を同期発火する (楽観的更新だけで完結する仕様)。
- * serverOnly handler のみ `await` で非同期実行し、完了後に `onState()` を呼ぶ。
+ * `logic.serverActions` は `Promise<void>` を返しうるので `await` で実行し、完了後に
+ * `onState()` を呼ぶ。同名なら actions → serverActions の順で走る (サーバーと同じ)。
  */
 import type { GameConfig } from '../types.js';
 import type { RunHandle } from '../dev-hooks.js';

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

@@ -24,39 +24,49 @@ export function runLocalServerAction(config) {
     let state = logic.setup(players, random);
     let tick = 0;
     const playerInputs = {};
-    // Action 処理。standard handler は同期実行で `sendAction()` 直後の同期 onState を
-    // 保証する (online の楽観的更新と同じ挙動)。serverOnly handler は `Promise<void>`
-    // を返しうるので `await` で実行し、完了後に events と onState を発火する。
+    // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する
+    // (online の楽観的更新と同じ挙動)。`serverActions` は `Promise<void>` を返しうるので
+    // `await` で実行し、完了後に events と onState を発火する。
     // どちらも 1 回しか実行しない (online の「楽観 → サーバー確定」の 2 段階は再現しない)。
     const dispatchAction = (type, payload) => {
-        const handler = logic.actions[type];
-        if (!handler)
+        const plain = logic.actions[type];
+        // 移行期: 旧 serverOnly() を actions に入れたままの logic も動かす。
+        const legacyServerOnly = isServerOnlyAction(plain) ? plain : null;
+        const server = logic.serverActions?.[type] ?? legacyServerOnly;
+        if (!plain && !server)
             return;
-        const actionEvents = [];
-        const actionEmit = (name, data) => actionEvents.push({ name, data: data ?? {} });
-        if (isServerOnlyAction(handler)) {
-            void (async () => {
-                try {
-                    await handler(state, payload ?? {}, myId, actionEmit, { tick });
-                }
-                catch (err) {
-                    console.warn('[SDK LocalServerAction] Action error:', err);
-                    return;
-                }
-                dispatchEvents(actionEvents);
-                onState(state, myId);
-            })();
-            return;
-        }
-        try {
-            handler(state, payload ?? {}, myId, actionEmit, {});
+        // events は emit 元ごとに分ける。online では actions 由来がクライアント先読みの
+        // 時点で発火するので、ここでも plain の実行直後に流す。共有すると serverActions が
+        // `await fetch()` を持つ場合に actions 側の events までその分遅れてしまい、
+        // 「ローカルモードだけ音が遅れる」というモード差になる。
+        const plainEvents = [];
+        const serverEvents = [];
+        const plainEmit = (name, data) => plainEvents.push({ name, data: data ?? {} });
+        const serverEmit = (name, data) => serverEvents.push({ name, data: data ?? {} });
+        if (plain && !legacyServerOnly) {
+            try {
+                plain(state, payload ?? {}, myId, plainEmit, {});
+            }
+            catch (err) {
+                console.warn('[SDK LocalServerAction] Action error:', err);
+                return;
+            }
+            dispatchEvents(plainEvents);
+            onState(state, myId);
         }
-        catch (err) {
-            console.warn('[SDK LocalServerAction] Action error:', err);
+        if (!server)
             return;
-        }
-        dispatchEvents(actionEvents);
-        onState(state, myId);
+        void (async () => {
+            try {
+                await server(state, payload ?? {}, myId, serverEmit, { tick, random });
+            }
+            catch (err) {
+                console.warn('[SDK LocalServerAction] Action error:', err);
+                return;
+            }
+            dispatchEvents(serverEvents);
+            onState(state, myId);
+        })();
     };
     inputs(dispatchAction);
     onState(state, myId);

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

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

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

@@ -0,0 +1,208 @@
+/**
+ * local-server-action.ts (ソロモード) の unit test。
+ *
+ * ソロモードは「クライアント = サーバー」なので `actions` と `serverActions` の
+ * 両方を 1 回ずつ実行する。online の「楽観 → サーバー確定」の 2 段階は再現しないが、
+ * **events の発火タイミングは online に揃える** 必要がある。
+ *
+ * online では actions 由来の events はクライアント先読みの時点で即座に発火する。
+ * ソロでも同じく plain の実行直後に流さないと、`serverActions` が `await fetch()` を
+ * 持つシナリオで「ソロモードだけ音が遅れる」というモード差になる。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { runLocalServerAction } from './local-server-action.js';
+import { serverOnly } from '../server-only.js';
+/** 遅延させた serverActions を持たせるための待ち。 */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const run = (logic) => {
+    const fired = [];
+    const states = [];
+    let send = () => { };
+    const config = {
+        logic,
+        playerCount: 1,
+        onState: (s) => states.push(structuredClone(s)),
+        inputs: (sendAction) => {
+            send = sendAction;
+        },
+        events: {
+            moved: () => fired.push('moved'),
+            charged: () => fired.push('charged'),
+        },
+    };
+    runLocalServerAction(config);
+    return { send: (t, p) => send(t, p), fired, states };
+};
+const baseLogic = (overrides = {}) => ({
+    setup: () => ({ moves: 0, charged: 0, rolled: -1 }),
+    actions: {},
+    update: () => { },
+    ...overrides,
+});
+describe('runLocalServerAction', () => {
+    describe('actions と serverActions の実行', () => {
+        /** actions だけの action は同期実行され、その場で state と events が確定する。 */
+        it('actions だけなら同期で state と events が確定する', () => {
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+            }));
+            h.send('move');
+            expect(h.states[h.states.length - 1].moves).toBe(1);
+            expect(h.fired).toEqual(['moved']);
+        });
+        /** serverActions だけの action は、await 完了後に state と events が反映される。 */
+        it('serverActions だけなら await 後に反映される', async () => {
+            const h = run(baseLogic({
+                serverActions: {
+                    notifyExternal: async (state, _payload, _playerId, emit) => {
+                        await tick();
+                        state.charged += 1;
+                        emit('charged');
+                    },
+                },
+            }));
+            h.send('notifyExternal');
+            expect(h.fired).toEqual([]); // まだ await 中
+            await tick();
+            await tick();
+            expect(h.states[h.states.length - 1].charged).toBe(1);
+            expect(h.fired).toEqual(['charged']);
+        });
+        /**
+         * 同名で両方定義されている場合、サーバーと同じく actions → serverActions の順で走る。
+         * serverActions は actions が書いた結果を見られる。
+         */
+        it('同名なら actions → serverActions の順に走る', async () => {
+            const order = [];
+            const h = run(baseLogic({
+                actions: {
+                    move: (state) => {
+                        order.push('actions');
+                        state.moves += 1;
+                    },
+                },
+                serverActions: {
+                    move: (state, _payload, _playerId, _emit, ctx) => {
+                        order.push('serverActions');
+                        // actions の結果が見えている
+                        expect(state.moves).toBe(1);
+                        state.charged += ctx.tick + 1;
+                        state.rolled = ctx.random.int(100);
+                    },
+                },
+            }));
+            h.send('move');
+            await tick();
+            expect(order).toEqual(['actions', 'serverActions']);
+            const last = h.states[h.states.length - 1];
+            expect(last.moves).toBe(1);
+            expect(last.charged).toBe(1); // tick 0 + 1
+            // ctx.random が渡っている (setup 前の -1 から変わっている)
+            expect(last.rolled).toBeGreaterThanOrEqual(0);
+        });
+    });
+    describe('events の発火タイミング', () => {
+        /**
+         * online では actions 由来の events は先読み時に即発火する。ソロでも同じタイミングで
+         * 流し、serverActions の await を待たせない。ここが揃っていないとモード差になる。
+         */
+        it('actions の events は serverActions の await を待たない', async () => {
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+                serverActions: {
+                    move: async (state, _payload, _playerId, emit) => {
+                        await tick();
+                        state.charged += 1;
+                        emit('charged');
+                    },
+                },
+            }));
+            h.send('move');
+            // serverActions がまだ await 中でも actions 側の events は出ている
+            expect(h.fired).toEqual(['moved']);
+            await tick();
+            await tick();
+            expect(h.fired).toEqual(['moved', 'charged']);
+        });
+    });
+    describe('エラー処理', () => {
+        /** actions が throw したら serverActions へ進まず、state 更新も通知しない。 */
+        it('actions が throw したら serverActions を実行しない', () => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            let serverRan = false;
+            const h = run(baseLogic({
+                actions: {
+                    move: () => {
+                        throw new Error('boom');
+                    },
+                },
+                serverActions: {
+                    move: () => {
+                        serverRan = true;
+                    },
+                },
+            }));
+            h.send('move');
+            expect(serverRan).toBe(false);
+            warn.mockRestore();
+        });
+        /** serverActions が throw しても、既に流れた actions 側の events は取り消さない。 */
+        it('serverActions が throw しても actions の events は残る', async () => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+                serverActions: {
+                    move: () => {
+                        throw new Error('boom');
+                    },
+                },
+            }));
+            h.send('move');
+            await tick();
+            expect(h.fired).toEqual(['moved']);
+            warn.mockRestore();
+        });
+    });
+    describe('旧 serverOnly() の互換', () => {
+        /**
+         * R2 の古い logic.js は serverOnly() の brand を付けたまま actions に入っている。
+         * ソロモードでも brand を見て「先読みしない handler」として扱う。
+         */
+        it('actions に入った serverOnly() は server 側として実行される', async () => {
+            const logic = baseLogic({
+                actions: {
+                    // 新しい型では actions に serverOnly() を入れられない (それが本 PR の狙い)。
+                    // ここは「R2 に残っている古い logic.js」を再現するための意図的な型違反。
+                    // @ts-expect-error 移行期の互換挙動を検証するため
+                    legacy: serverOnly(async (state, _payload, _playerId, emit, ctx) => {
+                        await tick();
+                        state.charged += ctx.tick + 1;
+                        emit('charged');
+                    }),
+                },
+            });
+            const h = run(logic);
+            h.send('legacy');
+            expect(h.fired).toEqual([]); // 先読みされていない
+            await tick();
+            await tick();
+            expect(h.states[h.states.length - 1].charged).toBe(1);
+            expect(h.fired).toEqual(['charged']);
+        });
+    });
+});

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

@@ -8,10 +8,10 @@
  * トランスポート (WebSocket / BroadcastChannel) と上位ロジック (楽観更新 / pending
  * キュー / ack ベースの確定 / rollback) を分離し、3 モードで挙動が揃うことを実装で保証する。
  *
- * - `send(type, payload)`: standard handler は同期で先行実行し pending キューへ。
- *   serverOnly handler は skip して transport にだけ送る。
- * - `applyState(state, { ack, from, events })`: フル state を受信した時に呼ぶ。
- * - `applyDelta(patches, { ack, from, events })`: JSON Patch を受信した時に呼ぶ
+ * - `send(type, payload)`: `logic.actions` の handler を同期で先行実行し pending キューへ。
+ *   `logic.serverActions` は先読みせず transport にだけ送る。
+ * - `applyState(state, { ack, from, events, serverEvents })`: フル state を受信した時に呼ぶ。
+ * - `applyDelta(patches, { ack, from, events, serverEvents })`: JSON Patch を受信した時に呼ぶ
  *   (適用失敗時は false を返すので transport 側でフル state を再要求する)。
  * - `rollback(seq)`: `__action_error` 受信時に該当 action を pending から除去して再適用。
  * - `reset(state)`: 再接続後の state 復元用 (pending を全クリア)。
@@ -27,8 +27,13 @@ export interface ConfirmOptions {
     ack?: number;
     /** ack の送信元 player id。自分の pending と一致した時だけ events を skip する */
     from?: string;
-    /** サーバー (or 仮想サーバー) が dispatch した events */
+    /** `logic.actions` 由来の events。自分の ack なら先読み時に発火済みなので skip する */
     events?: EventEntry[];
+    /**
+     * `logic.serverActions` 由来の events。先読みでは走らないので、自分の ack でも必ず配信する。
+     * これを `events` と混ぜると、同名 action の server 側 events が重複排除で消える。
+     */
+    serverEvents?: EventEntry[];
 }
 export interface OptimisticActionClientConfig<S> {
     logic: GameLogic<S>;

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

@@ -33,17 +33,21 @@ export function createOptimisticActionClient(config) {
         while (i < pendingActions.length) {
             const { action, payload } = pendingActions[i];
             const handler = logic.actions[action];
-            // serverOnly handler は send 時点で pending に積まれないので、ここに来るのは
-            // 素の handler だけ。型を絞るためにも明示的に弾く。
+            // 移行期の互換: 旧 serverOnly() を actions に入れたままの logic では、その handler は
+            // サーバー専用なので先読みの再適用対象から外す (send 時にも pending へ積んでいない)。
             if (!handler || isServerOnlyAction(handler)) {
                 pendingActions.splice(i, 1);
                 continue;
             }
+            // handler が途中まで state を変更してから throw すると、その部分変更が残ったまま
+            // publish されてしまう。1 件ごとに直前の確定形から作り直し、成功したものだけ採用する。
+            const base = structuredClone(displayState);
             try {
                 runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {}));
                 i++;
             }
             catch {
+                displayState = base;
                 pendingActions.splice(i, 1);
             }
         }
@@ -53,11 +57,13 @@ export function createOptimisticActionClient(config) {
      * 自分が出した pending action が ack されたかを判定し、events 重複排除と
      * pending キューの掃除を行う。
      */
-    const handleAck = (ack, from, evts) => {
+    const handleAck = (ack, from, evts, serverEvts) => {
         const isMyAck = from === playerId && ack !== undefined && pendingActions.some((p) => p.seq === ack);
         if (!isMyAck) {
             dispatchEvents(evts);
         }
+        // serverActions 由来は先読みで走っていないので、自分の ack でも必ず配信する。
+        dispatchEvents(serverEvts);
         if (from === playerId && ack !== undefined) {
             while (pendingActions.length > 0 && pendingActions[0].seq <= ack) {
                 pendingActions.shift();
@@ -68,11 +74,13 @@ export function createOptimisticActionClient(config) {
         send(type, payload) {
             actionSeq++;
             const seq = actionSeq;
-            // serverOnly handler は先行実行を skip。pending にも積まないので、ack 受信時の
-            // isMyAck 判定で false となり、サーバー発の events が普通に emit される。
+            // 先読みするのは logic.actions だけ。serverActions は transport にだけ送り、
+            // 結果は ack (state + serverEvents) で受け取る。
             const handler = logic.actions[type];
             // callback 内では displayState の narrowing が効かないので const に退避する。
             const target = displayState;
+            // 旧 serverOnly() が actions に残っている logic では、その handler を先読みすると
+            // サーバー専用のはずの副作用がクライアントでも走る。brand を見て弾く。
             if (handler && !isServerOnlyAction(handler) && target !== null) {
                 try {
                     runPredicted(type, () => handler(target, payload ?? {}, playerId, emit, {}));
@@ -86,7 +94,7 @@ export function createOptimisticActionClient(config) {
             sendAction({ action: type, payload: payload ?? {}, seq });
         },
         applyState(state, options = {}) {
-            handleAck(options.ack, options.from, options.events ?? []);
+            handleAck(options.ack, options.from, options.events ?? [], options.serverEvents ?? []);
             confirmedState = state;
             reapplyPendingActions();
         },
@@ -102,7 +110,7 @@ export function createOptimisticActionClient(config) {
             if (!ok)
                 return false;
             confirmedState = cloned;
-            handleAck(options.ack, options.from, options.events ?? []);
+            handleAck(options.ack, options.from, options.events ?? [], options.serverEvents ?? []);
             reapplyPendingActions();
             return true;
         },

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

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

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

@@ -0,0 +1,232 @@
+/**
+ * optimistic-action-client.ts の unit test。
+ *
+ * `logic.actions` (クライアント先読み + サーバーの 2 回実行) と `logic.serverActions`
+ * (サーバーのみ 1 回実行) を分離した設計が、events の重複排除と pending キューの
+ * 巻き戻しの両方で正しく閉じることを検証する。
+ *
+ * 特に重要なのは、同名 action で両方が定義されたケース。先読みで走るのは actions 側
+ * だけなので、serverActions が emit した events まで「自分の ack だから発火済み」として
+ * 捨ててしまうと、サーバー側のイベントが永久に届かなくなる。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createOptimisticActionClient } from './optimistic-action-client.js';
+import { serverOnly } from '../server-only.js';
+/** 旧 serverOnly() ブランド付き handler。actions に残っている古い logic を再現する。 */
+const legacyServerOnly = serverOnly((state) => {
+    state.charged += 1000;
+});
+const makeLogic = () => ({
+    setup: () => ({ moves: 0, charged: 0 }),
+    actions: {
+        move: (state) => {
+            state.moves += 1;
+        },
+        boom: () => {
+            throw new Error('always fails');
+        },
+        // 途中まで state を書き換えてから throw する (部分ミューテーションの検証用)
+        partial: (state) => {
+            state.moves += 1;
+            throw new Error('fails after mutating');
+        },
+        // 旧 serverOnly() が actions に残っている logic の再現
+        // @ts-expect-error 移行期の互換挙動を検証するため意図的に型違反させる
+        legacy: legacyServerOnly,
+    },
+    serverActions: {
+        // move と同名 = 同じ action の「サーバーだけで走る続き」
+        move: (state, _payload, _playerId, _emit, ctx) => {
+            state.charged += ctx.tick;
+        },
+        // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
+        notifyExternal: (state) => {
+            state.charged += 100;
+        },
+    },
+    update: () => { },
+});
+/** 直近の onState 通知。tsconfig の lib が Array#at 未対応なので添字で取る。 */
+const latest = (states) => states[states.length - 1];
+const setup = () => {
+    const sent = [];
+    const fired = [];
+    const states = [];
+    const client = createOptimisticActionClient({
+        logic: makeLogic(),
+        playerId: 'me',
+        onState: (s) => states.push(structuredClone(s)),
+        events: {
+            moved: () => fired.push('moved'),
+            charged: () => fired.push('charged'),
+        },
+        sendAction: ({ action, seq }) => sent.push({ action, seq }),
+    });
+    client.reset({ moves: 0, charged: 0 });
+    return { client, sent, fired, states };
+};
+describe('createOptimisticActionClient', () => {
+    describe('先読みの対象', () => {
+        /** actions にある handler だけがクライアントで先行実行される。 */
+        it('actions の handler は送信時に先行実行される', () => {
+            const { client, sent, states } = setup();
+            client.send('move');
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+            expect(sent).toEqual([{ action: 'move', seq: 1 }]);
+        });
+        /**
+         * serverActions にしか無い action は先読みされない。state を触らずサーバーへ送るだけ。
+         * 旧 serverOnly() と同じ挙動。
+         */
+        it('serverActions にしか無い action は先行実行されない', () => {
+            const { client, sent, states } = setup();
+            client.send('notifyExternal');
+            expect(latest(states)).toEqual({ moves: 0, charged: 0 });
+            expect(sent).toEqual([{ action: 'notifyExternal', seq: 1 }]);
+        });
+        /**
+         * 同名で両方定義されている場合、先読みされるのは actions 側だけ。
+         * serverActions 側の結果 (charged) はサーバーの ack が来るまで反映されない。
+         */
+        it('同名で両方ある場合、先読みは actions 側だけ', () => {
+            const { client, states } = setup();
+            client.send('move');
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+        });
+    });
+    describe('events の重複排除', () => {
+        /**
+         * 自分が出した action の ack では、actions 由来の events は先読み時に発火済みなので
+         * skip する。二重発火すると効果音が 2 回鳴るなどの不具合になる。
+         */
+        it('自分の ack では actions 由来の events を発火しない', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            client.applyState({ moves: 1, charged: 0 }, { ack: 1, from: 'me', events: [{ name: 'moved', data: {} }] });
+            expect(fired).toEqual([]);
+        });
+        /**
+         * serverActions 由来の events は先読みで走っていないので、自分の ack でも必ず発火する。
+         * ここを events と同じ配列で送ると重複排除に巻き込まれて永久に届かなくなる。
+         */
+        it('自分の ack でも serverEvents は発火する', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            client.applyState({ moves: 1, charged: 5 }, {
+                ack: 1,
+                from: 'me',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(fired).toEqual(['charged']);
+        });
+        /** 他プレイヤーの action なら先読みしていないので、両方とも発火する。 */
+        it('他プレイヤーの ack では両方発火する', () => {
+            const { client, fired } = setup();
+            client.applyState({ moves: 1, charged: 5 }, {
+                ack: 1,
+                from: 'other',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(fired).toEqual(['moved', 'charged']);
+        });
+    });
+    describe('pending キューと巻き戻し', () => {
+        /**
+         * pending に積まれるのは actions 分だけ。サーバー確定 state を受けたら、
+         * 未 ack の actions だけが再適用される (serverActions 分は state に含まれて来る)。
+         */
+        it('確定 state の上に未 ack の actions だけを再適用する', () => {
+            const { client, states } = setup();
+            client.send('move'); // seq 1
+            client.send('move'); // seq 2
+            // seq 1 だけ確定。charged はサーバー側で加算済みの値が入っている
+            client.applyState({ moves: 1, charged: 7 }, { ack: 1, from: 'me' });
+            // 確定 (moves:1) + 未 ack の seq 2 を再適用 = moves:2、charged はサーバー値のまま
+            expect(latest(states)).toEqual({ moves: 2, charged: 7 });
+        });
+        /** __action_error で該当 seq を除去し、残りを再適用する。 */
+        it('rollback は該当 action だけを取り消す', () => {
+            const { client, states } = setup();
+            client.send('move'); // seq 1
+            client.send('move'); // seq 2
+            expect(latest(states)).toEqual({ moves: 2, charged: 0 });
+            client.rollback(1);
+            // seq 1 が消えて seq 2 だけ再適用される
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+        });
+        /** 先行実行で throw した action は pending に積まれず、送信だけ行われる。 */
+        it('先行実行が throw した action は pending に積まれない', () => {
+            const { client, sent, states } = setup();
+            client.send('boom');
+            expect(sent).toEqual([{ action: 'boom', seq: 1 }]);
+            // pending が空なので、確定 state がそのまま表示される
+            client.applyState({ moves: 9, charged: 9 }, {});
+            expect(latest(states)).toEqual({ moves: 9, charged: 9 });
+        });
+    });
+    describe('applyDelta', () => {
+        /** delta 経路でも serverEvents の扱いは applyState と揃っている。 */
+        it('自分の ack でも serverEvents を発火する', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            const ok = client.applyDelta([{ op: 'replace', path: '/charged', value: 3 }], {
+                ack: 1,
+                from: 'me',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(ok).toBe(true);
+            expect(fired).toEqual(['charged']);
+        });
+        /** patch が当たらないときは events を発火せず false を返す (transport がフル state を再要求する)。 */
+        it('patch 適用に失敗したら events を発火せず false を返す', () => {
+            const { client, fired } = setup();
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const ok = client.applyDelta([{ op: 'replace', path: '/missing/deep', value: 1 }], {
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(ok).toBe(false);
+            expect(fired).toEqual([]);
+            warn.mockRestore();
+        });
+    });
+    describe('レビュー指摘の回帰防止', () => {
+        /**
+         * 旧 serverOnly() が actions に残っている logic では、その handler をクライアントで
+         * 先読みしてはいけない。サーバー専用の副作用 (fetch 等) が client でも走ってしまう。
+         */
+        it('actions に残った serverOnly() は先読みしない', () => {
+            const { client, sent, states } = setup();
+            client.send('legacy');
+            // state は動かず、送信だけ行われる
+            expect(latest(states)).toEqual({ moves: 0, charged: 0 });
+            expect(sent).toEqual([{ action: 'legacy', seq: 1 }]);
+        });
+        /** 再適用でも同じ。pending に積まれていても brand 付きなら実行しない。 */
+        it('再適用でも serverOnly() を実行しない', () => {
+            const { client, states } = setup();
+            client.send('move'); // seq 1 (pending へ)
+            client.send('legacy'); // seq 2 (pending へは積まれない)
+            client.applyState({ moves: 0, charged: 0 }, {});
+            // 確定 state に move だけが再適用され、legacy の +1000 は入らない
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+        });
+        /**
+         * 再適用中に handler が途中まで state を変更してから throw した場合、その部分変更を
+         * 残したまま publish してはいけない。
+         */
+        it('再適用で throw した handler の部分変更を残さない', () => {
+            const { client, states } = setup();
+            client.send('move'); // seq 1: moves +1
+            client.send('partial'); // seq 2: moves +1 してから throw (pending には積まれない)
+            // 送信時点で partial は throw するので pending に入らず、moves は 1 のまま
+            expect(latest(states).moves).toBe(1);
+            // 確定 state を受けて再適用しても、partial の部分変更は混ざらない
+            client.applyState({ moves: 0, charged: 0 }, {});
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+        });
+    });
+});

package/dist/run/server-action.js

@@ -123,9 +123,10 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
             const ack = parsed.ack;
             const from = parsed.from;
             const evts = parsed.events ?? [];
+            const serverEvts = parsed.serverEvents ?? [];
             serverSeq = parsed.seq ?? serverSeq + 1;
             requestStatePending = false;
-            client.applyState(parsed.state, { ack, from, events: evts });
+            client.applyState(parsed.state, { ack, from, events: evts, serverEvents: serverEvts });
             return;
         }
         // ─── Action 結果 (差分パッチ) ────────────────────────
@@ -133,6 +134,7 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
             const ack = parsed.ack;
             const from = parsed.from;
             const evts = parsed.events ?? [];
+            const serverEvts = parsed.serverEvents ?? [];
             const newSeq = parsed.seq ?? serverSeq + 1;
             if (newSeq !== serverSeq + 1) {
                 requestFullState();
@@ -142,6 +144,7 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
                 ack,
                 from,
                 events: evts,
+                serverEvents: serverEvts,
             });
             if (!ok) {
                 requestFullState();

package/dist/server-only.d.ts

@@ -3,24 +3,31 @@
  * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
  * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
  *
- * serverOnly() で wrap した handler はクライアント側の楽観的更新（先行実行）を
- * スキップし、サーバー側でだけ実行される。fetch などの副作用付き処理を安全に
- * 書ける。
+ * `serverOnly()` は `logic.serverActions` に置き換わった互換 API。
+ *
+ * 新しく書くコードでは `serverActions` フィールドへ直接置く。`actions` の型からは
+ * ユニオンが外れたため、`serverOnly()` で wrap した handler を `actions` に入れることは
+ * できない (型エラーになる)。
+ *
+ * `isServerOnlyAction()` はサーバー側テンプレが残す必要がある。R2 に保存済みの古い
+ * logic.js は `serverOnly()` の brand を持ったまま `actions` に入っており、新しい
+ * テンプレと組み合わさるため、brand を見ないと先読み対象として扱ってしまう。
  */
-import type { ActionHandler, ServerOnlyAction, ServerOnlyActionHandlerFn } from './types.js';
+import type { ActionHandler, ServerActionHandler, ServerOnlyAction } from './types.js';
 /**
- * server-only action handler を作る。
+ * @deprecated `logic.serverActions` に直接書く。
  *
- * 例:
  * ```ts
- * actions: {
- *   notifyExternal: serverOnly(async (state, payload, playerId) => {
- *     await fetch('https://example.com/notify', { ... });
- *     state.notifiedAt = Date.now();
- *   }),
- * }
+ * // before
+ * actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+ * // after
+ * serverActions: { notifyExternal: async (state) => { ... } }
  * ```
  */
-export declare function serverOnly<S>(handler: ServerOnlyActionHandlerFn<S>): ServerOnlyAction<S>;
-/** handler が serverOnly() で wrap されているか判定する。 */
-export declare function isServerOnlyAction<S>(handler: ActionHandler<S> | ServerOnlyAction<S> | undefined): handler is ServerOnlyAction<S>;
+export declare function serverOnly<S>(handler: ServerActionHandler<S>): ServerOnlyAction<S>;
+/**
+ * handler が `serverOnly()` で wrap されているか判定する。
+ *
+ * 移行期の互換用。`serverActions` へ移行済みの logic では常に false になる。
+ */
+export declare function isServerOnlyAction<S>(handler: ActionHandler<S> | ServerActionHandler<S> | ServerOnlyAction<S> | undefined): handler is ServerOnlyAction<S>;

package/dist/server-only.js

@@ -1,20 +1,21 @@
 /**
- * server-only action handler を作る。
+ * @deprecated `logic.serverActions` に直接書く。
  *
- * 例:
  * ```ts
- * actions: {
- *   notifyExternal: serverOnly(async (state, payload, playerId) => {
- *     await fetch('https://example.com/notify', { ... });
- *     state.notifiedAt = Date.now();
- *   }),
- * }
+ * // before
+ * actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+ * // after
+ * serverActions: { notifyExternal: async (state) => { ... } }
  * ```
  */
 export function serverOnly(handler) {
     return Object.assign(handler, { __serverOnly: true });
 }
-/** handler が serverOnly() で wrap されているか判定する。 */
+/**
+ * handler が `serverOnly()` で wrap されているか判定する。
+ *
+ * 移行期の互換用。`serverActions` へ移行済みの logic では常に false になる。
+ */
 export function isServerOnlyAction(handler) {
     return (typeof handler === 'function' && '__serverOnly' in handler && handler.__serverOnly === true);
 }

package/dist/types.d.ts

@@ -73,17 +73,25 @@ export interface SeededRandom {
  * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
  * 再現できない値 (tick / 実時刻 / 乱数) をここで配ると、サーバー・ソロ・dev では
  * 本物が入るのにオンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
- * そういう値が要る action は serverOnly() にして先読みの対象から外す。
+ * そういう値が要る処理は `serverActions` 側に書く。
  */
 export type ActionContext = Record<never, never>;
-/** serverOnly() handler の実行文脈。サーバーでしか走らないので tick を渡せる。 */
-export interface ServerOnlyActionContext {
+/** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
+export interface ServerActionContext {
     tick: number;
+    random: SeededRandom;
 }
+/** @deprecated `ServerActionContext` を使う。 */
+export type ServerOnlyActionContext = ServerActionContext;
 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> & {
+export type ServerActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerActionContext) => Promise<void> | void;
+/** @deprecated `ServerActionHandler` を使う。 */
+export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
+/**
+ * @deprecated `serverActions` フィールドに直接書く。
+ * `serverOnly()` で wrap された handler。`__serverOnly` brand で識別する。
+ */
+export type ServerOnlyAction<S> = ServerActionHandler<S> & {
     readonly __serverOnly: true;
 };
 export interface GameLogic<S> {
@@ -92,7 +100,22 @@ export interface GameLogic<S> {
      * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
      */
     setup(seats: Seat[], random: SeededRandom): S;
-    actions: Record<string, ActionHandler<S> | ServerOnlyAction<S>>;
+    /**
+     * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
+     *
+     * `serverActions` に同名のキーを置くと、同じ action の「サーバーだけで走る続き」に
+     * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
+     * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
+     */
+    actions: Record<string, ActionHandler<S>>;
+    /**
+     * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
+     * 再現できない処理をここに書く。async 可。
+     *
+     * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
+     * (旧 `serverOnly()` 相当) になる。
+     */
+    serverActions?: Record<string, ServerActionHandler<S>>;
     update(state: S, ctx: {
         random: SeededRandom;
         tick: number;

package/package.json

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