@classytic/labs 0.1.0

package/dist/chem/solution/dilution.mjs

@@ -0,0 +1,199 @@
+'use client';
+
+import { clamp } from "../../core/util.mjs";
+import { Tex } from "../../core/tex.mjs";
+import { Slider } from "../../kit/controls.mjs";
+import { Callout, ControlBar, Field, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { ChallengeCard, useChallenge, useCheckpoint } from "../../kit/pedagogy.mjs";
+import { SolutionField } from "./field.mjs";
+import { useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/chem/solution/dilution.tsx
+/**
+* DilutionLab — C₁V₁ = C₂V₂ is just: the dots don't leave.
+*
+* Take an aliquot of stock (V₁) and dilute it to a final volume (V₂). Two beakers
+* show the SAME solute dots — concentrated in the small aliquot on the left,
+* spread through the larger volume on the right — so the conserved quantity
+* (moles = C·V) is SEEN, not memorized: same dots, bigger box, paler colour, lower
+* C. Composes the shared SolutionField (single source of truth for the dots).
+*
+* Rearranging C₁V₁=C₂V₂ for an unknown / serial dilutions → a paired MathDerivation.
+*/
+const DOTS_PER_MOL = 200;
+/** Predict the conserved quantity: moles (dots) don't change on dilution, so adding water lowers C. */
+const DILUTION_CHALLENGE = [{
+	id: "conserved",
+	prompt: "You dilute the aliquot to a larger final volume. What stays the SAME?",
+	choices: [
+		{
+			value: "moles",
+			label: "the moles of solute (the dots)"
+		},
+		{
+			value: "conc",
+			label: "the concentration"
+		},
+		{
+			value: "volume",
+			label: "the volume"
+		}
+	],
+	answer: "moles",
+	explain: "Adding water never removes solute — n = C·V is conserved, which is exactly C₁V₁ = C₂V₂."
+}, {
+	id: "doubleV",
+	prompt: "Keep the same aliquot but DOUBLE the final volume V₂. The final concentration C₂…",
+	choices: [
+		{
+			value: "halves",
+			label: "halves"
+		},
+		{
+			value: "doubles",
+			label: "doubles"
+		},
+		{
+			value: "same",
+			label: "is unchanged"
+		}
+	],
+	answer: "halves",
+	explain: "C₂ = n/V₂ with n fixed — twice the volume means half the concentration."
+}];
+function DilutionLab({ stockConcentration = 2, aliquotVolume = .25, finalVolume = 1, maxMolarity = 4, hue = 200, title = "Dilution — the dots don’t leave", prompt = "Take an aliquot of stock, add water to the final volume. Same dots, bigger box → lower concentration.", height = 180, objectives }) {
+	const c1 = clamp(stockConcentration, .5, maxMolarity);
+	const [v1, setV1] = useState(clamp(aliquotVolume, .1, .5));
+	const [v2, setV2] = useState(clamp(finalVolume, .5, 1.5));
+	const n = c1 * v1;
+	const c2 = n / v2;
+	const dots = Math.round(n * DOTS_PER_MOL);
+	const challenge = useChallenge(DILUTION_CHALLENGE);
+	useCheckpoint({
+		solved: challenge.allCorrect,
+		activity: "dilution"
+	});
+	const figure = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "grid",
+			gridTemplateColumns: "1fr auto 1fr",
+			alignItems: "center",
+			gap: 8
+		},
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				style: {
+					borderRadius: 12,
+					overflow: "hidden",
+					background: "var(--stage-bg)",
+					border: "1px solid var(--stage-grid)"
+				},
+				children: [/* @__PURE__ */ jsx(SolutionField, {
+					dots,
+					fill: v1 / .5,
+					tint: c1 / maxMolarity,
+					hue,
+					height,
+					ariaLabel: `aliquot: ${n.toFixed(2)} moles, ${c1.toFixed(1)} molar`
+				}), /* @__PURE__ */ jsxs("p", {
+					style: {
+						textAlign: "center",
+						margin: "4px 0 6px",
+						fontSize: 12,
+						fontWeight: 700,
+						fontVariantNumeric: "tabular-nums"
+					},
+					children: [
+						"aliquot · C₁=",
+						c1.toFixed(1),
+						" · V₁=",
+						v1.toFixed(2),
+						" L"
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					fontSize: 22,
+					color: "var(--stage-muted)"
+				},
+				children: "→"
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				style: {
+					borderRadius: 12,
+					overflow: "hidden",
+					background: "var(--stage-bg)",
+					border: "1px solid var(--stage-grid)"
+				},
+				children: [/* @__PURE__ */ jsx(SolutionField, {
+					dots,
+					fill: v2 / 1.5,
+					tint: c2 / maxMolarity,
+					hue,
+					height,
+					ariaLabel: `diluted: ${n.toFixed(2)} moles, ${c2.toFixed(2)} molar`
+				}), /* @__PURE__ */ jsxs("p", {
+					style: {
+						textAlign: "center",
+						margin: "4px 0 6px",
+						fontSize: 12,
+						fontWeight: 700,
+						fontVariantNumeric: "tabular-nums"
+					},
+					children: [
+						"diluted · C₂=",
+						c2.toFixed(2),
+						" · V₂=",
+						v2.toFixed(2),
+						" L"
+					]
+				})]
+			})
+		]
+	}), /* @__PURE__ */ jsx(LiveRegion, { children: `${c1.toFixed(1)} molar times ${v1.toFixed(2)} litres gives ${n.toFixed(2)} moles, diluted to ${v2.toFixed(2)} litres is ${c2.toFixed(2)} molar.` })] });
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [/* @__PURE__ */ jsx(Field, {
+			label: "aliquot V₁ (L)",
+			value: v1.toFixed(2),
+			children: /* @__PURE__ */ jsx(Slider, {
+				value: v1,
+				min: .1,
+				max: .5,
+				step: .05,
+				onChange: setV1,
+				ariaLabel: "aliquot volume taken from stock"
+			})
+		}), /* @__PURE__ */ jsx(Field, {
+			label: "final V₂ (L)",
+			value: v2.toFixed(2),
+			children: /* @__PURE__ */ jsx(Slider, {
+				value: v2,
+				min: .5,
+				max: 1.5,
+				step: .05,
+				onChange: setV2,
+				ariaLabel: "final volume after adding water"
+			})
+		})] }),
+		footer: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(Callout, {
+			tone: "result",
+			children: [/* @__PURE__ */ jsx("b", {
+				style: { fontVariantNumeric: "tabular-nums" },
+				children: /* @__PURE__ */ jsx(Tex, { tex: `C_1 V_1 = C_2 V_2 = ${n.toFixed(2)}\\ \\text{mol}` })
+			}), " \xA0(the dots don’t leave)"]
+		}), /* @__PURE__ */ jsx(ChallengeCard, {
+			questions: DILUTION_CHALLENGE,
+			state: challenge,
+			title: "Predict"
+		})] }),
+		children: figure
+	});
+}
+
+//#endregion
+export { DilutionLab };

package/dist/chem/solution/field.d.mts

@@ -0,0 +1,30 @@
+import { ReactNode } from "react";
+
+//#region src/chem/solution/field.d.ts
+interface SolutionFieldProps {
+  /** Solute particle count (the amount). Capped internally for perf. */
+  dots: number;
+  /** Liquid's share of the box width, 0..1 (represents volume). */
+  fill: number;
+  /** Density tint 0..1 (e.g. molarity / maxMolarity) — deepens the colour. */
+  tint: number;
+  /** Solute hue in degrees (HSL) — encodes the species; default teal. */
+  hue?: number;
+  height?: number;
+  /** Drag a fixed-size probe to count dots in a sub-region. */
+  showProbe?: boolean;
+  animate?: boolean;
+  ariaLabel?: string;
+}
+declare function SolutionField({
+  dots,
+  fill,
+  tint,
+  hue,
+  height,
+  showProbe,
+  animate,
+  ariaLabel
+}: SolutionFieldProps): ReactNode;
+//#endregion
+export { SolutionField, SolutionFieldProps };

package/dist/chem/solution/field.mjs

@@ -0,0 +1,145 @@
+'use client';
+
+import { clamp } from "../../core/util.mjs";
+import { useFrameTick, useReducedMotionDeferred } from "../../kit/anim.mjs";
+import { useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CanvasLayer, useInView } from "@classytic/stage";
+
+//#region src/chem/solution/field.tsx
+/**
+* SolutionField — the SHARED "solute dots in a solution box" primitive (single
+* source of truth for the concentration family). Both SolutionBoxLab and
+* DilutionLab compose it, so the dot-field, density tint, Brownian jitter and the
+* draggable probe live in exactly ONE place.
+*
+* GENERIC on purpose: it takes a dot COUNT + a fill fraction (the liquid's share
+* of the box = volume) + a tint 0..1 — the chemistry (moles→dots, M→tint) is the
+* lab's job, not the field's. Dots hold fixed fractional positions so growing the
+* box spreads the SAME dots apart (dilution = spreading, never removing). SVG-free
+* CanvasLayer; deterministic seed (no Math.random at render) so SSR == client;
+* jitter + probe run client-side; honours prefers-reduced-motion.
+*/
+const MAXDOTS = 260;
+const PAD = .06;
+function SolutionField({ dots, fill, tint, hue = 178, height = 230, showProbe = false, animate = true, ariaLabel = "solution" }) {
+	const n = clamp(Math.round(dots), 0, MAXDOTS);
+	const seeds = useRef([]);
+	const probe = useRef({
+		x: .22,
+		y: .5
+	});
+	const [mounted, setMounted] = useState(false);
+	const reduce = useReducedMotionDeferred();
+	const { ref: viewRef, inView } = useInView();
+	useEffect(() => {
+		setMounted(true);
+	}, []);
+	if (seeds.current.length === 0) {
+		const pool = [];
+		for (let i = 0; i < MAXDOTS; i++) {
+			const fx = i * .61803398875 % 1;
+			const fy = (i * .38196601125 + .13) % 1;
+			const a = i * 2.39996 % (Math.PI * 2);
+			pool.push({
+				fx,
+				fy,
+				vx: Math.cos(a),
+				vy: Math.sin(a)
+			});
+		}
+		seeds.current = pool;
+	}
+	const repaint = useFrameTick(mounted && animate && !reduce && inView, (f) => {
+		const dt = Math.min(.05, f.dtMs / 1e3);
+		for (let i = 0; i < n; i++) {
+			const s = seeds.current[i];
+			s.fx = clamp(s.fx + s.vx * dt * .06, 0, 1);
+			s.fy = clamp(s.fy + s.vy * dt * .09, 0, 1);
+			if (s.fx <= 0 || s.fx >= 1) s.vx *= -1;
+			if (s.fy <= 0 || s.fy >= 1) s.vy *= -1;
+		}
+	});
+	const PROBE = .2;
+	let probeCount = 0;
+	const fillW = clamp(fill, .12, 1);
+	for (let i = 0; i < n; i++) {
+		const s = seeds.current[i];
+		const bx = PAD * fillW + s.fx * (fillW - 2 * PAD * fillW);
+		const by = PAD + s.fy * (1 - 2 * PAD);
+		if (Math.abs(bx - probe.current.x) < PROBE / 2 && Math.abs(by - probe.current.y) < PROBE / 2) probeCount++;
+	}
+	const draw = (ctx, c) => {
+		const [bx0, by0] = c.toPx(0, 1);
+		const [bx1, by1] = c.toPx(1, 0);
+		const W = bx1 - bx0, Hh = by1 - by0;
+		ctx.clearRect(bx0 - 4, by0 - 4, W + 8, Hh + 8);
+		const liqW = clamp(fill, .12, 1) * W;
+		ctx.fillStyle = `hsl(${hue} 70% 50% / ${(.1 + .55 * clamp(tint, 0, 1)).toFixed(3)})`;
+		ctx.fillRect(bx0, by0, liqW, Hh);
+		ctx.strokeStyle = getComputedStyle(document.documentElement).getPropertyValue("--stage-fg").trim() || "#333";
+		ctx.globalAlpha = .5;
+		ctx.lineWidth = 2;
+		ctx.strokeRect(bx0, by0, W, Hh);
+		ctx.globalAlpha = 1;
+		ctx.fillStyle = `hsl(${hue} 75% 38%)`;
+		const fw = clamp(fill, .12, 1);
+		for (let i = 0; i < n; i++) {
+			const s = seeds.current[i];
+			const px = bx0 + (PAD * fw + s.fx * (fw - 2 * PAD * fw)) * W;
+			const py = by0 + (PAD + s.fy * (1 - 2 * PAD)) * Hh;
+			ctx.beginPath();
+			ctx.arc(px, py, 3.2, 0, Math.PI * 2);
+			ctx.fill();
+		}
+		if (showProbe) {
+			ctx.strokeStyle = getComputedStyle(document.documentElement).getPropertyValue("--stage-accent").trim() || "#3b82f6";
+			ctx.lineWidth = 2;
+			ctx.strokeRect(bx0 + (probe.current.x - PROBE / 2) * W, by0 + (probe.current.y - PROBE / 2) * Hh, PROBE * W, PROBE * Hh);
+		}
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref: viewRef,
+		style: { position: "relative" },
+		children: [/* @__PURE__ */ jsx(CanvasLayer, {
+			view: {
+				xMin: 0,
+				xMax: 1,
+				yMin: 0,
+				yMax: 1
+			},
+			height,
+			draw,
+			onPointerMath: showProbe ? (m) => {
+				probe.current = {
+					x: clamp(m[0], PROBE / 2, 1 - PROBE / 2),
+					y: clamp(m[1], PROBE / 2, 1 - PROBE / 2)
+				};
+				repaint();
+			} : void 0,
+			ariaLabel
+		}), showProbe && /* @__PURE__ */ jsxs("span", {
+			style: {
+				position: "absolute",
+				top: 8,
+				right: 10,
+				fontSize: 12,
+				fontWeight: 700,
+				fontVariantNumeric: "tabular-nums",
+				background: "color-mix(in oklab, var(--stage-bg) 80%, transparent)",
+				border: "1px solid var(--stage-grid)",
+				borderRadius: 8,
+				padding: "2px 8px",
+				color: "var(--stage-accent)"
+			},
+			children: [
+				"probe: ",
+				probeCount,
+				" dots"
+			]
+		})]
+	});
+}
+
+//#endregion
+export { SolutionField };

package/dist/chem/solution/index.d.mts

@@ -0,0 +1,3 @@
+import { SolutionField, SolutionFieldProps } from "./field.mjs";
+import { SolutionBoxLab, SolutionBoxProps } from "./solution-box.mjs";
+import { DilutionLab, DilutionProps } from "./dilution.mjs";

package/dist/chem/solution/solution-box.d.mts

@@ -0,0 +1,28 @@
+import { ReactNode } from "react";
+
+//#region src/chem/solution/solution-box.d.ts
+interface SolutionBoxProps {
+  moles?: number;
+  volume?: number;
+  /** Tint scaling: the molarity that reads as fully saturated colour. */
+  maxMolarity?: number;
+  hue?: number;
+  showProbe?: boolean;
+  title?: string;
+  prompt?: string;
+  height?: number;
+  objectives?: string[];
+}
+declare function SolutionBoxLab({
+  moles,
+  volume,
+  maxMolarity,
+  hue,
+  showProbe,
+  title,
+  prompt,
+  height,
+  objectives
+}: SolutionBoxProps): ReactNode;
+//#endregion
+export { SolutionBoxLab, SolutionBoxProps };

package/dist/chem/solution/solution-box.mjs

@@ -0,0 +1,140 @@
+'use client';
+
+import { clamp } from "../../core/util.mjs";
+import { Slider } from "../../kit/controls.mjs";
+import { ControlBar, Field, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { ChallengeCard, useChallenge, useCheckpoint } from "../../kit/pedagogy.mjs";
+import { SolutionField } from "./field.mjs";
+import { useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/chem/solution/solution-box.tsx
+/**
+* SolutionBoxLab — molarity is a CROWD: particles per litre, seen.
+*
+* Solute shown as discrete dots in a transparent box. Add solute (more dots =
+* more moles, the numerator) or add water (the box widens so the SAME dots spread
+* apart, the denominator) — and M = n/V is read off as both a number AND the
+* colour intensity. A draggable probe counts dots in a fixed region, proving
+* molarity is a LOCAL density, not a whole-apparatus label. Composes the shared
+* SolutionField (single source of truth for the dot engine).
+*
+* The unit-bridging algebra (mol↔g via molar mass, mol↔particles via Nₐ) belongs
+* in a paired MathDerivation — this lab only makes density-vs-amount felt.
+*/
+const DOTS_PER_MOL = 200;
+/** Predict how M = n/V responds to changing the numerator vs the denominator — the core molarity misconception. */
+const SOLUTION_CHALLENGE = [{
+	id: "add-water",
+	prompt: "Add water (more volume, same solute). The molarity M = n/V…",
+	choices: [
+		{
+			value: "falls",
+			label: "falls"
+		},
+		{
+			value: "rises",
+			label: "rises"
+		},
+		{
+			value: "same",
+			label: "stays the same"
+		}
+	],
+	answer: "falls",
+	explain: "The same dots spread through a bigger box — n is fixed, V grows, so the density n/V drops."
+}, {
+	id: "add-solute",
+	prompt: "Add more solute at the same volume. The molarity…",
+	choices: [
+		{
+			value: "rises",
+			label: "rises"
+		},
+		{
+			value: "falls",
+			label: "falls"
+		},
+		{
+			value: "same",
+			label: "stays the same"
+		}
+	],
+	answer: "rises",
+	explain: "More dots in the same box — n grows, V is fixed, so n/V climbs."
+}];
+function SolutionBoxLab({ moles = .5, volume = .5, maxMolarity = 4, hue = 178, showProbe = true, title = "Molarity is a crowd — particles per litre", prompt = "Add solute (more dots) or add water (same dots, bigger box). M = n / V is the dot density.", height = 230, objectives }) {
+	const [n, setN] = useState(clamp(moles, .1, 1));
+	const [v, setV] = useState(clamp(volume, .2, 1));
+	const M = n / v;
+	const challenge = useChallenge(SOLUTION_CHALLENGE);
+	useCheckpoint({
+		solved: challenge.allCorrect,
+		activity: "solution-box"
+	});
+	const figure = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
+		style: {
+			borderRadius: 14,
+			overflow: "hidden",
+			background: "var(--stage-bg)",
+			border: "1px solid var(--stage-grid)"
+		},
+		children: /* @__PURE__ */ jsx(SolutionField, {
+			dots: Math.round(n * DOTS_PER_MOL),
+			fill: v,
+			tint: M / maxMolarity,
+			hue,
+			height,
+			showProbe,
+			ariaLabel: `solution: ${n.toFixed(1)} moles in ${v.toFixed(1)} litres, ${M.toFixed(2)} molar`
+		})
+	}), /* @__PURE__ */ jsx(LiveRegion, { children: `${n.toFixed(2)} moles in ${v.toFixed(2)} litres is ${M.toFixed(2)} molar.` })] });
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(Field, {
+				label: "solute (mol)",
+				value: `${n.toFixed(2)} mol`,
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: n,
+					min: .1,
+					max: 1,
+					step: .05,
+					onChange: setN,
+					ariaLabel: "moles of solute"
+				})
+			}),
+			/* @__PURE__ */ jsx(Field, {
+				label: "water → volume (L)",
+				value: `${v.toFixed(2)} L`,
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: v,
+					min: .2,
+					max: 1,
+					step: .05,
+					onChange: setV,
+					ariaLabel: "solution volume in litres"
+				})
+			}),
+			/* @__PURE__ */ jsx(Field, {
+				label: "M = n/V",
+				value: /* @__PURE__ */ jsxs("span", {
+					style: { color: "var(--stage-accent)" },
+					children: [M.toFixed(2), " mol·L⁻¹"]
+				}),
+				children: /* @__PURE__ */ jsx("span", {})
+			})
+		] }),
+		footer: /* @__PURE__ */ jsx(ChallengeCard, {
+			questions: SOLUTION_CHALLENGE,
+			state: challenge,
+			title: "Predict"
+		}),
+		children: figure
+	});
+}
+
+//#endregion
+export { SolutionBoxLab };

package/dist/chem/stoichiometry/index.d.mts

@@ -0,0 +1 @@
+import { StoichiometryLab, StoichiometryProps } from "./preset.mjs";

package/dist/chem/stoichiometry/preset.d.mts

@@ -0,0 +1,29 @@
+import { ReactNode } from "react";
+import { StoichSpecies } from "@classytic/stage/chem";
+
+//#region src/chem/stoichiometry/preset.d.ts
+interface Spec extends StoichSpecies {
+  color: string;
+}
+interface StoichiometryProps {
+  reaction?: 'water' | 'ammonia' | 'methane' | 'rust';
+  /** Override the reactant amounts (mol). */
+  amounts?: number[];
+  /** Author a custom reaction (overrides the preset). */
+  reactants?: Spec[];
+  products?: Spec[];
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+}
+declare function StoichiometryLab({
+  reaction,
+  amounts: amounts0,
+  reactants: customR,
+  products: customP,
+  title,
+  prompt,
+  objectives
+}?: StoichiometryProps): ReactNode;
+//#endregion
+export { StoichiometryLab, StoichiometryProps };