@uzuhq/code-sdk 0.8.7 → 0.8.9

package/README.md

@@ -296,6 +296,24 @@ changeRoom(null); // デフォルトルーム（全員が同じ音声チャン
 - 初期状態ではすべてのプレイヤーがデフォルトルーム（`null`）に所属する
 - `roomId` に文字列を指定すると、そのプレイヤーは指定ルームへ移動する
 
+### `finishGame(): void`
+
+ゲームを終えて、この端末のプレイ画面を閉じる。ホストはイベントを終了扱いにし、呼んだプレイヤーを退出させる。
+
+```ts
+import { finishGame } from '@uzuhq/code-sdk';
+
+onState(state) {
+  if (state.debriefClosed) finishGame();
+}
+```
+
+- 結果や感想戦を見終えて閉じるときに呼ぶ。勝敗が決まった瞬間 (`gameover` など) に呼ぶと、結果を見る前に画面が閉じる
+- 途中退出は UZU メニューの「退出」が担うので、ゲーム内の exit / quit ボタンには使わない
+- 閉じるのは呼んだ端末だけ。全員を閉じたいときは、終了を表す state を全員へ配り、各端末で呼ぶ
+- 再描画のたびに呼んでもよい (ホストは処理中の 2 回目以降を無視する)
+- 対応していない古いアプリや `uzu dev` では何も起きないので、呼んだあとも画面を操作不能にしない
+
 ### `onPlayersChanged(handler: (players: Record<string, PlayerVoiceState>) => void): void`
 
 プレイヤーのリアルタイム状態（音声状態）が変化したときのハンドラを登録する。

package/dist/index.d.ts

@@ -232,6 +232,27 @@ declare function firstFrameReady(): void;
  * ```
  */
 declare function gameReady(): void;
+/**
+ * ゲームを終えてプレイ画面を閉じるよう Flutter ホストに通知する。
+ *
+ * 閉じるのは**呼んだ端末だけ**。全員を閉じたいときは、終了を表す state を全員へ配り、
+ * 各端末の `onState` から呼ぶ。ホストはイベントを終了扱いにし (finishedAt を立てるのは
+ * 最初の 1 人だけ)、呼んだプレイヤーを退出させてから画面を閉じる。
+ *
+ * 呼び出しタイミング: 結果や感想戦を見終えて閉じるときなど、シナリオとしてゲームが完全に
+ * 終わった瞬間。勝敗が決まった瞬間 (`gameover` など) に呼ぶと、結果を見る前に画面が閉じる。
+ *
+ * 対応していない古いアプリや `uzu dev` harness では何も起きない。呼んだあとも画面を
+ * 操作不能にしないこと。
+ *
+ * @example
+ * ```ts
+ * onState(state) {
+ *   if (state.debriefClosed) finishGame();
+ * }
+ * ```
+ */
+declare function finishGame(): void;
 /** Flutter からの playersChanged メッセージを受信するハンドラを登録する。 */
 declare function onPlayersChanged(handler: PlayersChangedHandler): void;
 /**
@@ -245,4 +266,4 @@ declare function onPlayersChanged(handler: PlayersChangedHandler): void;
  */
 declare function run<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = Record<never, never>>(config: GameConfig<S, A, SA>): void;
 //#endregion
-export { type ActionArgs, type ActionContext, type ActionHandler, type ActionMap, type BridgeChannel, type BridgeMessage, type ConnectionCallbacks, type ConnectionState, DEFAULT_ICON_URLS, type Deadline, type DeadlineArgs, type DeadlineContext, type DevHooksCtx, type Duration, type Emit, type EventHandler, type EventSubscription, GAME_START, type GameConfig, type GameLogic, type GameTime, type Insets, type JsonMergePatch, type JsonPatchOp, type Operation, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, type RunHandle, type Seat, type SeatKind, type SeededRandom, SeededRandomImpl, type SendAction, type ServerActionArgs, type ServerActionContext, type ServerActionHandler, type ServerActionMap, type ServerEvent, type ServerOnlyAction, type ServerOnlyActionContext, type ServerOnlyActionHandlerFn, type SetupArgs, type SetupContext, type UpdateArgs, type UpdateContext, type UzuDevHooks, type UzuInsets, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getInsets, getPredictionWarnings, init, isHosted, isPaused, isServerOnlyAction, minus, on, onInsetsChange, onPauseChange, onPlayersChanged, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub };
+export { type ActionArgs, type ActionContext, type ActionHandler, type ActionMap, type BridgeChannel, type BridgeMessage, type ConnectionCallbacks, type ConnectionState, DEFAULT_ICON_URLS, type Deadline, type DeadlineArgs, type DeadlineContext, type DevHooksCtx, type Duration, type Emit, type EventHandler, type EventSubscription, GAME_START, type GameConfig, type GameLogic, type GameTime, type Insets, type JsonMergePatch, type JsonPatchOp, type Operation, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, type RunHandle, type Seat, type SeatKind, type SeededRandom, SeededRandomImpl, type SendAction, type ServerActionArgs, type ServerActionContext, type ServerActionHandler, type ServerActionMap, type ServerEvent, type ServerOnlyAction, type ServerOnlyActionContext, type ServerOnlyActionHandlerFn, type SetupArgs, type SetupContext, type UpdateArgs, type UpdateContext, type UzuDevHooks, type UzuInsets, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, finishGame, firstFrameReady, gameReady, gameTime, getInsets, getPredictionWarnings, init, isHosted, isPaused, isServerOnlyAction, minus, on, onInsetsChange, onPauseChange, onPlayersChanged, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub };

package/dist/index.js

@@ -1301,9 +1301,43 @@ function onInsetsChange(cb) {
 	};
 }
 //#endregion
+//#region src/scenario-callback.ts
+/**
+* @docs
+* - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+*
+* SDK からシナリオのコード (描画 / イベント購読 / bridge の購読) を呼ぶときの例外境界。
+* シナリオのコールバックを呼ぶ箇所は、すべてここを通す。
+*
+* これらは state 配信やメッセージ受信のたびに同じ経路を通る。例外をそのまま上へ通すと
+* 呼び出し元の state 適用 (confirmedState 更新 / ack 処理 / seq 前進) が途中で止まり、
+* 以降の配信でも同じ経路で投げ続ける。WebSocket もホストアプリも生きたまま画面だけが
+* 永久に更新されなくなる — 2026-09-09 の UZU TOKYO 公演で実際に起きた壊れ方がこれ。
+*
+* ここで断ち切れば state 適用は最後まで走り、次の配信で描画がやり直される
+* (onState は毎回フル state から再実行されるので冪等)。同じ理由で、購読が複数ある
+* ところでは 1 件の失敗を他の購読へ波及させない。
+*/
+/**
+* シナリオ側のコールバックを実行し、例外を境界で止める。
+*
+* 例外は握り潰さず `console.error` に出す。ホスト側のログ収集がこれを拾う。
+*/
+const callScenario = (label, fn) => {
+	try {
+		fn();
+	} catch (err) {
+		console.error(`[uzu] シナリオの ${label} で例外が発生しました (処理は継続します)`, err);
+	}
+};
+//#endregion
 //#region src/run/optimistic-action-client.ts
 function createOptimisticActionClient(config) {
-	const { logic, playerId, onState, events, sendAction } = config;
+	const { logic, playerId, events, sendAction } = config;
+	/** 呼び出し箇所ごとに守らず、シナリオの描画へ出る唯一の口をここで塞ぐ。 */
+	const onState = (state, id) => {
+		callScenario("描画 (onState)", () => config.onState(state, id));
+	};
 	/** サーバー確定 state (楽観的更新のベース) */
 	let confirmedState = null;
 	/** 表示用 state (pending actions 適用済み) */
@@ -1336,7 +1370,11 @@ function createOptimisticActionClient(config) {
 	/** 再適用時はイベントを発火しない (送信時に既に発火済み) */
 	const noopEmit = () => {};
 	const dispatchEvents = (evts) => {
-		for (const e of evts) events?.[e.name]?.handler(e.data);
+		for (const e of evts) {
+			const handler = events?.[e.name]?.handler;
+			if (!handler) continue;
+			callScenario(`event ハンドラ "${e.name}"`, () => handler(e.data));
+		}
 	};
 	/** events の同一性キー。name と data が一致すれば「同じ出来事」とみなす。 */
 	const eventKey = (e) => `${e.name}\u0000${JSON.stringify(e.data ?? {})}`;
@@ -1423,7 +1461,7 @@ function createOptimisticActionClient(config) {
 				const subscription = events?.[eventName];
 				if (!subscription?.predict) return;
 				const payloadData = data ?? {};
-				subscription.handler(payloadData);
+				callScenario(`event ハンドラ "${eventName}"`, () => subscription.handler(payloadData));
 				firedPredictions.push({
 					seq,
 					name: eventName,
@@ -1448,7 +1486,9 @@ function createOptimisticActionClient(config) {
 					time
 				});
 				onState(target, playerId);
-			} catch {}
+			} catch (err) {
+				console.warn(`[uzu] action "${type}" の先読み実行で例外`, err);
+			}
 			sendAction({
 				action: type,
 				payload: payload ?? {},
@@ -1552,13 +1592,7 @@ function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, se
 	config.inputs((type, payload) => {
 		client.send(type, payload);
 	});
-	ws.addEventListener("message", (ev) => {
-		let parsed;
-		try {
-			parsed = JSON.parse(ev.data);
-		} catch {
-			return;
-		}
+	const handleMessage = (parsed) => {
 		const msgType = parsed.type;
 		console.log(`[SDK ServerAction] ⬅ recv type=${msgType}`);
 		client.observeGameTime(parsed.gameTime);
@@ -1649,6 +1683,21 @@ function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, se
 			client.reset(parsed.state);
 			return;
 		}
+	};
+	ws.addEventListener("message", (ev) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(ev.data);
+		} catch {
+			return;
+		}
+		if (parsed === null || typeof parsed !== "object") return;
+		const msg = parsed;
+		try {
+			handleMessage(msg);
+		} catch (err) {
+			console.error(`[SDK ServerAction] ❌ message 処理で例外 type=${String(msg.type)}`, err);
+		}
 	});
 }
 //#endregion
@@ -1657,7 +1706,7 @@ function runLocalServerAction(config) {
 	const { logic, inputs, events } = config;
 	const onState = (next, id) => {
 		observeGameTime(gameTime());
-		config.onState(next, id, "player");
+		callScenario("描画 (onState)", () => config.onState(next, id, "player"));
 	};
 	const tickRate = logic.tickRate ?? 0;
 	const clock = new GameClock();
@@ -1744,7 +1793,11 @@ function runLocalServerAction(config) {
 		wakeupTimer = setTimeout(fireDue, Math.max(0, clock.toWall(next) - Date.now()));
 	};
 	const dispatchEvents = (evts) => {
-		for (const e of evts) events?.[e.name]?.handler(e.data);
+		for (const e of evts) {
+			const handler = events?.[e.name]?.handler;
+			if (!handler) continue;
+			callScenario(`event ハンドラ "${e.name}"`, () => handler(e.data));
+		}
 	};
 	clock.restart();
 	const setupTime = gameTime();
@@ -2022,6 +2075,29 @@ function firstFrameReady() {
 function gameReady() {
 	sendRaw("sdk", "gameReady", {});
 }
+/**
+* ゲームを終えてプレイ画面を閉じるよう Flutter ホストに通知する。
+*
+* 閉じるのは**呼んだ端末だけ**。全員を閉じたいときは、終了を表す state を全員へ配り、
+* 各端末の `onState` から呼ぶ。ホストはイベントを終了扱いにし (finishedAt を立てるのは
+* 最初の 1 人だけ)、呼んだプレイヤーを退出させてから画面を閉じる。
+*
+* 呼び出しタイミング: 結果や感想戦を見終えて閉じるときなど、シナリオとしてゲームが完全に
+* 終わった瞬間。勝敗が決まった瞬間 (`gameover` など) に呼ぶと、結果を見る前に画面が閉じる。
+*
+* 対応していない古いアプリや `uzu dev` harness では何も起きない。呼んだあとも画面を
+* 操作不能にしないこと。
+*
+* @example
+* ```ts
+* onState(state) {
+*   if (state.debriefClosed) finishGame();
+* }
+* ```
+*/
+function finishGame() {
+	sendRaw("sdk", "finishGame", {});
+}
 /** Flutter からの playersChanged メッセージを受信するハンドラを登録する。 */
 function onPlayersChanged(handler) {
 	_playersChangedHandlers.push(handler);
@@ -2118,7 +2194,7 @@ function handleMessage(msg) {
 				return;
 			case "playersChanged": {
 				const players = payload?.players ?? {};
-				_playersChangedHandlers.forEach((fn) => fn(players));
+				for (const fn of _playersChangedHandlers) callScenario("playersChanged ハンドラ", () => fn(players));
 				return;
 			}
 			case "requestPause":
@@ -2138,9 +2214,9 @@ function handleMessage(msg) {
 	if (channel === "game") {
 		const h = gameHandlers.get(type) || [];
 		console.log(`[SDK] 🔧 handleMessage game/${type} handlers=${h.length}`);
-		h.forEach((fn) => fn(payload ?? {}));
+		for (const fn of h) callScenario(`game/${type} ハンドラ`, () => fn(payload ?? {}));
 		return;
 	}
 }
 //#endregion
-export { DEFAULT_ICON_URLS, GAME_START, ReconnectableWebSocket, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getInsets, getPredictionWarnings, init, isHosted, isPaused, isServerOnlyAction, minus, on, onInsetsChange, onPauseChange, onPlayersChanged, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub };
+export { DEFAULT_ICON_URLS, GAME_START, ReconnectableWebSocket, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, finishGame, firstFrameReady, gameReady, gameTime, getInsets, getPredictionWarnings, init, isHosted, isPaused, isServerOnlyAction, minus, on, onInsetsChange, onPauseChange, onPlayersChanged, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub };

package/package.json

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