@yipe/dice 0.3.0 → 0.5.0

package/dist/{pmf-DqUCnYN9.d.cts → pmf-D5VRghZI.d.cts}

@@ -36,6 +36,41 @@ type DamageDistribution = Record<number, number>;
 /** Canonical outcome labels supported by the query helpers. */
 type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "saveFail" | "pc";
 type Rounding = "none" | "floor" | "round" | "ceil";
+/** How a d20 attack roll resolves: single die, keep-highest of 2/3, or keep-lowest of 2. */
+type RollType = "flat" | "advantage" | "disadvantage" | "elven accuracy";
+/**
+ * P(critical hit) for the given crit window and d20 {@link RollType}.
+ *
+ * `critRange` is the number of top faces that crit (1 for a natural 20, 2 for
+ * 19–20, …), so a single die crits with probability `critRange / 20`. Advantage
+ * rolls two d20s / elven accuracy three, keeping the best; disadvantage keeps
+ * the worst of two.
+ */
+declare function critProbability(critRange: number, rollType?: RollType): number;
+/**
+ * The canonical "clean miss" outcome — a point of zero damage with no rider.
+ * This is the {@link OutcomeType} that attribution charts and outcome stats key
+ * on, and is distinct from the builder's attack-resolution `miss` weight label.
+ */
+declare const MISS_NONE_OUTCOME: OutcomeType;
+/**
+ * All outcome types in canonical severity order — clean miss → crit. This is
+ * also the natural stacking order for attribution charts (least- to
+ * most-impactful, bottom → top). Enumerates every {@link OutcomeType} exactly
+ * once; use it instead of hand-maintained per-consumer outcome tables.
+ */
+declare const ALL_OUTCOME_TYPES: OutcomeType[];
+/**
+ * Outcome types in display order for stats / breakdown rows — most prominent
+ * first (crit, hit, …) down to the clean miss.
+ */
+declare const OUTCOME_DISPLAY_ORDER: OutcomeType[];
+/**
+ * Sort outcome labels by a canonical order (defaults to {@link ALL_OUTCOME_TYPES}).
+ * Labels not present in `order` sort after known ones, alphabetically — so
+ * ad-hoc/test labels outside the {@link OutcomeType} union stay stable.
+ */
+declare function sortOutcomes<T extends string>(outcomes: Iterable<T>, order?: readonly string[]): T[];
 declare const onAnyHit: OutcomeType[];
 declare const onCritOnly: OutcomeType[];
 declare const onHitOnly: OutcomeType[];
@@ -92,6 +127,21 @@ declare class DiceQuery {
      * // Now pmf can be used with toDamageAttributionChartSeries()
      */
     combinedWithAttribution(): PMF;
+    /**
+     * 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(): Map<string, Map<number, number>>;
+    /**
+     * 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: string): number;
     /**
      * Returns the expected damage across all possible outcomes.
      *
@@ -722,6 +772,16 @@ declare class PMF {
     static empty(epsilon?: number, identifier?: string): PMF;
     static zero(epsilon?: number): PMF;
     static delta(value: number, epsilon?: number): PMF;
+    /**
+     * 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?: number): PMF;
     static emptyMass(): PMF;
     [Symbol.iterator](): IterableIterator<[number, Bin]>;
     static clearCache(): void;
@@ -897,6 +957,27 @@ declare class PMF {
      * Example: `pmf.addScaled(critBranch, 0.05)` → PMF including 5% crit outcomes
      */
     addScaled(branch: PMF, probability: number): PMF;
+    /**
+     * 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: number): PMF;
     scaleMass(factor: number): PMF;
     mapDamage(damageTransformFunction: (damageValue: number) => number): PMF;
     scaleDamage(factor: number, rounding?: "floor" | "round" | "ceil"): PMF;
@@ -950,6 +1031,25 @@ declare class PMF {
     prune(epsRel: number, minBins?: number): PMF;
     /** Probability mass at exactly x. */
     pAt(x: number): number;
+    /**
+     * 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(): number;
+    /** P(no damage) — the mass at damage 0. The dual of {@link hitProbability}. */
+    missProbability(): number;
+    /**
+     * 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: number): PMF;
     /** Dense integer support from min..max (inclusive).
      * Useful for showing empty bars in charts.
      */
@@ -974,6 +1074,21 @@ declare class PMF {
     } | null;
     /** Check if outcome exists in this PMF. */
     hasOutcome(outcome: string): boolean;
+    /**
+     * 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(): Map<string, Map<number, number>>;
     tailProbGE(t: number): number;
     tailProbGT(t: number): number;
     /**
@@ -1011,4 +1126,4 @@ declare class PMF {
     query(): DiceQuery;
 }
 
-export { type Bin as B, type CritConfig as C, DiceQuery as D, EPS as E, LRUCache as L, type OutcomeLabelMap as O, PMF as P, type Rounding as R, type Snapshot as S, type DamageDistribution as a, type OutcomeSnapshot as b, type OutcomeType as c, onCritOnly as d, onHitOnly as e, onMissDamageOnly as f, onMissOnly as g, onPotentCantripOnly as h, onSaveFailOnly as i, onSaveHalfOnly as j, onAnyHit as o, pmfCache as p };
+export { ALL_OUTCOME_TYPES as A, type Bin as B, type CritConfig as C, type DamageDistribution as D, EPS as E, LRUCache as L, MISS_NONE_OUTCOME as M, type OutcomeLabelMap as O, PMF as P, type Rounding as R, type Snapshot as S, type OutcomeType as a, type RollType as b, critProbability as c, OUTCOME_DISPLAY_ORDER as d, onCritOnly as e, onHitOnly as f, onMissOnly as g, onMissDamageOnly as h, onSaveHalfOnly as i, onSaveFailOnly as j, onPotentCantripOnly as k, DiceQuery as l, type OutcomeSnapshot as m, onAnyHit as o, pmfCache as p, sortOutcomes as s };

package/dist/{pmf-DqUCnYN9.d.ts → pmf-D5VRghZI.d.ts}

@@ -36,6 +36,41 @@ type DamageDistribution = Record<number, number>;
 /** Canonical outcome labels supported by the query helpers. */
 type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "saveFail" | "pc";
 type Rounding = "none" | "floor" | "round" | "ceil";
+/** How a d20 attack roll resolves: single die, keep-highest of 2/3, or keep-lowest of 2. */
+type RollType = "flat" | "advantage" | "disadvantage" | "elven accuracy";
+/**
+ * P(critical hit) for the given crit window and d20 {@link RollType}.
+ *
+ * `critRange` is the number of top faces that crit (1 for a natural 20, 2 for
+ * 19–20, …), so a single die crits with probability `critRange / 20`. Advantage
+ * rolls two d20s / elven accuracy three, keeping the best; disadvantage keeps
+ * the worst of two.
+ */
+declare function critProbability(critRange: number, rollType?: RollType): number;
+/**
+ * The canonical "clean miss" outcome — a point of zero damage with no rider.
+ * This is the {@link OutcomeType} that attribution charts and outcome stats key
+ * on, and is distinct from the builder's attack-resolution `miss` weight label.
+ */
+declare const MISS_NONE_OUTCOME: OutcomeType;
+/**
+ * All outcome types in canonical severity order — clean miss → crit. This is
+ * also the natural stacking order for attribution charts (least- to
+ * most-impactful, bottom → top). Enumerates every {@link OutcomeType} exactly
+ * once; use it instead of hand-maintained per-consumer outcome tables.
+ */
+declare const ALL_OUTCOME_TYPES: OutcomeType[];
+/**
+ * Outcome types in display order for stats / breakdown rows — most prominent
+ * first (crit, hit, …) down to the clean miss.
+ */
+declare const OUTCOME_DISPLAY_ORDER: OutcomeType[];
+/**
+ * Sort outcome labels by a canonical order (defaults to {@link ALL_OUTCOME_TYPES}).
+ * Labels not present in `order` sort after known ones, alphabetically — so
+ * ad-hoc/test labels outside the {@link OutcomeType} union stay stable.
+ */
+declare function sortOutcomes<T extends string>(outcomes: Iterable<T>, order?: readonly string[]): T[];
 declare const onAnyHit: OutcomeType[];
 declare const onCritOnly: OutcomeType[];
 declare const onHitOnly: OutcomeType[];
@@ -92,6 +127,21 @@ declare class DiceQuery {
      * // Now pmf can be used with toDamageAttributionChartSeries()
      */
     combinedWithAttribution(): PMF;
+    /**
+     * 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(): Map<string, Map<number, number>>;
+    /**
+     * 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: string): number;
     /**
      * Returns the expected damage across all possible outcomes.
      *
@@ -722,6 +772,16 @@ declare class PMF {
     static empty(epsilon?: number, identifier?: string): PMF;
     static zero(epsilon?: number): PMF;
     static delta(value: number, epsilon?: number): PMF;
+    /**
+     * 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?: number): PMF;
     static emptyMass(): PMF;
     [Symbol.iterator](): IterableIterator<[number, Bin]>;
     static clearCache(): void;
@@ -897,6 +957,27 @@ declare class PMF {
      * Example: `pmf.addScaled(critBranch, 0.05)` → PMF including 5% crit outcomes
      */
     addScaled(branch: PMF, probability: number): PMF;
+    /**
+     * 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: number): PMF;
     scaleMass(factor: number): PMF;
     mapDamage(damageTransformFunction: (damageValue: number) => number): PMF;
     scaleDamage(factor: number, rounding?: "floor" | "round" | "ceil"): PMF;
@@ -950,6 +1031,25 @@ declare class PMF {
     prune(epsRel: number, minBins?: number): PMF;
     /** Probability mass at exactly x. */
     pAt(x: number): number;
+    /**
+     * 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(): number;
+    /** P(no damage) — the mass at damage 0. The dual of {@link hitProbability}. */
+    missProbability(): number;
+    /**
+     * 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: number): PMF;
     /** Dense integer support from min..max (inclusive).
      * Useful for showing empty bars in charts.
      */
@@ -974,6 +1074,21 @@ declare class PMF {
     } | null;
     /** Check if outcome exists in this PMF. */
     hasOutcome(outcome: string): boolean;
+    /**
+     * 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(): Map<string, Map<number, number>>;
     tailProbGE(t: number): number;
     tailProbGT(t: number): number;
     /**
@@ -1011,4 +1126,4 @@ declare class PMF {
     query(): DiceQuery;
 }
 
-export { type Bin as B, type CritConfig as C, DiceQuery as D, EPS as E, LRUCache as L, type OutcomeLabelMap as O, PMF as P, type Rounding as R, type Snapshot as S, type DamageDistribution as a, type OutcomeSnapshot as b, type OutcomeType as c, onCritOnly as d, onHitOnly as e, onMissDamageOnly as f, onMissOnly as g, onPotentCantripOnly as h, onSaveFailOnly as i, onSaveHalfOnly as j, onAnyHit as o, pmfCache as p };
+export { ALL_OUTCOME_TYPES as A, type Bin as B, type CritConfig as C, type DamageDistribution as D, EPS as E, LRUCache as L, MISS_NONE_OUTCOME as M, type OutcomeLabelMap as O, PMF as P, type Rounding as R, type Snapshot as S, type OutcomeType as a, type RollType as b, critProbability as c, OUTCOME_DISPLAY_ORDER as d, onCritOnly as e, onHitOnly as f, onMissOnly as g, onMissDamageOnly as h, onSaveHalfOnly as i, onSaveFailOnly as j, onPotentCantripOnly as k, DiceQuery as l, type OutcomeSnapshot as m, onAnyHit as o, pmfCache as p, sortOutcomes as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yipe/dice",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A high-performance dice probability engine for D&D 5e DPR calculations. Powers dprcalc.com.",
   "keywords": [
     "dnd",
@@ -90,4 +90,4 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   }
-}
+}