@classytic/labs 0.1.0

package/dist/circuits/circuit/preset.mjs

@@ -0,0 +1,235 @@
+'use client';
+
+import { Chip, LabStyles, Slider, StatusPill } from "../../kit/controls.mjs";
+import { Callout, ControlBar, Field, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { CIRCUIT_NETWORK_ASSET } from "./asset.mjs";
+import { useMemo } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Scene, controlsFromScene, isAssetGeom, registerAsset, resolve, useControlSurface, useEditor } from "@classytic/stage";
+
+//#region src/circuits/circuit/preset.tsx
+/**
+* Circuit network — a SceneDoc FACTORY on @classytic/stage. A creator declares a
+* battery + parallel BRANCHES (each a series chain of resistor/bulb/switch); the
+* learner closes switches and tunes the battery to hit a goal (light a bulb /
+* reach a target current / light them all). EMF + each switch are FREE scalars
+* driven through the editor command stack, so a voice/agent ("close switch 1",
+* "set battery to 9") drives the same path. The stage-based successor to the
+* legacy canvas CircuitBuilder.
+*/
+registerAsset("circuit-network", CIRCUIT_NETWORK_ASSET);
+const TYPE_CODE = {
+	resistor: 1,
+	bulb: 2,
+	switch: 3
+};
+const DEFAULT_BRANCHES = [[{
+	type: "switch",
+	closed: false
+}, {
+	type: "bulb",
+	ohms: 6
+}]];
+function flatten(branches) {
+	const comps = [];
+	const switches = [];
+	branches.forEach((chain, b) => chain.forEach((c, p) => {
+		comps.push({
+			c,
+			b,
+			p
+		});
+		if (c.type === "switch") switches.push({
+			id: `sw${switches.length}`,
+			label: c.label ?? `switch ${switches.length + 1}`
+		});
+	}));
+	return {
+		comps,
+		switches
+	};
+}
+function circuitDoc({ emf = 6, emfRange = [
+	1,
+	12,
+	1
+], internalR = 0, branches = DEFAULT_BRANCHES, goal = { kind: "lightBulb" } }) {
+	const { comps, switches } = flatten(branches);
+	const nBranch = branches.length;
+	const [emfMin, emfMax, emfStep] = emfRange;
+	const elements = [{
+		id: "emf",
+		kind: "scalar",
+		label: "battery",
+		a11y: { label: "battery voltage" },
+		free: {
+			value: emf,
+			min: emfMin,
+			max: emfMax,
+			step: emfStep
+		}
+	}];
+	switches.forEach((s, j) => elements.push({
+		id: s.id,
+		kind: "scalar",
+		a11y: { label: s.label },
+		free: {
+			value: branches.flat().filter((c) => c.type === "switch")[j].closed ? 1 : 0,
+			min: 0,
+			max: 1,
+			step: 1
+		}
+	}));
+	const params = {
+		nComp: comps.length,
+		nBranch,
+		internalR,
+		emf,
+		goalType: goal.kind === "lightBulb" ? 0 : goal.kind === "targetCurrent" ? 1 : 2,
+		goalComp: goal.comp ?? -1,
+		goalVal: goal.value ?? (goal.kind === "targetCurrent" ? 1 : .1),
+		goalTol: goal.tol ?? .05
+	};
+	const bind = { emf: { ref: "emf" } };
+	let swIdx = 0;
+	comps.forEach(({ c, b, p }, i) => {
+		params[`t${i}`] = TYPE_CODE[c.type];
+		params[`o${i}`] = c.type === "switch" ? 0 : c.ohms;
+		params[`b${i}`] = b;
+		params[`p${i}`] = p;
+		if (c.type === "switch") {
+			params[`sw${i}`] = swIdx;
+			bind[`k${swIdx}`] = { ref: `sw${swIdx}` };
+			swIdx++;
+		} else params[`sw${i}`] = -1;
+	});
+	elements.push({
+		id: "circuit",
+		kind: "asset",
+		def: {
+			op: "asset",
+			asset: "circuit-network",
+			params,
+			bind
+		}
+	});
+	const vy = ((nBranch - 1) * 1.5 + 2.2) / 2 + 1;
+	return {
+		schemaVersion: 2,
+		type: "stage-scene",
+		view: {
+			xMin: -4.6,
+			xMax: 4.6,
+			yMin: -vy,
+			yMax: vy
+		},
+		elements,
+		bindings: []
+	};
+}
+function CircuitNetworkLab(props) {
+	const { branches = DEFAULT_BRANCHES, emfRange = [
+		1,
+		12,
+		1
+	], controlId, height = 360, prompt = "Close the switch and power the circuit." } = props;
+	const { editor, doc } = useEditor(useMemo(() => circuitDoc(props), [JSON.stringify(props)]));
+	const resolved = resolve(doc);
+	const { switches } = useMemo(() => flatten(branches), [branches]);
+	const geom = resolved.values.get("circuit");
+	const meta = isAssetGeom(geom) ? geom.meta : {
+		solved: false,
+		Itotal: 0,
+		emf: 0
+	};
+	const emf = Number(resolved.values.get("emf") ?? 0);
+	const [emfMin, emfMax, emfStep] = emfRange;
+	useControlSurface(controlId, useMemo(() => controlsFromScene(editor, [{
+		id: "emf",
+		name: "battery",
+		min: emfMin,
+		max: emfMax,
+		step: emfStep
+	}]), [
+		editor,
+		emfMin,
+		emfMax,
+		emfStep
+	]));
+	const setEmf = (v) => {
+		editor.dispatch({
+			op: "mutate",
+			id: "emf",
+			patch: { free: { value: v } }
+		});
+	};
+	const toggle = (id) => {
+		const cur = Number(resolved.values.get(id) ?? 0);
+		editor.dispatch({
+			op: "mutate",
+			id,
+			patch: { free: { value: cur >= .5 ? 0 : 1 } }
+		});
+	};
+	useCheckpoint({
+		solved: meta.solved,
+		activity: "circuit-network"
+	});
+	const figure = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsx(LabStyles, {}),
+		/* @__PURE__ */ jsx(Scene, {
+			doc,
+			interactive: false,
+			showGrid: false,
+			showAxes: false,
+			height,
+			ariaLabel: prompt
+		}),
+		/* @__PURE__ */ jsx(LiveRegion, { children: meta.solved ? "Circuit powered, goal reached." : `Current ${(meta.Itotal * 1e3).toFixed(0)} milliamps.` })
+	] });
+	const controlsUi = /* @__PURE__ */ jsxs(ControlBar, { children: [switches.map((s) => {
+		const closed = Number(resolved.values.get(s.id) ?? 0) >= .5;
+		return /* @__PURE__ */ jsxs(Chip, {
+			selected: closed,
+			onClick: () => toggle(s.id),
+			children: [
+				s.label,
+				": ",
+				closed ? "closed" : "open"
+			]
+		}, s.id);
+	}), /* @__PURE__ */ jsx(Field, {
+		label: "🔋 battery",
+		value: `${emf} V`,
+		children: /* @__PURE__ */ jsx(Slider, {
+			value: emf,
+			min: emfMin,
+			max: emfMax,
+			step: emfStep,
+			onChange: setEmf,
+			ariaLabel: "battery voltage",
+			style: { width: 120 }
+		})
+	})] });
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title: "Power the circuit",
+		prompt,
+		aside: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(StatusPill, {
+			ok: meta.solved,
+			children: meta.solved ? "✓ Powered!" : "Not yet"
+		}), /* @__PURE__ */ jsxs(Callout, {
+			tone: "result",
+			children: [
+				"I ≈ ",
+				(meta.Itotal * 1e3).toFixed(0),
+				" mA"
+			]
+		})] }),
+		controls: controlsUi,
+		children: figure
+	});
+}
+
+//#endregion
+export { CircuitNetworkLab, circuitDoc };

package/dist/circuits/circuit-builder.d.mts

@@ -0,0 +1,30 @@
+import { ReactNode } from "react";
+
+//#region src/circuits/circuit-builder.d.ts
+type CircuitComponent = {
+  type: 'resistor';
+  ohms: number;
+  label?: string;
+} | {
+  type: 'bulb';
+  ohms: number;
+  label?: string;
+} | {
+  type: 'switch';
+  closed?: boolean;
+  label?: string;
+};
+interface CircuitBuilderProps {
+  battery?: number | string;
+  components?: CircuitComponent[];
+  title?: string;
+  height?: number;
+}
+declare function CircuitBuilder({
+  battery,
+  components,
+  title,
+  height
+}?: CircuitBuilderProps): ReactNode;
+//#endregion
+export { CircuitBuilder, CircuitBuilderProps, CircuitComponent };

package/dist/circuits/circuit-builder.mjs

@@ -0,0 +1,412 @@
+'use client';
+
+import { clamp, num } from "../core/util.mjs";
+import { Chip, Slider } from "../kit/controls.mjs";
+import { Callout, ControlBar, Field, LabFrame } from "../kit/frame.mjs";
+import { ResistorBox } from "../kit/diagram.mjs";
+import { useEffect, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Circle, Dot, Label, Polyline, Segment, Stage, useFrameLoop, useInView } from "@classytic/stage";
+
+//#region src/circuits/circuit-builder.tsx
+/**
+* CircuitBuilder — a circuit you BUILD and PLAY with, not a walkthrough.
+*
+* A creator declares the components in a series loop (battery + any mix of
+* resistors, bulbs, switches); the learner flips switches, tunes the battery, and
+* watches conventional current flow around the loop while bulbs glow in proportion
+* to the power through them. Open any switch → the loop breaks, current stops, the
+* bulb goes dark.
+*
+* Now on the @classytic/stage engine (SVG): the schematic + flowing-current dots
+* are primitives (accessible, themed); switches toggle via real buttons (keyboard-
+* operable) instead of canvas hit-testing.
+*
+* (Single series loop — the canonical "flashlight" circuit. Parallel topologies
+* are a future extension of the same model.)
+*/
+const DEFAULT = [{
+	type: "switch",
+	closed: false,
+	label: "switch"
+}, {
+	type: "bulb",
+	ohms: 12,
+	label: "bulb"
+}];
+const VIEW = {
+	xMin: 0,
+	xMax: 100,
+	yMin: 0,
+	yMax: 60
+};
+const L = 12, R = 92, TOP = 46, BOT = 12;
+/** Position along the rectangular loop perimeter at fraction u∈[0,1). */
+function onPerimeter(u) {
+	const pts = [
+		{
+			x: L,
+			y: TOP
+		},
+		{
+			x: R,
+			y: TOP
+		},
+		{
+			x: R,
+			y: BOT
+		},
+		{
+			x: L,
+			y: BOT
+		},
+		{
+			x: L,
+			y: TOP
+		}
+	];
+	const segLen = (p, q) => Math.hypot(q.x - p.x, q.y - p.y);
+	let total = 0;
+	for (let s = 0; s < 4; s++) total += segLen(pts[s], pts[s + 1]);
+	let d = u * total;
+	for (let s = 0; s < 4; s++) {
+		const p = pts[s], q = pts[s + 1], ln = segLen(p, q);
+		if (d <= ln) {
+			const k = d / ln;
+			return {
+				x: p.x + (q.x - p.x) * k,
+				y: p.y + (q.y - p.y) * k
+			};
+		}
+		d -= ln;
+	}
+	return pts[0];
+}
+function CircuitBuilder({ battery, components, title = "Build a circuit", height = 320 } = {}) {
+	const comps = components && components.length ? components : DEFAULT;
+	const [emf, setEmf] = useState(clamp(num(battery, 6), 1, 24));
+	const [closed, setClosed] = useState(() => Object.fromEntries(comps.map((c, i) => [i, c.type === "switch" ? c.closed !== false : true])));
+	const [t, setT] = useState(0);
+	const { ref: viewRef, inView } = useInView();
+	useEffect(() => {
+		setEmf(clamp(num(battery, 6), 1, 24));
+	}, [battery]);
+	useEffect(() => {
+		setClosed(Object.fromEntries(comps.map((c, i) => [i, c.type === "switch" ? c.closed !== false : true])));
+	}, [comps.map((c) => c.type + ("ohms" in c && c.ohms || "")).join("|")]);
+	const allClosed = comps.every((c, i) => c.type !== "switch" || closed[i]);
+	const totalR = comps.reduce((s, c) => s + ("ohms" in c ? c.ohms : 0), 0);
+	const current = allClosed ? emf / Math.max(totalR, .5) : 0;
+	useFrameLoop((f) => setT((v) => v + f.dtMs / 1e3), { running: current > 1e-4 && inView });
+	const n = comps.length;
+	const segW = (R - L) / n;
+	const cyMid = 58 / 2;
+	const speed = clamp(current * .18, .03, .5);
+	const N_DOTS = 28;
+	const switches = comps.map((c, i) => ({
+		c,
+		i
+	})).filter((x) => x.c.type === "switch");
+	const figure = /* @__PURE__ */ jsx("div", {
+		ref: viewRef,
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view: VIEW,
+			height,
+			preserveAspect: false,
+			ariaLabel: `Series circuit, ${emf}V battery, ${(current * 1e3).toFixed(0)} mA${allClosed ? "" : " — open, no current"}`,
+			children: [
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: L,
+						y: BOT
+					},
+					to: {
+						x: R,
+						y: BOT
+					},
+					color: "var(--stage-fg)",
+					opacity: .5,
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: R,
+						y: BOT
+					},
+					to: {
+						x: R,
+						y: TOP
+					},
+					color: "var(--stage-fg)",
+					opacity: .5,
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: L,
+						y: BOT
+					},
+					to: {
+						x: L,
+						y: cyMid - 6
+					},
+					color: "var(--stage-fg)",
+					opacity: .5,
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: L,
+						y: 35
+					},
+					to: {
+						x: L,
+						y: TOP
+					},
+					color: "var(--stage-fg)",
+					opacity: .5,
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: L - 5,
+						y: 35
+					},
+					to: {
+						x: 17,
+						y: 35
+					},
+					color: "var(--stage-accent-2)",
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: L - 3,
+						y: cyMid - 6
+					},
+					to: {
+						x: 15,
+						y: cyMid - 6
+					},
+					color: "var(--stage-accent-2)",
+					weight: 2.5
+				}),
+				/* @__PURE__ */ jsx(Label, {
+					x: 20,
+					y: cyMid,
+					text: `${emf.toFixed(0)} V`,
+					color: "var(--stage-accent-2)",
+					anchor: "start",
+					size: 12
+				}),
+				comps.map((c, i) => {
+					const cx = L + (i + .5) * segW;
+					const half = Math.min(segW * .28, 10);
+					const leftX = i === 0 ? L : L + i * segW;
+					const rightX = i === n - 1 ? R : L + (i + 1) * segW;
+					const label = c.label ?? c.type;
+					const wires = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Segment, {
+						from: {
+							x: leftX,
+							y: TOP
+						},
+						to: {
+							x: cx - half,
+							y: TOP
+						},
+						color: "var(--stage-fg)",
+						opacity: .5,
+						weight: 2.5
+					}), /* @__PURE__ */ jsx(Segment, {
+						from: {
+							x: cx + half,
+							y: TOP
+						},
+						to: {
+							x: rightX,
+							y: TOP
+						},
+						color: "var(--stage-fg)",
+						opacity: .5,
+						weight: 2.5
+					})] });
+					if (c.type === "resistor") return /* @__PURE__ */ jsxs("g", { children: [wires, /* @__PURE__ */ jsx(ResistorBox, {
+						center: {
+							x: cx,
+							y: TOP
+						},
+						w: 2 * half,
+						h: 7,
+						color: "var(--stage-accent)",
+						label: `${label} ${c.ohms}Ω`
+					})] }, i);
+					if (c.type === "bulb") {
+						const bright = clamp(current * 1.2, 0, 1) * (c.ohms / Math.max(totalR, 1));
+						const lit = bright > .02;
+						const rad = half * .95;
+						return /* @__PURE__ */ jsxs("g", { children: [
+							wires,
+							lit && /* @__PURE__ */ jsx(Circle, {
+								center: {
+									x: cx,
+									y: TOP
+								},
+								r: rad * 2,
+								color: "none",
+								fill: "var(--stage-warn)",
+								fillOpacity: .5 * bright,
+								weight: 0
+							}),
+							/* @__PURE__ */ jsx(Circle, {
+								center: {
+									x: cx,
+									y: TOP
+								},
+								r: rad,
+								color: lit ? "var(--stage-warn)" : "var(--stage-fg)",
+								fill: lit ? "var(--stage-warn)" : "var(--stage-bg)",
+								fillOpacity: lit ? .25 + .5 * bright : 1,
+								weight: 2
+							}),
+							/* @__PURE__ */ jsx(Polyline, {
+								points: [
+									{
+										x: cx - rad * .5,
+										y: TOP
+									},
+									{
+										x: cx - rad * .15,
+										y: TOP + rad * .4
+									},
+									{
+										x: cx + rad * .15,
+										y: TOP - rad * .4
+									},
+									{
+										x: cx + rad * .5,
+										y: TOP
+									}
+								],
+								color: lit ? "var(--stage-warn)" : "var(--stage-fg)",
+								weight: 1.5
+							}),
+							/* @__PURE__ */ jsx(Label, {
+								x: cx,
+								y: TOP,
+								text: label,
+								color: "var(--stage-fg)",
+								size: 11,
+								dy: -16
+							})
+						] }, i);
+					}
+					const open = !closed[i];
+					return /* @__PURE__ */ jsxs("g", { children: [
+						wires,
+						/* @__PURE__ */ jsx(Dot, {
+							x: cx - half,
+							y: TOP,
+							r: 3.5,
+							color: "var(--stage-good)"
+						}),
+						/* @__PURE__ */ jsx(Dot, {
+							x: cx + half,
+							y: TOP,
+							r: 3.5,
+							color: "var(--stage-good)"
+						}),
+						/* @__PURE__ */ jsx(Segment, {
+							from: {
+								x: cx - half,
+								y: TOP
+							},
+							to: open ? {
+								x: cx + half * .55,
+								y: TOP + half * .9
+							} : {
+								x: cx + half,
+								y: TOP
+							},
+							color: open ? "var(--stage-warn)" : "var(--stage-good)",
+							weight: 2.5
+						}),
+						/* @__PURE__ */ jsx(Label, {
+							x: cx,
+							y: TOP,
+							text: `${label} (${open ? "open" : "closed"})`,
+							color: "var(--stage-fg)",
+							size: 11,
+							dy: -16
+						})
+					] }, i);
+				}),
+				current > 1e-4 && Array.from({ length: N_DOTS }, (_, k) => {
+					const p = onPerimeter((t * speed + k / N_DOTS) % 1);
+					return /* @__PURE__ */ jsx(Dot, {
+						x: p.x,
+						y: p.y,
+						r: 3,
+						color: "var(--stage-accent)"
+					}, `f-${k}`);
+				})
+			]
+		})
+	});
+	const controls = /* @__PURE__ */ jsxs(ControlBar, { children: [/* @__PURE__ */ jsx(Field, {
+		label: "battery",
+		value: `${emf} V`,
+		children: /* @__PURE__ */ jsx(Slider, {
+			value: emf,
+			min: 1,
+			max: 24,
+			step: 1,
+			onChange: setEmf,
+			ariaLabel: "battery voltage",
+			style: { width: 120 }
+		})
+	}), switches.map(({ c, i }) => /* @__PURE__ */ jsxs(Chip, {
+		selected: !!closed[i],
+		onClick: () => setClosed((s) => ({
+			...s,
+			[i]: !s[i]
+		})),
+		children: [
+			c.label ?? "switch",
+			": ",
+			closed[i] ? "closed" : "open"
+		]
+	}, i))] });
+	const aside = /* @__PURE__ */ jsx(Callout, {
+		tone: "result",
+		children: /* @__PURE__ */ jsxs("span", {
+			style: {
+				display: "grid",
+				gap: 4,
+				fontVariantNumeric: "tabular-nums"
+			},
+			children: [
+				/* @__PURE__ */ jsx("span", { children: allClosed ? "closed" : "open — no current" }),
+				/* @__PURE__ */ jsxs("span", { children: [
+					"R ",
+					totalR.toFixed(0),
+					" Ω"
+				] }),
+				/* @__PURE__ */ jsxs("span", { children: [
+					"I ",
+					(current * 1e3).toFixed(0),
+					" mA"
+				] })
+			]
+		})
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt: switches.length ? "Flip a switch to open/close it. Tune the battery and watch the current — and the bulb." : "Tune the battery and watch the current flow.",
+		aside,
+		controls,
+		children: figure
+	});
+}
+
+//#endregion
+export { CircuitBuilder };

package/dist/circuits/circuit-lab.d.mts

@@ -0,0 +1,20 @@
+import { ReactNode } from "react";
+
+//#region src/circuits/circuit-lab.d.ts
+interface CircuitLabProps {
+  voltage?: number | string;
+  r1?: number | string;
+  r2?: number | string;
+  mode?: 'series' | 'parallel';
+  title?: string;
+  height?: number;
+}
+declare function CircuitLab({
+  voltage,
+  r1,
+  r2,
+  mode: modeInit,
+  height
+}?: CircuitLabProps): ReactNode;
+//#endregion
+export { CircuitLab, CircuitLabProps };