physbox-mcp 2.0.0__py3-none-any.whl

physbox_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "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)"]
+    }
+  }
+}

physbox_mcp/mcp-docs/circuit.json

@@ -0,0 +1,234 @@
+{
+  "overview": "Circuit Expert is a browser-based interactive electronics circuit playground. It uses a WASM-compiled ngspice simulator (via @tscircuit/ngspice-spice-engine) to run SPICE-accurate transient simulations. The canvas is built using React Flow, where components are nodes and connections are edges. In addition to analog components, it integrates logic gates and a Javascript-sandboxed Microcontroller (MCU) simulator for hybrid digital/analog designs. Coordinate system: standard canvas coordinates (X increases right, Y increases down).",
+  "workflow": [
+    "1. Call circuit_get_schema to find the list of supported components, their parameters, and connection terminal names.",
+    "2. Use circuit_get_state to check the current canvas state: which nodes (components) and edges (wires) are loaded.",
+    "3. Construct or modify the circuit by calling circuit_set_nodes and/or circuit_set_edges.",
+    "4. Trigger the transient simulation using circuit_run_sim. Always call this after modifying node properties or connections to update voltages, currents, and MCU outputs.",
+    "5. Retrieve the simulation waveforms using circuit_get_waveforms to inspect voltages, currents, and MCU logs programmatically.",
+    "6. If troubleshooting or analyzing a wire, call circuit_toggle_probe to enable real-time voltage inspection at specific coordinates."
+  ],
+  "gotchas": [
+    "SINGULAR MATRIX ERROR: ngspice is extremely sensitive to floating nodes. Any pin or terminal that is left unconnected will cause a singular matrix error. To prevent this, the simulation layer automatically shunts unconnected pins with a 1G ohm resistor to ground, but you should always ensure loops are closed and Ground (GND) is connected to a common reference.",
+    "MCU TWO-PASS SIMULATION: MCUs are simulated using a two-pass mechanism. Pass 1 runs standard SPICE. Pass 2 inputs the resulting node voltages into the JS sandbox, generates a Piecewise Linear (PWL) output, and re-runs SPICE. For analog reads (e.g. analogRead('A0')), make sure the source is connected to A0 and that you call sleep() in the loop to give the simulation time steps.",
+    "PORT TO NET NAMES: In ngspice, nodes are resolved to net names. If you use the probe tool (circuit_toggle_probe), it maps component ports like 'led1-anode' to net names like 'net1'. Keep track of these mappings if writing custom spice.",
+    "SAMPLING RATES: The oscilloscope and speaker components capture waveforms over the simulation duration (e.g., simLength). If you are outputting audio, make sure the sampling frequency of your signal generator or MCU code matches the time scale to avoid aliasing.",
+    "NMOS HIGH-SIDE SWITCHING: Do not use NMOS as the high-side switch in a buck converter (drain at Vin, source at switching node, gate driven from a GND-referenced signal). This is a fundamental electronics constraint, not a simulator limitation: when the NMOS turns on, the source rises toward Vin, collapsing Vgs below the threshold and immediately turning it off. A proper high-side NMOS requires a bootstrap gate driver. Without one, use NMOS low-side only (source tied to GND). For buck converters, the working topology is: NMOS drain at Vin, source at the switching node, freewheeling diode cathode also at the switching node, diode anode to GND, inductor from switching node to output.",
+    "SWITCHING FREQUENCY AND SIMULATION SPEED: The default SPICE timestep is around 1ms (normal resolution) or 0.05ms (high resolution). Signal generators running faster than roughly 1-5kHz may require many sub-steps per cycle to converge, significantly increasing simulation time. Very high frequencies (tens of kHz and above) combined with a long simLength can make the simulation slow or unresponsive. If a switching circuit is slow to simulate, try reducing the frequency or the simLength first.",
+    "BUCK CONVERTER DUTY CYCLE: The theoretical duty cycle for a buck converter is Vout/Vin. In practice, MOSFET threshold voltage and diode forward drop mean the effective duty is lower — expect to tune the dutyCycle parameter down by several percent from the ideal value."
+  ],
+  "coordinateSystem": {
+    "canvasGrid": "React Flow canvas uses a standard X/Y coordinate system. X increases to the right, Y increases downwards.",
+    "spacing": "Ensure components are spaced sufficiently (typically 100-300 units apart) so that their ports can be easily connected without overlapping wires."
+  },
+  "tools": {
+    "circuit_get_state": "Return full Circuit Expert state: nodes, edges, isSimulating, selectedPreset, probeMode.",
+    "circuit_get_components": "Return all circuit components (nodes) with positions and data.",
+    "circuit_run_sim": "Trigger the SPICE simulation in Circuit Expert.",
+    "circuit_stop_sim": "Stop the running SPICE simulation.",
+    "circuit_toggle_probe": "Toggle probe mode (click a wire to inspect voltage).",
+    "circuit_load_preset": "Load a named circuit preset.",
+    "circuit_set_nodes": "Replace all components in the Circuit Expert canvas.",
+    "circuit_set_edges": "Replace all wires in the Circuit Expert canvas.",
+    "circuit_get_schema": "Return the Circuit Expert component schema, state fields, and SPICE model specifications.",
+    "circuit_get_waveforms": "Return transient waveforms (voltage/current time series) for all components and wires after simulation runs.",
+    "circuit_upload_audio": "Upload audio samples to a microphone node.",
+    "circuit_download_audio": "Download audio waveforms from a speaker node, optionally interpolated."
+  },
+  "schema": {
+    "nodeFields": {
+      "id": "string — unique component identifier",
+      "type": "string — component type (e.g., resistor, capacitor, inductor, diode, led, switch, multimeter, scope, speaker, transistor (npn/pnp), source (voltage/current/acvoltage/signalgen), ground, mcu, sevensegment, potentiometer, opamp, timer555)",
+      "position": {
+        "x": "number — X position on canvas",
+        "y": "number — Y position on canvas"
+      },
+      "data": {
+        "label": "string — display label (e.g., '1k', '10u', '5V')",
+        "value": "string/number — component value",
+        "isSimulating": "boolean — true if SPICE simulation is running and rendering animation",
+        "current_array": "number[] — transient current through component in Amperes over time",
+        "time_points": "number[] — transient timestamps in milliseconds",
+        "voltageData": "{t: number, v: number}[] — transient voltage readings (e.g., for Oscilloscope, Speaker)",
+        "segmentVoltageArrays": "Record<string, number[]> — per-segment voltage readings for 7-Segment displays"
+      }
+    },
+    "componentTerminals": {
+      "resistor": ["in", "out"],
+      "capacitor": ["in", "out"],
+      "inductor": ["in", "out"],
+      "diode": ["anode", "cathode"],
+      "led": ["anode", "cathode"],
+      "zener": ["anode", "cathode"],
+      "switch": ["in", "out"],
+      "voltage": ["pos", "neg"],
+      "acvoltage": ["pos", "neg"],
+      "signalgen": ["out", "gnd", "sync"],
+      "ground": ["in"],
+      "scope": ["ch1", "ch2", "gnd"],
+      "speaker": ["in", "gnd"],
+      "npn": ["c", "b", "e"],
+      "pnp": ["c", "b", "e"],
+      "nmos": ["d", "g", "s"],
+      "pmos": ["d", "g", "s"],
+      "potentiometer": ["in", "out", "wiper"],
+      "sevensegment": ["a", "b", "c", "d", "e", "f", "g", "common"],
+      "mcu": ["D0", "D1", "D2", "D3", "A0", "A1", "5V", "GND"],
+      "opamp": ["in_non", "in_inv", "vcc", "vee", "out"],
+      "timer555": ["1", "2", "3", "4", "5", "6", "7", "8"]
+    },
+    "spiceModels": {
+      "potentiometer": {
+        "description": "Modelled as a two-resistor voltage divider to capture 3-terminal behaviour.",
+        "parameters": {
+          "totalResistance": "number — total end-to-end resistance in ohms",
+          "wiperPos": "number — wiper position from 0.0 (0%) to 1.0 (100%)",
+          "R_top": "TotalResistance * (1 - WiperPos) ohms",
+          "R_bottom": "TotalResistance * WiperPos ohms"
+        }
+      },
+      "sevensegment": {
+        "description": "Common Cathode 7-segment display node. Assumes common pin is grounded.",
+        "activationThreshold": "2.5V — segment lights up if (V_seg - V_common) > 2.5V"
+      },
+      "currentSource": {
+        "description": "Provides constant DC current.",
+        "parameters": {
+          "value": "number — DC current in Amperes"
+        }
+      }
+    },
+    "probeMode": {
+      "description": "Allows clicking on a wire/edge after a simulation run to inspect voltage at that node.",
+      "behavior": "Displays a floating tooltip showing the Net name and the final voltage value of the SPICE node."
+    }
+  },
+  "examples": [
+    {
+      "title": "Basic LED Blinker",
+      "description": "A signal generator producing a 1Hz square wave to blink a red LED through a 330 ohm current-limiting resistor.",
+      "nodes": [
+        { "id": "sg1", "type": "signalgen", "position": { "x": 100, "y": 150 }, "data": { "label": "Clock 1Hz", "waveform": "square", "frequency": 1, "amplitude": 5 } },
+        { "id": "r1", "type": "resistor", "position": { "x": 350, "y": 150 }, "data": { "label": "330" } },
+        { "id": "led1", "type": "led", "position": { "x": 600, "y": 150 }, "data": { "label": "Red LED", "color": "red", "v_drop": 2.0, "max_current": 20 } },
+        { "id": "g1", "type": "ground", "position": { "x": 600, "y": 300 }, "data": { "label": "GND" } },
+        { "id": "g2", "type": "ground", "position": { "x": 100, "y": 300 }, "data": { "label": "GND" } }
+      ],
+      "edges": [
+        { "id": "e-sg1-r1", "source": "sg1", "target": "r1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r1-led1", "source": "r1", "target": "led1", "sourceHandle": "out", "targetHandle": "anode", "type": "smoothstep" },
+        { "id": "e-led1-g1", "source": "led1", "target": "g1", "sourceHandle": "cathode", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-sg1-g2", "source": "sg1", "target": "g2", "sourceHandle": "gnd", "targetHandle": "in", "type": "smoothstep" }
+      ]
+    },
+    {
+      "title": "555 Timer Blinker",
+      "description": "An astable oscillator circuit built around the NE555 timer macro model, blinking an LED at around 1.3Hz.",
+      "nodes": [
+        { "id": "v1", "type": "voltage", "position": { "x": 100, "y": 50 }, "data": { "label": "5V" } },
+        { "id": "t555", "type": "timer555", "position": { "x": 400, "y": 200 }, "data": { "label": "555 Timer" } },
+        { "id": "r1", "type": "resistor", "position": { "x": 250, "y": 50 }, "data": { "label": "10k" } },
+        { "id": "r2", "type": "resistor", "position": { "x": 250, "y": 150 }, "data": { "label": "47k" } },
+        { "id": "c1", "type": "capacitor", "position": { "x": 250, "y": 250 }, "data": { "label": "10u" } },
+        { "id": "r3", "type": "resistor", "position": { "x": 600, "y": 200 }, "data": { "label": "330" } },
+        { "id": "led1", "type": "led", "position": { "x": 800, "y": 200 }, "data": { "label": "Blue LED", "color": "blue" } },
+        { "id": "g1", "type": "ground", "position": { "x": 100, "y": 400 }, "data": { "label": "GND" } }
+      ],
+      "edges": [
+        { "id": "e-v1-t8", "source": "v1", "target": "t555", "sourceHandle": "pos", "targetHandle": "8", "type": "smoothstep" },
+        { "id": "e-v1-t4", "source": "v1", "target": "t555", "sourceHandle": "pos", "targetHandle": "4", "type": "smoothstep" },
+        { "id": "e-v1-r1", "source": "v1", "target": "r1", "sourceHandle": "pos", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-v1-g1", "source": "v1", "target": "g1", "sourceHandle": "neg", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-t1-g1", "source": "t555", "target": "g1", "sourceHandle": "1", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r1-r2", "source": "r1", "target": "r2", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r1-t7", "source": "r1", "target": "t555", "sourceHandle": "out", "targetHandle": "7", "type": "smoothstep" },
+        { "id": "e-r2-c1", "source": "r2", "target": "c1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r2-t6", "source": "r2", "target": "t555", "sourceHandle": "out", "targetHandle": "6", "type": "smoothstep" },
+        { "id": "e-r2-t2", "source": "r2", "target": "t555", "sourceHandle": "out", "targetHandle": "2", "type": "smoothstep" },
+        { "id": "e-c1-g1", "source": "c1", "target": "g1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-t3-r3", "source": "t555", "target": "r3", "sourceHandle": "3", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r3-led1", "source": "r3", "target": "led1", "sourceHandle": "out", "targetHandle": "anode", "type": "smoothstep" },
+        { "id": "e-led1-g1", "source": "led1", "target": "g1", "sourceHandle": "cathode", "targetHandle": "in", "type": "smoothstep" }
+      ]
+    },
+    {
+      "title": "MCU Analog Logger",
+      "description": "An AC voltage source monitored by an MCU analog input channel. Demonstrates the two-pass MCU SPICE simulation loop and serial logging.",
+      "nodes": [
+        { "id": "vac1", "type": "acvoltage", "position": { "x": 50, "y": 180 }, "data": { "label": "5V 40Hz", "amplitude": 5, "frequency": 40 } },
+        { "id": "mcu1", "type": "mcu", "position": { "x": 300, "y": 150 }, "data": { "label": "Microcontroller", "code": "pinMode('A0', 'INPUT');\n\n// Read A0 every 5ms and log it\nwhile(true) {\n  const val = analogRead('A0');\n  Serial.println(`t=${millis()}ms -> A0: ${val}`);\n  sleep(5);\n}" } },
+        { "id": "g1", "type": "ground", "position": { "x": 50, "y": 300 }, "data": { "label": "GND" } },
+        { "id": "g2", "type": "ground", "position": { "x": 300, "y": 350 }, "data": { "label": "GND" } }
+      ],
+      "edges": [
+        { "id": "e-vac-mcu", "source": "vac1", "target": "mcu1", "sourceHandle": "pos", "targetHandle": "A0", "type": "smoothstep" },
+        { "id": "e-vac-gnd", "source": "vac1", "target": "g1", "sourceHandle": "neg", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-mcu-gnd", "source": "mcu1", "target": "g2", "sourceHandle": "GND", "targetHandle": "in", "type": "smoothstep" }
+      ]
+    },
+    {
+      "title": "BJT Audio Amplifier",
+      "description": "A single-stage common-emitter NPN transistor amplifier amplifying a microphone input signal to drive a speaker load.",
+      "nodes": [
+        { "id": "v1", "type": "voltage", "position": { "x": 100, "y": 50 }, "data": { "label": "12V VCC" } },
+        { "id": "mic1", "type": "microphone", "position": { "x": 100, "y": 300 }, "data": { "label": "Mic Input" } },
+        { "id": "cin", "type": "capacitor", "position": { "x": 250, "y": 300 }, "data": { "label": "10u" } },
+        { "id": "r1", "type": "resistor", "position": { "x": 400, "y": 150 }, "data": { "label": "47k" } },
+        { "id": "r2", "type": "resistor", "position": { "x": 400, "y": 400 }, "data": { "label": "10k" } },
+        { "id": "q1", "type": "npn", "position": { "x": 600, "y": 300 }, "data": { "label": "2N3904 NPN", "bf": 300 } },
+        { "id": "rc", "type": "resistor", "position": { "x": 600, "y": 150 }, "data": { "label": "2.2k" } },
+        { "id": "re", "type": "resistor", "position": { "x": 600, "y": 450 }, "data": { "label": "1k" } },
+        { "id": "cout", "type": "capacitor", "position": { "x": 800, "y": 300 }, "data": { "label": "470u" } },
+        { "id": "spk1", "type": "speaker", "position": { "x": 1000, "y": 300 }, "data": { "label": "Speaker Output", "acCouple": true, "normalize": true } },
+        { "id": "g1", "type": "ground", "position": { "x": 100, "y": 600 }, "data": { "label": "GND" } }
+      ],
+      "edges": [
+        { "id": "e-v1-rc", "source": "v1", "target": "rc", "sourceHandle": "pos", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-v1-r1", "source": "v1", "target": "r1", "sourceHandle": "pos", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-v1-g1", "source": "v1", "target": "g1", "sourceHandle": "neg", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-mic-cin", "source": "mic1", "target": "cin", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-mic-g1", "source": "mic1", "target": "g1", "sourceHandle": "gnd", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r1-b", "source": "r1", "target": "q1", "sourceHandle": "out", "targetHandle": "b", "type": "smoothstep" },
+        { "id": "e-r2-b", "source": "q1", "target": "r2", "sourceHandle": "b", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-r2-g1", "source": "r2", "target": "g1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-cin-b", "source": "cin", "target": "q1", "sourceHandle": "out", "targetHandle": "b", "type": "smoothstep" },
+        { "id": "e-rc-c", "source": "rc", "target": "q1", "sourceHandle": "out", "targetHandle": "c", "type": "smoothstep" },
+        { "id": "e-c-cout", "source": "q1", "target": "cout", "sourceHandle": "c", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-q1-re", "source": "q1", "target": "re", "sourceHandle": "e", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-re-g1", "source": "re", "target": "g1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-cout-spk", "source": "cout", "target": "spk1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-spk-g1", "source": "spk1", "target": "g1", "sourceHandle": "gnd", "targetHandle": "in", "type": "smoothstep" }
+      ]
+    },
+    {
+      "title": "MOSFET Boost Converter",
+      "description": "A switching DC-DC boost converter using an NMOS switch driven by a 50kHz PWM source, stepping up 5V to approximately 25V across a filter capacitor and resistor load.",
+      "nodes": [
+        { "id": "v5v", "type": "voltage", "position": { "x": 50, "y": 250 }, "data": { "label": "5V Input" } },
+        { "id": "l1", "type": "inductor", "position": { "x": 250, "y": 150 }, "data": { "label": "100u" } },
+        { "id": "sw1", "type": "nmos", "position": { "x": 450, "y": 300 }, "data": { "label": "NMOS Switch", "vto": 2.0, "kp": 0.5 } },
+        { "id": "pwm1", "type": "signalgen", "position": { "x": 50, "y": 450 }, "data": { "label": "PWM 50kHz", "waveform": "square", "frequency": 50000, "amplitude": 5, "dutyCycle": 80 } },
+        { "id": "d1", "type": "diode", "position": { "x": 550, "y": 150 }, "data": { "label": "Schottky Diode", "v_drop": 0.3 } },
+        { "id": "c1", "type": "capacitor", "position": { "x": 750, "y": 250 }, "data": { "label": "100u" } },
+        { "id": "rload", "type": "resistor", "position": { "x": 900, "y": 250 }, "data": { "label": "1k Load" } },
+        { "id": "mm_out", "type": "multimeter", "position": { "x": 1000, "y": 250 }, "data": { "label": "Output Volts" } },
+        { "id": "g1", "type": "ground", "position": { "x": 450, "y": 550 }, "data": { "label": "GND" } }
+      ],
+      "edges": [
+        { "id": "e-v5v-l1", "source": "v5v", "target": "l1", "sourceHandle": "pos", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-v5v-gnd", "source": "v5v", "target": "g1", "sourceHandle": "neg", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-l1-sw", "source": "l1", "target": "sw1", "sourceHandle": "out", "targetHandle": "d", "type": "smoothstep" },
+        { "id": "e-l1-d1", "source": "l1", "target": "d1", "sourceHandle": "out", "targetHandle": "anode", "type": "smoothstep" },
+        { "id": "e-sw-gnd", "source": "sw1", "target": "g1", "sourceHandle": "s", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-pwm-sw", "source": "pwm1", "target": "sw1", "sourceHandle": "out", "targetHandle": "g", "type": "smoothstep" },
+        { "id": "e-pwm-gnd", "source": "pwm1", "target": "g1", "sourceHandle": "gnd", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-d1-c1", "source": "d1", "target": "c1", "sourceHandle": "cathode", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-c1-rl", "source": "c1", "target": "rload", "sourceHandle": "in", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-rl-mmout", "source": "rload", "target": "mm_out", "sourceHandle": "in", "targetHandle": "pos", "type": "smoothstep" },
+        { "id": "e-c1-gnd", "source": "c1", "target": "g1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "e-rl-gnd", "source": "rload", "target": "g1", "sourceHandle": "out", "targetHandle": "in", "type": "smoothstep" },
+        { "id": "mmout-neg", "source": "mm_out", "target": "g1", "sourceHandle": "neg", "targetHandle": "in", "type": "smoothstep" }
+      ]
+    }
+  ]
+}