@downdraft/engine 0.0.0 → 0.1.0

package/libraries/sand/src/rules/builtin-rules.ts

@@ -0,0 +1,132 @@
+// ============================================================================
+// Built-in reaction rules — migrated from applyReactions().
+//
+// These rules replace the hardcoded if-else chains in applyReactions() with
+// a declarative format. The rule engine evaluates conditions and executes
+// actions based on these definitions.
+//
+// Complex reactions from applySpecialReactions() remain as custom handlers
+// in the rule engine — they use flood-fill, radius effects, and other logic
+// that's not easily expressed as simple rules.
+// ============================================================================
+
+import { IS_FIRE, IS_HOT, MAT_FLAGS, MAT_FLAMMABLE, Material } from "../materials";
+import { DIR, type ReactionRule } from "./rule-types";
+
+export const builtinRules: ReactionRule[] = [
+  // --- Water reactions ---
+  // Water + Lava → Steam + Obsidian (highest priority). Rapid quenching of
+  // lava by water produces volcanic glass (obsidian) rather than plain stone.
+  {
+    material: Material.Water,
+    priority: -10,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "material", mat: Material.Lava } }],
+    actions: [
+      { type: "transform_self", mat: Material.Steam, lifetime: 120 },
+      { type: "transform_neighbor", mat: Material.Obsidian, match: { kind: "material", mat: Material.Lava } },
+    ],
+  },
+  // Water + Fire → Steam + Smoke (chance-based, extinguishes flame)
+  {
+    material: Material.Water,
+    priority: -5,
+    chance: 0.25,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "is_fire" } }],
+    actions: [
+      { type: "transform_self", mat: Material.Steam, lifetime: 120 },
+      { type: "transform_neighbor", mat: Material.Smoke, lifetime: 40, match: { kind: "is_fire" } },
+    ],
+  },
+  // Water + high temp → Steam (evaporation)
+  {
+    material: Material.Water,
+    priority: -3,
+    minTemp: 1.5,
+    chance: 0.02, // simplified — original scales with temp
+    actions: [{ type: "transform_self", mat: Material.Steam, lifetime: 120 }],
+  },
+  // Water + Plant → Plant (growth)
+  {
+    material: Material.Water,
+    priority: -2,
+    chance: 0.02,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "material", mat: Material.Plant } }],
+    actions: [{ type: "transform_self", mat: Material.Plant }],
+  },
+  // Water + cold neighbor (dry ice / liquid nitrogen) → Ice (contact freezing).
+  // Higher priority and much higher chance than the ambient-cold rule below —
+  // direct contact with an active coolant freezes water quickly.
+  {
+    material: Material.Water,
+    priority: -2,
+    chance: 0.25,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "is_cold" } }],
+    actions: [{ type: "transform_self", mat: Material.Ice }],
+  },
+  // Water + low ambient temp → Ice (freezing)
+  {
+    material: Material.Water,
+    priority: -1,
+    maxTemp: 0.35,
+    chance: 0.02, // simplified — original scales with temp
+    actions: [{ type: "transform_self", mat: Material.Ice }],
+  },
+
+  // --- Fire reactions ---
+  // Fire + low temp → Smoke (dies faster in cold)
+  {
+    material: Material.Fire,
+    priority: 0,
+    maxTemp: 0.5,
+    chance: 0.05, // simplified — original scales with temp
+    actions: [{ type: "transform_self", mat: Material.Smoke, lifetime: 60 }],
+  },
+  // Also applies to FuseFire and BurningOil (IS_FIRE class)
+  {
+    material: Material.FuseFire,
+    priority: 0,
+    maxTemp: 0.5,
+    chance: 0.05,
+    actions: [{ type: "transform_self", mat: Material.Smoke, lifetime: 60 }],
+  },
+  {
+    material: Material.BurningOil,
+    priority: 0,
+    maxTemp: 0.5,
+    chance: 0.05,
+    actions: [{ type: "transform_self", mat: Material.Smoke, lifetime: 60 }],
+  },
+
+  // --- Ice reactions ---
+  // Ice + hot neighbor → Water (melts)
+  {
+    material: Material.Ice,
+    priority: 0,
+    chance: 0.3,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "is_hot" } }],
+    actions: [{ type: "transform_self", mat: Material.Water }],
+  },
+  // Ice + high ambient temp → Water (melts)
+  {
+    material: Material.Ice,
+    priority: 1,
+    minTemp: 1.3,
+    chance: 0.02, // simplified — original scales with temp
+    actions: [{ type: "transform_self", mat: Material.Water }],
+  },
+
+  // --- Lava + cold neighbor → Obsidian (rapid quench by dry ice / LN2 / ice / snow) ---
+  // Water contact is handled by the water-side rule above (water + lava →
+  // steam + obsidian). This handles lava touching a cold solid directly.
+  {
+    material: Material.Lava,
+    priority: -10,
+    chance: 0.3,
+    requireNeighbors: [{ directions: DIR.ALL_8, match: { kind: "is_cold" } }],
+    actions: [{ type: "transform_self", mat: Material.Obsidian }],
+  },
+];
+
+// Re-export material flags for the rule engine
+export { IS_FIRE, IS_HOT, MAT_FLAGS, MAT_FLAMMABLE };
+

package/libraries/sand/src/rules/rule-compiler.ts

@@ -0,0 +1,162 @@
+// ============================================================================
+// Rule compiler — compiles ReactionRule[] into typed-array lookup tables.
+//
+// The compiler organizes rules by material for O(1) lookup in the hot path.
+// Each material gets a contiguous slice of the flat rule array, so the engine
+// can dispatch to the right rules with a simple bounds check.
+// ============================================================================
+
+import { MAX_MATERIAL } from "../materials";
+import type { ReactionRule } from "./rule-types";
+
+export interface CompiledRule {
+  // Condition data
+  hasChance: boolean;
+  chance: number;
+  minTemp: number;  // -Infinity = no min
+  maxTemp: number;  // +Infinity = no max
+  // Neighbor requirements (precompiled to flat arrays for cache efficiency)
+  neighborCount: number;
+  // For each neighbor requirement:
+  neighborDirs: Uint8Array;     // DIR bitmask
+  neighborMatchKind: Uint8Array; // 0=material, 1=class, 2=is_hot, 3=is_fire, 4=not_material, 5=not_wall, 6=is_cold
+  neighborMatchValue: Uint32Array; // material id or flag bit
+  neighborMinCount: Uint8Array;
+  // Actions (flat arrays)
+  actionCount: number;
+  actionTypes: Uint8Array;      // 0=transform_self, 1=transform_neighbor, 2=transform_first_matching, 3=clear_self, 4=clear_neighbor, 5=explode, 6=impulse
+  actionMat: Uint32Array;       // target material for transform actions
+  actionLifetime: Uint32Array;  // target lifetime (0 = use default)
+  actionRadius: Uint32Array;    // radius for explode/impulse
+  actionStrength: Float32Array; // strength for impulse
+  // Match data for transform_neighbor/clear_neighbor actions
+  actionMatchKind: Uint8Array;
+  actionMatchValue: Uint32Array;
+}
+
+export interface CompiledRuleSet {
+  // ruleIndices[mat] = start index into the rules array
+  ruleIndices: Int32Array;  // length MAX_MATERIAL+1, -1 = no rules
+  ruleCounts: Uint8Array;   // length MAX_MATERIAL+1
+  rules: CompiledRule[];
+}
+
+const MAX_NEIGHBORS = 8;
+const MAX_ACTIONS = 8;
+
+export function compileRules(allRules: ReactionRule[]): CompiledRuleSet {
+  // Group rules by material
+  const byMaterial: ReactionRule[][] = new Array(MAX_MATERIAL + 1);
+  allRules.forEach((rule) => {
+    if (!byMaterial[rule.material]) byMaterial[rule.material] = [];
+    byMaterial[rule.material].push(rule);
+  });
+
+  const ruleIndices = new Int32Array(MAX_MATERIAL + 1).fill(-1);
+  const ruleCounts = new Uint8Array(MAX_MATERIAL + 1);
+  const compiled: CompiledRule[] = [];
+
+  let cursor = 0;
+  for (let mat = 0; mat <= MAX_MATERIAL; mat++) {
+    const rules = byMaterial[mat];
+    if (!rules || rules.length === 0) continue;
+    // Sort by priority (lower = higher priority)
+    rules.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    ruleIndices[mat] = cursor;
+    ruleCounts[mat] = rules.length;
+    rules.forEach((rule) => {
+      compiled.push(compileRule(rule));
+      cursor++;
+    });
+  }
+
+  return { ruleIndices, ruleCounts, rules: compiled };
+}
+
+function compileRule(rule: ReactionRule): CompiledRule {
+  const neighborReqs = rule.requireNeighbors ?? [];
+  const nc = Math.min(neighborReqs.length, MAX_NEIGHBORS);
+  const actions = rule.actions;
+  const ac = Math.min(actions.length, MAX_ACTIONS);
+
+  const neighborDirs = new Uint8Array(MAX_NEIGHBORS);
+  const neighborMatchKind = new Uint8Array(MAX_NEIGHBORS);
+  const neighborMatchValue = new Uint32Array(MAX_NEIGHBORS);
+  const neighborMinCount = new Uint8Array(MAX_NEIGHBORS);
+
+  for (let i = 0; i < nc; i++) {
+    const req = neighborReqs[i];
+    neighborDirs[i] = req.directions;
+    neighborMinCount[i] = req.minCount ?? 1;
+    switch (req.match.kind) {
+      case "material": neighborMatchKind[i] = 0; neighborMatchValue[i] = req.match.mat; break;
+      case "material_class": neighborMatchKind[i] = 1; neighborMatchValue[i] = req.match.flag; break;
+      case "is_hot": neighborMatchKind[i] = 2; break;
+      case "is_fire": neighborMatchKind[i] = 3; break;
+      case "is_cold": neighborMatchKind[i] = 6; break;
+      case "not_material": neighborMatchKind[i] = 4; neighborMatchValue[i] = req.match.mat; break;
+      case "not_wall": neighborMatchKind[i] = 5; break;
+    }
+  }
+
+  const actionTypes = new Uint8Array(MAX_ACTIONS);
+  const actionMat = new Uint32Array(MAX_ACTIONS);
+  const actionLifetime = new Uint32Array(MAX_ACTIONS);
+  const actionRadius = new Uint32Array(MAX_ACTIONS);
+  const actionStrength = new Float32Array(MAX_ACTIONS);
+  const actionMatchKind = new Uint8Array(MAX_ACTIONS);
+  const actionMatchValue = new Uint32Array(MAX_ACTIONS);
+
+  for (let i = 0; i < ac; i++) {
+    const action = actions[i];
+    switch (action.type) {
+      case "transform_self":
+        actionTypes[i] = 0; actionMat[i] = action.mat; actionLifetime[i] = action.lifetime ?? 0; break;
+      case "transform_neighbor":
+        actionTypes[i] = 1; actionMat[i] = action.mat; actionLifetime[i] = action.lifetime ?? 0;
+        setMatch(action.match, i, actionMatchKind, actionMatchValue); break;
+      case "transform_first_matching_neighbor":
+        actionTypes[i] = 2; actionMat[i] = action.mat; actionLifetime[i] = action.lifetime ?? 0;
+        setMatch(action.match, i, actionMatchKind, actionMatchValue); break;
+      case "clear_self":
+        actionTypes[i] = 3; break;
+      case "clear_neighbor":
+        actionTypes[i] = 4; setMatch(action.match, i, actionMatchKind, actionMatchValue); break;
+      case "explode":
+        actionTypes[i] = 5; actionRadius[i] = action.radius; break;
+      case "impulse":
+        actionTypes[i] = 6; actionRadius[i] = action.radius; actionStrength[i] = action.strength; break;
+    }
+  }
+
+  return {
+    hasChance: rule.chance !== undefined,
+    chance: rule.chance ?? 1,
+    minTemp: rule.minTemp ?? -Infinity,
+    maxTemp: rule.maxTemp ?? Infinity,
+    neighborCount: nc,
+    neighborDirs, neighborMatchKind, neighborMatchValue, neighborMinCount,
+    actionCount: ac,
+    actionTypes, actionMat, actionLifetime, actionRadius, actionStrength,
+    actionMatchKind, actionMatchValue,
+  };
+}
+
+function setMatch(
+  match: ReactionRule["actions"][0] extends infer A
+    ? A extends { match: infer M } ? M : never : never,
+  i: number,
+  kinds: Uint8Array,
+  values: Uint32Array,
+): void {
+  if (!match) return;
+  switch (match.kind) {
+    case "material": kinds[i] = 0; values[i] = match.mat; break;
+    case "material_class": kinds[i] = 1; values[i] = match.flag; break;
+    case "is_hot": kinds[i] = 2; break;
+    case "is_fire": kinds[i] = 3; break;
+    case "is_cold": kinds[i] = 6; break;
+    case "not_material": kinds[i] = 4; values[i] = match.mat; break;
+    case "not_wall": kinds[i] = 5; break;
+  }
+}

package/libraries/sand/src/rules/rule-engine.ts

@@ -0,0 +1,231 @@
+// ============================================================================
+// Rule engine — evaluates compiled rules for each active cell.
+//
+// Replaces applyReactions() with a data-driven dispatch. The engine iterates
+// the active-cell list, looks up rules for each material, evaluates conditions,
+// and executes actions.
+//
+// Complex reactions from applySpecialReactions() are handled as custom
+// material-specific handlers that run after the data-driven rules. This allows
+// gradual migration — simple reactions move to the rule system, complex ones
+// stay as optimized code.
+// ============================================================================
+
+import {
+    packCell
+} from "../cell";
+import {
+    IS_COLD,
+    IS_FIRE,
+    IS_HOT,
+    MAT_FLAGS,
+    MAT_LIFETIME,
+    Material
+} from "../materials";
+import type { SandWorld } from "../sand-world";
+import { builtinRules } from "./builtin-rules";
+import { compileRules, type CompiledRule, type CompiledRuleSet } from "./rule-compiler";
+
+// Direction offsets for the 8 neighbors, indexed by DIR bitmask bit position.
+// Bit 0 = N (0,-1), Bit 1 = S (0,+1), Bit 2 = E (+1,0), Bit 3 = W (-1,0),
+// Bit 4 = NE (+1,-1), Bit 5 = NW (-1,-1), Bit 6 = SE (+1,+1), Bit 7 = SW (-1,+1)
+const DIR_DX = [0, 0, 1, -1, 1, -1, 1, -1];
+const DIR_DY = [-1, 1, 0, 0, -1, -1, 1, 1];
+
+export class RuleEngine {
+  private compiled: CompiledRuleSet;
+
+  constructor() {
+    this.compiled = compileRules(builtinRules);
+  }
+
+  /**
+   * Execute data-driven rules for all active cells.
+   * Replaces SandWorld.applyReactions().
+   */
+  execute(world: SandWorld): void {
+    const W = world.W, H = world.H;
+    const grid = world.grid;
+    const fields = world.fields;
+    const active = world.getActiveCells();
+    const count = world.getActiveCount();
+    const rng = world.getRng();
+    const compiled = this.compiled;
+    const rules = compiled.rules;
+    const ruleIndices = compiled.ruleIndices;
+    const ruleCounts = compiled.ruleCounts;
+
+    for (let a = 0; a < count; a++) {
+      const idx = active[a];
+      const packed = grid[idx];
+      if (packed === 0) continue;
+
+      const mat = packed & 0xff;
+      if (mat === Material.Empty) continue;
+
+      // Look up rules for this material
+      const ruleStart = ruleIndices[mat];
+      if (ruleStart < 0) continue;
+      const ruleCount = ruleCounts[mat];
+
+      const fi = idx * 4;
+      const temp = fields[fi + 1] / 128; // FIELD.TEMP = 1
+      const x = idx % W;
+      const y = (idx / W) | 0;
+
+      for (let r = 0; r < ruleCount; r++) {
+        const rule = rules[ruleStart + r];
+
+        // Check temperature bounds
+        if (temp < rule.minTemp || temp > rule.maxTemp) continue;
+
+        // Check chance gate
+        if (rule.hasChance && rng.random() >= rule.chance) continue;
+
+        // Check neighbor requirements
+        if (rule.neighborCount > 0) {
+          if (!checkNeighbors(rule, grid, W, H, x, y)) continue;
+        }
+
+        // Execute actions
+        executeActions(rule, world, grid, W, H, x, y, idx, mat, rng);
+        break; // only one rule fires per cell per frame
+      }
+    }
+  }
+}
+
+/** Check all neighbor requirements for a rule. */
+function checkNeighbors(rule: CompiledRule, grid: Uint32Array, W: number, H: number, x: number, y: number): boolean {
+  for (let n = 0; n < rule.neighborCount; n++) {
+    const dirs = rule.neighborDirs[n];
+    const matchKind = rule.neighborMatchKind[n];
+    const matchValue = rule.neighborMatchValue[n];
+    const minCount = rule.neighborMinCount[n];
+
+    let found = 0;
+    // Check each direction in the bitmask
+    for (let d = 0; d < 8; d++) {
+      if (!(dirs & (1 << d))) continue;
+      const nx = x + DIR_DX[d];
+      const ny = y + DIR_DY[d];
+      if (nx < 0 || nx >= W || ny < 0 || ny >= H) continue;
+      const nMat = grid[ny * W + nx] & 0xff;
+      if (matchNeighbor(matchKind, matchValue, nMat)) {
+        found++;
+        if (found >= minCount) break;
+      }
+    }
+    if (found < minCount) return false;
+  }
+  return true;
+}
+
+/** Check if a neighbor material matches the requirement. */
+function matchNeighbor(kind: number, value: number, nMat: number): boolean {
+  switch (kind) {
+    case 0: return nMat === value;          // material
+    case 1: return (MAT_FLAGS[nMat] & value) !== 0;  // material_class
+    case 2: return IS_HOT[nMat] !== 0;      // is_hot
+    case 3: return IS_FIRE[nMat] !== 0;     // is_fire
+    case 4: return nMat !== value;          // not_material
+    case 5: return nMat !== Material.Wall;  // not_wall
+    case 6: return IS_COLD[nMat] !== 0;     // is_cold
+    default: return false;
+  }
+}
+
+/** Execute all actions for a rule. */
+function executeActions(
+  rule: CompiledRule,
+  world: SandWorld,
+  grid: Uint32Array,
+  W: number, H: number,
+  x: number, y: number,
+  idx: number,
+  mat: number,
+  rng: { randomShade(): number; random(): number },
+): void {
+  // Write bounds for strip mode — neighbor transforms that would write
+  // outside the strip are skipped (the coordinator's boundary cleanup
+  // handles them). Self transforms are always safe (the cell is in the strip).
+  const writeXMin = world.writeXMin;
+  const writeXMax = world.writeXMax;
+  for (let i = 0; i < rule.actionCount; i++) {
+    const type = rule.actionTypes[i];
+    switch (type) {
+      case 0: { // transform_self
+        const newMat = rule.actionMat[i];
+        const lt = rule.actionLifetime[i] || MAT_LIFETIME[newMat];
+        grid[idx] = packCell(newMat, lt, rng.randomShade());
+        break;
+      }
+      case 1: { // transform_neighbor (all matching neighbors)
+        const newMat = rule.actionMat[i];
+        const lt = rule.actionLifetime[i] || MAT_LIFETIME[newMat];
+        const mk = rule.actionMatchKind[i];
+        const mv = rule.actionMatchValue[i];
+        for (let d = 0; d < 8; d++) {
+          const nx = x + DIR_DX[d];
+          const ny = y + DIR_DY[d];
+          if (nx < 0 || nx >= W || ny < 0 || ny >= H) continue;
+          if (nx < writeXMin || nx >= writeXMax) continue;
+          const ni = ny * W + nx;
+          const nMat = grid[ni] & 0xff;
+          if (matchNeighbor(mk, mv, nMat)) {
+            grid[ni] = packCell(newMat, lt, rng.randomShade());
+          }
+        }
+        break;
+      }
+      case 2: { // transform_first_matching_neighbor
+        const newMat = rule.actionMat[i];
+        const lt = rule.actionLifetime[i] || MAT_LIFETIME[newMat];
+        const mk = rule.actionMatchKind[i];
+        const mv = rule.actionMatchValue[i];
+        for (let d = 0; d < 8; d++) {
+          const nx = x + DIR_DX[d];
+          const ny = y + DIR_DY[d];
+          if (nx < 0 || nx >= W || ny < 0 || ny >= H) continue;
+          if (nx < writeXMin || nx >= writeXMax) continue;
+          const ni = ny * W + nx;
+          const nMat = grid[ni] & 0xff;
+          if (matchNeighbor(mk, mv, nMat)) {
+            grid[ni] = packCell(newMat, lt, rng.randomShade());
+            break;
+          }
+        }
+        break;
+      }
+      case 3: { // clear_self
+        grid[idx] = 0;
+        break;
+      }
+      case 4: { // clear_neighbor
+        const mk = rule.actionMatchKind[i];
+        const mv = rule.actionMatchValue[i];
+        for (let d = 0; d < 8; d++) {
+          const nx = x + DIR_DX[d];
+          const ny = y + DIR_DY[d];
+          if (nx < 0 || nx >= W || ny < 0 || ny >= H) continue;
+          if (nx < writeXMin || nx >= writeXMax) continue;
+          const ni = ny * W + nx;
+          const nMat = grid[ni] & 0xff;
+          if (matchNeighbor(mk, mv, nMat)) {
+            grid[ni] = 0;
+          }
+        }
+        break;
+      }
+      case 5: { // explode
+        // Delegate to world's explode method via reflection
+        (world as any).explode(x, y, rule.actionRadius[i]);
+        break;
+      }
+      case 6: { // impulse
+        (world as any).applyImpulse(x, y, rule.actionRadius[i], rule.actionStrength[i]);
+        break;
+      }
+    }
+  }
+}

package/libraries/sand/src/rules/rule-types.ts

@@ -0,0 +1,87 @@
+// ============================================================================
+// Rule system type definitions.
+//
+// The data-driven rule system replaces hardcoded if-else chains in
+// applyReactions() with a declarative rule format. Rules are compiled into
+// typed-array lookup tables for hot-path performance.
+//
+// Each rule specifies:
+//   - The material it applies to
+//   - Conditions (chance, temperature, neighbor requirements)
+//   - Actions (transform self, transform neighbor, etc.)
+// ============================================================================
+
+import type { Material } from "../materials";
+
+/** Direction bitmask for neighbor requirements. */
+export const DIR = {
+  N: 0x01,    // (0, -1)
+  S: 0x02,    // (0, +1)
+  E: 0x04,    // (+1, 0)
+  W: 0x08,    // (-1, 0)
+  NE: 0x10,   // (+1, -1)
+  NW: 0x20,   // (-1, -1)
+  SE: 0x40,   // (+1, +1)
+  SW: 0x80,   // (-1, +1)
+  ALL_4: 0x0F,
+  ALL_8: 0xFF,
+  HORIZONTAL: 0x0C,
+  VERTICAL: 0x03,
+} as const;
+
+/** How to match a neighbor. */
+export type NeighborMatch =
+  | { kind: "material"; mat: Material }
+  | { kind: "material_class"; flag: number }  // MAT_FLAGS bit (e.g. MAT_FLAMMABLE)
+  | { kind: "is_hot" }                        // IS_HOT[mat]
+  | { kind: "is_fire" }                       // IS_FIRE[mat]
+  | { kind: "is_cold" }                       // IS_COLD[mat] (DryIce, LiquidNitrogen, Ice, Snow)
+  | { kind: "not_material"; mat: Material }
+  | { kind: "not_wall" };
+
+/** A neighbor requirement: look in certain directions for a match. */
+export interface NeighborRequirement {
+  directions: number;  // DIR bitmask
+  match: NeighborMatch;
+  minCount?: number;   // default 1
+}
+
+/** Action types for reactions. */
+export type ReactionAction =
+  | { type: "transform_self"; mat: Material; lifetime?: number }
+  | { type: "transform_neighbor"; mat: Material; lifetime?: number; match: NeighborMatch }
+  | { type: "transform_first_matching_neighbor"; mat: Material; lifetime?: number; match: NeighborMatch }
+  | { type: "clear_self" }
+  | { type: "clear_neighbor"; match: NeighborMatch }
+  | { type: "explode"; radius: number }
+  | { type: "impulse"; radius: number; strength: number };
+
+/** A single reaction rule. */
+export interface ReactionRule {
+  /** The material this rule applies to. */
+  material: Material;
+  /** Optional chance gate (0-1). If omitted, always fires when conditions met. */
+  chance?: number;
+  /** Minimum temperature (1.0 = normal). */
+  minTemp?: number;
+  /** Maximum temperature (1.0 = normal). */
+  maxTemp?: number;
+  /** Neighbor requirements — all must be satisfied. */
+  requireNeighbors?: NeighborRequirement[];
+  /** Actions to execute when the rule fires. */
+  actions: ReactionAction[];
+  /** Optional priority (lower = higher priority). Default 0. */
+  priority?: number;
+}
+
+/** Context passed to the rule engine for each cell. */
+export interface ReactionContext {
+  idx: number;
+  x: number;
+  y: number;
+  mat: number;
+  lifetime: number;
+  flags: number;
+  temp: number;  // normalized 0-2 (1.0 = normal)
+  frame: number;
+}