@uzuhq/code-sdk 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -15,9 +15,10 @@
  * 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 { SERVER_TIME, DEFAULT_ICON_URLS } 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, EventHandler, EventSubscription, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
+export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
+export { serverNow } from './server-clock.js';
 export { Room } from './room.js';
 export type { RoomLike } from './room.js';
 export { ReconnectableWebSocket } from './reconnectable-ws.js';

package/dist/index.js

@@ -1,5 +1,6 @@
-export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
+export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
+export { serverNow } from './server-clock.js';
 export { Room } from './room.js';
 export { ReconnectableWebSocket } from './reconnectable-ws.js';
 export { SeededRandomImpl } from './random.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

@@ -15,48 +15,94 @@ export function runLocalServerAction(config) {
     }));
     const myId = players[0].id;
     // イベント収集→一括配信（DO と同じパターン）
+    // ソロモードでは alarm の代わりに setTimeout で予約を実現する。
+    // key ごとに 1 件へ畳む点は本番と同じ。
+    const scheduled = new Map();
+    const makeScheduleCtx = () => ({
+        schedule(options) {
+            const at = options.at ?? Date.now() + (options.after ?? 0) * 1000;
+            const prev = scheduled.get(options.key);
+            if (prev)
+                clearTimeout(prev);
+            scheduled.set(options.key, setTimeout(() => {
+                scheduled.delete(options.key);
+                try {
+                    dispatchAction(options.action, options.payload ?? {});
+                }
+                catch (err) {
+                    console.error(`[Scheduler] ❌ key=${options.key}:`, err);
+                }
+            }, Math.max(0, at - Date.now())));
+            return at;
+        },
+        unschedule(key) {
+            const t = scheduled.get(key);
+            if (t)
+                clearTimeout(t);
+            scheduled.delete(key);
+        },
+    });
+    // ソロモードはこのクライアント自身がサーバーなので、先読みという概念が無い。
+    // predict の値によらず、確定として 1 回だけ実行する。
     const dispatchEvents = (evts) => {
         for (const e of evts) {
-            events?.[e.name]?.(e.data);
+            events?.[e.name]?.handler(e.data);
         }
     };
     // setRawState で全置換できるよう let。closures は名前参照なので最新束縛を読む。
     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 ?? {} });
+        // ソロモードはこのクライアント自身がサーバーなので、実時刻がそのまま正となる。
+        const now = Date.now();
+        if (plain && !legacyServerOnly) {
+            try {
+                plain(state, payload ?? {}, myId, plainEmit, { now, ...makeScheduleCtx() });
+            }
+            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,
+                    now,
+                    ...makeScheduleCtx(),
+                });
+            }
+            catch (err) {
+                console.warn('[SDK LocalServerAction] Action error:', err);
+                return;
+            }
+            dispatchEvents(serverEvents);
+            onState(state, myId);
+        })();
     };
     inputs(dispatchAction);
     onState(state, myId);
@@ -66,7 +112,14 @@ export function runLocalServerAction(config) {
             const tickEvents = [];
             const tickEmit = (name, data) => tickEvents.push({ name, data: data ?? {} });
             try {
-                logic.update(state, { random, tick, emit: tickEmit, playerInputs });
+                logic.update(state, {
+                    random,
+                    tick,
+                    now: Date.now(),
+                    ...makeScheduleCtx(),
+                    emit: tickEmit,
+                    playerInputs,
+                });
             }
             catch (err) {
                 console.error(`[SDK LocalServerAction] tick error at tick=${tick}:`, err);

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

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

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

@@ -0,0 +1,218 @@
+/**
+ * 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: {
+                predict: true,
+                handler: () => {
+                    fired.push('moved');
+                },
+            },
+            charged: {
+                predict: false,
+                handler: () => {
+                    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,15 +8,15 @@
  * トランスポート (WebSocket / BroadcastChannel) と上位ロジック (楽観更新 / pending
  * キュー / ack ベースの確定 / rollback) を分離し、3 モードで挙動が揃うことを実装で保証する。
  *
- * - `send(type, payload)`: standard handler は同期で先行実行し pending キューへ。
- *   serverOnly handler は skip して transport にだけ送る。
+ * - `send(type, payload)`: `logic.actions` の handler を同期で先行実行し pending キューへ。
+ *   `logic.serverActions` は先読みせず transport にだけ送る。
  * - `applyState(state, { ack, from, events })`: フル state を受信した時に呼ぶ。
  * - `applyDelta(patches, { ack, from, events })`: JSON Patch を受信した時に呼ぶ
  *   (適用失敗時は false を返すので transport 側でフル state を再要求する)。
  * - `rollback(seq)`: `__action_error` 受信時に該当 action を pending から除去して再適用。
  * - `reset(state)`: 再接続後の state 復元用 (pending を全クリア)。
  */
-import type { GameLogic } from '../types.js';
+import type { GameLogic, EventSubscription } from '../types.js';
 import type { Operation } from '../json-patch.js';
 export interface EventEntry {
     name: string;
@@ -25,16 +25,22 @@ export interface EventEntry {
 export interface ConfirmOptions {
     /** transport から受け取った action ack (確定された pending action の seq) */
     ack?: number;
-    /** ack の送信元 player id。自分の pending と一致した時だけ events を skip する */
+    /** ack の送信元 player id */
     from?: string;
-    /** サーバー (or 仮想サーバー) が dispatch した events */
+    /**
+     * サーバーが確定させた events。`actions` 由来と `serverActions` 由来を区別しない
+     * 1 本のリスト。
+     *
+     * 先読みで既に配信済みのものはクライアント側で差し引く (pending の `fired` 記録と
+     * 突き合わせる)。サーバーが袋を分ける必要はない。
+     */
     events?: EventEntry[];
 }
 export interface OptimisticActionClientConfig<S> {
     logic: GameLogic<S>;
     playerId: string;
     onState: (state: S, playerId: string) => void;
-    events?: Record<string, (data: Record<string, unknown>) => void>;
+    events?: Record<string, EventSubscription>;
     /** action を transport に流すコールバック */
     sendAction: (msg: {
         action: string;
@@ -45,6 +51,11 @@ export interface OptimisticActionClientConfig<S> {
 export interface OptimisticActionClient<S> {
     /** input から呼ばれる action dispatch (楽観更新 + transport 送信) */
     send(type: string, payload?: any): void;
+    /**
+     * サーバーが打刻した時刻の観測値を渡してクロックオフセットを更新する。
+     * transport が受信した全メッセージで呼んでよい (serverTime を持たないものは無視される)。
+     */
+    observeServerTime(serverTime: number | undefined): void;
     /** 仮想サーバー / DO からフル state を受信した時に呼ぶ */
     applyState(state: S, options?: ConfirmOptions): void;
     /** DO から JSON Patch delta を受信した時に呼ぶ。適用失敗時は false (transport で再要求) */

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

@@ -1,6 +1,7 @@
 import { applyPatch } from '../json-patch.js';
 import { isServerOnlyAction } from '../server-only.js';
 import { runPredicted } from '../dev-prediction-traps.js';
+import { observeServerTime, serverNow } from '../server-clock.js';
 export function createOptimisticActionClient(config) {
     const { logic, playerId, onState, events, sendAction } = config;
     /** サーバー確定 state (楽観的更新のベース) */
@@ -9,17 +10,71 @@ export function createOptimisticActionClient(config) {
     let displayState = null;
     /** クライアント側の action 通番 */
     let actionSeq = 0;
-    /** 送信済みだがサーバー未確認の action キュー */
+    /**
+     * 送信済みだがサーバー未確認の action キュー。
+     * `now` は送信時に推定した値。再適用でも同じ値を使う (取り直すと表示がガタつく)。
+     */
     const pendingActions = [];
-    const emit = (eventName, data) => {
-        events?.[eventName]?.(data ?? {});
-    };
+    /**
+     * 先読みで実行済みの events。
+     *
+     * IMPORTANT: pending action ごとではなくクライアント単位で持つ。二重実行は「自分の
+     * action の ack」だけでなく「他プレイヤーの action のブロードキャスト」でも起きるため
+     * (A と B が同時に同じ行送りを撃つと、B は自分の先読みで実行済みなのに A 由来の
+     * 配信でもう一度実行してしまう)。どの配信が来ても、まずここと突き合わせる。
+     *
+     * 記録には「どの action の先読みで実行したか」(seq) を持たせる。その action が ack
+     * された時点で引き当てられていない記録は「予測したが実際には起きなかった出来事」なので
+     * 捨てる。seq を持たせずに「pending が空になったら捨てる」だけにすると、別の action が
+     * 未確定な間ずっと外れた記録が生き残り、その後に本当に起きた同名イベントを 1 回
+     * 握り潰してしまう。
+     *
+     * サーバーは 1 本の接続へ処理順どおりに送るので、他プレイヤーの配信は自分の ack より
+     * 必ず先に届く = 引き当てのチャンスは記録が生きている間に必ず来る。
+     */
+    let firedPredictions = [];
     /** 再適用時はイベントを発火しない (送信時に既に発火済み) */
     const noopEmit = () => { };
     const dispatchEvents = (evts) => {
-        for (const e of evts) {
-            events?.[e.name]?.(e.data);
+        for (const e of evts)
+            events?.[e.name]?.handler(e.data);
+    };
+    /** events の同一性キー。name と data が一致すれば「同じ出来事」とみなす。 */
+    const eventKey = (e) => `${e.name}\u0000${JSON.stringify(e.data ?? {})}`;
+    /**
+     * 先読み用の schedule。予約自体はサーバーだけが持つので**何もしない**が、
+     * 戻り値 (確定した絶対時刻) は返す。シナリオは戻り値を表示用の endsAt として
+     * state に入れるので、ここで undefined を返すと先読み中だけタイマーが消える。
+     *
+     * 型には schedule があるのに実体を渡さないと `ctx.schedule is not a function` で
+     * 先読みが丸ごと落ちる (predicted な action から呼ばれた瞬間)。
+     */
+    const predictedScheduleCtx = (now) => ({
+        schedule: (options) => options.at != null ? Number(options.at) : now + Number(options.after ?? 0) * 1000,
+        unschedule: () => { },
+    });
+    /**
+     * サーバーの events から、先読みで実行済みのものを差し引く (多重集合の差)。
+     *
+     * - 予測が当たった  → 差が空。二重に実行しない
+     * - 予測が外れた    → サーバー側の正しい event が残り、確定として実行される
+     * - 先読みで実行していない (predict: false / serverActions 由来 / 他プレイヤー由来)
+     *   → そのまま残って実行される
+     */
+    const subtractFired = (serverEvts) => {
+        if (firedPredictions.length === 0)
+            return serverEvts;
+        const out = [];
+        for (const e of serverEvts) {
+            const k = eventKey(e);
+            const idx = firedPredictions.findIndex((f) => eventKey(f) === k);
+            // 一致したら「先読みで実行済み」なので配信せず、記録も 1 件消費する。
+            if (idx >= 0)
+                firedPredictions.splice(idx, 1);
+            else
+                out.push(e);
         }
+        return out;
     };
     /**
      * confirmedState をベースに pending actions を再適用して displayState を更新する。
@@ -31,52 +86,78 @@ export function createOptimisticActionClient(config) {
         displayState = structuredClone(confirmedState);
         let i = 0;
         while (i < pendingActions.length) {
-            const { action, payload } = pendingActions[i];
+            const { action, payload, now } = 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, {}));
+                runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {
+                    now,
+                    ...predictedScheduleCtx(now),
+                }));
                 i++;
             }
             catch {
+                displayState = base;
                 pendingActions.splice(i, 1);
             }
         }
         onState(displayState, playerId);
     };
     /**
-     * 自分が出した pending action が ack されたかを判定し、events 重複排除と
-     * pending キューの掃除を行う。
+     * サーバーからの配信を処理する。
+     *
+     * 送信元が誰であれ、まず先読みの実行記録と突き合わせる。自分の ack だけを見ていると、
+     * 他プレイヤーの action が同じ出来事を起こしたときに二重実行になる。
      */
     const handleAck = (ack, from, evts) => {
-        const isMyAck = from === playerId && ack !== undefined && pendingActions.some((p) => p.seq === ack);
-        if (!isMyAck) {
-            dispatchEvents(evts);
-        }
+        dispatchEvents(subtractFired(evts));
         if (from === playerId && ack !== undefined) {
             while (pendingActions.length > 0 && pendingActions[0].seq <= ack) {
                 pendingActions.shift();
             }
+            // 確定した action の記録で引き当てられなかったものは「予測したが実際には
+            // 起きなかった出来事」。残すと次に本当に起きたときに握り潰してしまう。
+            firedPredictions = firedPredictions.filter((f) => f.seq > ack);
         }
     };
     return {
         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;
+            // サーバーがこのアクションを処理する時刻の推定。再適用でも同じ値を使うので、
+            // ここで 1 回だけ確定させて pending に載せる。
+            const now = serverNow();
+            // predict: true の event だけ先読み時点で実行し、実行したものを記録する。
+            const predictEmit = (eventName, data) => {
+                const subscription = events?.[eventName];
+                if (!subscription?.predict)
+                    return;
+                const payloadData = data ?? {};
+                subscription.handler(payloadData);
+                firedPredictions.push({ seq, name: eventName, data: payloadData });
+            };
+            // 旧 serverOnly() が actions に残っている logic では、その handler を先読みすると
+            // サーバー専用のはずの副作用がクライアントでも走る。brand を見て弾く。
             if (handler && !isServerOnlyAction(handler) && target !== null) {
                 try {
-                    runPredicted(type, () => handler(target, payload ?? {}, playerId, emit, {}));
-                    pendingActions.push({ seq, action: type, payload: payload ?? {} });
+                    runPredicted(type, () => handler(target, payload ?? {}, playerId, predictEmit, {
+                        now,
+                        ...predictedScheduleCtx(now),
+                    }));
+                    pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
                     onState(target, playerId);
                 }
                 catch {
@@ -85,6 +166,10 @@ export function createOptimisticActionClient(config) {
             }
             sendAction({ action: type, payload: payload ?? {}, seq });
         },
+        observeServerTime(serverTime) {
+            // 実体は server-clock.ts (UI 側の serverNow() と同じオフセットを共有する)。
+            observeServerTime(serverTime);
+        },
         applyState(state, options = {}) {
             handleAck(options.ack, options.from, options.events ?? []);
             confirmedState = state;
@@ -110,11 +195,14 @@ export function createOptimisticActionClient(config) {
             const idx = pendingActions.findIndex((p) => p.seq === seq);
             if (idx !== -1) {
                 pendingActions.splice(idx, 1);
+                // rollback した action の先読み記録も捨てる (その出来事は起きなかった)。
+                firedPredictions = firedPredictions.filter((f) => f.seq !== seq);
                 reapplyPendingActions();
             }
         },
         reset(state) {
             pendingActions.length = 0;
+            firedPredictions = [];
             confirmedState = state;
             displayState = structuredClone(state);
             onState(displayState, playerId);