@yipe/dice 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,111 +1,9 @@
-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.
- *
- * Extends the built-in {@link Error}, so existing `catch (e)` / message checks
- * continue to work, while callers can now narrow with `instanceof DiceParseError`.
- *
- * @example
- * try {
- *   parse("d6@3");
- * } catch (e) {
- *   if (e instanceof DiceParseError) {
- *     // e.expression === "d6@3"
- *   }
- * }
- */
-declare class DiceParseError extends Error {
-    /** The original expression that failed to parse, when available. */
-    readonly expression?: string;
-    /** The underlying error that triggered this one, when available. */
-    readonly cause?: unknown;
-    constructor(message: string, options?: {
-        expression?: string;
-        cause?: unknown;
-    });
-}
-
-/** Enable or disable the internal parse cache. */
-declare function setCachingEnabled(enabled: boolean): void;
-/** Returns whether the internal parse cache is currently enabled. */
-declare function getCachingEnabled(): boolean;
-/** Clears the internal parse cache. */
-declare function clearParserCache(): void;
-/**
- * Parse a dice expression into a PMF.
- *
- * - Expression is case-insensitive and ignores spaces.
- */
-declare function parse(expression: string, n?: number): PMF;
-
-/** A labeled mixture builder that preserves provenance in Bin.count. */
-declare class Mixture<L extends string = string> {
-    private readonly totals;
-    private readonly labelMass;
-    private readonly eps;
-    constructor(eps?: number);
-    /** Remove all accumulated state. */
-    clear(): this;
-    /** Number of distinct outcome values currently accumulated. */
-    size(): number;
-    /** Whether a label was ever added. */
-    hasLabel(label: L): boolean;
-    /**
-     * Add a labeled component with a mixture weight.
-     * Weight can be any positive finite number. Very small contributions are pruned by eps.
-     */
-    add(label: L, pmf: PMF, weight?: number): this;
-    buildPMF(eps?: number): PMF;
-    /**
-     * Produce normalized *per-label* PMFs (labels independent).
-     * These are unlabeled PMFs built from the raw mass of that label alone.
-     */
-    byOutcome(): Record<L, PMF>;
-    /**
-     * Mixture weights per label, normalized to sum to 1 over labels that appeared.
-     * Uses raw mass before per-outcome normalization.
-     */
-    weights(): Record<L, number>;
-    toJSON(): {
-        totals: Array<[number, number]>;
-        labels: Array<[number, Record<L, number>]>;
-        eps: number;
-    };
-    static mix<L extends string = string>(items: Array<[label: L, pmf: PMF, weight: number]>, eps?: number): PMF;
-}
-
-export { type BounceOddsOptions, DiceParseError, Mixture, PMF, calculateBounceOdds, clearParserCache, getCachingEnabled, parse, setCachingEnabled };
+export * from "./common/bounce.js";
+export * from "./common/errors.js";
+export * from "./common/lru-cache.js";
+export * from "./common/types.js";
+export * from "./parser/parser.js";
+export * from "./pmf/mixture.js";
+export * from "./pmf/pmf.js";
+export * from "./pmf/query.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -201,7 +201,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) {
@@ -227,6 +227,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
@@ -831,290 +839,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.
@@ -2486,6 +2210,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) {