@uzuhq/code-sdk 0.5.0 → 0.7.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, ServerActionContext, ServerActionHandler, 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, ActionArgs, ActionContext, ActionHandler, ServerActionArgs, UpdateArgs, UpdateContext, 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.js

@@ -15,9 +15,38 @@ 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 は名前参照なので最新束縛を読む。
@@ -43,9 +72,16 @@ export function runLocalServerAction(config) {
         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, {});
+                plain({
+                    state,
+                    payload: payload ?? {},
+                    playerId: myId,
+                    ctx: { now, emit: plainEmit, ...makeScheduleCtx() },
+                });
             }
             catch (err) {
                 console.warn('[SDK LocalServerAction] Action error:', err);
@@ -58,7 +94,12 @@ export function runLocalServerAction(config) {
             return;
         void (async () => {
             try {
-                await server(state, payload ?? {}, myId, serverEmit, { tick, random });
+                await server({
+                    state,
+                    payload: payload ?? {},
+                    playerId: myId,
+                    ctx: { tick, random, now, emit: serverEmit, ...makeScheduleCtx() },
+                });
             }
             catch (err) {
                 console.warn('[SDK LocalServerAction] Action error:', err);
@@ -76,7 +117,17 @@ 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,
+                    ctx: {
+                        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.js

@@ -26,8 +26,18 @@ const run = (logic) => {
             send = sendAction;
         },
         events: {
-            moved: () => fired.push('moved'),
-            charged: () => fired.push('charged'),
+            moved: {
+                predict: true,
+                handler: () => {
+                    fired.push('moved');
+                },
+            },
+            charged: {
+                predict: false,
+                handler: () => {
+                    fired.push('charged');
+                },
+            },
         },
     };
     runLocalServerAction(config);
@@ -45,9 +55,9 @@ describe('runLocalServerAction', () => {
         it('actions だけなら同期で state と events が確定する', () => {
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
             }));
@@ -59,10 +69,10 @@ describe('runLocalServerAction', () => {
         it('serverActions だけなら await 後に反映される', async () => {
             const h = run(baseLogic({
                 serverActions: {
-                    notifyExternal: async (state, _payload, _playerId, emit) => {
+                    notifyExternal: async ({ state, ctx }) => {
                         await tick();
                         state.charged += 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     },
                 },
             }));
@@ -81,13 +91,13 @@ describe('runLocalServerAction', () => {
             const order = [];
             const h = run(baseLogic({
                 actions: {
-                    move: (state) => {
+                    move: ({ state }) => {
                         order.push('actions');
                         state.moves += 1;
                     },
                 },
                 serverActions: {
-                    move: (state, _payload, _playerId, _emit, ctx) => {
+                    move: ({ state, ctx }) => {
                         order.push('serverActions');
                         // actions の結果が見えている
                         expect(state.moves).toBe(1);
@@ -114,16 +124,16 @@ describe('runLocalServerAction', () => {
         it('actions の events は serverActions の await を待たない', async () => {
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
                 serverActions: {
-                    move: async (state, _payload, _playerId, emit) => {
+                    move: async ({ state, ctx }) => {
                         await tick();
                         state.charged += 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     },
                 },
             }));
@@ -161,9 +171,9 @@ describe('runLocalServerAction', () => {
             const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
                 serverActions: {
@@ -186,13 +196,14 @@ describe('runLocalServerAction', () => {
         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) => {
+                    // 検証対象は `__serverOnly` brand の判定であって、旧シグネチャの互換ではない。
+                    // handler 自体は現行の呼び出し形で書いている (旧形式の logic.js は現行テンプレでは
+                    // 動かない。公開済みゲームが無い前提で互換を切っている)。
+                    // @ts-expect-error actions に serverOnly() を入れるのは型違反だが、brand 判定を試す
+                    legacy: serverOnly(async ({ state, ctx }) => {
                         await tick();
                         state.charged += ctx.tick + 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     }),
                 },
             });

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

@@ -10,13 +10,13 @@
  *
  * - `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 を受信した時に呼ぶ
+ * - `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,21 +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;
-    /** `logic.actions` 由来の events。自分の ack なら先読み時に発火済みなので skip する */
-    events?: EventEntry[];
     /**
-     * `logic.serverActions` 由来の events。先読みでは走らないので、自分の ack でも必ず配信する。
-     * これを `events` と混ぜると、同名 action の server 側 events が重複排除で消える。
+     * サーバーが確定させた events。`actions` 由来と `serverActions` 由来を区別しない
+     * 1 本のリスト。
+     *
+     * 先読みで既に配信済みのものはクライアント側で差し引く (pending の `fired` 記録と
+     * 突き合わせる)。サーバーが袋を分ける必要はない。
      */
-    serverEvents?: EventEntry[];
+    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;
@@ -50,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,7 +86,7 @@ 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() を actions に入れたままの logic では、その handler は
             // サーバー専用なので先読みの再適用対象から外す (send 時にも pending へ積んでいない)。
@@ -43,7 +98,12 @@ export function createOptimisticActionClient(config) {
             // publish されてしまう。1 件ごとに直前の確定形から作り直し、成功したものだけ採用する。
             const base = structuredClone(displayState);
             try {
-                runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {}));
+                runPredicted(action, () => handler({
+                    state: displayState,
+                    payload,
+                    playerId,
+                    ctx: { now, emit: noopEmit, ...predictedScheduleCtx(now) },
+                }));
                 i++;
             }
             catch {
@@ -54,20 +114,20 @@ export function createOptimisticActionClient(config) {
         onState(displayState, playerId);
     };
     /**
-     * 自分が出した pending action が ack されたかを判定し、events 重複排除と
-     * pending キューの掃除を行う。
+     * サーバーからの配信を処理する。
+     *
+     * 送信元が誰であれ、まず先読みの実行記録と突き合わせる。自分の ack だけを見ていると、
+     * 他プレイヤーの action が同じ出来事を起こしたときに二重実行になる。
      */
-    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);
+    const handleAck = (ack, from, 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 {
@@ -79,12 +139,29 @@ export function createOptimisticActionClient(config) {
             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({
+                        state: target,
+                        payload: payload ?? {},
+                        playerId,
+                        ctx: { now, emit: predictEmit, ...predictedScheduleCtx(now) },
+                    }));
+                    pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
                     onState(target, playerId);
                 }
                 catch {
@@ -93,8 +170,12 @@ 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 ?? [], options.serverEvents ?? []);
+            handleAck(options.ack, options.from, options.events ?? []);
             confirmedState = state;
             reapplyPendingActions();
         },
@@ -110,7 +191,7 @@ export function createOptimisticActionClient(config) {
             if (!ok)
                 return false;
             confirmedState = cloned;
-            handleAck(options.ack, options.from, options.events ?? [], options.serverEvents ?? []);
+            handleAck(options.ack, options.from, options.events ?? []);
             reapplyPendingActions();
             return true;
         },
@@ -118,11 +199,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);

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

@@ -2,31 +2,50 @@
  * optimistic-action-client.ts の unit test。
  *
  * `logic.actions` (クライアント先読み + サーバーの 2 回実行) と `logic.serverActions`
- * (サーバーのみ 1 回実行) を分離した設計が、events の重複排除と pending キューの
- * 巻き戻しの両方で正しく閉じることを検証する。
+ * (サーバーのみ 1 回実行) を分離した設計が、events の配信と pending キューの巻き戻しの
+ * 両方で正しく閉じることを検証する。
  *
- * 特に重要なのは、同名 action で両方が定義されたケース。先読みで走るのは actions 側
- * だけなので、serverActions が emit した events まで「自分の ack だから発火済み」として
- * 捨ててしまうと、サーバー側のイベントが永久に届かなくなる。
+ * events はサーバーから 1 本のリストで届き、クライアントが「先読みで自分が配信した分」を
+ * 差し引いて残りを確定として発火する。予測が当たれば二重に鳴らず、外れればサーバー側の
+ * 正しい event が追って届く。
  */
 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) => {
+import { resetServerTimeOffset } from '../server-clock.js';
+/**
+ * `serverOnly()` の brand が付いた handler。`actions` に入っていても先読みされないこと
+ * (brand 判定が効くこと) を確かめる。旧シグネチャの互換は検証対象ではない。
+ */
+const legacyServerOnly = serverOnly(({ state }) => {
     state.charged += 1000;
 });
 const makeLogic = () => ({
-    setup: () => ({ moves: 0, charged: 0 }),
+    setup: () => ({ moves: 0, charged: 0, stampedAt: 0 }),
     actions: {
-        move: (state) => {
+        move: ({ state, ctx }) => {
+            state.moves += 1;
+            state.stampedAt = ctx.now;
+            ctx.emit('moved', {});
+        },
+        // 先読みでも ctx.schedule を呼ぶ action。型にはあるので呼べてしまう。
+        startTimer: ({ state, ctx }) => {
+            state.stampedAt = ctx.schedule({
+                key: 'timer',
+                after: 60,
+                action: 'timer.fire',
+            });
+        },
+        // 予測の結果によって別の event を出す (予測ミスの再現用)
+        guess: ({ state, payload, ctx }) => {
             state.moves += 1;
+            ctx.emit(payload?.willEmit ?? 'accepted', payload?.data ?? {});
         },
         boom: () => {
             throw new Error('always fails');
         },
         // 途中まで state を書き換えてから throw する (部分ミューテーションの検証用)
-        partial: (state) => {
+        partial: ({ state }) => {
             state.moves += 1;
             throw new Error('fails after mutating');
         },
@@ -36,11 +55,12 @@ const makeLogic = () => ({
     },
     serverActions: {
         // move と同名 = 同じ action の「サーバーだけで走る続き」
-        move: (state, _payload, _playerId, _emit, ctx) => {
+        move: ({ state, ctx }) => {
             state.charged += ctx.tick;
+            ctx.emit('charged', {});
         },
         // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
-        notifyExternal: (state) => {
+        notifyExternal: ({ state }) => {
             state.charged += 100;
         },
     },
@@ -49,6 +69,8 @@ const makeLogic = () => ({
 /** 直近の onState 通知。tsconfig の lib が Array#at 未対応なので添字で取る。 */
 const latest = (states) => states[states.length - 1];
 const setup = () => {
+    // サーバー時刻オフセットは module 単位で共有されるので、テスト間で持ち越さない。
+    resetServerTimeOffset();
     const sent = [];
     const fired = [];
     const states = [];
@@ -57,12 +79,42 @@ const setup = () => {
         playerId: 'me',
         onState: (s) => states.push(structuredClone(s)),
         events: {
-            moved: () => fired.push('moved'),
-            charged: () => fired.push('charged'),
+            // predict: true = 先読み時点で実行する
+            moved: {
+                predict: true,
+                handler: (d) => {
+                    fired.push(`moved${d.n ?? ''}`);
+                },
+            },
+            accepted: {
+                predict: true,
+                handler: () => {
+                    fired.push('accepted');
+                },
+            },
+            tooLate: {
+                predict: true,
+                handler: () => {
+                    fired.push('tooLate');
+                },
+            },
+            // predict: false = サーバー確定後だけ実行する
+            charged: {
+                predict: false,
+                handler: () => {
+                    fired.push('charged');
+                },
+            },
+            fanfare: {
+                predict: false,
+                handler: () => {
+                    fired.push('fanfare');
+                },
+            },
         },
         sendAction: ({ action, seq }) => sent.push({ action, seq }),
     });
-    client.reset({ moves: 0, charged: 0 });
+    client.reset({ moves: 0, charged: 0, stampedAt: 0 });
     return { client, sent, fired, states };
 };
 describe('createOptimisticActionClient', () => {
@@ -71,7 +123,7 @@ describe('createOptimisticActionClient', () => {
         it('actions の handler は送信時に先行実行される', () => {
             const { client, sent, states } = setup();
             client.send('move');
-            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
             expect(sent).toEqual([{ action: 'move', seq: 1 }]);
         });
         /**
@@ -81,7 +133,7 @@ describe('createOptimisticActionClient', () => {
         it('serverActions にしか無い action は先行実行されない', () => {
             const { client, sent, states } = setup();
             client.send('notifyExternal');
-            expect(latest(states)).toEqual({ moves: 0, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 0, charged: 0 });
             expect(sent).toEqual([{ action: 'notifyExternal', seq: 1 }]);
         });
         /**
@@ -91,46 +143,140 @@ describe('createOptimisticActionClient', () => {
         it('同名で両方ある場合、先読みは actions 側だけ', () => {
             const { client, states } = setup();
             client.send('move');
-            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
         });
     });
-    describe('events の重複排除', () => {
+    describe('events の配信', () => {
         /**
-         * 自分が出した action の ack では、actions 由来の events は先読み時に発火済みなので
-         * skip する。二重発火すると効果音が 2 回鳴るなどの不具合になる。
+         * 予測が当たった場合、確定時に再発火しない。二重に鳴ると効果音が 2 回鳴る。
+         * 先読みで 1 回だけ (predicted: true) 発火していること。
          */
-        it('自分の ack では actions 由来の events を発火しない', () => {
+        it('予測が当たったら確定時に再発火しない', () => {
             const { client, fired } = setup();
-            client.send('move');
-            client.applyState({ moves: 1, charged: 0 }, { ack: 1, from: 'me', events: [{ name: 'moved', data: {} }] });
-            expect(fired).toEqual([]);
+            client.send('move'); // 先読みで moved が発火
+            expect(fired).toEqual(['moved']);
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'moved', data: {} }] });
+            expect(fired).toEqual(['moved']);
         });
         /**
-         * serverActions 由来の events は先読みで走っていないので、自分の ack でも必ず発火する。
-         * ここを events と同じ配列で送ると重複排除に巻き込まれて永久に届かなくなる。
+         * IMPORTANT: 予測が外れた場合、サーバー側の正しい event が確定として発火する。
+         *
+         * 旧実装は「自分の ack なら actions 由来の events を全部 skip」していたため、
+         * 別の分岐を通っていると正しい event が永久に届かなかった。
          */
-        it('自分の ack でも serverEvents は発火する', () => {
+        it('予測が外れたらサーバー側の event が確定として発火する', () => {
             const { client, fired } = setup();
-            client.send('move');
-            client.applyState({ moves: 1, charged: 5 }, {
+            client.send('guess', { willEmit: 'accepted' }); // 先読みでは accepted
+            expect(fired).toEqual(['accepted']);
+            // サーバーは tooLate だった
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'tooLate', data: {} }] });
+            expect(fired).toEqual(['accepted', 'tooLate']);
+        });
+        /**
+         * serverActions 由来の events は先読みで走っていないので確定として発火する。
+         * サーバーは events を 1 本で送るが、クライアントが自分の発火記録を差し引くので
+         * 袋を分ける必要がない (旧 serverEvents は廃止)。
+         */
+        it('先読みしていない event は 1 本のリストからでも発火する', () => {
+            const { client, fired } = setup();
+            client.send('move'); // 先読みで moved のみ
+            client.applyState({ moves: 1, charged: 5, stampedAt: 0 }, {
                 ack: 1,
                 from: 'me',
-                events: [{ name: 'moved', data: {} }],
-                serverEvents: [{ name: 'charged', data: {} }],
+                // actions 由来 (moved) と serverActions 由来 (charged) が同じ配列で届く
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'charged', data: {} },
+                ],
             });
-            expect(fired).toEqual(['charged']);
+            expect(fired).toEqual(['moved', 'charged']);
         });
-        /** 他プレイヤーの action なら先読みしていないので、両方とも発火する。 */
-        it('他プレイヤーの ack では両方発火する', () => {
+        /** 他プレイヤーの action なら先読みしていないので全部確定として発火する。 */
+        it('他プレイヤーの ack では全部確定として発火する', () => {
             const { client, fired } = setup();
-            client.applyState({ moves: 1, charged: 5 }, {
+            client.applyState({ moves: 1, charged: 5, stampedAt: 0 }, {
                 ack: 1,
                 from: 'other',
-                events: [{ name: 'moved', data: {} }],
-                serverEvents: [{ name: 'charged', data: {} }],
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'charged', data: {} },
+                ],
             });
             expect(fired).toEqual(['moved', 'charged']);
         });
+        /** predict: false の event は先読みで実行されず、確定時に 1 回だけ実行される。 */
+        it('predict: false の event は確定時にだけ実行される', () => {
+            const { client, fired } = setup();
+            client.send('guess', { willEmit: 'fanfare' });
+            expect(fired).toEqual([]);
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'fanfare', data: {} }] });
+            expect(fired).toEqual(['fanfare']);
+        });
+        /**
+         * IMPORTANT: 他プレイヤーの action が同じ出来事を起こしても二重実行しない。
+         *
+         * A と B が同時に同じ行送りを撃つと、サーバーは先着の A だけを通し、B の分は
+         * 握り潰す。 B から見て届くのは「A の action の ack」なので、記録を自分の pending に
+         * 紐づけていると引き当てられず、先読みで実行済みなのにもう一度実行してしまう。
+         * (e2e/prediction-misfire.mjs で実測した回帰)
+         */
+        it('他プレイヤー由来の配信でも先読み済みなら二重実行しない', () => {
+            const { client, fired } = setup();
+            // 自分も撃った (先読みで moved1 を実行)
+            client.send('guess', { willEmit: 'moved', data: { n: 1 } });
+            expect(fired).toEqual(['moved1']);
+            // 先に着いた他プレイヤーの action が同じ出来事を起こして配信されてくる
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
+            expect(fired).toEqual(['moved1']);
+        });
+        /**
+         * IMPORTANT: 予測が外れた記録は「その action が ack された時点」で捨てる。
+         *
+         * 「未確定の action が全部無くなったら捨てる」だけだと、別の action が未確定な間
+         * ずっと外れた記録が生き残り、その後に本当に起きた同名イベントを 1 回握り潰す。
+         * (レビュー指摘の再現)
+         */
+        it('別の action が未確定でも、外れた記録はその ack で捨てる', () => {
+            const { client, fired } = setup();
+            client.send('guess', { willEmit: 'moved', data: { n: 1 } }); // seq 1: 先読みで実行
+            client.send('move'); // seq 2: まだ未確定のまま残す
+            expect(fired).toEqual(['moved1', 'moved']);
+            // seq 1 の ack。サーバーは moved1 を出さなかった = 予測が外れた
+            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [] });
+            // seq 2 が未確定でも、seq 1 の記録は捨てられている
+            // → 他プレイヤー由来の本物の moved1 は実行されるべき
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
+            expect(fired).toEqual(['moved1', 'moved', 'moved1']);
+        });
+        /**
+         * 予測が外れて実際には起きなかった出来事の記録は、その action の ack で破棄する。
+         * 残したままだと、次に本当にその出来事が起きたときに実行されなくなる。
+         */
+        it('外れた記録は ack で破棄する', () => {
+            const { client, fired } = setup();
+            client.send('guess', { willEmit: 'moved', data: { n: 1 } });
+            expect(fired).toEqual(['moved1']);
+            // 自分の ack。サーバーは何も起こさなかった (予測が外れた)
+            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [] });
+            expect(fired).toEqual(['moved1']);
+            // 後から本当に起きた同じ出来事は、記録が消えているので実行される
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 100, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
+            expect(fired).toEqual(['moved1', 'moved1']);
+        });
+        /** 同じ event が 2 回来たら、先読み 1 回分だけを差し引く (多重集合の差)。 */
+        it('同じ event が複数回でも先読み分だけ差し引く', () => {
+            const { client, fired } = setup();
+            client.send('move'); // 先読みで moved 1 回
+            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, {
+                ack: 1,
+                from: 'me',
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'moved', data: {} },
+                ],
+            });
+            expect(fired).toEqual(['moved', 'moved']);
+        });
     });
     describe('pending キューと巻き戻し', () => {
         /**
@@ -142,19 +288,19 @@ describe('createOptimisticActionClient', () => {
             client.send('move'); // seq 1
             client.send('move'); // seq 2
             // seq 1 だけ確定。charged はサーバー側で加算済みの値が入っている
-            client.applyState({ moves: 1, charged: 7 }, { ack: 1, from: 'me' });
+            client.applyState({ moves: 1, charged: 7, stampedAt: 0 }, { ack: 1, from: 'me' });
             // 確定 (moves:1) + 未 ack の seq 2 を再適用 = moves:2、charged はサーバー値のまま
-            expect(latest(states)).toEqual({ moves: 2, charged: 7 });
+            expect(latest(states)).toMatchObject({ 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 });
+            expect(latest(states)).toMatchObject({ moves: 2, charged: 0 });
             client.rollback(1);
             // seq 1 が消えて seq 2 だけ再適用される
-            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
         });
         /** 先行実行で throw した action は pending に積まれず、送信だけ行われる。 */
         it('先行実行が throw した action は pending に積まれない', () => {
@@ -162,23 +308,25 @@ describe('createOptimisticActionClient', () => {
             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 });
+            client.applyState({ moves: 9, charged: 9, stampedAt: 0 }, {});
+            expect(latest(states)).toMatchObject({ moves: 9, charged: 9 });
         });
     });
     describe('applyDelta', () => {
-        /** delta 経路でも serverEvents の扱いは applyState と揃っている。 */
-        it('自分の ack でも serverEvents を発火する', () => {
+        /** delta 経路でも events の差し引きは applyState と揃っている。 */
+        it('先読み済みを差し引いた残りだけを発火する', () => {
             const { client, fired } = setup();
-            client.send('move');
+            client.send('move'); // 先読みで moved
             const ok = client.applyDelta([{ op: 'replace', path: '/charged', value: 3 }], {
                 ack: 1,
                 from: 'me',
-                events: [{ name: 'moved', data: {} }],
-                serverEvents: [{ name: 'charged', data: {} }],
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'charged', data: {} },
+                ],
             });
             expect(ok).toBe(true);
-            expect(fired).toEqual(['charged']);
+            expect(fired).toEqual(['moved', 'charged']);
         });
         /** patch が当たらないときは events を発火せず false を返す (transport がフル state を再要求する)。 */
         it('patch 適用に失敗したら events を発火せず false を返す', () => {
@@ -186,7 +334,6 @@ describe('createOptimisticActionClient', () => {
             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([]);
@@ -202,7 +349,7 @@ describe('createOptimisticActionClient', () => {
             const { client, sent, states } = setup();
             client.send('legacy');
             // state は動かず、送信だけ行われる
-            expect(latest(states)).toEqual({ moves: 0, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 0, charged: 0 });
             expect(sent).toEqual([{ action: 'legacy', seq: 1 }]);
         });
         /** 再適用でも同じ。pending に積まれていても brand 付きなら実行しない。 */
@@ -210,9 +357,9 @@ describe('createOptimisticActionClient', () => {
             const { client, states } = setup();
             client.send('move'); // seq 1 (pending へ)
             client.send('legacy'); // seq 2 (pending へは積まれない)
-            client.applyState({ moves: 0, charged: 0 }, {});
+            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, {});
             // 確定 state に move だけが再適用され、legacy の +1000 は入らない
-            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
         });
         /**
          * 再適用中に handler が途中まで state を変更してから throw した場合、その部分変更を
@@ -225,8 +372,84 @@ describe('createOptimisticActionClient', () => {
             // 送信時点で 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 });
+            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, {});
+            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
+        });
+    });
+    /**
+     * ctx.now の配布。
+     *
+     * actions はクライアント先読みとサーバーで 2 回走るため、handler の中で Date.now() を
+     * 読むと端末の時計ズレがそのまま state に入る。ctx.now はサーバーとのクロック
+     * オフセットで補正した推定値を配ることでこれを防ぐ。
+     */
+    describe('ctx.now', () => {
+        /** オフセット未取得なら素のローカル時刻。オフラインでも壊れないこと。 */
+        it('サーバー時刻を観測する前はローカル時刻が入る', () => {
+            const { client, states } = setup();
+            const before = Date.now();
+            client.send('move');
+            expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
+            expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
+        });
+        /**
+         * 端末の時計が大きくズレていても、サーバー時刻の観測でオフセットが補正される。
+         * ここでは「サーバーが 1 時間先」を観測させ、ctx.now がそちらへ寄ることを見る。
+         */
+        it('サーバー時刻を観測するとオフセット分ずれた値が入る', () => {
+            const { client, states } = setup();
+            const ONE_HOUR = 3600 * 1000;
+            client.observeServerTime(Date.now() + ONE_HOUR);
+            client.send('move');
+            const stamped = latest(states).stampedAt;
+            // 1 時間先へ寄っている (テスト実行のブレを考慮して幅を持たせる)
+            expect(stamped).toBeGreaterThan(Date.now() + ONE_HOUR - 5000);
+            expect(stamped).toBeLessThan(Date.now() + ONE_HOUR + 5000);
+        });
+        /** 数値でない / 欠けている場合は無視する (serverTime を持たないメッセージ用)。 */
+        it('不正な観測値は無視される', () => {
+            const { client, states } = setup();
+            client.observeServerTime(undefined);
+            client.observeServerTime(Number.NaN);
+            const before = Date.now();
+            client.send('move');
+            expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
+            expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
+        });
+        /**
+         * IMPORTANT: 型に schedule があるので、先読みされる action からも呼べてしまう。
+         * 実体を渡していないと `ctx.schedule is not a function` で先読みが丸ごと落ちる。
+         *
+         * 予約自体はサーバーだけが持つので先読みでは何もしないが、戻り値 (絶対時刻) は
+         * 返す必要がある。シナリオはそれを表示用の endsAt として state に入れるため、
+         * undefined を返すと先読み中だけタイマーが消える。
+         */
+        it('先読みでも ctx.schedule が呼べて絶対時刻を返す', () => {
+            const { client, states, sent } = setup();
+            client.send('startTimer');
+            // 先読みが落ちていたら pending に積まれず state も変わらない
+            expect(sent).toEqual([{ action: 'startTimer', seq: 1 }]);
+            const stamped = latest(states).stampedAt;
+            expect(stamped).toBeGreaterThanOrEqual(Date.now() + 60000 - 5000);
+            expect(stamped).toBeLessThanOrEqual(Date.now() + 60000 + 5000);
+        });
+        /**
+         * IMPORTANT: 再適用 (reconciliation でのやり直し) では初回予測時の now を使い回す。
+         *
+         * 取り直すと、サーバーから ack が来るたびに handler が別の時刻で走り、
+         * timerEndsAt のような値が毎回ズレて秒読みがガタつく。
+         */
+        it('再適用でも初回予測時の now を使い回す', () => {
+            const { client, states } = setup();
+            client.send('move');
+            const firstStamp = latest(states).stampedAt;
+            // 再適用の直前にオフセットを大きく動かす。now を取り直す実装ならここで
+            // stampedAt が 1 時間ジャンプするので、使い回しているかを確実に判別できる。
+            client.observeServerTime(Date.now() + 3600 * 1000);
+            // 別プレイヤーの ack を受けて再適用させる (自分の pending は残る)
+            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other' });
+            expect(latest(states).moves).toBe(1);
+            expect(latest(states).stampedAt).toBe(firstStamp);
         });
     });
 });

package/dist/run/server-action.js

@@ -74,6 +74,9 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
         }
         const msgType = parsed.type;
         console.log(`[SDK ServerAction] ⬅ recv type=${msgType}`);
+        // サーバーは全ブロードキャストに実時刻を載せる。どのメッセージでもオフセットを
+        // 更新できるので、tick が回っている限り追加の往復は要らない。
+        client.observeServerTime(parsed.serverTime);
         if (msgType === '__room_init') {
             // サーバー (relay-room / sync-room / game-room) はいずれも接続 URL の playerId
             // クエリをそのまま `myId` として echo する。つまり parsed.myId は常に引数 playerId と
@@ -123,10 +126,9 @@ 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, serverEvents: serverEvts });
+            client.applyState(parsed.state, { ack, from, events: evts });
             return;
         }
         // ─── Action 結果 (差分パッチ) ────────────────────────
@@ -134,7 +136,6 @@ 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();
@@ -144,7 +145,6 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
                 ack,
                 from,
                 events: evts,
-                serverEvents: serverEvts,
             });
             if (!ok) {
                 requestFullState();

package/dist/server-clock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ *
+ * サーバー時刻の推定値をクライアント全体へ配る。
+ *
+ * state に入っている `endsAt` のような絶対時刻はサーバーの時計で打たれている。
+ * それを端末の `Date.now()` と引き算すると、端末の時計ズレがそのまま表示のズレになる
+ * (残り時間が恒久的に狂う / 期限判定がサーバーと食い違う)。読み取り側も同じ時計に
+ * 揃えるための関数。
+ *
+ * ```ts
+ * const remain = Math.ceil((state.game.timerEndsAt - serverNow()) / 1000);
+ * ```
+ *
+ * オフセットは transport がサーバーからのメッセージを受けるたびに更新する。
+ * 未接続 / 未観測ならローカル時刻をそのまま返す (オフラインでも壊れない)。
+ */
+/** transport から呼ぶ内部関数。サーバーが打刻した時刻を観測してオフセットを更新する。 */
+export declare function observeServerTime(serverTime: number | undefined): void;
+/**
+ * サーバー時刻の推定値 (ms)。
+ *
+ * カウントダウン描画のように毎秒/毎フレーム呼ぶ用途を想定しているので、
+ * state の到着とは無関係にいつでも呼べる。
+ */
+export declare function serverNow(): number;
+/** ソロモードなど「自分自身がサーバー」の経路で使う。 */
+export declare function resetServerTimeOffset(): void;

package/dist/server-clock.js

@@ -0,0 +1,40 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ *
+ * サーバー時刻の推定値をクライアント全体へ配る。
+ *
+ * state に入っている `endsAt` のような絶対時刻はサーバーの時計で打たれている。
+ * それを端末の `Date.now()` と引き算すると、端末の時計ズレがそのまま表示のズレになる
+ * (残り時間が恒久的に狂う / 期限判定がサーバーと食い違う)。読み取り側も同じ時計に
+ * 揃えるための関数。
+ *
+ * ```ts
+ * const remain = Math.ceil((state.game.timerEndsAt - serverNow()) / 1000);
+ * ```
+ *
+ * オフセットは transport がサーバーからのメッセージを受けるたびに更新する。
+ * 未接続 / 未観測ならローカル時刻をそのまま返す (オフラインでも壊れない)。
+ */
+let offset = 0;
+/** transport から呼ぶ内部関数。サーバーが打刻した時刻を観測してオフセットを更新する。 */
+export function observeServerTime(serverTime) {
+    if (typeof serverTime !== 'number' || !Number.isFinite(serverTime))
+        return;
+    // 下り片道遅延を無視するので推定は実サーバー時刻より僅かに遅れる。
+    // 表示用途では無視できる誤差なので、精度より単純さを取る。
+    offset = serverTime - Date.now();
+}
+/**
+ * サーバー時刻の推定値 (ms)。
+ *
+ * カウントダウン描画のように毎秒/毎フレーム呼ぶ用途を想定しているので、
+ * state の到着とは無関係にいつでも呼べる。
+ */
+export function serverNow() {
+    return Date.now() + offset;
+}
+/** ソロモードなど「自分自身がサーバー」の経路で使う。 */
+export function resetServerTimeOffset() {
+    offset = 0;
+}

package/dist/types.d.ts

@@ -56,6 +56,24 @@ export interface PlayersChangedMessage {
     players: Record<string, PlayerVoiceState>;
 }
 export type Emit = (eventName: string, data?: Record<string, unknown>) => void;
+/**
+ * events handler。
+ *
+ * `emit(name, data)` の `data` をそのまま受け取る。先読み中か確定後かは渡さない
+ * (どちらで呼ばれても同じ処理をする前提。 `predict` で宣言済みなので分岐の必要がない)。
+ */
+export type EventHandler = (data: Record<string, unknown>) => void;
+/**
+ * events の購読宣言。
+ *
+ * 先読みは外れることがあり、実行してしまったものは取り消せない。取り消せない副作用
+ * (analytics / 実績解除 / 長い演出) は必ず `predict: false` にすること。
+ */
+export interface EventSubscription {
+    /** 先読み時点で実行してよいか。宣言必須。 */
+    predict: boolean;
+    handler: EventHandler;
+}
 /** dev harness で観測される 1 件の emit。`data` は `emit(name)` 省略時に空 object になる。 */
 export interface ServerEvent {
     name: string;
@@ -71,20 +89,93 @@ export interface SeededRandom {
  * 素の action handler の実行文脈。空なのは意図的。
  *
  * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
- * 再現できない値 (tick / 実時刻 / 乱数) をここで配ると、サーバー・ソロ・dev では
- * 本物が入るのにオンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
+ * 再現できない値 (tick / 乱数) をここで配ると、サーバー・ソロ・dev では本物が入るのに
+ * オンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
  * そういう値が要る処理は `serverActions` 側に書く。
  */
-export type ActionContext = Record<never, never>;
+export interface ActionContext {
+    /**
+     * サーバーで処理される時刻 (ms)。先読みではクロックオフセットからの推定値。
+     *
+     * 推定なのでサーバーとは数十 ms ずれる。時刻での分岐に使うと境界で判定が割れるので、
+     * 分岐は `update()` (サーバー専用) で行う。
+     *
+     * 同じ action を再適用しても値は変わらない (初回予測時の値を使い回す)。
+     */
+    now: number;
+    emit: Emit;
+    /** 予約はサーバーだけが持つ。先読みでは戻り値を計算するだけで、予約も取り消しもしない。 */
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
+}
+/** 予約されたタイマーの識別子付き宣言。 */
+export interface ScheduleOptions {
+    /** 予約の識別子。同じ key で予約し直すと置き換わる (古い予約が残ると二重に発火する)。 */
+    key: string;
+    /** 絶対時刻 (ms)。`after` と排他。過去なら即座に発火する。 */
+    at?: number;
+    /** 何秒後か。`at` と排他。 */
+    after?: number;
+    action: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * サーバー権威のタイマー。
+ *
+ * クライアントの時計やアプリのバックグラウンド化に依存せず、サーバーが指定時刻に
+ * 自分で起きて action を撃つ。`tickRate` で毎秒ポーリングする必要が無くなり、
+ * その間 Durable Object は hibernate できる。
+ */
+export interface Scheduler {
+    /**
+     * 予約して確定した絶対時刻 (ms) を返す。表示用の endsAt にそのまま使える。
+     *
+     * 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で「自分が予約した
+     * ものか」を state と突き合わせて弾くこと (action 名や key では区別できない)。
+     */
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
+}
+/**
+ * 予約から発火した action に渡る playerId。
+ *
+ * 送信者がいないので、人間の操作と区別するための定数。
+ * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
+ */
+export declare const SCHEDULED_ACTOR = "__scheduled";
 /** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
 export interface ServerActionContext {
     tick: number;
     random: SeededRandom;
+    /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
+    now: number;
+    emit: Emit;
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
 }
 /** @deprecated `ServerActionContext` を使う。 */
 export type ServerOnlyActionContext = ServerActionContext;
-export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ActionContext) => void;
-export type ServerActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerActionContext) => Promise<void> | void;
+/**
+ * action handler の引数。
+ *
+ * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
+ * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
+ */
+export interface ActionArgs<S> {
+    state: S;
+    payload: any;
+    playerId: string;
+    ctx: ActionContext;
+}
+export type ActionHandler<S> = (args: ActionArgs<S>) => void;
+/** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
+export interface ServerActionArgs<S> {
+    state: S;
+    payload: any;
+    playerId: string;
+    ctx: ServerActionContext;
+}
+export type ServerActionHandler<S> = (args: ServerActionArgs<S>) => Promise<void> | void;
 /** @deprecated `ServerActionHandler` を使う。 */
 export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 /**
@@ -94,6 +185,21 @@ export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 export type ServerOnlyAction<S> = ServerActionHandler<S> & {
     readonly __serverOnly: true;
 };
+/** `update()` の ctx。サーバーでしか走らないので tick / random / playerInputs を持つ。 */
+export interface UpdateContext {
+    random: SeededRandom;
+    tick: number;
+    /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
+    now: number;
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
+    emit: Emit;
+    playerInputs: Record<string, Record<string, any>>;
+}
+export interface UpdateArgs<S> {
+    state: S;
+    ctx: UpdateContext;
+}
 export interface GameLogic<S> {
     /**
      * seats には kind !== 'player' の席 (spectator / admin) も含まれる。
@@ -116,19 +222,22 @@ export interface GameLogic<S> {
      * (旧 `serverOnly()` 相当) になる。
      */
     serverActions?: Record<string, ServerActionHandler<S>>;
-    update(state: S, ctx: {
-        random: SeededRandom;
-        tick: number;
-        emit: Emit;
-        playerInputs: Record<string, Record<string, any>>;
-    }): void;
+    update(args: UpdateArgs<S>): void;
     tickRate?: number;
 }
 export interface GameConfig<S> extends ConnectionCallbacks {
     logic: GameLogic<S>;
     onState: (state: S, myPlayerId: string) => void;
     inputs: (sendAction: (type: string, payload?: any) => void) => void;
-    events?: Record<string, (data: Record<string, unknown>) => void>;
+    /**
+     * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
+     *
+     * 同じ出来事が二重に実行されないよう、SDK は「先読みで実行した記録」を持ち、
+     * サーバーから同一の event (name と data が完全一致) が届いたら実行を抑止する。
+     * したがって `data` には**クライアントとサーバーで必ず同じ値になるもの**だけを
+     * 入れること。`ctx.now` や乱数 ID を混ぜると一致せず二重実行になる。
+     */
+    events?: Record<string, EventSubscription>;
     playerCount: number;
     /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
     orientation?: 'portrait' | 'landscape';

package/dist/types.js

@@ -1,3 +1,10 @@
+/**
+ * 予約から発火した action に渡る playerId。
+ *
+ * 送信者がいないので、人間の操作と区別するための定数。
+ * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
+ */
+export const SCHEDULED_ACTOR = '__scheduled';
 /** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
 export const SERVER_TIME = '__SERVER_TIME__';
 /** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */

package/package.json

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