@classytic/stage 0.1.0

package/dist/sim/particles.d.mts

@@ -0,0 +1,43 @@
+import { SimCore } from "./types.mjs";
+
+//#region src/sim/particles.d.ts
+interface Box {
+  w: number;
+  h: number;
+}
+interface ParticlesParams {
+  /** Particle count. Default 80. */
+  n?: number;
+  box?: Box;
+  /** Initial speed (∝ √temperature). Default 2. */
+  speed?: number;
+  /** Particle radius (for collisions + drawing). Default 0.14. */
+  radius?: number;
+  /** Elastic pairwise collisions (thermalises the speed distribution). Default true. */
+  collide?: boolean;
+  /** Start group 0 in the LEFT half, group 1 in the RIGHT half (diffusion). Default false = mixed. */
+  split?: boolean;
+  seed?: number;
+}
+interface ParticlesState {
+  n: number;
+  box: Box;
+  radius: number;
+  collide: boolean;
+  px: number[];
+  py: number[];
+  vx: number[];
+  vy: number[];
+  /** 0 or 1 — two populations (for diffusion / colour). */
+  group: number[];
+  tSec: number;
+  /** Mean kinetic energy ∝ temperature. */
+  temp: number;
+  /** Smoothed pressure (wall-collision momentum per unit time per unit perimeter). */
+  pressure: number;
+  /** Mixing index 0 (separated) → 1 (uniform) — fraction-based, for diffusion. */
+  mixed: number;
+}
+declare const ParticlesCore: SimCore<ParticlesState, ParticlesParams>;
+//#endregion
+export { Box, ParticlesCore, ParticlesParams, ParticlesState };

package/dist/sim/particles.mjs

@@ -0,0 +1,136 @@
+//#region src/sim/particles.ts
+function rng(a) {
+	a = a + 1831565813 | 0;
+	let t = Math.imul(a ^ a >>> 15, 1 | a);
+	t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+	return {
+		r: ((t ^ t >>> 14) >>> 0) / 4294967296,
+		a
+	};
+}
+/** Mixing: group-0's share of the RIGHT half, scaled so 0=separated, 1=uniform. */
+function mixIndex(s) {
+	let g0 = 0, g0right = 0;
+	for (let i = 0; i < s.n; i++) if (s.group[i] === 0) {
+		g0++;
+		if (s.px[i] > s.box.w / 2) g0right++;
+	}
+	if (g0 === 0) return 1;
+	return Math.min(1, g0right / g0 * 2);
+}
+const ParticlesCore = {
+	reset(params = {}) {
+		const n = Math.max(1, Math.min(400, Math.round(params.n ?? 80)));
+		const box = params.box ?? {
+			w: 10,
+			h: 6
+		};
+		const radius = params.radius ?? .14;
+		const collide = params.collide ?? true;
+		const speed = params.speed ?? 2;
+		const split = params.split ?? false;
+		let a = (params.seed ?? 1) | 0;
+		const px = [], py = [], vx = [], vy = [], group = [];
+		for (let i = 0; i < n; i++) {
+			const g = i < n / 2 ? 0 : 1;
+			let rx = rng(a);
+			a = rx.a;
+			let ry = rng(a);
+			a = ry.a;
+			const ra = rng(a);
+			a = ra.a;
+			const xLo = split ? g === 0 ? radius : box.w / 2 + radius : radius;
+			const xHi = split ? g === 0 ? box.w / 2 - radius : box.w - radius : box.w - radius;
+			px.push(xLo + rx.r * (xHi - xLo));
+			py.push(radius + ry.r * (box.h - 2 * radius));
+			const ang = ra.r * Math.PI * 2;
+			vx.push(Math.cos(ang) * speed);
+			vy.push(Math.sin(ang) * speed);
+			group.push(g);
+		}
+		const base = {
+			n,
+			box,
+			radius,
+			collide,
+			px,
+			py,
+			vx,
+			vy,
+			group,
+			tSec: 0,
+			temp: .5 * speed * speed,
+			pressure: 0
+		};
+		return {
+			...base,
+			mixed: mixIndex(base)
+		};
+	},
+	step(state, dtSec) {
+		const dt = Math.min(.04, Math.max(0, dtSec));
+		const { n, box, radius, px, py, vx, vy } = state;
+		let impulse = 0;
+		for (let i = 0; i < n; i++) {
+			px[i] += vx[i] * dt;
+			py[i] += vy[i] * dt;
+			if (px[i] < radius) {
+				px[i] = radius;
+				vx[i] = -vx[i];
+				impulse += 2 * Math.abs(vx[i]);
+			} else if (px[i] > box.w - radius) {
+				px[i] = box.w - radius;
+				vx[i] = -vx[i];
+				impulse += 2 * Math.abs(vx[i]);
+			}
+			if (py[i] < radius) {
+				py[i] = radius;
+				vy[i] = -vy[i];
+				impulse += 2 * Math.abs(vy[i]);
+			} else if (py[i] > box.h - radius) {
+				py[i] = box.h - radius;
+				vy[i] = -vy[i];
+				impulse += 2 * Math.abs(vy[i]);
+			}
+		}
+		if (state.collide) {
+			const d2 = 2 * radius * (2 * radius);
+			for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) {
+				const dx = px[j] - px[i], dy = py[j] - py[i];
+				const dist2 = dx * dx + dy * dy;
+				if (dist2 > 1e-9 && dist2 < d2) {
+					const dist = Math.sqrt(dist2);
+					const nx = dx / dist, ny = dy / dist;
+					const dvn = (vx[j] - vx[i]) * nx + (vy[j] - vy[i]) * ny;
+					if (dvn < 0) {
+						vx[i] += dvn * nx;
+						vy[i] += dvn * ny;
+						vx[j] -= dvn * nx;
+						vy[j] -= dvn * ny;
+					}
+					const overlap = (2 * radius - dist) / 2;
+					px[i] -= nx * overlap;
+					py[i] -= ny * overlap;
+					px[j] += nx * overlap;
+					py[j] += ny * overlap;
+				}
+			}
+		}
+		let ke = 0;
+		for (let i = 0; i < n; i++) ke += vx[i] * vx[i] + vy[i] * vy[i];
+		const temp = .5 * ke / n;
+		const perim = 2 * (box.w + box.h);
+		const instP = dt > 0 ? impulse / (dt * perim) : 0;
+		const pressure = state.pressure * .9 + instP * .1;
+		return {
+			...state,
+			tSec: state.tSec + dt,
+			temp,
+			pressure,
+			mixed: mixIndex(state)
+		};
+	}
+};
+
+//#endregion
+export { ParticlesCore };

package/dist/sim/rate.d.mts

@@ -0,0 +1,36 @@
+import { SimCore } from "./types.mjs";
+
+//#region src/sim/rate.d.ts
+interface RateParams {
+  /** Initial value. Named `value0`, NOT `value`: the runtime merges params onto
+   *  state each frame, so an evolving field sharing a param name would be reset
+   *  every step (the `value` would never relax). Keep them disjoint. */
+  value0?: number;
+  /** Asymptote the value relaxes toward. Default 0 (pure decay). */
+  target?: number;
+  /** Time constant τ (seconds) — the e-folding time. Default 1. */
+  tau?: number;
+  /** Stop after this many seconds (essentially relaxed) so it doesn't run forever. Default ∞. */
+  maxTime?: number;
+  /** Trace ring-buffer capacity. Default 240. */
+  trace?: number;
+}
+interface RateState {
+  value: number;
+  target: number;
+  tau: number;
+  /** Seconds elapsed on this core's timeline. */
+  tSec: number;
+  /** Rolling history of `value`, oldest-first — for the curve. */
+  samples: number[];
+  cap: number;
+  maxTime: number;
+  /** True once tSec ≥ maxTime — the runtime stops the loop. */
+  done: boolean;
+}
+declare const RateCore: SimCore<RateState, RateParams>;
+/** τ from a half-life (and back) — t½ = τ·ln2. */
+declare const halfLifeToTau: (halfLife: number) => number;
+declare const tauToHalfLife: (tau: number) => number;
+//#endregion
+export { RateCore, RateParams, RateState, halfLifeToTau, tauToHalfLife };

package/dist/sim/rate.mjs

@@ -0,0 +1,39 @@
+//#region src/sim/rate.ts
+const RateCore = {
+	reset(params = {}) {
+		const value = params.value0 ?? 1;
+		return {
+			value,
+			target: params.target ?? 0,
+			tau: Math.max(.001, params.tau ?? 1),
+			tSec: 0,
+			samples: [value],
+			cap: Math.max(2, Math.round(params.trace ?? 240)),
+			maxTime: params.maxTime ?? Infinity,
+			done: false
+		};
+	},
+	step(state, dtSec) {
+		if (state.tSec >= state.maxTime) return state.done ? state : {
+			...state,
+			done: true
+		};
+		const dt = Math.max(0, dtSec);
+		const value = state.target + (state.value - state.target) * Math.exp(-dt / state.tau);
+		const tSec = state.tSec + dt;
+		const samples = state.samples.length >= state.cap ? [...state.samples.slice(state.samples.length - state.cap + 1), value] : [...state.samples, value];
+		return {
+			...state,
+			value,
+			tSec,
+			samples,
+			done: tSec >= state.maxTime
+		};
+	}
+};
+/** τ from a half-life (and back) — t½ = τ·ln2. */
+const halfLifeToTau = (halfLife) => halfLife / Math.LN2;
+const tauToHalfLife = (tau) => tau * Math.LN2;
+
+//#endregion
+export { RateCore, halfLifeToTau, tauToHalfLife };

package/dist/sim/registry.d.mts

@@ -0,0 +1,10 @@
+import { SimCore } from "./types.mjs";
+
+//#region src/sim/registry.d.ts
+/** A core with its specifics erased — the runtime reads state fields by name. */
+type AnySim = SimCore<Record<string, unknown>, Record<string, unknown>>;
+declare function registerSim<S extends Record<string, unknown>, P>(name: string, core: SimCore<S, P>): void;
+declare function getSim(name: string): AnySim | undefined;
+declare function listSims(): string[];
+//#endregion
+export { getSim, listSims, registerSim };

package/dist/sim/registry.mjs

@@ -0,0 +1,27 @@
+import { WaveCore } from "./wave.mjs";
+import { SamplerCore } from "./sampler.mjs";
+import { RateCore } from "./rate.mjs";
+import { ParticlesCore } from "./particles.mjs";
+import { ThermalCore } from "./thermal.mjs";
+import { EquilibriumCore } from "./equilibrium.mjs";
+
+//#region src/sim/registry.ts
+const SIMS = /* @__PURE__ */ new Map();
+SIMS.set("wave", WaveCore);
+SIMS.set("sampler", SamplerCore);
+SIMS.set("rate", RateCore);
+SIMS.set("particles", ParticlesCore);
+SIMS.set("thermal", ThermalCore);
+SIMS.set("equilibrium", EquilibriumCore);
+function registerSim(name, core) {
+	SIMS.set(name, core);
+}
+function getSim(name) {
+	return SIMS.get(name);
+}
+function listSims() {
+	return [...SIMS.keys()];
+}
+
+//#endregion
+export { getSim, listSims, registerSim };

package/dist/sim/sampler.d.mts

@@ -0,0 +1,47 @@
+import { SimCore } from "./types.mjs";
+
+//#region src/sim/sampler.d.ts
+interface SamplerParams {
+  /** Relative weights per outcome. Default [1, 1] (a fair coin). */
+  weights?: number[];
+  /** Draws per step. Default 1 (raise to converge faster). */
+  perStep?: number;
+  /** PRNG seed. Default 1. */
+  seed?: number;
+  /** Stop drawing once `n` reaches this — a converged sim shouldn't run forever. Default ∞. */
+  maxDraws?: number;
+  /** History ring-buffer capacity for the headline estimate p[0]. Default 240. */
+  trace?: number;
+}
+interface SamplerState {
+  weights: number[];
+  perStep: number;
+  /**
+   * Current PRNG state (advances every draw). Deliberately NOT named `seed`: the
+   * Scene runtime merges the SimDecl `params` (which carries the initial `seed`)
+   * onto the state each frame, so an evolving field sharing a param name would be
+   * clobbered back to its initial value — freezing the RNG. Keep evolving state
+   * fields disjoint from param names.
+   */
+  rng: number;
+  /** Total draws so far. */
+  n: number;
+  /** Per-outcome counts. */
+  counts: number[];
+  /** Running frequency estimate per outcome (counts / n). */
+  p: number[];
+  /** True (normalized) probabilities — for convergence comparison. */
+  p0: number[];
+  /** Index of the most recent draw (-1 before the first). */
+  last: number;
+  /** Rolling history of p[0], oldest-first — for an LLN convergence plot. */
+  samples: number[];
+  cap: number;
+  /** Draw cap; step() becomes a no-op once n reaches it. */
+  maxDraws: number;
+  /** True once n ≥ maxDraws — the runtime stops the loop. */
+  done: boolean;
+}
+declare const SamplerCore: SimCore<SamplerState, SamplerParams>;
+//#endregion
+export { SamplerCore, SamplerParams, SamplerState };

package/dist/sim/sampler.mjs

@@ -0,0 +1,79 @@
+//#region src/sim/sampler.ts
+/** Pure mulberry32 step: returns a uniform r∈[0,1) and the next PRNG state. */
+function rng(a) {
+	a = a + 1831565813 | 0;
+	let t = Math.imul(a ^ a >>> 15, 1 | a);
+	t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+	return {
+		r: ((t ^ t >>> 14) >>> 0) / 4294967296,
+		a
+	};
+}
+function pick(weights, total, r) {
+	let x = r * total;
+	for (let i = 0; i < weights.length - 1; i++) {
+		const w = weights[i] ?? 0;
+		if (x < w) return i;
+		x -= w;
+	}
+	return weights.length - 1;
+}
+function normalize(weights) {
+	const total = weights.reduce((a, b) => a + b, 0) || 1;
+	return weights.map((w) => w / total);
+}
+const SamplerCore = {
+	reset(params = {}) {
+		const weights = params.weights && params.weights.length >= 2 ? params.weights.slice() : [1, 1];
+		const k = weights.length;
+		return {
+			weights,
+			perStep: Math.max(1, Math.round(params.perStep ?? 1)),
+			rng: (params.seed ?? 1) | 0,
+			n: 0,
+			counts: new Array(k).fill(0),
+			p: new Array(k).fill(0),
+			p0: normalize(weights),
+			last: -1,
+			samples: [0],
+			cap: Math.max(2, Math.round(params.trace ?? 240)),
+			maxDraws: params.maxDraws ?? Infinity,
+			done: false
+		};
+	},
+	step(state) {
+		if (state.n >= state.maxDraws) return state.done ? state : {
+			...state,
+			done: true
+		};
+		state.weights.length;
+		const total = state.weights.reduce((a, b) => a + b, 0) || 1;
+		const counts = state.counts.slice();
+		let a = state.rng;
+		let last = state.last;
+		for (let d = 0; d < state.perStep; d++) {
+			const next = rng(a);
+			a = next.a;
+			last = pick(state.weights, total, next.r);
+			counts[last] = (counts[last] ?? 0) + 1;
+		}
+		const n = state.n + state.perStep;
+		const p = counts.map((c) => c / n);
+		const head = p[0] ?? 0;
+		const samples = state.samples.length >= state.cap ? [...state.samples.slice(state.samples.length - state.cap + 1), head] : [...state.samples, head];
+		return {
+			...state,
+			rng: a,
+			n,
+			counts,
+			p,
+			p0: normalize(state.weights),
+			last,
+			samples,
+			done: n >= state.maxDraws
+		};
+	}
+};
+
+//#endregion
+export { SamplerCore };

package/dist/sim/thermal.d.mts

@@ -0,0 +1,78 @@
+import { SimCore } from "./types.mjs";
+
+//#region src/sim/thermal.d.ts
+/** A material: how much heat each gram needs to warm 1 °C in each phase, the
+ *  latent heats of its two transitions, and where those transitions sit. */
+interface Substance {
+  name: string;
+  solidName: string;
+  liquidName: string;
+  gasName: string;
+  /** Specific heat capacities, J/(g·°C), one per phase. */
+  cSolid: number;
+  cLiquid: number;
+  cGas: number;
+  /** Latent heat of fusion (melting) and vaporisation (boiling), J/g. */
+  lFusion: number;
+  lVapor: number;
+  /** Transition temperatures, °C. */
+  tMelt: number;
+  tBoil: number;
+  /** Liquid colour token (for the skin). */
+  color: string;
+}
+/** Real water — the canonical example (note: latent vaporisation ≫ everything,
+ *  so the boiling plateau dwarfs the rest, which is exactly the lesson). */
+declare const WATER: Substance;
+/** Ethanol — lower boiling point, smaller latent heats; a contrasting curve. */
+declare const ETHANOL: Substance;
+type Phase = 'solid' | 'melting' | 'liquid' | 'boiling' | 'gas';
+/** One run of the energy ladder. `kind:'heat'` is a sloped temperature rise
+ *  (q = m·c·Δθ); `kind:'change'` is a flat phase transition (q = m·L). */
+interface ThermalSeg {
+  phase: Phase;
+  kind: 'heat' | 'change';
+  which: 'melt' | 'boil' | null;
+  /** Heat this segment absorbs, J. */
+  q: number;
+  /** Cumulative heat at the START of this segment, J (x-position on the curve). */
+  qStart: number;
+  /** Temperature at the start / end of the segment, °C (equal for a change). */
+  t0: number;
+  t1: number;
+}
+interface ThermalParams {
+  substance?: Substance;
+  /** Mass, grams. Default 50. */
+  mass?: number;
+  /** Heating power, J/s. Negative cools. Default 100. */
+  powerW?: number;
+  /** Starting temperature, °C. Default −20 (cold ice). */
+  tStart?: number;
+  /** Top of the curve / highest temperature shown, °C. Default tBoil + 40. */
+  tMax?: number;
+}
+interface ThermalState {
+  sub: Substance;
+  mass: number;
+  powerW: number;
+  tStart: number;
+  tMax: number;
+  /** The full energy ladder — the heating curve, as data. */
+  segs: ThermalSeg[];
+  /** Total heat to walk the whole ladder, J. */
+  totalJ: number;
+  energyJ: number;
+  tempC: number;
+  phase: Phase;
+  /** Completion of the melting / boiling transitions, 0..1. */
+  fracMelt: number;
+  fracBoil: number;
+  tSec: number;
+  done: boolean;
+}
+declare const ThermalCore: SimCore<ThermalState, ThermalParams>;
+/** Human label for a segment ("warming ice", "melting", "boiling"…). */
+declare function segLabel(s: ThermalSeg, sub: Substance): string;
+//#endregion
+export { ETHANOL, Phase, Substance, ThermalCore, ThermalParams, ThermalSeg, ThermalState, WATER, segLabel };

package/dist/sim/thermal.mjs

@@ -0,0 +1,172 @@
+//#region src/sim/thermal.ts
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+/** Real water — the canonical example (note: latent vaporisation ≫ everything,
+*  so the boiling plateau dwarfs the rest, which is exactly the lesson). */
+const WATER = {
+	name: "Water",
+	solidName: "ice",
+	liquidName: "water",
+	gasName: "steam",
+	cSolid: 2.09,
+	cLiquid: 4.18,
+	cGas: 2.01,
+	lFusion: 334,
+	lVapor: 2260,
+	tMelt: 0,
+	tBoil: 100,
+	color: "var(--stage-accent, #3b82f6)"
+};
+/** Ethanol — lower boiling point, smaller latent heats; a contrasting curve. */
+const ETHANOL = {
+	name: "Ethanol",
+	solidName: "solid",
+	liquidName: "ethanol",
+	gasName: "vapour",
+	cSolid: 1.2,
+	cLiquid: 2.44,
+	cGas: 1.42,
+	lFusion: 108,
+	lVapor: 855,
+	tMelt: -114,
+	tBoil: 78,
+	color: "var(--stage-accent-2, #8b5cf6)"
+};
+/** Build the energy ladder from `tStart` up to `tMax`, including only the phases
+*  reachable heating upward (a liquid start skips the solid+melting runs). */
+function buildSegs(sub, mass, tStart, tMax) {
+	const segs = [];
+	let cum = 0;
+	const push = (s) => {
+		segs.push({
+			...s,
+			qStart: cum
+		});
+		cum += Math.max(0, s.q);
+	};
+	let t = tStart;
+	if (t < sub.tMelt) {
+		push({
+			phase: "solid",
+			kind: "heat",
+			which: null,
+			q: mass * sub.cSolid * (sub.tMelt - t),
+			t0: t,
+			t1: sub.tMelt
+		});
+		push({
+			phase: "melting",
+			kind: "change",
+			which: "melt",
+			q: mass * sub.lFusion,
+			t0: sub.tMelt,
+			t1: sub.tMelt
+		});
+		t = sub.tMelt;
+	}
+	if (t < sub.tBoil) {
+		push({
+			phase: "liquid",
+			kind: "heat",
+			which: null,
+			q: mass * sub.cLiquid * (sub.tBoil - t),
+			t0: t,
+			t1: sub.tBoil
+		});
+		push({
+			phase: "boiling",
+			kind: "change",
+			which: "boil",
+			q: mass * sub.lVapor,
+			t0: sub.tBoil,
+			t1: sub.tBoil
+		});
+		t = sub.tBoil;
+	}
+	push({
+		phase: "gas",
+		kind: "heat",
+		which: null,
+		q: Math.max(0, mass * sub.cGas * (tMax - t)),
+		t0: t,
+		t1: tMax
+	});
+	return segs;
+}
+/** Temperature / phase / transition-fractions at a given heat-added (pure). */
+function derive(segs, totalJ, energyRaw) {
+	const e = Math.max(0, Math.min(totalJ, energyRaw));
+	let fracMelt = 0, fracBoil = 0;
+	for (const s of segs) {
+		if (s.which === "melt") fracMelt = s.q > 0 ? clamp01((e - s.qStart) / s.q) : 1;
+		if (s.which === "boil") fracBoil = s.q > 0 ? clamp01((e - s.qStart) / s.q) : 1;
+	}
+	let tempC = segs[0].t0, phase = segs[0].phase;
+	for (let i = 0; i < segs.length; i++) {
+		const s = segs[i];
+		const last = i === segs.length - 1;
+		if (e <= s.qStart + s.q || last) {
+			const f = s.q > 0 ? clamp01((e - s.qStart) / s.q) : 1;
+			tempC = s.kind === "change" ? s.t0 : s.t0 + f * (s.t1 - s.t0);
+			phase = s.phase;
+			break;
+		}
+	}
+	return {
+		tempC,
+		phase,
+		fracMelt,
+		fracBoil
+	};
+}
+const ThermalCore = {
+	reset(params = {}) {
+		const sub = params.substance ?? WATER;
+		const mass = Math.max(.001, params.mass ?? 50);
+		const tStart = params.tStart ?? -20;
+		const tMax = params.tMax ?? sub.tBoil + 40;
+		const segs = buildSegs(sub, mass, tStart, tMax);
+		const totalJ = segs.reduce((a, s) => a + s.q, 0);
+		const d = derive(segs, totalJ, 0);
+		return {
+			sub,
+			mass,
+			powerW: params.powerW ?? 100,
+			tStart,
+			tMax,
+			segs,
+			totalJ,
+			energyJ: 0,
+			tempC: d.tempC,
+			phase: d.phase,
+			fracMelt: 0,
+			fracBoil: 0,
+			tSec: 0,
+			done: false
+		};
+	},
+	step(state, dtSec) {
+		const dt = Math.max(0, dtSec);
+		const energyJ = Math.max(0, Math.min(state.totalJ, state.energyJ + state.powerW * dt));
+		const d = derive(state.segs, state.totalJ, energyJ);
+		const done = state.powerW >= 0 && energyJ >= state.totalJ || state.powerW < 0 && energyJ <= 0;
+		return {
+			...state,
+			energyJ,
+			tempC: d.tempC,
+			phase: d.phase,
+			fracMelt: d.fracMelt,
+			fracBoil: d.fracBoil,
+			tSec: state.tSec + dt,
+			done
+		};
+	}
+};
+/** Human label for a segment ("warming ice", "melting", "boiling"…). */
+function segLabel(s, sub) {
+	if (s.which === "melt") return `melting ${sub.solidName}`;
+	if (s.which === "boil") return `boiling ${sub.liquidName}`;
+	return `warming ${s.phase === "solid" ? sub.solidName : s.phase === "gas" ? sub.gasName : sub.liquidName}`;
+}
+
+//#endregion
+export { ETHANOL, ThermalCore, WATER, segLabel };

package/dist/sim/types.d.mts

@@ -0,0 +1,24 @@
+//#region src/sim/types.d.ts
+/**
+ * Sim cores — the "physics engine" half of a lab: pure, time-stepped simulators
+ * with NO React and NO pixels. A core is `reset(params) → state`, then
+ * `step(state, dt) → state` once per frame. Because a core is a pure function of
+ * (params, elapsed time), a lab built on one is deterministic: it replays
+ * identically under a Remotion fixed-frame clock (→ video) and is unit-testable
+ * with no DOM. Rendering (glyphs) READS the returned state; drawing never lives
+ * in here. Live controls write their target fields onto `state` between steps —
+ * so a core's mutable inputs (e.g. `volts`, `mode`) live IN its state, which is
+ * also why those fields are readable by name from a binding.
+ */
+interface SimCore<S, P> {
+  /** Build initial state from params. Pure. */
+  reset(params: P): S;
+  /**
+   * Advance `state` by `dtSec` and return the NEXT state. Treat the incoming
+   * `state` as immutable (return a fresh object) so the runtime can keep the
+   * previous snapshot for change detection.
+   */
+  step(state: S, dtSec: number): S;
+}
+//#endregion
+export { SimCore };