@yipe/dice 0.10.0 → 0.11.0

package/dist/builder/index.cjs

@@ -1788,6 +1788,30 @@ var _PMF = class _PMF {
       `freq(${this.identifier},${freq})`
     );
   }
+  /**
+   * Splits this PMF into two complementary PMFs by an arbitrary per-damage-value factor in
+   * `[0, 1]` — bin `d`'s mass, `count`, and `attr` split `factor(d)` / `1 - factor(d)` between the
+   * two results (via the same proportional scaling {@link applyHitFrequency} uses, `scaleBin`), so
+   * `a.add(b)` recovers this PMF exactly and both halves stay chart-attributable. Unlike
+   * {@link applyHitFrequency}, mass is NOT redistributed to a miss bin at 0 — each bin stays at its
+   * own damage value in whichever half it lands in. `factor` outside `[0, 1]` is clamped.
+   *
+   * Built for `dice-match` trigger slicing: splitting a hit/crit sub-PMF into "matched" and
+   * "did not match" halves by the exact per-damage-value match probability.
+   */
+  splitByFactor(factor) {
+    const a = /* @__PURE__ */ new Map();
+    const b = /* @__PURE__ */ new Map();
+    for (const [damage, bin] of this.map) {
+      const f = Math.min(1, Math.max(0, factor(damage)));
+      if (f > 0) a.set(damage, _PMF.scaleBin(bin, f));
+      if (f < 1) b.set(damage, _PMF.scaleBin(bin, 1 - f));
+    }
+    return [
+      new _PMF(a, this.epsilon, false, `split+(${this.identifier})`),
+      new _PMF(b, this.epsilon, false, `split-(${this.identifier})`)
+    ];
+  }
   scaleMass(factor) {
     if (factor === 1) return this;
     const scaledMap = /* @__PURE__ */ new Map();
@@ -2474,6 +2498,84 @@ var _PMF = class _PMF {
 _PMF.__anonIdCounter = 1;
 var PMF = _PMF;
 
+// src/common/bounce.ts
+function faceWeights(faces, minimum = 0, reroll = 0) {
+  const f = Math.max(0, Math.floor(faces));
+  if (f <= 0) return [];
+  let weights = new Array(f).fill(1 / f);
+  const r = Math.max(0, Math.min(Math.floor(reroll), f));
+  if (r > 0) {
+    const rerollMass = r / f;
+    const uniformReroll = rerollMass / f;
+    weights = weights.map((_, i) => (i < r ? 0 : 1 / f) + uniformReroll);
+  }
+  const minV = Math.max(0, Math.floor(minimum));
+  if (minV > 1) {
+    const collapsed = new Array(f).fill(0);
+    for (let v = 1; v <= f; v++) {
+      const target = Math.min(f, Math.max(v, minV));
+      collapsed[target - 1] += weights[v - 1];
+    }
+    weights = collapsed;
+  }
+  return weights;
+}
+function diceSumDistribution(dice, weights) {
+  let dist = /* @__PURE__ */ new Map([[0, 1]]);
+  for (let die = 0; die < dice; die++) {
+    const next = /* @__PURE__ */ new Map();
+    for (const [sum, mass] of dist) {
+      for (let face = 1; face <= weights.length; face++) {
+        const w = weights[face - 1] ?? 0;
+        if (w <= 0) continue;
+        const s = sum + face;
+        next.set(s, (next.get(s) ?? 0) + mass * w);
+      }
+    }
+    dist = next;
+  }
+  return dist;
+}
+function sumAllDistinctDistribution(dice, weights) {
+  const faceCount = weights.length;
+  let dp = /* @__PURE__ */ new Map([[0, /* @__PURE__ */ new Map([[0, 1]])]]);
+  for (let face = 1; face <= faceCount; face++) {
+    const w = weights[face - 1] ?? 0;
+    const next = /* @__PURE__ */ new Map();
+    for (const [count, sumMap] of dp) next.set(count, new Map(sumMap));
+    if (w > 0) {
+      for (const [count, sumMap] of dp) {
+        const nextCount = count + 1;
+        if (nextCount > dice) continue;
+        const target = next.get(nextCount) ?? /* @__PURE__ */ new Map();
+        for (const [sum, mass] of sumMap) {
+          const s = sum + face;
+          target.set(s, (target.get(s) ?? 0) + mass * w);
+        }
+        next.set(nextCount, target);
+      }
+    }
+    dp = next;
+  }
+  let factorial = 1;
+  for (let i = 2; i <= dice; i++) factorial *= i;
+  const chosen = dp.get(dice) ?? /* @__PURE__ */ new Map();
+  const result = /* @__PURE__ */ new Map();
+  for (const [sum, mass] of chosen) result.set(sum, mass * factorial);
+  return result;
+}
+function jointSumAndMatch(dice, weights) {
+  if (dice <= 1) return /* @__PURE__ */ new Map();
+  const total = diceSumDistribution(dice, weights);
+  const distinct = sumAllDistinctDistribution(dice, weights);
+  const result = /* @__PURE__ */ new Map();
+  for (const [sum, mass] of total) {
+    const matchMass = Math.max(0, mass - (distinct.get(sum) ?? 0));
+    if (matchMass > 0) result.set(sum, matchMass);
+  }
+  return result;
+}
+
 // src/pmf/mixture.ts
 var Mixture = class _Mixture {
   constructor(eps = EPS) {
@@ -3572,16 +3674,17 @@ var defaultConfig = {
   modifier: 0,
   reroll: 0,
   explode: 0,
+  explodePoolBudget: 0,
   minimum: 0,
   bestOf: 0,
   keep: void 0,
   rollType: "flat"
 };
 var rollConfigsEqual = (a, b) => {
-  return a.count === b.count && a.sides === b.sides && a.modifier === b.modifier && a.reroll === b.reroll && a.explode === b.explode && a.minimum === b.minimum && a.bestOf === b.bestOf && a.keep === b.keep && a.rollType === b.rollType;
+  return a.count === b.count && a.sides === b.sides && a.modifier === b.modifier && a.reroll === b.reroll && a.explode === b.explode && a.explodePoolBudget === b.explodePoolBudget && a.minimum === b.minimum && a.bestOf === b.bestOf && a.keep === b.keep && a.rollType === b.rollType;
 };
 var configComplexityScore = (config) => {
-  return (config.reroll > 0 ? 1 : 0) + (config.explode > 0 ? 1 : 0) + (config.minimum > 0 ? 1 : 0) + (config.bestOf > 0 ? 1 : 0) + (config.keep !== void 0 ? 1 : 0) + (config.rollType !== "flat" ? 1 : 0);
+  return (config.reroll > 0 ? 1 : 0) + (config.explode > 0 ? 1 : 0) + (config.explodePoolBudget > 0 ? 1 : 0) + (config.minimum > 0 ? 1 : 0) + (config.bestOf > 0 ? 1 : 0) + (config.keep !== void 0 ? 1 : 0) + (config.rollType !== "flat" ? 1 : 0);
 };
 var RollBuilder = class _RollBuilder {
   constructor(countOrConfigs = 1) {
@@ -3763,10 +3866,35 @@ var RollBuilder = class _RollBuilder {
     if (count === void 0) return this;
     if (count === 0) return this;
     if (count < 0) throw new Error("Explode count must be >= 0");
+    if (this.lastConfig.explodePoolBudget > 0) {
+      throw new Error(
+        "Cannot set explode() on a config that already has a pool-wide explodePool() budget \u2014 the two exploding-dice semantics (per-die vs pool-wide) are mutually exclusive on one config."
+      );
+    }
     const newConfigs = this.getSubRollConfigs();
     newConfigs[newConfigs.length - 1].explode = count;
     return this.create(newConfigs);
   }
+  /**
+   * Set a pool-wide exploding-dice budget: at most `budget` extra dice may be added across the
+   * WHOLE pool (shared), as opposed to {@link explode}'s per-die cap (`n` dice each individually
+   * allowed up to `explode(k)` extra dice). `budget` must be a finite non-negative integer —
+   * unlike `explode()`, `Infinity` is not accepted (it would make the pool-wide DP non-terminating).
+   */
+  explodePool(budget) {
+    if (isNaN(budget)) throw new Error("Invalid NaN value for explodePool budget");
+    if (!Number.isFinite(budget)) throw new Error("explodePool budget must be finite");
+    if (budget < 0) throw new Error("explodePool budget must be >= 0");
+    if (budget === 0) return this;
+    if (this.lastConfig.explode > 0) {
+      throw new Error(
+        "Cannot set explodePool() on a config that already has a per-die explode() cap \u2014 the two exploding-dice semantics (per-die vs pool-wide) are mutually exclusive on one config."
+      );
+    }
+    const newConfigs = this.getSubRollConfigs();
+    newConfigs[newConfigs.length - 1].explodePoolBudget = Math.floor(budget);
+    return this.create(newConfigs);
+  }
   /** Apply per-die minimum value (floors each die roll at `val`, e.g. `minimum(3)` treats a 1 or
    * 2 as a 3 -- the 2024 Great Weapon Fighting style). */
   minimum(val) {
@@ -4005,6 +4133,11 @@ var RollBuilder = class _RollBuilder {
         `toExpression() cannot represent an exploding die (d${config.sides} explode(${config.explode})): the string grammar has no explode syntax. Use the builder's own PMF (.toPMF()/.pmf) instead of round-tripping through toExpression()/parse().`
       );
     }
+    if (config.explodePoolBudget && config.explodePoolBudget > 0) {
+      throw new Error(
+        `toExpression() cannot represent a pool-wide exploding-dice budget (d${config.sides} explodePool(${config.explodePoolBudget})): the string grammar has no explode syntax. Use the builder's own PMF (.toPMF()/.pmf) instead of round-tripping through toExpression()/parse().`
+      );
+    }
     let baseDie = `d${config.sides}`;
     const rerollClause = config.reroll > 0 ? config.reroll === 1 ? " reroll 1" : ` reroll d${config.reroll}` : "";
     if (config.reroll > 0) {
@@ -4503,6 +4636,9 @@ var PooledRollBuilder = class _PooledRollBuilder extends RollBuilder {
   explode(_count = Infinity) {
     throw new Error("Cannot set explode on a pooled roll.");
   }
+  explodePool(_budget) {
+    throw new Error("Cannot set explodePool on a pooled roll.");
+  }
   minimum(_val) {
     throw new Error("Cannot set minimum on a pooled roll.");
   }
@@ -4752,6 +4888,11 @@ function astFromRollConfigs(configs) {
       appliedRollType = true;
     }
     if (cfg.rollType === "flat" && effectiveKeep && effectiveKeep.total > 0) {
+      if (cfg.explodePoolBudget > 0) {
+        throw new Error(
+          "explodePool() cannot be combined with keep()/bestOf() on the same config \u2014 the match/keep pool is ambiguous once dice can be added mid-resolution. Use explodePool() on a plain (non-keep) pool."
+        );
+      }
       const baseCount = Math.max(1, Math.floor(Math.abs(count || 1)));
       const trials = Math.max(1, Math.floor(effectiveKeep.total));
       const k = Math.max(0, Math.floor(effectiveKeep.count));
@@ -4802,7 +4943,17 @@ function astFromRollConfigs(configs) {
       }
     } else {
       const c = appliedRollType ? 1 : Math.max(1, count || 1);
-      node = { type: "sum", count: c, child: node };
+      if (cfg.explodePoolBudget > 0 && appliedRollType) {
+        throw new Error(
+          "explodePool() cannot be combined with advantage/disadvantage/elven-accuracy on the same config \u2014 pool-wide explosion is for damage dice pools, not d20 rolls."
+        );
+      }
+      node = {
+        type: "sum",
+        count: c,
+        child: node,
+        explodePoolBudget: cfg.explodePoolBudget > 0 ? cfg.explodePoolBudget : void 0
+      };
     }
     children.push({ node, sign });
   }
@@ -4833,6 +4984,13 @@ function resolve(node, eps = defaultEps) {
         const base = resolve(node.child, eps);
         const n = Math.max(0, Math.floor(node.count));
         if (n === 0) return PMF.delta(0, eps);
+        if (node.explodePoolBudget && Number.isFinite(node.explodePoolBudget) && node.explodePoolBudget > 0) {
+          const die = findDie(node.child);
+          if (!die) {
+            throw new Error("explodePool() requires the pool's child to be a plain die.");
+          }
+          return resolveExplodingPool(base, die.sides, n, Math.floor(node.explodePoolBudget), eps);
+        }
         if (n === 1) return base;
         return base.power(n, eps);
       }
@@ -4970,6 +5128,31 @@ function resolveSingleDie(die, eps = defaultEps) {
   singleDiePMFCache.set(cacheKey, pmf);
   return pmf;
 }
+function resolveExplodingPool(diePMF, maxFace, count, budget, eps) {
+  const pMax = diePMF.pAt(maxFace);
+  const nonMax = /* @__PURE__ */ new Map();
+  for (const v of diePMF.support()) {
+    if (v !== maxFace) nonMax.set(v, diePMF.pAt(v));
+  }
+  if (nonMax.size === 0) {
+    return PMF.delta((count + budget) * maxFace, eps);
+  }
+  const nonMaxPMF = PMF.fromMap(nonMax, eps);
+  const memo = /* @__PURE__ */ new Map();
+  const f = (p, b) => {
+    if (p === 0) return PMF.delta(0, eps);
+    if (b === 0) return diePMF.power(p, eps);
+    const key = `${p},${b}`;
+    const cached = memo.get(key);
+    if (cached) return cached;
+    const maxBranch = f(p, b - 1).mapDamage((v) => v + maxFace);
+    const nonMaxBranch = nonMaxPMF.convolve(f(p - 1, b), eps);
+    const result = PMF.branch(maxBranch, nonMaxBranch, pMax);
+    memo.set(key, result);
+    return result;
+  };
+  return f(count, budget);
+}
 function findDie(node) {
   switch (node.type) {
     case "die":
@@ -5154,7 +5337,7 @@ function getASTSignature(node) {
       return `d{${parts.join(",")}}`;
     }
     case "sum":
-      return `sum{c:${node.count},ch:${getASTSignature(node.child)}}`;
+      return `sum{c:${node.count},b:${node.explodePoolBudget || 0},ch:${getASTSignature(node.child)}}`;
     case "d20Roll":
       return `d20{t:${node.rollType},ch:${getASTSignature(node.child)}}`;
     case "keep":
@@ -5375,6 +5558,55 @@ var AttackBuilder = class _AttackBuilder {
       weights: { hit: phit, crit: pcrit, miss: pmiss }
     };
   }
+  /**
+   * For `dice-match` trigger slicing (`turn/types.ts`'s `HasDiceMatchInfo`): the exact
+   * per-damage-value match probability for the hit and crit branches, or `null` per branch when no
+   * descriptor is available — a string-parsed effect, a wrapped transform whose PMF isn't fully
+   * captured by its `RollConfig`s (half/scale/maxOf/pooled — `cacheKey()` returns `null` for
+   * exactly these), a `keep`/`bestOf` pool (ambiguous "the dice" under crit doubling), a
+   * pool-wide exploding budget (composition with match not yet threaded through here), a
+   * multi-die-type pool, a single die (can never match), or (crit) `noCrit()`.
+   *
+   * The crit branch is built from the SAME crit-effect selection `resolve()` uses (an explicit
+   * `onCrit` roll, or the hit dice auto-doubled via `copy().doubleDice()`), so its descriptor
+   * reflects the crit branch's REAL doubled pool, not the hit pool re-used blindly.
+   */
+  diceMatchInfo(_eps = EPS) {
+    const hit = this.matchInfoForEffect(this.hitEffect);
+    let critEffect;
+    if (this.critEffect === null) {
+      critEffect = void 0;
+    } else if (this.critEffect) {
+      critEffect = this.critEffect;
+    } else if (this.hitEffect instanceof ParsedRollBuilder) {
+      critEffect = void 0;
+    } else {
+      critEffect = this.hitEffect?.copy().doubleDice();
+    }
+    const crit = this.matchInfoForEffect(critEffect);
+    return { hit, crit };
+  }
+  matchInfoForEffect(effect) {
+    if (!effect || effect instanceof ParsedRollBuilder) return null;
+    if (effect.cacheKey() === null) return null;
+    const diceConfigs = effect.getSubRollConfigs().filter((c) => c.sides > 0);
+    if (diceConfigs.length !== 1) return null;
+    const config = diceConfigs[0];
+    if (config.keep || config.bestOf > 0) return null;
+    if (config.explodePoolBudget > 0) return null;
+    if (config.count <= 1) return { matchProbabilityByDamage: /* @__PURE__ */ new Map() };
+    const weights = faceWeights(config.sides, config.minimum, config.reroll);
+    const totalDist = diceSumDistribution(config.count, weights);
+    const joint = jointSumAndMatch(config.count, weights);
+    const modifier = effect.modifier;
+    const matchProbabilityByDamage = /* @__PURE__ */ new Map();
+    for (const [sum, totalMass] of totalDist) {
+      if (totalMass <= 0) continue;
+      const matchMass = joint.get(sum) ?? 0;
+      matchProbabilityByDamage.set(sum + modifier, matchMass / totalMass);
+    }
+    return { matchProbabilityByDamage };
+  }
   /**
    * A cheap, complete key for this attack's resolved PMF, or `null` when it can't be cached soundly (an
    * effect whose PMF isn't captured by its {@link RollConfig}s — see {@link RollBuilder.cacheKey}). Composed
@@ -5699,14 +5931,15 @@ var TurnSpecError = class extends Error {
     this.name = "TurnSpecError";
   }
 };
-var MAX_TRIGGER_GROUPS = 4;
+var MAX_TRIGGER_GROUPS = 9;
 
 // src/turn/plan.ts
-var IS_HIT_TRIGGER = {
+var READS_GROUP = {
   "first-hit": true,
   "any-crit": true,
   "any-miss": true,
-  "every-hit": true
+  "every-hit": true,
+  "dice-match": true
 };
 function toPMF(damage, eps, id = "") {
   const parts = Array.isArray(damage) ? damage : [damage];
@@ -5750,20 +5983,49 @@ function critPMF(rider, base, eps) {
   if (doubled.length === 0) return base;
   return PMF.convolveMany(doubled, eps);
 }
-function sliceSource(pmf) {
+function diceMatchInfoOf(source, eps) {
+  const capable = source;
+  if (typeof capable.diceMatchInfo === "function") {
+    return capable.diceMatchInfo(eps);
+  }
+  return { hit: null, crit: null };
+}
+function sliceSource(pmf, matchInfo) {
   const labels = pmf.outcomes();
   if (!labels.includes("hit") && !labels.includes("crit")) return null;
   const missParts = ["missNone", "missDamage"].filter((label) => labels.includes(label)).map((label) => pmf.filterOutcome(label));
-  return {
-    hit: labels.includes("hit") ? pmf.filterOutcome("hit") : PMF.emptyMass(),
-    crit: labels.includes("crit") ? pmf.filterOutcome("crit") : PMF.emptyMass(),
-    miss: missParts.length ? missParts.reduce((all, part) => all.add(part)) : PMF.emptyMass()
-  };
+  const hit = labels.includes("hit") ? pmf.filterOutcome("hit") : PMF.emptyMass();
+  const crit = labels.includes("crit") ? pmf.filterOutcome("crit") : PMF.emptyMass();
+  const miss = missParts.length ? missParts.reduce((all, part) => all.add(part)) : PMF.emptyMass();
+  let hitMatch = null;
+  let hitNoMatch = null;
+  let critMatch = null;
+  let critNoMatch = null;
+  if (matchInfo?.hit) {
+    const info = matchInfo.hit;
+    const [m, nm] = hit.splitByFactor((d2) => info.matchProbabilityByDamage.get(d2) ?? 0);
+    hitMatch = m;
+    hitNoMatch = nm;
+  }
+  if (matchInfo?.crit) {
+    const info = matchInfo.crit;
+    const [m, nm] = crit.splitByFactor((d2) => info.matchProbabilityByDamage.get(d2) ?? 0);
+    critMatch = m;
+    critNoMatch = nm;
+  }
+  return { hit, crit, miss, hitMatch, hitNoMatch, critMatch, critNoMatch };
 }
 function buildPlan(spec, eps = EPS) {
   const fail = (code, id, message) => {
     throw new TurnSpecError(code, id, message);
   };
+  const riders = spec.riders ?? [];
+  const matchNeededSourceIds = /* @__PURE__ */ new Set();
+  for (const rider of riders) {
+    if (rider.on === "dice-match") {
+      for (const sourceId of rider.of) matchNeededSourceIds.add(sourceId);
+    }
+  }
   const attackIds = [];
   const attackPMFs = [];
   const attackSlices = [];
@@ -5773,11 +6035,11 @@ function buildPlan(spec, eps = EPS) {
     const id = hasWrapper ? named.id : `attack ${index + 1}`;
     const source = hasWrapper ? named.source : entry;
     const pmf = toPMF(source, eps, id);
+    const matchInfo = matchNeededSourceIds.has(id) ? diceMatchInfoOf(source, eps) : null;
     attackIds.push(id);
     attackPMFs.push(pmf);
-    attackSlices.push(sliceSource(pmf));
+    attackSlices.push(sliceSource(pmf, matchInfo));
   });
-  const riders = spec.riders ?? [];
   const riderIds = riders.map((rider, index) => rider.id ?? `rider ${index + 1}`);
   const seen = /* @__PURE__ */ new Set();
   for (const id of [...attackIds, ...riderIds]) {
@@ -5786,6 +6048,17 @@ function buildPlan(spec, eps = EPS) {
   }
   const attackIndexById = new Map(attackIds.map((id, index) => [id, index]));
   const riderIndexById = new Map(riderIds.map((id, index) => [id, index]));
+  const checkMatchable = (riderId, sourceId, slices) => {
+    const missingHit = slices.hit.mass() > 0 && slices.hitMatch === null;
+    const missingCrit = slices.crit.mass() > 0 && slices.critMatch === null;
+    if (missingHit || missingCrit) {
+      fail(
+        "no-dice-descriptor",
+        sourceId,
+        `Rider "${riderId}" reads "${sourceId}" for "dice-match", but "${sourceId}" has no dice descriptor to match against \u2014 a bare PMF, a string-parsed expression, or a keep()/bestOf() pool (ambiguous "the dice" under crit doubling) cannot be matched.`
+      );
+    }
+  };
   const sourceIdsByRider = riders.map((rider, index) => {
     const id = riderIds[index];
     if (rider.on === "not-fired") {
@@ -5810,7 +6083,7 @@ function buildPlan(spec, eps = EPS) {
       }
       return [target];
     }
-    const of = [...new Set(rider.of ?? attackIds)];
+    const of = [...new Set(rider.on === "dice-match" ? rider.of : rider.of ?? attackIds)];
     if (of.length === 0) {
       fail("unknown-id", id, `Rider "${id}" has no sources.`);
     }
@@ -5834,8 +6107,11 @@ function buildPlan(spec, eps = EPS) {
           `Rider "${id}" triggers on "${sourceId}", an every-hit rider. Those are folded into their own sources rather than resolved separately, so they cannot be triggered on \u2014 point at the attacks instead.`
         );
       }
+      const damageSource = isAttack ? void 0 : riders[riderIndex].damage;
+      const singleDamageSource = damageSource !== void 0 && !Array.isArray(damageSource) ? damageSource : void 0;
       const slices = isAttack ? attackSlices[attackIndexById.get(sourceId)] : sliceSource(
-        toPMF(riders[riderIndex].damage, eps, sourceId)
+        toPMF(damageSource, eps, sourceId),
+        matchNeededSourceIds.has(sourceId) && singleDamageSource !== void 0 ? diceMatchInfoOf(singleDamageSource, eps) : null
       );
       if (!slices) {
         fail(
@@ -5843,6 +6119,8 @@ function buildPlan(spec, eps = EPS) {
           sourceId,
           `Rider "${id}" triggers on "${sourceId}", which has no hit/crit outcomes.`
         );
+      } else if (rider.on === "dice-match") {
+        checkMatchable(id, sourceId, slices);
       }
     }
     return [...of];
@@ -5888,7 +6166,7 @@ function buildPlan(spec, eps = EPS) {
   const perHitGroups = /* @__PURE__ */ new Map();
   for (const index of order) {
     const rider = riders[index];
-    if (!IS_HIT_TRIGGER[rider.on]) continue;
+    if (!READS_GROUP[rider.on]) continue;
     const group = groupOf(sourceIdsByRider[index]);
     readsByRider.set(index, group);
     if (rider.on === "every-hit") perHitGroups.set(riderIds[index], group);
@@ -5918,21 +6196,34 @@ function buildPlan(spec, eps = EPS) {
     if (!payloads) return slices;
     let hit = slices.hit;
     let crit = slices.crit;
+    let hitMatch = slices.hitMatch;
+    let hitNoMatch = slices.hitNoMatch;
+    let critMatch = slices.critMatch;
+    let critNoMatch = slices.critNoMatch;
     for (const payload of payloads) {
       hit = hit.convolve(payload.hit, eps, true);
       crit = crit.convolve(payload.crit, eps, true);
+      if (hitMatch) hitMatch = hitMatch.convolve(payload.hit, eps, true);
+      if (hitNoMatch) hitNoMatch = hitNoMatch.convolve(payload.hit, eps, true);
+      if (critMatch) critMatch = critMatch.convolve(payload.crit, eps, true);
+      if (critNoMatch) critNoMatch = critNoMatch.convolve(payload.crit, eps, true);
     }
-    return { hit, crit, miss: slices.miss };
+    return { hit, crit, miss: slices.miss, hitMatch, hitNoMatch, critMatch, critNoMatch };
+  };
+  const emptySlices = {
+    hit: PMF.emptyMass(),
+    crit: PMF.emptyMass(),
+    miss: PMF.emptyMass(),
+    hitMatch: null,
+    hitNoMatch: null,
+    critMatch: null,
+    critNoMatch: null
   };
   const steps = attackIds.map((id, index) => ({
     id,
     trigger: null,
     slices: withPerHit(
-      attackSlices[index] ?? {
-        hit: attackPMFs[index],
-        crit: PMF.emptyMass(),
-        miss: PMF.emptyMass()
-      },
+      attackSlices[index] ?? { ...emptySlices, hit: attackPMFs[index] },
       id
     ),
     damage: null,
@@ -5947,7 +6238,9 @@ function buildPlan(spec, eps = EPS) {
     if (rider.on === "every-hit") continue;
     const id = riderIds[index];
     const hit = toPMF(rider.damage, eps, id);
-    const slices = sliceSource(hit);
+    const singleRiderDamage = !Array.isArray(rider.damage) ? rider.damage : void 0;
+    const matchInfo = matchNeededSourceIds.has(id) && singleRiderDamage !== void 0 ? diceMatchInfoOf(singleRiderDamage, eps) : null;
+    const slices = sliceSource(hit, matchInfo);
     if (slices && rider.critDamage !== void 0) {
       fail(
         "unused-crit-damage",
@@ -5969,6 +6262,15 @@ function buildPlan(spec, eps = EPS) {
     stepIndexByRider.set(index, steps.length - 1);
     riderSteps.set(id, steps.length - 1);
   }
+  const groupLastReadStep = new Array(groupSources.length).fill(-1);
+  steps.forEach((step, stepIndex) => {
+    if (step.reads !== -1) {
+      groupLastReadStep[step.reads] = Math.max(groupLastReadStep[step.reads], stepIndex);
+    }
+  });
+  for (const group of perHitGroups.values()) {
+    groupLastReadStep[group] = steps.length;
+  }
   return {
     steps,
     groupCount: groupSources.length,
@@ -5976,7 +6278,8 @@ function buildPlan(spec, eps = EPS) {
     attackIds,
     riderIds,
     riderSteps,
-    perHitGroups
+    perHitGroups,
+    groupLastReadStep
   };
 }
 
@@ -5986,18 +6289,36 @@ var FIRST_HIT = 1;
 var FIRST_CRIT = 2;
 var CRIT_BIT = 2;
 var MISS_BIT = 1;
+var MATCH_BIT = 16;
 var START_CODE = FIRST_NONE << 2;
-function advance(code, outcome) {
+function advance(code, outcome, matched = false) {
   if (outcome === "miss") return code | MISS_BIT;
-  const first = code >> 2;
+  const first = code >> 2 & 3;
   const withCrit = outcome === "crit" ? code | CRIT_BIT : code;
-  if (first !== FIRST_NONE) return withCrit;
+  const withMatch = matched ? withCrit | MATCH_BIT : withCrit;
+  if (first !== FIRST_NONE) return withMatch;
   const nextFirst = outcome === "crit" ? FIRST_CRIT : FIRST_HIT;
-  return nextFirst << 2 | withCrit & (CRIT_BIT | MISS_BIT);
+  return nextFirst << 2 | withMatch & (MATCH_BIT | CRIT_BIT | MISS_BIT);
 }
 
 // src/turn/turn.ts
-var OUTCOMES = ["hit", "crit", "miss"];
+function stepDraws(slices) {
+  const draws = [];
+  if (slices.hitMatch) {
+    draws.push({ outcome: "hit", matched: true, slice: slices.hitMatch });
+    draws.push({ outcome: "hit", matched: false, slice: slices.hitNoMatch });
+  } else {
+    draws.push({ outcome: "hit", matched: false, slice: slices.hit });
+  }
+  if (slices.critMatch) {
+    draws.push({ outcome: "crit", matched: true, slice: slices.critMatch });
+    draws.push({ outcome: "crit", matched: false, slice: slices.critNoMatch });
+  } else {
+    draws.push({ outcome: "crit", matched: false, slice: slices.crit });
+  }
+  draws.push({ outcome: "miss", matched: false, slice: slices.miss });
+  return draws;
+}
 function fireMode(step, codes, firedByStep) {
   const trigger = step.trigger;
   if (!trigger) return "hit";
@@ -6005,7 +6326,7 @@ function fireMode(step, codes, firedByStep) {
     return firedByStep[step.negates] === null ? "hit" : null;
   }
   const code = codes[step.reads];
-  const first = code >> 2;
+  const first = code >> 2 & 3;
   switch (trigger.on) {
     case "first-hit":
       if (first === FIRST_NONE) return null;
@@ -6014,6 +6335,8 @@ function fireMode(step, codes, firedByStep) {
       return (code & CRIT_BIT) !== 0 ? "crit" : null;
     case "any-miss":
       return (code & MISS_BIT) !== 0 ? "hit" : null;
+    case "dice-match":
+      return (code & MATCH_BIT) !== 0 ? "hit" : null;
     default:
       return null;
   }
@@ -6141,6 +6464,20 @@ var Turn = class _Turn {
     riders.push({ ...options, damage, on: "not-fired", of: target });
     return new _Turn(this.declaredAttacks, riders, this.eps);
   }
+  /**
+   * Fires once if any of `of`'s named sources' own damage dice matched (showed a
+   * duplicate value) on hit or crit — Chromatic Orb's bounce. Unlike the other
+   * `onX` triggers, `of` is required: "the dice matched" has no coherent meaning
+   * defaulted across every declared attack. Each named source must expose a
+   * dice-match descriptor (an `AttackBuilder`-shaped source does); naming one
+   * that doesn't is a `TurnSpecError("no-dice-descriptor", ...)`.
+   *
+   * Most callers want {@link bounce} instead of calling this directly — it
+   * builds the whole depth-capped chain of attack-shaped riders.
+   */
+  onDiceMatch(of, damage, options = {}) {
+    return this.rider({ ...options, damage, on: "dice-match", of });
+  }
   /**
    * The exact joint distribution: mass 1, outcome-labelled. Resolved once and
    * cached.
@@ -6213,8 +6550,14 @@ var Turn = class _Turn {
     let states = /* @__PURE__ */ new Map([[String.fromCharCode(), start]]);
     plan.steps.forEach((step, stepIndex) => {
       const next = /* @__PURE__ */ new Map();
+      const liveGroups = [];
+      for (let g = 0; g < plan.groupCount; g++) {
+        if (plan.groupLastReadStep[g] > stepIndex) liveGroups.push(g);
+      }
       const merge = (state) => {
-        const key = String.fromCharCode(...state.codes) + "
" + state.fired.map((mode) => mode === null ? "-" : "+").join("");
+        let codesKey = "";
+        for (const g of liveGroups) codesKey += String.fromCharCode(state.codes[g]);
+        const key = codesKey + "
" + state.fired.map((mode) => mode === null ? "-" : "+").join("");
         const existing = next.get(key);
         if (existing) existing.pmf = existing.pmf.add(state.pmf);
         else next.set(key, state);
@@ -6240,13 +6583,12 @@ var Turn = class _Turn {
           });
           continue;
         }
-        for (const outcome of OUTCOMES) {
-          const slice = step.slices[outcome];
+        for (const { outcome, matched, slice } of stepDraws(step.slices)) {
           const sliceMass = slice.mass();
           if (sliceMass <= eps) continue;
           const codes = [...state.codes];
           for (const group of step.updates) {
-            codes[group] = advance(codes[group], outcome);
+            codes[group] = advance(codes[group], outcome, matched);
           }
           merge({
             codes,
@@ -6270,7 +6612,7 @@ var Turn = class _Turn {
         }
       }
       for (const [id, group] of plan.perHitGroups) {
-        if (state.codes[group] >> 2 !== FIRST_NONE) {
+        if ((state.codes[group] >> 2 & 3) !== FIRST_NONE) {
           fireMass.set(id, fireMass.get(id) + mass);
         }
       }
@@ -6294,6 +6636,19 @@ function turn(attacks = [], eps = EPS) {
     eps
   );
 }
+function bounce({ source, max }) {
+  if (!Number.isInteger(max) || max < 0) {
+    throw new RangeError(`bounce({ max }) needs a non-negative integer, got ${max}.`);
+  }
+  let result = turn(source);
+  let previousId = result.attackIds[0];
+  for (let i = 0; i < max; i++) {
+    const riderId = `bounce ${i + 1}`;
+    result = result.onDiceMatch([previousId], source, { id: riderId });
+    previousId = riderId;
+  }
+  return result;
+}
 
 exports.ACBuilder = ACBuilder;
 exports.AlwaysCritBuilder = AlwaysCritBuilder;
@@ -6310,6 +6665,7 @@ exports.SaveBuilder = SaveBuilder;
 exports.ScaleRollBuilder = ScaleRollBuilder;
 exports.Turn = Turn;
 exports.TurnSpecError = TurnSpecError;
+exports.bounce = bounce;
 exports.builderPMFCache = builderPMFCache;
 exports.clearAttackCache = clearAttackCache;
 exports.clearDCCache = clearDCCache;