feat: スモウルビー甲子園 拡張機能の本格対応（ブロック挙動 + 実サーバー通信）[Epic]

[takaokouji]

背景・ゴール

スモウルビー甲子園拡張機能（packages/scratch-vm/src/extensions/koshien/index.js）は、AI を作って スモウルビー甲子園のゲームサーバー（tmp/smalruby-koshien/）と通信するための拡張機能。しかし現状、各ブロックは何もしない（-1 や undefined、空 Promise を返す）スタブ実装で、編集機上では意味のある挙動をしない。

この Epic で 2 段階の改良を行う:

1. ブロック単体で意味のある固定値/状態変化を返す（未接続モード）
2. 実ゲームサーバーに接続していれば本当にゲームを進行できる（接続モード）。未接続なら 1 の仮の値にフォールバック

過去にゲームサーバーを作ろうとした際、明確な仕様が無く実装が困難だった。今回は
実サーバーの挙動をゴールデン記録し、クライアントの整合性をテストスイートで担保することで
実現可能性を高める。

アーキテクチャ方針

ブロックの挙動を バックエンド差し替え可能 にする:

ブロックメソッド (index.js)
        │
        ▼
  KoshienClient (interface)
        ├── MockClient    … 固定値/簡易状態（未接続時 = Part 1）
        └── RemoteClient  … 実ゲームサーバーへ HTTP（接続時 = Part 2）

• Part 1（固定値）は Part 2（実通信）の「未接続モード」そのもの。地続きに積み上げる。
• 通信主体はブラウザ拡張(JS)自身（編集機上で実ゲームを進行できる）。

確定事項（設計時にユーザー確認済）

• Part 2 の通信主体 = ブラウザ拡張(JS)が直接 HTTP。CORS / サーバーホスティングは Sub-C で対処。
• テスト = ゴールデン記録 + jest 契約テスト（ローカル実サーバーの挙動を fixture 化）。
• ローカルサーバー起動は開発側で用意（Ruby/gem install 可）。

サブイシュー

• feat(scratch-vm): 甲子園ブロックの固定値/状態実装（MockClient） #739 ブロックの固定値/状態実装（MockClient）
• test: 甲子園クライアント契約テスト基盤（実サーバーのゴールデン記録 + jest） #740 クライアント契約テストスイート基盤（実サーバーのゴールデン記録 + jest）
• feat(scratch-vm): 甲子園 実ゲームサーバー通信モード（RemoteClient） #741 実ゲームサーバー通信モード（RemoteClient + 接続判定 + フォールバック）
• feat: 甲子園 Ruby v2 対応（クライアントライブラリのパッチ + editor 修正） #743 Ruby v2 対応（クライアントライブラリのパッチ + editor 修正）

追加作業（Epic 進行中に発生・対応済み）

当初のサブイシューに加え、以下を本 Epic ブランチ（PR #761）で対応済み:

• feat(koshien): 「AIを試す」で現スプライト・現バージョンの生成AIをiframeにplayer1で渡す #762 「AIを試す」で現スプライト・現バージョンの生成 AI を iframe に player1 で渡す
  （実ゲームサーバー通信モードを実機で試すための導線）

残作業（別レポジトリ: ゲームサーバー side）

editor 側（本リポジトリの scratch-vm / scratch-gui）は実装完了。実際にゲームを進行
させるには、本クライアント（remote-client.js が呼ぶ /api/manage/connectGame 等）を
受けるゲームサーバー側 smalruby3 ライブラリの更新が必要。これは別リポジトリ
（NaCl-Ltd/smalruby-koshien-web）の作業だが、本リポジトリに tracking Issue を用意済み:

• feat(koshien-web): game server smalruby3 を新旧両対応に (koshien.xxx + when_connect_game + $配列 / 旧 Sprite.new do…end 維持) #763 game server smalruby3 を新旧両対応に（koshien.xxx + when_connect_game
  • $配列 / 旧 Sprite.new do…end 維持）
• chore(koshien-web): tmp/smalruby-koshien-web をdevpodでローカル実行可能化し新旧APIを動作確認 (rbwasm) #764 tmp/smalruby-koshien-web を devpod でローカル実行可能化し新旧 API を動作確認（rbwasm）

→ #763（実装+ブラウザ実機検証 完了）/ #764（devpod ビルド+新旧 API 動作確認 完了）。
ゲームサーバー (NaCl-Ltd/smalruby-koshien-web) 側の PR レビュー/マージのみ残（リポジトリ外作業）。
エディタ側サブ Issue（#739/#740/#741/#743/#762/#827）はすべて完了・マージ済み。

ゲームサーバー / プロトコルの要点

詳細リファレンスは作業ログ notes/koshien/protocol.md（git 管理外）に集約。要点:

• サーバー: Ruby + WEBrick、127.0.0.1:3000。Game.instance Singleton 状態機械。
• ターン進行は viewer 駆動: turnOver は viewer の turnTransition までブロック。move_to は予約で、座標確定は turnTransition 後。
• 行動数 2/ターン（move/getMapArea/setDynamite/setBomb、setMessage 除く）、move は 1/ターン。
• マップ 15×15、地形コード 0=空間/1,2=壁/3=ゴール/4=水/5=壊せる壁/-1=未探索。アイテム a-e(加点)/A-D(減点)、e=草薙剣。
• 採点: アイテム加減点 / 歩行ボーナス(+3/5マス) / ゴールボーナス(100→60) / 敵接触(-10, 剣あり+30)。
• 終了: completed / timeout / timeup。
• コーナーケースの宝庫 = game_server/spec/（水たまり・行動数上限・無効移動・タイムアウト・ゴール後 already_finished・アイテム折半 等）。
• client の calc_route はサーバー実装と別物（重み付きダイクストラで既知空間優先）。再現は ai_lib.rb に合わせる。

進め方

P0 理解 ✅ → P0.5 サーバー起動 → P1 (Sub-A) → P2 (Sub-B) → P3 (Sub-C)。各 Sub は独立 PR。