@yipe/dice 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -203,7 +203,7 @@ var _DiceQuery = class _DiceQuery {
    * const attack = d20.plus(5).ac(15).onHit(d(2,6).plus(3)).onCrit(d(2,6))
    * const query = attack.toQuery()
    * const pmf = query.combinedWithAttribution()
-   * // Now pmf can be used with toDamageAttributionChartSeries()
+   * // Now pmf can be used with attributionByValue() / damageAttributionChartModel()
    */
   combinedWithAttribution() {
     if (this._combinedWithAttr) {
@@ -229,6 +229,14 @@ var _DiceQuery = class _DiceQuery {
   attributionByValue() {
     return this.combinedWithAttribution().attributionByValue();
   }
+  /**
+   * Full numeric model for the stacked damage-attribution chart. Convenience for
+   * `combinedWithAttribution().damageAttributionChartModel(options)`; see
+   * {@link PMF.damageAttributionChartModel}.
+   */
+  damageAttributionChartModel(options) {
+    return this.combinedWithAttribution().damageAttributionChartModel(options);
+  }
   /**
    * How many of the independent single PMFs can produce the given outcome
    * label. Useful for "all of them succeeded" style probabilities where the
@@ -833,290 +841,6 @@ var _DiceQuery = class _DiceQuery {
     }));
     return { labels: damageValues, datasets };
   }
-  /**
-   * Returns pure mathematical data for attribution charts showing outcome contributions.
-   *
-   * Automatically discovers all outcome types present in the PMF, applies filtering rules,
-   * and returns proportional data suitable for stacked visualization.
-   *
-   * @param options Configuration options
-   * @param options.stackOrder Preferred order for outcome types (unknowns placed at end)
-   * @param options.filterRules Function to determine if outcome should be included for a given damage value
-   * @param options.asPercentages Whether to return percentages (0-100) or probabilities (0-1)
-   * @returns Pure data structure with support, outcomes, and proportional data
-   *
-   * @example
-   * query.toAttributionChartSeries()
-   * // → {support: [0, 6, 12], outcomes: ['hit', 'crit'], data: {hit: [5.2, 8.1, ...], crit: [0, 2.3, ...]}}
-   */
-  toAttributionChartSeries(options = {}) {
-    const {
-      stackOrder = [
-        "missNone",
-        "missDamage",
-        "saveFail",
-        "saveHalf",
-        "pc",
-        "hit",
-        "crit"
-      ],
-      filterRules = (outcome, damage) => !(outcome === "missNone" && damage !== 0),
-      asPercentages = true
-    } = options;
-    const originalSupport = this.combined.support();
-    if (originalSupport.length === 0) {
-      return { support: [], outcomes: [], data: {} };
-    }
-    const minDamage = Math.min(...originalSupport);
-    const maxDamage = Math.max(...originalSupport);
-    const support = Array.from(
-      { length: maxDamage - minDamage + 1 },
-      (_, i) => minDamage + i
-    );
-    const allOutcomeTypes = /* @__PURE__ */ new Set();
-    for (const [, bin] of this.combined.map) {
-      for (const outcomeType in bin.count) {
-        if (bin.count[outcomeType] && bin.count[outcomeType] > 0) {
-          allOutcomeTypes.add(outcomeType);
-        }
-      }
-    }
-    const existingOutcomes = Array.from(allOutcomeTypes).sort((a, b) => {
-      const indexA = stackOrder.indexOf(a);
-      const indexB = stackOrder.indexOf(b);
-      if (indexA >= 0 && indexB >= 0) return indexA - indexB;
-      if (indexA >= 0) return -1;
-      if (indexB >= 0) return 1;
-      return a.localeCompare(b);
-    });
-    if (existingOutcomes.length === 0) {
-      return { support, outcomes: [], data: {} };
-    }
-    const data = {};
-    for (const outcome of existingOutcomes) {
-      data[outcome] = support.map((damage) => {
-        const bin = this.combined.map.get(damage);
-        if (!bin) return 0;
-        if (!filterRules(outcome, damage)) {
-          return 0;
-        }
-        const outcomeCount = bin.count[outcome] || 0;
-        let totalChartableCount = 0;
-        for (const [outcomeName, count] of Object.entries(bin.count)) {
-          if (filterRules(outcomeName, damage)) {
-            totalChartableCount += count || 0;
-          }
-        }
-        if (totalChartableCount === 0) return 0;
-        const outcomeFraction = outcomeCount / totalChartableCount;
-        const outcomeProbability = bin.p * outcomeFraction;
-        return asPercentages ? outcomeProbability * 100 : outcomeProbability;
-      });
-    }
-    return {
-      support,
-      outcomes: existingOutcomes,
-      data
-    };
-  }
-  /**
-   * Returns pure mathematical data for damage attribution charts showing damage contribution
-   * from each outcome type at each damage value.
-   *
-   * Similar to toAttributionChartSeries() but uses bin.attr (damage attribution) instead of
-   * bin.count (probability attribution).
-   *
-   * @param options Configuration options
-   * @param options.stackOrder Preferred order for outcome types (unknowns placed at end)
-   * @param options.filterRules Function to determine if outcome should be included for a given damage value
-   * @param options.asPercentages Whether to return percentages (0-100) or raw damage values (0+)
-   * @returns Pure data structure with support, outcomes, and damage attribution data
-   *
-   * @example
-   * query.toDamageAttributionChartSeries()
-   * // → {support: [0, 6, 12], outcomes: ['hit', 'crit'], data: {hit: [3.2, 5.1, ...], crit: [0, 1.8, ...]}}
-   */
-  toDamageAttributionChartSeries(options = {}) {
-    const {
-      stackOrder = [
-        "missNone",
-        "missDamage",
-        "saveFail",
-        "saveHalf",
-        "pc",
-        "hit",
-        "crit"
-      ],
-      filterRules = (outcome, damage) => !(outcome === "missNone" && damage !== 0),
-      asPercentages = true
-    } = options;
-    const originalSupport = this.combined.support();
-    if (originalSupport.length === 0) {
-      return { support: [], outcomes: [], data: {} };
-    }
-    const minDamage = Math.min(...originalSupport);
-    const maxDamage = Math.max(...originalSupport);
-    const support = Array.from(
-      { length: maxDamage - minDamage + 1 },
-      (_, i) => minDamage + i
-    );
-    const allOutcomeTypes = /* @__PURE__ */ new Set();
-    for (const [, bin] of this.combined.map) {
-      if (bin.attr) {
-        for (const outcomeType in bin.attr) {
-          if (bin.attr[outcomeType] && bin.attr[outcomeType] > 0) {
-            allOutcomeTypes.add(outcomeType);
-          }
-        }
-      }
-    }
-    const existingOutcomes = Array.from(allOutcomeTypes).sort((a, b) => {
-      const indexA = stackOrder.indexOf(a);
-      const indexB = stackOrder.indexOf(b);
-      if (indexA >= 0 && indexB >= 0) return indexA - indexB;
-      if (indexA >= 0) return -1;
-      if (indexB >= 0) return 1;
-      return a.localeCompare(b);
-    });
-    if (existingOutcomes.length === 0) {
-      return { support, outcomes: [], data: {} };
-    }
-    const data = {};
-    for (const outcome of existingOutcomes) {
-      data[outcome] = support.map((damage) => {
-        const bin = this.combined.map.get(damage);
-        if (!bin || !bin.attr) return 0;
-        if (!filterRules(outcome, damage)) {
-          return 0;
-        }
-        const outcomeDamageAttribution = bin.attr[outcome] || 0;
-        if (asPercentages) {
-          let totalDamageAttribution = 0;
-          for (const [outcomeName, damageAttr] of Object.entries(bin.attr)) {
-            if (filterRules(outcomeName, damage)) {
-              totalDamageAttribution += damageAttr || 0;
-            }
-          }
-          if (totalDamageAttribution === 0) return 0;
-          const damagePercentage = outcomeDamageAttribution / totalDamageAttribution * 100;
-          return damagePercentage * bin.p * 100;
-        } else {
-          return outcomeDamageAttribution;
-        }
-      });
-    }
-    return {
-      support,
-      outcomes: existingOutcomes,
-      data
-    };
-  }
-  /**
-   * Returns pure mathematical data for outcome attribution charts showing which
-   * attack outcome combinations can produce each damage value.
-   *
-   * Unlike toDamageAttributionChartSeries() which tracks damage sources, this tracks
-   * outcome combinations - answering "what attack outcomes produced this damage?"
-   *
-   * @param options Configuration options
-   * @param options.stackOrder Preferred order for outcome types (unknowns placed at end)
-   * @param options.filterRules Function to determine if outcome should be included for a given damage value
-   * @param options.asPercentages Whether to return percentages (0-100) or probabilities (0-1)
-   * @returns Pure data structure with support, outcomes, and outcome combination probabilities
-   *
-   * @example
-   * query.toOutcomeAttributionChartSeries()
-   * // → {support: [0, 6, 12], outcomes: ['all_miss', 'mixed', 'all_hit'], data: {all_miss: [15, 0, 0], mixed: [60, 80, 20], all_hit: [25, 20, 80]}}
-   */
-  toOutcomeAttributionChartSeries(options = {}) {
-    const {
-      stackOrder = [
-        "missNone",
-        "missDamage",
-        "saveFail",
-        "saveHalf",
-        "pc",
-        "hit",
-        "crit"
-      ],
-      filterRules = (outcome, damage) => !(outcome === "missNone" && damage !== 0),
-      asPercentages = true
-    } = options;
-    const originalSupport = this.combined.support();
-    if (originalSupport.length === 0) {
-      return { support: [], outcomes: [], data: {} };
-    }
-    const minDamage = Math.min(...originalSupport);
-    const maxDamage = Math.max(...originalSupport);
-    const support = Array.from(
-      { length: maxDamage - minDamage + 1 },
-      (_, i) => minDamage + i
-    );
-    const allOutcomeTypes = /* @__PURE__ */ new Set();
-    for (const [, bin] of this.combined.map) {
-      for (const outcomeType in bin.count) {
-        if (bin.count[outcomeType] && bin.count[outcomeType] > 0) {
-          allOutcomeTypes.add(outcomeType);
-        }
-      }
-    }
-    const existingOutcomes = Array.from(allOutcomeTypes).sort((a, b) => {
-      const indexA = stackOrder.indexOf(a);
-      const indexB = stackOrder.indexOf(b);
-      if (indexA >= 0 && indexB >= 0) return indexA - indexB;
-      if (indexA >= 0) return -1;
-      if (indexB >= 0) return 1;
-      return a.localeCompare(b);
-    });
-    if (existingOutcomes.length === 0) {
-      return { support, outcomes: [], data: {} };
-    }
-    const data = {};
-    for (const outcome of existingOutcomes) {
-      data[outcome] = support.map((damage) => {
-        const bin = this.combined.map.get(damage);
-        if (!bin) return 0;
-        if (!filterRules(outcome, damage)) {
-          return 0;
-        }
-        if (outcome === "missNone") {
-          const outcomeCount = bin.count[outcome] || 0;
-          if (outcomeCount === 0) return 0;
-          if (asPercentages) {
-            let totalChartableCount = 0;
-            for (const [outcomeName, count] of Object.entries(bin.count)) {
-              if (filterRules(outcomeName, damage)) {
-                totalChartableCount += count || 0;
-              }
-            }
-            if (totalChartableCount === 0) return 0;
-            const outcomeFraction = outcomeCount / totalChartableCount;
-            return outcomeFraction * bin.p * 100;
-          } else {
-            return outcomeCount;
-          }
-        }
-        if (!bin.attr) return 0;
-        const outcomeDamageContribution = bin.attr[outcome] || 0;
-        if (asPercentages) {
-          let totalDamageAttribution = 0;
-          for (const [, damageAttr] of Object.entries(bin.attr)) {
-            totalDamageAttribution += damageAttr || 0;
-          }
-          if (totalDamageAttribution === 0) return 0;
-          const outcomeFraction = outcomeDamageContribution / totalDamageAttribution;
-          return outcomeFraction * bin.p * 100;
-        } else {
-          return outcomeDamageContribution;
-        }
-      });
-    }
-    return {
-      support,
-      outcomes: existingOutcomes,
-      data
-    };
-  }
   /**
    * Returns pure mathematical data for cumulative distribution function (CDF).
    * Shows P(X ≤ x) - the probability of getting at most x damage.
@@ -2488,6 +2212,149 @@ var _PMF = class _PMF {
     }
     return result;
   }
+  /**
+   * Reversed-convention CCDF percentile markers used by the attribution chart:
+   * for each target probability t, the largest damage x still reached with
+   * P(X ≥ x) > t%, falling back to the smallest/largest support value at the
+   * edges. Ported verbatim from the app so `p80/p50/p20` keep their intentional
+   * reversed meaning (p80 is the low-damage end). Computed on the full, un-binned
+   * support. Assumes a non-empty map.
+   */
+  attributionPercentiles() {
+    const sortedKeys = [...this.map.keys()].sort((a, b) => a - b);
+    const sparseCCDF = [];
+    let cumulativeP = 0;
+    for (let i = sortedKeys.length - 1; i >= 0; i--) {
+      const key = sortedKeys[i];
+      const bin = this.map.get(key);
+      if (!bin) continue;
+      cumulativeP += bin.p;
+      sparseCCDF.unshift({ x: key, y: cumulativeP * 100 });
+    }
+    const findDamageAtProbability = (targetProb) => {
+      for (let i = 0; i < sparseCCDF.length; i++) {
+        if (sparseCCDF[i].y <= targetProb) {
+          return i > 0 ? sparseCCDF[i - 1].x : sparseCCDF[i].x;
+        }
+      }
+      return sparseCCDF[sparseCCDF.length - 1].x;
+    };
+    return {
+      p80: findDamageAtProbability(80),
+      p50: findDamageAtProbability(50),
+      p20: findDamageAtProbability(20)
+    };
+  }
+  /**
+   * Full numeric model for the stacked damage-attribution chart — bar-height
+   * masses, tooltip shares, bucket labels/ranges, percentile markers, and the
+   * mean. The caller only maps these into a rendering format (colors, labels,
+   * axis units); all of the dice-and-probability logic lives here.
+   *
+   * Built split-first-then-bin: the attribution split ({@link attributionByValue})
+   * runs on the un-binned distribution, then the resulting series are coarsened.
+   * {@link rebin} is deliberately *not* used — rebinning first would fold any
+   * sub-`binSize` damage into the damage-0 bucket, which the split then mistakes
+   * for a clean miss and drops.
+   *
+   * @param options.maxBuckets Coarsen to at most this many equal-width buckets
+   *   when the integer support is wider (`range > maxBuckets`); omit for a dense,
+   *   per-integer model.
+   * @param options.stackOrder Preferred outcome order (defaults to
+   *   {@link ALL_OUTCOME_TYPES}); labels outside it sort alphabetically after.
+   * @param options.epsilon Bucket-total floor below which a `shares` entry is 0
+   *   (divide-by-~0 guard). Defaults to 1e-9.
+   */
+  damageAttributionChartModel(options = {}) {
+    const { maxBuckets, stackOrder = ALL_OUTCOME_TYPES, epsilon = 1e-9 } = options;
+    const empty = {
+      labels: [],
+      outcomes: [],
+      series: /* @__PURE__ */ new Map(),
+      shares: /* @__PURE__ */ new Map(),
+      totals: [],
+      percentiles: { p80: 0, p50: 0, p20: 0 },
+      mean: 0
+    };
+    if (this.map.size === 0) return empty;
+    const split = this.attributionByValue();
+    const discovered = /* @__PURE__ */ new Set();
+    for (const [, bin] of this.map) {
+      for (const k in bin.count) discovered.add(k);
+      if (bin.attr) for (const k in bin.attr) discovered.add(k);
+    }
+    const outcomes = sortOutcomes([...discovered], stackOrder);
+    const hasAttribution = outcomes.length > 0;
+    let min = Infinity;
+    let max = -Infinity;
+    const widen = (d) => {
+      if (d < min) min = d;
+      if (d > max) max = d;
+    };
+    if (hasAttribution) {
+      for (const s of split.values())
+        for (const [d, m] of s) if (m > 0) widen(d);
+    } else {
+      for (const [d, bin] of this.map) if ((bin.p || 0) > 0) widen(d);
+    }
+    if (max < min) return empty;
+    const range = max - min;
+    const binned = maxBuckets !== void 0 && maxBuckets > 0 && range > maxBuckets;
+    const binSize = binned ? Math.ceil((range + 1) / maxBuckets) : 1;
+    const numBins = binned ? Math.ceil((range + 1) / binSize) : range + 1;
+    const bucketOf = (d) => Math.floor((d - min) / binSize);
+    const labels = [];
+    const binRanges = binned ? [] : void 0;
+    for (let i = 0; i < numBins; i++) {
+      const start = min + i * binSize;
+      labels.push(start);
+      if (binRanges)
+        binRanges.push({ start, end: Math.min(start + binSize - 1, max) });
+    }
+    const series = /* @__PURE__ */ new Map();
+    for (const outcome of outcomes) {
+      const arr = new Array(numBins).fill(0);
+      const s = split.get(outcome);
+      if (s) {
+        for (const [d, m] of s) {
+          const b = bucketOf(d);
+          if (b >= 0 && b < numBins) arr[b] += m;
+        }
+      }
+      series.set(outcome, arr);
+    }
+    const totals = new Array(numBins).fill(0);
+    if (hasAttribution) {
+      for (const arr of series.values())
+        for (let i = 0; i < numBins; i++) totals[i] += arr[i];
+    } else {
+      for (const [d, bin] of this.map) {
+        const p = bin.p || 0;
+        if (p <= 0) continue;
+        const b = bucketOf(d);
+        if (b >= 0 && b < numBins) totals[b] += p;
+      }
+    }
+    const shares = /* @__PURE__ */ new Map();
+    for (const outcome of outcomes) {
+      const arr = series.get(outcome);
+      const sh = new Array(numBins).fill(0);
+      for (let i = 0; i < numBins; i++) {
+        sh[i] = totals[i] > epsilon ? arr[i] / totals[i] : 0;
+      }
+      shares.set(outcome, sh);
+    }
+    return {
+      labels,
+      binRanges,
+      outcomes,
+      series,
+      shares,
+      totals,
+      percentiles: this.attributionPercentiles(),
+      mean: this.mean()
+    };
+  }
   tailProbGE(t) {
     let s = 0;
     for (const [x, bin] of this) {