@classytic/stage 0.3.0 → 0.4.0

package/dist/networking/models/wifi.mjs

@@ -0,0 +1,562 @@
+//#region src/networking/models/wifi.ts
+const BANDS = {
+	"2.4": {
+		id: "2.4",
+		label: "2.4 GHz",
+		megahertz: 2437,
+		channels: 3,
+		peakMbps: 150,
+		note: "Travels further and through more walls. Only three non-overlapping channels, shared with every neighbour, every microwave oven and every Bluetooth device."
+	},
+	"5": {
+		id: "5",
+		label: "5 GHz",
+		megahertz: 5180,
+		channels: 24,
+		peakMbps: 650,
+		note: "Far more room and far more speed, and it pays for that with range. A shorter wave is absorbed harder by everything it passes through."
+	}
+};
+/**
+* Loss per wall, in dB. These are the numbers a site survey actually uses, rounded to whole
+* decibels because the spread between real buildings is wider than the rounding.
+*
+* The column to read across is the band. Concrete costs 12 dB at 2.4 GHz and 20 dB at 5 GHz: the
+* SAME wall takes eight extra decibels out of the faster band, which is a further sixfold drop in
+* power. One interior wall is survivable on either band. Two concrete walls is where 5 GHz stops
+* being a choice.
+*/
+const MATERIALS = {
+	drywall: {
+		id: "drywall",
+		label: "Plasterboard partition",
+		loss: {
+			"2.4": 3,
+			"5": 4
+		},
+		note: "A hollow partition between two rooms. Nearly free to pass through, which is why open-plan flats cover easily."
+	},
+	wood: {
+		id: "wood",
+		label: "Wooden door",
+		loss: {
+			"2.4": 3,
+			"5": 5
+		},
+		note: "Closing an internal door costs real signal. Students rarely believe this until they watch the number move."
+	},
+	glass: {
+		id: "glass",
+		label: "Glass",
+		loss: {
+			"2.4": 3,
+			"5": 6
+		},
+		note: "Plain glass is mild. Coated energy-saving glass behaves closer to brick, which is why signal often dies at a balcony."
+	},
+	brick: {
+		id: "brick",
+		label: "Brick wall",
+		loss: {
+			"2.4": 6,
+			"5": 10
+		},
+		note: "The standard load-bearing wall in most homes here. Two of them between router and phone is the usual cause of a dead bedroom."
+	},
+	concrete: {
+		id: "concrete",
+		label: "Reinforced concrete",
+		loss: {
+			"2.4": 12,
+			"5": 20
+		},
+		note: "Slab, column or shear wall. The steel inside matters as much as the concrete: a conductive mesh reflects what it does not absorb."
+	},
+	metal: {
+		id: "metal",
+		label: "Metal / lift shaft",
+		loss: {
+			"2.4": 30,
+			"5": 35
+		},
+		note: "Effectively a wall a radio cannot cross. Signal reaches the far side by going around it, never through."
+	}
+};
+/**
+* Transmit power of a domestic access point, in dBm. 20 dBm is 100 mW, the legal ceiling in most
+* places and what essentially every home router emits, which is worth knowing because it means
+* "buy a more powerful router" is not available as an answer. The only levers are position,
+* frequency, and a second access point.
+*/
+const TX_POWER_DBM = 20;
+/**
+* How fast power falls with distance indoors.
+*
+* In free space the exponent is 2: pure spreading over a sphere. Indoors, 3.0 is the standard
+* figure for a home or small office, because furniture, floors and people absorb as well as the
+* geometry spreading. The walls are counted separately and explicitly, so this number represents
+* everything that is NOT a wall the learner placed.
+*/
+const PATH_LOSS_EXPONENT = 3;
+/**
+* The floor below which a number stops meaning anything, in dBm.
+*
+* Thermal noise in a 20 MHz channel sits near -101 dBm, so a receiver cannot distinguish a signal
+* from the noise it arrives in much below this. An uncapped model happily reports -114 dBm, which
+* looks precise and is fiction: the honest statement is "below the noise floor", and the lab should
+* say that rather than print a number a real radio could never measure.
+*/
+const NOISE_FLOOR_DBM = -100;
+/**
+* Loss over the first metre, in dB. This is where frequency enters before any wall is involved:
+* about 40 dB at 2.4 GHz and 46 dB at 5 GHz. The faster band starts six decibels behind at the
+* very first metre, having passed through nothing at all.
+*/
+function referenceLossDb(band) {
+	return 20 * Math.log10(BANDS[band].megahertz) + 20 * Math.log10(.001) + 32.44;
+}
+/** Do two segments cross? Used to find which walls sit between the router and a point. */
+function segmentsCross(a1, a2, b1, b2) {
+	const side = (p, q, r) => (q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x);
+	const d1 = side(b1, b2, a1);
+	const d2 = side(b1, b2, a2);
+	const d3 = side(a1, a2, b1);
+	const d4 = side(a1, a2, b2);
+	return (d1 > 0 !== d2 > 0 || d1 === 0 || d2 === 0) && (d3 > 0 !== d4 > 0 || d3 === 0 || d4 === 0) && d1 !== 0 && d2 !== 0 && d3 !== 0 && d4 !== 0;
+}
+/** The walls a straight line from the router to a point passes through. */
+function wallsBetween(plan, from, to) {
+	return plan.walls.filter((wall) => segmentsCross(from, to, {
+		x: wall.x1,
+		y: wall.y1
+	}, {
+		x: wall.x2,
+		y: wall.y2
+	}));
+}
+/**
+* Received signal strength at a point, by the log-distance model with explicit wall terms.
+*
+* This treats the signal as travelling in a straight line and ignores reflection, which in a real
+* flat delivers some signal around a corner that this model calls dead. That simplification is
+* deliberate and is the right one for teaching: it keeps the cause of every number visible, and a
+* model that says "a wall costs you this much" is exactly the intuition a learner should leave with.
+*/
+function signalAt(plan, router, point, band) {
+	const dx = point.x - router.x;
+	const dy = point.y - router.y;
+	const distanceM = Math.max(1, Math.hypot(dx, dy));
+	const obstacles = wallsBetween(plan, router, point);
+	const wallLossDb = obstacles.reduce((sum, wall) => sum + MATERIALS[wall.material].loss[band], 0);
+	const spreading = 10 * 3 * Math.log10(distanceM);
+	const rssi = 20 - referenceLossDb(band) - spreading - wallLossDb;
+	return {
+		rssi: Math.max(NOISE_FLOOR_DBM, rssi),
+		distanceM,
+		obstacles,
+		wallLossDb
+	};
+}
+/**
+* The grade ladder, in dBm.
+*
+* These are the thresholds a real site survey designs against rather than round numbers chosen to
+* look tidy: -67 dBm is the industry target for voice and video, and -70 is where ordinary data
+* starts to struggle. Naming what a learner could DO at each level, rather than calling it "3 bars",
+* is the point. Bars are a made-up scale that differs between handsets; dBm is a measurement.
+*/
+const GRADES = [
+	{
+		id: "excellent",
+		label: "Excellent",
+		floor: -50,
+		can: "Anything at full speed, right beside the router."
+	},
+	{
+		id: "good",
+		label: "Good",
+		floor: -60,
+		can: "HD video calls and large downloads, no trouble."
+	},
+	{
+		id: "usable",
+		label: "Usable",
+		floor: -67,
+		can: "Video works. This is the level a network is designed to reach everywhere it matters."
+	},
+	{
+		id: "weak",
+		label: "Weak",
+		floor: -80,
+		can: "Messaging and browsing. Calls break up and video stops to buffer."
+	},
+	{
+		id: "dead",
+		label: "No usable signal",
+		floor: -Infinity,
+		can: "The phone may still show a bar and nothing will load."
+	}
+];
+function grade(rssi) {
+	return GRADES.find((step) => rssi >= step.floor) ?? GRADES[GRADES.length - 1];
+}
+/**
+* A rough throughput for a reading, in Mbps.
+*
+* Real rate selection is a ladder of modulation schemes, and the shape that matters to a learner is
+* that throughput does not fade gently with distance: it holds up, then falls off a cliff as each
+* rung becomes unreadable. Interpolating between the grade thresholds reproduces that staircase
+* feel without pretending to model MCS tables.
+*/
+function throughputMbps(rssi, band) {
+	const peak = BANDS[band].peakMbps;
+	if (rssi >= -50) return peak;
+	if (rssi >= -60) return Math.round(peak * .7);
+	if (rssi >= -67) return Math.round(peak * .4);
+	if (rssi >= -73) return Math.round(peak * .15);
+	if (rssi >= -80) return Math.round(peak * .05);
+	return 0;
+}
+/** Sample points inside a room. A 3x3 grid inset from the walls, so a corner is not judged from its centre. */
+function samplePoints(room) {
+	const points = [];
+	for (let ix = 1; ix <= 3; ix++) for (let iy = 1; iy <= 3; iy++) points.push({
+		x: room.x + room.w * ix / 4,
+		y: room.y + room.h * iy / 4
+	});
+	return points;
+}
+/**
+* Grade every room from its WORST corner rather than its centre.
+*
+* Judging a room by its middle is how a coverage plan passes on paper and fails in the building:
+* the desk is against the far wall, not in the centre of the floor. Reporting the worst sample also
+* makes the lab honest when a learner parks the router in the hallway and every room reads "usable"
+* from its midpoint while the bed and the desk do not.
+*/
+function roomVerdicts(plan, router, band) {
+	return plan.rooms.map((room) => {
+		let worst = null;
+		for (const point of samplePoints(room)) {
+			const reading = signalAt(plan, router, point, band);
+			if (!worst || reading.rssi < worst.rssi) worst = reading;
+		}
+		const reading = worst;
+		const blamed = [...new Set(reading.obstacles.map((wall) => wall.material))].sort((a, b) => MATERIALS[b].loss[band] - MATERIALS[a].loss[band]);
+		return {
+			room,
+			rssi: reading.rssi,
+			grade: grade(reading.rssi),
+			mbps: throughputMbps(reading.rssi, band),
+			blamed
+		};
+	});
+}
+/**
+* RSSI on a regular grid over the whole plan, for the heat map.
+*
+* Returned row-major as `[row][col]` with row 0 at the top, matching how the SVG draws it, so the
+* scene never has to flip an index and quietly mirror the picture.
+*/
+function coverageGrid(plan, router, band, cols, rows) {
+	const grid = [];
+	for (let row = 0; row < rows; row++) {
+		const line = [];
+		const y = plan.heightM * (row + .5) / rows;
+		for (let col = 0; col < cols; col++) {
+			const x = plan.widthM * (col + .5) / cols;
+			line.push(signalAt(plan, router, {
+				x,
+				y
+			}, band).rssi);
+		}
+		grid.push(line);
+	}
+	return grid;
+}
+/** Share of the rooms that reach at least `usable`, which is the number a learner is trying to raise. */
+function coverageScore(plan, router, band) {
+	const verdicts = roomVerdicts(plan, router, band);
+	if (!verdicts.length) return 0;
+	return verdicts.filter((verdict) => verdict.rssi >= -67).length / verdicts.length;
+}
+/** A run of wall with doorway gaps left open, so a learner can see signal pour through a door. */
+function wallRun(axis, at, spans, material) {
+	return spans.map(([from, to]) => axis === "h" ? {
+		x1: from,
+		y1: at,
+		x2: to,
+		y2: at,
+		material
+	} : {
+		x1: at,
+		y1: from,
+		x2: at,
+		y2: to,
+		material
+	});
+}
+/**
+* Floor plans a learner recognises, which is most of the work.
+*
+* A generic rectangle labelled "room A / room B" teaches the model and none of the intuition. The
+* three-bedroom flat below is the ordinary shape of an apartment in Dhaka or Chattogram: brick
+* partitions, a concrete wet wall around the bathroom, and the router wherever the broadband cable
+* happened to enter, which is almost never where it should be. A learner who fixes THIS plan can
+* walk home and fix theirs, and that transfer is the whole reason to draw a room instead of a graph.
+*/
+const FLOOR_PLANS = [
+	{
+		id: "flat",
+		name: "Three-bedroom flat",
+		widthM: 12,
+		heightM: 9,
+		note: "The cable enters at the drawing room corner, so that is where the router sits. Two brick walls and a concrete wet wall stand between it and the far bedroom.",
+		rooms: [
+			{
+				id: "living",
+				name: "Drawing room",
+				x: 0,
+				y: 0,
+				w: 6,
+				h: 5
+			},
+			{
+				id: "kitchen",
+				name: "Kitchen",
+				x: 6,
+				y: 0,
+				w: 3,
+				h: 5
+			},
+			{
+				id: "bath",
+				name: "Bathroom",
+				x: 9,
+				y: 0,
+				w: 3,
+				h: 5
+			},
+			{
+				id: "bed1",
+				name: "Bedroom 1",
+				x: 0,
+				y: 5,
+				w: 4,
+				h: 4
+			},
+			{
+				id: "bed2",
+				name: "Bedroom 2",
+				x: 4,
+				y: 5,
+				w: 4,
+				h: 4
+			},
+			{
+				id: "bed3",
+				name: "Bedroom 3",
+				x: 8,
+				y: 5,
+				w: 4,
+				h: 4
+			}
+		],
+		spots: [
+			{
+				id: "corner",
+				name: "Drawing room corner, where the cable enters",
+				x: 1,
+				y: 1
+			},
+			{
+				id: "middle",
+				name: "Middle of the drawing room",
+				x: 4.6,
+				y: 2.4
+			},
+			{
+				id: "kitchen",
+				name: "On the kitchen worktop",
+				x: 7.5,
+				y: 4.3
+			},
+			{
+				id: "hall",
+				name: "Bedroom 2 wall, beside the door",
+				x: 7.6,
+				y: 5.4
+			},
+			{
+				id: "bed1",
+				name: "Bedroom 1, next to the bed",
+				x: 2,
+				y: 7
+			}
+		],
+		walls: [
+			...wallRun("h", 5, [
+				[0, 3],
+				[3.9, 7],
+				[7.9, 12]
+			], "brick"),
+			...wallRun("v", 6, [[0, 3.2], [4.1, 5]], "brick"),
+			...wallRun("v", 9, [[0, 5]], "concrete"),
+			...wallRun("v", 4, [[5, 8.1]], "brick"),
+			...wallRun("v", 8, [[5, 8.1]], "brick")
+		]
+	},
+	{
+		id: "open",
+		name: "Open-plan studio",
+		widthM: 10,
+		heightM: 7,
+		note: "Almost nothing in the way. Included so a learner can see what distance alone does, with absorption taken out of the picture.",
+		rooms: [
+			{
+				id: "main",
+				name: "Living and sleeping",
+				x: 0,
+				y: 0,
+				w: 7,
+				h: 7
+			},
+			{
+				id: "wash",
+				name: "Washroom",
+				x: 7,
+				y: 0,
+				w: 3,
+				h: 3
+			},
+			{
+				id: "balcony",
+				name: "Balcony",
+				x: 7,
+				y: 3,
+				w: 3,
+				h: 4
+			}
+		],
+		spots: [
+			{
+				id: "corner",
+				name: "Corner by the door",
+				x: 1,
+				y: 1
+			},
+			{
+				id: "middle",
+				name: "Middle of the room",
+				x: 3.5,
+				y: 3.5
+			},
+			{
+				id: "balcony",
+				name: "Out on the balcony",
+				x: 8.5,
+				y: 5
+			}
+		],
+		walls: [
+			...wallRun("v", 7, [[0, 2.2]], "brick"),
+			...wallRun("h", 3, [[7, 10]], "drywall"),
+			...wallRun("v", 7, [[3.4, 7]], "glass")
+		]
+	},
+	{
+		id: "office",
+		name: "Small office floor",
+		widthM: 16,
+		heightM: 10,
+		note: "A concrete core and a lift shaft. One access point cannot do this, and discovering that is the point of the plan.",
+		rooms: [
+			{
+				id: "open-desks",
+				name: "Open desks",
+				x: 0,
+				y: 0,
+				w: 9,
+				h: 10
+			},
+			{
+				id: "meeting",
+				name: "Meeting room",
+				x: 9,
+				y: 0,
+				w: 4,
+				h: 5
+			},
+			{
+				id: "server",
+				name: "Server room",
+				x: 9,
+				y: 5,
+				w: 4,
+				h: 5
+			},
+			{
+				id: "lobby",
+				name: "Lift lobby",
+				x: 13,
+				y: 0,
+				w: 3,
+				h: 10
+			}
+		],
+		spots: [
+			{
+				id: "desks",
+				name: "Above the open desks",
+				x: 4.5,
+				y: 5
+			},
+			{
+				id: "core",
+				name: "Against the concrete core",
+				x: 8.2,
+				y: 4.5
+			},
+			{
+				id: "meeting",
+				name: "Inside the meeting room",
+				x: 11,
+				y: 2.5
+			}
+		],
+		walls: [
+			...wallRun("v", 9, [[0, 4.1], [5, 10]], "concrete"),
+			...wallRun("h", 5, [[9, 13]], "concrete"),
+			...wallRun("v", 13, [[0, 4], [5.1, 10]], "metal")
+		]
+	}
+];
+/**
+* The best spot on the plan, found by trying a coarse grid of positions.
+*
+* Present this only AFTER a learner has committed to a position of their own. Shown first it is an
+* answer key and they will drag toward it without forming a reason; shown second it is feedback on
+* a guess they already had to justify, and the gap between the two is the lesson.
+*/
+function bestPlacement(plan, band, step = 1) {
+	let best = {
+		x: plan.widthM / 2,
+		y: plan.heightM / 2
+	};
+	let bestScore = -Infinity;
+	for (let x = step; x < plan.widthM; x += step) for (let y = step; y < plan.heightM; y += step) {
+		const candidate = {
+			x,
+			y
+		};
+		const worst = Math.min(...roomVerdicts(plan, candidate, band).map((verdict) => verdict.rssi));
+		if (worst > bestScore) {
+			bestScore = worst;
+			best = candidate;
+		}
+	}
+	return best;
+}
+
+//#endregion
+export { BANDS, FLOOR_PLANS, GRADES, MATERIALS, NOISE_FLOOR_DBM, PATH_LOSS_EXPONENT, TX_POWER_DBM, bestPlacement, coverageGrid, coverageScore, grade, referenceLossDb, roomVerdicts, signalAt, throughputMbps, wallsBetween };

package/dist/networking/nat-traversal.d.mts

@@ -0,0 +1,24 @@
+//#region src/networking/nat-traversal.d.ts
+type NatBehavior = "endpoint-independent" | "address-dependent" | "symmetric";
+type TraversalStrategy = "host-only" | "stun" | "ice";
+interface NatTraversalOptions {
+  leftNat: NatBehavior;
+  rightNat: NatBehavior;
+  strategy: TraversalStrategy;
+  turnAvailable?: boolean;
+}
+interface NatTraversalResult {
+  candidates: readonly ("host" | "server-reflexive" | "relay")[];
+  selectedPath: "direct" | "mapped-direct" | "relay" | "blocked";
+  relayRequired: boolean;
+  relativeLatency: 1 | 2;
+  explanation: string;
+}
+declare function simulateNatTraversal({
+  leftNat,
+  rightNat,
+  strategy,
+  turnAvailable
+}: NatTraversalOptions): NatTraversalResult;
+//#endregion
+export { NatBehavior, NatTraversalOptions, NatTraversalResult, TraversalStrategy, simulateNatTraversal };

package/dist/networking/nat-traversal.mjs

@@ -0,0 +1,38 @@
+//#region src/networking/nat-traversal.ts
+function simulateNatTraversal({ leftNat, rightNat, strategy, turnAvailable = true }) {
+	if (strategy === "host-only") return {
+		candidates: ["host"],
+		selectedPath: "blocked",
+		relayRequired: false,
+		relativeLatency: 1,
+		explanation: "Private host addresses are not reachable across the public Internet."
+	};
+	if (!(leftNat === "symmetric" || rightNat === "symmetric")) return {
+		candidates: ["host", "server-reflexive"],
+		selectedPath: "mapped-direct",
+		relayRequired: false,
+		relativeLatency: 1,
+		explanation: "STUN reveals usable public mappings, so the peers can check a direct path."
+	};
+	if (strategy === "ice" && turnAvailable) return {
+		candidates: [
+			"host",
+			"server-reflexive",
+			"relay"
+		],
+		selectedPath: "relay",
+		relayRequired: true,
+		relativeLatency: 2,
+		explanation: "Direct checks fail, so ICE selects the TURN relay candidate."
+	};
+	return {
+		candidates: ["host", "server-reflexive"],
+		selectedPath: "blocked",
+		relayRequired: true,
+		relativeLatency: 1,
+		explanation: "The changing mapping defeats the direct candidate and no relay is available."
+	};
+}
+
+//#endregion
+export { simulateNatTraversal };

package/dist/networking/protocols.d.mts

@@ -0,0 +1,17 @@
+//#region src/networking/protocols.d.ts
+type DnsCache = "cold" | "warm";
+interface DnsHop {
+  readonly id: string;
+  readonly label: string;
+  readonly answer: string;
+}
+declare function dnsHops(hostname?: string, address?: string): readonly DnsHop[];
+declare const DNS_HOPS: readonly DnsHop[];
+declare function dnsPath(cache: DnsCache, hostname?: string, address?: string): readonly DnsHop[];
+declare function dnsLookupMs(cache: DnsCache, hopMs: number): number;
+type CertificateKind = "trusted" | "wrong-name" | "untrusted";
+declare const TLS_STEPS: readonly ["ClientHello", "ServerHello", "Certificate", "Finished", "Application data"];
+declare function certificateAccepted(kind: CertificateKind): boolean;
+declare function visibleOnWire(step: number, accepted: boolean): string;
+//#endregion
+export { CertificateKind, DNS_HOPS, DnsCache, DnsHop, TLS_STEPS, certificateAccepted, dnsHops, dnsLookupMs, dnsPath, visibleOnWire };

package/dist/networking/protocols.mjs

@@ -0,0 +1,57 @@
+//#region src/networking/protocols.ts
+function dnsHops(hostname = "chat.example", address = "203.0.113.42") {
+	const suffix = hostname.includes(".") ? `.${hostname.split(".").at(-1)}` : hostname;
+	return [
+		{
+			id: "device",
+			label: "Your device",
+			answer: "Ask the recursive resolver"
+		},
+		{
+			id: "resolver",
+			label: "Recursive resolver",
+			answer: "Check cache, then do the lookup"
+		},
+		{
+			id: "root",
+			label: "Root",
+			answer: `Ask the ${suffix} servers`
+		},
+		{
+			id: "tld",
+			label: suffix,
+			answer: `Ask ${hostname}’s authority`
+		},
+		{
+			id: "authority",
+			label: "Authoritative server",
+			answer: address
+		}
+	];
+}
+const DNS_HOPS = dnsHops();
+function dnsPath(cache, hostname, address) {
+	const hops = dnsHops(hostname, address);
+	return cache === "warm" ? hops.slice(0, 2) : hops;
+}
+function dnsLookupMs(cache, hopMs) {
+	return cache === "warm" ? Math.max(1, hopMs) : Math.max(1, hopMs) * 4;
+}
+const TLS_STEPS = [
+	"ClientHello",
+	"ServerHello",
+	"Certificate",
+	"Finished",
+	"Application data"
+];
+function certificateAccepted(kind) {
+	return kind === "trusted";
+}
+function visibleOnWire(step, accepted) {
+	if (step < 2) return "ClientHello and ServerHello";
+	if (!accepted) return "handshake stopped";
+	return step < 4 ? "encrypted handshake bytes" : "encrypted application bytes";
+}
+
+//#endregion
+export { DNS_HOPS, TLS_STEPS, certificateAccepted, dnsHops, dnsLookupMs, dnsPath, visibleOnWire };

package/dist/networking/queue.d.mts

@@ -0,0 +1,12 @@
+//#region src/networking/queue.d.ts
+/** Pure finite-buffer queue mechanics. Rates are packets per second. */
+interface QueueResult {
+  readonly queued: number;
+  readonly dropped: number;
+  readonly delayMs: number;
+  readonly state: "clear" | "building" | "dropping";
+}
+declare function queueAtTime(arrivalPps: number, servicePps: number, bufferPackets: number, elapsedSeconds: number): QueueResult;
+declare function bottleneckQueue(arrivalPps: number, servicePps: number, bufferPackets: number): QueueResult;
+//#endregion
+export { QueueResult, bottleneckQueue, queueAtTime };