@yipe/dice 0.8.0 → 0.9.0

package/dist/builder/index.cjs

@@ -117,6 +117,10 @@ var _DiceQuery = class _DiceQuery {
     if (this._combinedWithAttr) {
       return this._combinedWithAttr;
     }
+    if (this._combinedProvided) {
+      this._combinedWithAttr = this.combined.withAttribution();
+      return this._combinedWithAttr;
+    }
     if (this.singles.every((pmf) => pmf.hasAttribution())) {
       this._combinedWithAttr = this.combined;
       return this._combinedWithAttr;
@@ -887,6 +891,55 @@ var _DiceQuery = class _DiceQuery {
     }
     return out;
   }
+  /**
+   * Per-outcome probabilities and damage ranges, aggregated over the individual
+   * singles rather than read off the combined distribution.
+   *
+   * `damageRange` is the sum, over every single that can produce the outcome, of
+   * that single's own conditional damage range: "what this outcome contributes
+   * across the whole turn when every attack that can produce it does". Linear in
+   * the number of attacks by construction.
+   *
+   * Prefer this over {@link DiceQuery.snapshot} for a multi-attack query.
+   * `snapshot` reads `damageRange` off the combined PMF's `count`, which the
+   * convolution accumulates as an expected count, so its `avg` is size-biased
+   * for N≥2 (its own doc comment says so). The two agree for a single attack.
+   *
+   * Only outcomes that actually occur appear in the result.
+   *
+   * Like every `singles`-based helper on this class, it describes the singles
+   * and not an explicitly provided `combined`. `Turn.toQuery()` supplies one whose
+   * distribution also contains rider attacks that are absent from `singles`
+   * (an `otherwise([unarmed, unarmed])` flurry, say), so those attacks do not
+   * appear here. For rider-inclusive figures read the combined distribution
+   * directly: {@link DiceQuery.outcomeTotals}, {@link DiceQuery.outcomeDamageRanges}.
+   *
+   * @param outcomes Which outcomes to consider; defaults to every canonical one.
+   */
+  outcomeStats(outcomes = ALL_OUTCOME_TYPES) {
+    const stats = /* @__PURE__ */ new Map();
+    const perSingle = this.singles.map((pmf) => new _DiceQuery([pmf], void 0, this._eps));
+    for (const outcome of outcomes) {
+      const atLeastOneProbability = this.probAtLeastOne(outcome);
+      if (atLeastOneProbability <= 0) continue;
+      const damageRange = { min: 0, avg: 0, max: 0 };
+      let contributors = 0;
+      for (const single of perSingle) {
+        if (single.probAtLeastOne(outcome) <= 0) continue;
+        contributors++;
+        const stat = single.damageStatsFrom(outcome);
+        damageRange.min += stat.min;
+        damageRange.avg += stat.avg;
+        damageRange.max += stat.max;
+      }
+      stats.set(outcome, {
+        atLeastOneProbability,
+        allProbability: contributors > 0 ? this.probExactlyK(outcome, contributors) : 0,
+        damageRange
+      });
+    }
+    return stats;
+  }
   /**
    * 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)
@@ -3454,6 +3507,10 @@ function d20PMF(rerollOne) {
 }
 
 // src/builder/roll.ts
+var rollPMFCache = new LRUCache(4e3);
+function clearRollCache() {
+  rollPMFCache.clear();
+}
 var defaultConfig = {
   count: 1,
   sides: 0,
@@ -3866,8 +3923,16 @@ var RollBuilder = class _RollBuilder {
     }
     return result.replace(/\+ -/g, "-");
   }
+  // Main AST entry point. Cached by the cheap config key across identical rebuilds; see `rollPMFCache`.
   toPMF(eps = 0) {
-    return pmfFromRollBuilder(this, eps);
+    const key = this.cacheKey();
+    if (key === null) return pmfFromRollBuilder(this, eps);
+    const fullKey = `${key}*e${eps}`;
+    const cached = rollPMFCache.get(fullKey);
+    if (cached) return cached;
+    const pmf = pmfFromRollBuilder(this, eps);
+    rollPMFCache.set(fullKey, pmf);
+    return pmf;
   }
   get pmf() {
     return this.toPMF();
@@ -5127,11 +5192,11 @@ var AttackBuilder = class _AttackBuilder {
       pMiss: pmiss
     } = this.resolveProbabilities(this.check, eps);
     const hitPMF = this.hitEffect ? this.hitEffect instanceof ParsedRollBuilder ? this.hitEffect.toPMF(eps) : pmfFromRollBuilder(this.hitEffect, eps) : PMF.delta(0, eps);
-    let critPMF = null;
+    let critPMF2 = null;
     let phit = pHit;
     let pcrit = pCrit;
     if (this.critEffect === null) {
-      critPMF = null;
+      critPMF2 = null;
       phit += pcrit;
       pcrit = 0;
     } else {
@@ -5139,7 +5204,7 @@ var AttackBuilder = class _AttackBuilder {
       if (this.critEffect) {
         critBuilder = this.critEffect;
       } else if (this.hitEffect instanceof ParsedRollBuilder) {
-        critPMF = null;
+        critPMF2 = null;
         phit += pcrit;
         pcrit = 0;
         critBuilder = void 0;
@@ -5147,20 +5212,20 @@ var AttackBuilder = class _AttackBuilder {
         critBuilder = this.hitEffect?.copy().doubleDice();
       }
       if (critBuilder) {
-        critPMF = critBuilder instanceof ParsedRollBuilder ? critBuilder.toPMF(eps) : pmfFromRollBuilder(critBuilder, eps);
+        critPMF2 = critBuilder instanceof ParsedRollBuilder ? critBuilder.toPMF(eps) : pmfFromRollBuilder(critBuilder, eps);
       }
     }
     const missPMF = this.missEffect ? this.missEffect instanceof ParsedRollBuilder ? this.missEffect.toPMF(eps) : pmfFromRollBuilder(this.missEffect, eps) : PMF.delta(0, eps);
     const mix = new Mixture(eps);
     if (phit > 0) mix.add("hit", hitPMF, phit);
-    if (critPMF && pcrit > 0) mix.add("crit", critPMF, pcrit);
+    if (critPMF2 && pcrit > 0) mix.add("crit", critPMF2, pcrit);
     if (pmiss > 0)
       mix.add(this.missEffect ? "missDamage" : "missNone", missPMF, pmiss);
     return {
       pmf: mix.buildPMF(eps) ?? PMF.delta(0, eps),
       check: this.check.toPMF(eps) ?? PMF.delta(0, eps),
       hit: hitPMF ?? PMF.delta(0, eps),
-      crit: critPMF ?? PMF.delta(0, eps),
+      crit: critPMF2 ?? PMF.delta(0, eps),
       miss: missPMF ?? PMF.delta(0, eps),
       weights: { hit: phit, crit: pcrit, miss: pmiss }
     };
@@ -5296,6 +5361,10 @@ RollBuilder.prototype.ac = function(targetAC) {
 };
 
 // src/builder/save.ts
+var savePMFCache = new LRUCache(4e3);
+function clearSaveCache() {
+  savePMFCache.clear();
+}
 var SaveBuilder = class _SaveBuilder {
   constructor(check, failureEffect, saveOutcome = "normal") {
     this.check = check;
@@ -5332,9 +5401,32 @@ var SaveBuilder = class _SaveBuilder {
       weights: { success: psuccess, fail: pfail }
     };
   }
-  // By default, create PMF with no pruning
+  /**
+   * A cheap, complete key for this save's resolved PMF, or `null` when it can't be cached soundly.
+   * {@link resolve} reads exactly three things: the DC check (via `resolveProbabilities`), the failure
+   * effect's PMF, and the save outcome — so composing their keys pins it. A `ParsedRollBuilder` failure
+   * effect returns `null`, which correctly forces this uncached.
+   */
+  cacheKey(eps) {
+    const checkKey = this.check.cacheKey();
+    if (checkKey === null) return null;
+    let failKey = "";
+    if (this.failureEffect) {
+      const k = this.failureEffect.cacheKey();
+      if (k === null) return null;
+      failKey = k;
+    }
+    return `${checkKey}*F${failKey}*O${this.saveOutcome}*e${eps}`;
+  }
+  // By default, create PMF with no pruning. Cached by the cheap config key across identical rebuilds.
   toPMF(eps = 0) {
-    return this.resolve(eps).pmf;
+    const key = this.cacheKey(eps);
+    if (key === null) return this.resolve(eps).pmf;
+    const cached = savePMFCache.get(key);
+    if (cached) return cached;
+    const pmf = this.resolve(eps).pmf;
+    savePMFCache.set(key, pmf);
+    return pmf;
   }
   get pmf() {
     return this.toPMF();
@@ -5370,6 +5462,10 @@ function resolveProbabilities(check) {
 }
 
 // src/builder/dc.ts
+var dcPMFCache = new LRUCache(4e3);
+function clearDCCache() {
+  dcPMFCache.clear();
+}
 var DCBuilder = class _DCBuilder extends RollBuilder {
   constructor(baseRoll, saveConfig) {
     super(baseRoll.getSubRollConfigs());
@@ -5410,7 +5506,22 @@ var DCBuilder = class _DCBuilder extends RollBuilder {
     const expression = new RollBuilder(allConfigs).toExpression();
     return `(${expression} DC ${this.saveConfig.dc})`;
   }
+  /**
+   * The DC check's PMF is fully determined by the save DC plus everything `toPMF` below reads off the roll
+   * configs (`rollType`, `baseReroll`, `modifier`, bonus dice) — all of which `super.cacheKey()` already
+   * serializes. So extend the base key with the DC, mirroring {@link AlwaysHitBuilder.cacheKey}.
+   */
+  cacheKey() {
+    const base = super.cacheKey();
+    return base === null ? null : `DC|${this.saveConfig.dc}|${base}`;
+  }
   toPMF(eps = 0) {
+    const key = this.cacheKey();
+    const fullKey = key === null ? null : `${key}*e${eps}`;
+    if (fullKey !== null) {
+      const cached = dcPMFCache.get(fullKey);
+      if (cached) return cached;
+    }
     const saveDC = this.saveDC;
     const rollType = this.rollType;
     const rerollOne = this.baseReroll > 0;
@@ -5432,7 +5543,9 @@ var DCBuilder = class _DCBuilder extends RollBuilder {
       [0, psuccess > 0 ? psuccess : 0],
       [1, pfail > 0 ? pfail : 0]
     ]);
-    return PMF.fromMap(m, eps);
+    const pmf = PMF.fromMap(m, eps);
+    if (fullKey !== null) dcPMFCache.set(fullKey, pmf);
+    return pmf;
   }
 };
 RollBuilder.prototype.dc = function(saveDC) {
@@ -5440,20 +5553,631 @@ RollBuilder.prototype.dc = function(saveDC) {
   return new DCBuilder(this).dc(saveDC);
 };
 
+// src/turn/types.ts
+var TurnSpecError = class extends Error {
+  constructor(code, id, message) {
+    super(message);
+    this.code = code;
+    this.id = id;
+    this.name = "TurnSpecError";
+  }
+};
+var MAX_TRIGGER_GROUPS = 4;
+
+// src/turn/plan.ts
+var IS_HIT_TRIGGER = {
+  "first-hit": true,
+  "any-crit": true,
+  "any-miss": true,
+  "every-hit": true
+};
+function toPMF(damage, eps, id = "") {
+  const parts = Array.isArray(damage) ? damage : [damage];
+  if (parts.length === 0) return PMF.delta(0, eps);
+  const pmfs = parts.map((part) => {
+    if (part instanceof PMF) return part;
+    if (typeof part.toPMF !== "function") {
+      throw new TurnSpecError(
+        "not-an-attack",
+        id,
+        `"${id}" is neither a PMF nor a builder with toPMF().`
+      );
+    }
+    const resolved = part.toPMF(eps);
+    if (!(resolved instanceof PMF)) {
+      throw new TurnSpecError(
+        "not-an-attack",
+        id,
+        `"${id}" has a toPMF() that did not return a PMF.`
+      );
+    }
+    return resolved;
+  });
+  return PMF.convolveMany(pmfs, eps);
+}
+function critPMF(rider, base, eps) {
+  if (rider.critDamage !== void 0) return toPMF(rider.critDamage, eps);
+  const parts = Array.isArray(rider.damage) ? rider.damage : [rider.damage];
+  const doubled = [];
+  for (const part of parts) {
+    const doublable = part;
+    if (part instanceof PMF || typeof doublable.doubleDice !== "function") {
+      return base;
+    }
+    try {
+      doubled.push(toPMF(doublable.doubleDice(), eps));
+    } catch {
+      return base;
+    }
+  }
+  if (doubled.length === 0) return base;
+  return PMF.convolveMany(doubled, eps);
+}
+function sliceSource(pmf) {
+  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()
+  };
+}
+function buildPlan(spec, eps = EPS) {
+  const fail = (code, id, message) => {
+    throw new TurnSpecError(code, id, message);
+  };
+  const attackIds = [];
+  const attackPMFs = [];
+  const attackSlices = [];
+  spec.attacks.forEach((entry, index) => {
+    const named = entry;
+    const hasWrapper = typeof named.id === "string" && named.source !== void 0;
+    const id = hasWrapper ? named.id : `attack ${index + 1}`;
+    const source = hasWrapper ? named.source : entry;
+    const pmf = toPMF(source, eps, id);
+    attackIds.push(id);
+    attackPMFs.push(pmf);
+    attackSlices.push(sliceSource(pmf));
+  });
+  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]) {
+    if (seen.has(id)) fail("duplicate-id", id, `Duplicate id "${id}".`);
+    seen.add(id);
+  }
+  const attackIndexById = new Map(attackIds.map((id, index) => [id, index]));
+  const riderIndexById = new Map(riderIds.map((id, index) => [id, index]));
+  const sourceIdsByRider = riders.map((rider, index) => {
+    const id = riderIds[index];
+    if (rider.on === "not-fired") {
+      const target = rider.of;
+      if (target === id) {
+        fail("self-reference", id, `Rider "${id}" cannot depend on itself.`);
+      }
+      const targetIndex = riderIndexById.get(target);
+      if (targetIndex === void 0) {
+        fail(
+          "unknown-id",
+          target,
+          `Rider "${id}" negates "${target}", which is not a rider in this turn.`
+        );
+      }
+      if (riders[targetIndex].on === "every-hit") {
+        fail(
+          "not-an-attack",
+          target,
+          `Rider "${id}" negates "${target}", an every-hit rider, which can fire more than once and so has no single "did not fire" branch.`
+        );
+      }
+      return [target];
+    }
+    const of = [...new Set(rider.of ?? attackIds)];
+    if (of.length === 0) {
+      fail("unknown-id", id, `Rider "${id}" has no sources.`);
+    }
+    for (const sourceId of of) {
+      if (sourceId === id) {
+        fail("self-reference", id, `Rider "${id}" cannot depend on itself.`);
+      }
+      const riderIndex = riderIndexById.get(sourceId);
+      const isAttack = attackIndexById.has(sourceId);
+      if (!isAttack && riderIndex === void 0) {
+        fail(
+          "unknown-id",
+          sourceId,
+          `Rider "${id}" depends on "${sourceId}", which is not in this turn.`
+        );
+      }
+      if (riderIndex !== void 0 && riders[riderIndex].on === "every-hit") {
+        fail(
+          "not-an-attack",
+          sourceId,
+          `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 slices = isAttack ? attackSlices[attackIndexById.get(sourceId)] : sliceSource(
+        toPMF(riders[riderIndex].damage, eps, sourceId)
+      );
+      if (!slices) {
+        fail(
+          "not-an-attack",
+          sourceId,
+          `Rider "${id}" triggers on "${sourceId}", which has no hit/crit outcomes.`
+        );
+      }
+    }
+    return [...of];
+  });
+  const order = [];
+  const visiting = /* @__PURE__ */ new Set();
+  const done = /* @__PURE__ */ new Set();
+  const visit = (index) => {
+    if (done.has(index)) return;
+    const id = riderIds[index];
+    if (visiting.has(index)) {
+      fail("cycle", id, `Rider "${id}" is part of a dependency cycle.`);
+    }
+    visiting.add(index);
+    for (const sourceId of sourceIdsByRider[index]) {
+      const dependency = riderIndexById.get(sourceId);
+      if (dependency !== void 0) visit(dependency);
+    }
+    visiting.delete(index);
+    done.add(index);
+    order.push(index);
+  };
+  riders.forEach((_, index) => visit(index));
+  const groupIndexByKey = /* @__PURE__ */ new Map();
+  const groupSources = [];
+  const groupOf = (sourceIds) => {
+    const key = JSON.stringify([...sourceIds].sort());
+    const existing = groupIndexByKey.get(key);
+    if (existing !== void 0) return existing;
+    if (groupSources.length >= MAX_TRIGGER_GROUPS) {
+      fail(
+        "too-many-groups",
+        key,
+        `A turn may track at most ${MAX_TRIGGER_GROUPS} distinct trigger source sets.`
+      );
+    }
+    const index = groupSources.length;
+    groupIndexByKey.set(key, index);
+    groupSources.push([...sourceIds]);
+    return index;
+  };
+  const readsByRider = /* @__PURE__ */ new Map();
+  const perHitGroups = /* @__PURE__ */ new Map();
+  for (const index of order) {
+    const rider = riders[index];
+    if (!IS_HIT_TRIGGER[rider.on]) continue;
+    const group = groupOf(sourceIdsByRider[index]);
+    readsByRider.set(index, group);
+    if (rider.on === "every-hit") perHitGroups.set(riderIds[index], group);
+  }
+  const perHitBySource = /* @__PURE__ */ new Map();
+  for (const index of order) {
+    const rider = riders[index];
+    if (rider.on !== "every-hit") continue;
+    const hit = toPMF(rider.damage, eps, riderIds[index]);
+    const payload = { hit, crit: critPMF(rider, hit, eps) };
+    for (const sourceId of sourceIdsByRider[index]) {
+      const existing = perHitBySource.get(sourceId);
+      if (existing) existing.push(payload);
+      else perHitBySource.set(sourceId, [payload]);
+    }
+  }
+  const updatesById = /* @__PURE__ */ new Map();
+  groupSources.forEach((sourceIds, groupIndex) => {
+    for (const sourceId of sourceIds) {
+      const existing = updatesById.get(sourceId);
+      if (existing) existing.push(groupIndex);
+      else updatesById.set(sourceId, [groupIndex]);
+    }
+  });
+  const withPerHit = (slices, id) => {
+    const payloads = perHitBySource.get(id);
+    if (!payloads) return slices;
+    let hit = slices.hit;
+    let crit = slices.crit;
+    for (const payload of payloads) {
+      hit = hit.convolve(payload.hit, eps, true);
+      crit = crit.convolve(payload.crit, eps, true);
+    }
+    return { hit, crit, miss: slices.miss };
+  };
+  const steps = attackIds.map((id, index) => ({
+    id,
+    trigger: null,
+    slices: withPerHit(
+      attackSlices[index] ?? {
+        hit: attackPMFs[index],
+        crit: PMF.emptyMass(),
+        miss: PMF.emptyMass()
+      },
+      id
+    ),
+    damage: null,
+    updates: updatesById.get(id) ?? [],
+    reads: -1,
+    negates: -1
+  }));
+  const stepIndexByRider = /* @__PURE__ */ new Map();
+  const riderSteps = /* @__PURE__ */ new Map();
+  for (const index of order) {
+    const rider = riders[index];
+    if (rider.on === "every-hit") continue;
+    const id = riderIds[index];
+    const hit = toPMF(rider.damage, eps, id);
+    const slices = sliceSource(hit);
+    if (slices && rider.critDamage !== void 0) {
+      fail(
+        "unused-crit-damage",
+        id,
+        `Rider "${id}" rolls its own attack, so its critDamage would never be used. Remove it, or pass plain damage dice instead.`
+      );
+    }
+    const negatedRider = rider.on === "not-fired" ? riderIndexById.get(rider.of) : void 0;
+    const step = {
+      id,
+      trigger: rider,
+      slices: slices ? withPerHit(slices, id) : null,
+      damage: slices ? null : { hit, crit: critPMF(rider, hit, eps) },
+      updates: updatesById.get(id) ?? [],
+      reads: readsByRider.get(index) ?? -1,
+      negates: negatedRider === void 0 ? -1 : stepIndexByRider.get(negatedRider)
+    };
+    steps.push(step);
+    stepIndexByRider.set(index, steps.length - 1);
+    riderSteps.set(id, steps.length - 1);
+  }
+  return {
+    steps,
+    groupCount: groupSources.length,
+    attackPMFs,
+    attackIds,
+    riderIds,
+    riderSteps,
+    perHitGroups
+  };
+}
+
+// src/turn/state.ts
+var FIRST_NONE = 0;
+var FIRST_HIT = 1;
+var FIRST_CRIT = 2;
+var CRIT_BIT = 2;
+var MISS_BIT = 1;
+var START_CODE = FIRST_NONE << 2;
+function advance(code, outcome) {
+  if (outcome === "miss") return code | MISS_BIT;
+  const first = code >> 2;
+  const withCrit = outcome === "crit" ? code | CRIT_BIT : code;
+  if (first !== FIRST_NONE) return withCrit;
+  const nextFirst = outcome === "crit" ? FIRST_CRIT : FIRST_HIT;
+  return nextFirst << 2 | withCrit & (CRIT_BIT | MISS_BIT);
+}
+
+// src/turn/turn.ts
+var OUTCOMES = ["hit", "crit", "miss"];
+function fireMode(step, codes, firedByStep) {
+  const trigger = step.trigger;
+  if (!trigger) return "hit";
+  if (trigger.on === "not-fired") {
+    return firedByStep[step.negates] === null ? "hit" : null;
+  }
+  const code = codes[step.reads];
+  const first = code >> 2;
+  switch (trigger.on) {
+    case "first-hit":
+      if (first === FIRST_NONE) return null;
+      return first === FIRST_CRIT ? "crit" : "hit";
+    case "any-crit":
+      return (code & CRIT_BIT) !== 0 ? "crit" : null;
+    case "any-miss":
+      return (code & MISS_BIT) !== 0 ? "hit" : null;
+    default:
+      return null;
+  }
+}
+var Turn = class _Turn {
+  constructor(attacks, riders, eps) {
+    this.declaredAttacks = [...attacks];
+    this.riders = [...riders];
+    this.eps = eps;
+    this.plan = buildPlan({ attacks: this.declaredAttacks, riders: this.riders }, eps);
+  }
+  /**
+   * Builds a turn from plain data, throwing {@link TurnSpecError} if it is
+   * malformed. Use this from a UI, where `error.code` maps to the field state to
+   * show.
+   */
+  static from(spec, eps = EPS) {
+    return new _Turn(spec.attacks, spec.riders ?? [], eps);
+  }
+  /**
+   * Appends an attack, throwing {@link TurnSpecError} if that makes the turn
+   * invalid.
+   *
+   * A rider with no explicit `of` watches every declared attack *including ones
+   * appended after it*, because `of` is resolved when the plan is built rather
+   * than when the rider is added. Pass an explicit `of` to pin a rider to the
+   * attacks it already saw. One attack must exist before a rider with a default
+   * `of` is added, or the build fails `unknown-id`.
+   */
+  attack(source, id) {
+    const entry = id === void 0 ? source : { id, source };
+    return new _Turn([...this.declaredAttacks, entry], this.riders, this.eps);
+  }
+  /**
+   * Appends `count` copies of the same attack — the Extra Attack case, which is
+   * most of 5e. Argument order mirrors `roll(count, die)`.
+   *
+   * ```ts
+   * turn().attacks(4, greatsword).onEveryHit(d6); // fighter 20 + hunter's mark
+   * ```
+   *
+   * @throws {RangeError} if `count` is not a positive integer.
+   */
+  attacks(count, source) {
+    if (!Number.isInteger(count) || count < 1) {
+      throw new RangeError(
+        `attacks(count) needs a positive integer, got ${count}.`
+      );
+    }
+    const added = new Array(count).fill(source);
+    return new _Turn([...this.declaredAttacks, ...added], this.riders, this.eps);
+  }
+  /**
+   * Appends a rider, throwing {@link TurnSpecError} if that makes the turn
+   * invalid. The `onX` methods below are the readable way to call this.
+   */
+  rider(rider) {
+    return new _Turn(this.declaredAttacks, [...this.riders, rider], this.eps);
+  }
+  /**
+   * Fires once, on the first source that lands, in that source's mode — so a
+   * crit on the first landing attack doubles the rider's dice. Sneak Attack.
+   */
+  onFirstHit(damage, options = {}) {
+    return this.rider({ ...options, damage, on: "first-hit" });
+  }
+  /**
+   * Fires once if any source crit, always in crit mode. Divine Smite: nothing is
+   * lost by holding it for a crit, so this is "any", not "first".
+   */
+  onAnyCrit(damage, options = {}) {
+    return this.rider({ ...options, damage, on: "any-crit" });
+  }
+  /**
+   * Fires once if any source missed. The reroll gate: a reroll is a fresh attack,
+   * so pass one as the damage. Kensei's Unerring Accuracy, Lucky.
+   */
+  onAnyMiss(damage, options = {}) {
+    return this.rider({ ...options, damage, on: "any-miss" });
+  }
+  /**
+   * Fires once per source that lands, in that hit's mode — so it can fire several
+   * times in a turn. Hunter's Mark, Hex, Rage.
+   */
+  onEveryHit(damage, options = {}) {
+    return this.rider({ ...options, damage, on: "every-hit" });
+  }
+  /**
+   * Damage for the turns where the rider added just before this one did *not*
+   * fire: "flurry of blows if I didn't smite".
+   *
+   * ```ts
+   * turn([dagger, dagger])
+   *   .onAnyCrit(roll(2, d8))      // smite
+   *   .otherwise([flurry, flurry]) // ... or two more attacks
+   * ```
+   *
+   * Always binds to the *immediately* preceding rider, so the two are branches of
+   * one decision and can never both land. Note that chaining it therefore
+   * alternates rather than laddering: `a.otherwise(b).otherwise(c)` makes `c`
+   * fire whenever `b` did not, which is exactly when `a` did. For a genuine
+   * three-way priority chain, name the riders and use explicit `not-fired`
+   * triggers against the right one.
+   */
+  otherwise(damage, options = {}) {
+    const index = this.riders.length - 1;
+    if (index < 0) {
+      throw new TurnSpecError(
+        "unknown-id",
+        "",
+        "otherwise() needs a preceding rider to negate."
+      );
+    }
+    const previous = this.riders[index];
+    if (previous.on === "every-hit") {
+      throw new TurnSpecError(
+        "not-an-attack",
+        previous.id ?? `rider ${index + 1}`,
+        "otherwise() cannot negate an every-hit rider: it can fire more than once."
+      );
+    }
+    const target = previous.id ?? `rider ${index + 1}`;
+    const riders = [...this.riders];
+    riders[index] = { ...previous, id: target };
+    riders.push({ ...options, damage, on: "not-fired", of: target });
+    return new _Turn(this.declaredAttacks, riders, this.eps);
+  }
+  /**
+   * The exact joint distribution: mass 1, outcome-labelled. Resolved once and
+   * cached.
+   *
+   * There is no `toPMF(eps)` to match the builders: a turn's epsilon is fixed
+   * when it is constructed, because the plan is validated and its sources are
+   * resolved at that point.
+   */
+  get pmf() {
+    return this.resolve().pmf;
+  }
+  /** Mean damage for the turn. */
+  mean() {
+    return this.pmf.mean();
+  }
+  /**
+   * A query whose `singles` are the **declared attacks** and whose combined
+   * distribution is the exact turn PMF.
+   *
+   * Riders are inside the combined PMF, not in `singles`, so singles-based
+   * helpers (`probAtLeastOne`, `countSinglesWith`, `outcomeStats`) describe the
+   * attacks only. Read rider-inclusive statistics off the combined PMF —
+   * `outcomeTotals`, `outcomeDamageRanges`, `damageAttributionChartModel`.
+   */
+  toQuery() {
+    return new DiceQuery([...this.plan.attackPMFs], this.pmf, this.eps);
+  }
+  /**
+   * Attack ids in declaration order, including the `attack 1`, `attack 2`, …
+   * defaults given to bare sources. These are the names `of` accepts.
+   */
+  get attackIds() {
+    return this.plan.attackIds;
+  }
+  /**
+   * Rider ids in declaration order, including the `rider 1`, `rider 2`, …
+   * defaults. These are the names {@link Turn.fireProbability} accepts.
+   */
+  get riderIds() {
+    return this.plan.riderIds;
+  }
+  /**
+   * P(this rider fired). For an `every-hit` rider it is P(at least one source
+   * hit), since that rider can fire more than once in a turn.
+   *
+   * @throws {TurnSpecError} `unknown-id` if `id` is not a rider — attack ids
+   * included, since attacks always happen and have no firing probability.
+   */
+  fireProbability(id) {
+    const mass = this.resolve().fireMass.get(id);
+    if (mass === void 0) {
+      throw new TurnSpecError(
+        "unknown-id",
+        id,
+        `"${id}" is not a rider in this turn. Riders: ${this.plan.riderIds.map((each) => `"${each}"`).join(", ")}.`
+      );
+    }
+    return mass;
+  }
+  resolve() {
+    if (this.resolved) return this.resolved;
+    const plan = this.plan;
+    const eps = this.eps;
+    const width = plan.groupCount;
+    const start = {
+      codes: new Array(width).fill(START_CODE),
+      pmf: PMF.delta(0, eps),
+      fired: new Array(plan.steps.length).fill(null)
+    };
+    let states = /* @__PURE__ */ new Map([[String.fromCharCode(), start]]);
+    plan.steps.forEach((step, stepIndex) => {
+      const next = /* @__PURE__ */ new Map();
+      const merge = (state) => {
+        const key = String.fromCharCode(...state.codes) + "
" + 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);
+      };
+      for (const state of states.values()) {
+        const mode = fireMode(step, state.codes, state.fired);
+        const fired = [...state.fired];
+        fired[stepIndex] = mode;
+        if (mode === null) {
+          merge({ codes: state.codes, pmf: state.pmf, fired });
+          continue;
+        }
+        if (!step.slices) {
+          const payload = step.damage;
+          merge({
+            codes: state.codes,
+            pmf: state.pmf.convolve(
+              mode === "crit" ? payload.crit : payload.hit,
+              eps,
+              true
+            ),
+            fired
+          });
+          continue;
+        }
+        for (const outcome of OUTCOMES) {
+          const slice = step.slices[outcome];
+          const sliceMass = slice.mass();
+          if (sliceMass <= eps) continue;
+          const codes = [...state.codes];
+          for (const group of step.updates) {
+            codes[group] = advance(codes[group], outcome);
+          }
+          merge({
+            codes,
+            pmf: state.pmf.convolve(slice, eps, true),
+            fired
+          });
+        }
+      }
+      states = next;
+    });
+    const fireMass = /* @__PURE__ */ new Map();
+    for (const id of plan.riderSteps.keys()) fireMass.set(id, 0);
+    for (const id of plan.perHitGroups.keys()) fireMass.set(id, 0);
+    let total;
+    for (const state of states.values()) {
+      total = total ? total.add(state.pmf) : state.pmf;
+      const mass = state.pmf.mass();
+      for (const [id, stepIndex] of plan.riderSteps) {
+        if (state.fired[stepIndex] !== null) {
+          fireMass.set(id, fireMass.get(id) + mass);
+        }
+      }
+      for (const [id, group] of plan.perHitGroups) {
+        if (state.codes[group] >> 2 !== FIRST_NONE) {
+          fireMass.set(id, fireMass.get(id) + mass);
+        }
+      }
+    }
+    const pmf = total ?? PMF.delta(0, eps);
+    const totalMass = pmf.mass();
+    const needsNormalizing = Math.abs(totalMass - 1) > eps && totalMass > 0;
+    if (needsNormalizing) {
+      for (const [id, mass] of fireMass) fireMass.set(id, mass / totalMass);
+    }
+    this.resolved = {
+      pmf: needsNormalizing ? pmf.normalize() : pmf,
+      fireMass
+    };
+    return this.resolved;
+  }
+};
+function turn(attacks = [], eps = EPS) {
+  return Turn.from(
+    { attacks: Array.isArray(attacks) ? attacks : [attacks] },
+    eps
+  );
+}
+
 exports.ACBuilder = ACBuilder;
 exports.AlwaysCritBuilder = AlwaysCritBuilder;
 exports.AlwaysHitBuilder = AlwaysHitBuilder;
 exports.AttackBuilder = AttackBuilder;
 exports.DCBuilder = DCBuilder;
 exports.HalfRollBuilder = HalfRollBuilder;
+exports.MAX_TRIGGER_GROUPS = MAX_TRIGGER_GROUPS;
 exports.MaxOfRollBuilder = MaxOfRollBuilder;
 exports.ParsedRollBuilder = ParsedRollBuilder;
 exports.PooledRollBuilder = PooledRollBuilder;
 exports.RollBuilder = RollBuilder;
 exports.SaveBuilder = SaveBuilder;
 exports.ScaleRollBuilder = ScaleRollBuilder;
+exports.Turn = Turn;
+exports.TurnSpecError = TurnSpecError;
 exports.builderPMFCache = builderPMFCache;
 exports.clearAttackCache = clearAttackCache;
+exports.clearDCCache = clearDCCache;
+exports.clearRollCache = clearRollCache;
+exports.clearSaveCache = clearSaveCache;
 exports.d = d;
 exports.d10 = d10;
 exports.d100 = d100;
@@ -5467,5 +6191,6 @@ exports.flat = flat;
 exports.hd20 = hd20;
 exports.roll = roll;
 exports.sumRolls = sumRolls;
+exports.turn = turn;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map