feat: 甲子園 Ruby v2 対応（クライアントライブラリのパッチ + editor 修正）

[takaokouji]

Epic: #738 / 関連: Ruby v2 対応

ゴール

甲子園拡張機能は現在 Ruby v1 でしか動作しない。v2 でも動くようにする。
ユーザー指示により 2 段階 で進める:

1. クライアントライブラリ (tmp/smalruby-koshien/src/lib) の v2 対応 + パッチ作成 + ゲームサーバー開発者への改善依頼
2. スモウルビー(editor / scratch-gui) の v2 対応

なぜ v1 でしか動かないか（調査済みの editor 側原因）

/design 調査で判明: 甲子園ブロックのうち リストを引数に取る 3 ブロック
（calc_route / calc_goal_route / locate_objects）のジェネレーターが
バージョン非依存で list("$名前") をハードコードしている。v2 では list() 構文は
禁止（「list() syntax is only available in Ruby version 1」エラー）で、グローバル配列変数
$名前（$名前.push() / $名前[0]）で表現する必要がある。他の甲子園ブロックは v2 でも
動作することを確認済み。

Phase 1: クライアントライブラリの v2 対応 + パッチ

src/lib/smalruby3/koshien.rb 等は v1 前提（list("$名前") が返す Smalruby3::List
オブジェクトを result.replace(...) する想定）。v2 では result に プレーンな Ruby Array
($名前) が渡る。Array も replace/[]/map に応答するため大半は動く見込みだが、
要検証:

• v2 形式のコード（koshien.calc_route(result: $最短経路) 等）を実際にライブラリへ
  流し、壊れる箇所を洗い出す（List.new 既定値、Sprite#list、クラス構造 等）
• v1/v2 双方で動くようライブラリを改良
• パッチ（diff）を作成し、notes/koshien/ に保存
• ゲームサーバー開発者へ送る 改善依頼ドキュメント（背景・差分・互換性）を作成

Phase 2: editor (scratch-gui) の v2 対応

• src/lib/ruby-generator/koshien.js: v2 では list("$名前") ではなく $名前 を出力
  （calc_route / calc_goal_route / locate_objects）
• src/lib/ruby-to-blocks-converter/koshien.js: v2 では引数の配列変数 $名前 を
  リストとして受理（data_variable をリスト化）
• roundtrip テスト（v1/v2 両方）
• ブラウザ確認（?ruby_version=2）で v2 でもエラーなくブロック化・Ruby 復元

Definition of Done

• クライアントライブラリが v1/v2 双方で動作（ローカル実行で確認）
• ライブラリのパッチ + 開発者向け改善依頼ドキュメントが notes/koshien/ にある
• editor が v2 で 3 ブロックをエラーなく入出力（roundtrip）
• v1 の既存挙動が回帰しない
• lint / CI green / ブラウザ確認

依存

• ローカル Ruby 環境（test: 甲子園クライアント契約テスト基盤（実サーバーのゴールデン記録 + jest） #740 の P0.5 と共通）が前提。
• editor 側修正は feat(scratch-vm): 甲子園ブロックの固定値/状態実装（MockClient） #739（MockClient）とは独立に進められる。

[takaokouji]

Phase 1（クライアントライブラリ v2 対応）完了 — パッチ + 開発者依頼を作成

ユーザー明確化（v2 非対応の主因は class 表現）を受けて深掘りし、実機（Ruby 3.1.2）で検証しました。

実行モデルの違い

• v1: Smalruby3::Sprite.new("名前") do ... end … ブロックを instance_eval で即時実行（現状動く）
• v2: class Foo < Smalruby3::Sprite + クラスレベル DSL（set_x/when_flag_clicked）+ def initialize … 後から instantiate して hat を実行（現状未対応）

lib に加えた最小対応（v1 完全維持の後方互換）

1. クラスレベル DSL（set_* は name 以外 no-op、when_flag_clicked でブロック登録）
2. Sprite.inherited でサブクラスを World に登録
3. Smalruby3.start（at_exit）で Stage→Sprite を instantiate し when_flag_clicked を instance_exec
4. initialize を v1（name,options,&block）/ v2（引数なし super）両対応に

検証: v2 で when_flag_clicked がインスタンス文脈で実行され koshien.*/$グローバル変数 が解決。v1 の即時実行・Smalruby3::List・二重実行なしも維持。

成果物（git管理外 notes/koshien/patches/）

• koshien-lib-v2-class-support.patch（src/lib への diff、+123行）
• dev-request-v2-class-support.md（開発者向け改善依頼文）

⚠ editor 側と要調整（Phase 2 で対応）: lib は v1 の bare 参照のため include Smalruby3 しており、editor が v2 ステージのクラス名を Stage にすると lib の Smalruby3::Stage 再オープンと衝突（def initialize の $グローバル変数初期化が走らない）。→ editor 側で v2 ステージを 一意名 + < ::Smalruby3::Stage にする必要がある（検証で確認済み）。

Phase 2（editor / scratch-gui）残作業

• v2 ステージクラスの命名・継承（Stage 衝突回避 + < ::Smalruby3::Stage）← 主因
• リスト引数 3 ブロック（calc_route/calc_goal_route/locate_objects）の list("$x") → $x 構文
• v1/v2 roundtrip テスト + ブラウザ確認

[takaokouji]

🔄 パッチ更新: koshien.when_connect_game(name:) do … end 対応を追加

editor 側の設計（[フラットだとクラス化できない問題]）に合わせ、ゲーム接続をイベント hat 化しました。lib もこれに対応するよう 前回のパッチを差し替えます（v1 完全後方互換は維持、Ruby 3.1 で検証済み）。

editor の v2 出力（このコメント末尾のサンプル参照）:

class Player1 < ::Smalruby3::Sprite
  koshien.when_connect_game(name: "player1") do
    koshien.get_map_area("0:0")
    koshien.turn_over
  end
end

lib 追加点（前回パッチに上乗せ）

• クラス文脈の koshien: クラス本体で koshien.when_connect_game(...) を受けるため、Smalruby3::KoshienClassRegistrar と クラスメソッド Sprite.koshien を追加（インスタンスの koshien=Koshien.instance とは別物）。
• when_connect_game(name:, &block): 接続フックをサブクラスに登録。
• start: instantiate 後、登録フックごとに koshien.connect_game(name:) → 本体ブロックを インスタンス文脈で実行。
• v1（Sprite.new do … koshien.connect_game(name:) … end）は不変。

検証（connect_game をスタブして plumbing 確認）: connected_name="player1", 本体が ["3:4", "ran"] をインスタンス文脈で実行。

差し替え後の完全パッチ（git apply）

diff --git a/src/lib/smalruby3.rb b/src/lib/smalruby3.rb
index 96da5ba..a30f1b0 100644
--- a/src/lib/smalruby3.rb
+++ b/src/lib/smalruby3.rb
@@ -6,3 +6,32 @@ require_relative "smalruby3/sprite"
 require_relative "smalruby3/stage"
 
 include Smalruby3 # standard:disable Style/MixinUsage
+
+module Smalruby3
+  # v2 (class 表現) のエントリポイント。
+  # 登録された Sprite/Stage サブクラスを instantiate し、flag_clicked ブロックを実行する。
+  def self.start
+    Sprite.start
+  end
+end
+
+# v2 形式 (`class Foo < Smalruby3::Sprite`) の AI は class 定義だけでは実行されないため、
+# プログラム末尾まで評価された後 (at_exit) に start する。
+# v1 形式 (`Sprite.new do...end`) は定義時に instance_eval で即時実行されるので、
+# ここでは v2 のサブクラスが登録されている場合のみ start する (二重実行しない)。
+at_exit do
+  if Smalruby3::Sprite.v2_targets?
+    begin
+      Smalruby3.start
+    rescue SystemExit
+      raise
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      if Object.const_defined?(:AILib)
+        AILib.instance.logger.error("エラーが発生しました (#{e.class}) #{e.message}")
+        e.backtrace&.each { |line| AILib.instance.logger.error(line) }
+      else
+        raise
+      end
+    end
+  end
+end
diff --git a/src/lib/smalruby3/sprite.rb b/src/lib/smalruby3/sprite.rb
index ea76886..f17c986 100644
--- a/src/lib/smalruby3/sprite.rb
+++ b/src/lib/smalruby3/sprite.rb
@@ -4,22 +4,127 @@ require_relative "ignore_method_missing"
 require_relative "koshien"
 
 module Smalruby3
+  # v2: クラス本体の `koshien.when_connect_game(name:) do ... end` を受けるための登録器。
+  # クラス文脈では `koshien` がこのインスタンスを返し、when_connect_game がサブクラスに
+  # 接続フックを登録する。インスタンス文脈の `koshien`(= Koshien.instance) とは別物。
+  class KoshienClassRegistrar
+    def initialize(target_class)
+      @target_class = target_class
+    end
+
+    def when_connect_game(name:, &block)
+      @target_class._connect_game_blocks << {name: name, block: block}
+    end
+  end
+
   class Sprite
     attr_accessor :name
     attr_reader :variables
     attr_reader :lists
 
-    def initialize(name, options = {}, &block)
-      @name = name
-      @variables = []
-      @lists = []
+    # ------------------------------------------------------------------
+    # v2 (class 表現) 対応: クラスレベル DSL とライフサイクル
+    #
+    # v1: `Sprite.new("name") do ... end` … ブロックを instance_eval で即時実行
+    # v2: `class Foo < Smalruby3::Sprite` … クラス本体で set_xxx / when_flag_clicked
+    #     を宣言し、Smalruby3.start で instantiate して hat ブロックを実行する
+    # ------------------------------------------------------------------
+    class << self
+      # サブクラス定義時に World へ登録する (v2)
+      def inherited(subclass)
+        super
+        World.instance.register_target_class(subclass)
+      end
+
+      # set_name で渡された名前 (なければクラス名)
+      def _name
+        @_name
+      end
+
+      # when_flag_clicked で登録されたブロック一覧
+      def _flag_clicked_blocks
+        @_flag_clicked_blocks ||= []
+      end
+
+      def when_flag_clicked(&block)
+        _flag_clicked_blocks << block if block
+      end
+
+      # when_connect_game で登録された接続フック一覧 ({name:, block:})
+      def _connect_game_blocks
+        @_connect_game_blocks ||= []
+      end
 
-      self.variables = options[:variables] if options[:variables]
-      self.lists = options[:lists] if options[:lists]
+      # クラス文脈での事前定義レシーバー: `koshien.when_connect_game(name:) do ... end`
+      def koshien
+        @_koshien_registrar ||= KoshienClassRegistrar.new(self)
+      end
 
-      World.instance.add_target(self)
+      # editor が出力するクラスレベル DSL。
+      # ヘッドレスな甲子園実行では描画・コスチューム等は不要なので、
+      # name 以外は「受け取って無視する」ことでエラーを防ぐ。
+      def set_name(name)
+        @_name = name
+      end
+
+      SET_NOOP_METHODS = %i[
+        set_sprite set_x set_y set_direction set_visible set_size
+        set_rotation_style set_costumes set_sounds set_current_costume
+        set_backdrops set_current_backdrop
+      ].freeze
+      SET_NOOP_METHODS.each do |m|
+        define_method(m) { |*_args| nil }
+      end
+
+      # v2: 登録済みサブクラスを instantiate し、flag_clicked ブロックを実行する。
+      # Stage を先に生成して $グローバル変数を用意してから Sprite を動かす。
+      def start
+        return if @started # 1 プロセスにつき 1 回だけ
+        @started = true
+
+        classes = World.instance.target_classes.reject { |k| k == Smalruby3::Stage }
+        stage_classes = classes.select { |k| k < Smalruby3::Stage }
+        sprite_classes = classes - stage_classes
+
+        targets = []
+        targets.concat(stage_classes.map(&:new))
+        targets.concat(sprite_classes.map(&:new))
+
+        targets.each do |target|
+          target.class._flag_clicked_blocks.each do |block|
+            target.instance_exec(&block)
+          end
+          # when_connect_game: ゲームへ接続してから AI 本体 (do...end) を実行する
+          target.class._connect_game_blocks.each do |entry|
+            target.instance_exec { koshien.connect_game(name: entry[:name]) }
+            target.instance_exec(&entry[:block])
+          end
+        end
+      end
+
+      # v2 のサブクラスが定義されているか (at_exit で start すべきか判定)
+      def v2_targets?
+        World.instance.target_classes.any? { |k| k != Smalruby3::Stage }
+      end
+    end
+
+    # v1: (name, options, &block) / v2: 引数なし (サブクラスから super)
+    def initialize(name = nil, options = {}, &block)
+      @variables = []
+      @lists = []
 
-      instance_eval(&block) if block
+      if name.is_a?(String) || block
+        # --- v1: Sprite.new("name", options) do ... end ---
+        @name = name
+        self.variables = options[:variables] if options[:variables]
+        self.lists = options[:lists] if options[:lists]
+        World.instance.add_target(self)
+        instance_eval(&block) if block
+      else
+        # --- v2: class Foo < Smalruby3::Sprite (サブクラスの super 経由) ---
+        @name = self.class._name || self.class.name
+        World.instance.add_target(self)
+      end
     end
 
     def stage?
diff --git a/src/lib/smalruby3/world.rb b/src/lib/smalruby3/world.rb
index cba7095..650684e 100644
--- a/src/lib/smalruby3/world.rb
+++ b/src/lib/smalruby3/world.rb
@@ -6,6 +6,8 @@ module Smalruby3
 
     attr_accessor :stage
     attr_accessor :sprites
+    # v2 (class 表現) 用: Sprite/Stage を継承したクラスの登録先
+    attr_reader :target_classes
 
     def initialize
       reset
@@ -15,6 +17,12 @@ module Smalruby3
       clear_sprites
     end
 
+    # v2: Sprite/Stage を継承したクラスを登録する (inherited フックから呼ばれる)
+    def register_target_class(klass)
+      @target_classes << klass unless @target_classes.include?(klass)
+      klass
+    end
+
     def add_target(stage_or_sprite)
       if stage_or_sprite.stage?
         stage = stage_or_sprite
@@ -37,6 +45,7 @@ module Smalruby3
       @stage = nil
       @sprites = []
       @name_to_sprite = {}
+      @target_classes = []
     end
   end
 end

[takaokouji]

🔄 v2 サンプル AI の更新（koshien.when_connect_game 形式）

先のサンプルは v2 のゲーム接続を旧フラット形式で書いていました。新設計（接続をイベント hat 化）に合わせ、v2 の正規形に更新します。editor が v2 で生成・解析するのもこの形です。

v2 実戦 AI（正規形）

# encoding: utf-8
require "smalruby3"

class MainStage < Smalruby3::Stage
  def initialize
    super
    $最短経路 = []
  end
end

class Player1 < Smalruby3::Sprite
  koshien.when_connect_game(name: "player1") do
    loop do
      koshien.get_map_area(koshien.player)
      koshien.calc_route(result: $最短経路)
      koshien.move_to($最短経路[1])   # v2 は 0-based: [0]=現在地, [1]=次の手
      koshien.turn_over
    end
  end
end

• koshien.when_connect_game(name:) do … end が「ゲームに接続したら本体を実行」する hat。本体（do…end）が AI ループ。
• これによりクラス本体（class < Smalruby3::Sprite）の中に AI を記述できます。
• v1 は従来どおり Sprite.new("…") do koshien.connect_game(name: "…"); … end（前掲③のまま）。

v2 スモークテスト（サーバー不要・検証済み）

require "smalruby3"

# connect_game は HTTP するためスタブ（plumbing のみ確認したい場合）
Smalruby3::Koshien.instance.define_singleton_method(:connect_game) { |name:| puts "connect: #{name}" }

class MainStage < Smalruby3::Stage
  def initialize; super; $log = []; end
end

class Player1 < Smalruby3::Sprite
  koshien.when_connect_game(name: "player1") do
    $log.push(koshien.position(3, 4))
    puts "v2 when_connect_game OK: #{$log.inspect}"
  end
end

期待出力: connect: player1 → v2 when_connect_game OK: ["3:4"]