);
}
const FSB_PROBE_COLORS = ["#39ff14", "#8be0ff", "#ffd166", "#ff5a72"];
const FSB_STORE = "hte-sandbox-v1";
function FlowSandbox() {
const [t, setTweak] = useTweaks({ theme: "paper", audience: "adult" });
useCrossChapterPersistence(t, setTweak);
fsbUseEffect(() => { document.body.setAttribute("data-theme", t.theme); }, [t.theme]);
const [flow, setFlow] = fsbUseState(1);
const [hoverId, setHoverId] = fsbUseState(null);
const [selId, setSelId] = fsbUseState(null);
const [parts, setParts] = fsbUseState(() => {
try {
const exq = new URLSearchParams(location.search).get("ex");
if (exq) { const ex = FSB_EXAMPLES.find(e => e.key === exq); if (ex) return ex.make(); }
} catch (_) {}
try { const s = JSON.parse(localStorage.getItem(FSB_STORE)); if (s && Array.isArray(s.parts) && s.parts.length) return s.parts; } catch (_) {}
return FSB_DEMO;
});
const [dragging, setDragging] = fsbUseState(false);
const [tool, setTool] = fsbUseState("select");
const [exCat, setExCat] = fsbUseState(() => {
try { const k = new URLSearchParams(location.search).get("ex"); const ex = FSB_EXAMPLES.find(e => e.key === k); if (ex) return ex.cat; } catch (_) {}
return "Basics";
});
const [exKey, setExKey] = fsbUseState(() => {
try {
const k = new URLSearchParams(location.search).get("ex");
if (FSB_EXAMPLES.some(e => e.key === k)) return k; // explicit deep link
const s = JSON.parse(localStorage.getItem(FSB_STORE));
if (s && Array.isArray(s.parts) && s.parts.length) return null; // restored custom circuit
} catch (_) {}
return "series"; // fresh → demo is series
});
const [probes, setProbes] = fsbUseState([]);
const svgRef = fsbUseRef(null);
const dragRef = fsbUseRef(null);
const probeDragRef = fsbUseRef(null);
const movedRef = fsbUseRef(false);
const idRef = fsbUseRef(1);
const selRef = fsbUseRef(null);
selRef.current = selId;
const newId = () => "p" + (idRef.current++);
// start id counter past any restored part ids
fsbUseEffect(() => {
let mx = 0; parts.forEach(p => { const m = /^p(\d+)$/.exec(p.id); if (m) mx = Math.max(mx, +m[1]); });
if (mx >= idRef.current) idRef.current = mx + 1;
// place the starting example's key probes (deep link or fresh demo)
const meta = exKey ? FSB_EX_META[exKey] : null;
if (meta && meta.probes) {
const placed = meta.probes.slice(0, 4).map((pr, i) => {
const id = "probe_init_" + i;
bufsRef.current[id] = [];
return { id, x: pr.x, y: pr.y, color: FSB_PROBE_COLORS[i], label: pr.label || null };
});
setProbes(placed);
}
}, []);
// persist circuit (debounced via rAF-ish microtask)
fsbUseEffect(() => {
try { localStorage.setItem(FSB_STORE, JSON.stringify({ parts })); } catch (_) {}
}, [parts]);
// ── probes (scope) ──
const probesRef = fsbUseRef([]);
probesRef.current = probes;
const bufsRef = fsbUseRef({});
const addProbe = (pt) => {
setProbes(prev => {
if (prev.length >= 4) return prev;
if (prev.some(p => p.x === pt.x && p.y === pt.y)) return prev;
const used = prev.map(p => p.color);
const color = FSB_PROBE_COLORS.find(c => !used.includes(c)) || FSB_PROBE_COLORS[prev.length % 4];
const id = "probe" + Date.now() + Math.round(Math.random() * 999);
bufsRef.current[id] = [];
return [...prev, { id, x: pt.x, y: pt.y, color, label: pt.label || null }];
});
};
const removeProbe = (id) => { setProbes(prev => prev.filter(p => p.id !== id)); delete bufsRef.current[id]; };
const clearProbes = () => { setProbes([]); bufsRef.current = {}; };
// start dragging an existing probe (works in any tool mode)
const onProbeDown = (e, pr) => {
e.preventDefault(); e.stopPropagation();
probeDragRef.current = pr.id;
movedRef.current = false;
setDragging(true);
try { svgRef.current.setPointerCapture(e.pointerId); } catch (_) {}
};
// nearest part endpoint to a click (for probe placement) — bind to the EXACT
// endpoint coord (no grid snap; example geometry isn't on the 20px grid, and
// flrVoltAt matches the endpoint's exact key).
const nearestNode = (p) => {
let best = null, bd = 26;
parts.forEach(pt => pt.ends.forEach(e => { const d = Math.hypot(e.x - p.x, e.y - p.y); if (d < bd) { bd = d; best = { x: e.x, y: e.y }; } }));
return best;
};
const toSvg = (e) => {
const svg = svgRef.current;
const pt = svg.createSVGPoint();
pt.x = e.clientX; pt.y = e.clientY;
const sp = pt.matrixTransform(svg.getScreenCTM().inverse());
return { x: sp.x, y: sp.y };
};
const addPart = (type) => { const id = newId(); setParts(prev => [...prev, fsbMakeDefault(type, id)]); setSelId(id); setTool("select"); };
const loadExample = (ex) => {
setParts(ex.make());
setSelId(null); setTool("select"); setExKey(ex.key);
bufsRef.current = {};
// start the example FRESH — drop any carried-over reactive state (a charged
// cap / inductor current) so RC ramps and LC ringing always restart cleanly.
engRef.current = null; linkRef.current = null; vR.current = [];
// auto-place the example's key probes
const meta = FSB_EX_META[ex.key];
if (meta && meta.probes) {
const placed = meta.probes.slice(0, 4).map((pr, i) => {
const id = "probe" + Date.now() + "_" + i;
bufsRef.current[id] = [];
return { id, x: pr.x, y: pr.y, color: FSB_PROBE_COLORS[i], label: pr.label || null };
});
setProbes(placed);
} else {
setProbes([]);
}
};
const deletePart = (id) => { setParts(prev => prev.filter(p => p.id !== id)); setSelId(s => s === id ? null : s); };
const rotatePart = (id) => setParts(prev => prev.map(pt => {
if (pt.id !== id || pt.ends.length < 2) return pt;
const mx = (pt.ends[0].x + pt.ends[1].x) / 2, my = (pt.ends[0].y + pt.ends[1].y) / 2;
return { ...pt, ends: pt.ends.map(en => fsbSnapPt({ x: mx - (en.y - my), y: my + (en.x - mx) })) };
}));
const setValue = (id, patch) => setParts(prev => prev.map(pt => pt.id === id ? { ...pt, ...patch } : pt));
const toggleSwitch = (id) => setParts(prev => prev.map(pt => pt.id === id ? { ...pt, closed: !pt.closed } : pt));
const onPartDown = (e, pt) => {
if (tool === "probe") { const n = nearestNode(toSvg(e)); if (n) addProbe(n); e.preventDefault(); return; }
if (tool === "wire") return;
e.preventDefault();
const p = toSvg(e);
let mode = "body", endIndex = -1, best = 13;
pt.ends.forEach((en, i) => { const d = Math.hypot(en.x - p.x, en.y - p.y); if (d < best) { best = d; mode = "end"; endIndex = i; } });
dragRef.current = { id: pt.id, mode, endIndex, start: p, orig: pt.ends.map(en => ({ ...en })), type: pt.type };
movedRef.current = false;
setSelId(pt.id); setDragging(true);
try { svgRef.current.setPointerCapture(e.pointerId); } catch (_) {}
};
const onBgDown = (e) => {
if (tool === "probe") { const n = nearestNode(toSvg(e)); if (n) addProbe(n); e.preventDefault(); return; }
if (tool !== "wire") return;
e.preventDefault();
const p = fsbSnapPt(toSvg(e));
const id = newId();
setParts(prev => [...prev, { id, type: "wire", ends: [{ ...p }, { ...p }] }]);
dragRef.current = { id, mode: "end", endIndex: 1, start: p, orig: [{ ...p }, { ...p }], wireDraw: true };
movedRef.current = false;
setSelId(id); setDragging(true);
try { svgRef.current.setPointerCapture(e.pointerId); } catch (_) {}
};
const onSvgMove = (e) => {
// dragging a probe — follow cursor, stick to the nearest node when in range
if (probeDragRef.current) {
const p = toSvg(e);
const n = nearestNode(p);
const pos = n || { x: p.x, y: p.y };
movedRef.current = true;
setProbes(prev => prev.map(pr => pr.id === probeDragRef.current ? { ...pr, x: pos.x, y: pos.y, snapped: !!n } : pr));
return;
}
const d = dragRef.current; if (!d) return;
const p = toSvg(e);
const dx = p.x - d.start.x, dy = p.y - d.start.y;
if (Math.hypot(dx, dy) > 5) movedRef.current = true;
setParts(prev => prev.map(pt => {
if (pt.id !== d.id) return pt;
if (d.mode === "end") {
const ends = pt.ends.map((en, i) => i === d.endIndex ? { x: fsbSnap(d.orig[i].x + dx), y: fsbSnap(d.orig[i].y + dy) } : en);
return { ...pt, ends };
}
const sdx = fsbSnap(dx), sdy = fsbSnap(dy);
return { ...pt, ends: d.orig.map(en => ({ x: en.x + sdx, y: en.y + sdy })) };
}));
};
const onSvgUp = (e) => {
// finish a probe drag: clear its buffer so the scope reads fresh from the new node
if (probeDragRef.current) {
const id = probeDragRef.current;
if (movedRef.current) { bufsRef.current[id] = []; setProbes(prev => prev.map(pr => pr.id === id ? { ...pr, label: null } : pr)); }
try { svgRef.current.releasePointerCapture(e.pointerId); } catch (_) {}
probeDragRef.current = null; setDragging(false);
return;
}
const d = dragRef.current;
if (d) { try { svgRef.current.releasePointerCapture(e.pointerId); } catch (_) {} }
if (d && d.wireDraw) {
setParts(prev => prev.filter(pt => !(pt.id === d.id && pt.ends[0].x === pt.ends[1].x && pt.ends[0].y === pt.ends[1].y)));
setTool("select");
} else if (d && !movedRef.current && d.type === "switch") {
toggleSwitch(d.id); // tap a switch (no drag) → toggle
}
dragRef.current = null; setDragging(false);
};
fsbUseEffect(() => {
const onKey = (e) => {
if (/input|textarea/i.test((e.target.tagName || ""))) return;
const id = selRef.current; if (!id && e.key !== "Escape") return;
if (e.key === "r" || e.key === "R") rotatePart(id);
else if (e.key === "Delete" || e.key === "Backspace") { e.preventDefault(); deletePart(id); }
else if (e.key === "Escape") { setSelId(null); setTool("select"); }
};
window.addEventListener("keydown", onKey);
return () => window.removeEventListener("keydown", onKey);
}, []);
// ── real-time engine: refs persist; rebuild on TOPOLOGY change, sync values live ──
const engRef = fsbUseRef(null);
const linkRef = fsbUseRef(null);
const vR = fsbUseRef([]);
const [, fsbForce] = fsbUseState(0);
// topology key = structure only (geometry + switch state), NOT values — so
// dragging a value slider doesn't reset the cap/inductor dynamics.
const topoKey = fsbUseMemo(() =>
parts.map(p => p.type + "@" + p.ends.map(e => fsbSnap(e.x) + "," + fsbSnap(e.y)).join("|") + (p.type === "switch" ? (p.closed ? "C" : "O") : "")).join(";"),
[parts]);
const link = fsbUseMemo(() => window.flBuildNetlist(parts), [topoKey]);
// rebuild the engine SYNCHRONOUSLY when topology (link) changes, so eng always
// matches the current link within the same render (no stale-index crash).
if (linkRef.current !== link) {
const oldLink = linkRef.current, oldEng = engRef.current;
// snapshot reactive state (cap voltage / inductor current) by part id, so a
// switch toggle or drag doesn't wipe a charged capacitor — only Reset / a new
// example (fresh ids) starts from zero.
const snap = {};
if (oldLink && oldEng) parts.forEach(p => {
if (p.type !== "cap" && p.type !== "ind") return;
const oi = oldLink.partElem.get(p.id); if (oi == null) return;
snap[p.id] = p.type === "cap" ? oldEng.getCapV(oi) : oldEng.getIndI(oi);
});
const neweng = window.mnaCreate(link.netlist);
parts.forEach(p => {
if (snap[p.id] == null) return;
const ni = link.partElem.get(p.id); if (ni == null) return;
if (p.type === "cap") neweng.setCapV(ni, snap[p.id]);
else if (p.type === "ind") neweng.setIndI(ni, snap[p.id]);
});
linkRef.current = link;
engRef.current = neweng;
vR.current = [];
}
const eng = engRef.current;
// sync element values every render (cheap; eng matches link here)
if (eng) parts.forEach(p => {
const ei = link.partElem.get(p.id); if (ei == null) return;
const el = eng.els[ei]; if (!el) return;
if (p.type === "resistor") el.ohms = p.value;
else if (p.type === "battery") el.volts = p.volts;
else if (p.type === "cap") el.farads = p.value / 330;
else if (p.type === "ind") el.henries = p.value;
else if (p.type === "pot") {
const total = p.value != null ? p.value : 10000;
const pos = p.pos != null ? p.pos : 0.5;
el.ohms = Math.max(1, total * (1 - pos)); // a → wiper
const ei2 = link.partElem2.get(p.id);
const el2 = ei2 != null ? eng.els[ei2] : null;
if (el2) el2.ohms = Math.max(1, total * pos); // wiper → b
}
});
fsbUseEffect(() => {
let raf, last = performance.now(), acc = 0;
const loop = (now) => {
const e = engRef.current;
if (e) {
const simT = Math.min(0.05, (now - last) / 1000); // 1 sim-second : 1 real-second
const dt = 1 / 240, n = Math.max(1, Math.min(40, Math.round(simT / dt)));
let vv; for (let i = 0; i < n; i++) vv = e.step(dt);
if (vv) vR.current = vv;
acc += (now - last);
if (acc >= 33) {
acc = 0;
// sample probes into ring buffers
const lk = linkRef.current, vv2 = vR.current;
if (lk && vv2 && vv2.length && probesRef.current.length) {
probesRef.current.forEach(pr => {
const buf = bufsRef.current[pr.id] || (bufsRef.current[pr.id] = []);
buf.push(window.flrVoltAt({ x: pr.x, y: pr.y }, lk, vv2));
if (buf.length > 240) buf.shift();
});
}
fsbForce(t => t + 1);
}
}
last = now;
raf = requestAnimationFrame(loop);
};
raf = requestAnimationFrame(loop);
return () => cancelAnimationFrame(raf);
}, []);
const v = vR.current;
const vref = Math.max(1, ...(v || []).map(x => Math.abs(x)));
const wireCur = (eng && v && v.length) ? window.flWireCurrents(parts, link, eng, v) : new Map();
// inspector locks to the SELECTED part; hover only previews when nothing is selected
const selPart = parts.find(p => p.id === selId) || null;
const displayPart = selPart || parts.find(p => p.id === hoverId) || null;
const readout = (displayPart && eng && v && v.length) ? window.flPartReadout(displayPart, parts, link, v, eng, wireCur) : null;
const adjustables = parts.filter(fsbAdjustable);
const activeMeta = FSB_EX_META[exKey] || null;
const customCircuit = !FSB_EXAMPLES.some(e => e.key === exKey) || activeMeta == null;
return (
<>
setTweak("audience", a)} />
the sandbox · see how it works
The Sandbox
See how a circuit works. Wire anything, probe anything, and watch the charges, voltages, and currents move.
Add parts, drag them into place, draw wires to connect — every adjustable part gets a
slider in the rail on the right; drag a battery below zero to reverse the current. Tap a switch to open/close it.
Endpoints sharing a grid point connect automatically. A circuit needs one battery and a ground (0 V reference) to solve.
*capacitor µF is illustrative — the timescale is compressed for watching.