@yipe/dice 0.2.15 → 0.2.17

package/dist/builder/index.cjs

@@ -54,6 +54,7 @@ var _DiceQuery = class _DiceQuery {
   constructor(singles, combined, eps = EPS) {
     __publicField(this, "singles");
     __publicField(this, "combined");
+    __publicField(this, "_combinedWithAttr");
     this.singles = Array.isArray(singles) ? singles : [singles];
     if (this.singles.some((s) => s === void 0)) {
       throw new Error("DiceQuery contains undefined singles");
@@ -61,6 +62,35 @@ var _DiceQuery = class _DiceQuery {
     const c = combined ?? PMF.convolveMany(this.singles);
     this.combined = Math.abs(c.mass() - 1) <= eps ? c : c.normalize();
   }
+  /**
+   * Returns a new PMF with damage attribution metadata populated.
+   *
+   * This method computes attribution on-demand for builder-generated PMFs,
+   * enabling them to work with damage attribution charts. The `attr` field
+   * tracks how much damage each outcome type contributes at each damage value.
+   *
+   * For each bin at damage D: sum(attr.values()) ≈ D × P(damage = D)
+   *
+   * Performance: Cached after first call. Adds minimal overhead vs `combined`.
+   *
+   * @returns PMF with attr field populated for damage attribution charts
+   *
+   * @example
+   * 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()
+   */
+  combinedWithAttribution() {
+    if (this._combinedWithAttr) {
+      return this._combinedWithAttr;
+    }
+    const singlesWithAttr = this.singles.map((pmf) => pmf.withAttribution());
+    const combined = PMF.convolveMany(singlesWithAttr, this.combined.epsilon);
+    const normalized = Math.abs(combined.mass() - 1) <= this.combined.epsilon ? combined : combined.normalize();
+    this._combinedWithAttr = normalized;
+    return normalized;
+  }
   /**
    * Returns the expected damage across all possible outcomes.
    *
@@ -1405,9 +1435,9 @@ var _PMF = class _PMF {
     let totalWeight = items.reduce((s, { weight }) => s + weight, 0);
     if (Math.abs(totalWeight) <= eps) totalWeight = 0;
     if (Math.abs(1 - totalWeight) <= eps) totalWeight = 1;
-    if (totalWeight > 1 + eps) {
+    if (totalWeight > 1 + EPS) {
       throw new Error(
-        `PMF.exclusive: total weight ${totalWeight.toFixed(6)} exceeds 1.`
+        `PMF.exclusive: total weight ${totalWeight} exceeds 1. (epsilon: ${eps})`
       );
     }
     let out = _PMF.empty(eps);
@@ -1449,6 +1479,44 @@ var _PMF = class _PMF {
     }
     return out;
   }
+  /**
+   * Adds damage attribution metadata to this PMF based on existing count metadata.
+   * For each bin, sets attr[outcome] = damage × count[outcome].
+   *
+   * This enables damage attribution charts to work with builder-generated PMFs.
+   * The parser generates attr automatically, but builder PMFs only have count.
+   *
+   * @returns New PMF with attr field populated in each bin
+   */
+  withAttribution() {
+    for (const [damage, bin] of this.map) {
+      if (damage !== 0 && bin.attr && Object.keys(bin.attr).length > 0) {
+        return this;
+      }
+      if (damage > 0) break;
+    }
+    const newMap = /* @__PURE__ */ new Map();
+    for (const [damage, bin] of this.map) {
+      const attr = {};
+      for (const outcome in bin.count) {
+        const probability = bin.count[outcome];
+        if (probability > 0) {
+          attr[outcome] = damage * probability;
+        }
+      }
+      newMap.set(damage, {
+        p: bin.p,
+        count: { ...bin.count },
+        attr: Object.keys(attr).length > 0 ? attr : void 0
+      });
+    }
+    return new _PMF(
+      newMap,
+      this.epsilon,
+      this.normalized,
+      `${this.identifier}~attr`
+    );
+  }
   /**
    * General-purpose N-way mixture.
    * weights: Array of [weight, PMF].
@@ -2671,6 +2739,9 @@ var RollBuilder = class _RollBuilder {
   alwaysHits() {
     return new AlwaysHitBuilder(this);
   }
+  alwaysCrits() {
+    return new AlwaysCritBuilder(this);
+  }
   copy() {
     return new this.constructor(this.getSubRollConfigs());
   }
@@ -2962,7 +3033,7 @@ var MaxOfRollBuilder = class _MaxOfRollBuilder extends RollBuilder {
           child: sumChild
         };
       }
-    } catch (e) {
+    } catch {
     }
     throw new Error(
       `MaxOfRollBuilder.toAST(): Unsupported innerRoll configuration`
@@ -2997,6 +3068,9 @@ var AlwaysHitBuilder = class _AlwaysHitBuilder extends RollBuilder {
     const newConfig = { critThreshold };
     return new _AlwaysHitBuilder(this, newConfig);
   }
+  alwaysCrits() {
+    return new AlwaysCritBuilder(this, void 0, true);
+  }
   // Legacy expressions
   toExpression() {
     const configs = this.getSubRollConfigs();
@@ -3014,23 +3088,28 @@ var AlwaysHitBuilder = class _AlwaysHitBuilder extends RollBuilder {
     return new _AlwaysHitBuilder(baseCopy, newConfig);
   }
 };
-var AlwaysCritBuilder = class extends RollBuilder {
-  constructor(baseRoll, attackConfig) {
+var AlwaysCritBuilder = class _AlwaysCritBuilder extends RollBuilder {
+  constructor(baseRoll, attackConfig, fromAlwaysHit = false) {
     super(baseRoll.getSubRollConfigs());
     __publicField(this, "attackConfig");
+    __publicField(this, "fromAlwaysHit");
     if (attackConfig) {
       this.attackConfig = { ...attackConfig };
     } else {
       this.attackConfig = { critThreshold: 20 };
     }
+    this.fromAlwaysHit = fromAlwaysHit || baseRoll instanceof AlwaysHitBuilder;
+  }
+  onHit(...args) {
+    const damageRoll = RollBuilder.fromArgs(...args);
+    return new AttackBuilder(this, damageRoll);
   }
   get critThreshold() {
     return this.attackConfig.critThreshold;
   }
-  // TODO - move this to AC Builder… or if we create a DC builder that has critOn, throw an error?
   critOn(critThreshold) {
-    const newConfig = { critThreshold };
-    return new AlwaysHitBuilder(this, newConfig);
+    const newConfig = { critThreshold, ac: this.attackConfig.ac };
+    return new _AlwaysCritBuilder(this, newConfig, this.fromAlwaysHit);
   }
   // Legacy expressions
   toExpression() {
@@ -3045,8 +3124,8 @@ var AlwaysCritBuilder = class extends RollBuilder {
   copy() {
     const baseCopy = new RollBuilder(this.getSubRollConfigs());
     const critThreshold = this.critThreshold;
-    const newConfig = { critThreshold };
-    return new AlwaysHitBuilder(baseCopy, newConfig);
+    const newConfig = { critThreshold, ac: this.attackConfig.ac };
+    return new _AlwaysCritBuilder(baseCopy, newConfig, this.fromAlwaysHit);
   }
 };
 
@@ -3582,9 +3661,9 @@ var AttackBuilder = class _AttackBuilder {
           crit = this.hitEffect?.copy().doubleDice() ?? RollBuilder.fromArgs(0);
         }
         const critThreshold = this.check.critThreshold;
-        if (critThreshold < 15 || critThreshold > 20) {
+        if (critThreshold < 1 || critThreshold > 20) {
           throw new Error(
-            `Invalid crit threshold: ${critThreshold}. Must be between 15 and 20.`
+            `Invalid crit threshold: ${critThreshold}. Must be between 1 and 20.`
           );
         }
         if (critThreshold === 20) {
@@ -3601,13 +3680,34 @@ var AttackBuilder = class _AttackBuilder {
     return `${checkPart} * ${effectPart}`;
   }
   resolveProbabilities(check, eps = 0) {
-    if (check instanceof AlwaysCritBuilder) {
-      return { pSuccess: 1, pHit: 0, pCrit: 1, pMiss: 0 };
-    }
     const rollType = check.rollType;
     const rerollOne = check.baseReroll > 0;
     const critThreshold = check.critThreshold;
     const d202 = d20RollPMF(rollType, rerollOne);
+    if (check instanceof AlwaysCritBuilder) {
+      if (check.fromAlwaysHit) {
+        return { pSuccess: 1, pHit: 0, pCrit: 1, pMiss: 0 };
+      }
+      const ac2 = check.attackConfig.ac ?? 0;
+      const staticMod2 = this.check.modifier;
+      const bonusDicePMFs2 = this.check.getBonusDicePMFs(this.check, eps);
+      const bonusPMF2 = bonusDicePMFs2.length ? PMF.convolveMany(bonusDicePMFs2, eps) : PMF.delta(0, eps);
+      let pcrit2 = 0;
+      let pmiss2 = 0;
+      for (const [r, rec] of d202) {
+        const pr = typeof rec === "number" ? rec : rec.p;
+        if (pr <= 0) continue;
+        if (r === 1) {
+          pmiss2 += pr;
+          continue;
+        }
+        const need = ac2 - staticMod2 - r;
+        const pBonusHit = bonusPMF2.tailProbGE(need);
+        pcrit2 += pr * pBonusHit;
+        pmiss2 += pr * (1 - pBonusHit);
+      }
+      return { pSuccess: pcrit2, pHit: 0, pCrit: pcrit2, pMiss: pmiss2 };
+    }
     if (check instanceof AlwaysHitBuilder) {
       let pCrit = 0;
       for (const [r, rec] of d202) {
@@ -3629,14 +3729,14 @@ var AttackBuilder = class _AttackBuilder {
     for (const [r, rec] of d202) {
       const pr = typeof rec === "number" ? rec : rec.p;
       if (pr <= 0) continue;
-      if (r >= critThreshold) {
-        pcrit += pr;
-        continue;
-      }
       if (r === 1) {
         pmiss += pr;
         continue;
       }
+      if (r >= critThreshold) {
+        pcrit += pr;
+        continue;
+      }
       const need = ac - staticMod - r;
       const pBonusHit = bonusPMF.tailProbGE(need);
       phit += pr * pBonusHit;
@@ -3717,6 +3817,16 @@ var ACBuilder = class _ACBuilder extends RollBuilder {
     };
     return new _ACBuilder(this, this.attackConfig.ac, newConfig);
   }
+  alwaysCrits() {
+    return new AlwaysCritBuilder(
+      this,
+      {
+        critThreshold: this.attackConfig.critThreshold,
+        ac: this.attackConfig.ac
+      },
+      false
+    );
+  }
   // Legacy expressions
   toExpression() {
     const configs = this.getSubRollConfigs();