@classytic/labs 0.2.0 → 0.3.0

package/dist/domains/networking/subnet-builder/runtime.mjs

@@ -0,0 +1,249 @@
+'use client';
+
+import { Chip, Slider } from "../../../kit/controls.mjs";
+import { Field, LiveRegion } from "../../../kit/frame.mjs";
+import { AuthoredActivityRuntime } from "../../../kit/authored-activity-runtime.mjs";
+import { SubnetScene } from "../../../networking/SubnetScene.mjs";
+import { bitsOf, describe, firstDifferingBit, sameNetwork, widestSharedPrefix } from "../../../networking/subnet.mjs";
+import { useCallback, useMemo, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/domains/networking/subnet-builder/runtime.tsx
+/**
+* SubnetBuilderLab — one question, answered by moving a line.
+*
+* Subnetting is where students drown, and the reason is the notation. In dotted decimal the network
+* boundary is invisible, so "192.168.1.10 and 192.168.2.10 with a /24" has to be resolved by a
+* memorised procedure. In binary the boundary is a line, and the answer is whether the highlighted
+* halves match.
+*
+* So the learner slides the prefix and watches the verdict flip at exactly the first bit where the
+* two addresses differ. Everything else a subnetting question can ask (mask, network address,
+* broadcast, usable hosts) is reported alongside as a consequence of where that line sits.
+*/
+const PAIRS = [
+	{
+		label: "Same office",
+		a: "192.168.1.10",
+		b: "192.168.1.200"
+	},
+	{
+		label: "Next department",
+		a: "192.168.1.10",
+		b: "192.168.2.10"
+	},
+	{
+		label: "Another company",
+		a: "192.168.1.10",
+		b: "10.0.0.5"
+	}
+];
+const SUBNET_ACTIVITY = {
+	pattern: "diagnosis",
+	title: "Decide whether two hosts can talk directly",
+	objectives: [
+		"Read an IPv4 address as 32 bits split by the prefix",
+		"Decide whether two addresses share a network by comparing their network halves",
+		"Find the longest prefix that still keeps two hosts together",
+		"Explain why adding one bit to the prefix halves the usable addresses"
+	],
+	success: [
+		{
+			id: "direct-prediction",
+			source: "answer",
+			key: "can-talk",
+			pendingLabel: "Predict whether these two need a router."
+		},
+		{
+			id: "found-boundary",
+			source: "metric",
+			key: "boundary",
+			pendingLabel: "Find the prefix where the answer flips."
+		},
+		{
+			id: "halving",
+			source: "answer",
+			key: "why-halve",
+			pendingLabel: "Say what one more prefix bit does to the address space."
+		}
+	],
+	questions: [{
+		id: "can-talk",
+		prompt: "192.168.1.10 and 192.168.2.10 both use a /24 mask. Can they send to each other directly?",
+		choices: [
+			{
+				value: "yes",
+				label: "Yes, they are both 192.168.x",
+				feedback: "A /24 fixes the first three octets, and those differ."
+			},
+			{
+				value: "no",
+				label: "No, a router has to carry it between them"
+			},
+			{
+				value: "depends",
+				label: "Only if they are plugged into the same switch"
+			}
+		],
+		answer: "no",
+		explain: "A /24 makes the first 24 bits the network, which covers all three of 192, 168 and the third octet. One says 1 and the other says 2, so the network halves differ and the two are on separate networks however they are cabled."
+	}, {
+		id: "why-halve",
+		prompt: "A /24 offers 254 usable addresses. Why does a /25 offer 126?",
+		choices: [
+			{
+				value: "half",
+				label: "One more network bit leaves one fewer host bit, which halves the range"
+			},
+			{
+				value: "reserved",
+				label: "More addresses become reserved"
+			},
+			{
+				value: "router",
+				label: "The router takes the other half"
+			}
+		],
+		answer: "half",
+		explain: "Each bit moved from the host side to the network side halves how many hosts the block can hold. The two lost from every block are the network address itself and the broadcast address."
+	}],
+	steps: [
+		{
+			id: "predict",
+			phase: "predict",
+			title: "Router or not?",
+			lead: "Two addresses that look almost the same. Decide whether they need help to reach each other.",
+			success: "direct-prediction"
+		},
+		{
+			id: "act",
+			phase: "act",
+			title: "Move the line",
+			lead: "Slide the prefix and find where the answer changes.",
+			controls: true,
+			success: "found-boundary"
+		},
+		{
+			id: "observe",
+			phase: "observe",
+			title: "The bit that decides",
+			lead: "The marked bit is the first place the two addresses disagree. Everything follows from it.",
+			controls: true
+		},
+		{
+			id: "explain",
+			phase: "explain",
+			title: "What the mask buys",
+			lead: "Read the block off the panel: network address, broadcast, and how many hosts fit.",
+			controls: true
+		},
+		{
+			id: "transfer",
+			phase: "transfer",
+			title: "The cost of a longer prefix",
+			lead: "A longer prefix separates more and holds fewer. Decide what one extra bit costs.",
+			controls: true,
+			success: "halving"
+		}
+	]
+};
+function SubnetBuilderLab({ hostA = "192.168.1.10", hostB = "192.168.2.10", prefix = 16, title, prompt } = {}) {
+	const [pair, setPair] = useState({
+		a: hostA,
+		b: hostB
+	});
+	const [bits, setBits] = useState(prefix);
+	const aBits = useMemo(() => bitsOf(pair.a, bits), [pair.a, bits]);
+	const bBits = useMemo(() => bitsOf(pair.b, bits), [pair.b, bits]);
+	const info = useMemo(() => describe(pair.a, bits), [pair.a, bits]);
+	const same = useMemo(() => sameNetwork(pair.a, pair.b, bits) ?? false, [pair, bits]);
+	const boundary = useMemo(() => firstDifferingBit(pair.a, pair.b), [pair]);
+	const widest = useMemo(() => widestSharedPrefix(pair.a, pair.b), [pair]);
+	const differing = boundary >= 0 ? [boundary] : [];
+	const move = useCallback((value, context) => {
+		setBits(value);
+		if (widest < 32 && (value === widest || value === widest + 1)) context.complete("found-boundary", "boundary");
+	}, [widest]);
+	const headline = same ? `At /${bits} the network halves match, so ${pair.a} and ${pair.b} can send to each other directly.` : `At /${bits} the network halves differ, so traffic between ${pair.a} and ${pair.b} needs a router.`;
+	if (!aBits || !bBits || !info) return null;
+	return /* @__PURE__ */ jsx(AuthoredActivityRuntime, {
+		activity: SUBNET_ACTIVITY,
+		activityId: "subnet-builder",
+		eyebrow: "Addressing",
+		title: title ?? "Same network, or not",
+		description: prompt ?? "Every subnetting question is really one question. In binary the answer is a line you can move, and it flips at exactly one bit.",
+		status: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsxs("span", { children: [
+				/* @__PURE__ */ jsxs("strong", { children: ["/", bits] }),
+				" · ",
+				info.mask
+			] }),
+			/* @__PURE__ */ jsxs("span", { children: [info.usableHosts.toLocaleString("en-US"), " usable"] }),
+			/* @__PURE__ */ jsx("span", {
+				"data-delivered": same || void 0,
+				children: same ? "direct" : "needs a router"
+			})
+		] }),
+		inspector: (context) => /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "network-inspector-heading",
+				children: [/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsxs("span", { children: ["The block containing ", pair.a] }), /* @__PURE__ */ jsxs("strong", { children: [
+					info.network,
+					"/",
+					bits
+				] })] }), /* @__PURE__ */ jsx("span", { children: info.mask })]
+			}),
+			/* @__PURE__ */ jsxs("ul", {
+				className: "lab-metric-list",
+				children: [
+					/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", { children: "Network address" }), /* @__PURE__ */ jsx("strong", { children: info.network })] }),
+					/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", { children: "Broadcast" }), /* @__PURE__ */ jsx("strong", { children: info.broadcast })] }),
+					/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", { children: "Usable range" }), /* @__PURE__ */ jsx("strong", { children: info.firstUsable ? `${info.firstUsable} to ${info.lastUsable}` : "none at this size" })] }),
+					/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", { children: "Hosts that fit" }), /* @__PURE__ */ jsx("strong", { children: info.usableHosts.toLocaleString("en-US") })] })
+				]
+			}),
+			/* @__PURE__ */ jsx(Field, {
+				label: "prefix",
+				value: /* @__PURE__ */ jsxs("b", { children: ["/", bits] }),
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: bits,
+					min: 0,
+					max: 32,
+					step: 1,
+					onChange: (value) => move(value, context),
+					ariaLabel: "prefix length"
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "lab-activity-fields",
+				children: PAIRS.map((item) => /* @__PURE__ */ jsx(Chip, {
+					selected: pair.a === item.a && pair.b === item.b,
+					onClick: () => setPair({
+						a: item.a,
+						b: item.b
+					}),
+					children: item.label
+				}, item.label))
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "lab-note",
+				children: widest >= 32 ? "These two addresses are identical, so no prefix can separate them." : `Anything up to /${widest} keeps them together. /${widest + 1} is the first prefix that splits them.`
+			}),
+			/* @__PURE__ */ jsx(LiveRegion, { children: headline })
+		] }),
+		observation: headline,
+		children: /* @__PURE__ */ jsx(SubnetScene, {
+			aLabel: pair.a,
+			bLabel: pair.b,
+			aBits,
+			bBits,
+			prefix: bits,
+			differing,
+			same,
+			label: `${pair.a} and ${pair.b} at a /${bits} prefix. ${same ? "Same network." : "Different networks."}`
+		})
+	});
+}
+
+//#endregion
+export { SubnetBuilderLab, SubnetBuilderLab as default };

package/dist/domains/networking/switch-learning/manifest.mjs

@@ -0,0 +1,62 @@
+import { defineLab } from "../../../lab-def/define-lab.mjs";
+import { z } from "zod";
+
+//#region src/domains/networking/switch-learning/manifest.ts
+var manifest_default = defineLab({
+	id: "switch-learning",
+	domain: "networking",
+	group: "Networking",
+	title: "The switch that learns (MAC forwarding)",
+	description: "An eight-port switch with a forwarding table that starts empty. Send a frame and it floods, because the switch has no idea where anything is. Send the reply and it forwards to one port only, because it just learned. Ports can be clicked to take the link down, which makes the switch forget and flood again, so the table stops being a definition and becomes a thing with consequences.",
+	schema: z.object({
+		ports: z.number().int().min(4).max(8).default(8),
+		connected: z.number().int().min(2).max(8).default(4),
+		title: z.string().optional(),
+		prompt: z.string().optional()
+	}),
+	taxonomy: {
+		grades: [
+			"10",
+			"11",
+			"12",
+			"undergraduate"
+		],
+		outcomes: [
+			"networking",
+			"switching",
+			"mac-addressing"
+		],
+		durationMinutes: 15,
+		interaction: "predict",
+		authorability: "simple",
+		representation: "schematic",
+		prerequisites: [],
+		related: ["packet-journey"],
+		starter: true
+	},
+	experience: {
+		objectives: [
+			"Predict what a switch does with a destination address it has never seen",
+			"Explain that the table is learned from the SOURCE address of arriving frames",
+			"Contrast the first frame of a conversation with the second",
+			"Predict what a port going down does to what the switch knows"
+		],
+		phases: [
+			"predict",
+			"act",
+			"observe",
+			"explain",
+			"transfer"
+		],
+		responses: ["choice"],
+		accessibility: {
+			keyboard: true,
+			textAlternative: true,
+			reducedMotion: true
+		}
+	},
+	loadRuntime: () => import("./runtime.mjs")
+});
+
+//#endregion
+export { manifest_default as default };

package/dist/domains/networking/switch-learning/runtime.mjs

@@ -0,0 +1,250 @@
+'use client';
+
+import { Chip } from "../../../kit/controls.mjs";
+import { LiveRegion } from "../../../kit/frame.mjs";
+import { AuthoredActivityRuntime } from "../../../kit/authored-activity-runtime.mjs";
+import { clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled } from "../../../networking/switch.mjs";
+import { SwitchScene } from "../../../networking/SwitchScene.mjs";
+import { useCallback, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/domains/networking/switch-learning/runtime.tsx
+/**
+* SwitchLearningLab — the first frame floods, the second one does not.
+*
+* Most courses state that a switch "learns MAC addresses" and then ask for it back. The learning
+* is trivial once seen and invisible until then, so this lab makes the table the object on screen:
+* it starts empty, fills as frames arrive, and every forwarding decision visibly reads from it.
+*
+* The transfer step disables a port. That is the moment the model stops being a story about
+* addresses and becomes a thing with consequences, because the table forgets and the switch goes
+* back to flooding.
+*/
+const SWITCH_ACTIVITY = {
+	pattern: "diagnosis",
+	title: "Watch a switch learn where everything is",
+	objectives: [
+		"Predict what a switch does with a destination it has never seen",
+		"Trace how the forwarding table is built from the source address of arriving frames",
+		"Explain why the second frame of a conversation behaves differently from the first",
+		"Predict the effect of a port going down on what the switch knows"
+	],
+	success: [
+		{
+			id: "flood-prediction",
+			source: "answer",
+			key: "first-frame",
+			pendingLabel: "Predict who receives the very first frame."
+		},
+		{
+			id: "sent-one",
+			source: "action",
+			key: "send",
+			pendingLabel: "Send a frame from any device."
+		},
+		{
+			id: "saw-unicast",
+			source: "metric",
+			key: "unicast",
+			pendingLabel: "Send a reply so the switch can forward to a single port."
+		},
+		{
+			id: "port-down",
+			source: "answer",
+			key: "link-down",
+			pendingLabel: "Predict what happens to the table when a port goes down."
+		}
+	],
+	questions: [{
+		id: "first-frame",
+		prompt: "The switch was unboxed a second ago and its table is empty. Laptop sends one frame to Printer. Which devices receive it?",
+		choices: [
+			{
+				value: "printer",
+				label: "Only Printer",
+				feedback: "The switch has no way to know where Printer is yet."
+			},
+			{
+				value: "all",
+				label: "Every connected device except Laptop"
+			},
+			{
+				value: "none",
+				label: "Nobody, the frame is dropped",
+				feedback: "A switch floods rather than discards."
+			}
+		],
+		answer: "all",
+		explain: "With nothing in the table the switch cannot know which port leads to Printer, so it floods: out of every port with a link, except the one the frame arrived on."
+	}, {
+		id: "link-down",
+		prompt: "A device is unplugged and its port goes down. What happens to the entry the switch learned for it?",
+		choices: [
+			{
+				value: "kept",
+				label: "It is kept, so traffic still goes to that port"
+			},
+			{
+				value: "removed",
+				label: "It is removed, so the switch floods for that address again"
+			},
+			{
+				value: "moved",
+				label: "It moves to the next free port"
+			}
+		],
+		answer: "removed",
+		explain: "An entry only means \"reachable through this port\". When the port has no link that is no longer true, so the entry goes and the switch is back to flooding for that address."
+	}],
+	steps: [
+		{
+			id: "predict",
+			phase: "predict",
+			title: "Predict the first frame",
+			lead: "The table is empty. Decide who hears the first frame before you send it.",
+			success: "flood-prediction"
+		},
+		{
+			id: "act",
+			phase: "act",
+			title: "Send it",
+			lead: "Click a device to send a frame from it, and watch which cables light up.",
+			controls: true,
+			success: "sent-one"
+		},
+		{
+			id: "observe",
+			phase: "observe",
+			title: "Now send a reply",
+			lead: "Send back the other way. Watch the table, then watch how many cables light this time.",
+			controls: true,
+			success: "saw-unicast"
+		},
+		{
+			id: "explain",
+			phase: "explain",
+			title: "Read the table",
+			lead: "Every entry was learned from the source address of a frame that arrived. Nothing was configured.",
+			controls: true
+		},
+		{
+			id: "transfer",
+			phase: "transfer",
+			title: "Take a port down",
+			lead: "Click a port on the switch to disable it, and predict what the table does.",
+			controls: true,
+			success: "port-down"
+		}
+	]
+};
+function SwitchLearningLab({ ports = 8, connected = 4, title, prompt } = {}) {
+	const [state, setState] = useState(() => makeSwitch(ports, connected));
+	const [events, setEvents] = useState([]);
+	const [ingress, setIngress] = useState();
+	const [delivered, setDelivered] = useState([]);
+	const [flooded, setFlooded] = useState(false);
+	const live = state.ports.filter(linkUp);
+	const send = useCallback((fromPort, context) => {
+		const target = state.ports.find((port) => port.id !== fromPort && linkUp(port));
+		if (!target?.device) return;
+		const result = sendFrame(state, fromPort, target.device.mac);
+		setState(result.next);
+		setEvents(result.events);
+		setIngress(fromPort);
+		setDelivered(result.delivered);
+		setFlooded(result.flooded);
+		context.complete("sent-one");
+		if (!result.flooded && result.delivered.length === 1) context.complete("saw-unicast", "unicast");
+	}, [state]);
+	const toggle = useCallback((portId) => {
+		setState((current) => {
+			const port = current.ports.find((item) => item.id === portId);
+			return port ? setPortEnabled(current, portId, !port.enabled) : current;
+		});
+		setIngress(void 0);
+		setDelivered([]);
+	}, []);
+	const reset = useCallback(() => {
+		setState(makeSwitch(ports, connected));
+		setEvents([]);
+		setIngress(void 0);
+		setDelivered([]);
+		setFlooded(false);
+	}, [ports, connected]);
+	const headline = events.at(-1)?.message ?? "Nothing has been sent yet, so the table is empty.";
+	const sceneLabel = `Eight-port switch. ${state.table.length} address${state.table.length === 1 ? "" : "es"} learned. ${delivered.length ? `Frame left by port${delivered.length > 1 ? "s" : ""} ${delivered.join(", ")}.` : ""}`;
+	return /* @__PURE__ */ jsx(AuthoredActivityRuntime, {
+		activity: SWITCH_ACTIVITY,
+		activityId: "switch-learning",
+		eyebrow: "Networking",
+		title: title ?? "The switch that learns",
+		description: prompt ?? "A switch is told nothing about the network. It works out where everything is by watching who talks, and until it has, it shouts.",
+		status: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsxs("span", { children: [
+				/* @__PURE__ */ jsxs("strong", { children: [
+					state.table.length,
+					" / ",
+					live.length
+				] }),
+				" ",
+				"addresses learned"
+			] }),
+			/* @__PURE__ */ jsxs("span", { children: [live.length, " ports with a link"] }),
+			delivered.length > 0 && /* @__PURE__ */ jsx("span", {
+				"data-delivered": !flooded || void 0,
+				children: flooded ? `flooded to ${delivered.length}` : `forwarded to port ${delivered[0]}`
+			})
+		] }),
+		inspector: (context) => /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "network-inspector-heading",
+				children: [/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("span", { children: "Learned from traffic" }), /* @__PURE__ */ jsx("strong", { children: "Forwarding table" })] }), /* @__PURE__ */ jsx("span", { children: state.table.length ? `${state.table.length} entries` : "empty" })]
+			}),
+			state.table.length === 0 ? /* @__PURE__ */ jsx("p", {
+				className: "lab-note",
+				children: "Empty. Until something arrives, the switch has no idea what is plugged into which port."
+			}) : /* @__PURE__ */ jsx("ul", {
+				className: "lab-metric-list",
+				children: state.table.map((entry) => {
+					const owner = state.ports.find((port) => port.device?.mac === entry.mac)?.device;
+					return /* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", { children: owner?.name ?? entry.mac }), /* @__PURE__ */ jsxs("strong", { children: ["port ", entry.port] })] }, entry.mac);
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "lab-activity-fields",
+				children: state.ports.filter(linkUp).map((port) => /* @__PURE__ */ jsxs(Chip, {
+					selected: ingress === port.id,
+					onClick: () => send(port.id, context),
+					children: ["Send from ", port.device.name]
+				}, port.id))
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "lab-activity-fields",
+				children: [/* @__PURE__ */ jsx(Chip, {
+					selected: false,
+					onClick: () => setState(clearTable(state)),
+					disabled: !state.table.length,
+					children: "Clear table"
+				}), /* @__PURE__ */ jsx(Chip, {
+					selected: false,
+					onClick: reset,
+					children: "Reset switch"
+				})]
+			}),
+			/* @__PURE__ */ jsx(LiveRegion, { children: headline })
+		] }),
+		observation: headline,
+		transcript: /* @__PURE__ */ jsx("ol", { children: events.map((event, index) => /* @__PURE__ */ jsx("li", { children: event.message }, index)) }),
+		children: /* @__PURE__ */ jsx(SwitchScene, {
+			state,
+			ingress,
+			delivered,
+			flooded,
+			onTogglePort: toggle,
+			label: sceneLabel
+		})
+	});
+}
+
+//#endregion
+export { SwitchLearningLab, SwitchLearningLab as default };

package/dist/domains/networking/vlan-designer/manifest.mjs

@@ -0,0 +1,66 @@
+import { defineLab } from "../../../lab-def/define-lab.mjs";
+import { z } from "zod";
+
+//#region src/domains/networking/vlan-designer/manifest.ts
+var manifest_default = defineLab({
+	id: "vlan-designer",
+	domain: "networking",
+	group: "Networking",
+	title: "Two networks in one switch (VLANs)",
+	description: "One physical switch drawn as the two separate switches it is pretending to be. A broadcast fills its own tinted region and visibly stops at the edge, and the machines in the other VLAN are marked as never having heard it. Clicking a port moves that machine into the other VLAN, changing who receives a broadcast without a cable being touched. The last phase adds a layer-3 interface, which lets addressed traffic cross while leaving the flooding boundary exactly where it was, so every crossing passes one point.",
+	schema: z.object({
+		connectedPorts: z.number().int().min(2).max(8).default(6),
+		routing: z.boolean().default(false),
+		title: z.string().optional(),
+		prompt: z.string().optional()
+	}),
+	taxonomy: {
+		grades: [
+			"11",
+			"12",
+			"undergraduate"
+		],
+		outcomes: [
+			"networking",
+			"vlan",
+			"broadcast-domain",
+			"segmentation"
+		],
+		durationMinutes: 15,
+		interaction: "explorer",
+		authorability: "simple",
+		representation: "device",
+		prerequisites: ["switch-learning"],
+		related: [
+			"switch-learning",
+			"subnet-builder",
+			"packet-journey"
+		],
+		starter: false
+	},
+	experience: {
+		objectives: [
+			"State what a VLAN is in terms of what a broadcast reaches",
+			"Change which machines hear a broadcast without touching a cable",
+			"Explain why nothing crosses between VLANs at layer 2",
+			"Describe what a layer-3 interface adds, and what it deliberately does not"
+		],
+		phases: [
+			"predict",
+			"act",
+			"observe",
+			"explain",
+			"transfer"
+		],
+		responses: ["choice"],
+		accessibility: {
+			keyboard: true,
+			textAlternative: true,
+			reducedMotion: true
+		}
+	},
+	loadRuntime: () => import("./runtime.mjs")
+});
+
+//#endregion
+export { manifest_default as default };