@uzuhq/code-sdk 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  * 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, ActionContext, ActionHandler, EventHandler, EventSubscription, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } 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, 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 { serverOnly, isServerOnlyAction } from './server-only.js';
 export { serverNow } from './server-clock.js';

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

@@ -76,7 +76,12 @@ export function runLocalServerAction(config) {
         const now = Date.now();
         if (plain && !legacyServerOnly) {
             try {
-                plain(state, payload ?? {}, myId, plainEmit, { now, ...makeScheduleCtx() });
+                plain({
+                    state,
+                    payload: payload ?? {},
+                    playerId: myId,
+                    ctx: { now, emit: plainEmit, ...makeScheduleCtx() },
+                });
             }
             catch (err) {
                 console.warn('[SDK LocalServerAction] Action error:', err);
@@ -89,11 +94,11 @@ export function runLocalServerAction(config) {
             return;
         void (async () => {
             try {
-                await server(state, payload ?? {}, myId, serverEmit, {
-                    tick,
-                    random,
-                    now,
-                    ...makeScheduleCtx(),
+                await server({
+                    state,
+                    payload: payload ?? {},
+                    playerId: myId,
+                    ctx: { tick, random, now, emit: serverEmit, ...makeScheduleCtx() },
                 });
             }
             catch (err) {
@@ -112,13 +117,16 @@ export function runLocalServerAction(config) {
             const tickEvents = [];
             const tickEmit = (name, data) => tickEvents.push({ name, data: data ?? {} });
             try {
-                logic.update(state, {
-                    random,
-                    tick,
-                    now: Date.now(),
-                    ...makeScheduleCtx(),
-                    emit: tickEmit,
-                    playerInputs,
+                logic.update({
+                    state,
+                    ctx: {
+                        random,
+                        tick,
+                        now: Date.now(),
+                        ...makeScheduleCtx(),
+                        emit: tickEmit,
+                        playerInputs,
+                    },
                 });
             }
             catch (err) {

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

@@ -55,9 +55,9 @@ describe('runLocalServerAction', () => {
         it('actions だけなら同期で state と events が確定する', () => {
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
             }));
@@ -69,10 +69,10 @@ describe('runLocalServerAction', () => {
         it('serverActions だけなら await 後に反映される', async () => {
             const h = run(baseLogic({
                 serverActions: {
-                    notifyExternal: async (state, _payload, _playerId, emit) => {
+                    notifyExternal: async ({ state, ctx }) => {
                         await tick();
                         state.charged += 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     },
                 },
             }));
@@ -91,13 +91,13 @@ describe('runLocalServerAction', () => {
             const order = [];
             const h = run(baseLogic({
                 actions: {
-                    move: (state) => {
+                    move: ({ state }) => {
                         order.push('actions');
                         state.moves += 1;
                     },
                 },
                 serverActions: {
-                    move: (state, _payload, _playerId, _emit, ctx) => {
+                    move: ({ state, ctx }) => {
                         order.push('serverActions');
                         // actions の結果が見えている
                         expect(state.moves).toBe(1);
@@ -124,16 +124,16 @@ describe('runLocalServerAction', () => {
         it('actions の events は serverActions の await を待たない', async () => {
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
                 serverActions: {
-                    move: async (state, _payload, _playerId, emit) => {
+                    move: async ({ state, ctx }) => {
                         await tick();
                         state.charged += 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     },
                 },
             }));
@@ -171,9 +171,9 @@ describe('runLocalServerAction', () => {
             const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
             const h = run(baseLogic({
                 actions: {
-                    move: (state, _payload, _playerId, emit) => {
+                    move: ({ state, ctx }) => {
                         state.moves += 1;
-                        emit('moved');
+                        ctx.emit('moved');
                     },
                 },
                 serverActions: {
@@ -196,13 +196,14 @@ describe('runLocalServerAction', () => {
         it('actions に入った serverOnly() は server 側として実行される', async () => {
             const logic = baseLogic({
                 actions: {
-                    // 新しい型では actions に serverOnly() を入れられない (それが本 PR の狙い)。
-                    // ここは「R2 に残っている古い logic.js」を再現するための意図的な型違反。
-                    // @ts-expect-error 移行期の互換挙動を検証するため
-                    legacy: serverOnly(async (state, _payload, _playerId, emit, ctx) => {
+                    // 検証対象は `__serverOnly` brand の判定であって、旧シグネチャの互換ではない。
+                    // handler 自体は現行の呼び出し形で書いている (旧形式の logic.js は現行テンプレでは
+                    // 動かない。公開済みゲームが無い前提で互換を切っている)。
+                    // @ts-expect-error actions に serverOnly() を入れるのは型違反だが、brand 判定を試す
+                    legacy: serverOnly(async ({ state, ctx }) => {
                         await tick();
                         state.charged += ctx.tick + 1;
-                        emit('charged');
+                        ctx.emit('charged');
                     }),
                 },
             });

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

@@ -98,9 +98,11 @@ export function createOptimisticActionClient(config) {
             // publish されてしまう。1 件ごとに直前の確定形から作り直し、成功したものだけ採用する。
             const base = structuredClone(displayState);
             try {
-                runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {
-                    now,
-                    ...predictedScheduleCtx(now),
+                runPredicted(action, () => handler({
+                    state: displayState,
+                    payload,
+                    playerId,
+                    ctx: { now, emit: noopEmit, ...predictedScheduleCtx(now) },
                 }));
                 i++;
             }
@@ -153,9 +155,11 @@ export function createOptimisticActionClient(config) {
             // サーバー専用のはずの副作用がクライアントでも走る。brand を見て弾く。
             if (handler && !isServerOnlyAction(handler) && target !== null) {
                 try {
-                    runPredicted(type, () => handler(target, payload ?? {}, playerId, predictEmit, {
-                        now,
-                        ...predictedScheduleCtx(now),
+                    runPredicted(type, () => handler({
+                        state: target,
+                        payload: payload ?? {},
+                        playerId,
+                        ctx: { now, emit: predictEmit, ...predictedScheduleCtx(now) },
                     }));
                     pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
                     onState(target, playerId);

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

@@ -13,20 +13,23 @@ import { describe, expect, it, vi } from 'vitest';
 import { createOptimisticActionClient } from './optimistic-action-client.js';
 import { serverOnly } from '../server-only.js';
 import { resetServerTimeOffset } from '../server-clock.js';
-/** 旧 serverOnly() ブランド付き handler。actions に残っている古い logic を再現する。 */
-const legacyServerOnly = serverOnly((state) => {
+/**
+ * `serverOnly()` の brand が付いた handler。`actions` に入っていても先読みされないこと
+ * (brand 判定が効くこと) を確かめる。旧シグネチャの互換は検証対象ではない。
+ */
+const legacyServerOnly = serverOnly(({ state }) => {
     state.charged += 1000;
 });
 const makeLogic = () => ({
     setup: () => ({ moves: 0, charged: 0, stampedAt: 0 }),
     actions: {
-        move: (state, _payload, _playerId, emit, ctx) => {
+        move: ({ state, ctx }) => {
             state.moves += 1;
             state.stampedAt = ctx.now;
-            emit('moved', {});
+            ctx.emit('moved', {});
         },
         // 先読みでも ctx.schedule を呼ぶ action。型にはあるので呼べてしまう。
-        startTimer: (state, _payload, _playerId, _emit, ctx) => {
+        startTimer: ({ state, ctx }) => {
             state.stampedAt = ctx.schedule({
                 key: 'timer',
                 after: 60,
@@ -34,15 +37,15 @@ const makeLogic = () => ({
             });
         },
         // 予測の結果によって別の event を出す (予測ミスの再現用)
-        guess: (state, payload, _playerId, emit) => {
+        guess: ({ state, payload, ctx }) => {
             state.moves += 1;
-            emit(payload?.willEmit ?? 'accepted', payload?.data ?? {});
+            ctx.emit(payload?.willEmit ?? 'accepted', payload?.data ?? {});
         },
         boom: () => {
             throw new Error('always fails');
         },
         // 途中まで state を書き換えてから throw する (部分ミューテーションの検証用)
-        partial: (state) => {
+        partial: ({ state }) => {
             state.moves += 1;
             throw new Error('fails after mutating');
         },
@@ -52,12 +55,12 @@ const makeLogic = () => ({
     },
     serverActions: {
         // move と同名 = 同じ action の「サーバーだけで走る続き」
-        move: (state, _payload, _playerId, emit, ctx) => {
+        move: ({ state, ctx }) => {
             state.charged += ctx.tick;
-            emit('charged', {});
+            ctx.emit('charged', {});
         },
         // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
-        notifyExternal: (state) => {
+        notifyExternal: ({ state }) => {
             state.charged += 100;
         },
     },

package/dist/types.d.ts

@@ -66,24 +66,8 @@ export type EventHandler = (data: Record<string, unknown>) => void;
 /**
  * events の購読宣言。
  *
- * `predict` は必須。 このイベントを「クライアント先読みの時点で実行してよいか」を
- * シナリオ側が明示する。
- *
- * | `predict` | 実行タイミング | 向いているもの |
- * |---|---|---|
- * | `true` | 先読み時に即実行。確定は待たない | 短く上書きできる SE、画面フラッシュ |
- * | `false` | サーバー確定後に 1 回だけ | 長い演出、ハプティクス、計測、外部通知 |
- *
- * IMPORTANT: 先読みは外れることがあり、実行してしまったものは取り消せない。
- * 「起きなかった出来事」で実行されて困るもの (analytics / 実績解除 / 長いカットイン)
- * は必ず `predict: false` にすること。誤送信は静かに、そして永久に残る。
- *
- * ```ts
- * events: {
- *   'dialogue.line': { predict: true, handler: (d) => playSound('page') },
- *   'game.finished': { predict: false, handler: () => playFanfare() },
- * }
- * ```
+ * 先読みは外れることがあり、実行してしまったものは取り消せない。取り消せない副作用
+ * (analytics / 実績解除 / 長い演出) は必ず `predict: false` にすること。
  */
 export interface EventSubscription {
     /** 先読み時点で実行してよいか。宣言必須。 */
@@ -111,46 +95,27 @@ export interface SeededRandom {
  */
 export interface ActionContext {
     /**
-     * このアクションがサーバーで処理される時刻 (ms)。
+     * サーバーで処理される時刻 (ms)。先読みではクロックオフセットからの推定値。
      *
-     * サーバーでは dispatch 時の実時刻。クライアント先読みでは、サーバーとのクロック
-     * オフセットから推定した値が入る。端末の時計がズレていても影響を受けない。
+     * 推定なのでサーバーとは数十 ms ずれる。時刻での分岐に使うと境界で判定が割れるので、
+     * 分岐は `update()` (サーバー専用) で行う。
      *
-     * IMPORTANT: 推定なのでサーバーの値とは数十 ms ずれる。時刻の **記録** に使うこと。
-     * `if (ctx.now > deadline)` のような **分岐** に使うと境界付近でクライアントと
-     * サーバーの判定が割れ、先読みが構造ごと外れる。時刻での分岐は `update()` で行う
-     * (サーバーでしか走らないので実時刻で正確)。
-     *
-     * 再適用 (reconciliation でのやり直し) では初回予測時の値を使い回す。取り直すと
-     * やり直すたびに値がズレて表示がガタつくため。
+     * 同じ action を再適用しても値は変わらない (初回予測時の値を使い回す)。
      */
     now: number;
-    /**
-     * サーバー権威のタイマー予約。
-     *
-     * IMPORTANT: クライアント先読みでは**何も予約しない** (予約はサーバーだけが持つ)。
-     * 戻り値の絶対時刻は先読みでも計算されるので、表示用の値は即座に出せる。
-     */
+    emit: Emit;
+    /** 予約はサーバーだけが持つ。先読みでは戻り値を計算するだけで、予約も取り消しもしない。 */
     schedule(options: ScheduleOptions): number;
-    /** 予約を取り消す。クライアント先読みでは何もしない。 */
     unschedule(key: string): void;
 }
 /** 予約されたタイマーの識別子付き宣言。 */
 export interface ScheduleOptions {
-    /**
-     * 予約の識別子。同じ key で予約し直すと**置き換わる**。
-     *
-     * key を必須にしているのは、古い予約を確実に消せるようにするため。
-     * 例: GM がタイマーを 20 分 -> 30 秒に変更したとき、同じ key で予約し直せば
-     * 古い 20 分の予約は消える。key が無いと両方が生き残り、19 分後に
-     * 「もう終わったフェーズ」を進める事故になる。
-     */
+    /** 予約の識別子。同じ key で予約し直すと置き換わる (古い予約が残ると二重に発火する)。 */
     key: string;
-    /** 発火する絶対時刻 (ms)。`after` と排他。過去を指定すると即座に発火する。 */
+    /** 絶対時刻 (ms)。`after` と排他。過去なら即座に発火する。 */
     at?: number;
-    /** 何秒後に発火するか。`at` と排他。 */
+    /** 何秒後か。`at` と排他。 */
     after?: number;
-    /** 発火時に実行する action 名。 */
     action: string;
     payload?: Record<string, unknown>;
 }
@@ -163,22 +128,12 @@ export interface ScheduleOptions {
  */
 export interface Scheduler {
     /**
-     * 予約する。戻り値は確定した絶対時刻 (ms)。
-     *
-     * 表示用の `endsAt` と発火の予約が二重管理で drift しないよう、戻り値をそのまま
-     * state に入れられるようにしている。
-     *
-     * ```ts
-     * state.game.timerEndsAt = ctx.schedule({
-     *   key: 'phaseTimer', after: 1200, action: 'phase.timeout', payload: { phaseId },
-     * });
-     * ```
+     * 予約して確定した絶対時刻 (ms) を返す。表示用の endsAt にそのまま使える。
      *
-     * IMPORTANT: 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で
-     * 「もう進んでいたら何もしない」ガードを書くこと。
+     * 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で「自分が予約した
+     * ものか」を state と突き合わせて弾くこと (action 名や key では区別できない)。
      */
     schedule(options: ScheduleOptions): number;
-    /** 予約を取り消す。存在しない key を渡しても何も起きない。 */
     unschedule(key: string): void;
 }
 /**
@@ -194,13 +149,33 @@ export interface ServerActionContext {
     random: SeededRandom;
     /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
     now: number;
+    emit: Emit;
     schedule(options: ScheduleOptions): number;
     unschedule(key: string): void;
 }
 /** @deprecated `ServerActionContext` を使う。 */
 export type ServerOnlyActionContext = ServerActionContext;
-export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ActionContext) => void;
-export type ServerActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerActionContext) => Promise<void> | void;
+/**
+ * action handler の引数。
+ *
+ * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
+ * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
+ */
+export interface ActionArgs<S> {
+    state: S;
+    payload: any;
+    playerId: string;
+    ctx: ActionContext;
+}
+export type ActionHandler<S> = (args: ActionArgs<S>) => void;
+/** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
+export interface ServerActionArgs<S> {
+    state: S;
+    payload: any;
+    playerId: string;
+    ctx: ServerActionContext;
+}
+export type ServerActionHandler<S> = (args: ServerActionArgs<S>) => Promise<void> | void;
 /** @deprecated `ServerActionHandler` を使う。 */
 export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 /**
@@ -210,6 +185,21 @@ export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
 export type ServerOnlyAction<S> = ServerActionHandler<S> & {
     readonly __serverOnly: true;
 };
+/** `update()` の ctx。サーバーでしか走らないので tick / random / playerInputs を持つ。 */
+export interface UpdateContext {
+    random: SeededRandom;
+    tick: number;
+    /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
+    now: number;
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
+    emit: Emit;
+    playerInputs: Record<string, Record<string, any>>;
+}
+export interface UpdateArgs<S> {
+    state: S;
+    ctx: UpdateContext;
+}
 export interface GameLogic<S> {
     /**
      * seats には kind !== 'player' の席 (spectator / admin) も含まれる。
@@ -232,16 +222,7 @@ export interface GameLogic<S> {
      * (旧 `serverOnly()` 相当) になる。
      */
     serverActions?: Record<string, ServerActionHandler<S>>;
-    update(state: S, ctx: {
-        random: SeededRandom;
-        tick: number;
-        /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
-        now: number;
-        schedule(options: ScheduleOptions): number;
-        unschedule(key: string): void;
-        emit: Emit;
-        playerInputs: Record<string, Record<string, any>>;
-    }): void;
+    update(args: UpdateArgs<S>): void;
     tickRate?: number;
 }
 export interface GameConfig<S> extends ConnectionCallbacks {

package/package.json

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