physbox-mcp 2.0.0__tar.gz

physbox_mcp-2.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: physbox-mcp
+Version: 2.0.0
+Summary: PhysBox: MCP - Model Context Protocol server for local simulation apps
+Author-email: Boab <boab@example.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: websockets>=12.0
+
+# PhysBox: MCP
+
+PhysBox: MCP is a Model Context Protocol (MCP) server that enables LLMs and MCP clients (such as Claude Code or Claude Desktop) to interact programmatically with the three simulation web applications in the browser:
+
+| Application | Production URL | Description |
+|---|---|---|
+| **Flux** | [flux.physbox.io](https://flux.physbox.io) | Discrete-event / system-dynamics simulation (interactive React Flow graph) |
+| **Volt** | [volt.physbox.io](https://volt.physbox.io) | SPICE circuit simulation (powered by NgSpice WASM in browser) |
+| **Mesh** | [mesh.physbox.io](https://mesh.physbox.io) | Rigid-body physics simulation (powered by MuJoCo WASM in browser) |
+
+All communication is handled via JSON over WebSockets directly to the web app in your browser—no browser automation or DOM scraping is needed.
+
+---
+
+## How It Works
+
+PhysBox: MCP functions as a local companion server that establishes a WebSocket relay on port `3142`. 
+
+When you open any of the simulation web apps, they connect directly to this WebSocket relay. When an MCP client executes a tool call, the command flows from the client to the companion server, gets forwarded to the active browser tab, and the results flow back.
+
+```
+MCP Client (e.g. Claude Desktop)
+  └── spawns → physbox-mcp (stdio)
+                 └── WebSocket Server (ws://localhost:3142)
+                                ├── Flux
+                                ├── Volt
+                                └── Mesh
+```
+
+---
+
+## Installation
+
+Install the companion server directly from PyPI:
+
+```bash
+pip install physbox-mcp
+```
+
+---
+
+## Usage & Setup
+
+### 1. Open the Web Applications
+Launch or access the simulation web applications in your web browser:
+*   **Flux:** [flux.physbox.io](https://flux.physbox.io)
+*   **Volt:** [volt.physbox.io](https://volt.physbox.io)
+*   **Mesh:** [mesh.physbox.io](https://mesh.physbox.io)
+
+As soon as a page finishes loading, it automatically registers with the companion WebSocket server.
+
+### 2. Configure Your MCP Client
+
+#### For Claude Desktop
+Add the following block to your Claude Desktop configuration file (typically located at `AppData/Roaming/Claude/claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "physbox-mcp": {
+      "command": "physbox-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+#### For Claude Code
+Add a `.mcp.json` file to your project root (or update your global configuration at `~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "physbox-mcp": {
+      "type": "stdio",
+      "command": "physbox-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+### 3. Run the Companion Server Manually (Optional)
+If you are running the server in HTTP mode rather than Stdio, you can run:
+
+```bash
+# Starts HTTP server listening on port 3141 (default)
+physbox-mcp
+```
+
+Or configure custom port parameters:
+```bash
+physbox-mcp --port=4000
+```
+
+---
+
+## Development & Contribution
+For instructions on local development, modifying schemas, extending tool definitions, and manual builds, please refer to [README_DEV.md](file:///wsl.localhost/Ubuntu-20.04/home/boab/expt_mcp/README_DEV.md).

physbox_mcp-2.0.0/README.md

@@ -0,0 +1,99 @@
+# PhysBox: MCP
+
+PhysBox: MCP is a Model Context Protocol (MCP) server that enables LLMs and MCP clients (such as Claude Code or Claude Desktop) to interact programmatically with the three simulation web applications in the browser:
+
+| Application | Production URL | Description |
+|---|---|---|
+| **Flux** | [flux.physbox.io](https://flux.physbox.io) | Discrete-event / system-dynamics simulation (interactive React Flow graph) |
+| **Volt** | [volt.physbox.io](https://volt.physbox.io) | SPICE circuit simulation (powered by NgSpice WASM in browser) |
+| **Mesh** | [mesh.physbox.io](https://mesh.physbox.io) | Rigid-body physics simulation (powered by MuJoCo WASM in browser) |
+
+All communication is handled via JSON over WebSockets directly to the web app in your browser—no browser automation or DOM scraping is needed.
+
+---
+
+## How It Works
+
+PhysBox: MCP functions as a local companion server that establishes a WebSocket relay on port `3142`. 
+
+When you open any of the simulation web apps, they connect directly to this WebSocket relay. When an MCP client executes a tool call, the command flows from the client to the companion server, gets forwarded to the active browser tab, and the results flow back.
+
+```
+MCP Client (e.g. Claude Desktop)
+  └── spawns → physbox-mcp (stdio)
+                 └── WebSocket Server (ws://localhost:3142)
+                                ├── Flux
+                                ├── Volt
+                                └── Mesh
+```
+
+---
+
+## Installation
+
+Install the companion server directly from PyPI:
+
+```bash
+pip install physbox-mcp
+```
+
+---
+
+## Usage & Setup
+
+### 1. Open the Web Applications
+Launch or access the simulation web applications in your web browser:
+*   **Flux:** [flux.physbox.io](https://flux.physbox.io)
+*   **Volt:** [volt.physbox.io](https://volt.physbox.io)
+*   **Mesh:** [mesh.physbox.io](https://mesh.physbox.io)
+
+As soon as a page finishes loading, it automatically registers with the companion WebSocket server.
+
+### 2. Configure Your MCP Client
+
+#### For Claude Desktop
+Add the following block to your Claude Desktop configuration file (typically located at `AppData/Roaming/Claude/claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "physbox-mcp": {
+      "command": "physbox-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+#### For Claude Code
+Add a `.mcp.json` file to your project root (or update your global configuration at `~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "physbox-mcp": {
+      "type": "stdio",
+      "command": "physbox-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+### 3. Run the Companion Server Manually (Optional)
+If you are running the server in HTTP mode rather than Stdio, you can run:
+
+```bash
+# Starts HTTP server listening on port 3141 (default)
+physbox-mcp
+```
+
+Or configure custom port parameters:
+```bash
+physbox-mcp --port=4000
+```
+
+---
+
+## Development & Contribution
+For instructions on local development, modifying schemas, extending tool definitions, and manual builds, please refer to [README_DEV.md](file:///wsl.localhost/Ubuntu-20.04/home/boab/expt_mcp/README_DEV.md).

physbox_mcp-2.0.0/physbox_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

physbox_mcp-2.0.0/physbox_mcp/mcp-docs/chemistry.json

@@ -0,0 +1,271 @@
+{
+  "overview": "Chemistry Sim is a browser-based interactive chemistry laboratory and reaction simulator. It uses a custom multi-iteration equilibrium solver (30 iterations per tick), kinetic tickers, and phase boundary models to simulate aqueous solutions, precipitates, indicators, liquid-liquid extraction, vacuum/distillation, electrolysis, and organic reactions. Canvas elements are built using React Flow, where apparatuses are nodes and tubing/pouring channels are edges.",
+  "workflow": [
+    "1. Use chemistry_get_schema to find the list of supported apparatuses, reagents, indicators, and solvents.",
+    "2. Use chemistry_get_state to check the current canvas: nodes (vessels/devices) and edges (pouring links or tubing).",
+    "3. Set up the lab apparatus on the canvas using chemistry_set_nodes and chemistry_set_edges.",
+    "4. Dispense starting chemicals/reagents into specific vessels using chemistry_dispense_reagent.",
+    "5. Set properties such as heating mantle temperature or vacuum pump status using chemistry_set_node_properties.",
+    "6. Pour between vessels by invoking chemistry_pour_vessel.",
+    "7. Simulate ticks headlessly using chemistry_run_headless to verify chemical changes, temperature spikes, pH indicator transitions, and distillates, then call chemistry_start to run in the live UI."
+  ],
+  "gotchas": [
+    "REACTION THERMODYNAMICS: Saponification (soap making) and Fischer esterification require a temperature above 60°C to run. Sulfuric acid catalyst is required for esterification, and strongly basic NaOH/KOH is required for saponification. Verify the heating mantle is connected via a 'heat' edge and set to a high temperature.",
+    "VACUUM BOILING: Engaging the vacuum line (connected via a 'vacuum' edge or checkbox) reduces pressure to 0.2 atm, dropping boiling points by ~120°C. For example, DMSO (bp 189°C) will boil and distill at 75°C.",
+    "OSCILLATORS: Briggs-Rauscher and Iodine Clock reactions require specific starting concentrations. The BR reaction will slowly damp out and eventually quench. If pH rises above 3.5, the BR reaction is instantly quenched.",
+    "PRECIPITATE CONSERVATION: When filtering using a Buchner Funnel, the liquid filtrate drains through the 'drain' edge into the receiver flask, leaving any solid precipitates (like soap cake or BaSO4) trapped inside the funnel as a cake.",
+    "HABER-BOSCH: Requires iron catalyst (fe_catalyst), temperature > 200°C (via heating mantle), N2 and H2 gases. Equilibrium position follows real thermodynamics — higher temperature favours reverse reaction (Le Chatelier). Optimal industrial temperature ~450°C balances rate vs yield.",
+    "ELECTROLYSIS: Connect an electrolysis node with current_A property. Cu anode is sacrificial (replenishes Cu2+). Inert Pt/C anode: Cl2 gas if [Cl-] > 0.5 M (chlor-alkali), else O2 from water oxidation. Cathode: Cu2+ > Ag+ deposited preferentially before H2 evolution.",
+    "AMPHOTERIC METALS: Zn, Al, Cr(OH)3 dissolve in excess NaOH to form zincate/aluminate/chromite. Zn(OH)2 and Ni(OH)2 also dissolve in excess NH3.",
+    "METAL REACTIVITY: Na/K react violently with water. Ca reacts steadily. Mg reacts in acid. Zn and Al are amphoteric. Cu dissolves only in oxidising acid (HNO3). Fe dissolves slowly in dilute acid.",
+    "DANGEROUS MIXTURES SIMULATED: Bleach + ammonia → chloramine gas. Bleach + acid → chlorine gas. Sulfide + acid → H2S gas. Sulfite + acid → SO2 gas. Cyanide + acid → HCN (do not acidify KCN)."
+  ],
+  "coordinateSystem": {
+    "canvasGrid": "React Flow canvas X increases to the right, Y increases downwards.",
+    "spacing": "Ensure vessels are spaced 150-300 units apart to leave room for visual connections without layout overlapping."
+  },
+  "reactionCapabilities": {
+    "acidBase": "Full strong/weak acid-base equilibria. Strong acids: HCl, H2SO4, HNO3, HF. Weak acids: CH3COOH (Ka=1.76e-5), H3PO4, H2C2O4 (Ka1=5.9e-2). Indicators: phenolphthalein (pKa 9.4), methyl orange (pKa 3.7), bromothymol blue (pKa 7.1). pH tracked to 0-14.",
+    "precipitation": "55+ ion pairs with real Ksp values. Includes silver salts (AgCl, AgBr, AgI, Ag2CO3, Ag2SO4, Ag3PO4, Ag2CrO4, Ag2S), barium salts (BaSO4, BaCO3, BaCrO4), calcium salts (CaCO3, CaSO4, CaF2, Ca3(PO4)2), lead salts (PbI2, PbSO4, PbCO3, PbS, PbCl2, PbCrO4), transition metal hydroxides and sulfides for Cu, Zn, Fe(II/III), Ni, Co, Mn, Cd, Mg, Al, Cr, Bi, Hg. Prussian Blue (Fe4[Fe(CN)6]3) from Fe3+/ferrocyanide.",
+    "complexation": "Cu2+ + 4NH3 → [Cu(NH3)4]2+ (deep blue, Kf~1e12). Fe3+ + SCN- → Fe(SCN)2+ (blood red, Kf=138). Fe2+/Fe3+ + 6CN- → ferrocyanide/ferricyanide. Ni2+ + dimethylglyoxime → scarlet NiDMG precipitate at pH 4-10. Cu2+ + 4I- → CuI + I2 (iodometric).",
+    "redox": "KMnO4 reduced to Mn2+ in acid or MnO2 in neutral/base. K2Cr2O7 reduced by Fe2+ in acid (Cr3+ product). H2O2 reduces MnO4- in acid. Oxalate reduces MnO4- (permanganometry standard).",
+    "chromateEquilibrium": "2CrO4(2-) + 2H+ ⇌ Cr2O7(2-) + H2O  K=1e14. Automatically shifts with pH — acidic: orange Cr2O7, basic: yellow CrO4.",
+    "organic": "Fischer esterification (CH3COOH + EtOH ⇌ EtOAc, needs H+ catalyst and T>60C). Saponification (fat/EtOAc + OH-, T-dependent rate). Bromination of cyclohexene (Br2 decolorisation). Fermentation (glucose + yeast → EtOH + CO2). Benedict's test (Cu2O from reducing sugars at T>60C). Tollens' silver mirror (Ag+ + aldehyde + NH3). Iodine-starch complexation.",
+    "haberBosch": "N2 + 3H2 ⇌ 2NH3. Real thermodynamics: dG = -92400 + 198*T(K) J/mol. Kc computed from dG. Arrhenius kinetics. Requires iron catalyst and T>200C. Equilibrium shifts with temperature per Le Chatelier.",
+    "electrolysis": "Faraday's law (n_e = I*t/F). Cathode: Cu2+ > Ag+ deposited before H2 evolution. Inert anode: Cl2 (chlor-alkali, [Cl-]>0.5M) else O2 from water. Cu anode: sacrificial dissolution. Tracks deposited Cu(dep), Ag, H2(g), O2(g), Cl2(g).",
+    "distillation": "Boiling points adjusted for pressure via Clausius-Clapeyron. Volatile species (EtOH 78C, MeOH 65C, acetone 56C, DCM 40C, Et2O 35C, THF 66C, CHCl3 61C, EtOAc 77C, hexane 69C, toluene 111C, DMSO 189C). Fractional distillation of crude oil fractions (petrol/kerosene/diesel/bitumen).",
+    "liquidLiquidExtraction": "Partition by log Kd: hexane 3.9, toluene 2.73, CHCl3 1.97, EtOAc 0.73, Et2O 0.89, DCM 1.25. Hydrophilic species (Na+, Cl-, Cu2+, Fe(SCN)2+) stay aqueous. I2 prefers organic.",
+    "gasEvolution": "CO2 (carbonates + acid, fermentation), H2 (metals + acid, electrolysis), Cl2 (bleach + acid, electrolysis), ClNH2 (bleach + ammonia), SO2 (sulfite + acid), H2S (sulfide + acid), NO (nitrite + acid). Gas rate displayed visually as bubbles."
+  },
+  "tools": {
+    "chemistry_get_state": "Return current Chemistry simulator state: nodes, edges, isRunning, activePreset.",
+    "chemistry_start": "Start simulation ticks in the browser view.",
+    "chemistry_stop": "Stop/pause simulation ticks in the browser view.",
+    "chemistry_reset": "Reset simulator to initial preset flow state.",
+    "chemistry_clear": "Clear all nodes and edges from the canvas.",
+    "chemistry_list_presets": "List built-in chemistry lab presets, including instructions, recommended actions, node IDs, and edge IDs.",
+    "chemistry_load_preset": "Load a named lab preset.",
+    "chemistry_set_nodes": "Replace all nodes/apparatuses in the canvas.",
+    "chemistry_set_edges": "Replace all edges/wires in the canvas.",
+    "chemistry_dispense_reagent": "Dispense a specific reagent of given volume (mL) into a vessel node.",
+    "chemistry_pour_vessel": "Pour the entire contents (liquid and solid precipitates) of a source vessel into a target vessel.",
+    "chemistry_set_node_properties": "Update apparatus properties such as temperature, vacuumOn, stirring, or note card markdown content.",
+    "chemistry_run_headless": "Simulate the chemistry reaction ticks headlessly for N ticks. Returns the final nodes and full tick-by-tick trajectory. 10-20 ticks ≈ 1 second of real-world reaction time.",
+    "chemistry_run_headless_final": "Simulate the chemistry reaction ticks headlessly for N ticks. Returns ONLY the final node states (no trajectory), ensuring a very small response payload.",
+    "chemistry_get_schema": "Return the list of chemicals, indicator pKas, apparatus types, partition coefficients, and boiling points."
+  },
+  "schema": {
+    "nodeTypes": [
+      "beaker",
+      "flask_round",
+      "flask_erlenmeyer",
+      "sep_funnel",
+      "distillation_flask",
+      "condenser",
+      "rotovap",
+      "buchner_funnel",
+      "vacuum_line",
+      "addition_funnel",
+      "heating_mantle",
+      "drain",
+      "card"
+    ],
+    "nodeFields": {
+      "id": "string — unique node identifier",
+      "type": "string — always 'apparatus' or 'card'",
+      "data": {
+        "type": "string — apparatus type (e.g. 'beaker', 'flask_round', 'heating_mantle')",
+        "label": "string — display label",
+        "temperature": "number — local temperature in °C",
+        "vacuumOn": "boolean — true if vacuum pump connected and active",
+        "stirring": "boolean — true if magnetic stirrer active",
+        "refluxOn": "boolean — true if reflux condenser connected above vessel",
+        "markdown": "string — note card content (markdown)",
+        "state": {
+          "volume": "number — current volume in mL",
+          "species": "Record<string, number> — solute concentration in mol/L (M)",
+          "precipitates": "Record<string, number> — moles of solid precipitates inside vessel",
+          "pH": "number — solution pH (0-14)",
+          "temperature": "number — solution temperature in °C",
+          "pressure": "number — internal pressure in atm",
+          "oscillatorActive": "boolean — true if oscillating clock reaction is active",
+          "oscillatorPhase": "number — internal oscillation counter"
+        }
+      }
+    },
+    "reagents": [
+      { "id": "hcl", "name": "Hydrochloric Acid", "formula": "HCl (aq) 1 M", "category": "acid" },
+      { "id": "h2so4", "name": "Sulfuric Acid (conc.)", "formula": "H2SO4 18 M", "category": "acid", "warning": "violent heat on dilution" },
+      { "id": "hno3", "name": "Nitric Acid (conc.)", "formula": "HNO3 16 M", "category": "acid", "warning": "oxidising acid" },
+      { "id": "h2o2", "name": "Hydrogen Peroxide (30%)", "formula": "H2O2 9.8 M", "category": "oxidiser" },
+      { "id": "h3po4", "name": "Phosphoric Acid", "formula": "H3PO4 85%", "category": "acid" },
+      { "id": "acetic", "name": "Acetic Acid (glacial)", "formula": "CH3COOH 17 M", "category": "acid", "boilingPoint": 118 },
+      { "id": "hf", "name": "Hydrofluoric Acid", "formula": "HF (aq)", "category": "acid", "warning": "severe tissue hazard" },
+      { "id": "naoh", "name": "Sodium Hydroxide", "formula": "NaOH (aq) 1 M", "category": "base" },
+      { "id": "koh", "name": "Potassium Hydroxide", "formula": "KOH (aq) 1 M", "category": "base" },
+      { "id": "nh3", "name": "Ammonia (conc.)", "formula": "NH3 (aq) 14 M", "category": "base", "warning": "pungent vapour" },
+      { "id": "conc_nh3", "name": "Ammonia (saturated 28%)", "formula": "NH3 (aq) 14 M", "category": "base" },
+      { "id": "ca_oh2", "name": "Calcium Hydroxide (slaked lime)", "formula": "Ca(OH)2 sat. 22 mM", "category": "base" },
+      { "id": "na2co3", "name": "Sodium Carbonate", "formula": "Na2CO3 0.1 M", "category": "base" },
+      { "id": "nahco3", "name": "Sodium Bicarbonate", "formula": "NaHCO3 1 M", "category": "base" },
+      { "id": "nacl", "name": "Sodium Chloride (brine)", "formula": "NaCl 1 M", "category": "salt" },
+      { "id": "agno3", "name": "Silver Nitrate", "formula": "AgNO3 0.1 M", "category": "salt", "warning": "stains skin black" },
+      { "id": "ki", "name": "Potassium Iodide", "formula": "KI 0.1 M", "category": "salt" },
+      { "id": "pb_no3", "name": "Lead Nitrate", "formula": "Pb(NO3)2 0.025 M", "category": "salt", "warning": "toxic — lead compound" },
+      { "id": "lead_nitrate", "name": "Lead Nitrate (0.5 M)", "formula": "Pb(NO3)2 0.5 M", "category": "salt", "warning": "toxic — lead compound" },
+      { "id": "bacl2", "name": "Barium Chloride", "formula": "BaCl2 0.1 M", "category": "salt", "warning": "toxic — soluble barium" },
+      { "id": "na2so4", "name": "Sodium Sulfate", "formula": "Na2SO4 0.1 M", "category": "salt" },
+      { "id": "fecl3", "name": "Iron(III) Chloride (5 mM)", "formula": "FeCl3 5 mM", "category": "salt" },
+      { "id": "iron3_chloride", "name": "Iron(III) Chloride (0.5 M)", "formula": "FeCl3 0.5 M", "category": "salt" },
+      { "id": "iron3_nitrate", "name": "Iron(III) Nitrate", "formula": "Fe(NO3)3 0.5 M", "category": "salt" },
+      { "id": "iron2_sulfate", "name": "Iron(II) Sulfate", "formula": "FeSO4 0.5 M", "category": "salt", "warning": "oxidises to Fe3+ in air" },
+      { "id": "cuso4", "name": "Copper(II) Sulfate", "formula": "CuSO4 0.1 M", "category": "salt" },
+      { "id": "copper_nitrate", "name": "Copper(II) Nitrate", "formula": "Cu(NO3)2 0.5 M", "category": "salt" },
+      { "id": "copper_sulfate_50", "name": "CuSO4 Electroplating Bath", "formula": "CuSO4 50 mM", "category": "electrolyte" },
+      { "id": "nh4scn", "name": "Ammonium Thiocyanate", "formula": "NH4SCN 25 mM", "category": "salt" },
+      { "id": "kmno4", "name": "Potassium Permanganate", "formula": "KMnO4 20 mM", "category": "oxidiser", "warning": "strong oxidiser" },
+      { "id": "k2cr2o7", "name": "Potassium Dichromate", "formula": "K2Cr2O7", "category": "oxidiser", "warning": "Cr(VI) carcinogen" },
+      { "id": "k2cro4", "name": "Potassium Chromate", "formula": "K2CrO4 0.02 M", "category": "salt", "warning": "Cr(VI) carcinogen" },
+      { "id": "potassium_chromate", "name": "Potassium Chromate (0.5 M)", "formula": "K2CrO4 0.5 M", "category": "salt" },
+      { "id": "na2s2o3", "name": "Sodium Thiosulfate", "formula": "Na2S2O3 0.1 M", "category": "reducing agent" },
+      { "id": "i2", "name": "Iodine Solution", "formula": "I2/KI (aq) 10 mM", "category": "reagent" },
+      { "id": "caso4", "name": "Calcium Sulfate (Drierite)", "formula": "CaSO4 anhydrous", "category": "drying agent" },
+      { "id": "mgso4", "name": "Magnesium Sulfate (anhydrous)", "formula": "MgSO4 anhydrous", "category": "drying agent" },
+      { "id": "phenol", "name": "Phenolphthalein", "formula": "C20H14O4 indicator", "category": "indicator", "pKa": 9.4, "colourChange": "colourless → pink at pH 8.2-10" },
+      { "id": "methyl_o", "name": "Methyl Orange", "formula": "indicator", "category": "indicator", "pKa": 3.7, "colourChange": "red → yellow at pH 3.1-4.4" },
+      { "id": "btb", "name": "Bromothymol Blue", "formula": "indicator", "category": "indicator", "pKa": 7.1, "colourChange": "yellow → blue at pH 6-7.6" },
+      { "id": "starch_solution", "name": "Starch Solution", "formula": "starch 0.5%", "category": "indicator", "note": "turns deep blue-black with I3-" },
+      { "id": "ethanol", "name": "Ethanol (95%)", "formula": "EtOH 16 M", "category": "solvent", "boilingPoint": 78.4, "density": 0.789, "flammable": true },
+      { "id": "methanol", "name": "Methanol", "formula": "MeOH 24.7 M", "category": "solvent", "boilingPoint": 64.7, "density": 0.791, "warning": "toxic — blindness/death" },
+      { "id": "acetone", "name": "Acetone", "formula": "(CH3)2CO 13.5 M", "category": "solvent", "boilingPoint": 56.1, "density": 0.791, "flammable": true },
+      { "id": "dcm", "name": "Dichloromethane (DCM)", "formula": "CH2Cl2 13.1 M", "category": "solvent", "boilingPoint": 40, "density": 1.325 },
+      { "id": "ethyl_acetate", "name": "Ethyl Acetate", "formula": "EtOAc 11.4 M", "category": "solvent", "boilingPoint": 77.1, "density": 0.902, "flammable": true },
+      { "id": "hexane", "name": "Hexane", "formula": "n-C6H14 7.7 M", "category": "solvent", "boilingPoint": 69, "density": 0.659, "flammable": true },
+      { "id": "toluene", "name": "Toluene", "formula": "PhCH3 9.4 M", "category": "solvent", "boilingPoint": 111, "density": 0.867, "flammable": true },
+      { "id": "diethyl_ether", "name": "Diethyl Ether", "formula": "Et2O 6.9 M", "category": "solvent", "boilingPoint": 34.6, "density": 0.713, "warning": "extreme fire hazard — forms peroxides" },
+      { "id": "chloroform", "name": "Chloroform", "formula": "CHCl3 12.5 M", "category": "solvent", "boilingPoint": 61.2, "density": 1.483 },
+      { "id": "dmso", "name": "DMSO", "formula": "(CH3)2SO 14.1 M", "category": "solvent", "boilingPoint": 189, "warning": "skin penetration enhancer" },
+      { "id": "thf", "name": "THF", "formula": "C4H8O 12.3 M", "category": "solvent", "boilingPoint": 66, "flammable": true, "warning": "forms explosive peroxides" },
+      { "id": "water", "name": "Distilled Water", "formula": "H2O", "category": "solvent", "boilingPoint": 100, "density": 1.0 },
+      { "id": "na_metal", "name": "Sodium Metal", "formula": "Na (s)", "category": "reactive metal", "warning": "violent reaction with water" },
+      { "id": "k_metal", "name": "Potassium Metal", "formula": "K (s)", "category": "reactive metal", "warning": "extremely violent reaction with water, may self-ignite" },
+      { "id": "mg_metal", "name": "Magnesium Ribbon", "formula": "Mg (s)", "category": "reactive metal", "warning": "burns with blinding white light" },
+      { "id": "zn_metal", "name": "Zinc (granulated)", "formula": "Zn (s)", "category": "reactive metal" },
+      { "id": "al_metal", "name": "Aluminium (foil/powder)", "formula": "Al (s)", "category": "reactive metal", "note": "amphoteric — dissolves in acid AND strong base" },
+      { "id": "ca_metal", "name": "Calcium Metal", "formula": "Ca (s)", "category": "reactive metal" },
+      { "id": "cu_metal", "name": "Copper (turnings)", "formula": "Cu (s)", "category": "reactive metal", "note": "unreactive in dilute acid; dissolves in HNO3" },
+      { "id": "fe_metal", "name": "Iron Wool / Filings", "formula": "Fe (s)", "category": "reactive metal" },
+      { "id": "vegetable_oil", "name": "Vegetable Oil", "formula": "tristearin", "category": "organic", "note": "saponifies with NaOH at T>60C" },
+      { "id": "crude_oil", "name": "Crude Oil", "formula": "hydrocarbon mixture", "category": "organic", "note": "fractionally distilled into petrol/kerosene/diesel/bitumen" },
+      { "id": "nicl2", "name": "Nickel(II) Chloride", "formula": "NiCl2 0.1 M", "category": "salt" },
+      { "id": "nickel_sulfate", "name": "Nickel Sulfate", "formula": "NiSO4 1 M", "category": "salt" },
+      { "id": "dmg", "name": "Dimethylglyoxime (DMG)", "formula": "C4H8N2O2 50 mM", "category": "chelating agent", "note": "scarlet NiDMG2 precipitate at pH 4-10" },
+      { "id": "na2s", "name": "Sodium Sulfide", "formula": "Na2S 0.1 M", "category": "salt", "warning": "releases toxic H2S in acid" },
+      { "id": "sodium_sulfide", "name": "Sodium Sulfide (0.5 M)", "formula": "Na2S 0.5 M", "category": "salt", "warning": "releases toxic H2S in acid" },
+      { "id": "znso4", "name": "Zinc Sulfate", "formula": "ZnSO4 0.1 M", "category": "salt" },
+      { "id": "zinc_sulfate", "name": "Zinc Sulfate (1 M)", "formula": "ZnSO4 1 M", "category": "salt" },
+      { "id": "zinc_chloride", "name": "Zinc Chloride", "formula": "ZnCl2 1 M", "category": "salt" },
+      { "id": "cobalt_chloride", "name": "Cobalt Chloride", "formula": "CoCl2 1 M", "category": "salt" },
+      { "id": "manganese_sulfate", "name": "Manganese Sulfate", "formula": "MnSO4 1 M", "category": "salt" },
+      { "id": "aluminium_sulfate", "name": "Aluminium Sulfate (Alum)", "formula": "Al2(SO4)3 0.5 M", "category": "salt" },
+      { "id": "magnesium_sulfate", "name": "Magnesium Sulfate (Epsom Salt)", "formula": "MgSO4 1 M", "category": "salt" },
+      { "id": "cadmium_nitrate", "name": "Cadmium Nitrate", "formula": "Cd(NO3)2 0.5 M", "category": "salt", "warning": "highly toxic — carcinogen" },
+      { "id": "bismuth_nitrate", "name": "Bismuth Nitrate", "formula": "Bi(NO3)3 0.1 M", "category": "salt" },
+      { "id": "mercury_nitrate", "name": "Mercury(II) Nitrate", "formula": "Hg(NO3)2 0.1 M", "category": "salt", "warning": "highly toxic neurotoxin" },
+      { "id": "sodium_bromide", "name": "Sodium Bromide", "formula": "NaBr 1 M", "category": "salt" },
+      { "id": "sodium_iodide", "name": "Sodium Iodide", "formula": "NaI 1 M", "category": "salt" },
+      { "id": "potassium_chromate", "name": "Potassium Chromate (0.5 M)", "formula": "K2CrO4 0.5 M", "category": "salt" },
+      { "id": "sodium_phosphate", "name": "Sodium Phosphate", "formula": "Na3PO4 0.3 M", "category": "salt" },
+      { "id": "sodium_fluoride", "name": "Sodium Fluoride", "formula": "NaF 1 M", "category": "salt" },
+      { "id": "k4fe_cn6", "name": "Potassium Ferrocyanide", "formula": "K4[Fe(CN)6] 0.1 M", "category": "salt", "note": "forms Prussian Blue with Fe3+" },
+      { "id": "k3fe_cn6", "name": "Potassium Ferricyanide", "formula": "K3[Fe(CN)6] 0.1 M", "category": "salt", "note": "Turnbull's Blue test for Fe2+" },
+      { "id": "na2so3", "name": "Sodium Sulfite", "formula": "Na2SO3 0.5 M", "category": "salt", "note": "SO2 gas released in acid" },
+      { "id": "nano2", "name": "Sodium Nitrite", "formula": "NaNO2 0.5 M", "category": "salt", "note": "NO gas released in acid" },
+      { "id": "kcn", "name": "Potassium Cyanide", "formula": "KCN 0.1 M", "category": "salt", "warning": "EXTREMELY TOXIC. Never acidify — releases HCN gas." },
+      { "id": "n2_gas", "name": "Nitrogen Gas", "formula": "N2 (g)", "category": "gas", "note": "Haber-Bosch feedstock" },
+      { "id": "h2_gas", "name": "Hydrogen Gas", "formula": "H2 (g)", "category": "gas", "warning": "highly flammable", "note": "Haber-Bosch feedstock" },
+      { "id": "fe_catalyst", "name": "Iron Catalyst", "formula": "Fe (s)", "category": "catalyst", "note": "required for Haber-Bosch at T>200C" },
+      { "id": "bleach", "name": "Bleach (NaOCl)", "formula": "NaOCl (aq) 1 M", "category": "oxidiser", "warning": "NEVER mix with ammonia or acids" },
+      { "id": "pool_shock", "name": "Pool Shock Ca(OCl)2", "formula": "Ca(OCl)2", "category": "oxidiser", "warning": "strong oxidiser — releases Cl2 with acid" },
+      { "id": "muriatic_acid", "name": "Muriatic Acid (HCl 30%)", "formula": "HCl 9.5 M", "category": "acid" },
+      { "id": "vinegar", "name": "White Vinegar (5% AcOH)", "formula": "CH3COOH 0.83 M", "category": "acid" },
+      { "id": "baking_soda", "name": "Baking Soda (NaHCO3)", "formula": "NaHCO3 1 M", "category": "base" },
+      { "id": "washing_soda", "name": "Washing Soda (Na2CO3)", "formula": "Na2CO3 0.1 M", "category": "base" },
+      { "id": "rust", "name": "Rust (Fe2O3)", "formula": "Fe2O3 (s)", "category": "solid", "note": "dissolves in acid or acetic acid to give Fe3+" },
+      { "id": "hard_water", "name": "Hard Water (Ca/Mg salts)", "formula": "CaCO3/MgCO3 dissolved", "category": "aqueous", "note": "softened by Na2CO3 (CaCO3 precipitate)" },
+      { "id": "pool_algicide", "name": "Copper Sulfate (Algicide)", "formula": "CuSO4 10 mM", "category": "salt" },
+      { "id": "glucose", "name": "Glucose Solution", "formula": "C6H12O6 0.5 M", "category": "organic", "note": "reducing sugar — Benedict's/Tollens' positive" },
+      { "id": "fructose", "name": "Fructose Solution", "formula": "C6H12O6 0.5 M", "category": "organic", "note": "reducing sugar — Benedict's positive" },
+      { "id": "formaldehyde", "name": "Formaldehyde (Formalin 10%)", "formula": "HCHO 3.3 M", "category": "organic", "warning": "IARC Group 1 carcinogen" },
+      { "id": "acetaldehyde", "name": "Acetaldehyde", "formula": "CH3CHO 12 M", "category": "organic", "boilingPoint": 20.2 },
+      { "id": "benedicts", "name": "Benedict's Reagent", "formula": "Cu2+/Na2CO3/citrate", "category": "analytical", "note": "brick-red Cu2O from reducing sugars at T>60C" },
+      { "id": "tollens", "name": "Tollens' Reagent (freshly prepared)", "formula": "[Ag(NH3)2]+ aq.", "category": "analytical", "warning": "PREPARE FRESH ONLY — aged forms explosive AgN3" },
+      { "id": "sodium_oxalate", "name": "Sodium Oxalate", "formula": "Na2C2O4 0.5 M", "category": "analytical", "note": "decolorises KMnO4 — primary standard" },
+      { "id": "oxalic_acid", "name": "Oxalic Acid", "formula": "H2C2O4 0.5 M", "category": "acid", "note": "diprotic, Ka1=5.9e-2. Primary standard for KMnO4" },
+      { "id": "nh4cl", "name": "Ammonium Chloride", "formula": "NH4Cl 1 M", "category": "salt", "note": "mildly acidic pH~5; NH4+/NH3 buffer with ammonia" },
+      { "id": "sodium_acetate", "name": "Sodium Acetate", "formula": "CH3COONa 1 M", "category": "salt", "note": "mildly basic pH~8.9; acetate buffer with acetic acid" },
+      { "id": "edta_solution", "name": "EDTA (0.1 M)", "formula": "Na2EDTA 0.1 M", "category": "chelating agent", "note": "titrates most metal ions; water hardness determination" },
+      { "id": "potassium_nitrate", "name": "Potassium Nitrate (saltpetre)", "formula": "KNO3 1 M", "category": "salt" },
+      { "id": "h2o2_3pct", "name": "Hydrogen Peroxide (3%)", "formula": "H2O2 0.9 M", "category": "oxidiser" },
+      { "id": "dilute_h2so4", "name": "Dilute Sulfuric Acid", "formula": "H2SO4 0.5 M", "category": "acid" },
+      { "id": "dilute_hno3", "name": "Dilute Nitric Acid", "formula": "HNO3 0.5 M", "category": "acid" },
+      { "id": "ammonium_sulfate", "name": "Ammonium Sulfate", "formula": "(NH4)2SO4 1 M", "category": "salt" },
+      { "id": "potassium_carbonate", "name": "Potassium Carbonate", "formula": "K2CO3 0.5 M", "category": "base" },
+      { "id": "strontium_chloride", "name": "Strontium Chloride", "formula": "SrCl2 0.5 M", "category": "salt" },
+      { "id": "bromine_water", "name": "Bromine Water", "formula": "Br2 (aq) 0.1 M", "category": "oxidiser", "warning": "toxic vapour — use in fume hood" },
+      { "id": "cyclohexene_l", "name": "Cyclohexene", "formula": "C6H10 neat", "category": "organic", "boilingPoint": 83, "note": "instantly decolorises Br2 — alkene test" },
+      { "id": "glucose_yeast", "name": "Glucose + Yeast (Fermentation)", "formula": "C6H12O6 + Saccharomyces", "category": "organic", "note": "ferments to EtOH + CO2" },
+      { "id": "brine_electrolysis", "name": "Saturated NaCl Brine", "formula": "NaCl 6 M", "category": "electrolyte", "note": "chlor-alkali: Cl2 at anode, H2 + NaOH at cathode" },
+      { "id": "dilute_h2so4_electrolysis", "name": "Dilute H2SO4 (Hofmann)", "formula": "H2SO4 0.5 M", "category": "electrolyte", "note": "water electrolysis: H2:O2 = 2:1 by volume" }
+    ],
+    "partitionCoefficients": {
+      "description": "log Kd values (positive = prefers organic layer, negative = prefers aqueous layer). Used in sep funnel liquid-liquid extraction.",
+      "hexane": 3.9,
+      "toluene": 2.73,
+      "CHCl3": 1.97,
+      "DCM": 1.25,
+      "Et2O": 0.89,
+      "EtOAc": 0.73,
+      "THF": 0.46,
+      "acetone": -0.24,
+      "EtOH": 0.1,
+      "DMSO": -1.35,
+      "MeOH": -0.77,
+      "I2(aq)": 2.5,
+      "I3-": -0.3,
+      "Fe(SCN)2+": -1.0,
+      "Cu2+": -3.0,
+      "Na+": -5,
+      "Cl-": -5
+    },
+    "boilingPoints": {
+      "description": "Normal boiling points at 1 atm (°C). Adjusted for pressure via Clausius-Clapeyron. Vacuum line reduces pressure to ~0.2 atm, lowering BP by ~120°C.",
+      "Et2O": 34.6,
+      "DCM": 40.0,
+      "acetone": 56.1,
+      "THF": 66.0,
+      "hexane": 69.0,
+      "EtOH": 78.4,
+      "cyclohexene": 83.0,
+      "acetic": 118.0,
+      "EtOAc": 77.1,
+      "MeOH": 64.7,
+      "CHCl3": 61.2,
+      "toluene": 111.0,
+      "water": 100.0,
+      "DMSO": 189.0,
+      "glycerol": 290.0,
+      "CH3CHO": 20.2
+    },
+    "precipitates": {
+      "description": "Solid precipitates tracked in mol. Form when ion product exceeds Ksp. 55+ ion pairs supported.",
+      "silverSalts": ["AgCl (white)", "AgBr (pale yellow)", "AgI (yellow)", "Ag2CO3 (pale yellow)", "Ag2SO4 (white)", "Ag3PO4 (yellow)", "Ag2CrO4 (brick red)", "Ag2S (black)", "AgOH (brownish)", "Ag (silver mirror — Tollens)"],
+      "bariumSalts": ["BaSO4 (white)", "BaCO3 (white)", "BaCrO4 (yellow)", "BaF2 (white)"],
+      "calciumSalts": ["CaCO3 (white)", "CaSO4 (white)", "CaF2 (white)", "Ca3(PO4)2 (white)"],
+      "leadSalts": ["PbI2 (golden — golden rain)", "PbSO4 (white)", "PbCO3 (white)", "PbS (black)", "PbCl2 (white)", "PbCrO4 (yellow)", "Pb(OH)2 (white)"],
+      "transitionMetalHydroxides": ["Cu(OH)2 (pale blue)", "Fe(OH)2 (pale green)", "Fe(OH)3 (rust)", "Ni(OH)2 (green)", "Co(OH)2 (pink)", "Mn(OH)2 (pale pink)", "Zn(OH)2 (white)", "Cd(OH)2 (white)", "Al(OH)3 (white gelatinous)", "Cr(OH)3 (grey-green)", "Mg(OH)2 (white)", "Bi(OH)3 (white)"],
+      "metalSulfides": ["CuS (black)", "ZnS (pale yellow)", "FeS (black)", "NiS (black)", "CoS (black)", "MnS (salmon)", "CdS (yellow)", "HgS (red/black)", "PbS (black)", "Ag2S (black)"],
+      "special": ["NiDMG (scarlet — dimethylglyoximate)", "Fe4[Fe(CN)6]3 (Prussian Blue)", "Cu2O (brick red — Benedict's positive)", "MnO2 (dark brown)", "Cu(dep) (orange — electrodeposited)", "CuI (white — iodometric)"]
+    }
+  }
+}