---
description: Chemistry engine — real science constraints and data patterns
globs: src/chemistry/**/*.ts
alwaysApply: false
---

# Chemistry Engine Rules

## Scientific Accuracy
All chemical data must be **real** (simplified, never fabricated):
- Element properties: atomic number, mass, electronegativity, group, period
- Reactions: real products, real conditions (temperature, catalyst)
- Failed reactions return a **reason**: "Requires catalyst", "Insufficient energy"

## Element Interface
```typescript
interface Element {
  symbol: string;           // "Na"
  name: string;             // "Sodium"
  atomicNumber: number;     // 11
  atomicMass: number;       // 22.99
  electronegativity: number;
  category: ElementCategory;
  state: MatterState;       // at room temperature
  color: string;            // hex for rendering
}
```

## Reaction Lookup
Reactions indexed by **sorted reactant key** for O(1) lookup:
```typescript
// "Cl+Na" → { products: [{ symbol: "NaCl", ... }], ... }
function reactionKey(symbols: string[]): string {
  return [...symbols].sort().join('+');
}
```

## Every Reaction Includes
- `description`: human-readable explanation of the science
- `failureReason`: if conditions not met, explain WHY (this is the teaching mechanism)