Merge branch 'dev' of https://github.com/bryanthaboi/gen1recomp into dev

docs/modding.md

@@ -1111,6 +1111,37 @@ own state, preserving selective control outside a battle; a wrapper that only
 owns battle presentation should return `false` only for its active battle or
 text-box state.
 
+`pokemon.level_visible` (RFC 0019) takes a Pokémon's level off the screens
+that print it, without moving anything else on them:
+
+```lua
+mod.hooks:wrap("pokemon.level_visible", function(next, mon, ctx)
+  -- ctx = { where = "battle.enemy" | "battle.player" | "party" | "summary",
+  --         game = <Game> }
+  if myMode.active and ctx.where ~= "party" then return false end
+  return next(mon, ctx)
+end)
+```
+
+It receives `(next, mon, ctx)` and defaults to `true`, so vanilla rendering
+is unchanged. Only an explicit `false` suppresses; `nil` and anything else
+print, so a wrapper that forgets a branch cannot blank a screen by accident.
+The `<LV>` glyph goes with the digits, and on status page 2 so does the
+`<to>` arrow that points at the next level, because an arrow with nothing
+after it is half a sentence. A status condition still replaces the level on
+a battle healthbox exactly as it does in the cart, so hiding a level never
+hides `PSN` or `BRN`.
+
+`ctx.where` names the surface rather than the widget, because the number
+means different things on different screens: on a battle HUD an opponent's
+level is information about them, on the party and status screens your own
+level is information about you. A mode can hide one and keep the other.
+
+**Gen 1 only for now.** The Gen 2 screens keep their own level readouts and
+do not consult this hook, and neither does the Gen 1 PC box list, where the
+level is part of a row label rather than a drawn field. Both are noted in
+RFC 0019 as follow-ups.
+
 `core.logic_speed` receives `(next, game)` once per `Game:logicSpeed()` call
 (once per frame). Vanilla behavior resolves the per-category GAME SPEED
 option (`GameSpeed.CATEGORIES`: overworld/battle/menu) for whichever

docs/rfcs/0019-pokemon-level-visible.md

@@ -0,0 +1,157 @@
+# RFC 0019: `pokemon.level_visible` — a level a mode can take off the screen
+
+## Status
+
+Proposed.
+
+## Motivation
+
+A Pokémon's level is printed on four Gen 1 surfaces — both battle
+healthboxes, the party rows, and page 1 and page 2 of the status screen —
+and every one of them prints it unconditionally. There is no seam. A mode
+that wants the number gone has exactly two options today, and both are bad.
+
+It can paint over the text from `render.hud`, which means knowing four pixel
+rectangles, matching the background shade, and surviving the palette flashes
+and the healthbox slide-in. Or it can monkey-patch the drawing modules from
+inside its sandbox, which works — `require` hands a mod the engine's own
+table — and is precisely what `CONTRIBUTING-mods.md` tells mods not to do.
+A mod that took the second road already deleted its patching layer once, for
+the reasons that document gives.
+
+The motivating case is a battle royale where every party is scaled to a
+shared rung that rises with the fog. The number on the healthbox is
+therefore never news — it is the same for everyone, it changes on a clock,
+and a player reading `:L37` on an opponent learns nothing except that they
+are playing the same match. Worse, it reads as a threat it is not: a Lv37
+opponent looks dangerous to a player who has not worked out that their own
+team is Lv37 too. The mode wants the level off the HUD and out of the party
+list, and the announcement it replaces it with is one line about everyone
+getting stronger at once.
+
+Nothing about that is specific to a battle royale. A randomizer that hides
+levels to keep an encounter unreadable, a challenge run that forbids
+level-checking, a hard mode that withholds an opponent's level, and a
+"blind" Nuzlocke all want the same switch, and none of them should have to
+learn where the `<LV>` glyph lives.
+
+## The decision it extends
+
+This extends the **additive, guarded seam convention** Route B in
+`CONTRIBUTING-mods.md` documents, and is gated by the parity guarantee
+`tests/engine/gate_meta_coverage.lua` enforces.
+
+It sits with the presentation predicates already on the battle screen —
+`battle.status_hud_visible`, `battle.bottom_ui_visible` and
+`battle.caught_marker_visible` — and takes the same shape: a hook consulted
+behind `Runtime.wantsHook`, defaulting to visible, where only an explicit
+`false` suppresses. The difference is that a level is not a battle-only
+readout, so this one is not named `battle.*` and carries the surface that
+asked.
+
+There is no in-repo D-number registry to amend.
+
+## Exact API delta
+
+### New hook: `pokemon.level_visible`
+
+```lua
+mod.hooks:wrap("pokemon.level_visible", function(next, mon, ctx)
+  -- ctx = { where = "battle.enemy" | "battle.player" | "party" | "summary",
+  --         game = <Game> }
+  if myMode.active and ctx.where ~= "party" then
+    return false      -- the level is not printed on that surface
+  end
+  return next(mon, ctx)   -- true: printed, as today
+end)
+```
+
+Default `true`. Only an explicit `false` suppresses; `nil` and every other
+value print, so a wrapper that forgets a branch cannot blank a screen by
+accident.
+
+`ctx.where` names the surface rather than the widget, because the number
+means different things on different screens: on a battle HUD an opponent's
+level is information about *them*, on the party and status screens your own
+level is information about *you*. A mode that wants to hide the first and
+keep the second can, and the motivating mode does exactly that.
+
+### New module: `src/ui/LevelDisplay.lua`
+
+One function, `LevelDisplay.visible(mon, where, game)`, wrapping the
+`wantsHook`/`call` pair. It exists so the four call sites are a one-line
+guard each instead of four copies of the same five lines, and so the hook
+has one definition of "visible" rather than four that can drift.
+
+### Call sites
+
+| Surface | File | `where` |
+| --- | --- | --- |
+| Enemy healthbox | `src/battle/BattleState.lua` | `battle.enemy` |
+| Player healthbox | `src/battle/BattleState.lua` | `battle.player` |
+| Party rows | `src/ui/PartyMenu.lua` | `party` |
+| Status page 1 and 2 | `src/ui/SummaryMenu.lua` | `summary` |
+
+No layout moves. Each site keeps its own hand-rolled PrintLevel rule
+(`home/pokemon.asm:335-345` — the `<LV>` tile, then the digits, with a level
+of 100 writing its third digit back over the tile); it just asks first.
+
+Two details are deliberate:
+
+- **A status condition still replaces the level on a healthbox**, exactly as
+  it does in the cart, so hiding the level never hides `PSN` or `BRN`. The
+  guard is an `elseif` on the existing status branch, not a wrapper around
+  it.
+- **On status page 2 the `<to>` arrow is hidden with the level it points
+  at.** The arrow introduces the next level; on its own it is half a
+  sentence. The EXP-to-next-level figure beside it is a different field and
+  still prints.
+
+### No other surface changes
+
+No event, no registry, no save field, no manifest key.
+
+## Migration
+
+None. The hook is additive and defaults to current behaviour.
+
+## Verification
+
+- `tests/modkit/cases/pokemon_level_visible.lua` — the contract through the
+  public mod API: default true with no mod, `false` suppresses, the surface
+  and the mon reach the hook, falling through prints, and a `nil` mon
+  answers rather than throwing.
+- `tests/engine/gate_hooks.lua` — the structural parity gate picks the hook
+  up automatically, because it walks the live catalog rather than a list.
+- `tests/engine/gate_meta_coverage.lua` — the coverage ratchet; the seam is
+  covered by name from the change that introduces it, so it never enters the
+  DEBT ledger.
+
+## Backward compatibility
+
+A build with no mod wrapping the hook never reaches `Runtime.call`:
+`wantsHook` is checked first, which matters because two of the four sites
+are on a per-frame draw path. Pixels are unchanged, and the parity gates
+assert it.
+
+## Scope, and what is deliberately not in this change
+
+**Gen 1 only.** The Gen 2 screens keep their own level readouts
+(`src/ui/gen2/PartyMenu.lua`, `SummaryMenu.lua`, `BoxMenu.lua`,
+`HallOfFame.lua`) and do not consult the hook. So does the Gen 1 PC box list
+(`src/ui/BoxMenu.lua`), where the level is baked into a row label string
+rather than drawn as a field, and the box-to-PNG print path beside it.
+
+Those are mechanical follow-ups, held back so this change stays reviewable
+against screens that can actually be exercised here. The limitation is
+stated in `docs/modding.md` beside the hook, so a mod author reads it before
+depending on it rather than after.
+
+## Compatibility seam for older engines
+
+There is none, and none is possible without patching: the call sites are
+mid-draw, so a mod on a stock engine cannot reach them. That is the argument
+for the seam rather than a gap around it — the alternatives available to a
+mod today are painting over the engine's own pixels or reaching into its
+render modules, and the second is the thing the mod contract exists to
+prevent.