@uzuhq/code-sdk 0.7.2 → 0.7.3

package/dist/action-types.test-d.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `run()` 経由の `inputs` でも同じ縛りが効くことの検証。
+ *
+ * `SendAction<A & SA>` は `SA` が `Record<string, …>` に落ちた瞬間
+ * `keyof` が `string` へ潰れて action 名の検査が丸ごと消える。 直接
+ * `SendAction<…>` を declare するだけの検査では踏めないので、 実際に
+ * `run()` を通す形で押さえる。
+ *
+ * 型検査だけが目的なので関数は呼ばない (`run` は window を触る)。
+ */
+export declare function _runTypeChecks(): void;

package/dist/action-types.test-d.js

@@ -0,0 +1,101 @@
+/**
+ * action 名と payload が型で縛られることの検証。
+ *
+ * 実行時の振る舞いは無いので、 tsc が通ること自体がテストになる。
+ * @ts-expect-error が「実際にエラーになる」ことも同時に確かめている
+ * (エラーが出なくなったら @ts-expect-error 自体が未使用エラーになる)。
+ *
+ * SDK は値を出さない。 logic は `satisfies` でキーを保ってから型注釈で組み立てる。
+ * 値を export すると scenario の logic.ts が SDK を実行時 import することになり、
+ * サーバー用 bundle (Workers) で解決できず落ちる。
+ */
+import { run } from './index.js';
+const actions = {
+    // payload に型を付けた handler
+    'vote.submit': ({ state, payload }) => {
+        state.count += payload.optionId.length;
+    },
+    // 注釈のない handler は payload: any のまま (段階的移行)
+    noop: ({ state }) => {
+        state.count += 1;
+    },
+};
+const serverActions = {
+    'server.only': ({ payload }) => {
+        payload.token.trim();
+    },
+};
+const _logic = {
+    setup: () => ({ count: 0 }),
+    actions,
+    serverActions,
+    update: () => { },
+};
+send('vote.submit', { optionId: 'a' });
+send('noop', { anything: 1 });
+send('noop'); // 注釈なし (any) は省略できる
+send('server.only', { token: 't' });
+// @ts-expect-error 存在しない action 名
+send('vote.submi', { optionId: 'a' });
+// @ts-expect-error payload の形違い
+send('vote.submit', { wrong: 1 });
+// @ts-expect-error payload が必須の action で省略はできない
+send('vote.submit');
+/**
+ * `run()` 経由の `inputs` でも同じ縛りが効くことの検証。
+ *
+ * `SendAction<A & SA>` は `SA` が `Record<string, …>` に落ちた瞬間
+ * `keyof` が `string` へ潰れて action 名の検査が丸ごと消える。 直接
+ * `SendAction<…>` を declare するだけの検査では踏めないので、 実際に
+ * `run()` を通す形で押さえる。
+ *
+ * 型検査だけが目的なので関数は呼ばない (`run` は window を触る)。
+ */
+export function _runTypeChecks() {
+    // serverActions を持たない logic (SA が既定値に落ちる経路)
+    run({
+        logic: { setup: () => ({ count: 0 }), actions, update: () => { } },
+        onState: () => { },
+        playerCount: 1,
+        inputs: (sendAction) => {
+            sendAction('vote.submit', { optionId: 'a' });
+            sendAction('noop');
+            // @ts-expect-error 存在しない action 名
+            sendAction('vote.submi', { optionId: 'a' });
+            // @ts-expect-error payload の形違い
+            sendAction('vote.submit', { wrong: 1 });
+        },
+    });
+    // 型引数を書かない呼び出しは A が推論されるので検査が効く
+    run({
+        logic: { setup: () => ({ count: 0 }), actions, update: () => { } },
+        onState: () => { },
+        playerCount: 1,
+        inputs: (sendAction) => {
+            sendAction('vote.submit', { optionId: 'a' });
+            // @ts-expect-error 存在しない action 名
+            sendAction('vote.submi', { optionId: 'a' });
+        },
+    });
+    // 既存シナリオの `run<State>({…})`。 A に既定値が無いと TS2558 で落ちる。
+    // 検査は効かなくなるが、 型引数を足さずに済むこと自体が後方互換の条件。
+    run({
+        logic: { setup: () => ({ count: 0 }), actions, update: () => { } },
+        onState: () => { },
+        playerCount: 1,
+        inputs: (sendAction) => {
+            sendAction('vote.submit', { optionId: 'a' });
+        },
+    });
+    // serverActions を持つ logic (SA が推論される経路)
+    run({
+        logic: { setup: () => ({ count: 0 }), actions, serverActions, update: () => { } },
+        onState: () => { },
+        playerCount: 1,
+        inputs: (sendAction) => {
+            sendAction('server.only', { token: 't' });
+            // @ts-expect-error 存在しない action 名
+            sendAction('server.onl', { token: 't' });
+        },
+    });
+}

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  * 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, ActionArgs, ActionContext, ActionHandler, ServerActionArgs, SetupArgs, SetupContext, UpdateArgs, UpdateContext, EventHandler, EventSubscription, Deadline, DeadlineArgs, DeadlineContext, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
+export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionArgs, ActionContext, ActionHandler, ServerActionArgs, SetupArgs, SetupContext, UpdateArgs, UpdateContext, EventHandler, EventSubscription, Deadline, DeadlineArgs, DeadlineContext, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, ActionMap, ServerActionMap, PayloadMap, SendAction, } from './types.js';
 export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { serverNow } from './server-clock.js';
@@ -30,7 +30,7 @@ export { attachDevHooks, createDevHooks } from './dev-hooks.js';
 export type { UzuDevHooks, DevHooksCtx, RunHandle, SyncHandle } from './dev-hooks.js';
 export { getPredictionWarnings } from './dev-prediction-traps.js';
 export type { PredictionWarning } from './dev-prediction-traps.js';
-import type { BridgeMessage, GameConfig, SyncConfig, PlayerVoiceState } from './types.js';
+import type { ActionMap, ServerActionMap, 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;
@@ -103,5 +103,14 @@ export declare function firstFrameReady(): void;
 export declare function gameReady(): void;
 /** Flutter からの playersChanged メッセージを受信するハンドラを登録する。 */
 export declare function onPlayersChanged(handler: PlayersChangedHandler): void;
-export declare function run<S>(config: GameConfig<S>): void;
+/**
+ * `A` に既定値が要る。 TypeScript は型引数の部分推論ができないので、 既定が無いと
+ * 既存の `run<State>({…})` が「2 つ必要」で落ちる。 既定を置けば型引数を書かない
+ * 呼び出しは `A` が推論されて検査が効き、 `run<State>` は従来どおり通る。
+ *
+ * `SA` の既定が `ServerActionMap<S>` (= `Record<string, …>`) だと
+ * `keyof (A & SA)` が `string` へ潰れ、action 名の検査が丸ごと消える。
+ * `serverActions` を持たない logic でもキーが残るよう空 map を既定にする。
+ */
+export declare function run<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = Record<never, never>>(config: GameConfig<S, A, SA>): void;
 export declare function sync<S>(config: SyncConfig<S>): void;

package/dist/index.js

@@ -66,7 +66,10 @@ function attachDevHooksIfNotHosted() {
     attachDevHooks(ctx);
 }
 // ─── Public API ─────────────────────────────────────────────
-export const isHosted = !!window.FlutterHost || window.parent !== window;
+// Node (serverActionLogic / vitest) からこの module を import しても落ちないよう
+// guard する。 トップレベルで window を読むと、 型やヘルパーを取りたいだけの
+// import でその場で ReferenceError になる。
+export const isHosted = typeof window !== 'undefined' && (!!window.FlutterHost || window.parent !== window);
 export function getRoom() {
     return _room;
 }
@@ -227,6 +230,15 @@ export function gameReady() {
 export function onPlayersChanged(handler) {
     _playersChangedHandlers.push(handler);
 }
+/**
+ * `A` に既定値が要る。 TypeScript は型引数の部分推論ができないので、 既定が無いと
+ * 既存の `run<State>({…})` が「2 つ必要」で落ちる。 既定を置けば型引数を書かない
+ * 呼び出しは `A` が推論されて検査が効き、 `run<State>` は従来どおり通る。
+ *
+ * `SA` の既定が `ServerActionMap<S>` (= `Record<string, …>`) だと
+ * `keyof (A & SA)` が `string` へ潰れ、action 名の検査が丸ごと消える。
+ * `serverActions` を持たない logic でもキーが残るよう空 map を既定にする。
+ */
 export function run(config) {
     _usesRun = true;
     const params = new URLSearchParams(window.location.search);

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

@@ -125,6 +125,12 @@ export function createOptimisticActionClient(config) {
             // 先読みするのは logic.actions だけ。serverActions は transport にだけ送り、
             // 結果は ack (state + serverEvents) で受け取る。
             const handler = logic.actions[type];
+            // どちらにも無い action は届く先が無い。 黙って捨てると UI 上は無反応なのに
+            // 原因が分からないので、 ここで気付けるようにする。 serverActions にだけある
+            // action は actions[type] が undefined でも正常なので、 両方を見る。
+            if (!handler && !logic.serverActions?.[type]) {
+                console.error(`[uzu] unknown action: "${type}". logic.actions / logic.serverActions のどちらにも登録されていません。`);
+            }
             // callback 内では displayState の narrowing が効かないので const に退避する。
             const target = displayState;
             // サーバーがこのアクションを処理する時刻の推定。再適用でも同じ値を使うので、

package/dist/types.d.ts

@@ -164,21 +164,26 @@ export type ServerOnlyActionContext = ServerActionContext;
  * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
  * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
  */
-export interface ActionArgs<S> {
+export interface ActionArgs<S, P = any> {
     state: S;
-    payload: any;
+    payload: P;
     playerId: string;
     ctx: ActionContext;
 }
-export type ActionHandler<S> = (args: ActionArgs<S>) => void;
+/**
+ * `P` は既定が `any` なので、 注釈のない handler はそのまま動く。 payload の形を
+ * 書いた handler だけが検査され、 送信側もその型で縛られる。 全部に注釈しないと
+ * 恩恵が無い、 という移行にならないようにするための既定値。
+ */
+export type ActionHandler<S, P = any> = (args: ActionArgs<S, P>) => void;
 /** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
-export interface ServerActionArgs<S> {
+export interface ServerActionArgs<S, P = any> {
     state: S;
-    payload: any;
+    payload: P;
     playerId: string;
     ctx: ServerActionContext;
 }
-export type ServerActionHandler<S> = (args: ServerActionArgs<S>) => Promise<void> | void;
+export type ServerActionHandler<S, P = any> = (args: ServerActionArgs<S, P>) => Promise<void> | void;
 /** @deprecated `ServerActionHandler` を使う。 */
 export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 /**
@@ -220,7 +225,31 @@ export interface SetupArgs {
     seats: Seat[];
     ctx: SetupContext;
 }
-export interface GameLogic<S> {
+/**
+ * `actions` の形だけを見る緩い制約。
+ *
+ * `Record<string, ActionHandler<S>>` (payload: any) を制約に使うと、 推論時に
+ * handler 型がそちらへ広げられ payload の型が取り出せなくなる。 payload を
+ * `any` のままにしてキーと引数の形だけ縛る。
+ */
+export type ActionMap<S> = Record<string, (args: ActionArgs<S, any>) => void>;
+/** `serverActions` 用。 ActionMap と同じ理由で payload は any のままにする。 */
+export type ServerActionMap<S> = Record<string, (args: ServerActionArgs<S, any>) => Promise<void> | void>;
+/** action 名から payload 型を引く表。 注釈のない handler は `any` になる。 */
+export type PayloadMap<A> = {
+    [K in keyof A]: A[K] extends (args: infer G) => any ? G extends {
+        payload: infer P;
+    } ? P : never : never;
+};
+/**
+ * `inputs` が受け取る送信関数。 action 名と payload の両方が型で縛られる。
+ *
+ * payload を一律 optional にすると、 形が必須の action でも省略が通ってしまう。
+ * payload 型が undefined を含むとき (= 注釈なしの any や明示的に optional) だけ
+ * 省略できるようにする。
+ */
+export type SendAction<A> = <K extends keyof A & string>(...args: undefined extends PayloadMap<A>[K] ? [type: K, payload?: PayloadMap<A>[K]] : [type: K, payload: PayloadMap<A>[K]]) => void;
+export interface GameLogic<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> {
     setup(args: SetupArgs): S;
     /**
      * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
@@ -229,7 +258,7 @@ export interface GameLogic<S> {
      * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
      * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
      */
-    actions: Record<string, ActionHandler<S>>;
+    actions: A;
     /**
      * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
      * 再現できない処理をここに書く。async 可。
@@ -237,7 +266,7 @@ export interface GameLogic<S> {
      * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
      * (旧 `serverOnly()` 相当) になる。
      */
-    serverActions?: Record<string, ServerActionHandler<S>>;
+    serverActions?: SA;
     update(args: UpdateArgs<S>): void;
     /**
      * state 由来の締切。サーバーが `at` の時刻に自分で起きて `handler` を呼ぶ。
@@ -248,10 +277,10 @@ export interface GameLogic<S> {
     deadlines?: Record<string, Deadline<S>>;
     tickRate?: number;
 }
-export interface GameConfig<S> extends ConnectionCallbacks {
-    logic: GameLogic<S>;
+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;
-    inputs: (sendAction: (type: string, payload?: any) => void) => void;
+    inputs: (sendAction: SendAction<A & SA>) => void;
     /**
      * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
      *

package/package.json

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