landlord-ts 1.0.4 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # landlord-ts
 
-Pure TypeScript Monte Carlo simulator for Magic: The Gathering on-curve probabilities. Port of the Rust [landlord](https://github.com/mtgoncurve/landlord) engine used by [mtgoncurve.com](https://mtgoncurve.com).
+Pure TypeScript Monte Carlo simulator for Magic: The Gathering on-curve probabilities, plus exact hypergeometric draw odds. Started as a port of the Rust [landlord](https://github.com/mtgoncurve/landlord) engine used by [mtgoncurve.com](https://mtgoncurve.com); since 2.0.0 it sequences land drops optimally and models how each land enters and what mana it makes (see [Land sequencing](#land-sequencing)).
 
 ## Requirements
 
@@ -29,6 +29,7 @@ const input = {
   mulliganDownTo: 5,
   mulliganOnLands: [0, 1, 6, 7],
   acceptableHandList: [],
+  landSequencing: 'optimal' as const, // default; 'draw-order' reruns the v1.x land model
 };
 
 const output = run(input);
@@ -53,7 +54,9 @@ for (const row of output.cards) {
     pCastOnCurve: row.pCastOnCurve,
     pManaGivenCmc: row.pManaGivenCmc,
     notEnoughLands: row.notEnoughLands,
-    colorOrTimingFail: row.colorOrTimingFail,
+    colorOrTimingFail: row.colorOrTimingFail, // = colorFail + timingFail
+    colorFail: row.colorFail, // enough lands, wrong colors
+    timingFail: row.timingFail, // the land was in hand on time but entered tapped
     manaOkUndrawn: row.manaOkUndrawn,
   });
 }
@@ -64,6 +67,8 @@ for (const land of output.landCounts) {
     kind: land.kind,
     copies: land.copies,
     producedMana: land.producedMana,
+    manaPerTap: land.manaPerTap, // most mana one tap makes (2 for bounce lands)
+    landFace: land.landFace, // set when a spell//land MDFC is played as its land face
   });
 }
 ```
@@ -77,6 +82,44 @@ For the full `RunInput` / `RunOutput` contract, `runAsync` (progress callbacks),
 - [landlord-ts API](https://github.com/lggarrison/landlord-ts/blob/develop/wiki/concepts/landlord-ts-api.md)
 - [Streaming progress](https://github.com/lggarrison/landlord-ts/blob/develop/wiki/concepts/streaming-progress.md)
 
+## Exact draw odds
+
+For quick, simulation-free answers ("how likely am I to have three lands by turn 3?"), the hypergeometric helpers compute exact probabilities from a parsed deck. They count draws only, from a random opening seven with no mulligans; whether a spell is castable still needs `run()`.
+
+```ts
+import { decklist, drawOdds, keepability } from 'landlord-ts';
+
+const deck = decklist(code);
+
+// Every land by default; pass `groups` to track other cards
+const { groups } = drawOdds({ deck, onThePlay: true, maxTurn: 4 });
+for (const t of groups[0].byTurn) {
+  console.log(t.turn, t.seen, t.atLeast1, t.expected);
+}
+
+// Opening-hand land counts: keep = 2–5 lands, screw = 0–1, flood = 6–7
+console.log(keepability(deck));
+```
+
+`landDistributionOpeningHand`, `cardsSeenByTurn` and the `hyperPMF` / `hyperAtLeast` / `hyperAtMost` / `hyperMean` core are exported too. See [Hypergeometric draw odds](https://github.com/lggarrison/landlord-ts/blob/develop/wiki/entities/hypergeometric.md).
+
+## Land sequencing
+
+By default (`landSequencing: 'optimal'`), each spell is checked against the best legal land drops by its target turn: one land per turn, each land only once drawn. Enters-tapped rules are applied to that sequence, and lands whose mana depends on other permanents (Verges, filter lands, bounce lands, fetches) are modeled. Pass `landSequencing: 'draw-order'` to rerun the landlord-ts v1.x land model, which played lands in the order they were drawn. Its mana-miss totals match v1.x (except where card data changed), but its buckets split like `optimal`'s: a land in hand on time that entered tapped is a timing miss, not "not enough lands". Before/after numbers are in the [land sequencing benchmark](https://github.com/lggarrison/landlord-ts/blob/develop/wiki/concepts/land-sequencing-benchmark.md).
+
+**Divergence from Rust landlord.** The Rust engine counts every land in hand by the target turn as available, with no enters-tapped gating. landlord-ts gates every land by its enters-tapped rule and sequences land drops optimally, so its numbers differ for decks with tapped or conditional lands. `draw-order` is the v1.x TypeScript behavior, not the Rust behavior. For decks of basics and untapped lands the two agree, and the Karsten tables match.
+
+## Upgrading from 1.x
+
+2.0.0 changes no function signatures, and every new input is optional. It is a major release because the numbers change:
+
+- **Rates move.** `pCastOnCurve`, `pManaGivenCmc` and the failure buckets change for decks with tapped or conditional lands (fast, slow, check, battle, reveal, Verge, filter, bounce, pathway, fetch) and for lands the card data had wrong. Decks of basics and always-untapped lands are unchanged.
+- **Buckets moved.** A land that was in hand on time but entered tapped is now a color / timing miss (`timingFail`), not `notEnoughLands`.
+- **Land kinds changed.** Six new `CardKind` values (`ReverseSlowLand`, `RevealLand`, `BasicCheckLand`, `CountedTypeLand`, `TappedFetchLand`, `PlayOrderLand`); 119 lands change kind and 299 change colors in the shipped data. Spell//land MDFCs report their land face's kind instead of `ForcedLand`; use `landFace` to spot them. If you switch on `kind`, handle the new values.
+- **Card data refreshed** from the 2026-10-16 Scryfall bulk (35 new cards).
+
+To compare against 1.x, pass `landSequencing: 'draw-order'`. The full list is in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Development
 
 ```bash