docs/interaction_patterns.md

# LovecaSim: Interaction Cheat Sheet

> [!NOTE]
> This document details the interaction flow between the **Rust Engine** and the **Frontend**, specifically how abilities pause (suspend) for user input.

## Opcode Categorization

### 1. Automatic (Non-Interactive)
These opcodes resolve immediately without stopping the interpreter.
- `O_DRAW`: Draws cards to hand.
- `O_BOOST`: Adds to score bonus.
- `O_BUFF` / `O_BLADES`: Adds power/blades to members.
- `O_ACTIVATE_ENERGY`: Untaps energy cards.
- `O_NEGATE`: Marks triggers as negated.
- `O_CHARGE`: Untaps energy from deck.

### 2. Mandatory Choices (Suspends)
These opcodes **always** pause and wait for an `ACTION_ID` response.
- `O_SELECT_MODE`: Opens a modal for branching logic. (ID Range: `570+`)
- `O_COLOR_SELECT`: Opens a color picker. (ID Range: `580-585`)
- `O_TAP_O`: Requests selection of an opponent's stage slot. (ID Range: `600-602`)

### 3. Dynamic Choices (Context Dependent)
These opcodes may skip interaction if only one valid target exists, or if certain attributes are set.
- `O_PAY_ENERGY`:
    - **Automatic**: If no optional bit is set, it auto-taps.
    - **Interactive**: If `attr & 0x82` is set, it asks "Pay Energy?" (ID Range: `550-551`).
- `O_LOOK_AND_CHOOSE` (List Selection):
    - Opens a card list overlay. (ID Range: `600+`)
- `O_TAP_M`:
    - **Automatic**: If selecting "Self" or only one member.
    - **Interactive**: If `attr & 0x02` is set, it asks for a specific member.

## Action ID Reference Table

| Range | Context | Usage |
| :--- | :--- | :--- |
| `0` | Global Skip | Discard remaining looked cards, skip optional cost, "No" to promt. |
| `500-559` | Hand | Selecting a card currently in hand. |
| `560-569` | Generic | Resumption signals. |
| `570-579` | Modal Mode | Choosing Option A/B/C from `SELECT_MODE`. |
| `580-585` | Modal Color | Pink(0), Red(1), Yellow(2), Green(3), Blue(4), Purple(5). |
| `600-602` | Stage Slots | Left, Mid, Right (Self or Opponent). |
| `600-659` | List Index | Choosing the N-th card in a "Looked Cards" or "Discard" list. |

## Resumption Logic in `interpreter.rs`
When an opcode calls `suspend_interaction`, the following happens:
1. `state.phase` shifts to `Phase::Response`.
2. A `PendingInteraction` is pushed to the stack containing the `program_counter` (IP) of the CURRENT instruction.
3. The engine returns controle to the caller.
4. The caller (Frontend/Server) must send a `step(action_id)` call to resume.
5. `resolve_bytecode` restarts from the stored IP, injecting the `action_id` into `ctx.choice_index`.

## State Transparency (The Visibility Gap)

The following engine states are **not** currently surfaced through the main Action serialization:

| Gap | Description | Impact |
| :--- | :--- | :--- |
| **Passive Stats** | Constant power/blade buffs from other members. | Card value in sidebar might not match calculated logic. |
| **Queue Depth** | How many abilities are still waiting to resolve. | Player doesn't know "one more popup is coming". |
| **Filter Logic** | Why a specific card is selectable (or not). | Debugging complex filters (e.g., "Member of Unit X with Cost >= 3"). |
| **Progress Count**| "Pick 1 of 3" status during multi-picks. | Action label is generic (e.g., "Select Slot 1"). |

### Recommended Verifications
- **For Passives**: Manually inspect `player.blade_buffs` or `player.heart_buffs` in the engine log.
- **For Filters**: Cross-reference the `filter_attr` bitmask with `logic.rs:card_matches_filter`.
- **For Queue**: Check `gs.pending_abilities.len()` in the debugger.