@yipe/dice 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,239 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.5.0]
-
-Pushes damage-attribution / provenance and D&D-probability logic that the
-consuming app (dprcalc) had hand-rolled over PMF internals down into the
-library, so the provenance model and dice math stay owned here, and adds a
-**composable scale node** so a scaled/rounded sub-roll can nest inside a larger
-damage payload (per-damage-type resistance / immunity / vulnerability). All
-additive except the Elemental-Adept bounce fix noted below.
-
-### Added
-
-- **`RollBuilder.scaleResult(numerator, denominator = 1, rounding = 'floor')`** —
-  wraps a builder in a composable `scale` AST node that scales its resolved PMF
-  by `numerator / denominator` with the given rounding. Unlike the old
-  `.half()` wrapper, a scaled builder composes: it survives `sumRolls(...)`
-  instead of being dropped on a flat-config merge, so a per-type resisted or
-  doubled sub-roll keeps its own scaling inside a larger hit/crit payload. The
-  rendered expression reflects it — `denominator === 1 → "N * (child)"`,
-  `numerator === 1 → "(child) // D"`, general → `"(child) * N // D"`. `.half()`
-  is now `scaleResult(1, 2, 'floor')`.
-- **`sumRolls(parts: RollBuilder[])`** — additive factory whose `toAST()` is an
-  `add` node over each part's AST, letting scaled and plain children sit side by
-  side without the flat `.plus()` merge collapsing them. `toExpression()` joins
-  the parts with ` + ` and `toPMF()` convolves them.
-- **`PMF.applyHitFrequency(frequency)`** — provenance-preserving mass
-  redistribution for effects that only occur with some probability (conditional
-  attacks, on-hit riders, sub-one AoE fractions): scales every hit bin (damage
-  > 0) by `frequency` and moves the freed mass into a `missNone` bin. Unlike a
-  bare `scaleMass`/`mapDamage`, it scales per-label `count` **and** `attr`, so a
-  frequency-scaled PMF still renders correctly in the damage-attribution charts.
-  Replaces the app's hand-rolled `applyFrequencyToPMF`, which dropped `attr`.
-- **`PMF.missNone(epsilon?)`** / **`MISS_NONE_OUTCOME`** — canonical "clean miss"
-  delta (point mass at 0 tagged with the `missNone` `OutcomeType`, distinct from
-  `PMF.zero`'s builder-side `miss` label), and the label as a single source of
-  truth.
-- **`PMF.hitProbability()` / `PMF.missProbability()`** — the `1 - P(0)` idiom
-  (miss encoded at damage 0), centralized.
-- **`PMF.rebin(maxBuckets)`** — coarsen a wide distribution into ≤ N contiguous
-  equal-width buckets, aggregating `count`/`attr` provenance. For charting wide
-  distributions, not DPR math.
-- **`PMF.attributionByValue()` / `DiceQuery.attributionByValue()`** — split each
-  damage value's probability mass across outcome labels (by `attr` for
-  damage-bearing bins, by `count` for the clean-miss bin), returning per-label
-  `value → mass` series. The provenance core of the stacked attribution chart.
-- **`DiceQuery.countSinglesWith(label)`** — how many independent single PMFs can
-  produce a given outcome label.
-- **`ALL_OUTCOME_TYPES`**, **`OUTCOME_DISPLAY_ORDER`**, **`sortOutcomes()`** —
-  canonical `OutcomeType` enumeration + stack / display orderings, replacing
-  per-consumer outcome tables.
-- **`critProbability(critRange, rollType)`** and **`RollType`** (now exported
-  from the package root as well as `@yipe/dice/builder`) — advantage-aware
-  P(crit) for a given crit window.
-- **`calculateBounceOdds(diceCount, dieFaces, options?)`** and
-  **`BounceOddsOptions`** — the "birthday problem" for bouncing damage dice
-  (Chromatic Orb), honoring Elemental Adept and Empowered Spell. Moved out of the
-  app; the base and Elemental-Adept cases are now computed **exactly** (verified
-  against brute-force enumeration in `tests/bounce.test.ts`).
-
-### Fixed
-
-- **`calculateBounceOdds` Elemental Adept was approximate.** The former
-  hand-derived adjustment factor drifted from the exact value by up to ~3.5%
-  (e.g. 3×d8, min-roll 3: 0.4965 → 0.5313). The Elemental-Adept branch now uses
-  an exact elementary-symmetric-polynomial computation. Consumers relying on the
-  old numbers for bouncing spells with Elemental Adept will see small DPR shifts.
-- **`calculateBounceOdds` Empowered Spell returned certainty when rerolling all
-  dice.** When `rerollDamageDice >= diceCount` (no dice kept), the model claimed
-  a guaranteed match (1.0) instead of treating the reroll as a second
-  independent roll. It now correctly yields `1 - (1 - pMatch)^2` in that case
-  (e.g. 3×d8 reroll-all: 1.0 → 0.5693).
-
-## [0.3.0]
-
-### Fixed (mathematical correctness)
-
-Every fix is verified against an independent brute-force enumeration (see
-`tests/math-correctness.test.ts`).
-
-- **`DiceQuery.probabilityOf(label)` over-counted.** It summed the full `bin.p`
-  of every combined bin that merely *contained* a label, but bins hold multiple
-  mutually-exclusive outcomes — so `probabilityOf('crit')` returned 0.49 where
-  the true P(crit)=0.05. It now returns the correct Poisson-binomial marginal
-  (= `probAtLeastOne`). `missChance()` is fixed by the same change.
-- **`DiceQuery.probExactlyK([labels], k)` array-path** delegated to the buggy
-  `probabilityOf`, disagreeing with the (correct) single-label string path; both
-  now match the true binomial.
-- **`DiceQuery.variance()/stddev()`** used the unstable `E[X²]−E[X]²` form and
-  lost all precision under a large constant damage offset (`1d6 + 1e8` gave
-  variance 2 instead of 35/12). Now uses the centered, additive-per-single form.
-- **`DiceQuery.mean()/variance()`** now stay consistent with an explicitly
-  supplied `combined` that diverges from `convolve(singles)`.
-- **`PMF.convolve()` produced `NaN`** for a zero-mass operand (divide-by-zero in
-  the mass rescale), silently poisoning `DiceQuery.combined`. A zero-mass
-  convolution now correctly yields mass 0.
-- **`probAtLeastOne` is now mass-invariant** (per-attack probability divided by
-  the single's mass) and clamped to `[0,1]` (was returning `1.0000000002`).
-- **`PMF.firstSuccessWeights`** throws on `pSpecial > pSuccess` instead of
-  returning out-of-range probabilities.
-- **Parser `hd6`/`hd20` (reroll-one)** used a weighted union giving
-  `P(1)=1/(2s−1)`; now uses `reroll(1)` for the correct `P(1)=1/s²`. The parser
-  `hd` distribution now matches the builder's `reroll(1)` exactly (the
-  previously loosened tests are tightened).
-- **`DiceQuery.snapshot()` outcome probabilities** (`atLeastOneProbability`,
-  `allProbability`) were aggregated as expected counts and could exceed 1 for
-  multi-attack queries. They now use the correct Poisson-binomial marginals
-  (P(≥1) and P(all)) and are always in [0,1]. (`damageRange.avg` remains a
-  size-biased mean for N≥2 — see Known limitations.)
-- **Parser save-for-half mislabeled outcomes** on odd/constant damage (e.g.
-  `(d20 DC 15) * (3) save half`): the brittle "2×half ∈ hit" detection
-  false-negatived, tagging the success mass as `saveFail` and the failure mass
-  as `hit`. Detection is now deterministic (the presence of a save distribution),
-  so `saveHalf`/`saveFail` are always labeled correctly.
-- **`PMF.compact()` corrupted PMFs that shared bin objects.** It deleted
-  sub-epsilon `count`/`attr` entries *in place* and reused that same bin
-  reference in the compacted map. Because bins are shared by reference across
-  PMFs (the `branch()` / `addScaled()` / `scaleMass()` fast paths can carry
-  another PMF's bin objects), this silently mutated the source PMF — and the
-  receiver's own bins. `compact()` now clones each surviving bin before pruning;
-  the compacted result is unchanged.
-
-### Security / hardening
-
-- **Parser resource-exhaustion guards.** Adversarial expressions are rejected
-  with a `DiceParseError` instead of exhausting CPU/memory: a die over 1,000,000
-  faces, a dice count over 10,000, a keep whose `faces^count` enumeration would
-  exceed 1,000,000 outcomes, and a binary operation whose `faces₁ × faces₂` work
-  would exceed 100,000,000 face pairs. The last closes a gap the per-operand
-  caps missed — two individually-legal large dice (e.g. `d100000 + d100000`,
-  ~10¹⁰ operations) previously hung for tens of seconds. All legitimate
-  expressions, including `d100000`, still parse.
-
-### Known limitations (documented; recommend maintainer review)
-
-These are real but require API/architecture decisions, so they are documented
-and pinned by tests rather than changed blindly:
-
-- **Parser crit probability with bonus to-hit dice is wrong.** With bonus dice in
-  the to-hit (e.g. Bless, `d20 + 5 + 1d4`), the string parser collapses crit to
-  `1/(20·∏bonusSides)` (and the DPR is off by a few %), because the natural-20
-  slice can't be separated after the bonus dice are convolved. **The builder API
-  computes it correctly** — use `d20.plus(..).plus(bonusDie).ac(..).onCrit(..)`.
-- **Multi-attack conditional damage `avg` is size-biased.** The `avg` returned by
-  `damageStatsFrom()` (single label), `outcomeDamageRanges()` and
-  `snapshot().damageRange` aggregates the combined PMF's `count` (an *expected
-  count* for N≥2 attacks), so it is the size-biased mean E[dmg·#label]/E[#label]
-  rather than a clean conditional expectation. It is correct for a single attack.
-  (The associated *probabilities* are now correct — see Fixed.)
-- **`PMF.mixN`/`gate`/`branch` build O(2ⁿ) identifier strings**, which can blow up
-  (multi-MB, eventual `RangeError`) for very deep (≈20+) gate chains. Prefer
-  `PMF.exclusive`/`PMF.mix` for large mixtures.
-
-### Breaking
-
-- **`PMF.toJSON()` now returns a plain object** (`{ bins, normalized, identifier }`)
-  instead of a JSON string, following the standard `toJSON` contract. This means
-  `JSON.stringify(pmf)` no longer double-encodes. If you relied on the old string
-  return, call the new `PMF.toJSONString()` instead.
-- **`DiceQuery.firstSuccessSplit()` is typed as `OutcomeType | OutcomeType[]`**
-  (previously `string | string[]`). Only affects callers passing arbitrary strings;
-  valid outcome labels are unchanged.
-
-### Added
-
-- **`DiceParseError`** — `parse()` now throws this typed error (a subclass of
-  `Error`) instead of a plain `Error`. Existing `try/catch` and message checks keep
-  working; you can now narrow with `instanceof DiceParseError` and read
-  `error.expression` / `error.cause`.
-- **`PMF.toJSONString()`** — returns the JSON string form (the previous
-  `toJSON()` behavior).
-- **`DiceQuery.stdev()`** — alias of `stddev()`, matching `PMF.stdev()`.
-- **`PMF.hasAttribution()`** — O(1) check for whether a PMF already carries
-  damage-attribution metadata.
-
-### Performance
-
-- **`DiceQuery.mean()` / `variance()` / `stddev()` use moment additivity**
-  (`E[ΣX]=ΣE[X]`, `Var[ΣX]=ΣVar[X]`) computed directly from the single PMFs.
-- **`DiceQuery.combined` is now built lazily** (on first access) instead of in
-  the constructor. Combined with the above, a query used only for DPR / mean /
-  variance never performs the N-way convolution — multi-attack stats-only
-  queries are ~10000× faster (e.g. ~17 ms → ~0.001 ms for a heavy 4-attack
-  expression). The materialized `combined` distribution is unchanged; mean and
-  variance may differ from the previous convolution-based values by at most a
-  few ULP (well within the library's tolerances).
-- **`DiceQuery.combinedWithAttribution()` reuses `combined`** when every single
-  already carries attribution (as parser-generated PMFs do), avoiding a
-  redundant convolution pass. Result is bit-for-bit identical.
-- **`PMF.convolve()` inner loop accumulates directly into destination bins**
-  instead of allocating a temporary bin per term and merging — ~1.6× faster
-  convolution (the cost of building the combined distribution for charts). The
-  probability channel is bit-identical; per-label `count`/`attr` provenance may
-  re-associate by at most a few ULP (≤1e-14 even at 16 attacks, ~100× below the
-  eps pruning threshold).
-- **Convolution cache-key fingerprint is memoized** on each (immutable) PMF
-  instead of re-summing every bin key on every `convolve()` call — ~36% faster
-  on warm cache hits. Bit-identical (`PMF.fingerprint()` returns the same string).
-- **`Dice.calculateHitDistribution()` no longer clones outcome distributions per
-  face** — it reads the stored maps once instead of `O(faces × outcomes)` clones,
-  ~10% faster cold parsing of wide-support expressions. Bit-identical.
-- **`DiceQuery.toStackedChartData()` drops a dead `O(N×L)` precomputation pass**
-  whose result was discarded — ~2× faster. Bit-identical.
-- Minor bit-identical cleanups on the parse path (`Dice.toPMF` iterates the
-  internal face map directly; `multiplyDiceByDice` uses a `Map`).
-- **`DiceQuery` count queries (`probExactlyK` / `probAtLeastK` / `probAtMostK`,
-  array-label paths)** compute each attack's success probability and the binomial
-  DP once instead of rebuilding a query per requested count (~3× on the looped
-  variants).
-- **`PMF.branch()` assembles its Bernoulli mixture in a single pass** rather than
-  chaining two `addScaled` calls (which copied the failure branch's bins twice).
-- **`keepSumPMF` packs its DP state into a single integer key** instead of a
-  `"used|r"` string parsed on every transition.
-- **`computeMaxOfPMF` walks the support once with a running CDF** for large pools,
-  reducing the max-of computation from O(N²) to O(N).
-- **`Dice.reroll()` uses a `Set` for membership** and **`Dice.binaryOp()` hoists
-  the inner die's face list** out of its loop.
-
-  All of the above were verified bit-for-bit identical (probabilities, counts,
-  means, variance) across the full expression corpus.
-
-### Changed
-
-- Removed the stale `package-lock.json` (the project uses Yarn 4) and dropped the
-  unused `ts-node` / `tsconfig-paths` dev dependencies.
-- Removed `console.error` calls from the parser so the library no longer writes to
-  a consumer's console.
-- Internal refactors with no behavioral change: deduplicated `Bin` clone/scale
-  logic in `PMF`, removed dead code and impossible iterator branches, and tightened
-  internal `any` usage.
-- `Dice.outcomeData` is typed `Partial<Record<OutcomeType, …>>` (dropping an
-  unsound `as Record<…>` cast); `getFullOutcomeDistribution()`'s return type
-  matches. Type-only change; runtime output is unchanged.
-- Added a `yarn format` script (ESLint autofix).

package/dist/builder/index.d.cts

@@ -1,429 +0,0 @@
-import { b as RollType, P as PMF, l as DiceQuery, C as CritConfig, L as LRUCache } from '../pmf-D5VRghZI.cjs';
-
-type RollFactory = {
-    (count: number, sides?: number, modifier?: number): RollBuilder;
-    (count: number, die: RollBuilder, modifier?: number): RollBuilder;
-    d(sides: number | string): RollBuilder;
-    hd20(): RollBuilder;
-    d4(): RollBuilder;
-    d6(): RollBuilder;
-    d8(): RollBuilder;
-    d10(): RollBuilder;
-    d12(): RollBuilder;
-    d20(): RollBuilder;
-    d100(): RollBuilder;
-    flat(n: number): RollBuilder;
-};
-type KeepMode = "highest" | "lowest";
-type RollConfig = {
-    count: number;
-    sides: number;
-    modifier: number;
-    reroll: number;
-    explode: number;
-    minimum: number;
-    bestOf: number;
-    keep: {
-        total: number;
-        count: number;
-        mode: KeepMode;
-    } | undefined;
-    rollType: RollType;
-    isSubtraction?: boolean;
-};
-type Resolution = {
-    pmf: PMF;
-    check: PMF;
-    weights: {
-        [key: string]: number;
-    };
-};
-type AttackResolution = Resolution & {
-    hit: PMF;
-    crit: PMF;
-    miss: PMF;
-    weights: {
-        hit: number;
-        crit: number;
-        miss: number;
-    };
-};
-type SaveResolution = Resolution & {
-    saveFail: PMF;
-    saveSuccess: PMF;
-    weights: {
-        success: number;
-        fail: number;
-    };
-};
-interface CheckBuilder {
-    resolve(eps?: number): Resolution;
-    toExpression(): string;
-    readonly pmf: PMF;
-}
-
-type SaveOutcome = "normal" | "half";
-declare class SaveBuilder implements CheckBuilder {
-    readonly check: DCBuilder;
-    private readonly failureEffect?;
-    private readonly saveOutcome;
-    constructor(check: DCBuilder, failureEffect?: RollBuilder | undefined, saveOutcome?: SaveOutcome);
-    saveHalf(): SaveBuilder;
-    toExpression(): string;
-    resolve(eps?: number): SaveResolution;
-    toPMF(eps?: number): PMF;
-    get pmf(): PMF;
-    toQuery(eps?: number): DiceQuery;
-}
-
-interface SaveConfig {
-    dc: number;
-}
-declare class DCBuilder extends RollBuilder {
-    private readonly saveConfig;
-    constructor(baseRoll: RollBuilder, saveConfig?: SaveConfig);
-    dc(saveDC: number): DCBuilder;
-    get saveDC(): number;
-    add(anotherRoll: RollBuilder): DCBuilder;
-    addRoll(count?: number): DCBuilder;
-    onSaveFailure(val: number): SaveBuilder;
-    onSaveFailure(val: string): SaveBuilder;
-    onSaveFailure(val: RollBuilder): SaveBuilder;
-    onSaveFailure(count: number, die: RollBuilder): SaveBuilder;
-    onSaveFailure(count: number, sides: number): SaveBuilder;
-    onSaveFailure(count: number, die: RollBuilder, modifier: number): SaveBuilder;
-    onSaveFailure(count: number, sides: number, modifier: number): SaveBuilder;
-    withElvenAccuracy(): never;
-    toExpression(): string;
-    toPMF(eps?: number): PMF;
-}
-
-type ExpressionNode = DieNode | ConstantNode | SumNode | AddNode | KeepNode | D20RollNode | HalfNode | MaxOfNode | ScaleNode;
-type DieNode = {
-    type: "die";
-    sides: number;
-    reroll?: number;
-    minimum?: number;
-    explode?: number;
-};
-type ConstantNode = {
-    type: "constant";
-    value: number;
-};
-type SumNode = {
-    type: "sum";
-    count: number;
-    child: ExpressionNode;
-};
-type AddNode = {
-    type: "add";
-    children: {
-        node: ExpressionNode;
-        sign: 1 | -1;
-    }[];
-};
-type KeepNode = {
-    type: "keep";
-    mode: "highest" | "lowest";
-    count: number;
-    child: SumNode | KeepNode;
-};
-type D20RollNode = {
-    type: "d20Roll";
-    rollType: "advantage" | "disadvantage" | "elven accuracy";
-    child: ExpressionNode;
-};
-type HalfNode = {
-    type: "half";
-    child: ExpressionNode;
-};
-type MaxOfNode = {
-    type: "maxOf";
-    count: number;
-    child: ExpressionNode;
-};
-/**
- * Scale the child's result by `numerator / denominator`, then round.
- *
- * Unlike {@link HalfNode} (a fixed `// 2` with floor), this is a general, composable
- * multiplier/divider — the building block for damage-type resistance (`1/2`, floor),
- * vulnerability (`2/1`), and similar per-source transforms. It renders as
- * `N * (child)` when the denominator is 1, `(child) // D` when the numerator is 1,
- * and `(child) * N // D` otherwise.
- */
-type ScaleNode = {
-    type: "scale";
-    numerator: number;
-    denominator: number;
-    rounding: "floor" | "round" | "ceil";
-    child: ExpressionNode;
-};
-
-declare const defaultConfig: RollConfig;
-declare class RollBuilder {
-    protected readonly subRollConfigs: readonly RollConfig[];
-    constructor(countOrConfigs?: number | readonly RollConfig[]);
-    protected create(configs: readonly RollConfig[]): RollBuilder;
-    protected get lastConfig(): RollConfig;
-    hasHiddenState(): boolean;
-    getSubRollConfigs(): readonly RollConfig[];
-    static fromConfig(config: Partial<RollConfig>): RollBuilder;
-    static fromConfigs(configs: Partial<RollConfig>[]): RollBuilder;
-    static fromArgs(...args: any[]): RollBuilder;
-    d(sides: number | undefined): RollBuilder;
-    plus(modOrRoll: number | RollBuilder | undefined): RollBuilder;
-    plus(count: number, die: RollBuilder): RollBuilder;
-    minus(modOrRoll: number | RollBuilder | undefined): RollBuilder;
-    minus(count: number, die: RollBuilder): RollBuilder;
-    /** Apply one-pass reroll threshold (k): reroll faces 1..k once, must keep. */
-    reroll(value: number): RollBuilder;
-    /** Set finite explode count for max-face explosions (Infinity allowed). */
-    explode(count?: number | undefined): RollBuilder;
-    /** Apply per-die minimum value (min > 0). */
-    minimum(val: number | undefined): RollBuilder;
-    bestOf(count: number | undefined): RollBuilder;
-    keepHighest(total: number, count: number): RollBuilder;
-    keepLowest(total: number, count: number): RollBuilder;
-    keepHighestAll(total: number, count: number): PooledRollBuilder;
-    keepLowestAll(total: number, count: number): PooledRollBuilder;
-    withAdvantage(): RollBuilder;
-    withDisadvantage(): RollBuilder;
-    add(anotherRoll: RollBuilder | undefined): RollBuilder;
-    withBonus(anotherRoll: RollBuilder): RollBuilder;
-    addRoll(count?: number): RollBuilder;
-    scaleDice(scale: number): RollBuilder;
-    doubleDice(): RollBuilder;
-    alwaysHits(): AlwaysHitBuilder;
-    alwaysCrits(): AlwaysCritBuilder;
-    copy(): RollBuilder;
-    d4: () => RollBuilder;
-    d6: () => RollBuilder;
-    d8: () => RollBuilder;
-    d10: () => RollBuilder;
-    d12: () => RollBuilder;
-    d20: () => RollBuilder;
-    d100: () => RollBuilder;
-    withElvenAccuracy(): RollBuilder;
-    toExpression(): string;
-    toPMF(eps?: number): PMF;
-    get pmf(): PMF;
-    toQuery(eps?: number): DiceQuery;
-    toAST(): ExpressionNode;
-    private configToSingleExpressionWithoutModifier;
-    getRootDieConfig(): RollConfig | undefined;
-    getAllDieConfigs(): readonly RollConfig[];
-    getBonusDiceConfigs(): RollConfig[];
-    getBonusDicePMFs(check: RollBuilder, eps?: number): PMF[];
-    get modifier(): number;
-    get rollType(): RollType;
-    get baseReroll(): number;
-    half(): HalfRollBuilder;
-    /**
-     * Scale this roll's result by `numerator / denominator`, rounding each outcome.
-     * A general, composable form of {@link half} — used to model damage-type resistance
-     * (`scaleResult(1, 2)` → `(expr) // 2`) and vulnerability (`scaleResult(2)` → `2 * (expr)`).
-     * Compose several of these (and plain rolls) into one payload with {@link sumRolls}.
-     */
-    scaleResult(numerator: number, denominator?: number, rounding?: "floor" | "round" | "ceil"): ScaleRollBuilder;
-    maxOf(count: number): MaxOfRollBuilder;
-    ac(_targetAC: number): ACBuilder;
-    dc(_saveDC: number): DCBuilder;
-}
-declare class HalfRollBuilder extends RollBuilder {
-    private readonly innerRoll;
-    constructor(innerRoll: RollBuilder);
-    hasHiddenState(): boolean;
-    get lastConfig(): RollConfig;
-    getSubRollConfigs(): readonly RollConfig[];
-    toExpression(): string;
-    toAST(): ExpressionNode;
-    toPMF(eps?: number): PMF;
-    copy(): HalfRollBuilder;
-}
-/**
- * A roll whose result is scaled by `numerator / denominator` and rounded — the composable
- * generalization of {@link HalfRollBuilder}. Renders as `N * (inner)`, `(inner) // D`, or
- * `(inner) * N // D`. Terminal (like `half`): use {@link sumRolls} to combine with other rolls.
- */
-declare class ScaleRollBuilder extends RollBuilder {
-    private readonly innerRoll;
-    private readonly numerator;
-    private readonly denominator;
-    private readonly rounding;
-    constructor(innerRoll: RollBuilder, numerator: number, denominator?: number, rounding?: "floor" | "round" | "ceil");
-    hasHiddenState(): boolean;
-    get lastConfig(): RollConfig;
-    getSubRollConfigs(): readonly RollConfig[];
-    toExpression(): string;
-    toAST(): ExpressionNode;
-    toPMF(eps?: number): PMF;
-    copy(): ScaleRollBuilder;
-}
-declare class MaxOfRollBuilder extends RollBuilder {
-    private readonly innerRoll;
-    private readonly count;
-    private readonly diceCount?;
-    private readonly diceSides?;
-    constructor(innerRoll: RollBuilder, count: number, diceCount?: number | undefined, diceSides?: number | undefined);
-    hasHiddenState(): boolean;
-    get lastConfig(): RollConfig;
-    getSubRollConfigs(): readonly RollConfig[];
-    toExpression(): string;
-    toAST(): ExpressionNode;
-    toPMF(eps?: number): PMF;
-    copy(): MaxOfRollBuilder;
-}
-declare class AlwaysHitBuilder extends RollBuilder {
-    readonly attackConfig: CritConfig;
-    constructor(baseRoll: RollBuilder, attackConfig?: CritConfig);
-    protected create(configs: readonly RollConfig[]): RollBuilder;
-    onHit(val: number): AttackBuilder;
-    onHit(val: string): AttackBuilder;
-    onHit(val: RollBuilder): AttackBuilder;
-    onHit(count: number, die: RollBuilder): AttackBuilder;
-    onHit(count: number, sides: number): AttackBuilder;
-    onHit(count: number, die: RollBuilder, modifier: number): AttackBuilder;
-    onHit(count: number, sides: number, modifier: number): AttackBuilder;
-    get critThreshold(): number;
-    critOn(critThreshold: number): AlwaysHitBuilder;
-    alwaysCrits(): AlwaysCritBuilder;
-    toExpression(): string;
-    toPMF(): PMF;
-    copy(): AlwaysHitBuilder;
-}
-declare class AlwaysCritBuilder extends RollBuilder {
-    readonly attackConfig: CritConfig & {
-        ac?: number;
-    };
-    readonly fromAlwaysHit: boolean;
-    constructor(baseRoll: RollBuilder, attackConfig?: CritConfig & {
-        ac?: number;
-    }, fromAlwaysHit?: boolean);
-    protected create(configs: readonly RollConfig[]): RollBuilder;
-    onHit(val: number): AttackBuilder;
-    onHit(val: string): AttackBuilder;
-    onHit(val: RollBuilder): AttackBuilder;
-    onHit(count: number, die: RollBuilder): AttackBuilder;
-    onHit(count: number, sides: number): AttackBuilder;
-    onHit(count: number, die: RollBuilder, modifier: number): AttackBuilder;
-    onHit(count: number, sides: number, modifier: number): AttackBuilder;
-    get critThreshold(): number;
-    critOn(critThreshold: number): AlwaysCritBuilder;
-    toExpression(): string;
-    toPMF(): PMF;
-    copy(): AlwaysCritBuilder;
-}
-declare class ParsedRollBuilder extends RollBuilder {
-    private readonly cachedPMF;
-    private readonly originalExpression;
-    constructor(expression: string);
-    hasHiddenState(): boolean;
-    protected create(configs: readonly RollConfig[]): RollBuilder;
-    toPMF(_eps?: number): PMF;
-    toExpression(): string;
-    toAST(): ExpressionNode;
-    copy(): ParsedRollBuilder;
-    doubleDice(): ParsedRollBuilder;
-}
-declare class PooledRollBuilder extends RollBuilder {
-    private readonly baseAST;
-    private readonly baseExpression;
-    constructor(baseAST: ExpressionNode, baseExpression: string, configs?: readonly RollConfig[]);
-    protected create(configs: readonly RollConfig[]): PooledRollBuilder;
-    hasHiddenState(): boolean;
-    d(_sides: number | undefined): RollBuilder;
-    reroll(_value: number): RollBuilder;
-    explode(_count?: number | undefined): RollBuilder;
-    minimum(_val: number | undefined): RollBuilder;
-    bestOf(_count: number | undefined): RollBuilder;
-    keepHighest(_total: number, _count: number): RollBuilder;
-    keepLowest(_total: number, _count: number): RollBuilder;
-    withAdvantage(): RollBuilder;
-    withDisadvantage(): RollBuilder;
-    withElvenAccuracy(): RollBuilder;
-    toAST(): ExpressionNode;
-    toExpression(): string;
-    copy(): PooledRollBuilder;
-    scaleDice(scale: number): RollBuilder;
-    times(count: number): PooledRollBuilder;
-}
-/**
- * Combine several rolls into one additive payload whose PMF is their convolution and whose
- * expression is them joined with ` + `. Unlike `a.plus(b)`, this preserves parts that carry
- * hidden state (e.g. `roll.scaleResult(1, 2)` / `roll.half()`), so per-damage-type resistance
- * and vulnerability survive into both the distribution and the rendered expression.
- * Empty parts collapse to `0`; a single part is returned unwrapped.
- */
-declare function sumRolls(parts: readonly RollBuilder[]): RollBuilder;
-
-type ActionEffect = RollBuilder;
-declare class AttackBuilder implements CheckBuilder {
-    readonly check: ACBuilder | AlwaysHitBuilder | AlwaysCritBuilder;
-    private readonly hitEffect?;
-    private readonly critEffect?;
-    private readonly missEffect?;
-    constructor(check: ACBuilder | AlwaysHitBuilder | AlwaysCritBuilder, hitEffect?: ActionEffect | undefined, critEffect?: (ActionEffect | null) | undefined, missEffect?: ActionEffect | undefined);
-    onCrit(val: number): AttackBuilder;
-    onCrit(val: string): AttackBuilder;
-    onCrit(val: RollBuilder): AttackBuilder;
-    onCrit(count: number, die: RollBuilder): AttackBuilder;
-    onCrit(count: number, sides: number): AttackBuilder;
-    onCrit(count: number, die: RollBuilder, modifier: number): AttackBuilder;
-    onCrit(count: number, sides: number, modifier: number): AttackBuilder;
-    onMiss(val: number): AttackBuilder;
-    onMiss(val: string): AttackBuilder;
-    onMiss(val: RollBuilder): AttackBuilder;
-    onMiss(count: number, die: RollBuilder): AttackBuilder;
-    onMiss(count: number, sides: number): AttackBuilder;
-    onMiss(count: number, die: RollBuilder, modifier: number): AttackBuilder;
-    onMiss(count: number, sides: number, modifier: number): AttackBuilder;
-    noCrit(): AttackBuilder;
-    toExpression(): string;
-    resolveProbabilities(check: ACBuilder | AlwaysHitBuilder | AlwaysCritBuilder, eps?: number): {
-        pSuccess: number;
-        pHit: number;
-        pCrit: number;
-        pMiss: number;
-    };
-    resolve(eps?: number): AttackResolution;
-    toPMF(eps?: number): PMF;
-    get pmf(): PMF;
-    toQuery(eps?: number): DiceQuery;
-}
-
-interface AttackConfig {
-    ac: number;
-    critThreshold: number;
-}
-declare class ACBuilder extends RollBuilder {
-    readonly attackConfig: AttackConfig;
-    constructor(baseRoll: RollBuilder, ac: number, attackConfig?: AttackConfig);
-    onHit(val: number): AttackBuilder;
-    onHit(val: string): AttackBuilder;
-    onHit(val: RollBuilder): AttackBuilder;
-    onHit(count: number, die: RollBuilder): AttackBuilder;
-    onHit(count: number, sides: number): AttackBuilder;
-    onHit(count: number, die: RollBuilder, modifier: number): AttackBuilder;
-    onHit(count: number, sides: number, modifier: number): AttackBuilder;
-    get critThreshold(): number;
-    critOn(threshold: number): ACBuilder;
-    alwaysCrits(): AlwaysCritBuilder;
-    toExpression(): string;
-    toPMF(eps?: number): PMF;
-    copy(): ACBuilder;
-}
-
-declare function d(sides: number | string): RollBuilder;
-declare const d4: RollBuilder;
-declare const d6: RollBuilder;
-declare const d8: RollBuilder;
-declare const d10: RollBuilder;
-declare const d12: RollBuilder;
-declare const d20: RollBuilder;
-declare const hd20: RollBuilder;
-declare const d100: RollBuilder;
-declare const flat: (n: number) => RollBuilder;
-declare const roll: RollFactory;
-declare const builderPMFCache: LRUCache<string, PMF>;
-
-export { ACBuilder, AlwaysCritBuilder, AlwaysHitBuilder, AttackBuilder, type AttackConfig, type AttackResolution, type CheckBuilder, DCBuilder, HalfRollBuilder, type KeepMode, MaxOfRollBuilder, ParsedRollBuilder, PooledRollBuilder, type Resolution, RollBuilder, type RollConfig, type RollFactory, RollType, SaveBuilder, type SaveOutcome, type SaveResolution, ScaleRollBuilder, builderPMFCache, d, d10, d100, d12, d20, d4, d6, d8, defaultConfig, flat, hd20, roll, sumRolls };