@yipe/dice 0.11.0 → 0.12.0

package/dist/turn/types.d.ts

@@ -3,9 +3,9 @@ import type { PMF } from "../pmf/pmf.js";
 export type { DiceMatchInfo, HasDiceMatchInfo };
 /**
  * Triggers that read the outcomes of source attacks, as opposed to `not-fired`,
- * which reads another rider. Includes `any-miss`, so this is not "hit triggers".
+ * which reads another rider. Includes `any-miss`/`first-miss`, so this is not "hit triggers".
  */
-export type AttackTriggerOn = "first-hit" | "any-crit" | "any-miss" | "every-hit";
+export type AttackTriggerOn = "first-hit" | "any-crit" | "any-miss" | "first-miss" | "every-hit";
 /**
  * When a rider fires. JSON-safe, so a consumer can persist this verbatim and hand
  * it straight back in a {@link TurnSpec}.
@@ -13,7 +13,16 @@ export type AttackTriggerOn = "first-hit" | "any-crit" | "any-miss" | "every-hit
  * - `first-hit` — the first source that lands. Fires in that source's mode, so a
  *   crit on the *first* landing attack doubles the rider's dice (Sneak Attack).
  * - `any-crit` — at least one source crit. Always fires in crit mode (Divine Smite).
- * - `any-miss` — at least one source missed. The reroll gate (Unerring Accuracy, Lucky).
+ * - `any-miss` — at least one source missed. Its step runs after every declared attack,
+ *   which is exact only when the reroll is identically distributed to every attack after
+ *   the one it replaces. An attack-shaped `any-miss` rider that reads a granted modifier
+ *   or applies a condition's grants is refused (`unsupported-trigger`): at the end of the
+ *   turn it would see the wrong grants. Use `first-miss` for such rerolls.
+ * - `first-miss` — the FIRST source in `of` that missed. Its step runs immediately after
+ *   that attack (one slot per watched source, sharing one fire bit), so a reroll lands in
+ *   turn order and anything that reads order — a `first-hit` rider's crit mode, or a
+ *   granted modifier — sees it where it happened. The exact model of "when you miss, you
+ *   may reroll" (Unerring Accuracy, Lucky).
  * - `every-hit` — once per landing source, in that hit's mode (Hunter's Mark, Hex, Rage).
  * - `dice-match` — at least one named source's own damage dice showed a duplicate
  *   value on hit or crit (Chromatic Orb's bounce). `of` is REQUIRED — unlike the
@@ -21,13 +30,25 @@ export type AttackTriggerOn = "first-hit" | "any-crit" | "any-miss" | "every-hit
  *   for "the dice matched", so there is no default. Each named source must expose
  *   a {@link HasDiceMatchInfo} descriptor (an `AttackBuilder`-shaped source does);
  *   naming one that doesn't (a bare `PMF`, a `keep`/`bestOf` pool, a string-parsed
- *   expression) is a `TurnSpecError`, not a silent "never matches".
+ *   expression) is a `TurnSpecError`, not a silent "never matches". A damage rider
+ *   fires in crit mode, its dice doubled, when a crit's dice matched (with several
+ *   sources, when any matching landing was a crit); otherwise in hit mode.
  * - `not-fired` — the named rider did **not** fire ("flurry of blows if I didn't smite").
+ *   It may also name a substitute: it then fires when the substitute was never spent.
  *
- * For the attack triggers besides `dice-match`, `of` is a list of attack ids and
- * defaults to every declared attack, which is what most riders mean. For
- * `not-fired` it is the single required id of the rider being negated — negating
- * a set of riders has no unambiguous meaning, so the type does not offer it.
+ * For the attack triggers besides `dice-match`, `of` is a list of attack ids,
+ * attack-shaped rider ids, or declaration tags (see {@link Attack}); a tag expands to
+ * every attack carrying it. A rider whose damage is a list of several attacks is not
+ * attack-shaped: naming it is `not-an-attack`, and it never joins a default `of`.
+ *
+ * `of` defaults to every declared attack plus every attack-shaped `any-miss` /
+ * `first-miss` rider before it — a reroll continues the attacks it watches. `Turn`'s
+ * chaining methods snapshot that at the call that adds the rider (the attacks and
+ * rerolls declared so far); a {@link TurnSpec} resolves it when the plan is built,
+ * giving a rider the rerolls listed before it in `riders` and a substitute or
+ * condition every reroll. Both spellings of one turn therefore watch the same
+ * sources. For `not-fired` it is the single required id of the rider being negated —
+ * negating a set of riders has no unambiguous meaning, so the type does not offer it.
  */
 export type Trigger = {
     on: AttackTriggerOn;
@@ -44,9 +65,12 @@ export interface ToPMF {
     toPMF(eps?: number): PMF;
 }
 /**
- * Rider or attack damage. Strings are not accepted: a parsed expression cannot
- * have its dice doubled, so a string rider would deal single dice on a crit. Call
- * `parse()` yourself if that is what you want.
+ * Rider or attack damage. Raw strings are not accepted; wrap one in `d("…")`. On a
+ * crit, a rider's dice double and its flats do not: a builder through
+ * `doubleDice()`, a `d("…")` string by rewriting its dice terms (`d("2d6+5")` crits
+ * as `4d6+5`), a pool inside, then pooled. A bare `PMF` is a fixed distribution with
+ * no dice to double, so it is added as-is on a crit. A `d("…")` attack string crits on
+ * its own roll: with no crit clause, at its natural 20, with its hit dice doubled.
  */
 export type Damage = PMF | ToPMF;
 /**
@@ -56,15 +80,29 @@ export type Damage = PMF | ToPMF;
  * `not-an-attack` {@link TurnSpecError} at build time, not a compile error.
  */
 export type Source = Damage;
-/** One payload, or several to convolve: Flurry of Blows is `[flurry, flurry]`. */
+/**
+ * One payload, or several to convolve: Flurry of Blows is `[flurry, flurry]`. A list of
+ * several attacks deals their exact summed damage, but it is one payload, not attacks
+ * that each land: nothing can watch it in `of`, and it never joins a default `of`. To
+ * watch each strike, declare each as its own rider.
+ */
 export type RiderDamage = Damage | readonly Damage[];
 /** Everything about a rider except what it does and when — see `Turn.onFirstHit`. */
 export interface RiderOptions {
     /** Required only if another rider names this one in `of`. */
     id?: string;
-    /** Which attacks to watch. Defaults to every declared attack. */
+    /**
+     * Which attacks to watch: attack ids, attack-shaped rider ids, or declaration tags.
+     * Defaults to the attacks declared so far, plus any attack-shaped `any-miss` /
+     * `first-miss` rider declared so far (see {@link Trigger}).
+     */
     of?: readonly string[];
-    /** Defaults to `damage` with dice doubled when that is possible, else `damage`. */
+    /**
+     * Defaults to `damage` with its dice doubled (builders and `d("…")` strings that can double);
+     * an attack or save builder or string, or a bare `PMF` part, is added as-is. A rider that
+     * rolls its own attack — one attack, or a list of several — crits on its own roll, so
+     * giving it one is an `unused-crit-damage` error.
+     */
     critDamage?: RiderDamage;
 }
 export type Rider = Trigger & {
@@ -72,6 +110,16 @@ export type Rider = Trigger & {
     damage: RiderDamage;
     critDamage?: RiderDamage;
 };
+/** How an attack is declared: `id` names it for `of`; `tag` groups it with others. */
+export interface AttackOptions {
+    id?: string;
+    /**
+     * A name several attacks can share. An `of` entry that is not an id expands to
+     * every attack carrying that tag, so a reordered turn cannot silently retarget
+     * the way a positional `attack 2` can. A tag matching nothing is `unknown-id`.
+     */
+    tag?: string;
+}
 /**
  * A bare source gets the id `attack 1`, `attack 2`, … in declaration order.
  *
@@ -79,15 +127,104 @@ export type Rider = Trigger & {
  * itself: an attack's value is a builder or PMF that this module does not own,
  * so there is nowhere to hang a field.
  */
-export type Attack = Source | {
-    id: string;
+export type Attack = Source | (AttackOptions & {
     source: Source;
+});
+/**
+ * When a substitute may be spent: on the first landing it sees (`always`, the
+ * default), only when the base payload total (dice plus the payload's own flat
+ * bonus, excluding separate-damage channels) is below the threshold for that
+ * mode (`below`; a landing spends regardless when no later watched step can
+ * still land in that turn state), or by backward induction (`optimal` — not
+ * supported in this release).
+ */
+export type SubstitutePolicy = {
+    kind: "always";
+} | {
+    kind: "below";
+    hit: number;
+    crit: number;
+} | {
+    kind: "optimal";
 };
+/**
+ * A once-per-turn payload transform: at the first watched landing the policy
+ * accepts, the attack's base payload is replaced by a transform of itself. The
+ * JSON-safe form of `Turn.onFirstHit(keepBestDamage())`; callers write the
+ * factory, never the string.
+ */
+export interface SubstituteSpec {
+    id?: string;
+    on: "first-hit";
+    /**
+     * Omit it: defaults to every declared attack plus every attack-shaped `any-miss` /
+     * `first-miss` rider, the same sources the chaining spelling watches (see {@link Trigger}).
+     */
+    of?: readonly string[];
+    /** Named transform, so a {@link TurnSpec} stays JSON-safe and persistable. */
+    substitute: "reroll-keep-higher";
+    /** Defaults to `{ kind: "always" }`. */
+    policy?: SubstitutePolicy;
+}
+/**
+ * One granted modifier: what it does to the attack rolls that read it, how long it
+ * lasts, and which attack rolls read it. JSON-safe — the persisted form of a
+ * `Grant` built with `advantage().untilNextAttack()` and friends.
+ *
+ * - `advantage` / `disadvantage` combine with the reading attack's own roll type by
+ *   cancellation; a net advantage rolls as many dice as that attacker's
+ *   `advantageDice` (`ACBuilder.threeDiceAdvantage()`).
+ * - `critOnHit` makes every landing attack a crit; a natural 1 still misses.
+ * - `until: "next-attack"` is consumed by the next attack roll that reads it, hit or
+ *   miss; `"end-of-turn"` lasts for the rest of the turn.
+ * - `to` lists attack ids, attack-shaped rider ids or tags. Omitted, every later
+ *   attack roll reads it, attack-shaped riders included (an attack-shaped `any-miss`
+ *   rider that would read it is refused; see {@link Trigger}).
+ */
+export interface GrantSpec {
+    advantage?: true;
+    disadvantage?: true;
+    critOnHit?: true;
+    until: "next-attack" | "end-of-turn";
+    to?: readonly string[];
+}
+/**
+ * Grants applied by the outcomes of earlier attacks to later attack rolls: "a hit
+ * gives the next attack advantage". The JSON-safe form of `Turn.onEveryHit(grant)`.
+ *
+ * `on` says which outcome among `of` applies the grants: `every-hit` on each
+ * landing, `first-hit` on the first landing only, `any-crit` on each crit,
+ * `first-miss` on the first miss, `any-miss` on each miss. Miss damage
+ * (`halfOnMiss`, `onMiss`) is a miss, never a landing.
+ *
+ * `chance` is the probability each application takes (a target's failed save);
+ * `grants` apply on that branch and `onSave` on the other one. Each application
+ * rolls it afresh, except that an application whose grants are all `end-of-turn`
+ * and all already in force is skipped: nothing is rolled and `onSave` does not
+ * apply. An application with any `next-attack` grant is always rolled.
+ */
+export interface ConditionSpec {
+    id?: string;
+    on: AttackTriggerOn;
+    /**
+     * Omit it: defaults to every declared attack plus every attack-shaped `any-miss` /
+     * `first-miss` rider (see {@link Trigger}).
+     */
+    of?: readonly string[];
+    /** In `[0, 1]`; defaults to 1. */
+    chance?: number;
+    /** Applied on the fail branch, or with probability `chance`. */
+    grants: readonly GrantSpec[];
+    /** Applied on the success branch. Requires `chance`. */
+    onSave?: readonly GrantSpec[];
+}
 export interface TurnSpec {
     attacks: readonly Attack[];
     riders?: readonly Rider[];
+    substitutes?: readonly SubstituteSpec[];
+    conditions?: readonly ConditionSpec[];
 }
-export type TurnSpecErrorCode = "unknown-id" | "duplicate-id" | "self-reference" | "cycle" | "not-an-attack" | "unused-crit-damage" | "too-many-groups" | "no-dice-descriptor";
+export type TurnSpecErrorCode = "unknown-id" | "duplicate-id" | "self-reference" | "cycle" | "not-an-attack" | "unused-crit-damage" | "too-many-groups" | "no-dice-descriptor" | "duplicate-substitute" | "attack-after-rider" | "no-rebindable-source" | "unsupported-trigger" | "unsupported-policy" | "too-many-flags";
 /**
  * A malformed turn. `code` is a stable contract: consumer UIs map it to their own
  * states (greyed dropdown option, "trigger missing" row error, …) instead of

package/dist/turn/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/turn/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,UAAU,GACV,UAAU,GACV,WAAW,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,OAAO,GACf;IAAE,EAAE,EAAE,eAAe,CAAC;IAAC,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/C;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEhD,kGAAkG;AAClG,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAErD,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,mFAAmF;IACnF,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,OAAO,GACP,eAAe,GACf,oBAAoB,GACpB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM;IAFrB,YACW,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAIhB;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/turn/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yipe/dice",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A high-performance dice probability engine for D&D 5e DPR calculations. Powers dprcalc.com.",
   "keywords": [
     "dnd",