# カード個体の値と所有者を指定した参照

## 山札の一番上だけを選ぶ

場所付き実カード選択のActionに `topOnly:true` を指定します。`choice.display:"surface"` と組み合わせると、各山・収納先の先頭1枚だけを盤面で選び、上部バーで確定します。裏向きでも選べますが、名前・表面・説明・変数は公開せず裏面だけを表示します。2枚目以降のIDによる回答はサーバーが拒否します。

`cardSelector.condition` は `{"kind":"all"}` にし、`cardSelector.selection` と `choice.candidateConditions` は指定しません。中身で候補を絞ったり並べ替えてから先頭を選ぶことはできません。省略・falseは従来の一覧選択を維持します。形式20／4のまま、必要な山札選択へ追加してください。旧基盤では未対応です。[読込可能な例](examples/blind-top-card-choice.json)。

複数の実カードを選ぶと、選択した順に1・2・3…を表示します。直接選択ではカード右上、一覧・ボタン形式ではカード名に表示します。解除すると番号を詰め、選び直したカードは最後の番号になります。追加設定・JSON修正は不要です。

「カードの変数を変更」は選択した実カードだけに適用されます。同じ種類の別のカードへは波及せず、まとめて山にする・分ける・移動・保存再読込・入力待ちの再開後も保持します。

カード定義のcardDefs[].variablesは初期値です。実行中の個体差分は任意のcardStates[].variables（文字列の辞書）に保存され、未指定の項目は初期値を使います。runtimeCardId・順番・公開範囲と一緒に保持してください。作者が個体IDを手作りして対応付ける必要はありません。既存JSONはそのまま読み込め、形式20／処理形式4を維持します。

個人・チームタブで作られたカードにも元のカード種類による条件を使えます。定義IDへプレイヤーIDを文字列連結しないでください。保存する外観と、手札から出す向きも元の定義を参照します。

## 変数の型と候補

一時値の属性では、カード部品名付きの変数候補を選べます。保存パスは["card-variables","カード部品の定義ID","変数名"]です。同名でも数値型と文字型を区別し、別のカード種類の変数を指定したら停止します。従来の["variables","変数名"]も使用できますが、異なる型を混ぜて計算・代入する場合は型を明示した候補や数値→文字の変換を使ってください。

## プレイヤー・チームのカウンターなど

一時値の属性を組み立てる画面で、ゲーム参照から対象プレイヤー／チーム→「このプレイヤーの部品」／「このチームの部品」を選べます。部品の「部品の定義ID」で対象を絞り、1つの部品として取得して「値」を参照してください。タイマーは現在の秒数、カウンター・サイコロは現在値です。所有者は必ず明示し、他人の部品を自動選択しません。

型付きの参照では部品の「中のカード」も通常の対象選択と同じ所在を使います。通常ボックス・ホルダー・ゴミ箱を区別します。枚数を数えるだけならカード名・秘密属性を読まない方法を使ってください。

フェーズ文章のカード変数も、通常のカード表示と同じ公開設定とタブ閲覧権限に従います。本人以外・チーム限定等の値を文章に表示しても公開範囲は広がりません。

[保存・読込できる個体値のサンプル](examples/physical-card-values.json)。

## 実カードの直接選択

`choice.display:"surface"` は `sourceKind:"card-location"` と `cardSelector` を持つ実カード選択専用。手札・ホルダー・盤面上の候補を直接押し、操作バーの「選択タイトル ［確定］」から回答する。直接選択中は同じ行へまとめ、「回答画面を開く」・回答人数・定型の操作説明・選択枚数表示・重複するフェーズ案内を出さない。未選択や枚数不足では確定を無効にし、送信中・失敗時の表示は維持する。ピースと種類・独自候補には指定しない。1枚の選択も確定操作を必要とする。複数枚は1回の回答として送信する。

回答値は既存の不透明な runtimeCardId 配列。未確定の選択は回答者の端末内だけで保持し、再読込では解除する。選択以外の移動・裏返しは待機中のまま禁止する。山はその場に個体別の横スクロールを表示し、同名カードを区別する。本人の候補手札は自動で開き、手札候補がなく別タブに候補があれば閲覧権限内のタブへ移る。手札・ホルダーの重ね表示は選択中だけ解除する。

サーバーは従来どおり回答者、runId、候補、個体、重複、最少・最多数を検証してから同じ継続処理を再開する。秘密投影と候補スナップショットの範囲は変更しない。私有プロンプトには実行用 selector を含めないため、画面判定は検証済みの表示形式・候補種別で行う。

省略時の `list` と既存の `buttons` は従来表示を保持する。形式20／処理形式4のまま、直接選択を希望する物理カード choice だけ display を surface へ変更すればよい。カード移動や後続処理を画面へ移植しない。旧クライアントはこの表示を保証しないため、新しい本体とセットで利用する。本番公開は別途必要。

所有者：`runtime-surface-choice-model.ts` は対象・個体選択・所在の純粋判定、`runtime-surface-choice.tsx` は回答者別の一時ドラフトと実カード表示、`runtime-surface-choice.css` はその表示、`RuntimeAutomationRunDialog` は既存の送信・再送・期限と上部バー、`GameController` は配置と閲覧導線を所有する。手札／ホルダー／盤面の描画は同じ `RuntimeSurfaceCard` を利用する。タッチのネイティブ操作部品は手札ドラッグを開始しない。

回帰確認：同名2個体、山の途中の個体、複数枚と上限、解除、別回答者、観戦、二重・偽造・他人の回答拒否、継続、再送失敗、PC・スマホ縦横、手札と公開ホルダーを検査する。内部の実カード選択回帰テスト と対応する契約検査を入口とする。

`use-runtime-surface-choice-navigation.ts` は候補の手札を要求ごとに一度だけ開く。その後は閉じる・別タブを見る操作を許す。選択対象を含む盤面の `BoardItem` は操作しないdivの外枠となり、内側の実カードボタンとの入れ子を作らない。待機中のinertは候補ボタンを含む手札カード／ホルダーだけ解除し、通常の移動・回転・シャッフルや対象外部品の禁止は維持する。送信中も上部バーを残し、カードをロックする。失敗時は同じ選択のまま再試行できる。

狭い画面の直接選択中は、手札ホストの明示的な `data-surface-choice` 状態で、手札を上部バーより下のゲーム領域へ収める。高さの上限をその領域に合わせ、縦横スクロールを許す。通常の手札配置と保存済みの幅・高さは変更しない。上部バーの案内行はメニューの操作より前に置く。

## カードの配置済みピース

型付き実カード参照の`pieces`（配置済みピース）は、その個体の配置枠にあるピース集合を返します。完成時の返却などに使えます。カードと各ピースの両方の閲覧・属性公開範囲を維持し、非公開カードを参照して秘密のピース情報を取得することはできません。