@uzuhq/code-sdk 0.7.1 → 0.7.3

package/README.md

@@ -271,8 +271,34 @@ const logic: GameLogic<MyState> = {
 ハンドラの引数は 1 つのオブジェクトで、使うものだけ書けばよい。
 `state` / `payload` / `playerId` はその呼び出しの事実、`ctx` は実行環境が与えるもの。
 
-時刻起点で何かを起こしたい場合は `tickRate` で毎秒ポーリングせず `ctx.schedule()` を使う。
-サーバーが指定時刻に自分で起きて action を撃つので、その間 Durable Object が hibernate できる。
+#### `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)`
 

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

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

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

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/run/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) => {
@@ -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++;
             }
@@ -137,6 +125,12 @@ export function createOptimisticActionClient(config) {
             // 先読みするのは logic.actions だけ。serverActions は transport にだけ送り、
             // 結果は ack (state + serverEvents) で受け取る。
             const handler = logic.actions[type];
+            // どちらにも無い action は届く先が無い。 黙って捨てると UI 上は無反応なのに
+            // 原因が分からないので、 ここで気付けるようにする。 serverActions にだけある
+            // action は actions[type] が undefined でも正常なので、 両方を見る。
+            if (!handler && !logic.serverActions?.[type]) {
+                console.error(`[uzu] unknown action: "${type}". logic.actions / logic.serverActions のどちらにも登録されていません。`);
+            }
             // callback 内では displayState の narrowing が効かないので const に退避する。
             const target = displayState;
             // サーバーがこのアクションを処理する時刻の推定。再適用でも同じ値を使うので、
@@ -159,7 +153,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;
@@ -161,21 +164,26 @@ export type ServerOnlyActionContext = ServerActionContext;
  * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
  * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
  */
-export interface ActionArgs<S> {
+export interface ActionArgs<S, P = any> {
     state: S;
-    payload: any;
+    payload: P;
     playerId: string;
     ctx: ActionContext;
 }
-export type ActionHandler<S> = (args: ActionArgs<S>) => void;
+/**
+ * `P` は既定が `any` なので、 注釈のない handler はそのまま動く。 payload の形を
+ * 書いた handler だけが検査され、 送信側もその型で縛られる。 全部に注釈しないと
+ * 恩恵が無い、 という移行にならないようにするための既定値。
+ */
+export type ActionHandler<S, P = any> = (args: ActionArgs<S, P>) => void;
 /** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
-export interface ServerActionArgs<S> {
+export interface ServerActionArgs<S, P = any> {
     state: S;
-    payload: any;
+    payload: P;
     playerId: string;
     ctx: ServerActionContext;
 }
-export type ServerActionHandler<S> = (args: ServerActionArgs<S>) => Promise<void> | void;
+export type ServerActionHandler<S, P = any> = (args: ServerActionArgs<S, P>) => Promise<void> | void;
 /** @deprecated `ServerActionHandler` を使う。 */
 export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 /**
@@ -191,8 +199,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>>;
 }
@@ -204,7 +210,6 @@ export interface UpdateArgs<S> {
  * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
  *
  * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
- * `schedule` も無い。開幕から予約したい要求が出たら足す。
  */
 export interface SetupContext {
     random: SeededRandom;
@@ -220,7 +225,31 @@ export interface SetupArgs {
     seats: Seat[];
     ctx: SetupContext;
 }
-export interface GameLogic<S> {
+/**
+ * `actions` の形だけを見る緩い制約。
+ *
+ * `Record<string, ActionHandler<S>>` (payload: any) を制約に使うと、 推論時に
+ * handler 型がそちらへ広げられ payload の型が取り出せなくなる。 payload を
+ * `any` のままにしてキーと引数の形だけ縛る。
+ */
+export type ActionMap<S> = Record<string, (args: ActionArgs<S, any>) => void>;
+/** `serverActions` 用。 ActionMap と同じ理由で payload は any のままにする。 */
+export type ServerActionMap<S> = Record<string, (args: ServerActionArgs<S, any>) => Promise<void> | void>;
+/** action 名から payload 型を引く表。 注釈のない handler は `any` になる。 */
+export type PayloadMap<A> = {
+    [K in keyof A]: A[K] extends (args: infer G) => any ? G extends {
+        payload: infer P;
+    } ? P : never : never;
+};
+/**
+ * `inputs` が受け取る送信関数。 action 名と payload の両方が型で縛られる。
+ *
+ * payload を一律 optional にすると、 形が必須の action でも省略が通ってしまう。
+ * payload 型が undefined を含むとき (= 注釈なしの any や明示的に optional) だけ
+ * 省略できるようにする。
+ */
+export type SendAction<A> = <K extends keyof A & string>(...args: undefined extends PayloadMap<A>[K] ? [type: K, payload?: PayloadMap<A>[K]] : [type: K, payload: PayloadMap<A>[K]]) => void;
+export interface GameLogic<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> {
     setup(args: SetupArgs): S;
     /**
      * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
@@ -229,7 +258,7 @@ export interface GameLogic<S> {
      * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
      * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
      */
-    actions: Record<string, ActionHandler<S>>;
+    actions: A;
     /**
      * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
      * 再現できない処理をここに書く。async 可。
@@ -237,14 +266,21 @@ export interface GameLogic<S> {
      * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
      * (旧 `serverOnly()` 相当) になる。
      */
-    serverActions?: Record<string, ServerActionHandler<S>>;
+    serverActions?: SA;
     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 {
-    logic: GameLogic<S>;
+export interface GameConfig<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> extends ConnectionCallbacks {
+    logic: GameLogic<S, A, SA>;
     onState: (state: S, myPlayerId: string) => void;
-    inputs: (sendAction: (type: string, payload?: any) => void) => void;
+    inputs: (sendAction: SendAction<A & SA>) => void;
     /**
      * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
      *

package/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.1",
+  "version": "0.7.3",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {