@uzuhq/code-sdk 0.7.6 → 0.7.7

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

@@ -1,217 +0,0 @@
-import { DEFAULT_ICON_URLS } from '../types.js';
-import { SeededRandomImpl } from '../random.js';
-import { isServerOnlyAction } from '../server-only.js';
-import { applyJsonMergePatch, applyJsonPatch } from '../dev-state-patch.js';
-export function runLocalServerAction(config) {
-    const { logic, inputs, events } = config;
-    // ソロモードは自分ひとりで観測者が存在しないので席種別は常に player。
-    const onState = (next, id) => config.onState(next, id, 'player');
-    const tickRate = logic.tickRate ?? 0; // DO と同じデフォルト(0=tickなし)
-    const seed = Math.floor(Math.random() * 0xffffffff);
-    const random = new SeededRandomImpl(seed);
-    const players = Array.from({ length: config.playerCount }, (_, i) => ({
-        id: `local_${i}`,
-        nickname: `Player ${i + 1}`,
-        iconUrl: DEFAULT_ICON_URLS[i % DEFAULT_ICON_URLS.length],
-    }));
-    const myId = players[0].id;
-    // イベント収集→一括配信（DO と同じパターン）
-    // ソロモードでは alarm の代わりに setTimeout で締切に起きる。締切は state から
-    // 導出するので、state を変えたら syncWakeup() を通すだけでよい。
-    let wakeupTimer = null;
-    let wakeupAt = null;
-    const nextDeadline = () => {
-        if (!logic.deadlines)
-            return null;
-        let earliest = null;
-        for (const [key, deadline] of Object.entries(logic.deadlines)) {
-            let at;
-            try {
-                at = deadline.at({ state });
-            }
-            catch (err) {
-                console.error(`[Deadline] ❌ ${key}.at() で例外`, err);
-                continue;
-            }
-            if (typeof at !== 'number' || !Number.isFinite(at))
-                continue;
-            if (earliest === null || at < earliest)
-                earliest = at;
-        }
-        return earliest;
-    };
-    const fireDue = () => {
-        wakeupTimer = null;
-        wakeupAt = null;
-        if (!logic.deadlines)
-            return;
-        const now = Date.now();
-        const evts = [];
-        const firedKeys = [];
-        for (const [key, deadline] of Object.entries(logic.deadlines)) {
-            // handler が emit してから throw したときに捨てられるよう、締切ごとに溜める。
-            // state を戻したのに音や演出だけ流れると、起きていない出来事が見えてしまう。
-            const pending = [];
-            let snapshot = null;
-            try {
-                const at = deadline.at({ state });
-                if (typeof at !== 'number' || !Number.isFinite(at) || at > now)
-                    continue;
-                // 期限が来たものだけ複製する。毎周撮ると締切の数だけ state の複製が走る。
-                snapshot = structuredClone(state);
-                deadline.handler({
-                    state,
-                    ctx: { now, random, emit: (name, data) => pending.push({ name, data: data ?? {} }) },
-                });
-                evts.push(...pending);
-                firedKeys.push(key);
-            }
-            catch (err) {
-                // サーバー (DO) 側と同じく、失敗した締切ぶんだけ巻き戻す。
-                if (snapshot !== null)
-                    state = snapshot;
-                console.error(`[Deadline] ❌ ${key} で例外`, err);
-            }
-        }
-        syncWakeup();
-        if (firedKeys.length === 0)
-            return;
-        console.log(`[Deadline] ⏰ ${firedKeys.length} 件発火: ${firedKeys.join(', ')}`);
-        dispatchEvents(evts);
-        onState(state, myId);
-    };
-    const syncWakeup = () => {
-        const next = nextDeadline();
-        if (next === wakeupAt)
-            return;
-        if (wakeupTimer)
-            clearTimeout(wakeupTimer);
-        wakeupTimer = null;
-        wakeupAt = next;
-        if (next === null)
-            return;
-        wakeupTimer = setTimeout(fireDue, Math.max(0, next - Date.now()));
-    };
-    // ソロモードはこのクライアント自身がサーバーなので、先読みという概念が無い。
-    // predict の値によらず、確定として 1 回だけ実行する。
-    const dispatchEvents = (evts) => {
-        for (const e of evts) {
-            events?.[e.name]?.handler(e.data);
-        }
-    };
-    // 移行期: publish 済みの logic.js は `setup({ seats })` で destructure したまま
-    // 固まっている。`players` へ寄せただけだと `seats === undefined` を受け取って
-    // throw するので、同じ配列を旧名でも渡す。`SetupArgs` に `seats` を宣言しないのは、
-    // 新規シナリオに旧名を選ばせないため。全 revision の再 publish 後に落とす。
-    const setupArgs = { players, seats: players, ctx: { random, now: Date.now() } };
-    // setRawState で全置換できるよう let。closures は名前参照なので最新束縛を読む。
-    let state = logic.setup(setupArgs);
-    let tick = 0;
-    const playerInputs = {};
-    // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する
-    // (online の楽観的更新と同じ挙動)。`serverActions` は `Promise<void>` を返しうるので
-    // `await` で実行し、完了後に events と onState を発火する。
-    // どちらも 1 回しか実行しない (online の「楽観 → サーバー確定」の 2 段階は再現しない)。
-    const dispatchAction = (type, payload) => {
-        const plain = logic.actions[type];
-        // 移行期: 旧 serverOnly() を actions に入れたままの logic も動かす。
-        const legacyServerOnly = isServerOnlyAction(plain) ? plain : null;
-        const server = logic.serverActions?.[type] ?? legacyServerOnly;
-        if (!plain && !server)
-            return;
-        // 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: payload ?? {},
-                    playerId: myId,
-                    ctx: { now, emit: plainEmit },
-                });
-            }
-            catch (err) {
-                console.warn('[SDK LocalServerAction] Action error:', err);
-                return;
-            }
-            dispatchEvents(plainEvents);
-            syncWakeup();
-            onState(state, myId);
-        }
-        if (!server)
-            return;
-        void (async () => {
-            try {
-                await server({
-                    state,
-                    payload: payload ?? {},
-                    playerId: myId,
-                    ctx: { tick, random, now, emit: serverEmit },
-                });
-            }
-            catch (err) {
-                console.warn('[SDK LocalServerAction] Action error:', err);
-                return;
-            }
-            dispatchEvents(serverEvents);
-            syncWakeup();
-            onState(state, myId);
-        })();
-    };
-    inputs(dispatchAction);
-    syncWakeup();
-    onState(state, myId);
-    // Tick ループ（tickRate > 0 の場合のみ、DO と同じ）
-    if (tickRate > 0) {
-        setInterval(() => {
-            const tickEvents = [];
-            const tickEmit = (name, data) => tickEvents.push({ name, data: data ?? {} });
-            try {
-                logic.update({
-                    state,
-                    ctx: {
-                        random,
-                        tick,
-                        now: Date.now(),
-                        emit: tickEmit,
-                        playerInputs,
-                    },
-                });
-            }
-            catch (err) {
-                console.error(`[SDK LocalServerAction] tick error at tick=${tick}:`, err);
-                tick++;
-                return;
-            }
-            tick++;
-            dispatchEvents(tickEvents);
-            syncWakeup();
-            onState(state, myId);
-        }, 1000 / tickRate);
-    }
-    return {
-        getRawState: () => state,
-        setRawState: async (next) => {
-            state = next;
-            syncWakeup();
-            onState(state, myId);
-        },
-        mergeRawState: async (patch) => {
-            applyJsonMergePatch(state, patch);
-            onState(state, myId);
-        },
-        patchRawState: async (ops) => {
-            applyJsonPatch(state, ops);
-            onState(state, myId);
-        },
-        sendAction: dispatchAction,
-    };
-}

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

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

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

@@ -1,242 +0,0 @@
-/**
- * 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 = [];
-    const seatKinds = [];
-    let send = () => { };
-    const config = {
-        logic,
-        playerCount: 1,
-        onState: (s, _myPlayerId, mySeatKind) => {
-            states.push(structuredClone(s));
-            seatKinds.push(mySeatKind);
-        },
-        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, seatKinds };
-};
-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, ctx }) => {
-                        state.moves += 1;
-                        ctx.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, ctx }) => {
-                        await tick();
-                        state.charged += 1;
-                        ctx.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, 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, ctx }) => {
-                        state.moves += 1;
-                        ctx.emit('moved');
-                    },
-                },
-                serverActions: {
-                    move: async ({ state, ctx }) => {
-                        await tick();
-                        state.charged += 1;
-                        ctx.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, ctx }) => {
-                        state.moves += 1;
-                        ctx.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: {
-                    // 検証対象は `__serverOnly` brand の判定であって、旧シグネチャの互換ではない。
-                    // handler 自体は現行の呼び出し形で書いている (旧形式の logic.js は現行テンプレでは
-                    // 動かない。公開済みゲームが無い前提で互換を切っている)。
-                    // @ts-expect-error actions に serverOnly() を入れるのは型違反だが、brand 判定を試す
-                    legacy: serverOnly(async ({ state, ctx }) => {
-                        await tick();
-                        state.charged += ctx.tick + 1;
-                        ctx.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']);
-        });
-    });
-    /**
-     * `onState` の第 3 引数は自分の席種別。roster に自分が居ないとき (観測者) に
-     * GM ビューと観戦ビューを出し分けるためのもので、他プレイヤーの席種別は渡らない。
-     */
-    describe('自分の席種別', () => {
-        /** ソロモードは自分ひとりで観測者が存在しないので、常に 'player' が渡る。 */
-        it('ソロモードでは常に player が渡る', () => {
-            const h = run(baseLogic({
-                actions: {
-                    move: ({ state }) => {
-                        state.moves += 1;
-                    },
-                },
-            }));
-            h.send('move');
-            expect(h.seatKinds.length).toBeGreaterThan(1);
-            expect(new Set(h.seatKinds)).toEqual(new Set(['player']));
-        });
-    });
-});

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

@@ -1,68 +0,0 @@
-/**
- * @docs
- * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
- * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
- *
- * ServerAction の楽観的更新クライアント — online / emulator 共通ロジック。
- *
- * トランスポート (WebSocket / BroadcastChannel) と上位ロジック (楽観更新 / pending
- * キュー / ack ベースの確定 / rollback) を分離し、3 モードで挙動が揃うことを実装で保証する。
- *
- * - `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, EventSubscription } from '../types.js';
-import type { Operation } from '../json-patch.js';
-export interface EventEntry {
-    name: string;
-    data: Record<string, unknown>;
-}
-export interface ConfirmOptions {
-    /** transport から受け取った action ack (確定された pending action の seq) */
-    ack?: number;
-    /** ack の送信元 player id */
-    from?: string;
-    /**
-     * サーバーが確定させた 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, EventSubscription>;
-    /** action を transport に流すコールバック */
-    sendAction: (msg: {
-        action: string;
-        payload: any;
-        seq: number;
-    }) => void;
-}
-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 で再要求) */
-    applyDelta(patches: Operation[], options?: ConfirmOptions): boolean;
-    /** `__action_error` 受信時に該当 action をロールバック */
-    rollback(seq: number): void;
-    /** 再接続時の state 復元 (pending を全クリア) */
-    reset(state: S): void;
-}
-export declare function createOptimisticActionClient<S>(config: OptimisticActionClientConfig<S>): OptimisticActionClient<S>;