JokerComboAdvisor/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

"Joker Combo Advisor" — a Steamodded (SMODS) mod for Balatro that scores shop/pack
jokers against the player's current jokers, shows a "Combo Advisor" tooltip on hover,
and pulses strongly recommended cards. Pure Lua, no build step.

## Commands

Syntax check, then run the test suite — **always both, after every edit**:

```sh
luac -p main.lua synergies.lua config.lua test.lua
lua test.lua
```

`test.lua` stubs the handful of game globals `main.lua` touches (the game cannot be
launched headlessly here) and then exercises the real engine, the real database and
the real catalog tab builders. It is the only safety net; there is no other harness.
It enforces, among other things:

- Score tiers: famous explicit pair + tags = 6, hand-type/suit cluster = 4, single
  tag match = 2, generic mult+xmult complement = +1 on top, unrelated = 0.
- **No orphan wants** — a `wants` tag nothing gives is a payoff with no enabler.
- **No dead gives** — a non-engine tag given but never wanted can never change a
  score, so it is invisible dead weight. (This caught `hand_level`, given by Space
  and Burnt Joker and wanted by nobody.)
- **Every theme is discoverable** — theme discovery needs a giver and a wanter on two
  *different* fielded jokers, so a theme with fewer than two members is an
  achievement no player can ever earn and pins the Progress tab under 100% forever.
  (This caught `four_kind`, whose only member was The Family.)
- `theme_info` and `THEME_TABS` cover exactly the same tag set.
- Pair/clash/caution keys all exist; every blurb fits its ~34-char row.
- Every card the catalog pages emplace is materialized (see the UI notes below).
- Jokers with no tags at all are listed in `EXPECTED_INERT` on purpose — a joker
  landing there by accident scores 0 against the entire game and says nothing.

To poke at the engine by hand, copy the stub block from the top of `test.lua`.

## In-game verification (this machine)

- The mod is **symlinked** into the live Mods folder:
  `~/.local/share/Balatro/Mods/JokerComboAdvisor -> ~/Documents/JokerComboAdvisor`
  (this repo). Edits here go live on next game launch — do not copy files anywhere.
  Lovely reads that folder as `C:\users\steamuser\AppData\Roaming\Balatro\Mods`.
- Game: Steam/Proton at `~/.local/share/Steam/steamapps/common/Balatro`. Lovely
  injector + Steamodded 1.0.0-beta are already installed; mods are managed via
  Balatro Mod Manager.
- Crash/load logs: `~/.local/share/Balatro/Mods/lovely/log/` (newest file).
- Remote: `https://git.aleshym.co/funman300/JokerComboAdvisor` (private, user's
  Gitea). `git push` just works: it authenticates through the global libsecret
  credential helper (`credential.helper=/usr/lib/git-core/git-credential-libsecret`).
  Never copy a token into the repo or the remote URL. Commit per feature.
- The `tea` CLI is installed and logged in as `funman300`, but its stored login has
  `auth_method: oauth` and **no token**, so `tea` cannot create repos or call the
  API — it is not the thing that authenticates pushes, despite what this file used
  to say. Creating a new remote repo needs the web UI (or a token added to `tea`).

## Architecture

Three-layer split; `JCA` is the single global namespace:

- `synergies.lua` — data only. Returns `{ jokers = {...}, pairs = {...} }`. Each of
  the 150 vanilla jokers gets `gives` (capabilities it adds) and `wants`
  (capabilities that strengthen it) tag lists, converted to sets at the bottom of
  the file. `PAIRS` lists famous explicit combos worth a flat +4.
- `main.lua` — engine + game integration:
  - Scoring: `JCA.score(a, b)` = explicit pair bonus (+4) + 2 per give→want tag
    match in each direction + 1 for the generic "+Mult/+Chips source with an
    ×Mult joker" complement (second return value flags when that +1 applied).
    `JCA.partners_for(card)` aggregates over `G.jokers.cards`; total ≥
    `JCA.config.threshold` ⇒ recommended. The generic +1 counts toward the
    total once per candidate, not per owned joker — since tag/pair scores are
    even and the threshold is 4, the generic bonus alone can never trigger a
    recommendation, so a pulsing card always has a nameable partner. Jokers
    whose multiplier the generic rule misreads opt out with
    `{no_generic = true}` in `synergies.lua` (Joker Stencil: its ×Mult grows
    with *empty* slots, so "+Mult jokers feed it" is backwards).
  - UI hooks: wraps `Card:generate_UIBox_ability_table` to append a tooltip entry
    to `aut.info` (format: array of rows-of-UIT-nodes plus a `.name` string —
    must match what vanilla `info_tip_from_rows` expects), and wraps
    `Card:update` for the ~2.5s pulse on recommended shop cards and the
    partner highlight (hovering a joker juices its owned partners ~0.9s;
    partner set cached on the card as `jca_hl`, dropped when hover ends).
    All hook bodies are pcall-wrapped so a scoring bug can never crash a
    run — keep it that way.
  - Sell advisor: `JCA.weakest_link()` (full board + ≥3 jokers + a strict
    minimum required, else nil) flags the lowest-scoring owned joker with a
    red verdict row; suppressed by learning mode, toggled by
    `config.sell_advisor`. Its ranking subtracts `CLASH_PENALTY` (odd, so it
    always breaks a tie) per clash with an owned joker — the joker eating
    another one's payoff is the one you want to cut. This is the **only**
    place a clash changes a number; `JCA.score` stays pure, because a trap
    must never make a card look like a combo.
  - Copy advisor: `JCA.copy_source(card)` returns what an owned Blueprint or
    Brainstorm is *actually* copying, from the live board order — Blueprint
    takes the joker to its right, Brainstorm the leftmost — plus whether
    vanilla will copy it at all (29 centers carry `blueprint_compat = false`).
    The tooltip names the target, or says it is copying nothing. Do not
    rebuild this with the `a and b or c` idiom: for a rightmost Blueprint the
    right-hand slot is nil and the idiom falls through to the leftmost joker,
    confidently reporting the wrong card.
  - Public API for other mods: `JCA.register(key, gives, wants, opts)`,
    `JCA.register_pair(a, b, blurb)` (sets `JCA._pairs_dirty` so the
    Combos tab re-sorts), `JCA.register_clash(a, b, warning)`. Unknown
    tags are dropped with a log line, never an error.
  - Config tab: registered on `SMODS.current_mod.config_tab`, guarded by
    `if SMODS.current_mod` so standalone tests don't need full stubs.
  - Synergy catalog: `SMODS.current_mod.extra_tabs` adds Combos/Engine/
    Economy/Hands tabs (plus a text-only Progress tab with discovery
    completion bars) that render real `Card` objects in `CardArea`s
    (collection-style, so hover shows each joker's own tooltip). One theme
    per page; pagers swap the `tab_contents` UIBox from an option-cycle
    callback — the same pattern as SMODS's achievements tab. Because pages
    contain live Card/CardArea objects, tab definitions must be rebuilt on
    every call — never cache the node trees. Cards must be `start_materialize`d
    as they are emplaced (`card_row_node`), exactly as every vanilla collection
    page does — that call *is* the appear animation, and without it cards pop
    in with no animation on tab open and page switch. Only the first card of a
    page build plays the sound (vanilla's `i>1 or j>1` silence flag); tab defs
    call `begin_page()` so the counter spans the page, not one row. The same
    tabs open in-run via a "Combos" HUD button (wrapped `create_UIBox_HUD`,
    injected into the `button_area` node under Run Info/Options); the pagers
    work there because vanilla `create_tabs` also names its body
    `tab_contents`.
  - Discovery: `CardArea:emplace` hook calls `JCA.check_discoveries` when a
    joker lands in `G.jokers`; famous pairs fielded together persist in
    `config.discovered` (saved immediately via `SMODS.save_mod_config`) and
    per-run in `G.GAME.jca_run_combos`. Undiscovered pairs render face-down
    with a `???` caption in the Combos tab; blurb replaces it once fielded.
    Themes (every `theme_info` tag) persist in `config.themes_found` once
    two DIFFERENT jokers connect the tag (giver + wanter; a joker carrying
    both sides needs a second joker). One toast per emplacement, famous
    pair outranking theme. Badge/progress render in `theme_tab_def`; toast
    names come from `JCA.theme_names` (filled after THEME_TABS, used only
    at gameplay time).
  - Post-run recap: wraps `create_UIBox_game_over`/`create_UIBox_win` and
    inserts a "Combos fielded this run" row (from `G.GAME.jca_run_combos`)
    relative to vanilla button ids (`from_game_over`; `from_game_won` or
    `win_cta`) via a parent-trail walk — anchor depths differ per screen.
  - Learning mode (`config.learning_mode`): suppresses the pulse and the
    "Strong pick!" line but never the explanations. No-synergy buy-area
    tooltips show "Looking for:"/"Offers:" hints from `TAG_LABEL`.
    `synergies.lua` also exports `theme_info` (one teaching sentence per
    catalog tag — keep ≤ ~90 chars and cover every THEME_TABS tag).
  - The real (Lovely-patched) game source is readable at
    `~/.local/share/Balatro/Mods/lovely/dump/` — check it before assuming
    what a vanilla function returns or expects.
- `config.lua` — default settings (`pulse`, `owned_tooltip`, `threshold`).
  Steamodded loads and persists this table itself; read it only via
  `SMODS.current_mod.config` (exposed as `JCA.config`).

## Conventions and gotchas

- **Cluster tags** (hand types `pair`/`straight`/`flush`/…, suits, `planet`,
  `spectral_gen`): put the same tag in *both* `gives` and `wants` of every member
  so members mutually reinforce (2+2 = 4). Pure enablers (e.g. Four Fingers,
  Smeared, Pareidolia, DNA) only `give`; pure payoffs only `want`.
  A cluster tag needs all three `TAG_TEXT` phrasings, not just `both`: `both` is
  only true when *both* jokers sit on both sides of the tag, and `JCA.explain`
  requires that before using it. Four Fingers does not "reward Straights" — it
  makes them reachable. The suite enforces the three phrasings.
- A tag needs **both sides to exist, on at least two different jokers**: something
  must give it, something must want it, or it is dead data that can never change a
  score — and if it is also a theme, an achievement nobody can earn. `lua test.lua`
  enforces both directions; run it after every `synergies.lua` edit.
- Tooltips teach: `JCA.explain(hovered, partner)` picks one reason per partner
  — famous-pair blurb (third element of each `PAIRS` entry), else the first
  `TAG_ORDER` match phrased from `TAG_TEXT` (give/want/both variants), else
  the generic mult×xmult line. Every non-engine tag (anything besides
  mult/chips/xmult) MUST have a `TAG_TEXT` entry; new `PAIRS` entries need a
  blurb under ~34 chars so name + blurb fits one tooltip row.
- Vanilla center keys contain intentional misspellings/abbreviations — do not
  "fix" them: `j_gluttenous_joker`, `j_selzer`, `j_ticket` (Golden Ticket),
  `j_trousers` (Spare Trousers), `j_ring_master` (Showman), `j_caino` (Canio),
  `j_delayed_grat`, `j_todo_list`.
- Unknown joker keys (from other mods) must keep scoring 0 — never index
  `JCA.db[key]` without a nil guard.
- Display names go through `localize{type='name_text', set='Joker', ...}` with a
  pcall + `center.name` fallback.
- Anti-synergies never affect scores. Known traps are warning-only data:
  `CLASHES` (pairwise, red "Clashes -" tooltip line vs owned jokers) and
  `CAUTIONS` (per-joker, buy-area "Caution:" line) in `synergies.lua`, same
  ~34-char blurb budget as `PAIRS`. Learning mode keeps warnings visible.
  **Verify every new trap against the dump before adding it** — a warning that
  is merely plausible is worse than none. The mod once shipped a `j_smeared` +
  `j_flower_pot` clash that was exactly backwards: Flower Pot fills its four
  suit slots with a greedy `if/elseif` chain (`card.lua:4256`) and Smeared makes
  Hearts answer for Diamonds, so any two red + two black cards fill the pot. It
  is one of the best combos in the game, and the mod was warning players off it.
  Most traps hinge on the scoring-pipeline order in `functions/state_events.lua`
  (`before` → per-card `individual` → `joker_main`): Vampire strips enhancements
  in `before`, so every enhancement payoff that reads them in `individual` —
  Golden Ticket, Glass, Stone, Driver's License — is looking at cards it has
  already eaten.
- The UI hooks used to be the untested surface. They are now covered in the real
  game by the smoke harness (see below). If a tooltip regression is reported,
  run it, then suspect the `aut.info` entry format and check the lovely log.

## In-game smoke tests

`lua test.lua` stubs the game, so it cannot tell you that vanilla accepted the
tooltip format or that a card is actually animating. The smoke harness runs the
real engine — real `Card` objects, the real `Card:generate_UIBox_ability_table`
pipeline, a real overlay `UIBox` — with no clicking:

```sh
~/Documents/BalatroSmoke/run.sh JokerComboAdvisor
```

It boots the game, runs `scenarios/JokerComboAdvisor.lua`, quits, and prints a
pass/fail report (non-zero exit on failure). Close Balatro first; it needs a clean
boot. Scenarios live in the harness repo, not here.

It covers the surfaces this repo's tests cannot reach: the hover tooltip naming a
partner, the clash and caution lines, discovery on emplace, and — the reason it
exists — that catalog cards really do `start_materialize` on tab build *and* on
page switch (asserted via `card.dissolve > 0` in the live UIBox).

The harness suppresses every save path and verifies from outside that no discovery
state leaked, so running it can never spoil the catalog. Do not "fix" that by
reversing writes after the fact — a crashed scenario would skip the reversal.