feat(scratch-gui): 甲子園 Ruby v2 対応（when_connect_game イベント hat + リスト引数 $配列構文）

[takaokouji]

Summary

スモウルビー甲子園拡張機能を Ruby v2 でも使えるようにする一歩目。リスト引数を取る 3 ブロック（calc_route / calc_goal_route / locate_objects）が v2 でエラーになる問題を修正します。Epic #738 / #743 Phase 2（editor）。

問題

generator がリスト引数をバージョン非依存で list("$名前") とハードコードしていたため、v2 では「list() syntax is only available in Ruby version 1」エラーで変換に失敗していました（他の甲子園ブロックは v2 で動作することは確認済み）。v2 ではリストはグローバル配列変数 $名前（$名前.push() / $名前[0]）で表現します。

Changes Made

• generator (ruby-generator/koshien.js): koshienListArg ヘルパーを追加し、version === '2' のときは list("$名前") ではなく $名前 を出力（calc_route の result/except_cells、calc_goal_route の result、locate_objects の result）。
• converter (ruby-to-blocks-converter/koshien.js): resolveListArg を追加。v2 では引数の配列変数（$名前 = data_variable）を convertToListBlock でリスト化して受理する。解決されるリスト名は v1 の list("$名前") と同一なので、フィールド値の互換性が保たれる。
• v1 の挙動は不変。

Test Coverage

• 新規 test/unit/lib/ruby-roundtrip/extension_koshien_v2.test.js: v2 で calc_route / calc_goal_route / locate_objects が $名前 構文で round-trip することを検証。
• 既存 v1 roundtrip (extension_koshien.test.js) + converter ユニット (koshien.test.js) が引き続き緑（回帰なし）。
• eslint / prettier 緑。

関連: クラス表現（class < Smalruby3::Sprite/Stage）について

v2 の本質は class 表現で、そのランタイム対応はクライアントライブラリ側（tmp/smalruby-koshien/src/lib）の対応が主です。これは別途パッチ + 開発者向け改善依頼として #743 にまとめています（検証済み）。本 PR はそのうち editor が出力する v2 コードの構文（リスト引数） を正す範囲です。

なお、v2 ステージのクラス名がライブラリの Smalruby3::Stage と衝突しうる件（lib の include Smalruby3 由来）は #743 に記録済みで、ライブラリ側のパッチ/命名で対応します（全 v2 出力に影響する汎用機構の変更は本 PR に含めません）。

Definition of Done

• v2 で 3 ブロックがエラーなく入出力（roundtrip）
• v1 の既存挙動が回帰しない
• ユニット/roundtrip テスト pass
• lint pass
• CI green
• ブラウザ確認（Playwright MCP, ?ruby_version=2）: 甲子園 v2 プログラムがエラーなくブロック化され、Ruby に戻すと $名前 構文で出力される

Related Issues

Refs #743 / Epic #738

🤖 Generated with Claude Code

[github-actions]

🚀 Preview deployed: https://smalruby.jp/smalruby3-editor/feature/issue-743-koshien-ruby-v2/

[takaokouji]

✅ ブラウザ DoD 確認（プレビューで実機検証, ruby_version=2）

プレビュー https://smalruby.jp/smalruby3-editor/feature/issue-743-koshien-ruby-v2/?ruby_version=2 で Playwright MCP により検証（CI も全 green）:

v2 の甲子園プログラム（リストは配列変数 $名前）を Monaco に入力 →

class Sprite1 < Smalruby3::Sprite
  when_flag_clicked do
    koshien.connect_game(name: "player1")
    koshien.calc_route(result: $最短経路)
    koshien.locate_objects(result: $地形, sq_size: 3, cent: "1:2", objects: "ABCD")
    koshien.move_to($最短経路[1])
    koshien.turn_over
  end
end

• コードタブへ切替: エラーなくブロック化（koshien_calcGoalRoute / koshien_locateObjects / connectGame / moveTo / turnOver 生成、エラーテキストなし）。
• ルビータブへ戻す: koshien.calc_route(result: $最短経路) / koshien.locate_objects(result: $地形, ...) と $名前 構文で再生成（list( なし、Monaco のエラーマーカーなし）。

→ 「v2 でエラーなくブロック化され、Ruby に戻すと $名前 構文で出力される」を確認。DoD のブラウザ項目を満たしました。

[takaokouji]

追加コミット: ゲーム接続をイベント hat 化（koshien.when_connect_game）

レビュー中に判明した重要な設計課題に対応しました。

問題: 甲子園プログラムはフラットな文列（koshien.connect_game(...) + 後続文）で生成され、v1 の Sprite.new do…end では走るが、v2 のクラス表現 class < Smalruby3::Sprite ではフラット文をスクリプトにできない。

対応: ゲーム接続を ブロックを取るイベント hat にし、AI 本体を do…end（サブスタック）に包む。

• generator: v2 は koshien.when_connect_game(name:) do … end（block.isStatement=true → scrub_ が next 連鎖を字下げ + end）。v1 はフラット維持。
• converter: koshien.when_connect_game(name:) do … end（v2）を hat + サブスタックとして解析。フラット koshien.connect_game(name:) は v1=正常 / v2=エラー（when_connect_game を使うよう促す）。
• ブロック opcode/構造は不変 → 既存 sb3 プロジェクトはそのまま読み込める。
• テスト追加: v2 when_connect_game roundtrip / v2 フラットエラー / v1 フラット維持。

ランタイム側（smalruby-koshien の src/lib）の when_connect_game 対応パッチは #743 に添付済み（検証済み）。

[takaokouji]

✅ ブラウザ DoD 確認: when_connect_game イベント hat（CI 全 green 後・更新プレビュー）

https://smalruby.jp/smalruby3-editor/feature/issue-743-koshien-ruby-v2/ を Playwright MCP で検証（#744 の CI は全 green）。

① v2: koshien.when_connect_game(name:) do … end がクラス表現に収まる形に

入力（ルビータブ）→ コードタブで変換 → 結果:

• 全ブロック生成（connectGame / getMapArea / calcGoalRoute / moveTo / turnOver）、エラーなし。
• koshien_connectGame は hat-root（topLevel=true / 親なし / サブスタックあり）= AI 本体を内包。
• ルビータブへ戻すと:

  koshien.when_connect_game(name: "player1") do
    koshien.get_map_area("0:0")
    koshien.calc_route(result: $最短経路)
    koshien.move_to($最短経路[1])
    koshien.turn_over
  end

  （本体は 2 スペース字下げ、リストは $最短経路、list( なし、エラーマーカーなし）

② v2: フラット koshien.connect_game はエラー

エラーマーカー: 「koshien.connect_game is only available in Ruby version 1. Please use koshien.when_connect_game(name: ...) do ... end instead.」

③ v1: フラット形式は従来どおり（後方互換）

ruby_version=1 で koshien.connect_game(name: "player1") + 後続文 → エラーなく変換、フラットのまま round-trip。

→ DoD のブラウザ確認項目（v2 でクラス本体に収まる / v2 フラットはエラー / v1 後方互換）をすべて満たしました。