@classytic/labs 0.1.0

package/dist/kit/electronics.mjs

@@ -0,0 +1,357 @@
+'use client';
+
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/electronics.tsx
+const WIRE = "var(--stage-wire)";
+const LIVE = "var(--stage-live)";
+const METAL = "var(--stage-metal)";
+const BG = "var(--stage-bg)";
+const FG = "var(--stage-fg)";
+const CHARGE = "var(--stage-charge)";
+const SHEEN = "color-mix(in oklab, var(--stage-sheen) 45%, transparent)";
+/** The two leads + terminal nubs from each terminal to the body edge at ±bodyHalf. */
+function Leads({ cx, cy, half, bodyHalf, live }) {
+	const wire = live ? LIVE : WIRE;
+	return /* @__PURE__ */ jsxs("g", { children: [
+		/* @__PURE__ */ jsx("line", {
+			x1: cx - half,
+			y1: cy,
+			x2: cx - bodyHalf,
+			y2: cy,
+			stroke: wire,
+			strokeWidth: 2.5,
+			strokeLinecap: "round"
+		}),
+		/* @__PURE__ */ jsx("line", {
+			x1: cx + bodyHalf,
+			y1: cy,
+			x2: cx + half,
+			y2: cy,
+			stroke: wire,
+			strokeWidth: 2.5,
+			strokeLinecap: "round"
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx: cx - half,
+			cy,
+			r: 2.6,
+			fill: METAL
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx: cx + half,
+			cy,
+			r: 2.6,
+			fill: METAL
+		})
+	] });
+}
+/** Value/name label above a body of half-height `bodyH`. */
+function GlyphLabel({ cx, cy, bodyH, label }) {
+	if (!label) return null;
+	return /* @__PURE__ */ jsx("text", {
+		x: cx,
+		y: cy - bodyH - 7,
+		fill: FG,
+		fontSize: 11,
+		fontWeight: 600,
+		textAnchor: "middle",
+		style: { pointerEvents: "none" },
+		children: label
+	});
+}
+/**
+* RESISTOR — the IEC/CAIE rectangle (an open box interrupting the wire). The
+* exam-standard symbol; clean token fill + metal outline + a top-edge sheen.
+*/
+function ResistorGlyph({ cx, cy, half, live, label }) {
+	const bw = 21;
+	const bh = 10;
+	return /* @__PURE__ */ jsxs("g", { children: [
+		/* @__PURE__ */ jsx(Leads, {
+			cx,
+			cy,
+			half,
+			bodyHalf: bw,
+			live
+		}),
+		/* @__PURE__ */ jsx("rect", {
+			x: cx - bw,
+			y: cy - bh,
+			width: bw * 2,
+			height: bh * 2,
+			rx: 3,
+			fill: BG,
+			stroke: live ? LIVE : METAL,
+			strokeWidth: 2
+		}),
+		/* @__PURE__ */ jsx("line", {
+			x1: cx - bw * .7,
+			y1: cy - bh + 1.5,
+			x2: cx + bw * .7,
+			y2: cy - bh + 1.5,
+			stroke: SHEEN,
+			strokeWidth: 1.4,
+			strokeLinecap: "round"
+		}),
+		/* @__PURE__ */ jsx(GlyphLabel, {
+			cx,
+			cy,
+			bodyH: bh,
+			label
+		})
+	] });
+}
+/**
+* CELL / BATTERY — one long thin plate (+) and one short thick plate (−). Pass
+* `cells` > 1 to draw a battery (repeated plate pairs). EMF label above.
+*/
+function CellGlyph({ cx, cy, half, live, label, cells = 1 }) {
+	const n = Math.max(1, Math.round(cells));
+	const gap = 7;
+	const span = n * gap * 2 - gap;
+	const bodyHalf = span / 2 + 2;
+	const longH = 13;
+	const shortH = 7;
+	const plates = [];
+	let x = cx - span / 2;
+	for (let i = 0; i < n; i++) {
+		plates.push(/* @__PURE__ */ jsx("line", {
+			x1: x,
+			y1: cy - longH,
+			x2: x,
+			y2: cy + longH,
+			stroke: METAL,
+			strokeWidth: 2,
+			strokeLinecap: "round"
+		}, `l${i}`));
+		x += gap;
+		plates.push(/* @__PURE__ */ jsx("line", {
+			x1: x,
+			y1: cy - shortH,
+			x2: x,
+			y2: cy + shortH,
+			stroke: METAL,
+			strokeWidth: 4.5,
+			strokeLinecap: "round"
+		}, `s${i}`));
+		x += gap;
+	}
+	return /* @__PURE__ */ jsxs("g", { children: [
+		/* @__PURE__ */ jsx(Leads, {
+			cx,
+			cy,
+			half,
+			bodyHalf,
+			live
+		}),
+		plates,
+		/* @__PURE__ */ jsx(GlyphLabel, {
+			cx,
+			cy,
+			bodyH: longH,
+			label
+		})
+	] });
+}
+/**
+* CAPACITOR — two parallel plates with a visible STORED-CHARGE field between them
+* and an optional LEAK. This is the centerpiece glyph: `charge` (0..1) sets how
+* many field lines bridge the plates and their intensity, so a charging cap fills
+* and a leaking cap visibly empties; `leaking` + `leakPhase` drip charge off the
+* lower plate (the "why capacitors don't hold charge forever" picture). All motion
+* is data — the lab's RC integrator lowers `charge` and advances `leakPhase`.
+*/
+function CapacitorGlyph({ cx, cy, half, live, label, charge = 0, leaking, leakPhase = 0, polarised }) {
+	const q = Math.max(0, Math.min(1, charge));
+	const plateGap = 14;
+	const plateH = 18;
+	const bodyHalf = 10;
+	const lx = cx - plateGap / 2;
+	const rx = cx + plateGap / 2;
+	const lines = q > .02 ? Math.round(1 + q * 2) : 0;
+	const field = [];
+	for (let i = 0; i < lines; i++) {
+		const fy = cy - plateH * .5 + plateH * (lines === 1 ? .5 : i / (lines - 1));
+		field.push(/* @__PURE__ */ jsx("line", {
+			x1: lx + 2,
+			y1: fy,
+			x2: rx - 2,
+			y2: fy,
+			stroke: CHARGE,
+			strokeWidth: 1,
+			strokeLinecap: "round",
+			opacity: .12 + .3 * q
+		}, `f${i}`));
+	}
+	const drips = [];
+	if (leaking && q > .02) for (let d = 0; d < 2; d++) {
+		const ph = (leakPhase + d * .5) % 1;
+		const dy = cy + plateH + ph * 16;
+		drips.push(/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy: dy,
+			r: 2.2,
+			fill: CHARGE,
+			opacity: (1 - ph) * (.3 + .5 * q)
+		}, `d${d}`));
+	}
+	return /* @__PURE__ */ jsxs("g", { children: [
+		/* @__PURE__ */ jsx(Leads, {
+			cx,
+			cy,
+			half,
+			bodyHalf,
+			live
+		}),
+		field,
+		/* @__PURE__ */ jsx("line", {
+			x1: lx,
+			y1: cy - plateH,
+			x2: lx,
+			y2: cy + plateH,
+			stroke: METAL,
+			strokeWidth: 3.5,
+			strokeLinecap: "round"
+		}),
+		polarised ? /* @__PURE__ */ jsx("path", {
+			d: `M ${rx} ${cy - plateH} Q ${rx + 5} ${cy} ${rx} ${cy + plateH}`,
+			fill: "none",
+			stroke: METAL,
+			strokeWidth: 3.5,
+			strokeLinecap: "round"
+		}) : /* @__PURE__ */ jsx("line", {
+			x1: rx,
+			y1: cy - plateH,
+			x2: rx,
+			y2: cy + plateH,
+			stroke: METAL,
+			strokeWidth: 3.5,
+			strokeLinecap: "round"
+		}),
+		polarised && /* @__PURE__ */ jsx("text", {
+			x: lx - 4,
+			y: cy - plateH + 2,
+			fill: FG,
+			fontSize: 11,
+			fontWeight: 700,
+			textAnchor: "end",
+			style: { pointerEvents: "none" },
+			children: "+"
+		}),
+		drips,
+		/* @__PURE__ */ jsx(GlyphLabel, {
+			cx,
+			cy,
+			bodyH: plateH,
+			label
+		})
+	] });
+}
+function LampGlyph({ cx, cy, brightness, r = 30 }) {
+	const b = Math.max(0, Math.min(1, brightness));
+	const hot = b > .04;
+	const filament = `color-mix(in oklab, var(--stage-metal) ${Math.round((1 - b) * 100)}%, var(--stage-warn))`;
+	return /* @__PURE__ */ jsxs("g", { children: [
+		hot && /* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r: r + 6 + b * 26,
+			fill: "url(#stage-grad-thermal)",
+			opacity: .18 + .7 * b,
+			filter: b > .55 ? "url(#stage-bloom)" : "url(#stage-glow)",
+			style: { pointerEvents: "none" }
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r,
+			fill: "var(--stage-bg)",
+			stroke: hot ? "var(--stage-warn)" : "var(--stage-metal)",
+			strokeWidth: 2.5
+		}),
+		/* @__PURE__ */ jsx("path", {
+			d: `M ${cx - 16} ${cy + 6} q 4 -16 8 0 q 4 16 8 0 q 4 -16 8 0 q 4 16 8 0`,
+			fill: "none",
+			stroke: filament,
+			strokeWidth: hot ? 3 : 2.2,
+			strokeLinecap: "round",
+			filter: b > .55 ? "url(#stage-bloom)" : void 0
+		}),
+		b > .6 && /* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r: 6 + (b - .6) * 14,
+			fill: "white",
+			opacity: (b - .6) * 1.6,
+			filter: "url(#stage-bloom)",
+			style: { pointerEvents: "none" }
+		}),
+		/* @__PURE__ */ jsx("rect", {
+			x: cx - 9,
+			y: cy + r - 2,
+			width: 18,
+			height: 10,
+			rx: 2,
+			fill: "var(--stage-metal)"
+		})
+	] });
+}
+/** An AC (~) or DC (=) source; a halo behind it tracks output magnitude `level` (-1..1). */
+function AcDcSourceGlyph({ cx, cy, mode, level, r = 30 }) {
+	const live = Math.abs(Math.max(-1, Math.min(1, level)));
+	return /* @__PURE__ */ jsxs("g", { children: [
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r: r + 10,
+			fill: "url(#stage-grad-halo)",
+			opacity: .25 + .6 * live,
+			style: { pointerEvents: "none" }
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r,
+			fill: "var(--stage-bg)",
+			stroke: "var(--stage-accent)",
+			strokeWidth: 2.5
+		}),
+		mode === "ac" ? /* @__PURE__ */ jsx("path", {
+			d: `M ${cx - 16} ${cy} q 8 -14 16 0 q 8 14 16 0`,
+			fill: "none",
+			stroke: "var(--stage-accent)",
+			strokeWidth: 3,
+			strokeLinecap: "round"
+		}) : /* @__PURE__ */ jsxs("g", {
+			stroke: "var(--stage-accent)",
+			strokeLinecap: "round",
+			children: [/* @__PURE__ */ jsx("line", {
+				x1: cx - 15,
+				y1: cy - 6,
+				x2: cx + 15,
+				y2: cy - 6,
+				strokeWidth: 3.5
+			}), /* @__PURE__ */ jsx("line", {
+				x1: cx - 15,
+				y1: cy + 6,
+				x2: cx + 15,
+				y2: cy + 6,
+				strokeWidth: 2,
+				strokeDasharray: "4 4"
+			})]
+		}),
+		/* @__PURE__ */ jsx("text", {
+			x: cx,
+			y: cy + r + 18,
+			textAnchor: "middle",
+			fontSize: 13,
+			fontWeight: 700,
+			fill: "var(--stage-accent)",
+			children: mode.toUpperCase()
+		})
+	] });
+}
+
+//#endregion
+export { AcDcSourceGlyph, CapacitorGlyph, CellGlyph, LampGlyph, ResistorGlyph };

package/dist/kit/expr-analysis.d.mts

@@ -0,0 +1,37 @@
+import { Node } from "@classytic/stage";
+
+//#region src/kit/expr-analysis.d.ts
+type Fn1 = (x: number) => number;
+/** A straight line y = m·x + c, with the point it was taken at and an evaluator. */
+interface Line {
+  m: number;
+  c: number;
+  at: {
+    x: number;
+    y: number;
+  };
+  f: Fn1;
+}
+/** Real roots of f on [a,b] via a sign-change scan refined by bisection. */
+declare function roots(f: Fn1, a: number, b: number, opts?: {
+  steps?: number;
+  tol?: number;
+}): number[];
+/** Points where f and g meet on [a,b]. */
+declare function intersections(f: Fn1, g: Fn1, a: number, b: number, opts?: {
+  steps?: number;
+  tol?: number;
+}): {
+  x: number;
+  y: number;
+}[];
+/** Exact tangent line to `ast` at x = x0 (params baked in via `scope`). */
+declare function tangentAt(ast: Node, x0: number, varName?: string, params?: Record<string, number>): Line | null;
+/** Normal line to `ast` at x = x0 (⟂ the tangent). Null if the tangent is horizontal. */
+declare function normalAt(ast: Node, x0: number, varName?: string, params?: Record<string, number>): Line | null;
+/** Composite-Simpson definite integral ∫_a^b f dx. */
+declare function integrate(f: Fn1, a: number, b: number, n?: number): number;
+/** Unsigned area between f and g over [a,b]. */
+declare function areaBetween(f: Fn1, g: Fn1, a: number, b: number, n?: number): number;
+//#endregion
+export { Fn1, Line, areaBetween, integrate, intersections, normalAt, roots, tangentAt };

package/dist/kit/expr-analysis.mjs

@@ -0,0 +1,111 @@
+import { differentiate, evaluate } from "@classytic/stage";
+
+//#region src/kit/expr-analysis.ts
+/**
+* expr-analysis — the numeric/symbolic "solving" layer of the interactive-problem
+* engine, built on @classytic/stage's expr engine. Pure functions (no React) so a
+* creator's authored config can derive the quantities A-level questions ask for —
+* roots, intersections, tangents/normals, areas — without anyone hand-coding a lab.
+*
+* Everything works on a compiled scalar `Fn1 = (x) => number` (params already baked
+* into the closure) plus, for exact tangents, the parsed `Node` AST.
+*/
+function pushUnique(out, x, tol) {
+	if (!out.some((p) => Math.abs(p - x) <= tol)) out.push(x);
+}
+/** Real roots of f on [a,b] via a sign-change scan refined by bisection. */
+function roots(f, a, b, opts = {}) {
+	const steps = opts.steps ?? 1e3;
+	const tol = opts.tol ?? 1e-9;
+	const grid = (b - a) / steps;
+	const out = [];
+	let xPrev = a;
+	let fPrev = f(a);
+	for (let i = 1; i <= steps; i++) {
+		const x = a + grid * i;
+		const fx = f(x);
+		if (Number.isFinite(fPrev) && Number.isFinite(fx)) {
+			if (fPrev === 0) pushUnique(out, xPrev, grid);
+			else if (fPrev * fx < 0) {
+				let lo = xPrev;
+				let hi = x;
+				let flo = fPrev;
+				for (let k = 0; k < 80 && hi - lo > tol; k++) {
+					const mid = (lo + hi) / 2;
+					const fm = f(mid);
+					if (!Number.isFinite(fm)) break;
+					if (flo * fm <= 0) hi = mid;
+					else {
+						lo = mid;
+						flo = fm;
+					}
+				}
+				pushUnique(out, (lo + hi) / 2, grid);
+			}
+		}
+		xPrev = x;
+		fPrev = fx;
+	}
+	return out;
+}
+/** Points where f and g meet on [a,b]. */
+function intersections(f, g, a, b, opts) {
+	return roots((x) => f(x) - g(x), a, b, opts).map((x) => ({
+		x,
+		y: f(x)
+	}));
+}
+/** Exact tangent line to `ast` at x = x0 (params baked in via `scope`). */
+function tangentAt(ast, x0, varName = "x", params = {}) {
+	const d = differentiate(ast, varName);
+	if (!d) return null;
+	const m = evaluate(d, {
+		...params,
+		[varName]: x0
+	});
+	const y0 = evaluate(ast, {
+		...params,
+		[varName]: x0
+	});
+	if (!Number.isFinite(m) || !Number.isFinite(y0)) return null;
+	const c = y0 - m * x0;
+	return {
+		m,
+		c,
+		at: {
+			x: x0,
+			y: y0
+		},
+		f: (x) => m * x + c
+	};
+}
+/** Normal line to `ast` at x = x0 (⟂ the tangent). Null if the tangent is horizontal. */
+function normalAt(ast, x0, varName = "x", params = {}) {
+	const t = tangentAt(ast, x0, varName, params);
+	if (!t || t.m === 0) return null;
+	const m = -1 / t.m;
+	const c = t.at.y - m * t.at.x;
+	return {
+		m,
+		c,
+		at: t.at,
+		f: (x) => m * x + c
+	};
+}
+/** Composite-Simpson definite integral ∫_a^b f dx. */
+function integrate(f, a, b, n = 1e3) {
+	if (a === b) return 0;
+	let N = Math.max(2, Math.round(n));
+	if (N % 2) N++;
+	const h = (b - a) / N;
+	let s = f(a) + f(b);
+	for (let i = 1; i < N; i++) s += (i % 2 ? 4 : 2) * f(a + i * h);
+	return h / 3 * s;
+}
+/** Unsigned area between f and g over [a,b]. */
+function areaBetween(f, g, a, b, n = 1e3) {
+	return Math.abs(integrate((x) => f(x) - g(x), a, b, n));
+}
+
+//#endregion
+export { areaBetween, integrate, intersections, normalAt, roots, tangentAt };

package/dist/kit/frame.d.mts

@@ -0,0 +1,70 @@
+import { ReactNode, Ref } from "react";
+
+//#region src/kit/frame.d.ts
+/** Per-control creator overrides: two name-lists, ergonomic for authors + agents. */
+interface ControlConfig {
+  /** Control names to remove entirely (learner can't see or change them). */
+  hide?: string[];
+  /** Control names to show read-only (frozen at the creator's initial value). */
+  lock?: string[];
+}
+interface LabFrameProps {
+  title?: string;
+  prompt?: string;
+  /** Collapsed "goals" disclosure (the old upfront Objectives wall, tamed). */
+  objectives?: string[];
+  /** The dominant visual. */
+  children: ReactNode;
+  /** Optional narrow side column (readouts, a guess, a result callout). */
+  aside?: ReactNode;
+  /** The single controls bar — pass <ControlBar>…</ControlBar>. */
+  controls?: ReactNode;
+  /** Quiet footer: feedback / hints / reveal / a note. */
+  footer?: ReactNode;
+  /** Ref on the outer container — e.g. for useInView() to pause a sim off-screen. */
+  rootRef?: Ref<HTMLDivElement>;
+  /** Creator's per-control hide/lock policy — flows to every Field/Control below. */
+  controlConfig?: ControlConfig;
+}
+declare function LabFrame({
+  title,
+  prompt,
+  objectives,
+  children,
+  aside,
+  controls,
+  footer,
+  rootRef,
+  controlConfig
+}: LabFrameProps): ReactNode;
+/** The single controls bar. Put `Field`s (or any control) inside. */
+declare function ControlBar({
+  children
+}: {
+  children: ReactNode;
+}): ReactNode;
+/**
+ * A labelled control: small-caps label + (control + value) on one row.
+ * Participates in creator `controlConfig` via `name ?? label`.
+ */
+declare function Field({
+  label,
+  name,
+  value,
+  children
+}: {
+  label: string;
+  name?: string;
+  value?: ReactNode;
+  children: ReactNode;
+}): ReactNode;
+/** A highlighted readout box. `tone="result"` for the headline answer. */
+declare function Callout({
+  tone,
+  children
+}: {
+  tone?: 'info' | 'result';
+  children: ReactNode;
+}): ReactNode;
+//#endregion
+export { Callout, ControlBar, ControlConfig, Field, LabFrame };