dndwright 0.23.0__tar.gz → 0.23.2__tar.gz

{dndwright-0.23.0 → dndwright-0.23.2}/CHANGELOG.md

@@ -10,6 +10,47 @@ breaking changes; these will always be noted here.
 
 ## [Unreleased]
 
+## [0.23.2] — 2026-06-06
+
+### Documentation
+- **Two new README/PyPI diagrams.** `assets/compose.svg` shows lego-style components snapping
+  onto the ruleset — typed `set`/`add`/`union` contributions that keep the target node's id, so
+  one snap-in recomputes the whole downstream subtree. `assets/theme-scaling.svg` shows one
+  computation graph re-skinned per setting via `ThemeScalingLayer`: the same `plate` node emerges
+  as AC 18 (traditional / modern, re-flavored) or AC 19 (sci-fi / steampunk) through
+  `input_overrides`, `lookup_overrides`, and display-only `flavor_renames`.
+- **New README sections** — "Composable — snap mini-graphs onto the ruleset" and "Re-skin for
+  any setting — theme scaling" (theme scaling was previously undocumented in the README), plus a
+  `apply_theme_scaling` / `ThemeScalingLayer` row in the feature table. Docs-only; no code change.
+
+## [0.23.1] — 2026-06-06
+
+### Fixed
+- **Critical damage preserves dice modifiers** — `DiceEngine.roll_damage(expr, is_critical=True)`
+  doubled die counts by rebuilding the expression as bare `XdY`, silently dropping per-group
+  `keep`/`drop`/`reroll`/`exploding` flags. A crit on `1d6!+2` now stays exploding (`2d6!+2`)
+  instead of becoming a plain `2d6+2`. As part of the fix, `str(DiceGroup)` now serialises
+  reroll-once as `ro` (was `r`), so the spec round-trips through `parse_expression`.
+- **Species damage immunities mis-categorised** — `_build_species_traits` tagged damage
+  immunities with `category: "resistance"` (condition immunities were already correct); they
+  are now `category: "immunity"`.
+
+### Changed
+- **`compose()` fails loudly on contradictory contributions** — a target that receives both a
+  `union` (set-valued) and an `add`/`set` (numeric) contribution now raises `ValueError` instead
+  of silently dropping the numeric ones.
+
+### Performance
+- **Topological sort** uses a binary heap (`heapq`) instead of re-sorting the ready-queue every
+  iteration — same deterministic order, `O(V·log V + E)` instead of `O(V²·log V)`. (Result is
+  still cached per ruleset, so this only matters the first time a large graph is evaluated.)
+
+### Internal
+- `cli._read_json` closes the file it opens (was leaked); `cli` content lookup calls
+  `categories()` once instead of twice.
+- `assembler.assemble_inputs` copies the ability-score dict once up front rather than on each
+  increase.
+
 ## [0.23.0] — 2026-06-05
 
 ### Added
@@ -413,7 +454,9 @@ from a working application.
 Pure (pydantic + stdlib); no application/framework coupling. Rules content derives
 from the SRD 5.2 (CC-BY-4.0); see NOTICE.
 
-[Unreleased]: https://github.com/sligara7/dndwright/compare/v0.23.0...HEAD
+[Unreleased]: https://github.com/sligara7/dndwright/compare/v0.23.2...HEAD
+[0.23.2]: https://github.com/sligara7/dndwright/compare/v0.23.1...v0.23.2
+[0.23.1]: https://github.com/sligara7/dndwright/compare/v0.23.0...v0.23.1
 [0.23.0]: https://github.com/sligara7/dndwright/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/sligara7/dndwright/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/sligara7/dndwright/compare/v0.20.0...v0.21.0

{dndwright-0.23.0 → dndwright-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dndwright
-Version: 0.23.0
+Version: 0.23.2
 Summary: Domain-neutral D&D 5e (2024) rules & character-sheet computation engine: a data-driven DAG of formulas (ability mods, proficiency, spell DC/slots, HP, AC).
 Project-URL: Homepage, https://github.com/sligara7/dndwright
 Project-URL: Repository, https://github.com/sligara7/dndwright
@@ -161,6 +161,43 @@ and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 1
   <img alt="The dndwright computation graph: ability scores, level, class and equipment flow through ability modifiers and proficiency bonus to saves, skills, spell DC/attack, spell slots, HP, AC and initiative" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/computation-graph.svg">
 </p>
 
+### Composable — snap mini-graphs onto the ruleset
+
+Items, feats and species traits are themselves tiny graphs. `compose()` merges a
+`Component`'s nodes and contributions onto a base ruleset and returns a new, larger
+`Ruleset` — the base is never mutated. Because each contribution keeps its target node's
+**id**, every existing edge downstream re-derives for free: a `set`/`add`/`union` on one
+node ripples out to every modifier, save, skill and attack that depends on it.
+
+<p align="center">
+  <img alt="Components are lego-style mini-graphs that snap onto the dndwright ruleset: a Belt of Giant Strength sets the Strength score, a Ring of Protection adds to Armor Class, and Dwarven Resilience unions in poison resistance — compose() merges them and one snap-in recomputes the whole downstream subtree (strength modifier to athletics, saving throws and melee attack)" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/compose.svg">
+</p>
+
+```python
+from dndwright import DND_5E_2024_RULESET, compose, modifier
+ring = modifier("ring_of_protection", target="armor_class", amount=1)
+rs = compose(DND_5E_2024_RULESET, ring)   # base untouched; AC now aggregates the +1
+```
+
+### Re-skin for any setting — theme scaling
+
+The same engine runs sci-fi, modern-warfare, steampunk or cosmic-horror. A `ThemeScalingLayer`
+folds three kinds of override onto a ruleset via `apply_theme_scaling()` (pure, like `compose`):
+`input_overrides` re-baseline a node's default value, `lookup_overrides` deep-merge into the
+lookup tables (so `plate` armour can read AC 19 instead of 18), and `flavor_renames` relabel
+terms for display **without ever changing a computed value**. The graph's shape never changes —
+only its numbers and names.
+
+<p align="center">
+  <img alt="dndwright theme scaling: one computation graph re-skinned per setting. A ThemeScalingLayer applies input_overrides (re-baseline node defaults), lookup_overrides (merge tables like armor AC and weapon ranges) and flavor_renames (display labels only). The same plate armor node emerges as 'plate AC 18' in traditional D&D, 'tactical body armor AC 18' in modern warfare, 'power armor AC 19' in sci-fi, and 'clockwork full-plate AC 19' in steampunk" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/theme-scaling.svg">
+</p>
+
+```python
+from dndwright import DND_5E_2024_RULESET, apply_theme_scaling, get_theme_scaling
+rs = apply_theme_scaling(DND_5E_2024_RULESET, get_theme_scaling("sci_fi"))
+rs.lookup_tables["armor_base_ac"]["plate"]   # 19 (base is still 18, untouched)
+```
+
 ## What's inside
 
 | Component | What it does |
@@ -172,6 +209,7 @@ and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 1
 | `validate_ruleset` / `assert_valid_ruleset` | Static integrity check for a ruleset (unknown ops, cycles, dangling refs) — catch authoring errors before evaluation. |
 | `compose` / `modifier` / `Component` | Snap mini-graphs (items/feats/traits) onto a ruleset; downstream values cascade. |
 | `component_from_content` | Build a `Component` from a bundled item/feat's `component` field — magic items & feats as data that snap onto a character (constant, dynamic, player-chosen, or *conditional* effects). |
+| `apply_theme_scaling` / `ThemeScalingLayer` / `get_theme_scaling` | Re-skin the ruleset for any setting (sci-fi, modern, steampunk, …): override node defaults & lookup tables and re-flavor names, same graph shape. `PREDEFINED_THEME_SCALING` ships ready-made themes. |
 | `to_mermaid` / `to_dot` | Render the computation DAG as Mermaid or Graphviz DOT — *see* the dependency graph. |
 | `dndwright.dice` | Typed dice engine: parse/roll 5e expressions, attacks, saves, damage, stat arrays. |
 | `dndwright.combat` | Pure combat rules over a frozen `CombatantState`: damage, temp HP, healing, death saves. |

{dndwright-0.23.0 → dndwright-0.23.2}/README.md

@@ -128,6 +128,43 @@ and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 1
   <img alt="The dndwright computation graph: ability scores, level, class and equipment flow through ability modifiers and proficiency bonus to saves, skills, spell DC/attack, spell slots, HP, AC and initiative" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/computation-graph.svg">
 </p>
 
+### Composable — snap mini-graphs onto the ruleset
+
+Items, feats and species traits are themselves tiny graphs. `compose()` merges a
+`Component`'s nodes and contributions onto a base ruleset and returns a new, larger
+`Ruleset` — the base is never mutated. Because each contribution keeps its target node's
+**id**, every existing edge downstream re-derives for free: a `set`/`add`/`union` on one
+node ripples out to every modifier, save, skill and attack that depends on it.
+
+<p align="center">
+  <img alt="Components are lego-style mini-graphs that snap onto the dndwright ruleset: a Belt of Giant Strength sets the Strength score, a Ring of Protection adds to Armor Class, and Dwarven Resilience unions in poison resistance — compose() merges them and one snap-in recomputes the whole downstream subtree (strength modifier to athletics, saving throws and melee attack)" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/compose.svg">
+</p>
+
+```python
+from dndwright import DND_5E_2024_RULESET, compose, modifier
+ring = modifier("ring_of_protection", target="armor_class", amount=1)
+rs = compose(DND_5E_2024_RULESET, ring)   # base untouched; AC now aggregates the +1
+```
+
+### Re-skin for any setting — theme scaling
+
+The same engine runs sci-fi, modern-warfare, steampunk or cosmic-horror. A `ThemeScalingLayer`
+folds three kinds of override onto a ruleset via `apply_theme_scaling()` (pure, like `compose`):
+`input_overrides` re-baseline a node's default value, `lookup_overrides` deep-merge into the
+lookup tables (so `plate` armour can read AC 19 instead of 18), and `flavor_renames` relabel
+terms for display **without ever changing a computed value**. The graph's shape never changes —
+only its numbers and names.
+
+<p align="center">
+  <img alt="dndwright theme scaling: one computation graph re-skinned per setting. A ThemeScalingLayer applies input_overrides (re-baseline node defaults), lookup_overrides (merge tables like armor AC and weapon ranges) and flavor_renames (display labels only). The same plate armor node emerges as 'plate AC 18' in traditional D&D, 'tactical body armor AC 18' in modern warfare, 'power armor AC 19' in sci-fi, and 'clockwork full-plate AC 19' in steampunk" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/theme-scaling.svg">
+</p>
+
+```python
+from dndwright import DND_5E_2024_RULESET, apply_theme_scaling, get_theme_scaling
+rs = apply_theme_scaling(DND_5E_2024_RULESET, get_theme_scaling("sci_fi"))
+rs.lookup_tables["armor_base_ac"]["plate"]   # 19 (base is still 18, untouched)
+```
+
 ## What's inside
 
 | Component | What it does |
@@ -139,6 +176,7 @@ and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 1
 | `validate_ruleset` / `assert_valid_ruleset` | Static integrity check for a ruleset (unknown ops, cycles, dangling refs) — catch authoring errors before evaluation. |
 | `compose` / `modifier` / `Component` | Snap mini-graphs (items/feats/traits) onto a ruleset; downstream values cascade. |
 | `component_from_content` | Build a `Component` from a bundled item/feat's `component` field — magic items & feats as data that snap onto a character (constant, dynamic, player-chosen, or *conditional* effects). |
+| `apply_theme_scaling` / `ThemeScalingLayer` / `get_theme_scaling` | Re-skin the ruleset for any setting (sci-fi, modern, steampunk, …): override node defaults & lookup tables and re-flavor names, same graph shape. `PREDEFINED_THEME_SCALING` ships ready-made themes. |
 | `to_mermaid` / `to_dot` | Render the computation DAG as Mermaid or Graphviz DOT — *see* the dependency graph. |
 | `dndwright.dice` | Typed dice engine: parse/roll 5e expressions, attacks, saves, damage, stat arrays. |
 | `dndwright.combat` | Pure combat rules over a frozen `CombatantState`: damage, temp HP, healing, death saves. |

dndwright-0.23.2/assets/compose.svg

@@ -0,0 +1,121 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 480" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f172a"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#64748b"/>
+    </marker>
+    <marker id="arrowT" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#2dd4bf"/>
+    </marker>
+    <style>
+      .lbl    { fill:#e2e8f0; font-size:13px; }
+      .sub    { fill:#94a3b8; font-size:11px; }
+      .node   { fill:#1e293b; stroke-width:1.5; }
+      .brick  { fill:#1e293b; stroke-width:1.6; }
+      .layer  { fill:#94a3b8; font-size:12px; letter-spacing:.14em; text-transform:uppercase; }
+      .edge   { stroke:#475569; stroke-width:1.5; fill:none; }
+      .casc   { stroke:#2dd4bf; stroke-width:1.8; fill:none; }
+      .mode   { fill:#7dd3fc; font-size:11px; font-family:ui-monospace, SFMono-Regular, Menlo, monospace; }
+      .pill   { fill:#0b1220; }
+      .note   { fill:#2dd4bf; font-size:11.5px; }
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="900" height="480" rx="16" fill="url(#bg)"/>
+
+  <text x="36" y="46" fill="#f8fafc" font-size="26" font-weight="700">dndwright</text>
+  <text x="36" y="72" fill="#94a3b8" font-size="15">Components are mini-graphs that snap onto the ruleset — <tspan fill="#7dd3fc" font-family="ui-monospace, Menlo, monospace">compose()</tspan> merges them and downstream values recompute.</text>
+
+  <!-- column captions -->
+  <text class="layer" x="140" y="112" text-anchor="middle">Components</text>
+  <text class="layer" x="418" y="112" text-anchor="middle">Base graph · targets</text>
+  <text class="layer" x="788" y="112" text-anchor="middle">Cascades to</text>
+
+  <!-- ============ edges (behind nodes) ============ -->
+  <!-- component -> target (snap-in) -->
+  <path class="edge" marker-end="url(#arrow)" d="M240 168 C290 168 296 168 330 168"/>
+  <path class="edge" marker-end="url(#arrow)" d="M240 276 C290 276 296 276 330 276"/>
+  <path class="edge" marker-end="url(#arrow)" d="M240 384 C290 384 296 384 330 384"/>
+  <!-- strength score -> strength mod -> outputs (cascade) -->
+  <path class="casc" marker-end="url(#arrowT)" d="M500 168 C528 168 532 175 552 175"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M708 175 C730 175 726 130 744 130"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M708 175 C730 175 730 175 744 175"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M708 175 C730 175 726 220 744 220"/>
+
+  <!-- mode labels on snap-in edges -->
+  <g>
+    <rect class="pill" x="270" y="150" width="34" height="17" rx="5"/>
+    <text class="mode" x="277" y="162">set</text>
+    <rect class="pill" x="268" y="258" width="40" height="17" rx="5"/>
+    <text class="mode" x="275" y="270">add</text>
+    <rect class="pill" x="262" y="366" width="52" height="17" rx="5"/>
+    <text class="mode" x="269" y="378">union</text>
+  </g>
+
+  <!-- ============ component bricks (lego) ============ -->
+  <!-- Belt of Giant Strength (amber) -->
+  <g>
+    <rect x="56"  y="135" width="16" height="11" rx="4" fill="#f59e0b"/>
+    <rect x="96"  y="135" width="16" height="11" rx="4" fill="#f59e0b"/>
+    <rect x="136" y="135" width="16" height="11" rx="4" fill="#f59e0b"/>
+    <rect x="176" y="135" width="16" height="11" rx="4" fill="#f59e0b"/>
+    <rect class="brick" rx="10" x="40" y="140" width="200" height="56" stroke="#f59e0b"/>
+    <text class="lbl" x="58" y="166">Belt of Giant Strength</text>
+    <text class="sub" x="58" y="184">Strength score = 25</text>
+  </g>
+  <!-- Ring of Protection (rose) -->
+  <g>
+    <rect x="56"  y="243" width="16" height="11" rx="4" fill="#fb7185"/>
+    <rect x="96"  y="243" width="16" height="11" rx="4" fill="#fb7185"/>
+    <rect x="136" y="243" width="16" height="11" rx="4" fill="#fb7185"/>
+    <rect x="176" y="243" width="16" height="11" rx="4" fill="#fb7185"/>
+    <rect class="brick" rx="10" x="40" y="248" width="200" height="56" stroke="#fb7185"/>
+    <text class="lbl" x="58" y="274">Ring of Protection</text>
+    <text class="sub" x="58" y="292">+1 Armor Class</text>
+  </g>
+  <!-- Dwarven Resilience (teal) -->
+  <g>
+    <rect x="56"  y="351" width="16" height="11" rx="4" fill="#2dd4bf"/>
+    <rect x="96"  y="351" width="16" height="11" rx="4" fill="#2dd4bf"/>
+    <rect x="136" y="351" width="16" height="11" rx="4" fill="#2dd4bf"/>
+    <rect x="176" y="351" width="16" height="11" rx="4" fill="#2dd4bf"/>
+    <rect class="brick" rx="10" x="40" y="356" width="200" height="56" stroke="#2dd4bf"/>
+    <text class="lbl" x="58" y="382">Dwarven Resilience</text>
+    <text class="sub" x="58" y="400">+ poison resistance</text>
+  </g>
+
+  <!-- ============ base-graph target nodes ============ -->
+  <g>
+    <!-- Strength score (input, becomes an aggregate) -->
+    <rect class="node" rx="9" x="330" y="150" width="170" height="36" stroke="#f59e0b"/>
+    <text class="lbl" x="346" y="166">Strength score</text>
+    <text class="sub" x="346" y="180">now an aggregate node</text>
+
+    <rect class="node" rx="9" x="330" y="259" width="170" height="34" stroke="#a78bfa"/>
+    <text class="lbl" x="346" y="281">Armor Class</text>
+
+    <rect class="node" rx="9" x="330" y="367" width="170" height="34" stroke="#a78bfa"/>
+    <text class="lbl" x="346" y="389">Resistances</text>
+  </g>
+
+  <!-- ============ derived + cascade outputs ============ -->
+  <g>
+    <rect class="node" rx="9" x="552" y="157" width="156" height="36" stroke="#2dd4bf"/>
+    <text class="lbl" x="568" y="179">Strength modifier</text>
+
+    <rect class="node" rx="9" x="744" y="113" width="140" height="34" stroke="#a78bfa"/>
+    <text class="lbl" x="760" y="135">Athletics</text>
+    <rect class="node" rx="9" x="744" y="158" width="140" height="34" stroke="#a78bfa"/>
+    <text class="lbl" x="760" y="180">STR saving throw</text>
+    <rect class="node" rx="9" x="744" y="203" width="140" height="34" stroke="#a78bfa"/>
+    <text class="lbl" x="760" y="225">Melee attack</text>
+  </g>
+
+  <text class="note" x="552" y="250">One snap-in recomputes the</text>
+  <text class="note" x="552" y="266">whole downstream subtree.</text>
+
+  <text x="36" y="462" fill="#64748b" font-size="12">compose(base, *components) -&gt; a larger Ruleset · pure (the base graph is never mutated) · the target id is kept, so existing edges cascade</text>
+</svg>

dndwright-0.23.2/assets/theme-scaling.svg

@@ -0,0 +1,107 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 480" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f172a"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#64748b"/>
+    </marker>
+    <marker id="arrowT" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#2dd4bf"/>
+    </marker>
+    <style>
+      .lbl   { fill:#e2e8f0; font-size:13px; }
+      .sub   { fill:#94a3b8; font-size:11px; }
+      .node  { fill:#1e293b; stroke-width:1.5; }
+      .layer { fill:#94a3b8; font-size:12px; letter-spacing:.14em; text-transform:uppercase; }
+      .edge  { stroke:#475569; stroke-width:1.5; fill:none; }
+      .casc  { stroke:#2dd4bf; stroke-width:1.8; fill:none; }
+      .mono  { font-size:11.5px; font-family:ui-monospace, SFMono-Regular, Menlo, monospace; }
+      .res   { fill:#7dd3fc; font-size:11px; font-family:ui-monospace, SFMono-Regular, Menlo, monospace; }
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="900" height="480" rx="16" fill="url(#bg)"/>
+
+  <text x="36" y="46" fill="#f8fafc" font-size="26" font-weight="700">dndwright</text>
+  <text x="36" y="72" fill="#94a3b8" font-size="15">One graph, any setting — a <tspan fill="#38bdf8">ThemeScalingLayer</tspan> re-baselines values &amp; lookup tables, and re-flavors names.</text>
+
+  <!-- column captions -->
+  <text class="layer" x="140" y="116" text-anchor="middle">Base ruleset</text>
+  <text class="layer" x="430" y="116" text-anchor="middle">ThemeScalingLayer</text>
+  <text class="layer" x="751" y="116" text-anchor="middle">Same graph, per theme</text>
+
+  <!-- ============ edges ============ -->
+  <!-- base -> lens -->
+  <path class="edge" marker-end="url(#arrow)" d="M240 250 C268 250 272 250 296 250"/>
+  <!-- lens -> per-theme results (cascade) -->
+  <path class="casc" marker-end="url(#arrowT)" d="M560 250 C590 250 592 151 616 151"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M560 250 C590 250 592 211 616 211"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M560 250 C590 250 592 271 616 271"/>
+  <path class="casc" marker-end="url(#arrowT)" d="M560 250 C590 250 592 331 616 331"/>
+
+  <!-- ============ base ruleset ============ -->
+  <g>
+    <rect class="node" rx="9" x="40" y="178" width="200" height="52" stroke="#f59e0b"/>
+    <text class="lbl" x="58" y="202">armor_base_ac (lookup)</text>
+    <text class="res" x="58" y="220">plate = 18</text>
+
+    <path class="edge" marker-end="url(#arrow)" d="M140 230 L140 268"/>
+
+    <rect class="node" rx="9" x="40" y="270" width="200" height="44" stroke="#a78bfa"/>
+    <text class="lbl" x="58" y="297">Armor Class</text>
+
+    <text class="sub" x="140" y="338" text-anchor="middle">138-node DAG · formulas as data</text>
+  </g>
+
+  <!-- ============ ThemeScalingLayer (lens) ============ -->
+  <g>
+    <rect class="node" rx="12" x="296" y="150" width="264" height="212" stroke="#38bdf8"/>
+
+    <circle cx="318" cy="181" r="4" fill="#2dd4bf"/>
+    <text class="mono" x="332" y="185" fill="#7dd3fc">input_overrides</text>
+    <text class="sub"  x="332" y="200">re-baseline a node's default value</text>
+
+    <circle cx="318" cy="227" r="4" fill="#2dd4bf"/>
+    <text class="mono" x="332" y="231" fill="#7dd3fc">lookup_overrides</text>
+    <text class="sub"  x="332" y="246">merge tables: armor AC, weapon ranges</text>
+
+    <circle cx="318" cy="273" r="4" fill="#64748b"/>
+    <text class="mono" x="332" y="277" fill="#7dd3fc">flavor_renames</text>
+    <text class="sub"  x="332" y="292">display label only — never changes math</text>
+
+    <line x1="316" y1="312" x2="540" y2="312" stroke="#334155" stroke-width="1"/>
+    <text class="mono" x="316" y="332" fill="#38bdf8">apply_theme_scaling(rs, layer)</text>
+    <text class="sub"  x="316" y="350">pure — the base graph is untouched</text>
+  </g>
+
+  <!-- ============ per-theme results ============ -->
+  <g>
+    <!-- traditional -->
+    <rect class="node" rx="9" x="616" y="128" width="266" height="46" stroke="#475569"/>
+    <circle cx="634" cy="151" r="4" fill="#94a3b8"/>
+    <text class="lbl" x="648" y="148" fill="#94a3b8">Traditional D&amp;D</text>
+    <text class="res" x="648" y="165" fill="#cbd5e1">plate · AC 18</text>
+
+    <!-- modern warfare -->
+    <rect class="node" rx="9" x="616" y="188" width="266" height="46" stroke="#f59e0b"/>
+    <circle cx="634" cy="211" r="4" fill="#f59e0b"/>
+    <text class="lbl" x="648" y="208" fill="#f59e0b">Modern warfare</text>
+    <text class="res" x="648" y="225" fill="#cbd5e1">tactical body armor · AC 18</text>
+
+    <!-- sci-fi -->
+    <rect class="node" rx="9" x="616" y="248" width="266" height="46" stroke="#38bdf8"/>
+    <circle cx="634" cy="271" r="4" fill="#38bdf8"/>
+    <text class="lbl" x="648" y="268" fill="#38bdf8">Sci-fi</text>
+    <text class="res" x="648" y="285" fill="#cbd5e1">power armor · AC <tspan fill="#2dd4bf" font-weight="700">19</tspan></text>
+
+    <!-- steampunk -->
+    <rect class="node" rx="9" x="616" y="308" width="266" height="46" stroke="#fb7185"/>
+    <circle cx="634" cy="331" r="4" fill="#fb7185"/>
+    <text class="lbl" x="648" y="328" fill="#fb7185">Steampunk</text>
+    <text class="res" x="648" y="345" fill="#cbd5e1">clockwork full-plate · AC <tspan fill="#2dd4bf" font-weight="700">19</tspan></text>
+  </g>
+
+  <text x="36" y="462" fill="#64748b" font-size="12">precedence: explicit input &gt; themed default &gt; original · flavor_renames never change a value · composes with compose()</text>
+</svg>

{dndwright-0.23.0 → dndwright-0.23.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dndwright"
-version = "0.23.0"
+version = "0.23.2"
 description = "Domain-neutral D&D 5e (2024) rules & character-sheet computation engine: a data-driven DAG of formulas (ability mods, proficiency, spell DC/slots, HP, AC)."
 readme = "README.md"
 requires-python = ">=3.10"

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/__init__.py

@@ -100,7 +100,7 @@ from .rules.validation import (
     validate_ruleset,
 )
 
-__version__ = "0.23.0"
+__version__ = "0.23.2"
 
 __all__ = [
     # high-level (dict in -> computed sheet out)

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/cli.py

@@ -23,7 +23,11 @@ from . import __version__
 
 def _read_json(path: str) -> Any:
     """Load JSON from ``path`` ('-' = stdin)."""
-    text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
+    if path == "-":
+        text = sys.stdin.read()
+    else:
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
     return json.loads(text)
 
 
@@ -59,11 +63,12 @@ def _cmd_graph(args: argparse.Namespace) -> int:
 def _cmd_content(args: argparse.Namespace) -> int:
     from .content import categories, load_content
 
+    cats = categories()
     if not args.category:
-        print("\n".join(categories()))
+        print("\n".join(cats))
         return 0
-    if args.category not in categories():
-        print(f"unknown category {args.category!r}; choose from {categories()}",
+    if args.category not in cats:
+        print(f"unknown category {args.category!r}; choose from {cats}",
               file=sys.stderr)
         return 2
     items = load_content(args.category)

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/dice/engine.py

@@ -25,7 +25,7 @@ from __future__ import annotations
 
 import random
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Protocol
 
 # Hard safety bound on reroll/explode loops so a pathological group (e.g. a die
@@ -64,7 +64,7 @@ class DiceGroup:
         if self.drop_lowest:
             s += f"dl{self.drop_lowest}"
         if self.reroll_on:
-            s += f"r{','.join(map(str, self.reroll_on))}"
+            s += f"{'ro' if self.reroll_once else 'r'}{','.join(map(str, self.reroll_on))}"
         if self.exploding:
             s += "!"
         return s
@@ -476,7 +476,12 @@ class DiceEngine:
         """Roll damage; on a crit, double the dice counts (the flat modifier is unchanged)."""
         if is_critical:
             parsed = self.parse_expression(expression)
-            doubled_groups = [f"{g.count * 2}d{g.sides}" for g in parsed.dice_groups]
+            # Double each group's die count while preserving its keep/drop/reroll/explode
+            # flags — str(DiceGroup) is the canonical, round-trippable serialization, so a
+            # crit on e.g. "1d6!+2" stays exploding ("2d6!+2") instead of silently dropping it.
+            doubled_groups = [
+                str(replace(g, count=g.count * 2)) for g in parsed.dice_groups
+            ]
             if doubled_groups:
                 doubled_expr = "+".join(doubled_groups)
                 if parsed.modifier:

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/rules/adapters.py

@@ -496,7 +496,7 @@ def _build_species_traits(species_data: dict) -> list[dict]:
         for c in sp_immunities.get("conditions", []):
             result.append({"name": f"{c} Immunity", "category": "immunity"})
         for d in sp_immunities.get("damage", []):
-            result.append({"name": f"{d} Immunity", "category": "resistance"})
+            result.append({"name": f"{d} Immunity", "category": "immunity"})
     elif isinstance(sp_immunities, list):
         for im in sp_immunities:
             result.append({"name": f"{im} Immunity", "category": "immunity"})

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/rules/assembler.py

@@ -67,7 +67,8 @@ def assemble_character_inputs(
         Dict keyed by computation node IDs, ready for evaluate().
     """
     inputs: dict[str, Any] = {}
-    scores = ability_scores or {
+    # Copy once up front so the caller's dict is never mutated by the increases below.
+    scores = dict(ability_scores) if ability_scores else {
         "strength": 10, "dexterity": 10, "constitution": 10,
         "intelligence": 10, "wisdom": 10, "charisma": 10,
     }
@@ -78,7 +79,6 @@ def assemble_character_inputs(
     if background_mechanics:
         for ability, increase in background_mechanics.ability_score_increases.items():
             if ability in scores:
-                scores = dict(scores)  # copy to avoid mutating original
                 scores[ability] = scores[ability] + increase
 
     # ------------------------------------------------------------------
@@ -88,7 +88,6 @@ def assemble_character_inputs(
         for feat in feats:
             for ability, increase in feat.grants_ability_increase.items():
                 if ability in scores:
-                    scores = dict(scores)
                     scores[ability] = scores[ability] + increase
 
     # ------------------------------------------------------------------

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/rules/compose.py

@@ -118,6 +118,14 @@ def _aggregate_nodes(
             base = [ov_id]
 
     if unions:
+        if adds or sets:
+            # union is for set-valued channels (resistances, languages); add/set are
+            # numeric. Mixing them on one target is a modelling error — fail loudly
+            # rather than silently dropping the add/set contributions.
+            raise ValueError(
+                f"target {target!r} mixes union with add/set contributions; "
+                "a target must be either set-valued or numeric, not both"
+            )
         formula = FormulaSpec(op="union", args=base + unions)
     elif adds and sets:
         sum_id = f"{target}.__sum__"

{dndwright-0.23.0 → dndwright-0.23.2}/src/dndwright/rules/evaluator.py

@@ -10,6 +10,7 @@ No I/O, no side effects, trivially testable.
 
 from __future__ import annotations
 
+import heapq
 import weakref
 from typing import Any
 
@@ -59,19 +60,20 @@ def _topological_sort(nodes: dict[str, ComputationNode]) -> list[str]:
             if dep in dependents:
                 dependents[dep].append(nid)
 
-    # Start with nodes that have no dependencies
+    # Start with nodes that have no dependencies. A min-heap keeps the pop order
+    # deterministic (always the lexicographically smallest ready node) in O(log n)
+    # per step, instead of re-sorting the whole queue on every iteration.
     queue = [nid for nid, deg in in_degree.items() if deg == 0]
+    heapq.heapify(queue)
     order: list[str] = []
 
     while queue:
-        # Sort for deterministic order
-        queue.sort()
-        nid = queue.pop(0)
+        nid = heapq.heappop(queue)
         order.append(nid)
         for dep_nid in dependents[nid]:
             in_degree[dep_nid] -= 1
             if in_degree[dep_nid] == 0:
-                queue.append(dep_nid)
+                heapq.heappush(queue, dep_nid)
 
     if len(order) != len(nodes):
         missing = set(nodes.keys()) - set(order)