@yipe/dice 0.3.0 → 0.4.0

package/dist/builder/index.d.cts

@@ -1,4 +1,4 @@
-import { P as PMF, D as DiceQuery, C as CritConfig, L as LRUCache } from '../pmf-DqUCnYN9.cjs';
+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;
@@ -14,7 +14,6 @@ type RollFactory = {
     d100(): RollBuilder;
     flat(n: number): RollBuilder;
 };
-type RollType = "flat" | "advantage" | "disadvantage" | "elven accuracy";
 type KeepMode = "highest" | "lowest";
 type RollConfig = {
     count: number;
@@ -377,4 +376,4 @@ 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, type RollType, SaveBuilder, type SaveOutcome, type SaveResolution, builderPMFCache, d, d10, d100, d12, d20, d4, d6, d8, defaultConfig, flat, hd20, roll };
+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, builderPMFCache, d, d10, d100, d12, d20, d4, d6, d8, defaultConfig, flat, hd20, roll };

package/dist/builder/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PMF, D as DiceQuery, C as CritConfig, L as LRUCache } from '../pmf-DqUCnYN9.js';
+import { b as RollType, P as PMF, l as DiceQuery, C as CritConfig, L as LRUCache } from '../pmf-D5VRghZI.js';
 
 type RollFactory = {
     (count: number, sides?: number, modifier?: number): RollBuilder;
@@ -14,7 +14,6 @@ type RollFactory = {
     d100(): RollBuilder;
     flat(n: number): RollBuilder;
 };
-type RollType = "flat" | "advantage" | "disadvantage" | "elven accuracy";
 type KeepMode = "highest" | "lowest";
 type RollConfig = {
     count: number;
@@ -377,4 +376,4 @@ 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, type RollType, SaveBuilder, type SaveOutcome, type SaveResolution, builderPMFCache, d, d10, d100, d12, d20, d4, d6, d8, defaultConfig, flat, hd20, roll };
+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, builderPMFCache, d, d10, d100, d12, d20, d4, d6, d8, defaultConfig, flat, hd20, roll };

package/dist/builder/index.js

@@ -42,6 +42,7 @@ var LRUCache = class {
 
 // src/common/types.ts
 var EPS = 1e-12;
+var MISS_NONE_OUTCOME = "missNone";
 
 // src/pmf/query.ts
 var _DiceQuery = class _DiceQuery {
@@ -104,6 +105,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.
    *
@@ -1387,6 +1411,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);
@@ -1908,6 +1946,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();
@@ -2135,6 +2216,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((d2) => min + Math.floor((d2 - min) / binSize) * binSize);
+  }
   /** Dense integer support from min..max (inclusive).
    * Useful for showing empty bars in charts.
    */
@@ -2210,6 +2324,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) {