@yipe/dice 0.2.23 → 0.4.0

package/dist/{pmf-BC1poIqF.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[];
@@ -57,9 +92,20 @@ declare const onPotentCantripOnly: OutcomeType[];
  */
 declare class DiceQuery {
     readonly singles: PMF[];
-    readonly combined: PMF;
+    private readonly _eps;
+    private readonly _combinedProvided;
+    private _combined?;
     private _combinedWithAttr?;
     constructor(singles: PMF | PMF[], combined?: PMF, eps?: number);
+    /**
+     * The combined damage distribution of all single PMFs (their convolution),
+     * normalized to total probability 1.
+     *
+     * Computed lazily on first access and cached. Queries that only need
+     * additive statistics — {@link DiceQuery.mean}, {@link DiceQuery.variance},
+     * {@link DiceQuery.stddev} — never trigger this convolution.
+     */
+    get combined(): PMF;
     private static readonly DEFAULT_OUTCOMES;
     /**
      * Returns a new PMF with damage attribution metadata populated.
@@ -81,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.
      *
@@ -104,6 +165,8 @@ declare class DiceQuery {
      * Used to determine how consistent the damage is.
      */
     stddev(): number;
+    /** Alias of {@link DiceQuery.stddev}, matching {@link PMF.stdev}. */
+    stdev(): number;
     /**
      * Returns the Cumulative Distribution Function.
      */
@@ -148,6 +211,18 @@ declare class DiceQuery {
      */
     max(): number;
     private singleProb;
+    /**
+     * Full count distribution [P(0), P(1), …, P(n)] for "an attack succeeds if it
+     * carries ANY of `labels`", over the n independent singles.
+     *
+     * Each single's per-event success probability is the Poisson-binomial
+     * marginal P(≥1 of labels) from {@link probabilityOf} (i.e. probAtLeastOne),
+     * computed exactly once. The binomial DP then runs once to produce the whole
+     * distribution, so the array-label paths of probExactlyK / probAtLeastK /
+     * probAtMostK can slice or sum from it instead of rebuilding a DiceQuery and
+     * re-running the DP per requested k.
+     */
+    private countDistribution;
     probAtLeastK(labels: OutcomeType | OutcomeType[], k: number): number;
     /**
      * Returns the probability that at least one attack has the specified outcome(s).
@@ -192,7 +267,7 @@ declare class DiceQuery {
      * Array examples:
      * - probExactlyK(['hit', 'crit'], 2) = probability exactly 2 attacks succeed
      * - probExactlyK(['hit', 'crit'], 1) = probability exactly 1 attack succeeds
-     * - probExactlyK(['miss', 'missNone'], 0) = probability no attacks miss
+     * - probExactlyK(['missDamage', 'missNone'], 0) = probability no attacks miss
      *
      * Use cases:
      * - "What's the chance exactly one of my attacks hits?"
@@ -209,7 +284,7 @@ declare class DiceQuery {
      * Single label examples:
      * - probAtMostK('hit', 1) = probability 0 or 1 attacks hit (at most 1)
      * - probAtMostK('crit', 0) = probability no attacks crit
-     * - probAtMostK('miss', 2) = probability at most 2 attacks miss
+     * - probAtMostK('missDamage', 2) = probability at most 2 attacks miss
      *
      * Array examples:
      * - probAtMostK(['hit', 'crit'], 1) = probability at most 1 attack succeeds
@@ -253,7 +328,7 @@ declare class DiceQuery {
      *
      * Array examples:
      * - damageStatsFrom(['hit', 'crit']) = damage range when at least one attack succeeds
-     * - damageStatsFrom(['miss', 'missNone']) = damage range when at least one attack misses
+     * - damageStatsFrom(['missDamage', 'missNone']) = damage range when at least one attack misses
      *
      * Tactical Use Cases:
      * - "Given that I don't completely whiff (99% of turns), what damage should I expect?"
@@ -271,6 +346,12 @@ declare class DiceQuery {
      * This includes mixed scenarios (2 hits + 1 crit, 3 hits + 1 miss, etc.) which
      * occur far more frequently than pure scenarios. For pure scenarios, use combinedDamageStats.
      *
+     * KNOWN LIMITATION (multi-attack, single label): the returned `count` is an
+     * EXPECTED COUNT (E[#label], so > 1 for N≥2 attacks, not a probability), and
+     * `avg` is the size-biased conditional mean E[dmg·#label]/E[#label] rather than
+     * E[dmg | the label occurs]. For a single attack both are the plain
+     * conditional figures. Use {@link probAtLeastOne} for the scenario probability.
+     *
      * @example
      * // High-level tactical planning
      * const successStats = query.damageStatsFrom('hit')
@@ -335,7 +416,8 @@ declare class DiceQuery {
         count: number;
     };
     /**
-     * Returns the probability that a result includes ANY of the specified labels.
+     * Returns the probability that at least one attack carries ANY of the
+     * specified labels (the marginal P(≥1) across the independent attacks).
      *
      * Examples:
      * - `query.probabilityOf('hit')` → 0.88 (probability at least one hit occurs)
@@ -344,6 +426,12 @@ declare class DiceQuery {
      * Use cases:
      * - "What's the chance my resolution includes a success label?"
      * - "How likely am I to get any hits or crits across all attacks?"
+     *
+     * Note: this must NOT be computed by summing `combined` bin probabilities. A
+     * single combined damage total is reachable by many outcome combinations and
+     * a bin can hold several labels at once, so summing `bin.p` over bins that
+     * contain a label over-counts. The correct marginal is the Poisson-binomial
+     * complement over the per-attack probabilities, i.e. {@link probAtLeastOne}.
      */
     probabilityOf(labels: OutcomeType | OutcomeType[]): number;
     /**
@@ -525,6 +613,16 @@ declare class DiceQuery {
      * Snapshot of the distribution in the exact shape the UI consumes.
      * - outcome probabilities are "at least one" (and equal to "all" for a single PMF)
      * - damageRange is conditional on the outcome occurring
+     *
+     * The outcome probabilities use the correct Poisson-binomial marginals
+     * (`atLeastOneProbability` = P(≥1 attack has it), `allProbability` = P(all do)),
+     * so they are always valid probabilities in [0,1].
+     *
+     * KNOWN LIMITATION (multi-attack): `damageRange.avg` is still aggregated from
+     * the combined PMF's `count`, which the convolution accumulates as an EXPECTED
+     * COUNT, so for N≥2 attacks it is the size-biased mean E[dmg·#label]/E[#label]
+     * rather than a clean conditional expectation. It is correct for a single
+     * attack.
      */
     snapshot(order?: readonly OutcomeType[]): Snapshot;
     /**
@@ -629,7 +727,7 @@ declare class DiceQuery {
      *
      * Returns tuple: [pFirstNonSubset, pFirstSubset, pAnySuccess, pNone]
      */
-    firstSuccessSplit(successOutcome: string | string[], subsetOutcome: string | string[], eps?: number): readonly [pSuccess: number, pSubset: number, pAny: number, pNone: number];
+    firstSuccessSplit(successOutcome: OutcomeType | OutcomeType[], subsetOutcome: OutcomeType | OutcomeType[], eps?: number): readonly [pSuccess: number, pSubset: number, pAny: number, pNone: number];
 }
 type OutcomeSnapshot = {
     atLeastOneProbability: number;
@@ -669,10 +767,21 @@ declare class PMF {
     private _mean?;
     private _variance?;
     private _stdev?;
+    private _fingerprint?;
     constructor(map?: Map<number, Bin>, epsilon?: number, normalized?: boolean, identifier?: string, _preservedProvenance?: boolean);
     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;
@@ -726,7 +835,7 @@ declare class PMF {
      * @param fallback PMF to apply when this PMF is *not* selected.
      * @returns A new PMF representing the weighted mixture of this PMF and the fallback.
      */
-    gate(p: number, zero: PMF): PMF;
+    gate(p: number, fallback: PMF): PMF;
     /**
      * PMF.exclusive()
      *
@@ -773,6 +882,13 @@ declare class PMF {
      *
      * @returns New PMF with attr field populated in each bin
      */
+    /**
+     * Returns true if this PMF already carries damage attribution metadata.
+     *
+     * Only the first positive-damage bin is inspected (parser-generated PMFs
+     * populate `attr` uniformly), so this is O(1) in practice.
+     */
+    hasAttribution(): boolean;
     withAttribution(): PMF;
     /**
      * General-purpose N-way mixture.
@@ -827,6 +943,10 @@ declare class PMF {
      * Returns the standard deviation of the damage distribution.
      */
     stdev(): number;
+    /** Deep-copies a Bin, cloning its count and (optional) attr maps. */
+    private static cloneBin;
+    /** Returns a new Bin with p, count, and attr all multiplied by `factor`. */
+    private static scaleBin;
     private static mergeInto;
     add(other: PMF): PMF;
     /**
@@ -837,10 +957,38 @@ 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;
     private getPMFCombineCacheKey;
+    /**
+     * A small content fingerprint (mass + bin count + face sum) so convolution
+     * cache keys change if the underlying numbers do. Memoized because a PMF is
+     * immutable once constructed — this avoids re-summing every key on each
+     * convolve() call (including cache hits).
+     */
+    fingerprint(): string;
     convolve(other: PMF, eps?: number, raw?: boolean): PMF;
     combineRaw(other: PMF, eps?: number): PMF;
     private static reduceConvolveLeft;
@@ -855,7 +1003,20 @@ declare class PMF {
      * - Order-independent cache keys work better with consistent build patterns
      */
     static convolveMany(pmfList: PMF[], eps?: number): PMF;
-    toJSON(): string;
+    /**
+     * Returns a plain, JSON-serializable representation of this PMF.
+     *
+     * Follows the standard `toJSON` contract, so `JSON.stringify(pmf)` produces
+     * the expected output (no double-encoding). Use {@link PMF.fromJSON} to
+     * reconstruct, or {@link PMF.toJSONString} if you need the string directly.
+     */
+    toJSON(): {
+        bins: Array<[number, Bin]>;
+        normalized: boolean;
+        identifier: string;
+    };
+    /** Serializes this PMF to a JSON string (equivalent to `JSON.stringify(pmf)`). */
+    toJSONString(): string;
     static fromJSON(jsonData: {
         bins: Array<[number, Bin]>;
         normalized?: boolean;
@@ -868,9 +1029,27 @@ declare class PMF {
      * Returns a new, non-normalized PMF.
      */
     prune(epsRel: number, minBins?: number): PMF;
-    /** NEW - REVIEW IF THESE ARE USEFUL OR DUPLCIATIVE?  */
     /** 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.
      */
@@ -895,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;
     /**
@@ -932,4 +1126,4 @@ declare class PMF {
     query(): DiceQuery;
 }
 
-export { type Bin as B, type CritConfig as C, type DamageDistribution as D, EPS as E, LRUCache as L, type OutcomeLabelMap as O, PMF as P, type Rounding as R, type Snapshot as S, type OutcomeType as a, onCritOnly as b, onHitOnly as c, onMissOnly as d, onMissDamageOnly as e, onSaveHalfOnly as f, onSaveFailOnly as g, onPotentCantripOnly as h, DiceQuery as i, type OutcomeSnapshot 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.2.23",
+  "version": "0.4.0",
   "description": "A high-performance dice probability engine for D&D 5e DPR calculations. Powers dprcalc.com.",
   "keywords": [
     "dnd",
@@ -62,6 +62,7 @@
     "./dist/builder/dc.js"
   ],
   "scripts": {
+    "format": "eslint . --fix",
     "lint": "eslint .",
     "typecheck": "tsc -p config/tsconfig.build.json --noEmit",
     "build": "tsup --config config/tsup.config.ts",
@@ -79,17 +80,14 @@
     "node": ">=18.17"
   },
   "devDependencies": {
-    "@types/node": "^24.3.1",
-    "@typescript-eslint/eslint-plugin": "^8.43.0",
-    "@typescript-eslint/parser": "^8.43.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^9.35.0",
-    "eslint-plugin-import": "^2.32.0",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
-    "tsup": "^8.5.0",
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "@types/node": "^26.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.62.0",
+    "@typescript-eslint/parser": "^8.62.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "eslint": "^10.6.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
   }
-}
+}