@uzuhq/code-sdk 0.7.6 → 0.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzuhq/code-sdk",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {
@@ -23,12 +23,15 @@
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "@uzuhq/code-engine-core": "0.0.0"
   },
   "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "test": "vitest run"
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
   }
 }

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

@@ -1,11 +0,0 @@
-/**
- * `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

@@ -1,101 +0,0 @@
-/**
- * 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/dev-hooks.d.ts

@@ -1,241 +0,0 @@
-/**
- * @docs
- * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
- *
- * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
- * state を決定論的に読み書きするための window.__uzu_dev API。
- *
- * Flutter native ホスト (window.FlutterHost あり) では一切 attach されない。
- * dev harness の子 iframe / Playwright iframe / 単独 page では attach される。
- *
- * state 書き換え API:
- * - `setRawState(fullState)`        : 全置換
- * - `mergeRawState(patch)`          : RFC 7396 風 JSON Merge Patch (object 階層の部分更新)
- * - `patchRawState(ops)`            : RFC 6902 JSON Patch (path-based ops、array index 単体書換可)
- *
- * online ServerAction では state が Worker DO 側にあるため 3 つとも undefined。
- *
- * SDK は state shape に依存しない generic primitive だけを提供する。
- * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
- * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
- */
-import type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
-import type { PredictionWarning } from './dev-prediction-traps.js';
-import type { ServerEvent } from './types.js';
-export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
-export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
-export interface UzuDevHooks<S = unknown> {
-    /** 現在の per-player 視点 snapshot (onState コールバックの最新値)。未初期化なら null。 */
-    getSnapshot(): unknown;
-    /** 生 server-side state (dev/local mode のみ。online ServerAction では null)。 */
-    getRawState(): S | null;
-    playerId(): string | null;
-    /**
-     * 親 frame で virtual server を実体化した時の seed。
-     * 親 frame の `runDevHarness({ server })` 経由でしか attach されず、子 iframe の
-     * dev hooks 側では undefined。bug report 用に `?__dev_seed=<value>` として
-     * 貼り付けやすい uint32 を返す。
-     */
-    getSeed?(): number;
-    /**
-     * 素の action handler が先読み実行中に実時刻 / 乱数を読んだ記録。
-     *
-     * 先読みはサーバーと同じ結果を再現できることが前提なので、ここに何か入っていたら
-     * そのシナリオはオンラインでだけ予測がズレる。E2E で `[]` を assert すると回帰を防げる。
-     */
-    getPredictionWarnings(): readonly PredictionWarning[];
-    /**
-     * Server-side で action を直接 dispatch する。
-     *
-     * **run devHarness の親 frame のみ** で attach される。それ以外 (runLocal /
-     * sync / online) では `undefined`。
-     * 非 parent モードで action を投げたい時は scenario 側の bridge
-     * (`window.__uzu.sendAction`) や実 UI 操作を使う。
-     *
-     * `args.as` は **必須**。server-side dispatch の `from` をこの値で指定する
-     * (バリデーションはしないので、未登録 ID で投げて action handler に弾かせる
-     * 運用も可)。turn-based の E2E (将棋・人狼・カードゲーム) で「先手 → 後手」
-     * を 1 frame から打ち分けたい時に使う。
-     */
-    send?(args: {
-        as: string;
-        type: string;
-        payload?: Record<string, unknown>;
-    }): Promise<void>;
-    /**
-     * 生 state を **全置換** する。state owner の frame (= dev/local) のみ。
-     *
-     * `setup` 後の任意の構造を流し込めるので、`getRawState()` の dump を読み込んで
-     * バグ再現する用途や、scenario の途中 state を JSON で復元する用途に使う。
-     * 部分更新は {@link mergeRawState} を、array 要素単体の書換は
-     * {@link patchRawState} を使うこと。
-     */
-    setRawState?(state: S): Promise<void>;
-    /**
-     * RFC 7396 風 JSON Merge Patch で生 state を部分更新する (dev/local のみ)。
-     *
-     * - object 階層は recursive merge
-     * - **array field は atomic replace のみ** (要素単位の merge 不可、RFC 7396 仕様)
-     * - `undefined` は no-op、`null` は明示セット (RFC 7396 strict と異なる)
-     * - array 内の cell 単体を書き換えたい場合は {@link patchRawState} を使う
-     *
-     * array が pure object に化ける silent な破壊を防ぐため、`array に
-     * non-array object patch を当てる`と **throw** する。
-     */
-    mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
-    /**
-     * RFC 6902 JSON Patch (path-based ops) で生 state を更新する (dev/local のみ)。
-     *
-     * - JSON Pointer (`/board/1/4`) で array index 単体の書換が可能
-     * - サポートする op: `add` / `remove` / `replace` / `move` / `copy` / `test`
-     * - 1 op でも失敗するとその場で throw する (atomic ではない)
-     *
-     * 局面の部分更新 (将棋の一手・盤面の cell 単体書換など) に使う。
-     */
-    patchRawState?(ops: JsonPatchOp[]): Promise<void>;
-    /**
-     * snapshot 更新を event-driven に listen する。返り値は unsubscribe 関数。
-     *
-     * `waitForSnapshot` が「特定条件まで待つ」のに対し、こちらは「state 変化を全部
-     * 取って trace test を書く」「deterministic record を作る」「sequence assert」
-     * のような用途で使う canonical な listener。
-     *
-     * cb には authoritative state の生参照 (run devHarness 親では `getRawState()` と
-     * 同一) が渡るので mutate しない。
-     */
-    subscribeSnapshot(cb: (snapshot: unknown) => void): () => void;
-    /** snapshot が predicate を満たすまで待つ。default 10 秒 timeout。 */
-    waitForSnapshot(predicate: (snapshot: unknown) => boolean, options?: {
-        timeoutMs?: number;
-    }): Promise<unknown>;
-    /**
-     * action handler / `logic.update` の `emit` を listen する。callback には 1 回の
-     * dispatch / tick 内で発火した event を batch でまとめて渡す。**run devHarness 親
-     * frame のみ** で attach され、それ以外 (runLocal ソロ /
-     * sync / online) では `undefined`。
-     *
-     * `getSnapshot()` に乗らない raw payload (`gameover` の `reason` 等) を assert
-     * したい場合に使う。`config.events` callback とは独立経路で、scenario callback の
-     * throw も subscriber 通知を止めない。unsubscribe 関数を返す。
-     */
-    subscribeEvents?(cb: (events: readonly ServerEvent[]) => void): () => void;
-    /**
-     * tick loop を pause する (run() devHarness 親 frame のみ)。
-     * 時間駆動の `logic.update` が走らなくなり、shogi の持ち時間減算等の自動進行を
-     * 止められる。pause 中も `send` (action dispatch) と state 書換 API は通る。
-     * tick loop を持たない frame (子 iframe / sync 単独 frame / online) と
-     * `tickRate <= 0` の scenario では undefined / no-op。
-     */
-    pauseTick?(): void;
-    /** pauseTick を解除する。 */
-    resumeTick?(): void;
-    /** 手動で n tick 進める。default n = 1。 */
-    stepTick?(n?: number): void;
-    /** 現在の tick 値を返す。tick loop を持たない frame では undefined。 */
-    getCurrentTick?(): number;
-    /** pauseTick で止まっているかどうか。 */
-    isTickPaused?(): boolean;
-    /**
-     * `logic.setup` を再実行して virtual server を fresh start させる。
-     * run() devHarness の親 frame のみ attach される (state owner でしか reset 不可)。
-     *
-     * - `seed` 省略時は現在の seed を再利用 (= 決定論的同一初期化)
-     * - 数値を渡すとその seed で再初期化、`getSeed()` の戻り値も更新
-     * - `'random'` で新 seed (uint32) を生成
-     *
-     * pause 状態は維持される。`logic.setup` が副作用を持つ場合は再呼出で副作用が再発火する。
-     */
-    reset?(opts?: {
-        seed?: number | 'random';
-    }): void;
-}
-declare global {
-    interface Window {
-        __uzu_dev?: UzuDevHooks;
-    }
-}
-/**
- * run/* モジュール (run/local-server-action / run/dev-server-action) が
- * dev hooks に state を expose するための handle。
- * online (server-action) モードでは handle 自体を返さない。
- *
- * state 書き換え API は state owner frame のみ提供する。
- */
-export interface RunHandle<S = unknown> {
-    /** 内部 state の getter (dev hooks 用)。host iframe を持たない側では undefined */
-    getRawState?(): S | null;
-    /** 生 state 全置換。host iframe を持たない側では undefined */
-    setRawState?(state: S): Promise<void>;
-    /** RFC 7396 風 Merge Patch。host iframe を持たない側では undefined */
-    mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
-    /** RFC 6902 JSON Patch。host iframe を持たない側では undefined */
-    patchRawState?(ops: JsonPatchOp[]): Promise<void>;
-    /** 既存 inputs と同等の action 送信 (dev hooks 用) */
-    sendAction(type: string, payload?: Record<string, unknown>): void;
-}
-/**
- * sync/* モジュール (sync/dev / sync/local) が dev hooks に state を expose
- * するための handle。online sync では handle 自体を返さない。
- */
-export interface SyncHandle<S = unknown> {
-    /** 内部 state の getter (dev hooks 用) */
-    getRawState?(): S | null;
-    /** 生 state 全置換 */
-    setRawState?(state: S): Promise<void>;
-    /** RFC 7396 風 Merge Patch */
-    mergeRawState?(patch: JsonMergePatch<S>): Promise<void>;
-    /** RFC 6902 JSON Patch */
-    patchRawState?(ops: JsonPatchOp[]): Promise<void>;
-}
-/**
- * dev-hooks.ts から見た「SDK 内部のコンテキスト」。
- * 各 run/* / sync/* モジュールがこの形の handle を組み立てて attachDevHooks に渡す。
- */
-export interface DevHooksCtx<S = unknown> {
-    /** 最新 snapshot (per-player view)。未初期化なら null。 */
-    getSnapshot(): unknown;
-    /** 生 state getter (dev/local mode のみ)。 */
-    getRawState?: () => S | null;
-    /** 生 state 全置換 (dev/local mode のみ)。 */
-    setRawState?: (state: S) => Promise<void>;
-    /** RFC 7396 風 Merge Patch (dev/local mode のみ)。 */
-    mergeRawState?: (patch: JsonMergePatch<S>) => Promise<void>;
-    /** RFC 6902 JSON Patch (dev/local mode のみ)。 */
-    patchRawState?: (ops: JsonPatchOp[]) => Promise<void>;
-    /** 現在の player ID (URL クエリ or runtime 解決)。 */
-    playerId(): string | null;
-    /**
-     * Action 送信。run devHarness 親 frame の `DevHostHandle` のみが
-     * 提供する。それ以外のモードでは省略 (= `__uzu_dev.send` も生えない)。
-     * `args.as` で server-side dispatch の `from` を指定する (必須)。
-     */
-    sendAction?(args: {
-        as: string;
-        type: string;
-        payload?: Record<string, unknown>;
-    }): Promise<void>;
-    /** snapshot 更新を listen する。unsubscribe 関数を返す。 */
-    subscribeSnapshot(cb: (snapshot: unknown) => void): () => void;
-    /**
-     * action handler / `logic.update` 由来の emit を listen する。run devHarness 親
-     * frame の `DevHostHandle` のみが提供する。それ以外のモードでは省略
-     * (= `__uzu_dev.subscribeEvents` も生えない)。
-     */
-    subscribeEvents?(cb: (events: readonly ServerEvent[]) => void): () => void;
-    /** dev harness 親 frame の virtual server seed。親 attach 経路のみ。 */
-    getSeed?: () => number;
-    pauseTick?: () => void;
-    resumeTick?: () => void;
-    stepTick?: (n?: number) => void;
-    getCurrentTick?: () => number;
-    isTickPaused?: () => boolean;
-    /**
-     * run() devHarness 親 frame の `DevHostHandle.reset` を expose する。
-     * state owner でしか fresh start できないので、それ以外の mode では undefined。
-     */
-    reset?: (opts?: {
-        seed?: number | 'random';
-    }) => void;
-}
-export declare function createDevHooks<S>(ctx: DevHooksCtx<S>): UzuDevHooks<S>;
-export declare function attachDevHooks<S>(ctx: DevHooksCtx<S>): void;

package/dist/dev-hooks.js

@@ -1,132 +0,0 @@
-/**
- * @docs
- * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
- *
- * 外部 automation (Playwright / AI agent / E2E test) が SDK が動いている iframe の
- * state を決定論的に読み書きするための window.__uzu_dev API。
- *
- * Flutter native ホスト (window.FlutterHost あり) では一切 attach されない。
- * dev harness の子 iframe / Playwright iframe / 単独 page では attach される。
- *
- * state 書き換え API:
- * - `setRawState(fullState)`        : 全置換
- * - `mergeRawState(patch)`          : RFC 7396 風 JSON Merge Patch (object 階層の部分更新)
- * - `patchRawState(ops)`            : RFC 6902 JSON Patch (path-based ops、array index 単体書換可)
- *
- * online ServerAction では state が Worker DO 側にあるため 3 つとも undefined。
- *
- * SDK は state shape に依存しない generic primitive だけを提供する。
- * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
- * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
- */
-import { getPredictionWarnings } from './dev-prediction-traps.js';
-export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
-export function createDevHooks(ctx) {
-    const getRawState = () => (ctx.getRawState ? ctx.getRawState() : null);
-    const waitForSnapshot = (predicate, options) => {
-        const timeoutMs = options?.timeoutMs ?? 10000;
-        return new Promise((resolve, reject) => {
-            const current = ctx.getSnapshot();
-            if (current != null) {
-                let ok = false;
-                try {
-                    ok = predicate(current);
-                }
-                catch (err) {
-                    reject(err);
-                    return;
-                }
-                if (ok) {
-                    resolve(current);
-                    return;
-                }
-            }
-            const timer = setTimeout(() => {
-                unsubscribe();
-                reject(new Error(`[uzu_dev] waitForSnapshot timed out after ${timeoutMs}ms`));
-            }, timeoutMs);
-            const unsubscribe = ctx.subscribeSnapshot((snap) => {
-                let ok;
-                try {
-                    ok = predicate(snap);
-                }
-                catch (err) {
-                    clearTimeout(timer);
-                    unsubscribe();
-                    reject(err);
-                    return;
-                }
-                if (ok) {
-                    clearTimeout(timer);
-                    unsubscribe();
-                    resolve(snap);
-                }
-            });
-        });
-    };
-    const hooks = {
-        getSnapshot: () => ctx.getSnapshot(),
-        getRawState,
-        playerId: () => ctx.playerId(),
-        subscribeSnapshot: (cb) => ctx.subscribeSnapshot(cb),
-        waitForSnapshot,
-        getPredictionWarnings: () => getPredictionWarnings(),
-    };
-    if (ctx.sendAction) {
-        const sendAction = ctx.sendAction;
-        hooks.send = (args) => sendAction(args);
-    }
-    if (ctx.setRawState) {
-        const setRawState = ctx.setRawState;
-        hooks.setRawState = (state) => setRawState(state);
-    }
-    if (ctx.mergeRawState) {
-        const mergeRawState = ctx.mergeRawState;
-        hooks.mergeRawState = (patch) => mergeRawState(patch);
-    }
-    if (ctx.patchRawState) {
-        const patchRawState = ctx.patchRawState;
-        hooks.patchRawState = (ops) => patchRawState(ops);
-    }
-    if (ctx.getSeed) {
-        const getSeed = ctx.getSeed;
-        hooks.getSeed = () => getSeed();
-    }
-    // Tick 制御: ctx 側で提供されている時だけ wire する。子 iframe / sync /
-    // online 等 tick loop を持たない frame では undefined のままなので、scenario 側で
-    // `__uzu_dev.pauseTick?.()` の optional chain で safe に呼べる。
-    if (ctx.pauseTick) {
-        const pauseTick = ctx.pauseTick;
-        hooks.pauseTick = () => pauseTick();
-    }
-    if (ctx.resumeTick) {
-        const resumeTick = ctx.resumeTick;
-        hooks.resumeTick = () => resumeTick();
-    }
-    if (ctx.stepTick) {
-        const stepTick = ctx.stepTick;
-        hooks.stepTick = (n) => stepTick(n);
-    }
-    if (ctx.getCurrentTick) {
-        const getCurrentTick = ctx.getCurrentTick;
-        hooks.getCurrentTick = () => getCurrentTick();
-    }
-    if (ctx.isTickPaused) {
-        const isTickPaused = ctx.isTickPaused;
-        hooks.isTickPaused = () => isTickPaused();
-    }
-    if (ctx.reset) {
-        const reset = ctx.reset;
-        hooks.reset = (opts) => reset(opts);
-    }
-    if (ctx.subscribeEvents) {
-        const subscribeEvents = ctx.subscribeEvents;
-        hooks.subscribeEvents = (cb) => subscribeEvents(cb);
-    }
-    return hooks;
-}
-export function attachDevHooks(ctx) {
-    // `init()` → `run()` の順で 2 回 attach されるのは正常フロー (run/sync 経由なら 1 回のみ)。
-    // silently 上書きする。
-    window.__uzu_dev = createDevHooks(ctx);
-}

package/dist/dev-hooks.test.d.ts

@@ -1 +0,0 @@
-export {};