@uzuhq/code-sdk 0.8.12 → 0.9.0

package/dist/index.js

@@ -271,6 +271,26 @@ const serverOnly = (handler) => Object.assign(handler, { __serverOnly: true });
 */
 const isServerOnlyAction = (handler) => typeof handler === "function" && "__serverOnly" in handler && handler.__serverOnly === true;
 //#endregion
+//#region ../engine-core/src/presence.ts
+/** `voicePlan` を書かない作品の既定。全員が全体の部屋、マイクは本人の自由。 */
+const DEFAULT_VOICE_PLAN = {
+	room: null,
+	mic: "free"
+};
+/** WebSocket で伝言を運ぶメッセージの type。`{ type: '__platform', message: PlatformMessage }`。 */
+const PLATFORM_WIRE_TYPE = "__platform";
+/** 伝言の type。 */
+const PLATFORM_MESSAGE_TYPE = {
+	/** サーバー → 端末: presence (`PresenceSnapshot`)。 */
+	presence: "presence",
+	/** 端末 → サーバー: 自分の通話の申告 (`VoiceReport`)。 */
+	voiceReport: "voice.report",
+	/** 端末 → サーバー: 緊急一時停止。 */
+	pauseRequest: "pause.request",
+	/** 端末 → サーバー: 緊急一時停止の解除。 */
+	pauseResume: "pause.resume"
+};
+//#endregion
 //#region src/server-clock.ts
 /**
 * @docs
@@ -329,65 +349,392 @@ const unfreezeGameTime = () => {
 	frozenAt = null;
 };
 //#endregion
-//#region src/pause-state.ts
+//#region src/scenario-callback.ts
 /**
 * @docs
-* - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
+* - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
 *
-* 緊急停止の状態を SDK 全体で 1 箇所に持つ。
+* SDK からシナリオのコード (描画 / イベント購読 / bridge の購読) を呼ぶときの例外境界。
+* シナリオのコールバックを呼ぶ箇所は、すべてここを通す。
 *
-* 停止は state ではない。シナリオの state に持ち込むと「停止中は state を変えるコードが
-* 1 行も走らない」という不変条件が崩れるので、`GameLogic` へは渡さず読み取り専用の
-* 関数として出す。用途は演出の停止 (rAF ループを止める等) に限る。
+* これらは state 配信やメッセージ受信のたびに同じ経路を通る。例外をそのまま上へ通すと
+* 呼び出し元の state 適用 (confirmedState 更新 / ack 処理 / seq 前進) が途中で止まり、
+* 以降の配信でも同じ経路で投げ続ける。WebSocket もホストアプリも生きたまま画面だけが
+* 永久に更新されなくなる — 2026-09-09 の UZU TOKYO 公演で実際に起きた壊れ方がこれ。
 *
-* ゲーム内時計の凍結もここから駆動する。停止フラグと時計の凍結が別々に動くと、
-* 「止まっているのにカウントダウンだけ進む」がいつか必ず起きる。
+* ここで断ち切れば state 適用は最後まで走り、次の配信で描画がやり直される
+* (onState は毎回フル state から再実行されるので冪等)。同じ理由で、購読が複数ある
+* ところでは 1 件の失敗を他の購読へ波及させない。
 */
-let paused = false;
-let pausedBy = null;
-const listeners$1 = /* @__PURE__ */ new Set();
-/** transport から呼ぶ内部関数。停止状態が変わったときだけ通知する。 */
-const setPauseState = (next, by) => {
-	pausedBy = next ? by : null;
-	if (next === paused) return;
-	paused = next;
-	if (paused) freezeGameTime();
-	else unfreezeGameTime();
-	for (const cb of listeners$1) try {
-		cb(paused);
+/**
+* シナリオ側のコールバックを実行し、例外を境界で止める。
+*
+* 例外は握り潰さず `console.error` に出す。ホスト側のログ収集がこれを拾う。
+*/
+const callScenario = (label, fn) => {
+	try {
+		fn();
 	} catch (err) {
-		console.warn("[uzu] onPauseChange listener threw:", err);
+		console.error(`[uzu] シナリオの ${label} で例外が発生しました (処理は継続します)`, err);
 	}
 };
-/** 緊急停止中か。 */
-const isPaused = () => {
-	return paused;
+//#endregion
+//#region src/presence.ts
+const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const OPEN_MIC = { status: "open" };
+const micOf = (value) => isRecord$2(value) && typeof value.status === "string" ? value : OPEN_MIC;
+const numberOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+const roomOf = (value) => typeof value === "string" ? value : null;
+const meConnection = (connection) => connection.status === "online" ? { status: "online" } : {
+	status: connection.status,
+	since: connection.since
+};
+const meVoice = (input) => {
+	const self = input.voice?.self;
+	if (!self) return {
+		status: "connecting",
+		since: input.startedAt
+	};
+	const since = self.since ?? input.startedAt;
+	switch (self.session) {
+		case "off": return {
+			status: "off",
+			reason: self.reason === "table" ? "table" : "this-device"
+		};
+		case "reconnecting": return {
+			status: "reconnecting",
+			since
+		};
+		case "failed": return {
+			status: "failed",
+			reason: self.reason === "mic-permission" ? "mic-permission" : "network",
+			since
+		};
+		case "connected": return {
+			status: "here",
+			room: self.room,
+			mic: micOf(self.mic),
+			speaking: self.speaking,
+			quality: self.quality
+		};
+		default: return {
+			status: "connecting",
+			since
+		};
+	}
 };
-/** 停止を要求した playerId。停止していなければ null。 */
-const getPausedBy = () => {
-	return pausedBy;
+/** アプリが聞こえていると言う相手。形が崩れていても既定の値で埋める。 */
+const heardOf = (value) => {
+	const heard = isRecord$2(value) ? value : {};
+	return {
+		status: "here",
+		mic: micOf(heard.mic),
+		speaking: heard.speaking === true,
+		quality: heard.quality === "poor" ? "poor" : "good"
+	};
 };
-/** 停止状態の変化を購読する。 */
-const onPauseChange = (cb) => {
-	listeners$1.add(cb);
+const otherVoice = (seatId, seat, me, input) => {
+	const voice = isRecord$2(seat) && isRecord$2(seat.voice) ? seat.voice : {};
+	const status = typeof voice.status === "string" ? voice.status : "unknown";
+	if (status === "lost") return {
+		status: "lost",
+		since: numberOr(voice.since, Date.now() - input.clockOffset) + input.clockOffset
+	};
+	if (me.status === "here") {
+		const heard = input.voice?.heard[seatId];
+		if (heard !== void 0) return heardOf(heard);
+		const missing = input.voice?.missing[seatId];
+		if (missing !== void 0) return {
+			status: "lost",
+			since: numberOr(isRecord$2(missing) ? missing.since : void 0, Date.now())
+		};
+	}
+	switch (status) {
+		case "off": return { status: "off" };
+		case "connected": {
+			if (me.status !== "here") return {
+				status: "unknown",
+				reason: "me-not-connected"
+			};
+			const room = roomOf(voice.room);
+			if (room !== me.room) return {
+				status: "elsewhere",
+				room
+			};
+			return {
+				status: "here",
+				mic: OPEN_MIC,
+				speaking: false,
+				quality: "good"
+			};
+		}
+		default: return {
+			status: "unknown",
+			reason: "no-report"
+		};
+	}
 };
-let requester = null;
-const setPauseRequester = (fn) => {
-	requester = fn;
+/** 3 つの入力から、シナリオに出す値を組み立てる。 */
+const buildPresence = (input) => {
+	const me = {
+		connection: meConnection(input.connection),
+		voice: meVoice(input)
+	};
+	const others = {};
+	const seats = isRecord$2(input.snapshot?.seats) ? input.snapshot.seats : {};
+	for (const [seatId, seat] of Object.entries(seats)) {
+		if (seatId === input.mySeatId) continue;
+		others[seatId] = { voice: otherVoice(seatId, seat, me.voice, input) };
+	}
+	const heardAll = isRecord$2(input.voice?.heard) ? input.voice.heard : {};
+	const speaking = Object.entries(heardAll).filter(([, heard]) => isRecord$2(heard) && heard.speaking === true).filter(([id]) => id !== input.mySeatId && !(id in seats)).map(([id, heard]) => {
+		const nickname = isRecord$2(heard) ? heard.nickname : void 0;
+		return {
+			id,
+			nickname: typeof nickname === "string" ? nickname : id
+		};
+	});
+	const observers = input.snapshot?.observers;
+	return {
+		me,
+		others,
+		observers: {
+			count: numberOr(isRecord$2(observers) ? observers.count : void 0, 0),
+			speaking
+		}
+	};
 };
-const requestPause = () => {
-	if (!requester) {
-		console.warn("[uzu] requestPause: サーバーへ接続していないので停止できません");
-		return;
+/** 前回との差分。席が初めて現れたこと自体は変化として扱わない。 */
+const diffPresence = (mySeatId, prev, next) => {
+	const changes = [];
+	const pushVoice = (seatId, before, after) => {
+		if (before && before.voice.status !== after.voice.status) changes.push({
+			kind: "voice",
+			seatId,
+			from: before.voice.status,
+			to: after.voice.status
+		});
+	};
+	if (prev.me.connection.status !== next.me.connection.status) changes.push({
+		kind: "connection",
+		seatId: mySeatId,
+		from: prev.me.connection.status,
+		to: next.me.connection.status
+	});
+	pushVoice(mySeatId, prev.me, next.me);
+	for (const [seatId, other] of Object.entries(next.others)) pushVoice(seatId, prev.others[seatId], other);
+	if (prev.observers.count !== next.observers.count) changes.push({
+		kind: "observers",
+		from: prev.observers.count,
+		to: next.observers.count
+	});
+	return changes;
+};
+const SESSIONS = [
+	"off",
+	"connecting",
+	"connected",
+	"reconnecting",
+	"failed"
+];
+/**
+* アプリから届いた `voiceChanged` を検める。形が合わなければ null。
+* 新しいアプリが項目を足しても落ちないよう、知っている項目だけを見る。
+*
+* 知らない通話の状態は connecting として受ける。アプリは SDK より先に新しくなるので、
+* 捨てると聞こえている相手 (heard) まで止まってしまう。
+*/
+const parseVoiceChanged = (payload) => {
+	const { self, heard, missing } = payload;
+	if (!isRecord$2(self) || typeof self.session !== "string") return null;
+	const session = SESSIONS.includes(self.session) ? self.session : "connecting";
+	const room = typeof self.room === "string" ? self.room : null;
+	return {
+		self: {
+			session,
+			...typeof self.reason === "string" ? { reason: self.reason } : {},
+			...typeof self.since === "number" ? { since: self.since } : {},
+			room,
+			mic: micOf(self.mic),
+			speaking: self.speaking === true,
+			quality: self.quality === "poor" ? "poor" : "good"
+		},
+		heard: isRecord$2(heard) ? heard : {},
+		missing: isRecord$2(missing) ? missing : {}
+	};
+};
+const initialInput = () => ({
+	mySeatId: "",
+	snapshot: null,
+	clockOffset: 0,
+	voice: null,
+	connection: {
+		status: "connecting",
+		since: Date.now()
+	},
+	startedAt: Date.now()
+});
+const initialState = () => ({
+	input: initialInput(),
+	fixed: null,
+	current: null,
+	pause: null,
+	pendingChanges: [],
+	flushScheduled: false,
+	lastNotified: ""
+});
+let state = initialState();
+const presenceListeners = /* @__PURE__ */ new Set();
+const pauseListeners = /* @__PURE__ */ new Set();
+/** 発話は 1 秒に数回変わるので、描画のフレームごとにまとめて届ける。 */
+const scheduleFlush = () => {
+	if (state.flushScheduled) return;
+	state.flushScheduled = true;
+	const run = () => {
+		state.flushScheduled = false;
+		flush();
+	};
+	if (typeof requestAnimationFrame === "function") requestAnimationFrame(run);
+	else setTimeout(run, 0);
+};
+const flush = () => {
+	const presence = getPresence();
+	const serialized = JSON.stringify(presence);
+	if (serialized === state.lastNotified && state.pendingChanges.length === 0) return;
+	state.lastNotified = serialized;
+	const changes = state.pendingChanges;
+	state.pendingChanges = [];
+	for (const listener of presenceListeners) callScenario("onPresenceChange ハンドラ", () => listener(presence, changes));
+};
+/**
+* 入力が変わったら組み立て直す。
+*
+* ここで例外を出すと、呼んだ側 (WebSocket の状態の処理) まで抜けて再接続の予約が消える。
+* 組み立てに失敗したら直前の値を出し続ける。
+*/
+const recompute = () => {
+	try {
+		const prev = getPresence();
+		const next = state.fixed ?? buildPresence(state.input);
+		state.current = next;
+		state.pendingChanges.push(...diffPresence(state.input.mySeatId, prev, next));
+		scheduleFlush();
+	} catch (err) {
+		console.error("[uzu] presence を組み立てられなかったので、直前の値を使い続けます", err);
 	}
-	requester(true);
 };
-const requestResume = () => {
-	if (!requester) {
-		console.warn("[uzu] requestResume: サーバーへ接続していないので解除できません");
-		return;
+const setPause = (pause) => {
+	if (JSON.stringify(pause) === JSON.stringify(state.pause)) return;
+	state.pause = pause;
+	for (const listener of pauseListeners) callScenario("onPauseChange ハンドラ", () => listener(pause));
+};
+const configurePresence = (mySeatId) => {
+	state.input = {
+		...state.input,
+		mySeatId
+	};
+	recompute();
+};
+/** ローカル実行。サーバーが無いので、自分はつながっていて通話は無いものとして固定する。 */
+const useFixedPresence = (mySeatId) => {
+	state.input = {
+		...state.input,
+		mySeatId
+	};
+	state.fixed = {
+		me: {
+			connection: { status: "online" },
+			voice: {
+				status: "off",
+				reason: "this-device"
+			}
+		},
+		others: {},
+		observers: {
+			count: 0,
+			speaking: []
+		}
+	};
+	recompute();
+};
+/** ローカル実行の一時停止。サーバーが居ないので presence ではなく SDK 自身が決める。 */
+const setLocalPause = (pause) => {
+	setPause(pause);
+};
+const applyPresenceSnapshot = (snapshot) => {
+	state.input = {
+		...state.input,
+		snapshot,
+		clockOffset: Date.now() - snapshot.serverNow
+	};
+	const pause = snapshot.pause;
+	setPause(isRecord$2(pause) ? pause : null);
+	recompute();
+};
+const applyVoiceChanged = (voice) => {
+	state.input = {
+		...state.input,
+		voice
+	};
+	recompute();
+};
+const setWireStatus = (status) => {
+	if (state.input.connection.status === status) return;
+	state.input = {
+		...state.input,
+		connection: {
+			status,
+			since: Date.now()
+		}
+	};
+	recompute();
+};
+const EMPTY_PRESENCE = {
+	me: {
+		connection: { status: "online" },
+		voice: {
+			status: "off",
+			reason: "this-device"
+		}
+	},
+	others: {},
+	observers: {
+		count: 0,
+		speaking: []
 	}
-	requester(false);
+};
+/** 今の接続と通話の状態。 */
+const getPresence = () => {
+	if (state.current === null) try {
+		state.current = state.fixed ?? buildPresence(state.input);
+	} catch (err) {
+		console.error("[uzu] presence を組み立てられませんでした", err);
+		return EMPTY_PRESENCE;
+	}
+	return state.current;
+};
+/**
+* 接続と通話の状態が変わったときに呼ばれる。値全体と、変わったところの一覧を渡す。
+* 発話やミュートの変化では `changes` は空で、値だけが新しくなる。
+* 戻り値を呼ぶと、呼ばれなくなる。
+*/
+const onPresenceChange = (listener) => {
+	presenceListeners.add(listener);
+	return () => {
+		presenceListeners.delete(listener);
+	};
+};
+/** 今止まっているか、止まっていればその理由。止まっていなければ null。 */
+const getPause = () => state.pause;
+/**
+* 止まった・再開したときに呼ばれる。理由は今後増えることがあるので、知らない理由でも止まって
+* いるものとして扱う。戻り値を呼ぶと、呼ばれなくなる。
+*/
+const onPauseChange = (listener) => {
+	pauseListeners.add(listener);
+	return () => {
+		pauseListeners.delete(listener);
+	};
 };
 //#endregion
 //#region src/reconnectable-ws.ts
@@ -1093,7 +1440,7 @@ let hud = {
 };
 let current = null;
 let envProbe = null;
-const listeners = /* @__PURE__ */ new Set();
+const listeners$1 = /* @__PURE__ */ new Set();
 const zero = () => ({
 	top: 0,
 	right: 0,
@@ -1176,7 +1523,7 @@ const refresh = () => {
 	const next = compute();
 	if (current && same(current, next)) return;
 	current = next;
-	for (const cb of listeners) try {
+	for (const cb of listeners$1) try {
 		cb(next);
 	} catch (err) {
 		console.warn("[UZU SDK] onInsetsChange listener threw:", err);
@@ -1287,15 +1634,15 @@ const getInsets = () => {
 * 登録時に即時呼び出しはしない。初期値は [getInsets] で読むこと。
 */
 const onInsetsChange = (cb) => {
-	listeners.add(cb);
+	listeners$1.add(cb);
 	return () => {
-		listeners.delete(cb);
+		listeners$1.delete(cb);
 	};
 };
 //#endregion
 //#region src/bridge-envelope.ts
-const isBridgeChannel = (value) => value === "sdk" || value === "game";
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isBridgeChannel = (value) => value === "sdk" || value === "game" || value === "platform";
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * 親 frame から postMessage で届く envelope を BridgeMessage に復元する。
 * string でも object でも来るので、形を確かめてから通す。
@@ -1311,45 +1658,119 @@ const parseBridgeEnvelope = (raw) => {
 	} catch {
 		return null;
 	}
-	if (!isRecord(value)) return null;
+	if (!isRecord$1(value)) return null;
 	const { channel, type, payload, playerId } = value;
 	if (!isBridgeChannel(channel) || typeof type !== "string") return null;
 	return {
 		channel,
 		type,
-		payload: isRecord(payload) ? payload : {},
+		payload: isRecord$1(payload) ? payload : {},
 		...typeof playerId === "string" ? { playerId } : {}
 	};
 };
 //#endregion
-//#region src/scenario-callback.ts
+//#region src/host-bridge.ts
+let sender = null;
+const setHostSender = (fn) => {
+	sender = fn;
+};
+const sendToHost = (channel, type, payload) => {
+	sender?.(channel, type, payload);
+};
+//#endregion
+//#region src/pause-state.ts
 /**
 * @docs
-* - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+* - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
 *
-* SDK からシナリオのコード (描画 / イベント購読 / bridge の購読) を呼ぶときの例外境界。
-* シナリオのコールバックを呼ぶ箇所は、すべてここを通す。
+* サーバーが時計を止めているか (wire の `frozen`) を SDK 全体で 1 箇所に持つ。
 *
-* これらは state 配信やメッセージ受信のたびに同じ経路を通る。例外をそのまま上へ通すと
-* 呼び出し元の state 適用 (confirmedState 更新 / ack 処理 / seq 前進) が途中で止まり、
-* 以降の配信でも同じ経路で投げ続ける。WebSocket もホストアプリも生きたまま画面だけが
-* 永久に更新されなくなる — 2026-09-09 の UZU TOKYO 公演で実際に起きた壊れ方がこれ。
+* 止まった理由は見ない。理由 (緊急一時停止・自動中断) は presence の `pause` で届き、
+* シナリオには `getPause` / `onPauseChange` で出す。ここは理由を問わず時計と送信を
+* 止めるだけにしておき、理由が増えても公開済みのシナリオの時計が止まるようにする。
 *
-* ここで断ち切れば state 適用は最後まで走り、次の配信で描画がやり直される
-* (onState は毎回フル state から再実行されるので冪等)。同じ理由で、購読が複数ある
-* ところでは 1 件の失敗を他の購読へ波及させない。
+* ゲーム内時計の凍結もここから駆動する。停止フラグと時計の凍結が別々に動くと、
+* 「止まっているのにカウントダウンだけ進む」がいつか必ず起きる。
+*/
+let paused = false;
+let pausedBy = null;
+const listeners = /* @__PURE__ */ new Set();
+/** transport から呼ぶ内部関数。停止状態が変わったときだけ通知する。 */
+const setPauseState = (next, by) => {
+	pausedBy = next ? by : null;
+	if (next === paused) return;
+	paused = next;
+	if (paused) freezeGameTime();
+	else unfreezeGameTime();
+	for (const cb of listeners) try {
+		cb(paused);
+	} catch (err) {
+		console.warn("[uzu] frozen listener threw:", err);
+	}
+};
+/** 時計が止まっているか。送信の先読みを止めるのに使う。 */
+const isPaused = () => {
+	return paused;
+};
+/** 停止を要求した playerId。停止していなければ null。 */
+const getPausedBy = () => {
+	return pausedBy;
+};
+/** 時計の停止の変化を購読する (ホストへの中継用)。 */
+const onFrozenChange = (cb) => {
+	listeners.add(cb);
+};
+//#endregion
+//#region src/platform.ts
+/**
+* @docs
+* - 接続と通話の状態 (Presence): docs/docs/uzu_code/presence.md
+* - ブリッジ仕様: docs/docs/uzu_code/bridge.md
+*
+* アプリとサーバーのあいだの伝言 (bridge の `platform` チャネル ⇄ WebSocket の `__platform`) を運ぶ。
+*
+* 中身は見ない。通話の申告や一時停止の要求の中身は、アプリとサーバーの更新だけで変えられる
+* ようにしておく。例外は presence で、SDK も読んでシナリオの `Presence` を組み立てる。
 */
+let serverSink = null;
 /**
-* シナリオ側のコールバックを実行し、例外を境界で止める。
+* 出口ができる前に届いた伝言。種類ごとに最新の 1 通だけ持つ。
 *
-* 例外は握り潰さず `console.error` に出す。ホスト側のログ収集がこれを拾う。
+* アプリは SDK の `ready` で通話の申告を送り直すが、`ready` は `run()` (出口を作る) より前に
+* 出る。捨てると、WebView を読み込み直したときに申告がサーバーへ届かないままになる
+* (ゲームの接続は online のまま残るので、アプリの送り直しも走らない)。どの種類も「今の状態」を
+* 伝えるものなので、溜めるのは最新の 1 通で足りる。
 */
-const callScenario = (label, fn) => {
-	try {
-		fn();
-	} catch (err) {
-		console.error(`[uzu] シナリオの ${label} で例外が発生しました (処理は継続します)`, err);
+const pending = /* @__PURE__ */ new Map();
+/**
+* サーバーへの出口を登録する。オンラインは WebSocket、ローカル実行は SDK 自身
+* (サーバーが無いので、一時停止の要求だけをその場で処理する)。
+*/
+const setPlatformServerSink = (sink) => {
+	serverSink = sink;
+	if (!sink) return;
+	const held = [...pending.values()];
+	pending.clear();
+	for (const message of held) sink(message);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** アプリから届いた伝言をサーバーへ運ぶ。つながる前・切れている間は WebSocket 側が溜める。 */
+const forwardToServer = (message) => {
+	if (!serverSink) {
+		pending.delete(message.type);
+		pending.set(message.type, message);
+		return;
 	}
+	serverSink(message);
+};
+/** 組み立てに要る最低限だけを見る。足りない項目は組み立てる側が既定の値で埋める。 */
+const isPresenceSnapshot = (value) => isRecord(value) && typeof value.serverNow === "number" && isRecord(value.seats);
+/** サーバーから届いた伝言をアプリへ運ぶ。 */
+const forwardToHost = (raw) => {
+	if (!isRecord(raw) || typeof raw.type !== "string") return;
+	const payload = isRecord(raw.payload) ? raw.payload : {};
+	sendToHost("platform", raw.type, payload);
+	if (raw.type === PLATFORM_MESSAGE_TYPE.presence && isPresenceSnapshot(raw.payload)) applyPresenceSnapshot(raw.payload);
 };
 //#endregion
 //#region src/run/local-server-action.ts
@@ -1451,7 +1872,7 @@ const runLocalServerAction = (config) => {
 		}
 	};
 	clock.restart();
-	const setupTime = gameTime();
+	const setupTime = GAME_START;
 	const setupArgs = {
 		players,
 		ctx: {
@@ -1534,10 +1955,18 @@ const runLocalServerAction = (config) => {
 		if (!(paused ? clock.freeze("emergency-stop") : clock.unfreeze("emergency-stop"))) return;
 		observeGameTime(gameTime());
 		setPauseState(paused, paused ? myId : null);
+		setLocalPause(paused ? {
+			reason: "emergency",
+			by: myId
+		} : null);
 		observeGameTime(gameTime());
 		syncWakeup();
 	};
-	setPauseRequester(applyPause);
+	setPlatformServerSink((message) => {
+		if (message.type === PLATFORM_MESSAGE_TYPE.pauseRequest) applyPause(true);
+		else if (message.type === PLATFORM_MESSAGE_TYPE.pauseResume) applyPause(false);
+	});
+	useFixedPresence(myId);
 	inputs(dispatchAction);
 	syncWakeup();
 	onState(state, myId);
@@ -1793,23 +2222,52 @@ const createOptimisticActionClient = (config) => {
 };
 //#endregion
 //#region src/run/server-action.ts
-const runOnlineServerAction = (config, gameEndpoint, roomId, seatId, players, seatKind) => {
+/**
+* @docs
+* - play-server 仕様: docs/docs/uzu_code/play-server.md
+* - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+*
+* ServerAction モードのオンライン接続 (WebSocket トランスポート)。
+*
+* ホスト/ゲストの区別なし。全クライアントがサーバーに対して同じ立場で action を送信し、
+* サーバーが reducer を実行して state を遷移させる。
+*
+* 楽観的更新ロジック (pending actions / reapply / ack 重複排除) は
+* `optimistic-action-client.ts` に集約。本ファイルは WebSocket 固有の責務
+* (接続管理 / メッセージ振り分け / delta seq の連続性チェック / フル state 再要求) のみ持つ。
+*/
+const WIRE_STATUS = {
+	connecting: "connecting",
+	connected: "online",
+	reconnecting: "reconnecting",
+	disconnected: "offline"
+};
+const runOnlineServerAction = (config, gameEndpoint, roomId, seatId, players, seatKind, monitor) => {
+	configurePresence(seatId);
 	const toWire = (p) => ({
 		id: p.id,
 		name: p.nickname,
 		iconUrl: p.iconUrl,
 		characterId: p.characterId
 	});
-	const wsUrl = `${gameEndpoint}/${roomId}?${new URLSearchParams({
+	const query = new URLSearchParams({
 		seatId,
 		nickname: "Player",
 		players: JSON.stringify(players.map(toWire))
-	})}`;
+	});
+	if (monitor) query.set("monitor", "1");
+	const wsUrl = `${gameEndpoint}/${roomId}?${query}`;
 	console.log(`[SDK ServerAction] 🔗 Connecting wsUrl=${wsUrl}`);
 	const ws = new ReconnectableWebSocket(wsUrl, {
 		onConnectionStateChange: (state) => {
 			console.log(`[SDK ServerAction] 📡 Connection state: ${state}`);
-			config.onConnectionStateChange?.(state);
+			try {
+				const status = WIRE_STATUS[state];
+				setWireStatus(status);
+				sendToHost("sdk", "connectionChanged", { status });
+			} catch (err) {
+				console.error("[SDK ServerAction] 接続の状態を伝えられませんでした", err);
+			}
 		},
 		shouldBuffer: (data) => {
 			try {
@@ -1820,9 +2278,11 @@ const runOnlineServerAction = (config, gameEndpoint, roomId, seatId, players, se
 			}
 		}
 	});
-	setPauseRequester((paused) => {
-		console.log(`[SDK ServerAction] ➡ send ${paused ? "__pause" : "__resume"}`);
-		ws.send(JSON.stringify({ type: paused ? "__pause" : "__resume" }));
+	setPlatformServerSink((message) => {
+		ws.send(JSON.stringify({
+			type: PLATFORM_WIRE_TYPE,
+			message
+		}));
 	});
 	/** サーバー seq (delta の連続性チェック用) */
 	let serverSeq = 0;
@@ -1858,6 +2318,10 @@ const runOnlineServerAction = (config, gameEndpoint, roomId, seatId, players, se
 		const msgType = parsed.type;
 		console.log(`[SDK ServerAction] ⬅ recv type=${msgType}`);
 		client.observeGameTime(parsed.gameTime);
+		if (msgType === "__platform") {
+			forwardToHost(parsed.message);
+			return;
+		}
 		if (msgType === "__pause_state") {
 			const frozen = parsed.frozen === true;
 			console.log(`[SDK ServerAction] ${frozen ? "⏸" : "▶️"} pause_state frozen=${String(frozen)}`);
@@ -1965,7 +2429,6 @@ const runOnlineServerAction = (config, gameEndpoint, roomId, seatId, players, se
 //#endregion
 //#region src/index.ts
 const gameHandlers = /* @__PURE__ */ new Map();
-const _playersChangedHandlers = [];
 let _lastStateSnap = null;
 let _gameEndpoint = null;
 let _initialized = false;
@@ -2025,7 +2488,7 @@ const init = (_opts) => {
 			handleMessage(data);
 		});
 		applyInsets(params);
-		onPauseChange((paused) => {
+		onFrozenChange((paused) => {
 			sendRaw("sdk", "pauseState", {
 				paused,
 				by: getPausedBy()
@@ -2054,11 +2517,23 @@ const playBgm = (sound) => {
 const stopBgm = () => {
 	sendRaw("sdk", "stopBgm", {});
 };
-const setMicEnabled = (enabled) => {
-	sendRaw("sdk", "setMicEnabled", { enabled });
+/**
+* 観測席 (観戦・進行管理) が聴く通話の部屋を選ぶ。null は全体の部屋。
+*
+* プレイヤーの部屋はロジックの `voicePlan` が決めるので、プレイヤー席では何も起きない。
+*/
+const setListeningRoom = (room) => {
+	sendRaw("sdk", "setListeningRoom", { room });
 };
-const changeRoom = (roomId) => {
-	sendRaw("sdk", "changeRoom", { roomId });
+/**
+* 本人のマイクをミュートする。
+*
+* 作品からできるのはミュートだけで、外すことはできない。外すのは本人が HUD のマイクボタンで
+* 行う。勝手にマイクを開くと、本人の知らないうちに声が他の人へ届いてしまうため。
+* 場面ごとに決まったミュートは `voicePlan` の `mic` で宣言する。
+*/
+const muteMic = () => {
+	sendRaw("sdk", "setMicMuted", { muted: true });
 };
 const HAPTIC_FALLBACK_MS = {
 	light: 10,
@@ -2139,10 +2614,6 @@ const gameReady = () => {
 const finishGame = () => {
 	sendRaw("sdk", "finishGame", {});
 };
-/** Flutter からの playersChanged メッセージを受信するハンドラを登録する。 */
-const onPlayersChanged = (handler) => {
-	_playersChangedHandlers.push(handler);
-};
 /**
 * `A` に既定値が要る。 TypeScript は型引数の部分推論ができないので、 既定が無いと
 * 既存の `run<State>({…})` が「2 つ必要」で落ちる。 既定を置けば型引数を書かない
@@ -2175,7 +2646,8 @@ const run = (config) => {
 	else if (_gameEndpoint) {
 		const { seatId, players } = resolveSeatParams(params);
 		const seatKind = resolveSeatKind(params);
-		runOnlineServerAction(wrappedConfig, _gameEndpoint, roomId, seatId, players, seatKind);
+		const monitor = params.get("monitor") === "1";
+		runOnlineServerAction(wrappedConfig, _gameEndpoint, roomId, seatId, players, seatKind, monitor);
 	} else throw new Error("[UZU SDK] roomId is set but ?server= is missing. Multiplayer requires a WebSocket server URL — pass ?server=ws://host:port in the URL.");
 	attachDevHooksIfNotHosted();
 };
@@ -2225,6 +2697,7 @@ const sendRaw = (channel, type, payload) => {
 	if (window.FlutterHost) window.FlutterHost.postMessage(JSON.stringify(msg));
 	else if (window.parent !== window) window.parent.postMessage(JSON.stringify(msg), "*");
 };
+setHostSender(sendRaw);
 const handleMessage = (msg) => {
 	const { channel, type, payload } = msg;
 	if (channel === "sdk") {
@@ -2233,28 +2706,27 @@ const handleMessage = (msg) => {
 				console.log(`[SDK] 🔧 handleMessage sdk/getState → responding`);
 				sendRaw("sdk", "stateResponse", { state: _lastStateSnap });
 				return;
-			case "playersChanged": {
-				const players = payload.players ?? {};
-				for (const fn of _playersChangedHandlers) callScenario("playersChanged ハンドラ", () => fn(players));
+			case "voiceChanged": {
+				const voice = parseVoiceChanged(payload);
+				if (voice) applyVoiceChanged(voice);
 				return;
 			}
-			case "requestPause":
-				console.log(`[SDK] ⏸ handleMessage sdk/requestPause`);
-				requestPause();
-				return;
-			case "requestResume":
-				console.log(`[SDK] ▶️ handleMessage sdk/requestResume`);
-				requestResume();
-				return;
 			case "insetsChanged":
 				handleInsetsChanged(payload);
 				return;
 		}
 		return;
 	}
+	if (channel === "platform") {
+		forwardToServer({
+			type,
+			payload
+		});
+		return;
+	}
 	const h = gameHandlers.get(type) ?? [];
 	console.log(`[SDK] 🔧 handleMessage game/${type} handlers=${h.length}`);
 	for (const fn of h) callScenario(`game/${type} ハンドラ`, () => fn(payload));
 };
 //#endregion
-export { DEFAULT_ICON_URLS, GAME_START, ReconnectableWebSocket, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, finishGame, firstFrameReady, gameReady, gameTime, getInsets, getPredictionWarnings, haptic, init, isHosted, isPaused, isServerOnlyAction, minus, on, onInsetsChange, onPauseChange, onPlayersChanged, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub };
+export { DEFAULT_ICON_URLS, DEFAULT_VOICE_PLAN, GAME_START, ReconnectableWebSocket, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, createDevHooks, finishGame, firstFrameReady, gameReady, gameTime, getInsets, getPause, getPredictionWarnings, getPresence, haptic, init, isHosted, isServerOnlyAction, minus, muteMic, on, onInsetsChange, onPauseChange, onPresenceChange, playBgm, playSound, plus, run, send, serverOnly, setListeningRoom, stopBgm, sub };