@classytic/stage 0.2.0 → 0.4.0

package/dist/networking/models/index.d.mts

@@ -0,0 +1,14 @@
+import { AirtimeResult, Client, ClientShare, HOUSEHOLD, PAYLOAD_BITS, TURN_OVERHEAD_US, rateFromRssi, shareAirtime, signalWord } from "./airtime.mjs";
+import { Blocker, EIRP_DBM, GENERATIONS, Generation, GenerationId, HANDSET_SENSITIVITY_DBM, MAX_PATH_LOSS_DB, TASKS, TERRAIN, Task, Terrain, TerrainSpec, blockedBy, canServe, cellAreaKm2, cellRadiusKm, firstGenerationFor, generationById, pathLossDb, rssiFromMast, towersFor } from "./cellular.mjs";
+import { DEFAULT_PATH, Encapsulation, EncapsulationSegment, HEADERS, Header, LayerKind, NodeKind, OVERHEAD_BYTES, PathNode, WireFrame, decapsulate, encapsulate, frameOn, journey, opensTo, segmentsOf } from "./encapsulation.mjs";
+import { DEFAULT_DRIVE, DRIVE_WINDOW, DROP_AFTER_KM, DriveOptions, DriveResult, DriveSample, HandoverEvent, MarginVerdict, Mast, TWO_MAST_ROAD, drive, judgeMargin } from "./handover.mjs";
+import { DEFAULT_RTO_MS, DROPS, DropSpec, DropWhich, HandshakeOptions, HandshakeResult, Side, TcpSegment, firstResponseMs, handshake } from "./handshake.mjs";
+import { MEDIA, Medium, MediumId, PAIRS, PINOUTS, PinoutCheck, PinoutStandard, SCENARIOS, Scenario, WIRE_INK, WIRE_LABEL, WireColor, cableKind, checkPinout, isSplitPair, isStriped, pairOf, pairPins, ruleOut } from "./media.mjs";
+import { C_KM_S, EARTH_AREA_KM2, EARTH_RADIUS_KM, MU_EARTH, ORBITS, Orbit, centralAngleRad, footprintAreaKm2, footprintRadiusKm, oneWayMs, orbitById, orbitalPeriodMin, passMinutes, roundTripMs, satellitesForCoverage } from "./satellite.mjs";
+import { C, PENETRATION, Penetration, PenetrationSpec, SPECTRUM, SpectrumBand, bandById, decades, humanFrequency, humanLength, logPosition, quarterWaveM, wavelengthM } from "./spectrum.mjs";
+import { FrameResult, MacEntry, SwitchDevice, SwitchEvent, SwitchPort, SwitchState, clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled } from "./switch.mjs";
+import { BroadcastResult, DeliveryResult, Vlan, VlanPort, VlanState, broadcastFrom, domainCount, domainOf, isLive, makeVlanSwitch, sendBetween, setPortVlan, setRouting } from "./vlan.mjs";
+import { Field, OBSERVERS, Observer, ObserverId, Setup, Sighting, TUNNEL_OVERHEAD_BYTES, canReadContents, canSeeDestination, observe, observersFor, surveyOf, usableBytes } from "./vpn.mjs";
+import { ADVICE, Exposure, LISTENERS, Listener, PROTECTIONS, PrivacyVerdict, Protection, ProtectionSpec, Transport, judgePrivacy, linkReadable, whatTheySee } from "./wifi-privacy.mjs";
+import { BANDS, Band, BandSpec, FLOOR_PLANS, FloorPlan, GRADES, Grade, GradeSpec, MATERIALS, MaterialSpec, NOISE_FLOOR_DBM, PATH_LOSS_EXPONENT, Point, Reading, Room, RoomVerdict, Spot, TX_POWER_DBM, Wall, WallMaterial, bestPlacement, coverageGrid, coverageScore, grade, referenceLossDb, roomVerdicts, signalAt, throughputMbps, wallsBetween } from "./wifi.mjs";
+export { ADVICE, AirtimeResult, BANDS, Band, BandSpec, Blocker, BroadcastResult, C, C_KM_S, Client, ClientShare, DEFAULT_DRIVE, DEFAULT_PATH, DEFAULT_RTO_MS, DRIVE_WINDOW, DROPS, DROP_AFTER_KM, DeliveryResult, DriveOptions, DriveResult, DriveSample, DropSpec, DropWhich, EARTH_AREA_KM2, EARTH_RADIUS_KM, EIRP_DBM, Encapsulation, EncapsulationSegment, Exposure, FLOOR_PLANS, Field, FloorPlan, FrameResult, GENERATIONS, GRADES, Generation, GenerationId, Grade, GradeSpec, HANDSET_SENSITIVITY_DBM, HEADERS, HOUSEHOLD, HandoverEvent, HandshakeOptions, HandshakeResult, Header, LISTENERS, LayerKind, Listener, MATERIALS, MAX_PATH_LOSS_DB, MEDIA, MU_EARTH, MacEntry, MarginVerdict, Mast, MaterialSpec, Medium, MediumId, NOISE_FLOOR_DBM, NodeKind, OBSERVERS, ORBITS, OVERHEAD_BYTES, Observer, ObserverId, Orbit, PAIRS, PATH_LOSS_EXPONENT, PAYLOAD_BITS, PENETRATION, PINOUTS, PROTECTIONS, PathNode, Penetration, PenetrationSpec, PinoutCheck, PinoutStandard, Point, PrivacyVerdict, Protection, ProtectionSpec, Reading, Room, RoomVerdict, SCENARIOS, SPECTRUM, Scenario, Setup, Side, Sighting, SpectrumBand, Spot, SwitchDevice, SwitchEvent, SwitchPort, SwitchState, TASKS, TERRAIN, TUNNEL_OVERHEAD_BYTES, TURN_OVERHEAD_US, TWO_MAST_ROAD, TX_POWER_DBM, Task, TcpSegment, Terrain, TerrainSpec, Transport, Vlan, VlanPort, VlanState, WIRE_INK, WIRE_LABEL, Wall, WallMaterial, WireColor, WireFrame, bandById, bestPlacement, blockedBy, broadcastFrom, cableKind, canReadContents, canSeeDestination, canServe, cellAreaKm2, cellRadiusKm, centralAngleRad, checkPinout, clearTable, coverageGrid, coverageScore, decades, decapsulate, domainCount, domainOf, drive, encapsulate, firstGenerationFor, firstResponseMs, footprintAreaKm2, footprintRadiusKm, frameOn, generationById, grade, handshake, humanFrequency, humanLength, isLive, isSplitPair, isStriped, journey, judgeMargin, judgePrivacy, linkReadable, linkUp, logPosition, makeSwitch, makeVlanSwitch, observe, observersFor, oneWayMs, opensTo, orbitById, orbitalPeriodMin, pairOf, pairPins, passMinutes, pathLossDb, quarterWaveM, rateFromRssi, referenceLossDb, roomVerdicts, roundTripMs, rssiFromMast, ruleOut, satellitesForCoverage, segmentsOf, sendBetween, sendFrame, setPortEnabled, setPortVlan, setRouting, shareAirtime, signalAt, signalWord, surveyOf, throughputMbps, towersFor, usableBytes, wallsBetween, wavelengthM, whatTheySee };

package/dist/networking/models/index.mjs

@@ -0,0 +1,15 @@
+import { HOUSEHOLD, PAYLOAD_BITS, TURN_OVERHEAD_US, rateFromRssi, shareAirtime, signalWord } from "./airtime.mjs";
+import { EIRP_DBM, GENERATIONS, HANDSET_SENSITIVITY_DBM, MAX_PATH_LOSS_DB, TASKS, TERRAIN, blockedBy, canServe, cellAreaKm2, cellRadiusKm, firstGenerationFor, generationById, pathLossDb, rssiFromMast, towersFor } from "./cellular.mjs";
+import { DEFAULT_PATH, HEADERS, OVERHEAD_BYTES, decapsulate, encapsulate, frameOn, journey, opensTo, segmentsOf } from "./encapsulation.mjs";
+import { DEFAULT_DRIVE, DRIVE_WINDOW, DROP_AFTER_KM, TWO_MAST_ROAD, drive, judgeMargin } from "./handover.mjs";
+import { DEFAULT_RTO_MS, DROPS, firstResponseMs, handshake } from "./handshake.mjs";
+import { MEDIA, PAIRS, PINOUTS, SCENARIOS, WIRE_INK, WIRE_LABEL, cableKind, checkPinout, isSplitPair, isStriped, pairOf, pairPins, ruleOut } from "./media.mjs";
+import { C_KM_S, EARTH_AREA_KM2, EARTH_RADIUS_KM, MU_EARTH, ORBITS, centralAngleRad, footprintAreaKm2, footprintRadiusKm, oneWayMs, orbitById, orbitalPeriodMin, passMinutes, roundTripMs, satellitesForCoverage } from "./satellite.mjs";
+import { C, PENETRATION, SPECTRUM, bandById, decades, humanFrequency, humanLength, logPosition, quarterWaveM, wavelengthM } from "./spectrum.mjs";
+import { clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled } from "./switch.mjs";
+import { broadcastFrom, domainCount, domainOf, isLive, makeVlanSwitch, sendBetween, setPortVlan, setRouting } from "./vlan.mjs";
+import { OBSERVERS, TUNNEL_OVERHEAD_BYTES, canReadContents, canSeeDestination, observe, observersFor, surveyOf, usableBytes } from "./vpn.mjs";
+import { ADVICE, LISTENERS, PROTECTIONS, judgePrivacy, linkReadable, whatTheySee } from "./wifi-privacy.mjs";
+import { BANDS, FLOOR_PLANS, GRADES, MATERIALS, NOISE_FLOOR_DBM, PATH_LOSS_EXPONENT, TX_POWER_DBM, bestPlacement, coverageGrid, coverageScore, grade, referenceLossDb, roomVerdicts, signalAt, throughputMbps, wallsBetween } from "./wifi.mjs";
+
+export { ADVICE, BANDS, C, C_KM_S, DEFAULT_DRIVE, DEFAULT_PATH, DEFAULT_RTO_MS, DRIVE_WINDOW, DROPS, DROP_AFTER_KM, EARTH_AREA_KM2, EARTH_RADIUS_KM, EIRP_DBM, FLOOR_PLANS, GENERATIONS, GRADES, HANDSET_SENSITIVITY_DBM, HEADERS, HOUSEHOLD, LISTENERS, MATERIALS, MAX_PATH_LOSS_DB, MEDIA, MU_EARTH, NOISE_FLOOR_DBM, OBSERVERS, ORBITS, OVERHEAD_BYTES, PAIRS, PATH_LOSS_EXPONENT, PAYLOAD_BITS, PENETRATION, PINOUTS, PROTECTIONS, SCENARIOS, SPECTRUM, TASKS, TERRAIN, TUNNEL_OVERHEAD_BYTES, TURN_OVERHEAD_US, TWO_MAST_ROAD, TX_POWER_DBM, WIRE_INK, WIRE_LABEL, bandById, bestPlacement, blockedBy, broadcastFrom, cableKind, canReadContents, canSeeDestination, canServe, cellAreaKm2, cellRadiusKm, centralAngleRad, checkPinout, clearTable, coverageGrid, coverageScore, decades, decapsulate, domainCount, domainOf, drive, encapsulate, firstGenerationFor, firstResponseMs, footprintAreaKm2, footprintRadiusKm, frameOn, generationById, grade, handshake, humanFrequency, humanLength, isLive, isSplitPair, isStriped, journey, judgeMargin, judgePrivacy, linkReadable, linkUp, logPosition, makeSwitch, makeVlanSwitch, observe, observersFor, oneWayMs, opensTo, orbitById, orbitalPeriodMin, pairOf, pairPins, passMinutes, pathLossDb, quarterWaveM, rateFromRssi, referenceLossDb, roomVerdicts, roundTripMs, rssiFromMast, ruleOut, satellitesForCoverage, segmentsOf, sendBetween, sendFrame, setPortEnabled, setPortVlan, setRouting, shareAirtime, signalAt, signalWord, surveyOf, throughputMbps, towersFor, usableBytes, wallsBetween, wavelengthM, whatTheySee };

package/dist/networking/models/media.d.mts

@@ -0,0 +1,82 @@
+//#region src/networking/models/media.d.ts
+/**
+ * The physical layer: what the signal actually travels through, and how the eight wires are ordered.
+ *
+ * Two things get memorised without being understood. The first is the T568B colour order, which
+ * students chant and cannot reconstruct. The second is that "the cable" is one thing, when copper,
+ * fibre and radio carry a signal by three different physical mechanisms with three different limits.
+ *
+ * The order is reconstructable once you see the PAIRS. Four twisted pairs go into eight pins, and
+ * the blue pair sits in the middle at 4 and 5 so an RJ45 socket stays compatible with an older
+ * two-wire telephone plug. That single constraint pushes the green pair apart, which is why pin 3
+ * is white-green and pin 6 is green with two other wires between them. It looks arbitrary and is not.
+ */
+type WireColor = "white-orange" | "orange" | "white-green" | "green" | "white-blue" | "blue" | "white-brown" | "brown";
+/**
+ * Real wire colours, so they are fixed rather than themed. A green wire is green in both themes
+ * for the same reason the link LED is green: the colour IS the information, and a student matching
+ * this against a cable in their hand needs it to agree.
+ */
+declare const WIRE_INK: Record<WireColor, string>;
+/** A striped wire is the pale half of its pair. */
+declare const isStriped: (wire: WireColor) => boolean;
+declare const WIRE_LABEL: Record<WireColor, string>;
+type PinoutStandard = "T568A" | "T568B";
+/** Pin 1 to pin 8, left to right with the clip facing away from you. */
+declare const PINOUTS: Record<PinoutStandard, WireColor[]>;
+/** The four twisted pairs, by the colour they are named after. */
+declare const PAIRS: {
+  name: string;
+  wires: [WireColor, WireColor];
+}[];
+/** Which pair a wire belongs to, 0-based, or -1 if the colour is not a pair member. */
+declare const pairOf: (wire: WireColor) => number;
+/** The pin positions (1-based) each pair occupies under a standard. */
+declare function pairPins(standard: PinoutStandard, pairName: string): number[];
+/** True when a pair sits on two pins that are not next to each other. */
+declare const isSplitPair: (standard: PinoutStandard, pairName: string) => boolean;
+interface PinoutCheck {
+  correct: boolean;
+  /** 1-based pins that do not match the standard. */
+  wrong: number[];
+  placed: number;
+}
+/** Compare an attempt against a standard. Empty slots count as not yet placed, not as wrong. */
+declare function checkPinout(attempt: readonly (WireColor | undefined)[], standard: PinoutStandard): PinoutCheck;
+/**
+ * A cable with the same standard at both ends is straight-through; different ends make a crossover.
+ * Modern gear auto-detects, which is worth saying, because it is why crossover cables have
+ * essentially disappeared and why the distinction still appears in every exam.
+ */
+declare const cableKind: (endA: PinoutStandard, endB: PinoutStandard) => "straight-through" | "crossover";
+type MediumId = "copper" | "fibre" | "radio";
+interface Medium {
+  id: MediumId;
+  label: string;
+  /** What physically carries the signal. */
+  carrier: string;
+  /** Practical maximum for one run, in metres. Radio is a typical indoor figure. */
+  maxMetres: number;
+  typicalGbps: number;
+  /** Survives electrical noise from motors, lighting and power cable runs. */
+  emiImmune: boolean;
+  /** Can anyone within range receive the signal without touching anything. */
+  broadcast: boolean;
+  note: string;
+}
+declare const MEDIA: Medium[];
+interface Scenario {
+  id: string;
+  need: string;
+  metres: number;
+  /** True when the run passes heavy electrical machinery. */
+  noisy: boolean;
+  mustMove: boolean;
+  best: MediumId;
+  why: string;
+}
+declare const SCENARIOS: Scenario[];
+/** Is a medium usable for a scenario at all, and if not, why not. */
+declare function ruleOut(medium: Medium, scenario: Scenario): string | null;
+//#endregion
+export { MEDIA, Medium, MediumId, PAIRS, PINOUTS, PinoutCheck, PinoutStandard, SCENARIOS, Scenario, WIRE_INK, WIRE_LABEL, WireColor, cableKind, checkPinout, isSplitPair, isStriped, pairOf, pairPins, ruleOut };

package/dist/networking/models/media.mjs

@@ -0,0 +1,188 @@
+//#region src/networking/models/media.ts
+/**
+* Real wire colours, so they are fixed rather than themed. A green wire is green in both themes
+* for the same reason the link LED is green: the colour IS the information, and a student matching
+* this against a cable in their hand needs it to agree.
+*/
+const WIRE_INK = {
+	"white-orange": "oklch(0.72 0.16 55)",
+	orange: "oklch(0.68 0.19 48)",
+	"white-green": "oklch(0.70 0.15 150)",
+	green: "oklch(0.58 0.17 148)",
+	"white-blue": "oklch(0.70 0.13 250)",
+	blue: "oklch(0.55 0.18 255)",
+	"white-brown": "oklch(0.62 0.07 60)",
+	brown: "oklch(0.45 0.08 55)"
+};
+/** A striped wire is the pale half of its pair. */
+const isStriped = (wire) => wire.startsWith("white-");
+const WIRE_LABEL = {
+	"white-orange": "white / orange",
+	orange: "orange",
+	"white-green": "white / green",
+	green: "green",
+	"white-blue": "white / blue",
+	blue: "blue",
+	"white-brown": "white / brown",
+	brown: "brown"
+};
+/** Pin 1 to pin 8, left to right with the clip facing away from you. */
+const PINOUTS = {
+	T568B: [
+		"white-orange",
+		"orange",
+		"white-green",
+		"blue",
+		"white-blue",
+		"green",
+		"white-brown",
+		"brown"
+	],
+	T568A: [
+		"white-green",
+		"green",
+		"white-orange",
+		"blue",
+		"white-blue",
+		"orange",
+		"white-brown",
+		"brown"
+	]
+};
+/** The four twisted pairs, by the colour they are named after. */
+const PAIRS = [
+	{
+		name: "orange",
+		wires: ["white-orange", "orange"]
+	},
+	{
+		name: "green",
+		wires: ["white-green", "green"]
+	},
+	{
+		name: "blue",
+		wires: ["white-blue", "blue"]
+	},
+	{
+		name: "brown",
+		wires: ["white-brown", "brown"]
+	}
+];
+/** Which pair a wire belongs to, 0-based, or -1 if the colour is not a pair member. */
+const pairOf = (wire) => PAIRS.findIndex((pair) => pair.wires.includes(wire));
+/** The pin positions (1-based) each pair occupies under a standard. */
+function pairPins(standard, pairName) {
+	const order = PINOUTS[standard];
+	const pair = PAIRS.find((item) => item.name === pairName);
+	if (!pair) return [];
+	return order.map((wire, index) => pair.wires.includes(wire) ? index + 1 : 0).filter((pin) => pin > 0);
+}
+/** True when a pair sits on two pins that are not next to each other. */
+const isSplitPair = (standard, pairName) => {
+	const pins = pairPins(standard, pairName);
+	return pins.length === 2 && pins[1] - pins[0] !== 1;
+};
+/** Compare an attempt against a standard. Empty slots count as not yet placed, not as wrong. */
+function checkPinout(attempt, standard) {
+	const target = PINOUTS[standard];
+	const wrong = [];
+	let placed = 0;
+	target.forEach((wire, index) => {
+		const got = attempt[index];
+		if (!got) return;
+		placed++;
+		if (got !== wire) wrong.push(index + 1);
+	});
+	return {
+		correct: placed === 8 && wrong.length === 0,
+		wrong,
+		placed
+	};
+}
+/**
+* A cable with the same standard at both ends is straight-through; different ends make a crossover.
+* Modern gear auto-detects, which is worth saying, because it is why crossover cables have
+* essentially disappeared and why the distinction still appears in every exam.
+*/
+const cableKind = (endA, endB) => endA === endB ? "straight-through" : "crossover";
+const MEDIA = [
+	{
+		id: "copper",
+		label: "Twisted pair copper",
+		carrier: "a changing voltage along a wire",
+		maxMetres: 100,
+		typicalGbps: 1,
+		emiImmune: false,
+		broadcast: false,
+		note: "Cheap, and every device already has the socket. The 100 m limit is the reason wiring closets exist."
+	},
+	{
+		id: "fibre",
+		label: "Optical fibre",
+		carrier: "pulses of light in a glass core",
+		maxMetres: 4e4,
+		typicalGbps: 10,
+		emiImmune: true,
+		broadcast: false,
+		note: "Light carries no current, so it ignores electrical noise entirely and can cross a city."
+	},
+	{
+		id: "radio",
+		label: "Radio (Wi-Fi)",
+		carrier: "radio waves through open air",
+		maxMetres: 40,
+		typicalGbps: 1,
+		emiImmune: false,
+		broadcast: true,
+		note: "No cable at all, and the medium is shared: everyone in range competes for it and can hear it."
+	}
+];
+const SCENARIOS = [
+	{
+		id: "desk",
+		need: "A desktop to the switch in the same room",
+		metres: 15,
+		noisy: false,
+		mustMove: false,
+		best: "copper",
+		why: "Short, fixed and cheap. Copper is already on both ends and there is nothing to gain by paying for anything else."
+	},
+	{
+		id: "buildings",
+		need: "Between two buildings 800 m apart",
+		metres: 800,
+		noisy: false,
+		mustMove: false,
+		best: "fibre",
+		why: "Copper stops working at about 100 m. Distance alone rules it out before any other argument."
+	},
+	{
+		id: "factory",
+		need: "Across a factory floor beside large motors",
+		metres: 60,
+		noisy: true,
+		mustMove: false,
+		best: "fibre",
+		why: "The distance suits copper, but motors throw electrical noise into it. Light carries no current, so the interference cannot reach the signal."
+	},
+	{
+		id: "phone",
+		need: "A phone carried around a café",
+		metres: 20,
+		noisy: false,
+		mustMove: true,
+		best: "radio",
+		why: "Nothing that moves can stay plugged in. That decides it before speed or cost are even considered."
+	}
+];
+/** Is a medium usable for a scenario at all, and if not, why not. */
+function ruleOut(medium, scenario) {
+	if (scenario.mustMove && !scenario.metres) return null;
+	if (scenario.mustMove && medium.id !== "radio") return "a moving device cannot stay plugged into a cable";
+	if (scenario.metres > medium.maxMetres) return `the run is longer than ${medium.maxMetres} m`;
+	if (scenario.noisy && !medium.emiImmune) return "electrical noise from the machinery would corrupt the signal";
+	return null;
+}
+
+//#endregion
+export { MEDIA, PAIRS, PINOUTS, SCENARIOS, WIRE_INK, WIRE_LABEL, cableKind, checkPinout, isSplitPair, isStriped, pairOf, pairPins, ruleOut };

package/dist/networking/models/satellite.d.mts

@@ -0,0 +1,86 @@
+//#region src/networking/models/satellite.d.ts
+/**
+ * Satellite links: the one delay nobody can engineer away.
+ *
+ * Every other limit in this course yields to money. A weak room gets a second access point, a city
+ * gets more masts, a slow band gets refarmed. Distance does not yield to anything, because the signal
+ * travels at the speed of light and that is the end of the discussion.
+ *
+ * A geostationary satellite sits 35,786 km up. The signal has to climb that, come back down, and then
+ * do it again for the reply, so a round trip is roughly half a second before a single byte is
+ * processed. No better modem, no wider band and no amount of capital changes it. That is why
+ * satellite television, which is one-way and buffered, has always worked beautifully, and why a video
+ * call over the same link has always been unbearable.
+ *
+ * It is also the whole reason low orbit was worth the trouble. Flying at 550 km instead cuts the
+ * round trip by a factor of about sixty and brings interactive use back within reach. The price is
+ * paid twice over: a low satellite covers a tiny patch of ground so you need hundreds of them, and it
+ * crosses the sky in minutes, so the link must be handed from one satellite to the next exactly as a
+ * moving phone is handed between masts. Chapters 2 and 3 are the bill for this chapter's fix.
+ */
+/** Speed of light in vacuum, km/s. Every number in this file is a consequence of it. */
+declare const C_KM_S: number;
+/** Mean radius of the Earth, km. */
+declare const EARTH_RADIUS_KM = 6371;
+/** Standard gravitational parameter of the Earth, km³/s². */
+declare const MU_EARTH = 398600.4418;
+interface Orbit {
+  id: string;
+  label: string;
+  altitudeKm: number;
+  /** Lowest angle above the horizon at which a ground terminal can still work, in degrees. */
+  minElevationDeg: number;
+  use: string;
+  note: string;
+}
+declare const ORBITS: Orbit[];
+/**
+ * Round trip in ms for a request and its reply, from propagation alone.
+ *
+ * Four times the altitude: up, down, up and down again. Deliberately propagation only, with nothing
+ * added for the modem, the gateway or the server. A learner should see the number that cannot be
+ * argued with first, and meet the extra overheads afterwards as things engineers can actually attack.
+ */
+declare const roundTripMs: (altitudeKm: number) => number;
+/** One hop, ground to satellite to ground, in ms. What a one-way broadcast costs. */
+declare const oneWayMs: (altitudeKm: number) => number;
+/**
+ * Orbital period in minutes, from Kepler's third law.
+ *
+ * Worth computing rather than quoting, because it explains the two things about geostationary orbit
+ * that look like coincidences. It sits at exactly the altitude where one orbit takes a day, which is
+ * why it appears motionless, which is why a dish never has to move. There is only one such altitude,
+ * which is why that orbit is crowded and regulated.
+ */
+declare function orbitalPeriodMin(altitudeKm: number): number;
+/**
+ * Half-angle of the ground patch a satellite can serve, in radians, measured from the Earth's centre.
+ *
+ *   cos(θ + ε) = (R / (R + h)) · cos(ε)
+ *
+ * The minimum elevation matters as much as the altitude: a terminal near the horizon is looking
+ * through far more atmosphere and past far more rooftops, so constellations set a floor and give up
+ * the rest of the geometric footprint to get a link that works.
+ */
+declare function centralAngleRad(altitudeKm: number, minElevationDeg: number): number;
+/** Radius of that patch measured along the ground, in km. */
+declare const footprintRadiusKm: (altitudeKm: number, minElevationDeg: number) => number;
+/** Area of the patch, in km², as a spherical cap rather than a flat disc. */
+declare function footprintAreaKm2(altitudeKm: number, minElevationDeg: number): number;
+declare const EARTH_AREA_KM2: number;
+/**
+ * Satellites needed to see the whole planet at once, as a geometric floor.
+ *
+ * This is the number of caps required to cover a sphere, and it is a FLOOR rather than a fleet size.
+ * Real constellations fly several times more, because caps must overlap for a link to survive a
+ * satellite setting, because the orbits have to form a workable pattern, and above all because
+ * capacity is shared: one satellite over a city serves everyone under it at once. Starlink flies
+ * thousands where the geometry asks for a few hundred, and almost all of that difference is capacity
+ * rather than coverage. Saying so is the difference between a model and a claim.
+ */
+declare function satellitesForCoverage(altitudeKm: number, minElevationDeg: number): number;
+/** How long one satellite stays in view of a fixed point, in minutes. Zero when it never sets. */
+declare function passMinutes(altitudeKm: number, minElevationDeg: number): number;
+declare const orbitById: (id: string) => Orbit;
+//#endregion
+export { C_KM_S, EARTH_AREA_KM2, EARTH_RADIUS_KM, MU_EARTH, ORBITS, Orbit, centralAngleRad, footprintAreaKm2, footprintRadiusKm, oneWayMs, orbitById, orbitalPeriodMin, passMinutes, roundTripMs, satellitesForCoverage };

package/dist/networking/models/satellite.mjs

@@ -0,0 +1,121 @@
+import { SPEED_OF_LIGHT } from "../../core/constants.mjs";
+
+//#region src/networking/models/satellite.ts
+/**
+* Satellite links: the one delay nobody can engineer away.
+*
+* Every other limit in this course yields to money. A weak room gets a second access point, a city
+* gets more masts, a slow band gets refarmed. Distance does not yield to anything, because the signal
+* travels at the speed of light and that is the end of the discussion.
+*
+* A geostationary satellite sits 35,786 km up. The signal has to climb that, come back down, and then
+* do it again for the reply, so a round trip is roughly half a second before a single byte is
+* processed. No better modem, no wider band and no amount of capital changes it. That is why
+* satellite television, which is one-way and buffered, has always worked beautifully, and why a video
+* call over the same link has always been unbearable.
+*
+* It is also the whole reason low orbit was worth the trouble. Flying at 550 km instead cuts the
+* round trip by a factor of about sixty and brings interactive use back within reach. The price is
+* paid twice over: a low satellite covers a tiny patch of ground so you need hundreds of them, and it
+* crosses the sky in minutes, so the link must be handed from one satellite to the next exactly as a
+* moving phone is handed between masts. Chapters 2 and 3 are the bill for this chapter's fix.
+*/
+/** Speed of light in vacuum, km/s. Every number in this file is a consequence of it. */
+const C_KM_S = SPEED_OF_LIGHT / 1e3;
+/** Mean radius of the Earth, km. */
+const EARTH_RADIUS_KM = 6371;
+/** Standard gravitational parameter of the Earth, km³/s². */
+const MU_EARTH = 398600.4418;
+const ORBITS = [
+	{
+		id: "leo",
+		label: "Low orbit",
+		altitudeKm: 550,
+		minElevationDeg: 25,
+		use: "Starlink and similar constellations",
+		note: "Low enough that the round trip stops being the problem. It sees so little ground that hundreds are needed, and it crosses the sky in minutes, so the link is handed on constantly."
+	},
+	{
+		id: "meo",
+		label: "Medium orbit",
+		altitudeKm: 8063,
+		minElevationDeg: 10,
+		use: "O3b, and the navigation constellations a little higher",
+		note: "A working compromise. Far fewer satellites than low orbit and a round trip a business can live with, though still too long for anything reflex-driven."
+	},
+	{
+		id: "geo",
+		label: "Geostationary",
+		altitudeKm: 35786,
+		minElevationDeg: 10,
+		use: "Television broadcast, and the satellite internet that came before Starlink",
+		note: "It orbits once per day, so it hangs over the same spot and a dish can be aimed once and bolted down. Three of them see almost the whole planet. The half-second is the price of all of that."
+	}
+];
+/**
+* Round trip in ms for a request and its reply, from propagation alone.
+*
+* Four times the altitude: up, down, up and down again. Deliberately propagation only, with nothing
+* added for the modem, the gateway or the server. A learner should see the number that cannot be
+* argued with first, and meet the extra overheads afterwards as things engineers can actually attack.
+*/
+const roundTripMs = (altitudeKm) => 4 * altitudeKm / C_KM_S * 1e3;
+/** One hop, ground to satellite to ground, in ms. What a one-way broadcast costs. */
+const oneWayMs = (altitudeKm) => 2 * altitudeKm / C_KM_S * 1e3;
+/**
+* Orbital period in minutes, from Kepler's third law.
+*
+* Worth computing rather than quoting, because it explains the two things about geostationary orbit
+* that look like coincidences. It sits at exactly the altitude where one orbit takes a day, which is
+* why it appears motionless, which is why a dish never has to move. There is only one such altitude,
+* which is why that orbit is crowded and regulated.
+*/
+function orbitalPeriodMin(altitudeKm) {
+	const a = EARTH_RADIUS_KM + altitudeKm;
+	return 2 * Math.PI * Math.sqrt(a * a * a / MU_EARTH) / 60;
+}
+/**
+* Half-angle of the ground patch a satellite can serve, in radians, measured from the Earth's centre.
+*
+*   cos(θ + ε) = (R / (R + h)) · cos(ε)
+*
+* The minimum elevation matters as much as the altitude: a terminal near the horizon is looking
+* through far more atmosphere and past far more rooftops, so constellations set a floor and give up
+* the rest of the geometric footprint to get a link that works.
+*/
+function centralAngleRad(altitudeKm, minElevationDeg) {
+	const epsilon = minElevationDeg * Math.PI / 180;
+	const ratio = EARTH_RADIUS_KM / (EARTH_RADIUS_KM + altitudeKm) * Math.cos(epsilon);
+	return Math.acos(Math.min(1, Math.max(-1, ratio))) - epsilon;
+}
+/** Radius of that patch measured along the ground, in km. */
+const footprintRadiusKm = (altitudeKm, minElevationDeg) => EARTH_RADIUS_KM * centralAngleRad(altitudeKm, minElevationDeg);
+/** Area of the patch, in km², as a spherical cap rather than a flat disc. */
+function footprintAreaKm2(altitudeKm, minElevationDeg) {
+	const theta = centralAngleRad(altitudeKm, minElevationDeg);
+	return 2 * Math.PI * EARTH_RADIUS_KM * EARTH_RADIUS_KM * (1 - Math.cos(theta));
+}
+const EARTH_AREA_KM2 = 4 * Math.PI * EARTH_RADIUS_KM * EARTH_RADIUS_KM;
+/**
+* Satellites needed to see the whole planet at once, as a geometric floor.
+*
+* This is the number of caps required to cover a sphere, and it is a FLOOR rather than a fleet size.
+* Real constellations fly several times more, because caps must overlap for a link to survive a
+* satellite setting, because the orbits have to form a workable pattern, and above all because
+* capacity is shared: one satellite over a city serves everyone under it at once. Starlink flies
+* thousands where the geometry asks for a few hundred, and almost all of that difference is capacity
+* rather than coverage. Saying so is the difference between a model and a claim.
+*/
+function satellitesForCoverage(altitudeKm, minElevationDeg) {
+	return Math.max(1, Math.ceil(EARTH_AREA_KM2 / footprintAreaKm2(altitudeKm, minElevationDeg)));
+}
+/** How long one satellite stays in view of a fixed point, in minutes. Zero when it never sets. */
+function passMinutes(altitudeKm, minElevationDeg) {
+	const period = orbitalPeriodMin(altitudeKm);
+	if (period >= 1400) return Infinity;
+	return period * (2 * centralAngleRad(altitudeKm, minElevationDeg)) / (2 * Math.PI);
+}
+const orbitById = (id) => ORBITS.find((orbit) => orbit.id === id) ?? ORBITS[0];
+
+//#endregion
+export { C_KM_S, EARTH_AREA_KM2, EARTH_RADIUS_KM, MU_EARTH, ORBITS, centralAngleRad, footprintAreaKm2, footprintRadiusKm, oneWayMs, orbitById, orbitalPeriodMin, passMinutes, roundTripMs, satellitesForCoverage };

package/dist/networking/models/spectrum.d.mts

@@ -0,0 +1,83 @@
+//#region src/networking/models/spectrum.d.ts
+/**
+ * The invisible spectrum: why a remote control needs to be pointed and Wi-Fi does not.
+ *
+ * Radio, microwave, infrared and light are one thing, and are almost always taught as four. A
+ * student learns that Wi-Fi is "radio waves", that a remote uses "infrared", that 5G is "faster",
+ * and nothing connects those three facts, so none of them predicts anything. They are the same
+ * phenomenon at different frequencies, and almost every practical difference between them follows
+ * from one number.
+ *
+ * The number is the wavelength, and the reason it decides everything is SIZE. A wave interacts with
+ * an object according to how the object compares to its own wavelength. An FM broadcast is three
+ * metres long and treats a person as though they were not there. Wi-Fi is twelve centimetres and
+ * treats a brick wall as an obstacle it loses some energy to. A 5G millimetre wave is a centimetre
+ * and is stopped by a hand, a leaf, or coated window glass. Infrared is a thousandth of a
+ * millimetre and is stopped by anything at all, which is why the remote has to see the television.
+ *
+ * So this table exists to be sorted and compared rather than recited. The derived quantities are
+ * computed from the frequency instead of stored, because the whole claim of the lesson is that they
+ * FOLLOW from it: change the frequency and the wavelength, the antenna and the ability to cross a
+ * wall all move together, and a learner who has watched them move together owns the relationship.
+ *
+ * It also settles the single most common misconception about Wi-Fi in one line. A microwave oven
+ * runs at 2.45 GHz and a Wi-Fi router runs at 2.437 GHz. They are the same band. The oven is not
+ * interfering with the network by coincidence or by poor design: it is shouting on the channel.
+ */
+declare const C = 299792458;
+/** How well a band crosses ordinary building materials. */
+type Penetration = "through-anything" | "through-walls" | "through-one-wall" | "blocked" | "line-of-sight";
+interface SpectrumBand {
+  id: string;
+  label: string;
+  /** Centre frequency in hertz. Everything else on this record is derived from it. */
+  hz: number;
+  /** What this band is used for, in the words a learner would meet it by. */
+  use: string;
+  penetration: Penetration;
+  /** A familiar object of roughly the same size as one wavelength. */
+  compare: string;
+  /** That object's real size in metres, so the figure can draw the two lengths to one scale. */
+  compareM: number;
+  note: string;
+}
+/**
+ * Real centre frequencies, in the order a learner should meet them: longest wave first, because the
+ * story is what happens as the wave gets shorter.
+ */
+declare const SPECTRUM: SpectrumBand[];
+/** Wavelength in metres. Everything visual about a band comes from this one division. */
+declare const wavelengthM: (hz: number) => number;
+/**
+ * Quarter-wave antenna length in metres, the classic first-order rule.
+ *
+ * It is worth computing rather than asserting, because it explains hardware a learner has already
+ * seen and never questioned: the metre-long whip on an old car radio, the few centimetres inside a
+ * phone, and the fact that a 5G millimetre-wave antenna is small enough to put dozens on one chip.
+ */
+declare const quarterWaveM: (hz: number) => number;
+/** A length in the largest unit that keeps it readable, which is how a person would say it. */
+declare function humanLength(metres: number): string;
+/** A frequency in the unit it is normally quoted in. */
+declare function humanFrequency(hz: number): string;
+interface PenetrationSpec {
+  id: Penetration;
+  label: string;
+  /** What actually stops it, said as a thing rather than as a category. */
+  stoppedBy: string;
+}
+declare const PENETRATION: Record<Penetration, PenetrationSpec>;
+/**
+ * Position on a logarithmic axis from 0 (left) to 1 (right).
+ *
+ * The axis has to be logarithmic because the table spans nine orders of magnitude: on a linear
+ * scale every radio band would pile into the first pixel and the lesson would be invisible. Worth
+ * saying to a learner rather than hiding, since "the axis multiplies instead of adding" is itself
+ * one of the more useful things this figure can teach.
+ */
+declare function logPosition(hz: number, fromHz?: number, toHz?: number): number;
+/** The decade ticks an axis should carry between two frequencies. */
+declare function decades(fromHz?: number, toHz?: number): number[];
+declare const bandById: (id: string) => SpectrumBand;
+//#endregion
+export { C, PENETRATION, Penetration, PenetrationSpec, SPECTRUM, SpectrumBand, bandById, decades, humanFrequency, humanLength, logPosition, quarterWaveM, wavelengthM };