@uzuhq/code-sdk 0.7.4 → 0.7.5

package/README.md

@@ -144,7 +144,7 @@ sync<GameState>({
 | キー           | 型                                                           | 必須 | 説明                         |
 | -------------- | ------------------------------------------------------------ | ---- | ---------------------------- |
 | `playerCount`  | `number`                                                     | Yes  | プレイヤー数                 |
-| `initialState` | `(seats: Seat[]) => S`                                       | Yes  | 初期 state を生成            |
+| `initialState` | `(players: Seat[]) => S`                                     | Yes  | 初期 state を生成            |
 | `onState`      | `(state: S, myPlayerId: string, serverTime: number) => void` | Yes  | state 更新時のコールバック   |
 | `inputs`       | `(patch: PatchFn, set: SetFn) => void`                       | Yes  | 入力ハンドラ登録             |
 | `events`       | `Record<string, (data: Record<string, unknown>) => void>`    | No   | ゲームイベントハンドラ       |
@@ -222,10 +222,9 @@ run({
 import type { GameLogic } from '@uzuhq/code-sdk';
 
 const logic: GameLogic<MyState> = {
-  setup({ seats, ctx }) {
+  setup({ players, ctx }) {
     // 初期 state を生成。ctx.random は SeededRandom、ctx.now はサーバーの実時刻。
-    // seats には観戦系の席 (kind: 'spectator' | 'admin') も含まれ得るため、
-    // ゲームの席は kind === 'player' に絞る
+    // players は配役を受け取る参加者だけで、観測者は含まれない
     return { players: {}, items: [] };
   },
 
@@ -260,13 +259,13 @@ const logic: GameLogic<MyState> = {
 };
 ```
 
-| キー            | 型                                       | 必須 | 説明                                                             |
-| --------------- | ---------------------------------------- | ---- | ---------------------------------------------------------------- |
-| `setup`         | `(args: SetupArgs) => S`                 | Yes  | 初期 state を生成。seats には `kind !== 'player'` の席も含まれる |
-| `actions`       | `Record<string, ActionHandler<S>>`       | Yes  | クライアント先読み + サーバーの 2 回走る。決定的であること       |
-| `serverActions` | `Record<string, ServerActionHandler<S>>` | No   | サーバーでのみ走る。async 可。`ctx` に `tick` / `random` が入る  |
-| `update`        | `(args: UpdateArgs<S>) => void`          | Yes  | 毎 tick 実行 (`tickRate` が 0 なら呼ばれない)                    |
-| `tickRate`      | `number`                                 | No   | 秒間 tick 数 (default: 0 = tick なし)                            |
+| キー            | 型                                       | 必須 | 説明                                                            |
+| --------------- | ---------------------------------------- | ---- | --------------------------------------------------------------- |
+| `setup`         | `(args: SetupArgs) => S`                 | Yes  | 初期 state を生成。`args.players` は配役を受け取る参加者だけ    |
+| `actions`       | `Record<string, ActionHandler<S>>`       | Yes  | クライアント先読み + サーバーの 2 回走る。決定的であること      |
+| `serverActions` | `Record<string, ServerActionHandler<S>>` | No   | サーバーでのみ走る。async 可。`ctx` に `tick` / `random` が入る |
+| `update`        | `(args: UpdateArgs<S>) => void`          | Yes  | 毎 tick 実行 (`tickRate` が 0 なら呼ばれない)                   |
+| `tickRate`      | `number`                                 | No   | 秒間 tick 数 (default: 0 = tick なし)                           |
 
 ハンドラの引数は 1 つのオブジェクトで、使うものだけ書けばよい。
 `state` / `payload` / `playerId` はその呼び出しの事実、`ctx` は実行環境が与えるもの。
@@ -460,22 +459,45 @@ interface BridgeMessage {
 
 ### Seat
 
-セッション参加者。ゲームの席を占める `player` のほか、観戦席 (`spectator`) と進行管理席 (`admin`、dev ハーネスのテストプレイ用) がある。
+roster に載る席。roster は配役を受け取る参加者だけで構成される。席種別は roster エントリ
+ではなく、自分の `SeatKind` として `onState` に渡る。
 
 ```ts
-type SeatKind = 'player' | 'spectator' | 'admin';
-
 interface Seat {
   id: string;
   nickname: string;
   iconUrl: string;
   /** 選択済みキャラクターの ID。未選択時は undefined */
   characterId?: string;
-  /** 席種 */
-  kind: SeatKind;
 }
 ```
 
+### SeatKind
+
+自分の席種別。ホストが iframe URL の `?seatKind=` で伝え、SDK が `onState` の第 3 引数
+として渡す。
+
+```ts
+type SeatKind = 'player' | 'spectator' | 'admin';
+```
+
+観戦席・進行管理席は roster に載らないまま接続してくる。`setup()` の `players` にも
+現れないので「player か観測者か」は `state.players` の空振りで分かるが、`spectator` と
+`admin` の区別は state から導けない。そこをこの値で分ける。
+
+```ts
+onState(state, myPlayerId, mySeatKind) {
+  const me = state.players.find((p) => p.playerId === myPlayerId);
+  if (me) return playerView(me);
+  // roster に居ない = 観測者
+  return mySeatKind === 'admin' ? gmView() : spectatorView();
+}
+```
+
+自己申告なので表示の分岐にだけ使う。渡るのは自分の席種別だけで、他プレイヤーの席種別は
+サーバー側 handler (`ActionArgs`) にも渡らない。seatId の命名規約 (`admin_0` 等) から
+判定すると、命名が変わった瞬間に静かに壊れるので避けること。
+
 ### ConnectionState
 
 ```ts

package/dist/index.js

@@ -250,9 +250,9 @@ export function run(config) {
     const origOnState = config.onState;
     const wrappedConfig = {
         ...config,
-        onState(state, myPlayerId) {
+        onState(state, myPlayerId, mySeatKind) {
             _lastStateSnap = { state, serverTime: 0, myId: myPlayerId };
-            origOnState(state, myPlayerId);
+            origOnState(state, myPlayerId, mySeatKind);
             notifyDevSnapshot(state);
         },
     };
@@ -263,8 +263,9 @@ export function run(config) {
     }
     else if (_gameEndpoint) {
         // ServerAction モード: GameRoom に接続 (本番 Cloudflare Worker DO / uzu dev の Node ws)
-        const { seatId, seats } = resolveSeatParams(params);
-        runOnlineServerAction(wrappedConfig, _gameEndpoint, roomId, seatId, seats);
+        const { seatId, players } = resolveSeatParams(params);
+        const seatKind = resolveSeatKind(params);
+        runOnlineServerAction(wrappedConfig, _gameEndpoint, roomId, seatId, players, seatKind);
     }
     else {
         throw new Error('[UZU SDK] roomId is set but ?server= is missing. ' +
@@ -294,8 +295,8 @@ export function sync(config) {
         _syncHandle = syncLocal(wrappedConfig);
     }
     else if (_syncEndpoint) {
-        const { seatId, seats } = resolveSeatParams(params);
-        const { ws } = syncOnline(wrappedConfig, _syncEndpoint, roomId, seatId, seats);
+        const { seatId, players } = resolveSeatParams(params);
+        const { ws } = syncOnline(wrappedConfig, _syncEndpoint, roomId, seatId, players);
         _syncWs = ws;
         // online sync: dev hooks は read-only (setRawState 未提供)
     }
@@ -306,6 +307,25 @@ export function sync(config) {
     attachDevHooksIfNotHosted();
 }
 // ─── Internal ───────────────────────────────────────────────
+/**
+ * 自分の席種別を URL から取り出す。
+ *
+ * `?seatKind=` はホスト (harness / emulator) が観測席の iframe に付ける。付いていない
+ * ホストからの接続は player とみなす — 本番 (mobile / uzutokyo) は player 席しか開かない。
+ *
+ * この値は iframe URL 限定で、WebSocket には出さない。play-server は roster に居ない接続を
+ * 通すだけで、その席が admin か spectator かを知る必要が無い。
+ */
+function resolveSeatKind(params) {
+    const raw = params.get('seatKind');
+    return raw === 'admin' || raw === 'spectator' ? raw : 'player';
+}
+/**
+ * 自席の ID と roster を URL から取り出す。
+ *
+ * roster (`?seats=`) に自席が居ないことは異常ではない。観測者はそもそも roster に
+ * 載らないまま接続してくる。
+ */
 function resolveSeatParams(params) {
     const seatId = params.get('seatId');
     if (!seatId) {
@@ -316,19 +336,13 @@ function resolveSeatParams(params) {
         throw new Error('[UZU SDK] seats is required. Pass ?seats=[...] in the URL.');
     }
     const raw = JSON.parse(json);
-    const seats = raw.map((p) => {
-        if (!p.kind) {
-            throw new Error(`[UZU SDK] seats entry ${p.id} is missing kind.`);
-        }
-        return {
-            id: p.id,
-            nickname: p.name,
-            iconUrl: p.iconUrl,
-            characterId: p.characterId,
-            kind: p.kind,
-        };
-    });
-    return { seatId, seats };
+    const players = raw.map((p) => ({
+        id: p.id,
+        nickname: p.name,
+        iconUrl: p.iconUrl,
+        characterId: p.characterId,
+    }));
+    return { seatId, players };
 }
 function requireEndpoint(endpoint, name) {
     if (!endpoint) {
@@ -437,10 +451,8 @@ function calcHudInsets(params) {
     const json = params.get('seats');
     if (json) {
         try {
-            // spectator / admin 席はゲームの player 数に数えない
             const raw = JSON.parse(json);
-            const playerCount = raw.filter((p) => p.kind === 'player').length;
-            actionCount = playerCount >= 2 ? 2 : 0;
+            actionCount = raw.length >= 2 ? 2 : 0;
         }
         catch {
             // パース失敗時はデフォルト値を使用

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

@@ -3,7 +3,9 @@ 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 { 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);
@@ -11,7 +13,6 @@ export function runLocalServerAction(config) {
         id: `local_${i}`,
         nickname: `Player ${i + 1}`,
         iconUrl: DEFAULT_ICON_URLS[i % DEFAULT_ICON_URLS.length],
-        kind: 'player',
     }));
     const myId = players[0].id;
     // イベント収集→一括配信（DO と同じパターン）
@@ -98,8 +99,13 @@ export function runLocalServerAction(config) {
             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({ seats: players, ctx: { random, now: Date.now() } });
+    let state = logic.setup(setupArgs);
     let tick = 0;
     const playerInputs = {};
     // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する

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

@@ -17,11 +17,15 @@ 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) => states.push(structuredClone(s)),
+        onState: (s, _myPlayerId, mySeatKind) => {
+            states.push(structuredClone(s));
+            seatKinds.push(mySeatKind);
+        },
         inputs: (sendAction) => {
             send = sendAction;
         },
@@ -41,7 +45,7 @@ const run = (logic) => {
         },
     };
     runLocalServerAction(config);
-    return { send: (t, p) => send(t, p), fired, states };
+    return { send: (t, p) => send(t, p), fired, states, seatKinds };
 };
 const baseLogic = (overrides = {}) => ({
     setup: () => ({ moves: 0, charged: 0, rolled: -1 }),
@@ -216,4 +220,23 @@ describe('runLocalServerAction', () => {
             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/server-action.d.ts

@@ -12,5 +12,5 @@
  * `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;
+import type { GameConfig, Seat, SeatKind } from '../types.js';
+export declare function runOnlineServerAction<S>(config: GameConfig<S>, gameEndpoint: string, roomId: string, seatId: string, players: Seat[], seatKind: SeatKind): void;

package/dist/run/server-action.js

@@ -1,17 +1,19 @@
 import { ReconnectableWebSocket } from '../reconnectable-ws.js';
 import { createOptimisticActionClient } from './optimistic-action-client.js';
-export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seats) {
+export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, seatKind) {
+    // `kind` は移行期の互換措置。旧 SDK / 旧 play-server が読む wire を変えないために
+    // 残す。roster は player だけになったので値は常に 'player'。
     const toWire = (p) => ({
         id: p.id,
         name: p.nickname,
         iconUrl: p.iconUrl,
         characterId: p.characterId,
-        kind: p.kind,
+        kind: 'player',
     });
     const query = new URLSearchParams({
         seatId,
         nickname: 'Player',
-        seats: JSON.stringify(seats.map(toWire)),
+        seats: JSON.stringify(players.map(toWire)),
     });
     const wsUrl = `${gameEndpoint}/${roomId}?${query}`;
     console.log(`[SDK ServerAction] 🔗 Connecting wsUrl=${wsUrl}`);
@@ -44,7 +46,9 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
     const client = createOptimisticActionClient({
         logic: config.logic,
         playerId: seatId,
-        onState: config.onState,
+        // seatKind は接続ごとに固定なのでここで束ねる。楽観更新クライアント側は
+        // 席種別を一切見ない (state の再適用にしか関心が無い)。
+        onState: (state, playerId) => config.onState(state, playerId, seatKind),
         events: config.events,
         sendAction: ({ action, payload, seq }) => {
             console.log(`[SDK ServerAction] ➡ send __action action=${action} seq=${seq}`);

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

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

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

@@ -0,0 +1,96 @@
+/**
+ * server-action.ts (オンライン接続) の unit test。
+ *
+ * 検証対象は「自分の席種別 (`seatKind`) の扱い」に絞る。楽観的更新まわりは
+ * `optimistic-action-client.test.ts` が持っている。
+ *
+ * `seatKind` は roster に載らない観測者が GM ビューと観戦ビューを出し分けるためだけの
+ * 値で、**client 内で完結する**。サーバーは roster に居ない接続を通すだけで、その席が
+ * admin か spectator かを知る必要が無い。ここではその 2 点を固定する。
+ */
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { runOnlineServerAction } from './server-action.js';
+const logic = {
+    setup: () => ({ moves: 0 }),
+    actions: {},
+    update: () => { },
+};
+const players = [
+    { id: 'p1', nickname: 'P1', iconUrl: '' },
+    { id: 'p2', nickname: 'P2', iconUrl: '' },
+];
+const stubWebSocket = () => {
+    const sockets = [];
+    class FakeWebSocket {
+        constructor(url) {
+            this.url = url;
+            this.readyState = FakeWebSocket.OPEN;
+            this.onopen = null;
+            this.onclose = null;
+            this.onerror = null;
+            this.onmessage = null;
+            sockets.push({
+                url,
+                push: (msg) => this.onmessage?.({ data: JSON.stringify(msg) }),
+            });
+            // ReconnectableWebSocket は onopen 登録後に発火する必要がある。
+            setTimeout(() => this.onopen?.(), 0);
+        }
+        send() { }
+        close() {
+            this.readyState = FakeWebSocket.CLOSED;
+        }
+    }
+    FakeWebSocket.OPEN = 1;
+    FakeWebSocket.CLOSED = 3;
+    vi.stubGlobal('WebSocket', FakeWebSocket);
+    return { sockets };
+};
+const connect = (seatKind, seatId = 'p1') => {
+    const { sockets } = stubWebSocket();
+    const onState = vi.fn();
+    const config = {
+        logic,
+        playerCount: 2,
+        onState,
+        inputs: () => { },
+    };
+    runOnlineServerAction(config, 'ws://localhost:1234/ws/games/rev1', 'room1', seatId, players, seatKind);
+    return { sockets, onState };
+};
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe('runOnlineServerAction の seatKind', () => {
+    /**
+     * `seatKind` は iframe URL 限定。WebSocket に載せると「サーバーが席種別を知っている」
+     * ように見えるが、自己申告なので何も保証しない。プロトコルを増やさない。
+     */
+    it('WebSocket URL に seatKind を載せない', () => {
+        const { sockets } = connect('admin', 'admin_0');
+        expect(sockets).toHaveLength(1);
+        const url = new URL(sockets[0].url);
+        expect(url.searchParams.get('seatKind')).toBeNull();
+        expect(url.searchParams.get('seatId')).toBe('admin_0');
+    });
+    /**
+     * roster (`?seats=`) は player 席だけ。観測者は自分が載っていない roster を送る。
+     */
+    it('roster には自分が居なくてよい', () => {
+        const { sockets } = connect('admin', 'admin_0');
+        const raw = JSON.parse(new URL(sockets[0].url).searchParams.get('seats') ?? '[]');
+        expect(raw.map((s) => s.id)).toEqual(['p1', 'p2']);
+    });
+    /** シナリオが GM ビューと観戦ビューを分けられるよう、自分の席種別だけを渡す。 */
+    it('onState の第 3 引数に自分の seatKind を渡す', () => {
+        const { sockets, onState } = connect('admin', 'admin_0');
+        sockets[0].push({ type: '__game_start', state: { moves: 0 }, seq: 0 });
+        expect(onState).toHaveBeenCalledWith({ moves: 0 }, 'admin_0', 'admin');
+    });
+    /** player 席も同じ経路で自分の席種別を受け取る。 */
+    it('player 席には player が渡る', () => {
+        const { sockets, onState } = connect('player');
+        sockets[0].push({ type: '__game_start', state: { moves: 0 }, seq: 0 });
+        expect(onState).toHaveBeenCalledWith({ moves: 0 }, 'p1', 'player');
+    });
+});

package/dist/sync/local.js

@@ -15,7 +15,6 @@ export function syncLocal(config) {
             id: `local_${i}`,
             nickname: `Player ${i + 1}`,
             iconUrl: DEFAULT_ICON_URLS[i % DEFAULT_ICON_URLS.length],
-            kind: 'player',
         });
     }
     let state = initialState(players);

package/dist/types.d.ts

@@ -31,20 +31,29 @@ export interface BridgeMessage {
     playerId?: string;
 }
 /**
- * セッションの席種。
- * - player: ゲームの参加者 (キャラクターを担当する)
- * - spectator: 観戦者 (state を閲覧するだけで、ゲームの席は占めない)
- * - admin: 進行管理席 (観戦 + GM 操作。dev harness のテストプレイ用)
+ * 自分の席種別。ホストが iframe URL の `?seatKind=` で伝える。
+ *
+ * roster に載るのは `player` だけ。観測者 (`spectator` / `admin`) は roster 外の接続として
+ * 開くので、「player か観測者か」は `state.players` の空振りで分かる。一方 **`spectator` と
+ * `admin` の区別は state から導けない**ため、この値で分ける。seatId の命名規約
+ * (`admin_0` 等) をシナリオに見せると、規約が変わった瞬間に静かに壊れる。
+ *
+ * 自己申告なので権限の根拠にはならない。表示の分岐にだけ使うこと。
  */
 export type SeatKind = 'player' | 'spectator' | 'admin';
+/**
+ * roster に載る席。
+ *
+ * roster は配役を受け取る参加者だけで構成される。観測者 (GM 席・観戦席) は roster に
+ * 載らないまま接続してくるので、シナリオは「roster に居ない = 観測者」で判別する。
+ * 席種別は roster エントリではなく自分の `SeatKind` として渡る。
+ */
 export interface Seat {
     id: string;
     nickname: string;
     iconUrl: string;
     /** ホスト（mobile / emulator）から渡される、選択済みキャラクターの ID。未選択時は undefined。 */
     characterId?: string;
-    /** 席種。 */
-    kind: SeatKind;
 }
 /** プレイヤーごとのリアルタイム状態 */
 export interface PlayerVoiceState {
@@ -218,11 +227,8 @@ export interface SetupContext {
 }
 /** `setup()` の引数。 */
 export interface SetupArgs {
-    /**
-     * seats には kind !== 'player' の席 (spectator / admin) も含まれる。
-     * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
-     */
-    seats: Seat[];
+    /** 配役を受け取る参加者。観測者は含まれない。 */
+    players: Seat[];
     ctx: SetupContext;
 }
 /**
@@ -279,7 +285,11 @@ export interface GameLogic<S, A extends ActionMap<S> = ActionMap<S>, SA extends
 }
 export interface GameConfig<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> extends ConnectionCallbacks {
     logic: GameLogic<S, A, SA>;
-    onState: (state: S, myPlayerId: string) => void;
+    /**
+     * `mySeatKind` は自分の席種別。roster に自分が居ない (= 観測者) ときに、GM ビューと
+     * 観戦ビューを出し分けるために使う。他プレイヤーの席種別は渡らない。
+     */
+    onState: (state: S, myPlayerId: string, mySeatKind: SeatKind) => void;
     inputs: (sendAction: SendAction<A & SA>) => void;
     /**
      * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
@@ -303,7 +313,7 @@ export interface GameConfig<S, A extends ActionMap<S> = ActionMap<S>, SA extends
 export type PatchFn = (ops: Operation[]) => void;
 export type SetFn = (path: string, value: unknown) => void;
 export interface SyncConfig<S = any> extends ConnectionCallbacks {
-    initialState: (seats: Seat[]) => S;
+    initialState: (players: Seat[]) => S;
     onState: (state: S, myPlayerId: string, serverTime: number) => void;
     inputs: (patch: PatchFn, set: SetFn) => void;
     events?: Record<string, (data: Record<string, unknown>) => void>;

package/package.json

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