@uzuhq/code-sdk 0.7.0 → 0.7.2

package/README.md

@@ -219,61 +219,99 @@ run({
 ### GameLogic
 
 ```ts
-import { serverOnly, type GameLogic } from '@uzuhq/code-sdk';
+import type { GameLogic } from '@uzuhq/code-sdk';
 
 const logic: GameLogic<MyState> = {
-  setup(seats, random) {
-    // 初期 state を生成。random は SeededRandom。
+  setup({ seats, ctx }) {
+    // 初期 state を生成。ctx.random は SeededRandom、ctx.now はサーバーの実時刻。
     // seats には観戦系の席 (kind: 'spectator' | 'admin') も含まれ得るため、
     // ゲームの席は kind === 'player' に絞る
     return { players: {}, items: [] };
   },
 
+  // クライアント先読みとサーバーの 2 回走る。決定的でなければならない。
   actions: {
-    move(state, payload, playerId, emit, ctx) {
+    move({ state, payload, playerId, ctx }) {
       // state を直接変更する（Immer 的な mutable 操作）
       state.players[playerId].x += payload.dx;
-      // emit でイベント発火
-      emit('sound', { sound: 'step' });
-      // ctx.tick でサーバーの現在 tick を参照可能
+      // ctx.emit でイベント発火 (購読側は events で predict を宣言する)
+      ctx.emit('sound', { sound: 'step' });
+      // 時刻は ctx.now を使う。Date.now() は端末とサーバーでズレる
     },
+  },
 
-    // serverOnly(): client 先行実行をスキップしてサーバーだけで実行 (async OK)
-    notifyExternal: serverOnly(async (state, payload, playerId) => {
+  // サーバーでのみ走る。実時刻・乱数・fetch などクライアントが再現できない処理。
+  // actions と同名にすると「同じ action のサーバー側の続き」になる。
+  serverActions: {
+    async notifyExternal({ state, payload, playerId }) {
       await fetch('https://example.com/notify', {
         method: 'POST',
         body: JSON.stringify({ playerId, ...payload }),
       });
       state.notifiedAt = Date.now();
-    }),
+    },
   },
 
-  update(state, ctx) {
-    // 毎 tick 実行。ctx.tick, ctx.random, ctx.emit, ctx.playerInputs が使える
+  update({ state, ctx }) {
+    // 毎 tick 実行。ctx.tick / ctx.random / ctx.now / ctx.emit / ctx.playerInputs が使える
   },
 
-  tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし, 0 でターン制)
+  tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし)
 };
 ```
 
-| キー       | 型                                                                                                                                 | 必須 | 説明                                                                        |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------- |
-| `setup`    | `(seats: Seat[], random: SeededRandom) => S`                                                                                       | Yes  | 初期 state を生成。seats には `kind !== 'player'` の席も含まれる            |
-| `actions`  | `Record<string, ActionHandler<S> \| ServerOnlyAction<S>>`                                                                          | Yes  | アクションハンドラ。`serverOnly()` で wrap すると client 先行実行をスキップ |
-| `update`   | `(state: S, ctx: { random: SeededRandom, tick: number, emit: EmitFn, playerInputs: Record<string, Record<string, any>> }) => void` | Yes  | 毎 tick 実行                                                                |
-| `tickRate` | `number`                                                                                                                           | No   | 秒間 tick 数 (default: 0 = tick なし)                                       |
+| キー            | 型                                       | 必須 | 説明                                                             |
+| --------------- | ---------------------------------------- | ---- | ---------------------------------------------------------------- |
+| `setup`         | `(args: SetupArgs) => S`                 | Yes  | 初期 state を生成。seats には `kind !== 'player'` の席も含まれる |
+| `actions`       | `Record<string, ActionHandler<S>>`       | Yes  | クライアント先読み + サーバーの 2 回走る。決定的であること       |
+| `serverActions` | `Record<string, ServerActionHandler<S>>` | No   | サーバーでのみ走る。async 可。`ctx` に `tick` / `random` が入る  |
+| `update`        | `(args: UpdateArgs<S>) => void`          | Yes  | 毎 tick 実行 (`tickRate` が 0 なら呼ばれない)                    |
+| `tickRate`      | `number`                                 | No   | 秒間 tick 数 (default: 0 = tick なし)                            |
+
+ハンドラの引数は 1 つのオブジェクトで、使うものだけ書けばよい。
+`state` / `payload` / `playerId` はその呼び出しの事実、`ctx` は実行環境が与えるもの。
+
+#### `deadlines`
+
+「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが最も早い `at` に合わせて
+自分で起き、過ぎた締切の `handler` を呼ぶ。
+
+```ts
+deadlines: {
+  phaseTimer: {
+    at: ({ state }) => state.timerEndsAt,   // null / undefined なら締切なし
+    handler: ({ state, ctx }) => {
+      state.phase = nextPhase(state);
+      ctx.emit('phase.changed', { phase: state.phase });
+    },
+  },
+},
+```
+
+|           |                                                                                                                                                                         |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `at`      | 締切の絶対時刻 (ms)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い関数にすること** (state が変わるたびに呼ばれる) |
+| `handler` | サーバーでのみ走る。`ctx` は `{ now, random, emit }`                                                                                                                    |
+
+締切は state から導出するので、**予約を張り替える処理を書かなくてよい**。action が throw して
+state が巻き戻れば締切も一緒に巻き戻る。発火直前に `at` を評価し直すので、二重発火を
+handler 側で弾く必要も無い。
+
+時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
+ポーリング中は Durable Object が hibernate できない。
 
 #### `serverOnly(handler)`
 
-`actions` に登録する handler を「サーバーでだけ実行される」ものに変換する wrapper。
+> **Deprecated**: `serverActions` に直接書く。
 
-- クライアント側ではローカル先行実行 (楽観的更新) をスキップし、サーバーからの state delta を待つ
-- サーバー側で `await` で実行され、`fetch` などの副作用付き処理を安全に書ける
-- handler のシグネチャ: `(state, payload, playerId, emit, ctx) => Promise<void> | void`
-- 例外を投げると送信元クライアントに `__action_error` が返る (state は変更されない)
+`actions` に登録する handler を「サーバーでだけ実行される」ものに変換する旧 wrapper。
+`serverActions` フィールドが同じことを型で表現できるので、新しいコードでは使わない。
 
 ```ts
-import { serverOnly } from '@uzuhq/code-sdk';
+// before
+actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+// after
+serverActions: { notifyExternal: async ({ state }) => { ... } }
 ```
 
 ### manifest.json（run() を使う場合）

package/dist/index.d.ts

@@ -15,8 +15,8 @@
  * 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, UpdateArgs, UpdateContext, EventHandler, EventSubscription, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
-export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } 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, } 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';
 export { Room } from './room.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } 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';
 export { Room } from './room.js';

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

@@ -15,33 +15,82 @@ export function runLocalServerAction(config) {
     }));
     const myId = players[0].id;
     // イベント収集→一括配信（DO と同じパターン）
-    // ソロモードでは alarm の代わりに setTimeout で予約を実現する。
-    // key ごとに 1 件へ畳む点は本番と同じ。
-    const scheduled = new Map();
-    const makeScheduleCtx = () => ({
-        schedule(options) {
-            const at = options.at ?? Date.now() + (options.after ?? 0) * 1000;
-            const prev = scheduled.get(options.key);
-            if (prev)
-                clearTimeout(prev);
-            scheduled.set(options.key, setTimeout(() => {
-                scheduled.delete(options.key);
-                try {
-                    dispatchAction(options.action, options.payload ?? {});
-                }
-                catch (err) {
-                    console.error(`[Scheduler] ❌ key=${options.key}:`, err);
-                }
-            }, Math.max(0, at - Date.now())));
-            return at;
-        },
-        unschedule(key) {
-            const t = scheduled.get(key);
-            if (t)
-                clearTimeout(t);
-            scheduled.delete(key);
-        },
-    });
+    // ソロモードでは alarm の代わりに setTimeout で締切に起きる。締切は state から
+    // 導出するので、state を変えたら syncWakeup() を通すだけでよい。
+    let wakeupTimer = null;
+    let wakeupAt = null;
+    const nextDeadline = () => {
+        if (!logic.deadlines)
+            return null;
+        let earliest = null;
+        for (const [key, deadline] of Object.entries(logic.deadlines)) {
+            let at;
+            try {
+                at = deadline.at({ state });
+            }
+            catch (err) {
+                console.error(`[Deadline] ❌ ${key}.at() で例外`, err);
+                continue;
+            }
+            if (typeof at !== 'number' || !Number.isFinite(at))
+                continue;
+            if (earliest === null || at < earliest)
+                earliest = at;
+        }
+        return earliest;
+    };
+    const fireDue = () => {
+        wakeupTimer = null;
+        wakeupAt = null;
+        if (!logic.deadlines)
+            return;
+        const now = Date.now();
+        const evts = [];
+        const firedKeys = [];
+        for (const [key, deadline] of Object.entries(logic.deadlines)) {
+            // handler が emit してから throw したときに捨てられるよう、締切ごとに溜める。
+            // state を戻したのに音や演出だけ流れると、起きていない出来事が見えてしまう。
+            const pending = [];
+            let snapshot = null;
+            try {
+                const at = deadline.at({ state });
+                if (typeof at !== 'number' || !Number.isFinite(at) || at > now)
+                    continue;
+                // 期限が来たものだけ複製する。毎周撮ると締切の数だけ state の複製が走る。
+                snapshot = structuredClone(state);
+                deadline.handler({
+                    state,
+                    ctx: { now, random, emit: (name, data) => pending.push({ name, data: data ?? {} }) },
+                });
+                evts.push(...pending);
+                firedKeys.push(key);
+            }
+            catch (err) {
+                // サーバー (DO) 側と同じく、失敗した締切ぶんだけ巻き戻す。
+                if (snapshot !== null)
+                    state = snapshot;
+                console.error(`[Deadline] ❌ ${key} で例外`, err);
+            }
+        }
+        syncWakeup();
+        if (firedKeys.length === 0)
+            return;
+        console.log(`[Deadline] ⏰ ${firedKeys.length} 件発火: ${firedKeys.join(', ')}`);
+        dispatchEvents(evts);
+        onState(state, myId);
+    };
+    const syncWakeup = () => {
+        const next = 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()));
+    };
     // ソロモードはこのクライアント自身がサーバーなので、先読みという概念が無い。
     // predict の値によらず、確定として 1 回だけ実行する。
     const dispatchEvents = (evts) => {
@@ -50,7 +99,7 @@ export function runLocalServerAction(config) {
         }
     };
     // setRawState で全置換できるよう let。closures は名前参照なので最新束縛を読む。
-    let state = logic.setup(players, random);
+    let state = logic.setup({ seats: players, ctx: { random, now: Date.now() } });
     let tick = 0;
     const playerInputs = {};
     // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する
@@ -80,7 +129,7 @@ export function runLocalServerAction(config) {
                     state,
                     payload: payload ?? {},
                     playerId: myId,
-                    ctx: { now, emit: plainEmit, ...makeScheduleCtx() },
+                    ctx: { now, emit: plainEmit },
                 });
             }
             catch (err) {
@@ -88,6 +137,7 @@ export function runLocalServerAction(config) {
                 return;
             }
             dispatchEvents(plainEvents);
+            syncWakeup();
             onState(state, myId);
         }
         if (!server)
@@ -98,7 +148,7 @@ export function runLocalServerAction(config) {
                     state,
                     payload: payload ?? {},
                     playerId: myId,
-                    ctx: { tick, random, now, emit: serverEmit, ...makeScheduleCtx() },
+                    ctx: { tick, random, now, emit: serverEmit },
                 });
             }
             catch (err) {
@@ -106,10 +156,12 @@ export function runLocalServerAction(config) {
                 return;
             }
             dispatchEvents(serverEvents);
+            syncWakeup();
             onState(state, myId);
         })();
     };
     inputs(dispatchAction);
+    syncWakeup();
     onState(state, myId);
     // Tick ループ（tickRate > 0 の場合のみ、DO と同じ）
     if (tickRate > 0) {
@@ -123,7 +175,6 @@ export function runLocalServerAction(config) {
                         random,
                         tick,
                         now: Date.now(),
-                        ...makeScheduleCtx(),
                         emit: tickEmit,
                         playerInputs,
                     },
@@ -136,6 +187,7 @@ export function runLocalServerAction(config) {
             }
             tick++;
             dispatchEvents(tickEvents);
+            syncWakeup();
             onState(state, myId);
         }, 1000 / tickRate);
     }
@@ -143,6 +195,7 @@ export function runLocalServerAction(config) {
         getRawState: () => state,
         setRawState: async (next) => {
             state = next;
+            syncWakeup();
             onState(state, myId);
         },
         mergeRawState: async (patch) => {

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

@@ -41,18 +41,6 @@ export function createOptimisticActionClient(config) {
     };
     /** events の同一性キー。name と data が一致すれば「同じ出来事」とみなす。 */
     const eventKey = (e) => `${e.name}\u0000${JSON.stringify(e.data ?? {})}`;
-    /**
-     * 先読み用の schedule。予約自体はサーバーだけが持つので**何もしない**が、
-     * 戻り値 (確定した絶対時刻) は返す。シナリオは戻り値を表示用の endsAt として
-     * state に入れるので、ここで undefined を返すと先読み中だけタイマーが消える。
-     *
-     * 型には schedule があるのに実体を渡さないと `ctx.schedule is not a function` で
-     * 先読みが丸ごと落ちる (predicted な action から呼ばれた瞬間)。
-     */
-    const predictedScheduleCtx = (now) => ({
-        schedule: (options) => options.at != null ? Number(options.at) : now + Number(options.after ?? 0) * 1000,
-        unschedule: () => { },
-    });
     /**
      * サーバーの events から、先読みで実行済みのものを差し引く (多重集合の差)。
      *
@@ -102,7 +90,7 @@ export function createOptimisticActionClient(config) {
                     state: displayState,
                     payload,
                     playerId,
-                    ctx: { now, emit: noopEmit, ...predictedScheduleCtx(now) },
+                    ctx: { now, emit: noopEmit },
                 }));
                 i++;
             }
@@ -159,7 +147,7 @@ export function createOptimisticActionClient(config) {
                         state: target,
                         payload: payload ?? {},
                         playerId,
-                        ctx: { now, emit: predictEmit, ...predictedScheduleCtx(now) },
+                        ctx: { now, emit: predictEmit },
                     }));
                     pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
                     onState(target, playerId);

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

@@ -28,14 +28,6 @@ const makeLogic = () => ({
             state.stampedAt = ctx.now;
             ctx.emit('moved', {});
         },
-        // 先読みでも ctx.schedule を呼ぶ action。型にはあるので呼べてしまう。
-        startTimer: ({ state, ctx }) => {
-            state.stampedAt = ctx.schedule({
-                key: 'timer',
-                after: 60,
-                action: 'timer.fire',
-            });
-        },
         // 予測の結果によって別の event を出す (予測ミスの再現用)
         guess: ({ state, payload, ctx }) => {
             state.moves += 1;
@@ -416,23 +408,6 @@ describe('createOptimisticActionClient', () => {
             expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
             expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
         });
-        /**
-         * IMPORTANT: 型に schedule があるので、先読みされる action からも呼べてしまう。
-         * 実体を渡していないと `ctx.schedule is not a function` で先読みが丸ごと落ちる。
-         *
-         * 予約自体はサーバーだけが持つので先読みでは何もしないが、戻り値 (絶対時刻) は
-         * 返す必要がある。シナリオはそれを表示用の endsAt として state に入れるため、
-         * undefined を返すと先読み中だけタイマーが消える。
-         */
-        it('先読みでも ctx.schedule が呼べて絶対時刻を返す', () => {
-            const { client, states, sent } = setup();
-            client.send('startTimer');
-            // 先読みが落ちていたら pending に積まれず state も変わらない
-            expect(sent).toEqual([{ action: 'startTimer', seq: 1 }]);
-            const stamped = latest(states).stampedAt;
-            expect(stamped).toBeGreaterThanOrEqual(Date.now() + 60000 - 5000);
-            expect(stamped).toBeLessThanOrEqual(Date.now() + 60000 + 5000);
-        });
         /**
          * IMPORTANT: 再適用 (reconciliation でのやり直し) では初回予測時の now を使い回す。
          *

package/dist/types.d.ts

@@ -104,45 +104,50 @@ export interface ActionContext {
      */
     now: number;
     emit: Emit;
-    /** 予約はサーバーだけが持つ。先読みでは戻り値を計算するだけで、予約も取り消しもしない。 */
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
 }
-/** 予約されたタイマーの識別子付き宣言。 */
-export interface ScheduleOptions {
-    /** 予約の識別子。同じ key で予約し直すと置き換わる (古い予約が残ると二重に発火する)。 */
-    key: string;
-    /** 絶対時刻 (ms)。`after` と排他。過去なら即座に発火する。 */
-    at?: number;
-    /** 何秒後か。`at` と排他。 */
-    after?: number;
-    action: string;
-    payload?: Record<string, unknown>;
+/** `deadlines` handler の実行文脈。サーバーでしか走らないので tick 以外を渡せる。 */
+export interface DeadlineContext {
+    /** 発火時刻 (ms)。サーバー専用なので常に正確。 */
+    now: number;
+    random: SeededRandom;
+    emit: Emit;
+}
+/** `deadlines` handler の引数。 */
+export interface DeadlineArgs<S> {
+    state: S;
+    ctx: DeadlineContext;
 }
 /**
- * サーバー権威のタイマー。
+ * サーバー権威の締切。
+ *
+ * 「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが `at` の最も早いものに
+ * 合わせて自分で起き、過ぎた締切の `handler` を呼ぶ。`tickRate` で毎秒ポーリングする
+ * 必要が無くなり、その間 Durable Object は hibernate できる。
  *
- * クライアントの時計やアプリのバックグラウンド化に依存せず、サーバーが指定時刻に
- * 自分で起きて action を撃つ。`tickRate` で毎秒ポーリングする必要が無くなり、
- * その間 Durable Object は hibernate できる。
+ * 締切は state から導出するので、予約を張り替える処理を書かなくてよい。action が
+ * throw して state が巻き戻れば、締切も一緒に巻き戻る。
  */
-export interface Scheduler {
+export interface Deadline<S> {
     /**
-     * 予約して確定した絶対時刻 (ms) を返す。表示用の endsAt にそのまま使える。
+     * 締切の絶対時刻 (ms)。締切が無いときは null / undefined。
+     *
+     * `state.timer?.endsAt` のような optional chain の結果をそのまま返せるよう
+     * undefined も受ける。数値以外は「締切なし」として同じに扱う。
      *
-     * 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で「自分が予約した
-     * ものか」を state と突き合わせて弾くこと (action 名や key では区別できない)。
+     * state が変わるたびに呼ばれるので、state だけから決まる軽い関数にすること。
+     * ここで実時刻や乱数を読むと、呼ばれるたびに答えが変わって予約が暴れる。
      */
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
+    at(args: {
+        state: S;
+    }): number | null | undefined;
+    /**
+     * `at` の時刻を過ぎたときにサーバーで呼ばれる。
+     *
+     * 発火は at-least-once だが、SDK が発火直前に `at` を評価し直して過ぎているものだけを
+     * 呼ぶので、handler 側で二重発火を弾く必要は無い。
+     */
+    handler(args: DeadlineArgs<S>): void;
 }
-/**
- * 予約から発火した action に渡る playerId。
- *
- * 送信者がいないので、人間の操作と区別するための定数。
- * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
- */
-export declare const SCHEDULED_ACTOR = "__scheduled";
 /** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
 export interface ServerActionContext {
     tick: number;
@@ -150,8 +155,6 @@ export interface ServerActionContext {
     /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
     now: number;
     emit: Emit;
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
 }
 /** @deprecated `ServerActionContext` を使う。 */
 export type ServerOnlyActionContext = ServerActionContext;
@@ -191,8 +194,6 @@ export interface UpdateContext {
     tick: number;
     /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
     now: number;
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
     emit: Emit;
     playerInputs: Record<string, Record<string, any>>;
 }
@@ -200,12 +201,27 @@ export interface UpdateArgs<S> {
     state: S;
     ctx: UpdateContext;
 }
-export interface GameLogic<S> {
+/**
+ * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
+ *
+ * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
+ */
+export interface SetupContext {
+    random: SeededRandom;
+    /** サーバーの実時刻 (ms)。setup はサーバーでしか走らないので常に正確。 */
+    now: number;
+}
+/** `setup()` の引数。 */
+export interface SetupArgs {
     /**
      * seats には kind !== 'player' の席 (spectator / admin) も含まれる。
      * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
      */
-    setup(seats: Seat[], random: SeededRandom): S;
+    seats: Seat[];
+    ctx: SetupContext;
+}
+export interface GameLogic<S> {
+    setup(args: SetupArgs): S;
     /**
      * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
      *
@@ -223,6 +239,13 @@ export interface GameLogic<S> {
      */
     serverActions?: Record<string, ServerActionHandler<S>>;
     update(args: UpdateArgs<S>): void;
+    /**
+     * state 由来の締切。サーバーが `at` の時刻に自分で起きて `handler` を呼ぶ。
+     *
+     * 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
+     * ポーリング中は Durable Object が hibernate できない。
+     */
+    deadlines?: Record<string, Deadline<S>>;
     tickRate?: number;
 }
 export interface GameConfig<S> extends ConnectionCallbacks {

package/dist/types.js

@@ -1,10 +1,3 @@
-/**
- * 予約から発火した action に渡る playerId。
- *
- * 送信者がいないので、人間の操作と区別するための定数。
- * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
- */
-export const SCHEDULED_ACTOR = '__scheduled';
 /** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
 export const SERVER_TIME = '__SERVER_TIME__';
 /** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */

package/package.json

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