@uzuhq/code-sdk 0.3.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sally, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,573 @@
+# @uzuhq/code-sdk
+
+[UZU](https://uzu-app.com) 上で動くゲーム・シナリオを作るための通信 SDK。マルチプレイ状態同期、サウンド再生、デバイス連携を提供します。
+
+```bash
+npm install @uzuhq/code-sdk
+```
+
+ゲームのビルド・配信には [@uzuhq/code-cli](https://www.npmjs.com/package/@uzuhq/code-cli) を併用してください。
+
+> **Note:** API を変更した場合、このドキュメントも必ず同期してください。
+
+## メッセージプロトコル
+
+すべてのブリッジメッセージは `{ channel, type, payload }` の共通構造を持つ。
+
+| チャネル | 用途                         | 説明                                                          |
+| -------- | ---------------------------- | ------------------------------------------------------------- |
+| `sdk`    | SDK/プラットフォームコマンド | サウンド再生、マイク制御、ルーム移動など SDK 内部のメッセージ |
+| `game`   | ゲーム独自メッセージ         | `send()` / `on()` で送受信するカスタムメッセージ              |
+
+`send()` は `channel: 'game'` のメッセージのみを送信する。`on()` は `channel: 'game'` のメッセージのみを受信し、handler には `payload` が直接渡される。
+
+SDK チャネルのメッセージは `playSound()`, `setMicEnabled()` などの専用関数から自動送信される。
+
+---
+
+## 3 つのパラダイム
+
+SDK は用途に応じて 3 つの API パターンを提供する。
+
+| パラダイム | API                   | state 管理                         | 向いているゲーム             |
+| ---------- | --------------------- | ---------------------------------- | ---------------------------- |
+| **Relay**  | `init()` + `onRoom()` | ゲーム側の責務                     | 独自プロトコルが必要なゲーム |
+| **sync()** | `sync()`              | SDK + サーバーが JSON Patch で同期 | ターン制・ボードゲーム       |
+| **run()**  | `run()`               | SDK + reducer がサーバーで逐次実行 | リアルタイム・アクション全般 |
+
+### 選択基準
+
+- 同時操作で同じリソースを奪い合う → **`run()`**（reducer が最新 state に対して逐次実行、条件保証あり）
+- 各プレイヤーが自分の領域だけ変更 → **`sync()`** で十分
+- 独自のメッセージプロトコルが必要 → **Relay**
+
+---
+
+## 初期化
+
+### `init(): void`
+
+SDK を初期化し、Flutter ホスト / 親ウィンドウに準備完了を通知する。
+
+```ts
+import { init } from '@uzuhq/code-sdk';
+init();
+```
+
+- `run()` / `sync()` を使う場合は内部で `init()` が呼ばれるため不要
+- Relay パターン (`onRoom()`) のみ、最初に呼び出す
+
+---
+
+## パターン 1: Relay
+
+### `onRoom(callback: (room: RoomLike) => void): void`
+
+Room に接続されたときのコールバックを登録する。
+
+```ts
+import { init, onRoom } from '@uzuhq/code-sdk';
+
+init();
+
+onRoom((room) => {
+  console.log('My ID:', room.myId);
+
+  room.on('attack', (msg) => {
+    console.log(`${msg.__from} sent ${msg.lines} lines`);
+  });
+
+  room.broadcast({ type: 'attack', lines: 2 });
+  room.send(targetId, { type: 'whisper', text: 'hello' });
+});
+```
+
+### Room API
+
+| メソッド/プロパティ      | 型                                                     | 説明                                                     |
+| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
+| `room.myId`              | `string` (readonly)                                    | 自分の playerId                                          |
+| `room.broadcast(msg)`    | `(msg: Record<string, unknown>) => void`               | 自分以外の全員に送信                                     |
+| `room.send(id, msg)`     | `(id: string, msg: Record<string, unknown>) => void`   | 特定プレイヤーに送信                                     |
+| `room.on(type, handler)` | `(type: string, handler: (data: any) => void) => void` | メッセージハンドラ登録。受信データに `__from` が含まれる |
+
+---
+
+## パターン 2: sync()
+
+### `sync<S>(config: SyncConfig<S>): void`
+
+JSON Patch ベースの状態同期を開始する。
+
+```ts
+import { sync, SERVER_TIME } from '@uzuhq/code-sdk';
+import type { Seat } from '@uzuhq/code-sdk';
+
+sync<GameState>({
+  playerCount: 2,
+
+  initialState(players: Seat[]) {
+    return { board: createBoard(8), currentPlayer: players[0].id };
+  },
+
+  onState(state, myPlayerId, serverTime) {
+    currentState = state;
+    render();
+  },
+
+  inputs(patch, set) {
+    canvas.addEventListener('click', (e) => {
+      const { row, col } = getCellFromClick(e);
+      // 複数操作をまとめて送信
+      patch([
+        { op: 'replace', path: `/board/${row}/${col}`, value: myPlayerId },
+        { op: 'replace', path: '/lastMoveAt', value: SERVER_TIME },
+      ]);
+      // 単一値のショートカット
+      set('/currentPlayer', getNextPlayer());
+    });
+  },
+
+  connection: {
+    onConnectionStateChange(state) {
+      console.log('Connection:', state);
+    },
+    onPatchFailed(error) {
+      console.error('Patch failed:', error);
+    },
+  },
+});
+```
+
+### SyncConfig
+
+| キー           | 型                                                           | 必須 | 説明                         |
+| -------------- | ------------------------------------------------------------ | ---- | ---------------------------- |
+| `playerCount`  | `number`                                                     | Yes  | プレイヤー数                 |
+| `initialState` | `(seats: Seat[]) => S`                                       | Yes  | 初期 state を生成            |
+| `onState`      | `(state: S, myPlayerId: string, serverTime: number) => void` | Yes  | state 更新時のコールバック   |
+| `inputs`       | `(patch: PatchFn, set: SetFn) => void`                       | Yes  | 入力ハンドラ登録             |
+| `events`       | `Record<string, (data: Record<string, unknown>) => void>`    | No   | ゲームイベントハンドラ       |
+| `connection`   | `ConnectionCallbacks`                                        | No   | 接続状態・エラーコールバック |
+
+### PatchFn / SetFn
+
+```ts
+type PatchFn = (ops: Operation[]) => void; // 複数操作をまとめて送信
+type SetFn = (path: string, value: unknown) => void; // 単一パスの replace ショートカット
+```
+
+### Operation (JSON Patch)
+
+```ts
+interface Operation {
+  op: 'replace' | 'add' | 'remove';
+  path: string; // JSON Pointer パス (例: '/players/alice/score')
+  value?: unknown; // 値。SERVER_TIME sentinel 使用可
+}
+```
+
+### 楽観的更新
+
+`sync()` は送信した patch をローカルに即座に適用する。サーバーからの権威的な state を受信すると上書きする。
+
+**注意**: `sync()` は patch の条件を検証しない。同時に同じパスを変更すると後勝ちになる。条件付きの状態遷移が必要なら `run()` を使う。
+
+---
+
+## パターン 3: run()
+
+### `run<S>(config: GameConfig<S>): void`
+
+Host-authoritative ゲームループを実行する。サーバー (GameRoom DO) が reducer を逐次実行するため、条件保証あり。
+
+```ts
+import { run } from '@uzuhq/code-sdk';
+
+run({
+  logic,
+  onState(state, myPlayerId) {
+    currentState = state;
+    myId = myPlayerId;
+  },
+  inputs(sendAction) {
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'ArrowUp') sendAction('move', { dx: 0, dy: -1 });
+    });
+  },
+  events: {
+    sound(data) {
+      new Audio(`/sounds/${data.sound}.mp3`).play().catch(() => {});
+    },
+  },
+  playerCount: 2,
+});
+```
+
+### GameConfig
+
+| キー                      | 型                                                             | 必須 | 説明                                |
+| ------------------------- | -------------------------------------------------------------- | ---- | ----------------------------------- |
+| `logic`                   | `GameLogic<S>`                                                 | Yes  | ゲームロジック定義                  |
+| `onState`                 | `(state: S, myPlayerId: string) => void`                       | Yes  | state 更新時のコールバック          |
+| `inputs`                  | `(sendAction: (action: string, payload: any) => void) => void` | Yes  | 入力ハンドラ登録                    |
+| `events`                  | `Record<string, (data: any) => void>`                          | No   | ゲームイベントハンドラ              |
+| `playerCount`             | `number`                                                       | Yes  | プレイヤー数                        |
+| `onConnectionStateChange` | `(state: ConnectionState) => void`                             | No   | 接続状態変化コールバック            |
+| `onPatchFailed`           | `(reason: string) => void`                                     | No   | サーバー patch 適用失敗コールバック |
+
+### GameLogic
+
+```ts
+import { serverOnly, type GameLogic } from '@uzuhq/code-sdk';
+
+const logic: GameLogic<MyState> = {
+  setup(seats, random) {
+    // 初期 state を生成。random は SeededRandom。
+    // seats には観戦系の席 (kind: 'spectator' | 'admin') も含まれ得るため、
+    // ゲームの席は kind === 'player' に絞る
+    return { players: {}, items: [] };
+  },
+
+  actions: {
+    move(state, payload, playerId, emit, ctx) {
+      // state を直接変更する（Immer 的な mutable 操作）
+      state.players[playerId].x += payload.dx;
+      // emit でイベント発火
+      emit('sound', { sound: 'step' });
+      // ctx.tick でサーバーの現在 tick を参照可能
+    },
+
+    // serverOnly(): client 先行実行をスキップしてサーバーだけで実行 (async OK)
+    notifyExternal: serverOnly(async (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 が使える
+  },
+
+  tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし, 0 でターン制)
+};
+```
+
+| キー       | 型                                                                                                                                 | 必須 | 説明                                                                        |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------- |
+| `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 なし)                                       |
+
+#### `serverOnly(handler)`
+
+`actions` に登録する handler を「サーバーでだけ実行される」ものに変換する wrapper。
+
+- クライアント側ではローカル先行実行 (楽観的更新) をスキップし、サーバーからの state delta を待つ
+- サーバー側で `await` で実行され、`fetch` などの副作用付き処理を安全に書ける
+- handler のシグネチャ: `(state, payload, playerId, emit, ctx) => Promise<void> | void`
+- 例外を投げると送信元クライアントに `__action_error` が返る (state は変更されない)
+
+```ts
+import { serverOnly } from '@uzuhq/code-sdk';
+```
+
+### manifest.json（run() を使う場合）
+
+`run()` を使う場合、`manifest.json` に `serverActionLogicPath` を指定する:
+
+```json
+{
+  "id": "my-game",
+  "serverActionLogicPath": "./src/logic.ts",
+  "playerCount": 2,
+  "build": "npm run build",
+  "output": "dist"
+}
+```
+
+---
+
+## SeededRandom
+
+`GameLogic` の `setup` / `update` で提供される seed 付き乱数生成器。
+
+| メソッド         | 説明                                |
+| ---------------- | ----------------------------------- |
+| `float()`        | 0.0〜1.0 の浮動小数点               |
+| `int(max)`       | 0〜max-1 の整数                     |
+| `pick(array)`    | 配列からランダムに 1 つ選択         |
+| `shuffle(array)` | 配列をシャッフル (新しい配列を返す) |
+
+---
+
+## サウンド
+
+```ts
+import { playSound, playBgm, stopBgm } from '@uzuhq/code-sdk';
+
+playSound('sounds/clear.mp3'); // 効果音
+playBgm('bgm/main.mp3'); // BGM ループ再生
+stopBgm(); // BGM 停止
+```
+
+サウンドファイルはゲームの `public/` ディレクトリに配置する。
+
+---
+
+## デバイス連携
+
+### `setMicEnabled(enabled: boolean): void`
+
+マイクのオンオフを切り替える。
+
+```ts
+import { setMicEnabled } from '@uzuhq/code-sdk';
+
+setMicEnabled(false); // マイクをミュート
+setMicEnabled(true); // マイクをオン
+```
+
+### `changeRoom(roomId: string | null): void`
+
+ボイスチャットルームを移動する。`null` でデフォルトルーム（全体ルーム）に戻る。
+
+```ts
+import { changeRoom } from '@uzuhq/code-sdk';
+
+changeRoom('room_a'); // room_a に移動（同じルームのプレイヤーとのみ音声通話可能）
+changeRoom(null); // デフォルトルーム（全員が同じ音声チャンネル）に戻る
+```
+
+- 初期状態ではすべてのプレイヤーがデフォルトルーム（`null`）に所属する
+- `roomId` に文字列を指定すると、そのプレイヤーは指定ルームへ移動する
+
+### `onPlayersChanged(handler: (players: Record<string, PlayerVoiceState>) => void): void`
+
+プレイヤーのリアルタイム状態（音声状態）が変化したときのハンドラを登録する。
+
+```ts
+import { onPlayersChanged } from '@uzuhq/code-sdk';
+
+onPlayersChanged((players) => {
+  for (const [id, state] of Object.entries(players)) {
+    // state.audioStatus: 'speaking' | 'listening' | 'muted' | 'unstable' | null
+    updatePlayerUI(id, state.audioStatus);
+  }
+});
+```
+
+---
+
+## メッセージング
+
+### `send(type: string, payload?: object): void`
+
+Flutter ホスト / 親ウィンドウへゲームチャネル (`channel: 'game'`) のメッセージを送信する。
+
+```ts
+import { send } from '@uzuhq/code-sdk';
+send('attack', { lines: 2 });
+// → { channel: 'game', type: 'attack', payload: { lines: 2 } }
+```
+
+### `on(type: string, handler: (payload: any) => void): void`
+
+ゲームチャネル (`channel: 'game'`) のメッセージを受信する。handler には `payload` が直接渡される。
+
+```ts
+import { on } from '@uzuhq/code-sdk';
+
+on('attack', (payload) => {
+  console.log(`Received attack with ${payload.lines} lines`);
+});
+```
+
+:::caution
+`on()` は `channel: 'game'` のメッセージのみを受信する。SDK チャネルのメッセージ（`playersChanged` 等）は `onPlayersChanged()` などの専用関数を使用すること。
+:::
+
+### `isHosted`
+
+`boolean` (読み取り専用)。Flutter WebView または iframe 内で動作しているか。
+
+---
+
+## SERVER_TIME
+
+サーバー時刻 sentinel 定数。Patch の `value` に指定すると、サーバー側で `Date.now()` に自動置換される。
+
+```ts
+import { SERVER_TIME } from '@uzuhq/code-sdk';
+set('/meta/phaseStartedAt', SERVER_TIME);
+```
+
+---
+
+## 型定義
+
+### BridgeMessage
+
+```ts
+interface BridgeMessage {
+  channel: 'sdk' | 'game';
+  type: string;
+  payload: Record<string, unknown>;
+}
+```
+
+### Seat
+
+セッション参加者。ゲームの席を占める `player` のほか、観戦席 (`spectator`) と進行管理席 (`admin`、dev ハーネスのテストプレイ用) がある。
+
+```ts
+type SeatKind = 'player' | 'spectator' | 'admin';
+
+interface Seat {
+  id: string;
+  nickname: string;
+  iconUrl: string;
+  /** 選択済みキャラクターの ID。未選択時は undefined */
+  characterId?: string;
+  /** 席種 */
+  kind: SeatKind;
+}
+```
+
+### ConnectionState
+
+```ts
+type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+```
+
+### ConnectionCallbacks
+
+```ts
+interface ConnectionCallbacks {
+  onConnectionStateChange?: (state: ConnectionState) => void;
+  onPatchFailed?: (error: string) => void;
+}
+```
+
+### PlayerVoiceState
+
+```ts
+interface PlayerVoiceState {
+  audioStatus: 'speaking' | 'listening' | 'muted' | 'unstable' | null;
+}
+```
+
+| audioStatus | 説明                     |
+| ----------- | ------------------------ |
+| `speaking`  | 発話中                   |
+| `listening` | 音声接続済み・聞いている |
+| `muted`     | ミュート中               |
+| `unstable`  | 接続に問題あり           |
+| `null`      | 音声通話に未接続         |
+
+---
+
+## URL パラメータ
+
+`init()` / `run()` / `sync()` は以下の URL パラメータを読み取る。
+
+| パラメータ  | 説明                                          |
+| ----------- | --------------------------------------------- |
+| `?server=`  | WebSocket サーバーの URL                      |
+| `?roomId=`  | ルーム ID。指定するとオンラインモードになる   |
+| `?seatId=`  | 自分の席 ID                                   |
+| `?players=` | JSON エンコードされたプレイヤーリスト         |
+| `?__dev=N`  | Dev ハーネスモード (N 画面の iframe 並列表示) |
+
+### モードの自動判定
+
+- URL に `?roomId=xxx` がない → **ローカルモード** (サーバー不要)
+- URL に `?roomId=xxx&server=xxx` がある → **オンラインモード**
+- URL に `?__dev=N` がある → **Dev ハーネスモード**
+
+---
+
+## Dev Hooks (`window.__uzu_dev`)
+
+外部 automation (Playwright / AI agent / E2E test) が iframe 内 state を決定論的に読み書きするための API。SDK は state shape に依存しない generic primitive だけを提供する。
+
+**Flutter native ホスト (`window.FlutterHost` あり) では一切 attach されない**。authoritative state を持つ frame に 1 個だけ生える:
+
+- `run()` の devHarness → **親 frame だけ** (`page.mainFrame()`)
+- `runLocalServerAction` (ソロモード) 単独 frame → その frame
+- sync 系単独 frame → その frame
+- devHarness の **子 iframe には attach しない**
+
+```ts
+window.__uzu_dev.getSnapshot(); // 現在 state (run devHarness 親 = authoritative raw)
+window.__uzu_dev.getRawState(); // 生 server-side state (dev/local mode のみ)
+window.__uzu_dev.playerId(); // 現在の player ID (run devHarness 親は null)
+
+// action 送信 (run devHarness 親 frame のみ attach、それ以外は undefined)
+// `as` は必須 — server-side dispatch の `from` を指定する
+// Promise<void> を返す。await すると handler 完了 + broadcast 投函まで待つ
+await window.__uzu_dev.send?.({ as: 'dev_0', type: 'host.phase.jump', payload: { phaseId: 'p1' } });
+await window.__uzu_dev.send?.({
+  as: 'dev_1',
+  type: 'move.piece',
+  payload: { from: 'a1', to: 'a2' },
+});
+
+// illegal move は Promise rejection になる
+await expect(
+  window.__uzu_dev.send({
+    as: 'dev_0',
+    type: 'move.piece',
+    payload: {/* 相手の手番 */},
+  }),
+).rejects.toThrow('Not your turn');
+
+// 生 state 書換は 3 API。用途別に使い分ける:
+
+// 1. 全置換 (dump した state を流し込み、bug 再現など)
+await window.__uzu_dev.setRawState(fullState);
+
+// 2. RFC 7396 風 Merge Patch (object 階層の部分更新、array は atomic replace のみ)
+await window.__uzu_dev.mergeRawState({ game: { timerEndsAt: null } });
+
+// 3. RFC 6902 JSON Patch (path-based ops、array index 単体書換 OK)
+await window.__uzu_dev.patchRawState([
+  { op: 'replace', path: '/board/1/4', value: 99 },
+  { op: 'replace', path: '/currentTurn', value: 'dev_1' },
+]);
+
+// snapshot が条件を満たすまで待つ (default 10s timeout)
+await window.__uzu_dev.waitForSnapshot((s) => s.self.isReady === true);
+```
+
+- **state 書換 3 API**: `setRawState` (全置換) / `mergeRawState` (RFC 7396 風 Merge Patch) / `patchRawState` (RFC 6902 JSON Patch)
+  - 部分更新は `mergeRawState`、array 要素単体の書換は `patchRawState` を使う
+  - `mergeRawState` で array field に non-array object patch を当てると **throw** する (array が pure object に化けるのを構造的に防止)
+- online ServerAction では 3 API すべて `undefined`
+- `send` は run devHarness 親 frame のみ。非 parent モード (runLocal / emulator / sync) では scenario 側の `window.__uzu.sendAction` を使う
+- `await d.send(...)` / `await d.*RawState(...)` は **(a) handler 完了 (b) parent state broadcast 投函** までを待つ。**子 iframe canvas の paint 完了は含まない** ので、screenshot / visual e2e test では `await new Promise(r => requestAnimationFrame(r))` を別途挟むこと
+- phase 遷移時の field reset や `markReady` 等の **state shape を仮定する helper は SDK には含めない**。scenario 側で `window.__<scene>_dev` を生やして上記 primitive を組み合わせる
+
+### scenario test/tools から型補完を効かせる
+
+scenario の `test/*.ts` / `tools/*.ts` で SDK を import せず `window.__uzu_dev` だけ叩く場合、`tsconfig.json` の `types` に `@uzuhq/code-sdk/dev-globals` を足すと ambient で `UzuDevHooks` が効く:
+
+```jsonc
+{
+  "compilerOptions": {
+    "types": ["@uzuhq/code-sdk/dev-globals"],
+  },
+}
+```
+
+これで `(window as any).__uzu_dev` で殴らずに `window.__uzu_dev?.send({ as: 'dev_0', type: '...', payload: ... })` が補完 + 型チェックされる。SDK を直接 import するモジュールでは `dev-hooks.ts` 側の `declare global` で既に型が見えているため、本 entry を `types` に足す必要はない。
+
+詳細は `docs/play_screen_v3/sdk-guide/dev-hooks.md` を参照。
+
+## License
+
+[MIT](./LICENSE)

package/dist/dev-globals.d.ts

@@ -0,0 +1,28 @@
+/**
+ * scenario 側 (`test/*.ts` / `tools/*.ts`) から `window.__uzu_dev` を
+ * 補完 + 型チェック付きで呼べるようにする ambient module。
+ *
+ * 使い方: scenario の `tsconfig.json` で
+ *
+ * ```jsonc
+ * { "compilerOptions": { "types": ["@uzuhq/code-sdk/dev-globals"] } }
+ * ```
+ *
+ * SDK 自身を import するコード (= `@uzuhq/code-sdk` の named import を持つ
+ * モジュール) では `dev-hooks.ts` 側の `declare global` で同じ型が既に効く
+ * ため、本 module を `types` に足す必要はない。target は import しない
+ * scenario test/tools のみ。
+ */
+import type { UzuDevHooks } from './dev-hooks.js';
+declare global {
+    interface Window {
+        /**
+         * dev harness / Playwright / 単独 page で attach される dev hooks。
+         * 本番 (Flutter native ホスト) では undefined。
+         * - run() devHarness: 親 frame に attach (authoritative state)
+         * - sync() / online: 子 frame で undefined
+         */
+        __uzu_dev?: UzuDevHooks<unknown>;
+    }
+}
+export {};

package/dist/dev-globals.js

@@ -0,0 +1,16 @@
+/**
+ * scenario 側 (`test/*.ts` / `tools/*.ts`) から `window.__uzu_dev` を
+ * 補完 + 型チェック付きで呼べるようにする ambient module。
+ *
+ * 使い方: scenario の `tsconfig.json` で
+ *
+ * ```jsonc
+ * { "compilerOptions": { "types": ["@uzuhq/code-sdk/dev-globals"] } }
+ * ```
+ *
+ * SDK 自身を import するコード (= `@uzuhq/code-sdk` の named import を持つ
+ * モジュール) では `dev-hooks.ts` 側の `declare global` で同じ型が既に効く
+ * ため、本 module を `types` に足す必要はない。target は import しない
+ * scenario test/tools のみ。
+ */
+export {};