landlord-ts 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,504 @@
+/** Mana cost and color helpers — port of lib/src/card/mana_cost.rs */
+type ManaCost = {
+    bits: number;
+    r: number;
+    w: number;
+    b: number;
+    u: number;
+    g: number;
+    c: number;
+};
+declare function manaCostFromRgbuwc(r: number, g: number, b: number, u: number, w: number, c: number): ManaCost;
+declare function manaCostCmc(cost: ManaCost): number;
+/** Expand a mana cost string like "{2}{R/G}" into all concrete ManaCost combinations. */
+declare function manaCostsFromStr(manaCostStr: string): ManaCost[];
+
+/** Internal card type — port of CardKind in lib/src/card/card.rs */
+declare enum CardKind {
+    BasicLand = "BasicLand",
+    TapLand = "TapLand",
+    CheckLand = "CheckLand",
+    ShockLand = "ShockLand",
+    FastLand = "FastLand",
+    SlowLand = "SlowLand",
+    BattleLand = "BattleLand",
+    TurnLand = "TurnLand",
+    SurveilLand = "SurveilLand",
+    BounceLand = "BounceLand",
+    TriomeLand = "TriomeLand",
+    CyclingLand = "CyclingLand",
+    PainLand = "PainLand",
+    FetchLand = "FetchLand",
+    CanopyLand = "CanopyLand",
+    PathwayLand = "PathwayLand",
+    OtherLand = "OtherLand",
+    ForcedLand = "ForcedLand",
+    Creature = "Creature",
+    Spell = "Spell",
+    Enchantment = "Enchantment",
+    Instant = "Instant",
+    Planeswalker = "Planeswalker",
+    Sorcery = "Sorcery",
+    Artifact = "Artifact",
+    Unknown = "Unknown"
+}
+declare enum Rarity {
+    Common = "common",
+    Uncommon = "uncommon",
+    Rare = "rare",
+    Mythic = "mythic",
+    Special = "special",
+    Bonus = "bonus",
+    Other = "other"
+}
+declare enum GameFormat {
+    Standard = "standard",
+    Other = "other"
+}
+/** Set code stored as a string (Rust uses a large enum). */
+type SetCode = string;
+type Card = {
+    name: string;
+    oracleId: string;
+    manaCostString: string;
+    imageUri: string;
+    kind: CardKind;
+    /** Stable hash of the card name (FNV-1a 64-bit). */
+    hash: number;
+    turn: number;
+    manaCost: ManaCost;
+    allManaCosts: ManaCost[];
+    arenaId: number;
+    rarity: Rarity;
+    set: SetCode;
+    isFace: boolean;
+    /** Bitmask of basic land types on this card (see BasicLandType). */
+    basicLandTypes: number;
+    /** Bitmask of basic types that unlock this check land; 0 if not a check. */
+    checkTypes: number;
+    /** Mana units produced per tap (default 1); >1 for fixed-quantity lands like Ancient Tomb. */
+    manaPerTap: number;
+};
+declare function isLandKind(kind: CardKind): boolean;
+declare function isLand(card: Card): boolean;
+/** FNV-1a 64-bit — stable across runs (unlike Rust DefaultHasher). */
+declare function hashCardName(name: string): number;
+
+/** Bitmask for basic land types (Plains / Island / Swamp / Mountain / Forest). */
+declare const BasicLandType: {
+    readonly Plains: number;
+    readonly Island: number;
+    readonly Swamp: number;
+    readonly Mountain: number;
+    readonly Forest: number;
+};
+/** Parse Plains/Island/Swamp/Mountain/Forest subtypes from a type line. */
+declare function basicLandTypesFromTypeLine(typeLine: string): number;
+/**
+ * Parse check-land requirements from oracle text after "unless you control".
+ * e.g. "enters tapped unless you control a Plains or an Island."
+ */
+declare function checkTypesFromOracleText(oracleText: string): number;
+
+type ManaColorCount = {
+    total: number;
+    c: number;
+    w: number;
+    u: number;
+    b: number;
+    r: number;
+    g: number;
+    wu: number;
+    wb: number;
+    ub: number;
+    ur: number;
+    br: number;
+    bg: number;
+    rg: number;
+    rw: number;
+    gw: number;
+    gu: number;
+};
+
+type DeckCard = {
+    card: Card;
+    count: number;
+};
+type Deck = {
+    title: string | null;
+    url: string | null;
+    cards: DeckCard[];
+    format: GameFormat;
+    cardCount: number;
+};
+declare class DeckcodeError extends Error {
+    /**
+     * All unresolved card names from this parse (set/collector stripped).
+     * Prefer this for UI lists when multiple cards are missing.
+     */
+    readonly unknownCardNames: string[];
+    /** First unknown card name; same as `unknownCardNames[0]` when present. */
+    readonly unknownCardName?: string;
+    constructor(message: string, options?: {
+        unknownCardName?: string;
+        unknownCardNames?: string[];
+    });
+}
+declare function deckFromCards(cards: Iterable<Card>): Deck;
+declare function deckFlatten(deck: Deck): Card[];
+declare function deckFromList(list: string): Deck;
+declare function decklist(list: string): Deck;
+/**
+ * Non-throwing parse for UI validation (e.g. textarea before `run()`).
+ * On failure, `error.message` is human-readable; unknown cards set
+ * `error.unknownCardNames` (and `error.unknownCardName` for the first).
+ */
+type ParseDecklistResult = {
+    ok: true;
+    deck: Deck;
+} | {
+    ok: false;
+    error: DeckcodeError;
+};
+declare function parseDecklist(list: string): ParseDecklistResult;
+
+type Rng = {
+    /** Uniform integer in `[min, max)`. */
+    genRange(min: number, max: number): number;
+};
+type Mulligan = {
+    simulateHand(rng: Rng, deck: readonly Card[], draws: number): Hand;
+};
+/** Mulberry32 PRNG for reproducible simulations. */
+declare function createMulberry32(seed: number): Rng;
+
+type SimCard = {
+    hash: number;
+    kind: CardKind;
+    manaCost: ManaCost;
+    basicLandTypes: number;
+    checkTypes: number;
+    manaPerTap: number;
+};
+declare enum PlayOrder {
+    First = "First",
+    Second = "Second"
+}
+type AutoTapResult = {
+    paid: boolean;
+    cmc: boolean;
+    inOpeningHand: boolean;
+    inDrawHand: boolean;
+};
+type Hand = {
+    cards: SimCard[];
+    startingHandSize: number;
+    openingHandSize: number;
+    mulliganCount: number;
+};
+declare function handFromOpeningAndDraws(opening: readonly Card[], draws: readonly Card[], startingHandSize?: number): Hand;
+declare function autoTapByTurn(hand: Hand, goal: Card, turn: number, playOrder: PlayOrder): AutoTapResult;
+declare function playCmcAutoTap(hand: Hand, goal: Card): AutoTapResult;
+declare function drawCmcAutoTap(hand: Hand, goal: Card): AutoTapResult;
+/**
+ * Available turn for a land given board state when it is played.
+ * Always-available kinds ignore play-turn gating for Karsten parity (sources in hand).
+ * `basicsOnBoard` counts Basic-supertype lands already played (for BattleLand).
+ */
+declare function availableTurnForLand(card: SimCard, playTurn: number, otherLands: number, boardTypes: number, basicsOnBoard?: number): number;
+
+type SimulationConfig = {
+    runCount: number;
+    drawCount: number;
+    deck: Deck;
+    mulligan: Mulligan;
+    onThePlay: boolean;
+    /** Optional seed for reproducible runs (tests). */
+    seed?: number;
+    /**
+     * When set, `runs` is a maximum; stop early when the Wilson half-width of the
+     * aggregate pManaGivenCmc across observed CMC opportunities is below this.
+     */
+    epsilon?: number;
+    /** Shard Monte Carlo trials across worker threads (Node). Default: true when runCount >= 2000. */
+    parallel?: boolean;
+    /** London/Never starting hand size used when reconstructing workers. */
+    startingHandSize?: number;
+    mulliganDownTo?: number;
+    mulliganOnLands?: number[];
+    acceptableHandList?: number[][];
+};
+type Simulation = {
+    hands: Hand[];
+    accumulatedOpeningHandSize: number;
+    accumulatedOpeningHandLandCount: number;
+    onThePlay: boolean;
+};
+type Observations = {
+    mana: number;
+    cmc: number;
+    play: number;
+    inOpeningHand: number;
+    totalRuns: number;
+};
+declare function pMana(obs: Observations): number;
+declare function pManaGivenCmc(obs: Observations): number;
+declare function pPlay(obs: Observations): number;
+/** Wilson score half-width for a binomial proportion (approx. 95% z=1.96). */
+declare function wilsonHalfWidth(successes: number, trials: number, z?: number): number;
+declare function simulationFromConfig(config: SimulationConfig): Simulation;
+type SimulationProgress = {
+    completed: number;
+    total: number;
+};
+type SimulationAsyncOptions = {
+    /**
+     * Trials per progress tick when `epsilon` is unset (default 500).
+     * Ignored when `epsilon` is set — batches use the same size as sync adaptive (1000).
+     */
+    batchSize?: number;
+    onProgress?: (progress: SimulationProgress) => void;
+    /** Required for Wilson early-stop when `config.epsilon` is set. */
+    cards?: readonly Card[];
+    /** When aborted, stops between batches (throws `AbortError`). */
+    signal?: AbortSignal;
+};
+/**
+ * Sequential batched hand generation with optional progress callbacks and event-loop yields.
+ * Always single-threaded (`parallel` ignored) so hosts can flush SSE between batches.
+ * Without `epsilon`, uses one continuous RNG stream (seeded runs match `simulationFromConfig` with parallel off).
+ * With `epsilon`, batch size matches sync adaptive (`EARLY_STOP_BATCH`) so seeded results match `run()`.
+ */
+declare function simulationFromConfigAsync(config: SimulationConfig, options?: SimulationAsyncOptions): Promise<Simulation>;
+declare function observationsForCard(sim: Simulation, card: Card): Observations;
+
+/**
+ * On-curve observations report builders — used to populate flattened RunOutput.
+ */
+
+/** Fraction of CMC opportunities that must fail color/timing to flag `colorConstrained`. */
+declare const COLOR_CONSTRAINED_THRESHOLD = 0.15;
+/** Fraction of mana hits that must be undrawn to flag `drawDependent`. */
+declare const DRAW_DEPENDENT_THRESHOLD = 0.15;
+type CardObservationsReport = {
+    name: string;
+    manaCost: string;
+    imageUri: string;
+    kind: CardKind;
+    turn: number;
+    copies: number;
+    cmc: number;
+    playedOnCurve: number;
+    notPlayedOnCurve: number;
+    totalSimulations: number;
+    pCastOnCurve: number;
+    pManaGivenCmc: number;
+    pInOpeningHand: number;
+    notEnoughLands: number;
+    colorOrTimingFail: number;
+    manaOkUndrawn: number;
+};
+type WeakestOnCurveEntry = {
+    name: string;
+    pCastOnCurve: number;
+    turn: number;
+};
+type ColorConstrainedEntry = {
+    name: string;
+    colorOrTimingFail: number;
+    cmcOpportunities: number;
+};
+type DrawDependentEntry = {
+    name: string;
+    manaOkUndrawn: number;
+    manaHits: number;
+};
+
+/**
+ * Public run() / runAsync() façade — Arena decklist → Monte Carlo on-curve report.
+ * Public field names use camelCase.
+ */
+
+/** Thrown for invalid `RunInput` (bad deckcode, empty deck, bad acceptable hands). */
+declare class RunValidationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+type RunInput = {
+    code: string;
+    runs: number;
+    onThePlay: boolean;
+    mulliganDownTo: number;
+    mulliganOnLands: number[];
+    acceptableHandList: string[][];
+    /** Optional RNG seed for reproducible runs. */
+    seed?: number;
+    /** Optional starting hand size (default 7). */
+    startingHandSize?: number;
+    /**
+     * Optional early-stop half-width on aggregate pManaGivenCmc.
+     * When set, `runs` is treated as a maximum.
+     */
+    epsilon?: number;
+    /** Shard trials across worker threads (default: auto when runs >= 2000). */
+    parallel?: boolean;
+};
+type RunProgressPhase = 'simulating' | 'scoring';
+type RunProgress = {
+    completed: number;
+    total: number;
+    /** `simulating` during hand batches; `scoring` once before report build. */
+    phase: RunProgressPhase;
+};
+type RunAsyncInput = RunInput & {
+    onProgress?: (progress: RunProgress) => void;
+    /**
+     * Trials per progress tick when `epsilon` is unset (default 500).
+     * Ignored when `epsilon` is set (uses the same 1000-trial batches as sync adaptive).
+     */
+    batchSize?: number;
+    /** When aborted, stops between batches (throws `AbortError`). */
+    signal?: AbortSignal;
+};
+type LandCount = {
+    name: string;
+    manaCost: string;
+    imageUri: string;
+    kind: CardKind;
+    copies: number;
+    hash: number;
+};
+type RunOutput = {
+    totalSimulations: number;
+    avgOpeningHandSize: number;
+    avgOpeningLandCount: number;
+    deckSize: number;
+    deckAverageCmc: number;
+    cards: CardObservationsReport[];
+    weakestOnCurve: WeakestOnCurveEntry[];
+    colorConstrained: ColorConstrainedEntry[];
+    drawDependent: DrawDependentEntry[];
+    landCounts: LandCount[];
+    totalLandCounts: ManaColorCount;
+    basicLandCounts: ManaColorCount;
+    tapLandCounts: ManaColorCount;
+    checkLandCounts: ManaColorCount;
+    shockLandCounts: ManaColorCount;
+    fastLandCounts: ManaColorCount;
+    slowLandCounts: ManaColorCount;
+    battleLandCounts: ManaColorCount;
+    turnLandCounts: ManaColorCount;
+    surveilLandCounts: ManaColorCount;
+    bounceLandCounts: ManaColorCount;
+    triomeLandCounts: ManaColorCount;
+    cyclingLandCounts: ManaColorCount;
+    painLandCounts: ManaColorCount;
+    fetchLandCounts: ManaColorCount;
+    canopyLandCounts: ManaColorCount;
+    pathwayLandCounts: ManaColorCount;
+    otherLandCounts: ManaColorCount;
+    nonLandCounts: ManaColorCount;
+};
+/** SSE `data:` payload shapes for wiki Pattern A hosts (types only). */
+type SimulateProgressEvent = {
+    type: 'progress';
+} & RunProgress;
+type SimulateDoneEvent = {
+    type: 'done';
+    result: RunOutput;
+};
+type SimulateErrorEvent = {
+    type: 'error';
+    message: string;
+};
+type SimulateStreamEvent = SimulateProgressEvent | SimulateDoneEvent | SimulateErrorEvent;
+/**
+ * Run a Monte Carlo simulation for an Arena decklist.
+ * Returns a single flattened on-curve report (`cards`, insights, land tallies).
+ */
+declare function run(input: RunInput): RunOutput;
+/**
+ * Async Monte Carlo run with optional progress callbacks for streaming hosts (e.g. SSE).
+ * Always sequential batches (`parallel` ignored) so the event loop can flush between ticks.
+ * Emits `phase: 'simulating'` after each hand batch, then `phase: 'scoring'` before report build.
+ */
+declare function runAsync(input: RunAsyncInput): Promise<RunOutput>;
+
+type Collection = {
+    cards: Card[];
+};
+/** Convenience object API matching Rust Collection methods. */
+type CollectionApi = Collection & {
+    cardFromName(name: string): Card | undefined;
+    otherFacesByName(name: string): Card[];
+    readonly length: number;
+};
+
+declare function loadCardsFromGzipBytes(bytes: Uint8Array): CollectionApi;
+/** Lazily loaded card collection (Node). */
+declare function getAllCards(): CollectionApi;
+/** Replace the in-memory collection (tests / custom DBs). Pass null to clear. */
+declare function setAllCards(collection: CollectionApi | null): void;
+/**
+ * Proxy so `ALL_CARDS.cardFromName(...)` works like Rust lazy_static.
+ * Loads the gzipped DB on first property access.
+ */
+declare const ALL_CARDS: CollectionApi;
+
+/**
+ * Scryfall → landlord Card conversion.
+ * Port of landlord lib/src/scryfall.rs (feat/enters-tapped-lands)
+ * and flatten/filter from bins/scryfall2landlord (feat/jsonl-bulk-data-support).
+ */
+
+type ScryfallLegality = 'legal' | 'not_legal' | 'banned' | 'restricted' | string;
+type ScryfallCard = {
+    name?: string;
+    id?: string;
+    oracle_id?: string;
+    mana_cost?: string;
+    oracle_text?: string;
+    collector_number?: string;
+    type_line?: string;
+    color_identity?: string[];
+    legalities?: Record<string, ScryfallLegality>;
+    image_uris?: Record<string, string>;
+    cmc?: number;
+    arena_id?: number;
+    card_faces?: ScryfallCard[];
+    set?: string;
+    set_type?: string;
+    rarity?: string;
+    object?: string;
+    released_at?: string;
+    lang?: string | null;
+    promo?: boolean;
+};
+/** Override land color sources when Scryfall color_identity is wrong. */
+declare const SPECIAL_LANDS: ReadonlyMap<string, ManaCost>;
+/**
+ * Classify land ETB / nickname cycle from oracle text.
+ * Order matters: conditional ETB matchers before bare TapLand; specialty untapped before Other.
+ */
+declare function landKindFromOracleText(oracleText: string, typeLine: string, name?: string): CardKind;
+/** Extract the ETB clause after "enters tapped" for mining / diagnostics. */
+declare function etbClauseFromOracle(oracleText: string): string | null;
+declare function scryfallCardToCard(raw: ScryfallCard): Card;
+declare function scryfallCardsToCards(cards: readonly ScryfallCard[]): Card[];
+
+type London = {
+    startingHandSize: number;
+    mulliganDownTo: number;
+    mulliganOnLands: Set<number>;
+    acceptableHandList: Set<number>[];
+};
+declare function londonNever(): London;
+declare function asLondonMulligan(london: London): Mulligan;
+
+type Never = {
+    startingHandSize: number;
+};
+declare function asNeverMulligan(n?: Never): Mulligan;
+
+export { ALL_CARDS, BasicLandType, COLOR_CONSTRAINED_THRESHOLD, type Card, CardKind, type CardObservationsReport, type ColorConstrainedEntry, DRAW_DEPENDENT_THRESHOLD, type Deck, type DeckCard, DeckcodeError, type DrawDependentEntry, type LandCount, type ManaColorCount, type ManaCost, type Observations, type ParseDecklistResult, PlayOrder, Rarity, type RunAsyncInput, type RunInput, type RunOutput, type RunProgress, type RunProgressPhase, RunValidationError, SPECIAL_LANDS, type ScryfallCard, type SimulateDoneEvent, type SimulateErrorEvent, type SimulateProgressEvent, type SimulateStreamEvent, type Simulation, type SimulationAsyncOptions, type SimulationProgress, type WeakestOnCurveEntry, asLondonMulligan, asNeverMulligan, autoTapByTurn, availableTurnForLand, basicLandTypesFromTypeLine, checkTypesFromOracleText, createMulberry32, deckFlatten, deckFromCards, deckFromList, decklist, drawCmcAutoTap, etbClauseFromOracle, getAllCards, handFromOpeningAndDraws, hashCardName, isLand, isLandKind, landKindFromOracleText, loadCardsFromGzipBytes, londonNever, manaCostCmc, manaCostFromRgbuwc, manaCostsFromStr, observationsForCard, pMana, pManaGivenCmc, pPlay, parseDecklist, playCmcAutoTap, run, runAsync, scryfallCardToCard, scryfallCardsToCards, setAllCards, simulationFromConfig, simulationFromConfigAsync, wilsonHalfWidth };