@uzuhq/code-sdk 0.3.8

package/dist/dev-state-patch.test.js

@@ -0,0 +1,333 @@
+/**
+ * `dev-state-patch.ts` の単体テスト。
+ *
+ * カバー対象:
+ * - applyJsonMergePatch: undefined / null / 再帰 merge / array atomic replace /
+ *   array に object patch を当てる際の throw / target が array の入口でも throw
+ * - applyJsonPatch: add / remove / replace / move / copy / test の 6 op、
+ *   JSON Pointer のエスケープ (~0 / ~1)、array index と `-` (append)、
+ *   存在しない path や不正な op の throw、root (`''`) replace
+ */
+import { describe, expect, it } from 'vitest';
+import { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
+function makeState() {
+    return {
+        game: { currentPhaseId: 'phase_a', timerEndsAt: 1000 },
+        players: {
+            p1: { ready: false, name: 'Alice' },
+            p2: { ready: false, name: 'Bob' },
+        },
+        scenario: { id: 'scenario_1' },
+        tags: ['initial'],
+        board: [
+            [0, 0, 0],
+            [0, 0, 0],
+            [0, 0, 0],
+        ],
+    };
+}
+describe('applyJsonMergePatch (RFC 7396 風)', () => {
+    it('既存 nested フィールドだけを上書きし他のフィールドを保持する', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            game: { timerEndsAt: null },
+        });
+        expect(state.game.timerEndsAt).toBeNull();
+        expect(state.game.currentPhaseId).toBe('phase_a');
+    });
+    it('深い path への object patch を recursive merge する', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            players: { p1: { ready: true } },
+        });
+        expect(state.players.p1.ready).toBe(true);
+        expect(state.players.p1.name).toBe('Alice');
+        expect(state.players.p2.ready).toBe(false);
+    });
+    it('undefined は no-op で何もしない', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            game: { currentPhaseId: undefined },
+        });
+        expect(state.game.currentPhaseId).toBe('phase_a');
+    });
+    it('null は明示的に null をセットする (RFC 7396 strict と異なる、deletion はしない)', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            scenario: null,
+        });
+        expect(state.scenario).toBeNull();
+        // 削除ではないので key は残る
+        expect('scenario' in state).toBe(true);
+    });
+    it('array は要素 merge せずまるごと overwrite する (RFC 7396 spec)', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            tags: ['new1', 'new2'],
+        });
+        expect(state.tags).toEqual(['new1', 'new2']);
+    });
+    it('object → primitive へ型が変わるパスは overwrite する', () => {
+        const state = makeState();
+        applyJsonMergePatch(state, {
+            game: 'replaced',
+        });
+        expect(state.game).toBe('replaced');
+    });
+    it('array field に non-array object patch を当てると throw する', () => {
+        const state = makeState();
+        expect(() => applyJsonMergePatch(state, {
+            board: { 1: { 4: 99 } },
+        })).toThrow(/refusing to merge a plain object into array field/);
+        // throw 後に array が dict 化していないことも確認
+        expect(Array.isArray(state.board)).toBe(true);
+    });
+    it('array field を別の array で atomic replace するのは OK', () => {
+        const state = makeState();
+        const next = [
+            [1, 1, 1],
+            [2, 2, 2],
+            [3, 3, 3],
+        ];
+        applyJsonMergePatch(state, {
+            board: next,
+        });
+        expect(state.board).toEqual(next);
+    });
+    it('target が array (直接呼び出し) でも throw する', () => {
+        const arr = [1, 2, 3];
+        expect(() => applyJsonMergePatch(arr, { 0: 99 })).toThrow(/cannot deep-merge into an array field/);
+    });
+});
+describe('applyJsonPatch (RFC 6902)', () => {
+    describe('replace', () => {
+        it('object フィールドを replace する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'replace', path: '/game/currentPhaseId', value: 'phase_b' },
+            ]);
+            expect(state.game.currentPhaseId).toBe('phase_b');
+        });
+        it('array 要素単体を replace する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'replace', path: '/board/1/1', value: 99 },
+            ]);
+            expect(state.board[1][1]).toBe(99);
+            // 他の cell は破壊されない
+            expect(state.board[0]).toEqual([0, 0, 0]);
+            expect(state.board[1][0]).toBe(0);
+            expect(Array.isArray(state.board)).toBe(true);
+            expect(Array.isArray(state.board[1])).toBe(true);
+        });
+        it('存在しない object key を replace すると throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: '/missing', value: 1 },
+            ])).toThrow(/cannot replace non-existent path/);
+        });
+        it('array の range 外 index を replace すると throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: '/tags/5', value: 'x' },
+            ])).toThrow(/out of range/);
+        });
+    });
+    describe('add', () => {
+        it('object に新しい key を add する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'add', path: '/players/p3', value: { ready: true, name: 'Charlie' } },
+            ]);
+            expect(state.players.p3).toEqual({ ready: true, name: 'Charlie' });
+        });
+        it('array に index 指定で insert する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'add', path: '/tags/0', value: 'first' },
+            ]);
+            expect(state.tags).toEqual(['first', 'initial']);
+        });
+        it('array に `-` で append する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'add', path: '/tags/-', value: 'last' },
+            ]);
+            expect(state.tags).toEqual(['initial', 'last']);
+        });
+        it('既存 object key を add すると replace と同じく上書きする', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'add', path: '/game/currentPhaseId', value: 'phase_z' },
+            ]);
+            expect(state.game.currentPhaseId).toBe('phase_z');
+        });
+    });
+    describe('remove', () => {
+        it('object key を remove する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'remove', path: '/players/p1' },
+            ]);
+            expect(state.players.p1).toBeUndefined();
+            expect(state.players.p2).toBeDefined();
+        });
+        it('array element を remove する', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'add', path: '/tags/-', value: 'extra' },
+                { op: 'remove', path: '/tags/0' },
+            ]);
+            expect(state.tags).toEqual(['extra']);
+        });
+        it('存在しない path の remove は throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'remove', path: '/players/missing' },
+            ])).toThrow(/cannot remove non-existent path/);
+        });
+        it('root 自体の remove は throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [{ op: 'remove', path: '' }])).toThrow(/cannot remove the root document/);
+        });
+    });
+    describe('move / copy', () => {
+        it('move は from から path へ値を移し from は消える', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'move', from: '/players/p1', path: '/players/p3' },
+            ]);
+            expect(state.players.p1).toBeUndefined();
+            expect(state.players.p3).toEqual({ ready: false, name: 'Alice' });
+        });
+        it('move で from と path が同じなら no-op', () => {
+            const state = makeState();
+            const before = JSON.stringify(state);
+            applyJsonPatch(state, [
+                { op: 'move', from: '/players/p1', path: '/players/p1' },
+            ]);
+            expect(JSON.stringify(state)).toBe(before);
+        });
+        it('move で from が path の真の prefix だと throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'move', from: '/game', path: '/game/nested' },
+            ])).toThrow(/cannot move into own descendant/);
+        });
+        it('copy は from の値を deep clone して path に置く (参照共有なし)', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'copy', from: '/players/p1', path: '/players/p3' },
+            ]);
+            expect(state.players.p3).toEqual(state.players.p1);
+            // 別参照なので p3 を変えても p1 は変わらない
+            state.players.p3.name = 'Charlie';
+            expect(state.players.p1.name).toBe('Alice');
+        });
+    });
+    describe('test', () => {
+        it('値が一致すれば no-op', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'test', path: '/game/currentPhaseId', value: 'phase_a' },
+                { op: 'replace', path: '/game/currentPhaseId', value: 'phase_b' },
+            ]);
+            expect(state.game.currentPhaseId).toBe('phase_b');
+        });
+        it('値が異なれば throw し以降の op は実行されない', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'test', path: '/game/currentPhaseId', value: 'phase_x' },
+                { op: 'replace', path: '/game/currentPhaseId', value: 'phase_b' },
+            ])).toThrow(/test failed/);
+            expect(state.game.currentPhaseId).toBe('phase_a');
+        });
+        it('test は deep equality でチェックする (object / array)', () => {
+            const state = makeState();
+            applyJsonPatch(state, [
+                { op: 'test', path: '/tags', value: ['initial'] },
+            ]);
+            expect(() => applyJsonPatch(state, [
+                { op: 'test', path: '/tags', value: ['other'] },
+            ])).toThrow(/test failed/);
+        });
+    });
+    describe('JSON Pointer (RFC 6901)', () => {
+        it('~1 は `/` にエスケープされる', () => {
+            const state = { 'a/b': { c: 1 } };
+            applyJsonPatch(state, [{ op: 'replace', path: '/a~1b/c', value: 2 }]);
+            expect(state['a/b'].c).toBe(2);
+        });
+        it('~0 は `~` にエスケープされる', () => {
+            const state = { 'a~b': 1 };
+            applyJsonPatch(state, [{ op: 'replace', path: '/a~0b', value: 2 }]);
+            expect(state['a~b']).toBe(2);
+        });
+        it('複合エスケープ ~01 は `~1` に戻る (~1 と取り違えない)', () => {
+            const state = { '~1': 1 };
+            applyJsonPatch(state, [{ op: 'replace', path: '/~01', value: 2 }]);
+            expect(state['~1']).toBe(2);
+        });
+        it('先頭が `/` でない pointer は throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: 'game/currentPhaseId', value: 'phase_b' },
+            ])).toThrow(/must start with "\/"/);
+        });
+        it('array 内に `-` を `replace` で渡すと throw (RFC 6902: append は add のみ)', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: '/tags/-', value: 'x' },
+            ])).toThrow(/array append.*only valid for `add`/);
+        });
+        it('array index は先頭 0 を許容しない (RFC 6901)', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: '/tags/01', value: 'x' },
+            ])).toThrow(/invalid array index/);
+        });
+    });
+    describe('root (`""`)', () => {
+        it('replace で doc を丸ごと差し替える (in-place)', () => {
+            const state = makeState();
+            const ref = state;
+            applyJsonPatch(ref, [
+                {
+                    op: 'replace',
+                    path: '',
+                    value: { onlyKey: 'kept' },
+                },
+            ]);
+            expect(Object.keys(ref)).toEqual(['onlyKey']);
+            expect(ref.onlyKey).toBe('kept');
+        });
+        it('root を primitive で replace するのは throw', () => {
+            const state = makeState();
+            expect(() => applyJsonPatch(state, [
+                { op: 'replace', path: '', value: 42 },
+            ])).toThrow(/root replace requires a plain object/);
+        });
+    });
+    it('複数 op を順番に適用する (使用例: 将棋の王の移動)', () => {
+        const state = {
+            board: [
+                [1, 0, 0],
+                [0, 0, 0],
+                [0, 0, 0],
+            ],
+            currentTurn: 'dev_0',
+        };
+        applyJsonPatch(state, [
+            { op: 'replace', path: '/board/0/0', value: 0 },
+            { op: 'replace', path: '/board/2/2', value: 1 },
+            { op: 'replace', path: '/currentTurn', value: 'dev_1' },
+        ]);
+        expect(state.board).toEqual([
+            [0, 0, 0],
+            [0, 0, 0],
+            [0, 0, 1],
+        ]);
+        expect(state.currentTurn).toBe('dev_1');
+        expect(Array.isArray(state.board)).toBe(true);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @docs
+ * - SDK仕様: docs/docs/play_screen_v3/play-screen-sdk.md
+ * - ブリッジ仕様: docs/docs/play_screen_v3/bridge.md
+ * - Relay仕様: docs/docs/play_screen_v3/relay.md
+ * - SyncRoom仕様: docs/docs/play_screen_v3/sync-room.md
+ * - ゲーム仕様: docs/docs/play_screen_v3/games.md
+ * - システム全体像: docs/docs/play_screen_v3/overview.md
+ * - AI用APIリファレンス (README): javascript/play_screen_v3/uzuhq-sdk/README.md
+ *
+ * SDK は runtime のみ。 dev harness の DOM 描画 (iframe grid / HUD / state
+ * inspector) と in-memory サーバー (Node ws による GameRoom / SyncRoom / RelayRoom) は
+ * `@uzuhq/code-cli` の `uzu dev` サブコマンドに統合されている。 parent frame で
+ * `init()` / `run()` / `sync()` を呼んでも何もしない (= noop)。 harness を立てるには
+ * 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, ActionHandler, ServerOnlyAction, ServerOnlyActionHandlerFn, } from './types.js';
+export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
+export { serverOnly, isServerOnlyAction } from './server-only.js';
+export { Room } from './room.js';
+export type { RoomLike } from './room.js';
+export { ReconnectableWebSocket } from './reconnectable-ws.js';
+export type { ReconnectableWSOptions } from './reconnectable-ws.js';
+export { SeededRandomImpl } from './random.js';
+export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
+export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
+export { attachDevHooks, createDevHooks } from './dev-hooks.js';
+export type { UzuDevHooks, DevHooksCtx, RunHandle, SyncHandle } from './dev-hooks.js';
+import type { BridgeMessage, GameConfig, SyncConfig, PlayerVoiceState } from './types.js';
+import type { RoomLike } from './room.js';
+type GameMessageHandler = (payload: Record<string, unknown>) => void;
+type PlayersChangedHandler = (players: Record<string, PlayerVoiceState>) => void;
+declare global {
+    interface Window {
+        __ps?: {
+            onMessage: (msg: BridgeMessage) => void;
+        };
+        FlutterHost?: {
+            postMessage: (message: string) => void;
+        };
+    }
+}
+export declare const isHosted: boolean;
+export declare function getRoom(): RoomLike | null;
+export declare function onRoom(callback: (room: RoomLike) => void): void;
+export declare function init(opts?: {
+    wsEndpoint?: string;
+    syncEndpoint?: string;
+    playerCount?: number;
+    orientation?: 'portrait' | 'landscape';
+    /**
+     * Dev harness の iframe inner viewport 短辺 (CSS px) の下限。default 360。
+     * harness 側で参照される値で、 SDK runtime 本体は使わない。
+     */
+    devMinIframeShortEdge?: number;
+}): void;
+/** game channel でカスタムメッセージを送信する。 native コマンドには使用不可。 */
+export declare function send(type: string, payload?: Record<string, unknown>): void;
+/** game channel のカスタムメッセージを受信する。 */
+export declare function on(type: string, handler: GameMessageHandler): void;
+export declare function playSound(sound: string): void;
+export declare function playBgm(sound: string): void;
+export declare function stopBgm(): void;
+export declare function setMicEnabled(enabled: boolean): void;
+export declare function changeRoom(roomId: string | null): void;
+/**
+ * splash 描画完了を Flutter ホストに通知する。
+ *
+ * YouTube Playables の `firstFrameReady()` 相当。 Flutter は受信時に splash overlay を
+ * 非表示にし WebView を可視化する。 **呼ばないと splash が出っぱなしになる**。
+ *
+ * 呼び出しタイミング: scenario が最初の絵 (splash / loading 画面) を画面に描いた直後。
+ * paint commit を保証するため `requestAnimationFrame` を 1 段挟むのが定石。
+ *
+ * @example
+ * ```ts
+ * init();
+ * drawSplash();
+ * requestAnimationFrame(() => firstFrameReady());
+ * ```
+ */
+export declare function firstFrameReady(): void;
+/**
+ * ユーザー操作受付可能を Flutter ホストに通知する。
+ *
+ * YouTube Playables の `gameReady()` 相当。 Flutter は受信時に入力受付を開始し、TTI
+ * (Time To Interactive) 計測を終了する。 将来の広告タイマー / leaderboard / analytics
+ * の発火点としても使われる予定。
+ *
+ * 呼び出しタイミング: asset load 完了、 ゲーム本体の setup 完了、 入力受付可能になった直後。
+ *
+ * @example
+ * ```ts
+ * await loadAssets();
+ * setupGame();
+ * gameReady();
+ * ```
+ */
+export declare function gameReady(): void;
+/** Flutter からの playersChanged メッセージを受信するハンドラを登録する。 */
+export declare function onPlayersChanged(handler: PlayersChangedHandler): void;
+export declare function run<S>(config: GameConfig<S>): void;
+export declare function sync<S>(config: SyncConfig<S>): void;