@yipe/dice 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,37 @@
-import { P as PMF } from './pmf-DqUCnYN9.cjs';
-export { B as Bin, C as CritConfig, a as DamageDistribution, D as DiceQuery, E as EPS, L as LRUCache, O as OutcomeLabelMap, b as OutcomeSnapshot, c as OutcomeType, R as Rounding, S as Snapshot, o as onAnyHit, d as onCritOnly, e as onHitOnly, f as onMissDamageOnly, g as onMissOnly, h as onPotentCantripOnly, i as onSaveFailOnly, j as onSaveHalfOnly, p as pmfCache } from './pmf-DqUCnYN9.cjs';
+import { P as PMF } from './pmf-D5VRghZI.cjs';
+export { A as ALL_OUTCOME_TYPES, B as Bin, C as CritConfig, D as DamageDistribution, l as DiceQuery, E as EPS, L as LRUCache, M as MISS_NONE_OUTCOME, d as OUTCOME_DISPLAY_ORDER, O as OutcomeLabelMap, m as OutcomeSnapshot, a as OutcomeType, b as RollType, R as Rounding, S as Snapshot, c as critProbability, o as onAnyHit, e as onCritOnly, f as onHitOnly, h as onMissDamageOnly, g as onMissOnly, k as onPotentCantripOnly, j as onSaveFailOnly, i as onSaveHalfOnly, p as pmfCache, s as sortOutcomes } from './pmf-D5VRghZI.cjs';
+
+/**
+ * Bounce odds — the "birthday problem" for bouncing damage dice (e.g. Chromatic
+ * Orb): the probability that at least two of K dice with S faces show the same
+ * value, which is what lets the spell jump to another target.
+ *
+ * Accounts for two modifiers:
+ * - **Elemental Adept** (`minimumDieRoll >= 2`): rolls below the minimum are
+ *   bumped up to it, collapsing the low faces onto a single heavier value.
+ * - **Empowered Spell** (`rerollDamageDice > 0`): a number of dice may be
+ *   rerolled once, giving a second chance at a match.
+ *
+ * The base and Elemental-Adept cases are computed exactly (see
+ * {@link pAllDistinct}); the Empowered-Spell reroll is an explicit model layered
+ * on the exact base match probability.
+ */
+/** Options that modify bounce odds via metamagic / feats. */
+interface BounceOddsOptions {
+    /** Minimum die roll — e.g. 2 for Elemental Adept, 3 for Great Weapon Fighting 2024. */
+    minimumDieRoll?: number;
+    /** Number of dice that may be rerolled once — e.g. CHA modifier for Empowered Spell. */
+    rerollDamageDice?: number;
+}
+/**
+ * P(at least two of `diceCount` dice with `dieFaces` faces match), honoring
+ * Elemental Adept and Empowered Spell. Returns a probability in [0, 1].
+ *
+ * @param diceCount Number of dice rolled.
+ * @param dieFaces Faces per die (e.g. 8 for d8).
+ * @param options Optional metamagic / feat modifiers.
+ */
+declare function calculateBounceOdds(diceCount: number, dieFaces: number, options?: BounceOddsOptions): number;
 
 /**
  * Error thrown when a dice expression cannot be parsed.
@@ -76,4 +108,4 @@ declare class Mixture<L extends string = string> {
     static mix<L extends string = string>(items: Array<[label: L, pmf: PMF, weight: number]>, eps?: number): PMF;
 }
 
-export { DiceParseError, Mixture, PMF, clearParserCache, getCachingEnabled, parse, setCachingEnabled };
+export { type BounceOddsOptions, DiceParseError, Mixture, PMF, calculateBounceOdds, clearParserCache, getCachingEnabled, parse, setCachingEnabled };

package/dist/index.d.ts

@@ -1,5 +1,37 @@
-import { P as PMF } from './pmf-DqUCnYN9.js';
-export { B as Bin, C as CritConfig, a as DamageDistribution, D as DiceQuery, E as EPS, L as LRUCache, O as OutcomeLabelMap, b as OutcomeSnapshot, c as OutcomeType, R as Rounding, S as Snapshot, o as onAnyHit, d as onCritOnly, e as onHitOnly, f as onMissDamageOnly, g as onMissOnly, h as onPotentCantripOnly, i as onSaveFailOnly, j as onSaveHalfOnly, p as pmfCache } from './pmf-DqUCnYN9.js';
+import { P as PMF } from './pmf-D5VRghZI.js';
+export { A as ALL_OUTCOME_TYPES, B as Bin, C as CritConfig, D as DamageDistribution, l as DiceQuery, E as EPS, L as LRUCache, M as MISS_NONE_OUTCOME, d as OUTCOME_DISPLAY_ORDER, O as OutcomeLabelMap, m as OutcomeSnapshot, a as OutcomeType, b as RollType, R as Rounding, S as Snapshot, c as critProbability, o as onAnyHit, e as onCritOnly, f as onHitOnly, h as onMissDamageOnly, g as onMissOnly, k as onPotentCantripOnly, j as onSaveFailOnly, i as onSaveHalfOnly, p as pmfCache, s as sortOutcomes } from './pmf-D5VRghZI.js';
+
+/**
+ * Bounce odds — the "birthday problem" for bouncing damage dice (e.g. Chromatic
+ * Orb): the probability that at least two of K dice with S faces show the same
+ * value, which is what lets the spell jump to another target.
+ *
+ * Accounts for two modifiers:
+ * - **Elemental Adept** (`minimumDieRoll >= 2`): rolls below the minimum are
+ *   bumped up to it, collapsing the low faces onto a single heavier value.
+ * - **Empowered Spell** (`rerollDamageDice > 0`): a number of dice may be
+ *   rerolled once, giving a second chance at a match.
+ *
+ * The base and Elemental-Adept cases are computed exactly (see
+ * {@link pAllDistinct}); the Empowered-Spell reroll is an explicit model layered
+ * on the exact base match probability.
+ */
+/** Options that modify bounce odds via metamagic / feats. */
+interface BounceOddsOptions {
+    /** Minimum die roll — e.g. 2 for Elemental Adept, 3 for Great Weapon Fighting 2024. */
+    minimumDieRoll?: number;
+    /** Number of dice that may be rerolled once — e.g. CHA modifier for Empowered Spell. */
+    rerollDamageDice?: number;
+}
+/**
+ * P(at least two of `diceCount` dice with `dieFaces` faces match), honoring
+ * Elemental Adept and Empowered Spell. Returns a probability in [0, 1].
+ *
+ * @param diceCount Number of dice rolled.
+ * @param dieFaces Faces per die (e.g. 8 for d8).
+ * @param options Optional metamagic / feat modifiers.
+ */
+declare function calculateBounceOdds(diceCount: number, dieFaces: number, options?: BounceOddsOptions): number;
 
 /**
  * Error thrown when a dice expression cannot be parsed.
@@ -76,4 +108,4 @@ declare class Mixture<L extends string = string> {
     static mix<L extends string = string>(items: Array<[label: L, pmf: PMF, weight: number]>, eps?: number): PMF;
 }
 
-export { DiceParseError, Mixture, PMF, clearParserCache, getCachingEnabled, parse, setCachingEnabled };
+export { type BounceOddsOptions, DiceParseError, Mixture, PMF, calculateBounceOdds, clearParserCache, getCachingEnabled, parse, setCachingEnabled };

package/dist/index.js

@@ -1,3 +1,53 @@
+// src/common/bounce.ts
+function binom(n, k) {
+  if (k < 0 || k > n) return 0;
+  let result = 1;
+  for (let i = 0; i < k; i++) result = result * (n - i) / (i + 1);
+  return result;
+}
+function pAllDistinct(dice, faces, uniformCount, heavyWeight) {
+  const light = 1 / faces;
+  const eK = binom(uniformCount, dice) * Math.pow(light, dice) + heavyWeight * binom(uniformCount, dice - 1) * Math.pow(light, dice - 1);
+  let kFactorial = 1;
+  for (let i = 2; i <= dice; i++) kFactorial *= i;
+  return kFactorial * eK;
+}
+function pMatch(dice, faces, minimumDieRoll) {
+  if (dice <= 1) return 0;
+  if (dice > faces) return 1;
+  if (minimumDieRoll >= 2) {
+    const uniformCount = faces - minimumDieRoll;
+    const effectiveValues = uniformCount + 1;
+    if (dice > effectiveValues) return 1;
+    const heavyWeight = minimumDieRoll / faces;
+    const distinct = pAllDistinct(dice, faces, uniformCount, heavyWeight);
+    return Math.min(1, Math.max(0, 1 - distinct));
+  }
+  let pDistinct = 1;
+  for (let i = 0; i < dice; i++) pDistinct *= (faces - i) / faces;
+  return 1 - pDistinct;
+}
+function calculateBounceOdds(diceCount, dieFaces, options) {
+  if (diceCount <= 1) return 0;
+  if (diceCount > dieFaces) return 1;
+  const minimumDieRoll = options?.minimumDieRoll ?? 0;
+  const rerollDamageDice = options?.rerollDamageDice ?? 0;
+  const pMatchFirst = pMatch(diceCount, dieFaces, minimumDieRoll);
+  const rerollCount = Math.min(rerollDamageDice, diceCount);
+  if (rerollCount <= 0) return pMatchFirst;
+  const pNoMatchFirst = 1 - pMatchFirst;
+  const keptDice = diceCount - rerollCount;
+  const effectiveFaces = minimumDieRoll >= 2 ? dieFaces - (minimumDieRoll - 1) : dieFaces;
+  const pRerollDieMissesAll = keptDice > 0 ? Math.pow((effectiveFaces - keptDice) / effectiveFaces, rerollCount) : 1;
+  const pAtLeastOneRerollMatches = 1 - pRerollDieMissesAll;
+  const pRerolledMatch = rerollCount >= 2 ? pMatch(rerollCount, dieFaces, minimumDieRoll) : 0;
+  const pMatchAfterReroll = Math.min(
+    1,
+    pAtLeastOneRerollMatches + pRerolledMatch * (1 - pAtLeastOneRerollMatches)
+  );
+  return Math.min(1, pMatchFirst + pNoMatchFirst * pMatchAfterReroll);
+}
+
 // src/common/errors.ts
 var DiceParseError = class _DiceParseError extends Error {
   constructor(message, options) {
@@ -53,6 +103,50 @@ var LRUCache = class {
 
 // src/common/types.ts
 var EPS = 1e-12;
+function critProbability(critRange, rollType = "flat") {
+  const base = critRange / 20;
+  switch (rollType) {
+    case "advantage":
+      return 1 - (1 - base) ** 2;
+    case "elven accuracy":
+      return 1 - (1 - base) ** 3;
+    case "disadvantage":
+      return base ** 2;
+    case "flat":
+    default:
+      return base;
+  }
+}
+var MISS_NONE_OUTCOME = "missNone";
+var ALL_OUTCOME_TYPES = [
+  "missNone",
+  "missDamage",
+  "saveFail",
+  "saveHalf",
+  "pc",
+  "hit",
+  "crit"
+];
+var OUTCOME_DISPLAY_ORDER = [
+  "crit",
+  "hit",
+  "missDamage",
+  "saveHalf",
+  "saveFail",
+  "pc",
+  "missNone"
+];
+function sortOutcomes(outcomes, order = ALL_OUTCOME_TYPES) {
+  const rank = new Map(order.map((o, i) => [o, i]));
+  return [...outcomes].sort((a, b) => {
+    const ra = rank.get(a);
+    const rb = rank.get(b);
+    if (ra !== void 0 && rb !== void 0) return ra - rb;
+    if (ra !== void 0) return -1;
+    if (rb !== void 0) return 1;
+    return a.localeCompare(b);
+  });
+}
 var onAnyHit = ["hit", "crit"];
 var onCritOnly = ["crit"];
 var onHitOnly = ["hit"];
@@ -123,6 +217,29 @@ var _DiceQuery = class _DiceQuery {
     this._combinedWithAttr = normalized;
     return normalized;
   }
+  /**
+   * Per-label `damage value → probability mass` series for the combined,
+   * attribution-carrying distribution — the provenance core of the stacked
+   * damage-attribution chart. Convenience for
+   * `combinedWithAttribution().attributionByValue()`; see
+   * {@link PMF.attributionByValue}.
+   */
+  attributionByValue() {
+    return this.combinedWithAttribution().attributionByValue();
+  }
+  /**
+   * How many of the independent single PMFs can produce the given outcome
+   * label. Useful for "all of them succeeded" style probabilities where the
+   * exponent is the number of contributing attacks (see
+   * {@link DiceQuery.probExactlyK}).
+   */
+  countSinglesWith(label) {
+    let count = 0;
+    for (const single of this.singles) {
+      if (single.hasOutcome(label)) count++;
+    }
+    return count;
+  }
   /**
    * Returns the expected damage across all possible outcomes.
    *
@@ -1406,6 +1523,20 @@ var _PMF = class _PMF {
   static delta(value, epsilon = EPS) {
     return _PMF.fromMap(/* @__PURE__ */ new Map([[value, 1]]), epsilon);
   }
+  /**
+   * Point mass at damage 0 tagged with the canonical `missNone` outcome.
+   *
+   * Differs from {@link PMF.zero}, which labels its zero bin `miss` — the
+   * builder's attack-resolution vocabulary. This uses the `missNone`
+   * {@link OutcomeType} that the attribution charts and outcome stats key on,
+   * so it is the correct "clean miss / no damage" delta for provenance-aware
+   * mixtures feeding those consumers.
+   */
+  static missNone(epsilon = EPS) {
+    const m = /* @__PURE__ */ new Map();
+    m.set(0, { p: 1, count: { [MISS_NONE_OUTCOME]: 1 }, attr: {} });
+    return new _PMF(m, epsilon, false, "missNone");
+  }
   // This creates a single bin at value 0, but with weight 0.
   static emptyMass() {
     return _PMF.zero().scaleMass(0);
@@ -1927,6 +2058,49 @@ var _PMF = class _PMF {
       `${this.identifier}+scaled(${branch.identifier},${probability})`
     );
   }
+  /**
+   * Redistributes probability mass to model an effect that only occurs with
+   * probability `frequency` — a conditional attack, an on-hit rider, or a
+   * sub-one AoE target fraction.
+   *
+   * Every hit outcome (damage > 0) is scaled by `frequency` — probability mass,
+   * per-label `count`, AND per-label `attr` — and the freed mass is moved into
+   * the miss bin at damage 0, tagged with the canonical `missNone` outcome.
+   * Total probability mass is preserved.
+   *
+   * Unlike a bare {@link scaleMass} or {@link mapDamage}, this keeps damage
+   * attribution (`attr`) intact, so a frequency-scaled PMF still renders
+   * correctly in the damage-attribution charts.
+   *
+   * `frequency >= 1` (or non-finite) returns this PMF unchanged; `frequency <= 0`
+   * collapses all mass into the miss bin. The miss outcome is assumed to be
+   * encoded at damage value 0.
+   *
+   * @param frequency Probability in [0, 1] that the effect occurs.
+   */
+  applyHitFrequency(frequency) {
+    if (!Number.isFinite(frequency) || frequency >= 1) return this;
+    const freq = Math.max(0, frequency);
+    const pMiss = this.pAt(0);
+    const pHit = 1 - pMiss;
+    const newMissMass = pMiss + (1 - freq) * pHit;
+    const newMap = /* @__PURE__ */ new Map();
+    newMap.set(0, {
+      p: newMissMass,
+      count: { [MISS_NONE_OUTCOME]: newMissMass },
+      attr: {}
+    });
+    for (const [damage, bin] of this.map) {
+      if (damage <= 0) continue;
+      newMap.set(damage, _PMF.scaleBin(bin, freq));
+    }
+    return new _PMF(
+      newMap,
+      this.epsilon,
+      false,
+      `freq(${this.identifier},${freq})`
+    );
+  }
   scaleMass(factor) {
     if (factor === 1) return this;
     const scaledMap = /* @__PURE__ */ new Map();
@@ -2154,6 +2328,39 @@ var _PMF = class _PMF {
   pAt(x) {
     return this.map.get(x)?.p ?? 0;
   }
+  /**
+   * P(any damage) — the mass on all non-zero outcomes, i.e. `1 - P(0)`.
+   * Assumes a miss is encoded as the damage-0 bin (the convention used across
+   * attack/save PMFs). The dual of {@link missProbability}.
+   */
+  hitProbability() {
+    return 1 - this.pAt(0);
+  }
+  /** P(no damage) — the mass at damage 0. The dual of {@link hitProbability}. */
+  missProbability() {
+    return this.pAt(0);
+  }
+  /**
+   * Coarsen the distribution into at most `maxBuckets` contiguous, equal-width
+   * damage buckets, aggregating probability mass (and `count`/`attr`
+   * provenance) into each bucket's start value. Returns this PMF unchanged when
+   * its integer support already fits within `maxBuckets`.
+   *
+   * This is a lossy display/downsampling transform (bucket start replaces the
+   * exact damage value) — use it for charting wide distributions, not for DPR
+   * math.
+   */
+  rebin(maxBuckets) {
+    if (!(maxBuckets > 0)) return this;
+    const support = this.support();
+    if (support.length === 0) return this;
+    const min = support[0];
+    const max = support[support.length - 1];
+    const range = max - min;
+    if (range + 1 <= maxBuckets) return this;
+    const binSize = Math.ceil((range + 1) / maxBuckets);
+    return this.mapDamage((d) => min + Math.floor((d - min) / binSize) * binSize);
+  }
   /** Dense integer support from min..max (inclusive).
    * Useful for showing empty bars in charts.
    */
@@ -2229,6 +2436,56 @@ var _PMF = class _PMF {
     }
     return false;
   }
+  /**
+   * Split each damage value's probability mass across outcome labels, returning
+   * per-label maps of `damage value → probability mass attributable to that
+   * label`. Summing over labels at a given value recovers that value's `p`.
+   *
+   * Damage-bearing bins are split by `attr` weight (the share of damage each
+   * outcome contributed); the clean-miss bin at 0 is split by `count` weight
+   * (there is no damage to attribute). Attribution is computed on demand via
+   * {@link withAttribution} when absent, so builder-generated PMFs work too.
+   *
+   * This is the provenance core of the stacked damage-attribution chart — the
+   * caller only maps these series into its rendering format (colors, binning,
+   * axis labels).
+   */
+  attributionByValue() {
+    const src = this.hasAttribution() ? this : this.withAttribution();
+    const result = /* @__PURE__ */ new Map();
+    const add = (label, damage, mass) => {
+      if (!(mass > 0)) return;
+      let series = result.get(label);
+      if (!series) {
+        series = /* @__PURE__ */ new Map();
+        result.set(label, series);
+      }
+      series.set(damage, (series.get(damage) ?? 0) + mass);
+    };
+    for (const [damage, bin] of src.map) {
+      const p = bin.p || 0;
+      if (p <= 0) continue;
+      const isMissBin = damage === 0;
+      if (isMissBin) {
+        let totalCount = 0;
+        for (const k in bin.count) totalCount += bin.count[k] || 0;
+        if (totalCount > 0) {
+          const c = bin.count[MISS_NONE_OUTCOME] || 0;
+          add(MISS_NONE_OUTCOME, damage, c / totalCount * p);
+        }
+        continue;
+      }
+      let totalAttr = 0;
+      if (bin.attr) for (const k in bin.attr) totalAttr += bin.attr[k] || 0;
+      if (bin.attr && totalAttr > 0) {
+        for (const k in bin.attr) {
+          if (k === MISS_NONE_OUTCOME) continue;
+          add(k, damage, (bin.attr[k] || 0) / totalAttr * p);
+        }
+      }
+    }
+    return result;
+  }
   tailProbGE(t) {
     let s = 0;
     for (const [x, bin] of this) {
@@ -3339,6 +3596,6 @@ var Mixture = class _Mixture {
   }
 };
 
-export { DiceParseError, DiceQuery, EPS, LRUCache, Mixture, PMF, clearParserCache, getCachingEnabled, onAnyHit, onCritOnly, onHitOnly, onMissDamageOnly, onMissOnly, onPotentCantripOnly, onSaveFailOnly, onSaveHalfOnly, parse, pmfCache, setCachingEnabled };
+export { ALL_OUTCOME_TYPES, DiceParseError, DiceQuery, EPS, LRUCache, MISS_NONE_OUTCOME, Mixture, OUTCOME_DISPLAY_ORDER, PMF, calculateBounceOdds, clearParserCache, critProbability, getCachingEnabled, onAnyHit, onCritOnly, onHitOnly, onMissDamageOnly, onMissOnly, onPotentCantripOnly, onSaveFailOnly, onSaveHalfOnly, parse, pmfCache, setCachingEnabled, sortOutcomes };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map