@uzuhq/code-sdk 0.3.8

package/dist/reconnectable-ws.js

@@ -0,0 +1,229 @@
+/**
+ * 自動再接続 WebSocket ラッパー
+ *
+ * - Exponential backoff + jitter 付き自動再接続
+ * - Heartbeat (__ping / __pong) による接続生存確認
+ * - 再接続中のメッセージバッファリング
+ */
+const DEFAULTS = {
+    maxReconnectAttempts: 15,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    jitterFactor: 0.5,
+    heartbeatInterval: 25000,
+    heartbeatTimeout: 10000,
+    maxBufferSize: 50,
+};
+export class ReconnectableWebSocket {
+    constructor(url, options = {}) {
+        this.ws = null;
+        this._state = 'connecting';
+        this.reconnectAttempt = 0;
+        this.messageBuffer = [];
+        this.messageHandlers = [];
+        this.heartbeatTimer = null;
+        this.heartbeatTimeoutTimer = null;
+        this.reconnectTimer = null;
+        this.disposed = false;
+        this.url = url;
+        this.opts = {
+            maxReconnectAttempts: options.maxReconnectAttempts ?? DEFAULTS.maxReconnectAttempts,
+            baseDelay: options.baseDelay ?? DEFAULTS.baseDelay,
+            maxDelay: options.maxDelay ?? DEFAULTS.maxDelay,
+            jitterFactor: options.jitterFactor ?? DEFAULTS.jitterFactor,
+            heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
+            heartbeatTimeout: options.heartbeatTimeout ?? DEFAULTS.heartbeatTimeout,
+            maxBufferSize: options.maxBufferSize ?? DEFAULTS.maxBufferSize,
+            shouldBuffer: options.shouldBuffer,
+            onConnectionStateChange: options.onConnectionStateChange,
+        };
+        this.connect();
+    }
+    // ─── Public API ──────────────────────────────────────────
+    get connectionState() {
+        return this._state;
+    }
+    /** WebSocket.readyState 互換 (既存コードとの互換用) */
+    get readyState() {
+        return this.ws?.readyState ?? WebSocket.CLOSED;
+    }
+    send(data) {
+        if (this._state === 'connected' && this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(data);
+        }
+        else if (this._state === 'reconnecting') {
+            if (this.opts.shouldBuffer && !this.opts.shouldBuffer(data))
+                return;
+            if (this.messageBuffer.length < this.opts.maxBufferSize) {
+                this.messageBuffer.push(data);
+            }
+        }
+        // disconnected / connecting: ドロップ
+    }
+    addEventListener(type, handler) {
+        if (type === 'message') {
+            this.messageHandlers.push(handler);
+        }
+    }
+    removeEventListener(type, handler) {
+        if (type === 'message') {
+            const index = this.messageHandlers.indexOf(handler);
+            if (index !== -1) {
+                this.messageHandlers.splice(index, 1);
+            }
+        }
+    }
+    /** バッファをクリア（権威的 state 受信時に呼ぶ） */
+    clearBuffer() {
+        this.messageBuffer = [];
+    }
+    /** 全リソース解放 */
+    dispose() {
+        this.disposed = true;
+        this.stopHeartbeat();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.onopen = null;
+            this.ws.onclose = null;
+            this.ws.onerror = null;
+            this.ws.onmessage = null;
+            try {
+                if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+                    this.ws.close();
+                }
+            }
+            catch (e) {
+                console.warn('[ReconnectableWS] Error closing WebSocket:', e);
+            }
+            this.ws = null;
+        }
+    }
+    // ─── Private ─────────────────────────────────────────────
+    connect() {
+        if (this.disposed)
+            return;
+        console.log(`[ReconnectableWS] 🔗 Connecting to ${this.url} (attempt=${this.reconnectAttempt})`);
+        const ws = new WebSocket(this.url);
+        ws.onopen = () => {
+            if (this.disposed)
+                return;
+            console.log(`[ReconnectableWS] ✅ Connected`);
+            this.reconnectAttempt = 0;
+            this.setState('connected');
+            this.startHeartbeat();
+            this.flushBuffer();
+        };
+        ws.onclose = (ev) => {
+            if (this.disposed)
+                return;
+            // 正常終了 (1000) の場合はリコネクトしない
+            if (ev.code === 1000) {
+                console.log(`[ReconnectableWS] 🔒 Closed cleanly (code=${ev.code})`);
+                return;
+            }
+            console.log(`[ReconnectableWS] ❌ Closed (code=${ev.code} reason=${ev.reason})`);
+            this.stopHeartbeat();
+            this.scheduleReconnect();
+        };
+        ws.onerror = () => {
+            if (this.disposed)
+                return;
+            console.log(`[ReconnectableWS] ⚠️ Error`);
+            // onclose が後続で発火するため、ここではリコネクトをトリガーしない
+        };
+        ws.onmessage = (ev) => {
+            if (this.disposed)
+                return;
+            const data = ev.data;
+            // Heartbeat pong のフィルタリング
+            if (data === '__pong') {
+                this.handlePong();
+                return;
+            }
+            // 通常メッセージをハンドラに配信
+            for (const handler of this.messageHandlers) {
+                handler(ev);
+            }
+        };
+        this.ws = ws;
+    }
+    setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        console.log(`[ReconnectableWS] 📡 State: ${state}`);
+        this.opts.onConnectionStateChange?.(state);
+    }
+    scheduleReconnect() {
+        if (this.disposed)
+            return;
+        if (this.reconnectAttempt >= this.opts.maxReconnectAttempts) {
+            console.log(`[ReconnectableWS] 🚫 Max reconnect attempts reached (${this.opts.maxReconnectAttempts})`);
+            this.setState('disconnected');
+            return;
+        }
+        this.setState('reconnecting');
+        const delay = this.getReconnectDelay();
+        console.log(`[ReconnectableWS] ⏳ Reconnecting in ${Math.round(delay)}ms (attempt=${this.reconnectAttempt + 1})`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectAttempt++;
+            this.connect();
+        }, delay);
+    }
+    getReconnectDelay() {
+        const { baseDelay, maxDelay, jitterFactor } = this.opts;
+        const exponentialDelay = Math.min(baseDelay * Math.pow(2, this.reconnectAttempt), maxDelay);
+        const jitter = exponentialDelay * jitterFactor * (Math.random() * 2 - 1);
+        return Math.max(0, exponentialDelay + jitter);
+    }
+    flushBuffer() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        const buffer = this.messageBuffer;
+        this.messageBuffer = [];
+        for (const data of buffer) {
+            try {
+                this.ws.send(data);
+            }
+            catch (e) {
+                console.warn(`[ReconnectableWS] ⚠️ Failed to flush buffered message:`, e);
+            }
+        }
+        if (buffer.length > 0) {
+            console.log(`[ReconnectableWS] 📤 Flushed ${buffer.length} buffered messages`);
+        }
+    }
+    // ─── Heartbeat ───────────────────────────────────────────
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send('__ping');
+                this.heartbeatTimeoutTimer = setTimeout(() => {
+                    console.log(`[ReconnectableWS] 💔 Heartbeat timeout`);
+                    // 強制切断 → onclose がリコネクトをトリガー
+                    this.ws?.close(4001, 'heartbeat_timeout');
+                }, this.opts.heartbeatTimeout);
+            }
+        }, this.opts.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+    }
+    handlePong() {
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+    }
+}

package/dist/room.d.ts

@@ -0,0 +1,23 @@
+type RoomMessageHandler = (data: Record<string, unknown>) => void;
+/** WebSocket 互換の send/addEventListener インターフェース */
+interface WebSocketLike {
+    send(data: string): void;
+    addEventListener(type: 'message', handler: (ev: MessageEvent) => void): void;
+}
+/** Room の公開インターフェース。WebSocket / BroadcastChannel どちらでも実装可能。 */
+export interface RoomLike {
+    readonly myId: string;
+    broadcast(msg: Record<string, unknown>): void;
+    send(id: string, msg: Record<string, unknown>): void;
+    on(type: string, handler: RoomMessageHandler): void;
+}
+export declare class Room implements RoomLike {
+    readonly myId: string;
+    private ws;
+    private handlers;
+    constructor(ws: WebSocketLike, myId: string);
+    broadcast(msg: Record<string, unknown>): void;
+    send(id: string, msg: Record<string, unknown>): void;
+    on(type: string, handler: RoomMessageHandler): void;
+}
+export {};

package/dist/room.js

@@ -0,0 +1,36 @@
+export class Room {
+    constructor(ws, myId) {
+        this.handlers = new Map();
+        this.ws = ws;
+        this.myId = myId;
+        this.ws.addEventListener('message', (ev) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(ev.data);
+            }
+            catch {
+                return;
+            }
+            const type = parsed.type;
+            if (!type)
+                return;
+            const from = parsed.__from;
+            console.log(`[SDK Room] ⬅ recv type=${type} from=${from}`, JSON.stringify(parsed));
+            const handlers = this.handlers.get(type) || [];
+            handlers.forEach((h) => h({ ...parsed, __from: from }));
+        });
+    }
+    broadcast(msg) {
+        console.log(`[SDK Room] ➡ broadcast type=${msg.type}`, JSON.stringify(msg));
+        this.ws.send(JSON.stringify(msg));
+    }
+    send(id, msg) {
+        console.log(`[SDK Room] ➡ send to=${id} type=${msg.type}`, JSON.stringify(msg));
+        this.ws.send(JSON.stringify({ ...msg, __to: id }));
+    }
+    on(type, handler) {
+        if (!this.handlers.has(type))
+            this.handlers.set(type, []);
+        this.handlers.get(type).push(handler);
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
+ * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
+ *
+ * ブラウザ内 LocalGameRoom — GameRoom DO の動作をサーバーレスで再現する。
+ * server_url がない場合に vite dev だけで ServerAction シナリオをローカル実行する。
+ *
+ * online (`runOnlineServerAction`) と挙動を揃えるため、standard handler は同期で実行し
+ * `sendAction()` 直後に `onState()` を同期発火する (楽観的更新だけで完結する仕様)。
+ * serverOnly handler のみ `await` で非同期実行し、完了後に `onState()` を呼ぶ。
+ */
+import type { GameConfig } from '../types.js';
+import type { RunHandle } from '../dev-hooks.js';
+export declare function runLocalServerAction<S>(config: GameConfig<S>): RunHandle<S>;

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

@@ -0,0 +1,97 @@
+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, onState, inputs, events } = config;
+    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],
+        kind: 'player',
+    }));
+    const myId = players[0].id;
+    // イベント収集→一括配信（DO と同じパターン）
+    const dispatchEvents = (evts) => {
+        for (const e of evts) {
+            events?.[e.name]?.(e.data);
+        }
+    };
+    // setRawState で全置換できるよう let。closures は名前参照なので最新束縛を読む。
+    let state = logic.setup(players, random);
+    let tick = 0;
+    const playerInputs = {};
+    // Action 処理。standard handler は同期実行で `sendAction()` 直後の同期 onState を
+    // 保証する (online の楽観的更新と同じ挙動)。serverOnly handler は `Promise<void>`
+    // を返しうるので `await` で実行し、完了後に events と onState を発火する。
+    // どちらも 1 回しか実行しない (online の「楽観 → サーバー確定」の 2 段階は再現しない)。
+    const dispatchAction = (type, payload) => {
+        const handler = logic.actions[type];
+        if (!handler)
+            return;
+        const actionEvents = [];
+        const actionEmit = (name, data) => actionEvents.push({ name, data: data ?? {} });
+        if (isServerOnlyAction(handler)) {
+            void (async () => {
+                try {
+                    await handler(state, payload ?? {}, myId, actionEmit, { tick });
+                }
+                catch (err) {
+                    console.warn('[SDK LocalServerAction] Action error:', err);
+                    return;
+                }
+                dispatchEvents(actionEvents);
+                onState(state, myId);
+            })();
+            return;
+        }
+        try {
+            handler(state, payload ?? {}, myId, actionEmit, { tick });
+        }
+        catch (err) {
+            console.warn('[SDK LocalServerAction] Action error:', err);
+            return;
+        }
+        dispatchEvents(actionEvents);
+        onState(state, myId);
+    };
+    inputs(dispatchAction);
+    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, { random, tick, emit: tickEmit, playerInputs });
+            }
+            catch (err) {
+                console.error(`[SDK LocalServerAction] tick error at tick=${tick}:`, err);
+                tick++;
+                return;
+            }
+            tick++;
+            dispatchEvents(tickEvents);
+            onState(state, myId);
+        }, 1000 / tickRate);
+    }
+    return {
+        getRawState: () => state,
+        setRawState: async (next) => {
+            state = next;
+            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/optimistic-action-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
+ * - 開発パターン: docs/docs/play_screen_v3/sdk-guide/patterns.md
+ *
+ * ServerAction の楽観的更新クライアント — online / emulator 共通ロジック。
+ *
+ * トランスポート (WebSocket / BroadcastChannel) と上位ロジック (楽観更新 / pending
+ * キュー / ack ベースの確定 / rollback) を分離し、3 モードで挙動が揃うことを実装で保証する。
+ *
+ * - `send(type, payload)`: standard handler は同期で先行実行し pending キューへ。
+ *   serverOnly handler は skip して transport にだけ送る。
+ * - `applyState(state, { ack, from, events })`: フル state を受信した時に呼ぶ。
+ * - `applyDelta(patches, { ack, from, events })`: JSON Patch を受信した時に呼ぶ
+ *   (適用失敗時は false を返すので transport 側でフル state を再要求する)。
+ * - `rollback(seq)`: `__action_error` 受信時に該当 action を pending から除去して再適用。
+ * - `reset(state)`: 再接続後の state 復元用 (pending を全クリア)。
+ */
+import type { GameLogic } 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。自分の pending と一致した時だけ events を skip する */
+    from?: string;
+    /** サーバー (or 仮想サーバー) が dispatch した events */
+    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>;
+    /** 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;
+    /** 仮想サーバー / 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>;

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

@@ -0,0 +1,119 @@
+import { applyPatch } from '../json-patch.js';
+import { isServerOnlyAction } from '../server-only.js';
+export function createOptimisticActionClient(config) {
+    const { logic, playerId, onState, events, sendAction } = config;
+    /** サーバー確定 state (楽観的更新のベース) */
+    let confirmedState = null;
+    /** 表示用 state (pending actions 適用済み) */
+    let displayState = null;
+    /** クライアント側の action 通番 */
+    let actionSeq = 0;
+    /** 送信済みだがサーバー未確認の action キュー */
+    const pendingActions = [];
+    const emit = (eventName, data) => {
+        events?.[eventName]?.(data ?? {});
+    };
+    /** 再適用時はイベントを発火しない (送信時に既に発火済み) */
+    const noopEmit = () => { };
+    const dispatchEvents = (evts) => {
+        for (const e of evts) {
+            events?.[e.name]?.(e.data);
+        }
+    };
+    /**
+     * confirmedState をベースに pending actions を再適用して displayState を更新する。
+     * 再適用失敗した action はキューから除去する。
+     */
+    const reapplyPendingActions = () => {
+        if (confirmedState === null)
+            return;
+        displayState = structuredClone(confirmedState);
+        let i = 0;
+        while (i < pendingActions.length) {
+            const { action, payload } = pendingActions[i];
+            const handler = logic.actions[action];
+            if (!handler) {
+                pendingActions.splice(i, 1);
+                continue;
+            }
+            try {
+                // tick はサーバー側でのみ正確に管理される。再適用ではサーバー tick が不明のため 0 を使う。
+                handler(displayState, payload, playerId, noopEmit, { tick: 0 });
+                i++;
+            }
+            catch {
+                pendingActions.splice(i, 1);
+            }
+        }
+        onState(displayState, playerId);
+    };
+    /**
+     * 自分が出した pending action が ack されたかを判定し、events 重複排除と
+     * pending キューの掃除を行う。
+     */
+    const handleAck = (ack, from, evts) => {
+        const isMyAck = from === playerId && ack !== undefined && pendingActions.some((p) => p.seq === ack);
+        if (!isMyAck) {
+            dispatchEvents(evts);
+        }
+        if (from === playerId && ack !== undefined) {
+            while (pendingActions.length > 0 && pendingActions[0].seq <= ack) {
+                pendingActions.shift();
+            }
+        }
+    };
+    return {
+        send(type, payload) {
+            actionSeq++;
+            const seq = actionSeq;
+            // serverOnly handler は先行実行を skip。pending にも積まないので、ack 受信時の
+            // isMyAck 判定で false となり、サーバー発の events が普通に emit される。
+            const handler = logic.actions[type];
+            if (handler && !isServerOnlyAction(handler) && displayState !== null) {
+                try {
+                    handler(displayState, payload ?? {}, playerId, emit, { tick: 0 });
+                    pendingActions.push({ seq, action: type, payload: payload ?? {} });
+                    onState(displayState, playerId);
+                }
+                catch {
+                    // ローカル実行失敗 → 楽観的更新せずサーバーに送るだけ
+                }
+            }
+            sendAction({ action: type, payload: payload ?? {}, seq });
+        },
+        applyState(state, options = {}) {
+            handleAck(options.ack, options.from, options.events ?? []);
+            confirmedState = state;
+            reapplyPendingActions();
+        },
+        applyDelta(patches, options = {}) {
+            if (confirmedState === null)
+                return false;
+            // patch の適用可否を確定してから events 発火と pending 掃除を行う。適用失敗時は
+            // events を発火せず false を返し、transport 側でフル state を再要求する。これにより
+            // 「delta を適用できない (seq gap / patch 失敗) なら events を発火せずフル state を
+            // 要求する」という挙動が両経路で揃う (seq gap は transport 側で早期 return)。
+            const cloned = structuredClone(confirmedState);
+            const ok = applyPatch(cloned, patches);
+            if (!ok)
+                return false;
+            confirmedState = cloned;
+            handleAck(options.ack, options.from, options.events ?? []);
+            reapplyPendingActions();
+            return true;
+        },
+        rollback(seq) {
+            const idx = pendingActions.findIndex((p) => p.seq === seq);
+            if (idx !== -1) {
+                pendingActions.splice(idx, 1);
+                reapplyPendingActions();
+            }
+        },
+        reset(state) {
+            pendingActions.length = 0;
+            confirmedState = state;
+            displayState = structuredClone(state);
+            onState(displayState, playerId);
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/play_screen_v3/connection-method/arch3-authority.md
+ * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
+ *
+ * ServerAction モードのオンライン接続 (WebSocket トランスポート)。
+ *
+ * ホスト/ゲストの区別なし。全クライアントがサーバーに対して同じ立場で action を送信し、
+ * サーバーが reducer を実行して state を遷移させる。
+ *
+ * 楽観的更新ロジック (pending actions / reapply / ack 重複排除) は
+ * `optimistic-action-client.ts` に集約。本ファイルは WebSocket 固有の責務
+ * (接続管理 / メッセージ振り分け / delta seq の連続性チェック / フル state 再要求) のみ持つ。
+ */
+import type { GameConfig, Seat } from '../types.js';
+export declare function runOnlineServerAction<S>(config: GameConfig<S>, gameEndpoint: string, roomId: string, seatId: string, seats: Seat[]): void;