@uzuhq/code-sdk 0.4.0 → 0.6.0

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

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

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

@@ -0,0 +1,452 @@
+/**
+ * optimistic-action-client.ts の unit test。
+ *
+ * `logic.actions` (クライアント先読み + サーバーの 2 回実行) と `logic.serverActions`
+ * (サーバーのみ 1 回実行) を分離した設計が、events の配信と pending キューの巻き戻しの
+ * 両方で正しく閉じることを検証する。
+ *
+ * events はサーバーから 1 本のリストで届き、クライアントが「先読みで自分が配信した分」を
+ * 差し引いて残りを確定として発火する。予測が当たれば二重に鳴らず、外れればサーバー側の
+ * 正しい event が追って届く。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createOptimisticActionClient } from './optimistic-action-client.js';
+import { serverOnly } from '../server-only.js';
+import { resetServerTimeOffset } from '../server-clock.js';
+/** 旧 serverOnly() ブランド付き handler。actions に残っている古い logic を再現する。 */
+const legacyServerOnly = serverOnly((state) => {
+    state.charged += 1000;
+});
+const makeLogic = () => ({
+    setup: () => ({ moves: 0, charged: 0, stampedAt: 0 }),
+    actions: {
+        move: (state, _payload, _playerId, emit, ctx) => {
+            state.moves += 1;
+            state.stampedAt = ctx.now;
+            emit('moved', {});
+        },
+        // 先読みでも ctx.schedule を呼ぶ action。型にはあるので呼べてしまう。
+        startTimer: (state, _payload, _playerId, _emit, ctx) => {
+            state.stampedAt = ctx.schedule({
+                key: 'timer',
+                after: 60,
+                action: 'timer.fire',
+            });
+        },
+        // 予測の結果によって別の event を出す (予測ミスの再現用)
+        guess: (state, payload, _playerId, emit) => {
+            state.moves += 1;
+            emit(payload?.willEmit ?? 'accepted', payload?.data ?? {});
+        },
+        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;
+            emit('charged', {});
+        },
+        // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
+        notifyExternal: (state) => {
+            state.charged += 100;
+        },
+    },
+    update: () => { },
+});
+/** 直近の onState 通知。tsconfig の lib が Array#at 未対応なので添字で取る。 */
+const latest = (states) => states[states.length - 1];
+const setup = () => {
+    // サーバー時刻オフセットは module 単位で共有されるので、テスト間で持ち越さない。
+    resetServerTimeOffset();
+    const sent = [];
+    const fired = [];
+    const states = [];
+    const client = createOptimisticActionClient({
+        logic: makeLogic(),
+        playerId: 'me',
+        onState: (s) => states.push(structuredClone(s)),
+        events: {
+            // 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, stampedAt: 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)).toMatchObject({ 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)).toMatchObject({ 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)).toMatchObject({ moves: 1, charged: 0 });
+        });
+    });
+    describe('events の配信', () => {
+        /**
+         * 予測が当たった場合、確定時に再発火しない。二重に鳴ると効果音が 2 回鳴る。
+         * 先読みで 1 回だけ (predicted: true) 発火していること。
+         */
+        it('予測が当たったら確定時に再発火しない', () => {
+            const { client, fired } = setup();
+            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']);
+        });
+        /**
+         * IMPORTANT: 予測が外れた場合、サーバー側の正しい event が確定として発火する。
+         *
+         * 旧実装は「自分の ack なら actions 由来の events を全部 skip」していたため、
+         * 別の分岐を通っていると正しい event が永久に届かなかった。
+         */
+        it('予測が外れたらサーバー側の event が確定として発火する', () => {
+            const { client, fired } = setup();
+            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',
+                // actions 由来 (moved) と serverActions 由来 (charged) が同じ配列で届く
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'charged', data: {} },
+                ],
+            });
+            expect(fired).toEqual(['moved', 'charged']);
+        });
+        /** 他プレイヤーの action なら先読みしていないので全部確定として発火する。 */
+        it('他プレイヤーの ack では全部確定として発火する', () => {
+            const { client, fired } = setup();
+            client.applyState({ moves: 1, charged: 5, stampedAt: 0 }, {
+                ack: 1,
+                from: 'other',
+                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 キューと巻き戻し', () => {
+        /**
+         * 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, stampedAt: 0 }, { ack: 1, from: 'me' });
+            // 確定 (moves:1) + 未 ack の seq 2 を再適用 = moves:2、charged はサーバー値のまま
+            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)).toMatchObject({ moves: 2, charged: 0 });
+            client.rollback(1);
+            // seq 1 が消えて seq 2 だけ再適用される
+            expect(latest(states)).toMatchObject({ 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, stampedAt: 0 }, {});
+            expect(latest(states)).toMatchObject({ moves: 9, charged: 9 });
+        });
+    });
+    describe('applyDelta', () => {
+        /** delta 経路でも events の差し引きは applyState と揃っている。 */
+        it('先読み済みを差し引いた残りだけを発火する', () => {
+            const { client, fired } = setup();
+            client.send('move'); // 先読みで moved
+            const ok = client.applyDelta([{ op: 'replace', path: '/charged', value: 3 }], {
+                ack: 1,
+                from: 'me',
+                events: [
+                    { name: 'moved', data: {} },
+                    { name: 'charged', data: {} },
+                ],
+            });
+            expect(ok).toBe(true);
+            expect(fired).toEqual(['moved', '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: {} }],
+            });
+            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)).toMatchObject({ 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, stampedAt: 0 }, {});
+            // 確定 state に move だけが再適用され、legacy の +1000 は入らない
+            expect(latest(states)).toMatchObject({ 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, 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 と

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/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);
 }