@uzuhq/code-sdk 0.7.7 → 0.8.1

package/README.md

@@ -223,7 +223,7 @@ import type { GameLogic } from '@uzuhq/code-sdk';
 
 const logic: GameLogic<MyState> = {
   setup({ players, ctx }) {
-    // 初期 state を生成。ctx.random は SeededRandom、ctx.now はサーバーの実時刻。
+    // 初期 state を生成。ctx.random は SeededRandom、ctx.time はゲーム内時刻 (必ず 0)。
     // players は配役を受け取る参加者だけで、観測者は含まれない
     return { players: {}, items: [] };
   },
@@ -235,24 +235,24 @@ const logic: GameLogic<MyState> = {
       state.players[playerId].x += payload.dx;
       // ctx.emit でイベント発火 (購読側は events で predict を宣言する)
       ctx.emit('sound', { sound: 'step' });
-      // 時刻は ctx.now を使う。Date.now() は端末とサーバーでズレる
+      // 時刻は ctx.after(d) を使う。Date.now() は epoch が違う (Unix ms vs ゲーム内時刻)
     },
   },
 
   // サーバーでのみ走る。実時刻・乱数・fetch などクライアントが再現できない処理。
   // actions と同名にすると「同じ action のサーバー側の続き」になる。
   serverActions: {
-    async notifyExternal({ state, payload, playerId }) {
+    async notifyExternal({ state, payload, playerId, ctx }) {
       await fetch('https://example.com/notify', {
         method: 'POST',
         body: JSON.stringify({ playerId, ...payload }),
       });
-      state.notifiedAt = Date.now();
+      state.notifiedAt = ctx.time;
     },
   },
 
   update({ state, ctx }) {
-    // 毎 tick 実行。ctx.tick / ctx.random / ctx.now / ctx.emit / ctx.playerInputs が使える
+    // 毎 tick 実行。ctx.tick / ctx.random / ctx.time / ctx.after / ctx.emit / ctx.playerInputs が使える
   },
 
   tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし)
@@ -287,10 +287,10 @@ deadlines: {
 },
 ```
 
-|           |                                                                                                                                                                         |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `at`      | 締切の絶対時刻 (ms)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い関数にすること** (state が変わるたびに呼ばれる) |
-| `handler` | サーバーでのみ走る。`ctx` は `{ now, random, emit }`                                                                                                                    |
+|           |                                                                                                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `at`      | 締切の[ゲーム内時刻](#ゲーム内時計) (`GameTime`)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い純関数にすること** (state が変わるたびに呼ばれる) |
+| `handler` | サーバーでのみ走る。`ctx` は `{ time, after, random, emit }`                                                                                                                                           |
 
 締切は state から導出するので、**予約を張り替える処理を書かなくてよい**。action が throw して
 state が巻き戻れば締切も一緒に巻き戻る。発火直前に `at` を評価し直すので、二重発火を
@@ -299,6 +299,51 @@ handler 側で弾く必要も無い。
 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
 ポーリング中は Durable Object が hibernate できない。
 
+### ゲーム内時計
+
+**時刻は Unix epoch ではない。** `ctx.time` はゲーム開始からの経過 ms (`GameTime`) で、
+[緊急一時停止](#緊急一時停止)中は進まない。`Date.now()` とは桁も意味も違う。
+
+| API                        | 意味                                                              |
+| -------------------------- | ----------------------------------------------------------------- |
+| `ctx.time`                 | そのハンドラが走っているゲーム内時刻。`setup` では必ず `0`        |
+| `ctx.after(d)`             | 今から `d` ms 後のゲーム内時刻。締切を state に置くときに使う     |
+| `gameTime()`               | 描画側で読む現在のゲーム内時刻 (推定値)。`performance.now()` 基準 |
+| `plus(t, d)` / `sub(t, d)` | 時刻に長さを足す / 引く                                           |
+| `minus(a, b)`              | 2 つの時刻の差 (ms)                                               |
+
+```ts
+import { gameTime, minus } from '@uzuhq/code-sdk';
+
+// 締切を置く
+actions: {
+  startPhase: ({ state, ctx }) => { state.phaseEndsAt = ctx.after(5 * 60_000); },
+},
+
+// 残り時間を描く
+const remain = Math.ceil(minus(state.phaseEndsAt, gameTime()) / 1000);
+```
+
+`GameTime` は brand 型なので実行時はただの数値で、state は素の JSON のまま。ただし型の上では
+`number` と混ざらないので、`Date.now()` を書き込む式も `endsAt - Date.now()` と読む式も
+コンパイルが通らない。
+
+### 緊急一時停止
+
+プレイヤーが UZU メニューから全員のタイマーを止められる。**シナリオは停止を知らないし、
+知る必要も無い。** 停止中は `update()` が呼ばれず、action はサーバーが弾き、締切も来ない。
+
+演出だけを止めたいときに限り、読み取り専用で参照できる。
+
+```ts
+import { isPaused, onPauseChange } from '@uzuhq/code-sdk';
+
+onPauseChange((paused) => (paused ? engine.stop() : engine.start()));
+```
+
+`GameLogic` からは触れない。停止を state に持ち込むと「停止中は state が変わらない」という
+前提が崩れる。
+
 #### `serverOnly(handler)`
 
 > **Deprecated**: `serverActions` に直接書く。

package/dist/dev-globals.d.ts

@@ -1,4 +1,4 @@
-import { i as UzuDevHooks } from "./dev-hooks-ClWM8HzI.js";
+import { i as UzuDevHooks } from "./dev-hooks-BYl_jrcy.js";
 //#region src/dev-globals.d.ts
 declare global {
   interface Window {

package/dist/{dev-hooks-ClWM8HzI.d.ts → dev-hooks-BYl_jrcy.d.ts}

@@ -79,19 +79,54 @@ declare function applyJsonMergePatch(target: Record<string, unknown>, patch: Jso
  */
 declare function applyJsonPatch(target: Record<string, unknown>, ops: JsonPatchOp[]): void;
 //#endregion
-//#region ../engine-core/src/types.d.ts
+//#region ../engine-core/src/game-time.d.ts
 /**
  * @docs
- * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
- * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
+ * - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
+ *
+ * ゲーム内時刻。ゲーム開始からの ms で、停止中は進まない。**Unix epoch ではない。**
+ *
+ * 実行時はただの number。brand はコンパイル時だけの区別なので、state は素の JSON の
+ * まま保たれる (structuredClone / json-patch / JSON.stringify がそのまま通る)。
+ * 値を作れるのは `ctx.after` / `plus` だけになるので、`Date.now()` を混ぜると型で落ちる。
+ *
+ * 型が効くのは TypeScript を書いているシナリオだけだが、JS のシナリオでも epoch が
+ * 違うぶんは残る (`Date.now()` を混ぜれば締切が 56,000 日後になって初回で気付く)。
+ */
+declare const gameTimeBrand: unique symbol;
+/** brand の印。`GameTime` を組み立てるためだけに使う。 */
+type GameTimeTag = {
+  readonly [gameTimeBrand]: 'GameTime';
+};
+/**
+ * ゲーム内時刻 (ゲーム開始からの ms)。停止中は進まない。
  *
- * シナリオが書く `GameLogic` と、その実行文脈の型。
+ * `number & Tag` ではなく `(number & Tag) | Tag` にしてあるのは、**読み側を守るため**。
+ * 交差だけだと `GameTime` が `number` へ代入できてしまい、
+ * `state.endsAt - Date.now()` が型検査を通る。これは `GameTime` を導入した動機
+ * そのもののバグで、しかも実行時に静かに壊れる (巨大な負数が
+ * `Math.max(0, ...)` に潰されてタイマーが 00:00 で固まる)。
  *
- * SDK (browser) / cli dev-server (Node) / play-server の facet (Workers) の 3 ランタイムが
- * この 1 ファイルを共有する。ここに browser / Node / Workers いずれかの API を持ち込むと、
- * 残り 2 つのランタイムでビルドが落ちる (engine-core の tsconfig は lib を ES2022 だけに
- * 絞ってある)。
+ * union にすると `number` への代入と算術が型で止まり、`GameTime` 同士の比較・`===`・
+ * テンプレート・`Number.isFinite`・JSON 往復・一段 cast はそのまま使える。
+ * TypeScript コンパイラ自身が `__String` (識別子の内部表現) で同じ形を採っている
+ * (microsoft/TypeScript#16915)。
  */
+type GameTime = (number & GameTimeTag) | GameTimeTag;
+/** 長さ (ms)。差や間隔はこちら。 */
+type Duration = number;
+/**
+ * `GameTime` に長さを足す。
+ *
+ * 算術は型で止まるので、`GameTime` を作り直す道はこの関数と `ctx.after` に限られる。
+ */
+declare const plus: (t: GameTime, d: Duration) => GameTime;
+/** `GameTime` から長さを引く。`plus(t, -d)` と書かせないための対。 */
+declare const sub: (t: GameTime, d: Duration) => GameTime;
+/** 2 つの `GameTime` の差 (ms)。 */
+declare const minus: (a: GameTime, b: GameTime) => Duration;
+//#endregion
+//#region ../engine-core/src/types.d.ts
 /**
  * roster に載る席。
  *
@@ -128,20 +163,24 @@ interface SeededRandom {
  */
 interface ActionContext {
   /**
-   * サーバーで処理される時刻 (ms)。先読みではクロックオフセットからの推定値。
+   * 現在のゲーム内時刻。先読みではクロックオフセットからの推定値。
    *
    * 推定なのでサーバーとは数十 ms ずれる。時刻での分岐に使うと境界で判定が割れるので、
-   * 分岐は `update()` (サーバー専用) で行う。
+   * 分岐は `update()` / `deadlines` (サーバー専用) へ寄せる。
    *
    * 同じ action を再適用しても値は変わらない (初回予測時の値を使い回す)。
    */
-  now: number;
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。締切を state へ置くときに使う。 */
+  after(d: Duration): GameTime;
   emit: Emit;
 }
 /** `deadlines` handler の実行文脈。サーバーでしか走らないので tick 以外を渡せる。 */
 interface DeadlineContext {
-  /** 発火時刻 (ms)。サーバー専用なので常に正確。 */
-  now: number;
+  /** 発火時点のゲーム内時刻。サーバー専用なので常に正確。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。次の締切を state へ置き直すときに使う。 */
+  after(d: Duration): GameTime;
   random: SeededRandom;
   emit: Emit;
 }
@@ -162,17 +201,21 @@ interface DeadlineArgs<S> {
  */
 interface Deadline<S> {
   /**
-   * 締切の絶対時刻 (ms)。締切が無いときは null / undefined。
+   * 締切のゲーム内時刻。締切が無いときは null / undefined。
    *
    * `state.timer?.endsAt` のような optional chain の結果をそのまま返せるよう
    * undefined も受ける。数値以外は「締切なし」として同じに扱う。
    *
-   * state が変わるたびに呼ばれるので、state だけから決まる軽い関数にすること。
+   * 戻り値が `GameTime` なのは強制点。`Date.now() + 尺` も素の number も返せないので、
+   * 値を得る道が `ctx.after()` / `plus()` に限られ、state の時刻フィールドを
+   * `GameTime` で持つ動機が自動的に生まれる。
+   *
+   * state が変わるたびに呼ばれるので、state だけから決まる軽い純関数にすること。
    * ここで実時刻や乱数を読むと、呼ばれるたびに答えが変わって予約が暴れる。
    */
   at(args: {
     state: S;
-  }): number | null | undefined;
+  }): GameTime | null | undefined;
   /**
    * `at` の時刻を過ぎたときにサーバーで呼ばれる。
    *
@@ -185,8 +228,10 @@ interface Deadline<S> {
 interface ServerActionContext {
   tick: number;
   random: SeededRandom;
-  /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
-  now: number;
+  /** 現在のゲーム内時刻。同じ dispatch の `actions` に渡る `ctx.time` と同一値。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。 */
+  after(d: Duration): GameTime;
   emit: Emit;
 }
 /** @deprecated `ServerActionContext` を使う。 */
@@ -230,8 +275,10 @@ type ServerOnlyAction<S> = ServerActionHandler<S> & {
 interface UpdateContext {
   random: SeededRandom;
   tick: number;
-  /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
-  now: number;
+  /** 現在のゲーム内時刻。update はサーバーでしか走らないので常に正確。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。 */
+  after(d: Duration): GameTime;
   emit: Emit;
   playerInputs: Record<string, Record<string, any>>;
 }
@@ -246,8 +293,10 @@ interface UpdateArgs<S> {
  */
 interface SetupContext {
   random: SeededRandom;
-  /** サーバーの実時刻 (ms)。setup はサーバーでしか走らないので常に正確。 */
-  now: number;
+  /** ゲーム内時刻。setup は時計の起点なので必ず `0`。 */
+  time: GameTime;
+  /** 今から `d` ms 後のゲーム内時刻。setup では `d` そのものになる。 */
+  after(d: Duration): GameTime;
 }
 /** `setup()` の引数。 */
 interface SetupArgs {
@@ -454,7 +503,7 @@ declare global {
 //#endregion
 //#region src/dev-prediction-traps.d.ts
 interface PredictionWarning {
-  /** 呼び出した action 名 */
+  /** 呼び出した action 名。描画経路では `'(render)'`。 */
   action: string;
   /** 呼ばれた API 名 (`'Date.now()'` など) */
   api: string;
@@ -679,4 +728,4 @@ interface DevHooksCtx<S = unknown> {
 declare function createDevHooks<S>(ctx: DevHooksCtx<S>): UzuDevHooks<S>;
 declare function attachDevHooks<S>(ctx: DevHooksCtx<S>): void;
 //#endregion
-export { applyJsonMergePatch as $, DEFAULT_ICON_URLS as A, ServerActionContext as B, SetFn as C, ActionContext as D, ActionArgs as E, GameLogic as F, ServerOnlyActionContext as G, ServerActionMap as H, SERVER_TIME as I, SetupContext as J, ServerOnlyActionHandlerFn as K, Seat as L, DeadlineArgs as M, DeadlineContext as N, ActionHandler as O, Emit as P, JsonPatchOp as Q, SeededRandom as R, SendAction as S, Operation as T, ServerEvent as U, ServerActionHandler as V, ServerOnlyAction as W, UpdateContext as X, UpdateArgs as Y, JsonMergePatch as Z, PayloadMap as _, attachDevHooks as a, PlayersChangedMessage as b, getPredictionWarnings as c, ConnectionCallbacks as d, applyJsonPatch as et, ConnectionState as f, PatchFn as g, GameConfig as h, UzuDevHooks as i, Deadline as j, ActionMap as k, BridgeChannel as l, EventSubscription as m, RunHandle as n, createDevHooks as o, EventHandler as p, SetupArgs as q, SyncHandle as r, PredictionWarning as s, DevHooksCtx as t, BridgeMessage as u, PlayScreenMessage as v, SyncConfig as w, SeatKind as x, PlayerVoiceState as y, ServerActionArgs as z };
+export { minus as $, DEFAULT_ICON_URLS as A, ServerActionContext as B, SetFn as C, ActionContext as D, ActionArgs as E, GameLogic as F, ServerOnlyActionContext as G, ServerActionMap as H, SERVER_TIME as I, SetupContext as J, ServerOnlyActionHandlerFn as K, Seat as L, DeadlineArgs as M, DeadlineContext as N, ActionHandler as O, Emit as P, GameTime as Q, SeededRandom as R, SendAction as S, Operation as T, ServerEvent as U, ServerActionHandler as V, ServerOnlyAction as W, UpdateContext as X, UpdateArgs as Y, Duration as Z, PayloadMap as _, attachDevHooks as a, applyJsonPatch as at, PlayersChangedMessage as b, getPredictionWarnings as c, ConnectionCallbacks as d, plus as et, ConnectionState as f, PatchFn as g, GameConfig as h, UzuDevHooks as i, applyJsonMergePatch as it, Deadline as j, ActionMap as k, BridgeChannel as l, EventSubscription as m, RunHandle as n, JsonMergePatch as nt, createDevHooks as o, EventHandler as p, SetupArgs as q, SyncHandle as r, JsonPatchOp as rt, PredictionWarning as s, DevHooksCtx as t, sub as tt, BridgeMessage as u, PlayScreenMessage as v, SyncConfig as w, SeatKind as x, PlayerVoiceState as y, ServerActionArgs as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as applyJsonMergePatch, A as DEFAULT_ICON_URLS, B as ServerActionContext, C as SetFn, D as ActionContext, E as ActionArgs, F as GameLogic, G as ServerOnlyActionContext, H as ServerActionMap, I as SERVER_TIME, J as SetupContext, K as ServerOnlyActionHandlerFn, L as Seat, M as DeadlineArgs, N as DeadlineContext, O as ActionHandler, P as Emit, Q as JsonPatchOp, R as SeededRandom, S as SendAction, T as Operation, U as ServerEvent, V as ServerActionHandler, W as ServerOnlyAction, X as UpdateContext, Y as UpdateArgs, Z as JsonMergePatch, _ as PayloadMap, a as attachDevHooks, b as PlayersChangedMessage, c as getPredictionWarnings, d as ConnectionCallbacks, et as applyJsonPatch, f as ConnectionState, g as PatchFn, h as GameConfig, i as UzuDevHooks, j as Deadline, k as ActionMap, l as BridgeChannel, m as EventSubscription, n as RunHandle, o as createDevHooks, p as EventHandler, q as SetupArgs, r as SyncHandle, s as PredictionWarning, t as DevHooksCtx, u as BridgeMessage, v as PlayScreenMessage, w as SyncConfig, x as SeatKind, y as PlayerVoiceState, z as ServerActionArgs } from "./dev-hooks-ClWM8HzI.js";
+import { $ as minus, A as DEFAULT_ICON_URLS, B as ServerActionContext, C as SetFn, D as ActionContext, E as ActionArgs, F as GameLogic, G as ServerOnlyActionContext, H as ServerActionMap, I as SERVER_TIME, J as SetupContext, K as ServerOnlyActionHandlerFn, L as Seat, M as DeadlineArgs, N as DeadlineContext, O as ActionHandler, P as Emit, Q as GameTime, R as SeededRandom, S as SendAction, T as Operation, U as ServerEvent, V as ServerActionHandler, W as ServerOnlyAction, X as UpdateContext, Y as UpdateArgs, Z as Duration, _ as PayloadMap, a as attachDevHooks, at as applyJsonPatch, b as PlayersChangedMessage, c as getPredictionWarnings, d as ConnectionCallbacks, et as plus, f as ConnectionState, g as PatchFn, h as GameConfig, i as UzuDevHooks, it as applyJsonMergePatch, j as Deadline, k as ActionMap, l as BridgeChannel, m as EventSubscription, n as RunHandle, nt as JsonMergePatch, o as createDevHooks, p as EventHandler, q as SetupArgs, r as SyncHandle, rt as JsonPatchOp, s as PredictionWarning, t as DevHooksCtx, tt as sub, u as BridgeMessage, v as PlayScreenMessage, w as SyncConfig, x as SeatKind, y as PlayerVoiceState, z as ServerActionArgs } from "./dev-hooks-BYl_jrcy.js";
 //#region ../engine-core/src/random.d.ts
 declare class SeededRandomImpl implements SeededRandom {
   private _state;
@@ -32,12 +32,18 @@ declare function isServerOnlyAction<S>(handler: ActionHandler<S> | ServerActionH
 //#endregion
 //#region src/server-clock.d.ts
 /**
- * サーバー時刻の推定値 (ms)。
+ * ゲーム内時刻の推定値。停止中は凍る。
  *
  * カウントダウン描画のように毎秒/毎フレーム呼ぶ用途を想定しているので、
  * state の到着とは無関係にいつでも呼べる。
  */
-declare function serverNow(): number;
+declare function gameTime(): GameTime;
+//#endregion
+//#region src/pause-state.d.ts
+/** 緊急停止中か。 */
+declare function isPaused(): boolean;
+/** 停止状態の変化を購読する。 */
+declare function onPauseChange(cb: (paused: boolean) => void): void;
 //#endregion
 //#region src/room.d.ts
 type RoomMessageHandler = (data: Record<string, unknown>) => void;
@@ -199,4 +205,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;
 declare function sync<S>(config: SyncConfig<S>): 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 Emit, type EventHandler, type EventSubscription, type GameConfig, type GameLogic, type JsonMergePatch, type JsonPatchOp, type Operation, type PatchFn, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, Room, type RoomLike, type RunHandle, SERVER_TIME, 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 SetFn, type SetupArgs, type SetupContext, type SyncConfig, type SyncHandle, type UpdateArgs, type UpdateContext, type UzuDevHooks, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, getPredictionWarnings, getRoom, init, isHosted, isServerOnlyAction, on, onPlayersChanged, onRoom, playBgm, playSound, run, send, serverNow, serverOnly, setMicEnabled, stopBgm, sync };
+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, type GameConfig, type GameLogic, type GameTime, type JsonMergePatch, type JsonPatchOp, type Operation, type PatchFn, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, Room, type RoomLike, type RunHandle, SERVER_TIME, 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 SetFn, type SetupArgs, type SetupContext, type SyncConfig, type SyncHandle, type UpdateArgs, type UpdateContext, type UzuDevHooks, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub, sync };

package/dist/index.js

@@ -8,6 +8,180 @@ const DEFAULT_ICON_URLS = [
 	"https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/43f45d11-da38-4d6e-637d-3df78e583500/original"
 ];
 //#endregion
+//#region ../engine-core/src/game-time.ts
+/**
+* エンジン内部で素の ms へ落とす。**パッケージの公開 API には出さない** (`index.ts` を見よ)。
+*
+* 公開すると `toMs(a) - toMs(b)` と書けてしまい brand の保護が丸ごと消える。
+* 差を取る正当な用途は `minus` が既に埋めているので、外へ出す理由が無い。
+* 外部 API へ素の数値を渡したいという実需が出たら、そのとき足す。
+*/
+const toMs = (t) => t;
+/**
+* `GameTime` に長さを足す。
+*
+* 算術は型で止まるので、`GameTime` を作り直す道はこの関数と `ctx.after` に限られる。
+*/
+const plus = (t, d) => toMs(t) + d;
+/** `GameTime` から長さを引く。`plus(t, -d)` と書かせないための対。 */
+const sub = (t, d) => toMs(t) - d;
+/** 2 つの `GameTime` の差 (ms)。 */
+const minus = (a, b) => toMs(a) - toMs(b);
+/**
+* エンジン内部専用。作家コードから呼ばない。
+*
+* 時計の実装 (play-server の facet / dev-server / ソロ / SDK の補間) だけがここを通る。
+*/
+const asGameTime = (ms) => ms;
+//#endregion
+//#region ../engine-core/src/game-clock.ts
+/**
+* @docs
+* - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
+*
+* ゲーム内時計の実体。3 つのサーバー実装 (play-server の facet / cli の dev-server /
+* SDK のソロ) が同じ挙動になるよう、時計の算術と凍結の出入りをここ 1 箇所に置く。
+*
+* ここに置かないもの: 永続化・tick ループ・broadcast・無人凍結の発火条件。
+* それらはランタイムごとに手段が違うので、各実装が持つ。
+*/
+/**
+* ゲーム開始からの経過時間を数える時計。停止中は進まない。
+*
+* 実体はスカラー 3 本。シナリオの state は 1 バイトも書き換えない (どのフィールドが
+* 時刻かエンジンは知らないので書き換えられない)。
+*/
+var GameClock = class {
+	constructor() {
+		this.startedAtWall = 0;
+		this.pausedTotalMs = 0;
+		this.pausedAtWall = null;
+		this.frozenBy = /* @__PURE__ */ new Set();
+	}
+	/** 時計を 0 から始め直す。`setup()` を呼ぶ直前に通す。 */
+	restart() {
+		this.startedAtWall = Date.now();
+		this.pausedTotalMs = 0;
+		this.pausedAtWall = null;
+		this.frozenBy.clear();
+	}
+	get frozen() {
+		return this.frozenBy.size > 0;
+	}
+	isFrozenBy(reason) {
+		return this.frozenBy.has(reason);
+	}
+	/**
+	* 現在のゲーム内時刻。停止中は `pausedAtWall` で凍るので同じ値を返し続ける。
+	*
+	* IMPORTANT: [withGameClock] の中で呼んではいけない。実装が `Date.now()` を読むので、
+	* 差し替え済みの時刻を実時刻として引き算し、大きく負の値になる。
+	* ハンドラへ渡す時刻は必ず外で 1 回取ってから渡すこと。
+	*/
+	now() {
+		return asGameTime((this.pausedAtWall ?? Date.now()) - this.startedAtWall - this.pausedTotalMs);
+	}
+	/** ゲーム内時刻を、alarm / setTimeout が使う実時刻へ直す。 */
+	toWall(at) {
+		return toMs(at) + this.startedAtWall + this.pausedTotalMs;
+	}
+	/** 実際に理由を足したら true。呼び出し側が永続化や tick 停止の要否に使う。 */
+	freeze(reason) {
+		if (this.frozenBy.has(reason)) return false;
+		const wasFrozen = this.frozen;
+		this.frozenBy.add(reason);
+		if (!wasFrozen) this.pausedAtWall = Date.now();
+		return true;
+	}
+	/** 実際に理由を外したら true。 */
+	unfreeze(reason) {
+		if (!this.frozenBy.delete(reason)) return false;
+		if (!this.frozen && this.pausedAtWall !== null) {
+			this.pausedTotalMs += Date.now() - this.pausedAtWall;
+			this.pausedAtWall = null;
+		}
+		return true;
+	}
+	snapshot() {
+		return {
+			startedAtWall: this.startedAtWall,
+			pausedTotalMs: this.pausedTotalMs,
+			pausedAtWall: this.pausedAtWall,
+			frozenBy: [...this.frozenBy]
+		};
+	}
+	/**
+	* 永続化した内容から復元する。欠損は「未停止」に倒す。
+	*
+	* 読めなかったせいで世界が止まったままになる方が、動き出すより悪い。
+	*/
+	restore(saved) {
+		this.startedAtWall = saved.startedAtWall ?? 0;
+		this.pausedTotalMs = saved.pausedTotalMs ?? 0;
+		this.pausedAtWall = saved.pausedAtWall ?? null;
+		this.frozenBy.clear();
+		for (const reason of saved.frozenBy ?? []) this.frozenBy.add(reason);
+		if (this.frozen && this.pausedAtWall === null) this.frozenBy.clear();
+	}
+};
+/**
+* 作家の**同期**ハンドラを、時刻 API を差し替えた状態で走らせる。
+*
+* `sdk/src/dev-prediction-traps.ts` の runPredicted と同じ形。あちらは dev で警告を
+* 出すための差し替えだが、こちらはゲーム内時計を返すための差し替え。
+* `await` を挟まないので、JS が単一スレッドである以上ほかの部屋と混ざらない。
+*
+* IMPORTANT: 3 実装すべてで通すこと。ここが片方だけだと、生 `Date.now()` を書いた
+* シナリオが「dev では壊れるのに本番では動く」(あるいはその逆) になる。
+*
+* 適用しないもの:
+* - `serverActions` — async なので `await` をまたぐと復元が効かない
+* - `deadlines[].at()` — state だけの純関数という契約があり、毎 state 変更で呼ばれる
+*
+* IMPORTANT: `fn` は**同期で完結すること**。`await` をまたぐと差し替えたまま制御が
+* 抜け、無関係な処理まで偽の `Date.now` を読む。`fn` が Promise を返す形にしたく
+* なったら、それは `serverActions` 側へ寄せるべき処理という合図。
+*
+* IMPORTANT: `fn` の中で [GameClock.now] を呼ばないこと。差し替えた `Date.now` を
+* 実時刻として引き算してしまう。ハンドラへ渡す ctx は呼び出す前に組み立てる。
+*/
+function withGameClock(time, fn) {
+	const realNow = Date.now;
+	const RealDate = Date;
+	const ms = toMs(time);
+	Date.now = () => ms;
+	globalThis.Date = new Proxy(RealDate, { construct: (target, args) => Reflect.construct(target, args.length === 0 ? [ms] : args) });
+	try {
+		return fn();
+	} finally {
+		globalThis.Date = RealDate;
+		Date.now = realNow;
+	}
+}
+/**
+* `deadlines[].at()` が返した値を締切として使えるかに正規化する。使えなければ null。
+*
+* `null` / `undefined` は「締切なし」で正常なので黙って捨てる。**数値だが有限でない
+* (NaN / Infinity) 場合だけは記録に残す。** これはほぼ確実に `undefined` を含む算術の
+* 結果で、旧 `ctx.now` を読んでいるシナリオを新エンジンで動かすと
+* `undefined + 尺 = NaN` になり、締切が「二度と来ない」形で静かに死ぬ。
+* 黙って捨てるとログにも例外にも出ないので、key ごとに 1 回だけ必ず出す。
+*
+* `report` を受け取るのは、engine-core が `console` を含むどのランタイム API にも
+* 依存できないため (3 ランタイムが lib ES2022 だけでこのファイルを共有している)。
+*
+* @param warned 既に警告した key。呼び出し側がインスタンスごとに持つ。
+*/
+function resolveDeadline(at, key, warned, report) {
+	if (at === null || at === void 0) return null;
+	if (typeof at === "number" && Number.isFinite(at)) return asGameTime(at);
+	if (!warned.has(key)) {
+		warned.add(key);
+		report(`deadline "${key}" の at() が締切に使えない値を返した: ${String(at)}。この締切は二度と発火しない。廃止された ctx.now を読んでいないか確認すること`);
+	}
+	return null;
+}
+//#endregion
 //#region ../engine-core/src/json-patch.ts
 function unescapePointer(token) {
 	return token.replace(/~1/g, "/").replace(/~0/g, "~");
@@ -101,35 +275,119 @@ function isServerOnlyAction(handler) {
 /**
 * @docs
 * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+* - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
 *
-* サーバー時刻の推定値をクライアント全体へ配る。
+* サーバーのゲーム内時計の推定値をクライアント全体へ配る。
 *
-* state に入っている `endsAt` のような絶対時刻はサーバーの時計で打たれている。
-* それを端末の `Date.now()` と引き算すると、端末の時計ズレがそのまま表示のズレになる
-* (残り時間が恒久的に狂う / 期限判定がサーバーと食い違う)。読み取り側も同じ時計に
-* 揃えるための関数。
+* state に入っている `endsAt` のような締切はサーバーのゲーム内時計で打たれている。
+* 読み取り側も同じ時計に揃えないと、残り時間が恒久的に狂う。
 *
 * ```ts
-* const remain = Math.ceil((state.game.timerEndsAt - serverNow()) / 1000);
+* const remain = Math.ceil(minus(state.game.timerEndsAt, gameTime()) / 1000);
 * ```
 *
+* 基準は `performance.now()` (単調時計)。`Date.now()` を長さの計算に使うと、端末の時計が
+* NTP やユーザー操作でずれた瞬間に全部のカウントダウンが飛ぶ。POSIX / Rust / C++ が
+* 揃って禁じている形なので、ここでも採らない。
+*
 * オフセットは transport がサーバーからのメッセージを受けるたびに更新する。
-* 未接続 / 未観測ならローカル時刻をそのまま返す (オフラインでも壊れない)。
+* 未接続 / 未観測ならオフセット 0 のまま (オフラインでも壊れない)。
 */
 let offset = 0;
-/** transport から呼ぶ内部関数。サーバーが打刻した時刻を観測してオフセットを更新する。 */
-function observeServerTime(serverTime) {
-	if (typeof serverTime !== "number" || !Number.isFinite(serverTime)) return;
-	offset = serverTime - Date.now();
+/** 停止中に凍らせた値。null なら進んでいる。 */
+let frozenAt = null;
+/**
+* transport から呼ぶ内部関数。サーバーが打刻したゲーム内時刻を観測してオフセットを更新する。
+*
+* 下り片道遅延を無視するので推定は実サーバー時刻より僅かに遅れる。
+* 表示用途では無視できる誤差なので、精度より単純さを取る。
+*/
+function observeGameTime(t) {
+	if (typeof t !== "number" || !Number.isFinite(t)) return;
+	offset = t - performance.now();
 }
 /**
-* サーバー時刻の推定値 (ms)。
+* ゲーム内時刻の推定値。停止中は凍る。
 *
 * カウントダウン描画のように毎秒/毎フレーム呼ぶ用途を想定しているので、
 * state の到着とは無関係にいつでも呼べる。
 */
-function serverNow() {
-	return Date.now() + offset;
+function gameTime() {
+	return frozenAt ?? asGameTime(performance.now() + offset);
+}
+/**
+* 時計を凍らせる。
+*
+* 停止中はサーバーの broadcast が止まって打刻が来ないので、`__pause_state` を受けた
+* 時点の値で明示的に止める。解除後は通常の打刻でオフセットが入れ替わるため、
+* 特別な補正は要らない。
+*/
+function freezeGameTime() {
+	frozenAt = gameTime();
+}
+function unfreezeGameTime() {
+	frozenAt = null;
+}
+//#endregion
+//#region src/pause-state.ts
+/**
+* @docs
+* - 緊急停止とゲーム内時計: docs/docs/uzu_code/emergency-stop.md
+*
+* 緊急停止の状態を SDK 全体で 1 箇所に持つ。
+*
+* 停止は state ではない。シナリオの state に持ち込むと「停止中は state を変えるコードが
+* 1 行も走らない」という不変条件が崩れるので、`GameLogic` へは渡さず読み取り専用の
+* 関数として出す。用途は演出の停止 (rAF ループを止める等) に限る。
+*
+* ゲーム内時計の凍結もここから駆動する。停止フラグと時計の凍結が別々に動くと、
+* 「止まっているのにカウントダウンだけ進む」がいつか必ず起きる。
+*/
+let paused = false;
+let pausedBy = null;
+const listeners = /* @__PURE__ */ new Set();
+/** transport から呼ぶ内部関数。停止状態が変わったときだけ通知する。 */
+function 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] onPauseChange listener threw:", err);
+	}
+}
+/** 緊急停止中か。 */
+function isPaused() {
+	return paused;
+}
+/** 停止を要求した playerId。停止していなければ null。 */
+function getPausedBy() {
+	return pausedBy;
+}
+/** 停止状態の変化を購読する。 */
+function onPauseChange(cb) {
+	listeners.add(cb);
+}
+let requester = null;
+function setPauseRequester(fn) {
+	requester = fn;
+}
+function requestPause() {
+	if (!requester) {
+		console.warn("[uzu] requestPause: サーバーへ接続していないので停止できません");
+		return;
+	}
+	requester(true);
+}
+function requestResume() {
+	if (!requester) {
+		console.warn("[uzu] requestResume: サーバーへ接続していないので解除できません");
+		return;
+	}
+	requester(false);
 }
 //#endregion
 //#region src/room.ts
@@ -578,61 +836,75 @@ function replaceRoot(doc, value) {
 }
 //#endregion
 //#region src/dev-prediction-traps.ts
-const TRAPS = [
-	{ install: (report) => {
-		const RealDate = Date;
-		const realNow = Date.now;
-		globalThis.Date = new Proxy(RealDate, { construct: (target, args) => {
-			if (args.length === 0) report("new Date()");
-			return Reflect.construct(target, args);
-		} });
-		Date.now = () => {
-			report("Date.now()");
-			return realNow();
-		};
-		return () => {
-			Date.now = realNow;
-			globalThis.Date = RealDate;
-		};
-	} },
-	{ install: (report) => {
-		const real = Math.random;
-		Math.random = () => {
-			report("Math.random()");
-			return real();
-		};
-		return () => {
-			Math.random = real;
-		};
-	} },
-	{ install: (report) => {
-		const real = globalThis.crypto?.randomUUID;
-		if (!real) return () => {};
-		const bound = real.bind(globalThis.crypto);
-		globalThis.crypto.randomUUID = () => {
-			report("crypto.randomUUID()");
-			return bound();
-		};
-		return () => {
-			globalThis.crypto.randomUUID = real;
-		};
-	} },
-	{ install: (report) => {
-		const real = globalThis.performance?.now;
-		if (!real) return () => {};
-		const bound = real.bind(globalThis.performance);
-		globalThis.performance.now = () => {
-			report("performance.now()");
-			return bound();
-		};
-		return () => {
-			globalThis.performance.now = real;
-		};
-	} }
-];
+/** 描画経路の警告に使う擬似 action 名。 */
+const RENDER_CONTEXT = "(render)";
+const CLOCK_TRAPS = [{ install: (report) => {
+	const RealDate = Date;
+	const realNow = Date.now;
+	globalThis.Date = new Proxy(RealDate, { construct: (target, args) => {
+		if (args.length === 0) report("new Date()");
+		return Reflect.construct(target, args);
+	} });
+	Date.now = () => {
+		report("Date.now()");
+		return realNow();
+	};
+	return () => {
+		Date.now = realNow;
+		globalThis.Date = RealDate;
+	};
+} }, { install: (report) => {
+	const real = globalThis.performance?.now;
+	if (!real) return () => {};
+	const bound = real.bind(globalThis.performance);
+	globalThis.performance.now = () => {
+		report("performance.now()");
+		return bound();
+	};
+	return () => {
+		globalThis.performance.now = real;
+	};
+} }];
+/** 乱数系。先読みでだけ問題になるので描画経路には張らない。 */
+const RANDOM_TRAPS = [{ install: (report) => {
+	const real = Math.random;
+	Math.random = () => {
+		report("Math.random()");
+		return real();
+	};
+	return () => {
+		Math.random = real;
+	};
+} }, { install: (report) => {
+	const real = globalThis.crypto?.randomUUID;
+	if (!real) return () => {};
+	const bound = real.bind(globalThis.crypto);
+	globalThis.crypto.randomUUID = () => {
+		report("crypto.randomUUID()");
+		return bound();
+	};
+	return () => {
+		globalThis.crypto.randomUUID = real;
+	};
+} }];
+const TRAPS = [...CLOCK_TRAPS, ...RANDOM_TRAPS];
 const warnings = [];
 const reported = /* @__PURE__ */ new Set();
 const printWarning = (action, api) => {
+	if (action === RENDER_CONTEXT) {
+		console.groupCollapsed(`⚠️ [uzu-code] 描画中に ${api} を呼びました`);
+		console.log([
+			`${api} は Unix epoch の実時刻を返します。state に入っている締切は`,
+			"ゲーム内時刻 (ゲーム開始からの経過 ms) なので、引き算すると桁が合いません。",
+			"また実時刻は緊急停止中も進むので、止まっているのにカウントダウンだけ動きます。",
+			"",
+			"直し方: 時刻は gameTime() から取る。",
+			"  import { gameTime, minus } from '@uzuhq/code-sdk';",
+			"  const remain = Math.ceil(minus(state.timerEndsAt, gameTime()) / 1000);"
+		].join("\n"));
+		console.groupEnd();
+		return;
+	}
 	console.groupCollapsed(`⚠️ [uzu-code] action "${action}" が先読み中に ${api} を呼びました`);
 	console.log([
 		"先読み (楽観的更新) は「サーバーと同じコードを同じ入力で走らせれば同じ結果になる」",
@@ -670,12 +942,24 @@ const notifyParent = (action, api) => {
 * Flutter native ホスト (本番) では計装せず素通しする。判定基準は dev hooks と同じ。
 */
 const runPredicted = (action, run) => {
+	runInstrumented(action, run);
+};
+/**
+* `onState` から同期で走る描画を計装する。
+*
+* 乱数は描画で使ってよいので、時刻の罠だけ張る。ここで拾えるのは同期の描画だけで、
+* `requestAnimationFrame` の中は原理的に拾えない。
+*/
+const runRendered = (run) => {
+	runInstrumented(RENDER_CONTEXT, run);
+};
+const runInstrumented = (action, run) => {
 	if (typeof window === "undefined" || window.FlutterHost) {
 		run();
 		return;
 	}
 	const report = (api) => {
-		const key = `${action}${api}`;
+		const key = `${action}\u0000${api}`;
 		if (reported.has(key)) return;
 		reported.add(key);
 		warnings.push({
@@ -685,7 +969,7 @@ const runPredicted = (action, run) => {
 		printWarning(action, api);
 		notifyParent(action, api);
 	};
-	const restores = TRAPS.map((trap) => trap.install(report));
+	const restores = (action === RENDER_CONTEXT ? CLOCK_TRAPS : TRAPS).map((trap) => trap.install(report));
 	try {
 		run();
 	} finally {
@@ -810,7 +1094,7 @@ function createOptimisticActionClient(config) {
 	let actionSeq = 0;
 	/**
 	* 送信済みだがサーバー未確認の action キュー。
-	* `now` は送信時に推定した値。再適用でも同じ値を使う (取り直すと表示がガタつく)。
+	* `time` は送信時に推定した値。再適用でも同じ値を使う (取り直すと表示がガタつく)。
 	*/
 	const pendingActions = [];
 	/**
@@ -866,7 +1150,7 @@ function createOptimisticActionClient(config) {
 		displayState = structuredClone(confirmedState);
 		let i = 0;
 		while (i < pendingActions.length) {
-			const { action, payload, now } = pendingActions[i];
+			const { action, payload, time } = pendingActions[i];
 			const handler = logic.actions[action];
 			if (!handler || isServerOnlyAction(handler)) {
 				pendingActions.splice(i, 1);
@@ -879,7 +1163,8 @@ function createOptimisticActionClient(config) {
 					payload,
 					playerId,
 					ctx: {
-						now,
+						time,
+						after: (d) => plus(time, d),
 						emit: noopEmit
 					}
 				}));
@@ -906,12 +1191,16 @@ function createOptimisticActionClient(config) {
 	};
 	return {
 		send(type, payload) {
+			if (isPaused()) {
+				console.warn(`[uzu] 緊急停止中は action を送れません (action="${type}")`);
+				return;
+			}
 			actionSeq++;
 			const seq = actionSeq;
 			const handler = logic.actions[type];
 			if (!handler && !logic.serverActions?.[type]) console.error(`[uzu] unknown action: "${type}". logic.actions / logic.serverActions のどちらにも登録されていません。`);
 			const target = displayState;
-			const now = serverNow();
+			const time = gameTime();
 			const predictEmit = (eventName, data) => {
 				const subscription = events?.[eventName];
 				if (!subscription?.predict) return;
@@ -929,7 +1218,8 @@ function createOptimisticActionClient(config) {
 					payload: payload ?? {},
 					playerId,
 					ctx: {
-						now,
+						time,
+						after: (d) => plus(time, d),
 						emit: predictEmit
 					}
 				}));
@@ -937,7 +1227,7 @@ function createOptimisticActionClient(config) {
 					seq,
 					action: type,
 					payload: payload ?? {},
-					now
+					time
 				});
 				onState(target, playerId);
 			} catch {}
@@ -947,8 +1237,8 @@ function createOptimisticActionClient(config) {
 				seq
 			});
 		},
-		observeServerTime(serverTime) {
-			observeServerTime(serverTime);
+		observeGameTime(t) {
+			observeGameTime(t);
 		},
 		applyState(state, options = {}) {
 			handleAck(options.ack, options.from, options.events ?? []);
@@ -1013,6 +1303,10 @@ function 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" }));
+	});
 	/** サーバー seq (delta の連続性チェック用) */
 	let serverSeq = 0;
 	/** フル state 再要求中フラグ (多重要求防止) */
@@ -1052,7 +1346,13 @@ function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, se
 		}
 		const msgType = parsed.type;
 		console.log(`[SDK ServerAction] ⬅ recv type=${msgType}`);
-		client.observeServerTime(parsed.serverTime);
+		client.observeGameTime(parsed.gameTime);
+		if (msgType === "__pause_state") {
+			const frozen = parsed.frozen === true;
+			console.log(`[SDK ServerAction] ${frozen ? "⏸" : "▶️"} pause_state frozen=${frozen}`);
+			setPauseState(frozen, parsed.by ?? null);
+			return;
+		}
 		if (msgType === "__room_init") {
 			console.log(`[SDK ServerAction] ✅ Room init myId=${parsed.myId}`);
 			return;
@@ -1130,6 +1430,7 @@ function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, se
 			serverSeq = parsed.seq ?? 0;
 			requestStatePending = false;
 			console.log(`[SDK ServerAction] 🔄 State restored (reconnect/late join) seq=${serverSeq}`);
+			setPauseState(parsed.frozen === true, parsed.pausedBy ?? null);
 			client.reset(parsed.state);
 			return;
 		}
@@ -1139,8 +1440,21 @@ function runOnlineServerAction(config, gameEndpoint, roomId, seatId, players, se
 //#region src/run/local-server-action.ts
 function runLocalServerAction(config) {
 	const { logic, inputs, events } = config;
-	const onState = (next, id) => config.onState(next, id, "player");
+	const onState = (next, id) => {
+		observeGameTime(gameTime());
+		config.onState(next, id, "player");
+	};
 	const tickRate = logic.tickRate ?? 0;
+	const clock = new GameClock();
+	const gameTime = () => clock.now();
+	const frozen = () => clock.frozen;
+	/** ハンドラへ渡す ctx の時刻部分。1 回の呼び出し内で値が動かないよう束ねる。 */
+	const timeCtx = (t) => ({
+		time: t,
+		after: (d) => plus(t, d)
+	});
+	/** at() が壊れた値を返したと既に記録した締切。ログを 1 回に絞るため。 */
+	const warnedDeadlines = /* @__PURE__ */ new Set();
 	const random = new SeededRandomImpl(Math.floor(Math.random() * 4294967295));
 	const players = Array.from({ length: config.playerCount }, (_, i) => ({
 		id: `local_${i}`,
@@ -1154,14 +1468,15 @@ function runLocalServerAction(config) {
 		if (!logic.deadlines) return null;
 		let earliest = null;
 		for (const [key, deadline] of Object.entries(logic.deadlines)) {
-			let at;
+			let raw;
 			try {
-				at = deadline.at({ state });
+				raw = deadline.at({ state });
 			} catch (err) {
 				console.error(`[Deadline] ❌ ${key}.at() で例外`, err);
 				continue;
 			}
-			if (typeof at !== "number" || !Number.isFinite(at)) continue;
+			const at = resolveDeadline(raw, key, warnedDeadlines, (m) => console.error(`[Deadline] ❌ ${m}`));
+			if (at === null) continue;
 			if (earliest === null || at < earliest) earliest = at;
 		}
 		return earliest;
@@ -1169,28 +1484,28 @@ function runLocalServerAction(config) {
 	const fireDue = () => {
 		wakeupTimer = null;
 		wakeupAt = null;
-		if (!logic.deadlines) return;
-		const now = Date.now();
+		if (!logic.deadlines || frozen()) return;
+		const time = gameTime();
 		const evts = [];
 		const firedKeys = [];
 		for (const [key, deadline] of Object.entries(logic.deadlines)) {
 			const pending = [];
 			let snapshot = null;
 			try {
-				const at = deadline.at({ state });
-				if (typeof at !== "number" || !Number.isFinite(at) || at > now) continue;
+				const at = resolveDeadline(deadline.at({ state }), key, warnedDeadlines, (m) => console.error(`[Deadline] ❌ ${m}`));
+				if (at === null || at > time) continue;
 				snapshot = structuredClone(state);
-				deadline.handler({
+				withGameClock(time, () => deadline.handler({
 					state,
 					ctx: {
-						now,
+						...timeCtx(time),
 						random,
 						emit: (name, data) => pending.push({
 							name,
 							data: data ?? {}
 						})
 					}
-				});
+				}));
 				evts.push(...pending);
 				firedKeys.push(key);
 			} catch (err) {
@@ -1205,29 +1520,35 @@ function runLocalServerAction(config) {
 		onState(state, myId);
 	};
 	const syncWakeup = () => {
-		const next = nextDeadline();
+		const next = frozen() ? null : nextDeadline();
 		if (next === wakeupAt) return;
 		if (wakeupTimer) clearTimeout(wakeupTimer);
 		wakeupTimer = null;
 		wakeupAt = next;
 		if (next === null) return;
-		wakeupTimer = setTimeout(fireDue, Math.max(0, next - Date.now()));
+		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);
 	};
+	clock.restart();
+	const setupTime = gameTime();
 	const setupArgs = {
 		players,
 		seats: players,
 		ctx: {
 			random,
-			now: Date.now()
+			...timeCtx(setupTime)
 		}
 	};
-	let state = logic.setup(setupArgs);
+	let state = withGameClock(setupTime, () => logic.setup(setupArgs));
 	let tick = 0;
 	const playerInputs = {};
 	const dispatchAction = (type, payload) => {
+		if (frozen()) {
+			console.warn(`[SDK LocalServerAction] 緊急停止中は action を実行しません (action="${type}")`);
+			return;
+		}
 		const plain = logic.actions[type];
 		const legacyServerOnly = isServerOnlyAction(plain) ? plain : null;
 		const server = logic.serverActions?.[type] ?? legacyServerOnly;
@@ -1242,18 +1563,18 @@ function runLocalServerAction(config) {
 			name,
 			data: data ?? {}
 		});
-		const now = Date.now();
+		const time = gameTime();
 		if (plain && !legacyServerOnly) {
 			try {
-				plain({
+				withGameClock(time, () => plain({
 					state,
 					payload: payload ?? {},
 					playerId: myId,
 					ctx: {
-						now,
+						...timeCtx(time),
 						emit: plainEmit
 					}
-				});
+				}));
 			} catch (err) {
 				console.warn("[SDK LocalServerAction] Action error:", err);
 				return;
@@ -1272,7 +1593,7 @@ function runLocalServerAction(config) {
 					ctx: {
 						tick,
 						random,
-						now,
+						...timeCtx(time),
 						emit: serverEmit
 					}
 				});
@@ -1285,26 +1606,42 @@ function runLocalServerAction(config) {
 			onState(state, myId);
 		})();
 	};
+	/**
+	* ソロの停止 / 解除。サーバーが居ないので自分の時計を直接触る。
+	*
+	* `__uzu_dev.pauseTick()` とは別物。あちらは tick を止めるだけの開発者ツールで、
+	* ゲーム内時計も action ゲートも持たない。流用しない。
+	*/
+	const applyPause = (paused) => {
+		if (!(paused ? clock.freeze("emergency-stop") : clock.unfreeze("emergency-stop"))) return;
+		observeGameTime(gameTime());
+		setPauseState(paused, paused ? myId : null);
+		observeGameTime(gameTime());
+		syncWakeup();
+	};
+	setPauseRequester(applyPause);
 	inputs(dispatchAction);
 	syncWakeup();
 	onState(state, myId);
 	if (tickRate > 0) setInterval(() => {
+		if (frozen()) return;
 		const tickEvents = [];
 		const tickEmit = (name, data) => tickEvents.push({
 			name,
 			data: data ?? {}
 		});
+		const time = gameTime();
 		try {
-			logic.update({
+			withGameClock(time, () => logic.update({
 				state,
 				ctx: {
 					random,
 					tick,
-					now: Date.now(),
+					...timeCtx(time),
 					emit: tickEmit,
 					playerInputs
 				}
-			});
+			}));
 		} catch (err) {
 			console.error(`[SDK LocalServerAction] tick error at tick=${tick}:`, err);
 			tick++;
@@ -1615,6 +1952,12 @@ function init(opts) {
 		const { x: fallbackX, y: fallbackY } = calcHudInsets(params);
 		document.documentElement.style.setProperty("--uzu-hud-inset-x", `${hudX ?? fallbackX}px`);
 		document.documentElement.style.setProperty("--uzu-hud-inset-y", `${hudY ?? fallbackY}px`);
+		onPauseChange((paused) => {
+			sendRaw("sdk", "pauseState", {
+				paused,
+				by: getPausedBy()
+			});
+		});
 		sendRaw("sdk", "ready", {});
 		_initialized = true;
 	}
@@ -1716,7 +2059,7 @@ function run(config) {
 				serverTime: 0,
 				myId: myPlayerId
 			};
-			origOnState(state, myPlayerId, mySeatKind);
+			runRendered(() => origOnState(state, myPlayerId, mySeatKind));
 			notifyDevSnapshot(state);
 		}
 	};
@@ -1848,6 +2191,14 @@ function handleMessage(msg) {
 				_playersChangedHandlers.forEach((fn) => fn(players));
 				return;
 			}
+			case "requestPause":
+				console.log(`[SDK] ⏸ handleMessage sdk/requestPause`);
+				requestPause();
+				return;
+			case "requestResume":
+				console.log(`[SDK] ▶️ handleMessage sdk/requestResume`);
+				requestResume();
+				return;
 		}
 		return;
 	}
@@ -1886,4 +2237,4 @@ function calcHudInsets(params) {
 	};
 }
 //#endregion
-export { DEFAULT_ICON_URLS, ReconnectableWebSocket, Room, SERVER_TIME, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, getPredictionWarnings, getRoom, init, isHosted, isServerOnlyAction, on, onPlayersChanged, onRoom, playBgm, playSound, run, send, serverNow, serverOnly, setMicEnabled, stopBgm, sync };
+export { DEFAULT_ICON_URLS, ReconnectableWebSocket, Room, SERVER_TIME, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub, sync };

package/package.json

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