@isothrum/editor 0.0.0-stage → 0.1.0

package/src/lib/tool/placement.test.ts

@@ -0,0 +1,79 @@
+import type { NodeChange } from "@xyflow/react";
+import { describe, expect, test } from "vitest";
+import type { LabNode } from "./model";
+import { paletteSpot, placeAppliance, placeMachine, placeSwitch, snapMoves } from "./placement";
+import { PRESETS, type Preset } from "./presets";
+import { autoRouter, lan, machine, switchNode } from "@/test/lab";
+
+const preset = (id: string): Preset => PRESETS.find((p) => p.id === id) ?? PRESETS[0];
+/** The 400 by 300 office LAN at the origin, selected. */
+const office = { ...lan("office"), selected: true };
+const far = { x: 1000, y: 1000 };
+
+test("paletteSpot staggers devices placed from the palette around the view's center", () => {
+  expect(paletteSpot({ x: 500, y: 400 }, [])).toEqual({ x: 444, y: 360 });
+  expect(paletteSpot({ x: 500, y: 400 }, Array.from({ length: 6 }, (_, i) => machine(String(i))))).toEqual({ x: 468, y: 384 });
+});
+
+describe("placeAppliance", () => {
+  test("lands on a LAN's border when placed near it, the rest unselected", () => {
+    const placed = placeAppliance(preset("router"), { x: 330, y: 100 }, false, [office], [office]);
+    expect(placed.map((n) => [n.type, n.selected])).toEqual([
+      ["lan", false],
+      ["machine", true],
+    ]);
+    expect(placed[1].position).toEqual({ x: 340, y: 100 });
+  });
+
+  test("comes with a LAN of its own under it, away from any LAN", () => {
+    const [newLan, , router] = placeAppliance(preset("router"), far, false, [office], [office]);
+    expect(newLan.type === "lan" && newLan.data).toMatchObject({ name: "lan1", cidr: "10.10.2.0/24" });
+    expect(newLan.position.y).toBe(router.position.y + 58);
+  });
+
+  test("centers a dropped router you configure on the point, as a machine would be", () => {
+    const placed = placeAppliance(preset("router-frr"), far, true, [], []);
+    expect(placed.at(-1)?.position).toEqual({ x: 976, y: 1021 });
+  });
+});
+
+test("placeMachine adds the machine selected, the rest unselected", () => {
+  const placed = placeMachine(preset("web"), { x: 5, y: 5 }, [{ ...machine("old"), selected: true }]);
+  expect(placed.map((n) => [n.type !== "note" && n.data.name, n.selected])).toEqual([
+    ["old", false],
+    ["web1", true],
+  ]);
+});
+
+describe("placeSwitch", () => {
+  test("lands on a LAN's border when placed near it", () => {
+    const placed = placeSwitch({ x: 217, y: 293 }, [office], [office]);
+    expect(placed).toHaveLength(2);
+    expect(placed[1].position).toEqual({ x: 47, y: 263 });
+  });
+
+  test("comes with its first VLAN's LAN hanging under it, away from any LAN", () => {
+    const [vlanLan] = placeSwitch(far, [], []);
+    expect(vlanLan).toMatchObject({ type: "lan", width: 600, height: 300, data: { name: "vlan10", cidr: "10.10.10.0/24" } });
+  });
+});
+
+describe("snapMoves", () => {
+  const nodes: LabNode[] = [office, autoRouter("r"), switchNode("sw"), machine("web")];
+  const move = (id: string, position = { x: 330, y: 100 }): NodeChange<LabNode> => ({ type: "position", id, position });
+
+  test("routers and firewalls dragged near a LAN's border land on it", () => {
+    expect(snapMoves([move("r")], nodes, [office])[0]).toEqual(move("r", { x: 340, y: 100 }));
+  });
+
+  test("switches land on it too, by their own size", () => {
+    expect(snapMoves([move("sw", { x: 47, y: 250 })], nodes, [office])[0]).toEqual(move("sw", { x: 47, y: 263 }));
+  });
+
+  test("other machines, and other changes, are left as they are", () => {
+    const changes: NodeChange<LabNode>[] = [move("web"), { type: "select", id: "r", selected: true }];
+    const snapped = snapMoves(changes, nodes, [office]);
+    expect(snapped[0]).toBe(changes[0]);
+    expect(snapped[1]).toBe(changes[1]);
+  });
+});

package/src/lib/tool/placement.ts

@@ -0,0 +1,60 @@
+import type { NodeChange, XYPosition } from "@xyflow/react";
+import { lanBelow, newMachine, newSwitch } from "./create";
+import { snapToLanEdge } from "./geometry";
+import { MACHINE_H, MACHINE_W, ROUTER_H, ROUTER_W, SWITCH_H, SWITCH_W, isAppliance, isRealRouter, isSwitch, sizeOf, unselected, type LabNode, type LanNode } from "./model";
+import type { Preset } from "./presets";
+import { vlanName } from "./vlans";
+
+/** Placing devices: where they land, and what comes with them. */
+
+/** A device placed from the palette (no point given): in the middle of the view, staggered so machines added in a row don't stack exactly. */
+export function paletteSpot(viewCenter: XYPosition, nodes: LabNode[]): XYPosition {
+  const step = (nodes.length % 5) * 24;
+  return { x: viewCenter.x - 56 + step, y: viewCenter.y - 40 + step };
+}
+
+/**
+ * The nodes after placing a router or firewall at `position`: near a LAN's border it lands on
+ * it, as when dragged; away from any LAN it comes with its own LAN under it (it is that LAN's
+ * gateway). `dropped`: placed at a point (a click, a drop), centered there like a machine.
+ */
+export function placeAppliance(preset: Preset, position: XYPosition, dropped: boolean, nodes: LabNode[], lans: LanNode[]): LabNode[] {
+  const real = isRealRouter({ id: "", type: "machine", position, data: { ...preset.data, name: "" } });
+  const size = real ? { w: ROUTER_W, h: ROUTER_H } : { w: MACHINE_W, h: MACHINE_H };
+  const at = dropped ? { x: position.x + MACHINE_W / 2 - size.w / 2, y: position.y + MACHINE_H / 2 - size.h / 2 } : position;
+  const snapped = snapToLanEdge(at, lans, size);
+  const m = { ...newMachine(preset, snapped, nodes), selected: true };
+  if (snapped !== at) return [...unselected(nodes), m];
+  const lan = lanBelow({ x: snapped.x + size.w / 2, y: snapped.y + size.h / 2 }, [...nodes, m]);
+  return [lan, ...unselected(nodes), m];
+}
+
+/** The nodes after placing a machine at `position`, selected. */
+export function placeMachine(preset: Preset, position: XYPosition, nodes: LabNode[]): LabNode[] {
+  return [...unselected(nodes), { ...newMachine(preset, position, nodes), selected: true }];
+}
+
+/**
+ * The nodes after placing a switch at `at`: on a LAN's edge when near one; away from any LAN it
+ * comes with its LAN, its first VLAN, hanging under it.
+ */
+export function placeSwitch(at: XYPosition, nodes: LabNode[], lans: LanNode[]): LabNode[] {
+  const sw = newSwitch(at, nodes);
+  const snapped = snapToLanEdge(sw.position, lans, { w: SWITCH_W, h: SWITCH_H });
+  const placed = { ...sw, position: snapped, selected: true };
+  if (snapped !== sw.position) return [...unselected(nodes), placed];
+  const first = sw.data.vlans[0];
+  const lan = lanBelow({ x: sw.position.x + SWITCH_W / 2, y: sw.position.y + SWITCH_H / 2 }, nodes, { name: vlanName(first.id), cidr: first.cidr }, { w: 600, h: 300 });
+  return [lan, ...unselected(nodes), placed];
+}
+
+/** Routers, firewalls and switches are magnetic: dragged near a LAN's border, they land on it. */
+export function snapMoves(changes: NodeChange<LabNode>[], nodes: LabNode[], lans: LanNode[]): NodeChange<LabNode>[] {
+  return changes.map((c) => {
+    if (c.type !== "position" || !c.position) return c;
+    const n = nodes.find((x) => x.id === c.id);
+    if (n && isAppliance(n)) return { ...c, position: snapToLanEdge(c.position, lans, sizeOf(n)) };
+    if (n && isSwitch(n)) return { ...c, position: snapToLanEdge(c.position, lans, { w: SWITCH_W, h: SWITCH_H }) };
+    return c;
+  });
+}

package/src/lib/tool/ports.test.ts

@@ -0,0 +1,39 @@
+import fc from "fast-check";
+import { describe, expect, test } from "vitest";
+import { PORT_PROTOCOLS, portsText, readPorts, type Service } from "./ports";
+
+describe("readPorts", () => {
+  test("reads each port, with what it speaks when it isn't TCP", () => {
+    expect(readPorts("80, 443/https,53/udp , 22/tcp")).toEqual({
+      services: [{ port: 80 }, { port: 443, protocol: "https" }, { port: 53, protocol: "udp" }, { port: 22 }],
+      bad: [],
+    });
+  });
+
+  test("reports each entry Isoloom couldn't take, and keeps the others", () => {
+    expect(readPorts("80, http, 0, 65536, 80.5, 53/UDP, 25/smtp, 22")).toEqual({
+      services: [{ port: 80 }, { port: 22 }],
+      bad: ["http", "0", "65536", "80.5", "53/UDP", "25/smtp"],
+    });
+  });
+
+  test("an empty field is no ports and no problem", () => {
+    expect(readPorts(" , ")).toEqual({ services: [], bad: [] });
+  });
+});
+
+describe("portsText", () => {
+  test("writes TCP as the number, and the rest with their protocol", () => {
+    expect(portsText([{ port: 80 }, { port: 22, protocol: "tcp" }, { port: 53, protocol: "udp" }])).toBe("80, 22, 53/udp");
+  });
+
+  test("is read back as the same ports", () => {
+    const service: fc.Arbitrary<Service> = fc.record({ port: fc.integer({ min: 1, max: 65535 }), protocol: fc.constantFrom(...PORT_PROTOCOLS) });
+    fc.assert(
+      fc.property(fc.array(service, { maxLength: 6 }), (services) => {
+        const normal = services.map((s) => (s.protocol === "tcp" ? { port: s.port } : s));
+        expect(readPorts(portsText(services))).toEqual({ services: normal, bad: [] });
+      }),
+    );
+  });
+});

package/src/lib/tool/ports.ts

@@ -0,0 +1,48 @@
+/**
+ * A machine's ports field (`80, 443/https, 53/udp`): each entry a port, 1 to 65535, and what it
+ * speaks when it isn't plain TCP: Isoloom's port `protocol`. An entry Isoloom couldn't take is
+ * kept out of the topology and reported (see `canvasIssues`), never guessed.
+ */
+
+/** What a port speaks: TCP (the default), UDP, or TCP that speaks HTTP, HTTPS or TLS. */
+export const PORT_PROTOCOLS = ["tcp", "udp", "http", "https", "tls"] as const;
+type PortProtocol = (typeof PORT_PROTOCOLS)[number];
+
+/** A port as the engine's topology takes it (`protocol` left out for TCP). */
+export interface Service {
+  port: number;
+  protocol?: PortProtocol;
+}
+
+const ENTRY = /^(\d{1,5})(?:\/([a-z]+))?$/;
+
+const isProtocol = (p: string): p is PortProtocol => PORT_PROTOCOLS.some((x) => x === p);
+
+/** One entry as a port, or null when Isoloom couldn't take it. */
+function service(entry: string): Service | null {
+  const m = ENTRY.exec(entry);
+  if (!m) return null;
+  // An entry without its protocol is TCP.
+  const [, digits, protocol = "tcp"] = m;
+  const port = Number(digits);
+  if (port < 1 || port > 65535) return null;
+  if (protocol === "tcp") return { port };
+  return isProtocol(protocol) ? { port, protocol } : null;
+}
+
+/** The ports field read: its ports, and each entry it couldn't read. */
+export function readPorts(text: string): { services: Service[]; bad: string[] } {
+  const services: Service[] = [];
+  const bad: string[] = [];
+  for (const entry of text.split(",").map((e) => e.trim()).filter(Boolean)) {
+    const s = service(entry);
+    if (s) services.push(s);
+    else bad.push(entry);
+  }
+  return { services, bad };
+}
+
+/** Ports as the field writes them: `80, 53/udp`. */
+export function portsText(services: readonly Service[]): string {
+  return services.map((s) => (s.protocol && s.protocol !== "tcp" ? `${String(s.port)}/${s.protocol}` : String(s.port))).join(", ");
+}

package/src/lib/tool/presets.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { PRESETS, deviceFrom, presetForKey, runAs, shortcutOf } from "./presets";
+import { machine } from "@/test/lab";
+
+describe("number keys", () => {
+  test("keys 1 to 9 then 0 pick the first ten devices, in toolbar order", () => {
+    expect(PRESETS.slice(0, 10).map((p) => shortcutOf(p.id))).toEqual(["1", "2", "3", "4", "5", "6", "7", "8", "9", "0"]);
+    expect(presetForKey("1")?.id).toBe("router");
+    expect(presetForKey("0")?.id).toBe(PRESETS[9].id);
+  });
+
+  test("devices after the tenth, unknown devices and other keys have no shortcut", () => {
+    expect(shortcutOf(PRESETS[10].id)).toBeNull();
+    expect(shortcutOf("nope")).toBeNull();
+    expect(presetForKey("a")).toBeUndefined();
+    expect(presetForKey("10")).toBeUndefined();
+  });
+});
+
+describe("deviceFrom", () => {
+  test("saves a machine as a device of mine, named after it, without its fixed addresses", () => {
+    const device = deviceFrom(machine("m", { name: "web2", pins: { office: 20 } }).data);
+    expect(device).toMatchObject({ group: "mine", label: "web2", prefix: "web" });
+    expect(device.id).toMatch(/^my-/);
+    expect(device.data.pins).toBeUndefined();
+    expect("name" in device.data).toBe(false);
+  });
+
+  test("prefixes a device whose name is only digits 'device'", () => {
+    expect(deviceFrom(machine("m", { name: "42" }).data).prefix).toBe("device");
+  });
+});
+
+describe("runAs", () => {
+  test("a VM keeps its OS, Debian 12 by default", () => {
+    expect(runAs(machine("m", { os: "kali@rolling" }).data, "vm")).toEqual({ kind: "vm", os: "kali@rolling" });
+    expect(runAs(machine("m").data, "vm")).toEqual({ kind: "vm", os: "debian@12" });
+  });
+
+  test("a container keeps its image: FRR for a router, Alpine otherwise", () => {
+    expect(runAs(machine("m", { image: "" }).data, "container")).toEqual({ kind: "container", image: "alpine:3.20" });
+    expect(runAs(machine("m", { image: "", icon: "router" }).data, "container")).toEqual({ kind: "container", image: "frrouting/frr:v8.5.2" });
+    expect(runAs(machine("m").data, "container")).toEqual({ kind: "container", image: "nginx:1.27-alpine" });
+  });
+
+  test("an automatic router takes only its kind, and an unknown kind changes nothing", () => {
+    expect(runAs(machine("m").data, "router")).toEqual({ kind: "router" });
+    expect(runAs(machine("m").data, "pod")).toBeNull();
+  });
+});

package/src/lib/tool/presets.ts

@@ -0,0 +1,77 @@
+import { uid, type MachineData } from "./model";
+import { DEFAULT_OS } from "./os";
+
+/** The devices the toolbar places, and the ones saved from the canvas. */
+
+export interface Preset {
+  id: string;
+  /** Toolbar groups: network appliances first, then containers, then VMs, then saved devices. */
+  group: "network" | "container" | "vm" | "mine";
+  /** A saved device's name. The built-in devices are named in the editor's text, by their id. */
+  label?: string;
+  /** Prefix of the generated machine name (`router1`, `router2`...). */
+  prefix: string;
+  data: Omit<MachineData, "name">;
+}
+
+const base = { image: "", os: "", provision: "", ports: "", access: false };
+
+/** A built-in device: `id` in `group`, named `<prefix><n>`, with `data` over the defaults. */
+const preset = (id: string, group: Preset["group"], prefix: string, data: Pick<MachineData, "kind" | "icon"> & Partial<MachineData>): Preset => ({
+  id,
+  group,
+  prefix,
+  data: { ...base, ...data },
+});
+
+export const PRESETS: Preset[] = [
+  preset("router", "network", "router", { kind: "router", icon: "router" }),
+  preset("router-frr", "network", "frr", { kind: "container", icon: "router", image: "frrouting/frr:v8.5.2" }),
+  preset("firewall", "network", "fw", { kind: "container", icon: "shield", image: "alpine:3.20" }),
+  preset("container", "container", "box", { kind: "container", icon: "container", image: "alpine:3.20" }),
+  preset("web", "container", "web", { kind: "container", icon: "server", image: "nginx:1.27-alpine", ports: "80" }),
+  preset("database", "container", "db", { kind: "container", icon: "server", image: "postgres:16-alpine", ports: "5432" }),
+  preset("linux-vm", "vm", "vm", { kind: "vm", icon: "monitor", os: DEFAULT_OS }),
+  preset("ubuntu-vm", "vm", "ubuntu", { kind: "vm", icon: "monitor", os: "ubuntu@24.04" }),
+  preset("kali-vm", "vm", "kali", { kind: "vm", icon: "monitor", os: "kali@rolling" }),
+  preset("windows-vm", "vm", "win", { kind: "vm", icon: "monitor", os: "windows-server@2022" }),
+  preset("workstation", "vm", "user", { kind: "vm", icon: "laptop", os: DEFAULT_OS, access: true }),
+  // Last, so the number keys above keep their devices.
+  preset("cisco-iol", "network", "r", { kind: "container", icon: "router", image: "vrnetlab/cisco_iol:17.12.01", appliance: "cisco-iol" }),
+  preset("cisco-iol-l2", "network", "sw", { kind: "container", icon: "router", image: "vrnetlab/cisco_iol:L2-17.12.01", appliance: "cisco-iol-l2" }),
+  // A Linux desktop with a VNC server (GNS3's desktop appliances): its screen opens from the
+  // desktop app (right-click, Screen). VNC password: vncpassword.
+  preset("desktop", "container", "desk", { kind: "container", icon: "monitor", image: "consol/debian-xfce-vnc:latest" }),
+];
+
+/** Keys 1–9 then 0 pick the devices, in toolbar order. */
+export function shortcutOf(presetId: string): string | null {
+  const i = PRESETS.findIndex((p) => p.id === presetId);
+  return i < 0 || i > 9 ? null : String((i + 1) % 10);
+}
+
+/** The device a number key picks: 1–9 the first nine, 0 the tenth. */
+export function presetForKey(key: string): Preset | undefined {
+  return /^[0-9]$/.test(key) ? PRESETS[(Number(key) + 9) % 10] : undefined;
+}
+
+/** A device from a machine on the canvas: everything but its name and fixed addresses. */
+export function deviceFrom(m: MachineData): Preset {
+  const { name, ...rest } = m;
+  const data: Omit<MachineData, "name"> = { ...rest, pins: undefined };
+  return {
+    id: uid("my"),
+    group: "mine",
+    label: name,
+    prefix: name.replace(/\d+$/, "") || "device",
+    data,
+  };
+}
+
+/** What changes when a machine is set to run as `kind`: a VM keeps its OS (Debian 12 by default), a container its image (FRR for a router, Alpine otherwise). */
+export function runAs(m: MachineData, kind: string): Partial<MachineData> | null {
+  if (kind === "vm") return { kind, os: m.os || DEFAULT_OS };
+  if (kind === "router") return { kind };
+  if (kind === "container") return { kind, image: m.image || (m.icon === "router" ? "frrouting/frr:v8.5.2" : "alpine:3.20") };
+  return null;
+}

package/src/lib/tool/projects-api.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test, vi } from "vitest";
+import { deleteProject, getVersion, listProjects, projectFromLink, saveProject } from "./projects-api";
+
+/** Answers every request with `response`; the calls it gets. */
+function useServer(response: () => Response) {
+  const server = vi.fn<typeof fetch>(() => Promise.resolve(response()));
+  vi.stubGlobal("fetch", server);
+  return server;
+}
+
+const draft = { name: "lab", nodes: [], edges: [] };
+
+describe("the project store", () => {
+  test("lists the user's projects", async () => {
+    const server = useServer(() => Response.json([{ id: "p1", name: "lab", updatedAt: "2026-10-15T00:00:00.000Z" }]));
+    await expect(listProjects()).resolves.toEqual([{ id: "p1", name: "lab", updatedAt: "2026-10-15T00:00:00.000Z" }]);
+    expect(server).toHaveBeenCalledWith("/api/projects", { method: "GET", headers: { "content-type": "application/json" }, body: undefined });
+  });
+
+  test("saves a new project with POST, and over one with PUT", async () => {
+    const server = useServer(() => Response.json({ id: "p1", name: "lab", updatedAt: "" }));
+    await saveProject(null, { draft, isoloomYml: null });
+    await saveProject("p1", { draft, isoloomYml: "x" });
+    expect(server.mock.calls.map(([url, init]) => [url, init?.method, init?.body])).toEqual([
+      ["/api/projects", "POST", JSON.stringify({ draft, isoloomYml: null })],
+      ["/api/projects/p1", "PUT", JSON.stringify({ draft, isoloomYml: "x" })],
+    ]);
+  });
+
+  test("reads an earlier version by its number", async () => {
+    const server = useServer(() => Response.json({ draft }));
+    await expect(getVersion("p1", 3)).resolves.toEqual({ draft });
+    expect(server.mock.calls[0][0]).toBe("/api/projects/p1/versions/3");
+  });
+
+  test("gives nothing for a deletion the server answers with no content", async () => {
+    useServer(() => new Response(null, { status: 204 }));
+    await expect(deleteProject("p1")).resolves.toBeNull();
+  });
+
+  test("fails with the server's reason, or its status when it gives none", async () => {
+    useServer(() => Response.json({ error: "sign in first" }, { status: 401 }));
+    await expect(listProjects()).rejects.toThrow("sign in first");
+    useServer(() => new Response("oops", { status: 500 }));
+    await expect(listProjects()).rejects.toThrow("500");
+  });
+});
+
+describe("projectFromLink", () => {
+  test("reads the project a link names", async () => {
+    useServer(() => Response.json({ id: "p1", name: "lab", draft }));
+    await expect(projectFromLink("p1")).resolves.toEqual({ id: "p1", name: "lab", draft });
+  });
+
+  test("is nothing when the project can't be read", async () => {
+    useServer(() => new Response(null, { status: 404 }));
+    await expect(projectFromLink("p1")).resolves.toBeNull();
+  });
+});

package/src/lib/tool/projects-api.ts

@@ -0,0 +1,47 @@
+import type { Draft } from "./model";
+
+/**
+ * The site's project store (`/api/projects`), for a signed-in user: their projects, each with
+ * its earlier versions. Errors carry the server's message, or the HTTP status.
+ */
+
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  updatedAt: string;
+}
+export interface ProjectVersion {
+  id: number;
+  savedAt: string;
+}
+
+/** The server's reason in an error response (`{ error }`), or the status when it gives none. */
+async function failure(r: Response): Promise<Error> {
+  const body = (await r.json().catch(() => null)) as { error?: unknown } | null;
+  const reason = body?.error;
+  return new Error(typeof reason === "string" ? reason : String(r.status));
+}
+
+async function api<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const r = await fetch(path, { method, headers: { "content-type": "application/json" }, body: body ? JSON.stringify(body) : undefined });
+  if (!r.ok) throw await failure(r);
+  return (r.status === 204 ? null : await r.json()) as T;
+}
+
+export const listProjects = () => api<ProjectSummary[]>("GET", "/api/projects");
+export const getProject = (id: string) => api<{ id: string; name: string; draft: Draft }>("GET", `/api/projects/${id}`);
+export const deleteProject = (id: string) => api("DELETE", `/api/projects/${id}`);
+export const listVersions = (id: string) => api<ProjectVersion[]>(`GET`, `/api/projects/${id}/versions`);
+export const getVersion = (id: string, version: number) => api<{ draft: Draft }>("GET", `/api/projects/${id}/versions/${String(version)}`);
+
+/** Saves the lab as a new project (POST), or as the next version of `id` (PUT). */
+export function saveProject(id: string | null, body: { name?: string; draft: Draft; isoloomYml: string | null }): Promise<ProjectSummary> {
+  if (id) return api<ProjectSummary>("PUT", `/api/projects/${id}`, body);
+  return api<ProjectSummary>("POST", "/api/projects", body);
+}
+
+/** A project by the id in a link (#project=…), or null when it can't be read. */
+export async function projectFromLink(id: string): Promise<{ id: string; name: string; draft: unknown } | null> {
+  const r = await fetch(`/api/projects/${id}`);
+  return r.ok ? ((await r.json()) as { id: string; name: string; draft: unknown }) : null;
+}

package/src/lib/tool/router-ports.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "vitest";
+import { routerPortsOf } from "./router-ports";
+import { autoRouter, cable, lan, machine, realRouter, switchNode } from "@/test/lab";
+import { trunkStripes } from "./vlans";
+
+const office = lan("office");
+const away = { x: 2000, y: 2000 };
+
+describe("a router's cabled ports", () => {
+  const sw1 = switchNode("sw1", {}, { x: 3000, y: 0 });
+  const nodes = [office, sw1, realRouter("frr", away), machine("web", {}, away)];
+  const edges = [
+    cable("c1", "frr", "sw1", { sourceHandle: "eth0", targetHandle: "trunk" }),
+    cable("c2", "frr", "office", { sourceHandle: "eth1" }),
+    cable("c3", "web", "frr", { targetHandle: "eth2" }),
+  ];
+  const addresses = { frr: [["office", "10.10.1.1"], ["vlan10", "10.10.10.1"], ["link-0", "10.0.0.1"]] as [string, string][] };
+  const ports = routerPortsOf(nodes, edges, [office], addresses).frr;
+
+  test("lists each port's network and address, in port order, a LAN blue and a link gray", () => {
+    expect(ports.interfaces.slice(0, 2)).toEqual([
+      { name: "eth1", network: "office", ip: "10.10.1.1", color: "#74c0fc" },
+      { name: "eth2", network: "link-0", ip: "10.0.0.1", color: "#adb5bd" },
+    ]);
+  });
+
+  test("a port on a switch's trunk has one sub-interface per VLAN, named after the switch's LAN", () => {
+    expect(ports.interfaces.slice(2)).toEqual([
+      { name: "sw1.10", network: "vlan10", ip: "10.10.10.1", color: "#2f9e44" },
+      { name: "sw1.20", network: "vlan20", ip: undefined, color: "#1971c2" },
+    ]);
+  });
+
+  test("colors each port by its network, a trunk striped with its VLANs", () => {
+    expect(ports.colors).toEqual({ eth0: trunkStripes(sw1.data.vlans), eth1: "#74c0fc", eth2: "#adb5bd" });
+  });
+});
+
+describe("other routers", () => {
+  test("a Cisco appliance's interfaces are its OS's, in the order of its addresses", () => {
+    const iol = realRouter("r1", away, { appliance: "cisco-iol" });
+    const ports = routerPortsOf([iol], [], [], { r1: [["office", "10.10.1.1"], ["dmz", "10.10.2.1"]] }).r1;
+    expect(ports.interfaces.map((i) => [i.name, i.network])).toEqual([
+      ["Ethernet0/1", "office"],
+      ["Ethernet0/2", "dmz"],
+    ]);
+  });
+
+  test("on a LAN's border, the LAN is on the first port no cable uses", () => {
+    const edge = realRouter("frr", { x: 316, y: 113 });
+    const alone = routerPortsOf([office, edge], [], [office], {}).frr;
+    const cabled = routerPortsOf([office, edge, machine("web", {}, away)], [cable("c", "frr", "web", { sourceHandle: "eth0" })], [office], {}).frr;
+    expect(alone.interfaces.map((i) => [i.name, i.network])).toEqual([["eth0", "office"]]);
+    expect(cabled.interfaces.map((i) => [i.name, i.network])).toEqual([
+      ["eth0", "link-0"],
+      ["eth1", "office"],
+    ]);
+  });
+
+  test("an automatic router has no ports to show", () => {
+    expect(routerPortsOf([autoRouter("r")], [], [], {})).toEqual({});
+  });
+});

package/src/lib/tool/router-ports.ts

@@ -0,0 +1,88 @@
+import { networkOfCable } from "./cables";
+import { lanUnder } from "./geometry";
+import { applianceInterface, isRealRouter, isSwitch, routerPort, type CableEdge, type LabNode, type LanNode, type MachineNode } from "./model";
+import { isTrunkPort, switchLans, trunkInterface, trunkStripes, vlanColor, vlanName, vlanOf } from "./vlans";
+
+/**
+ * A real router's interfaces: each port's color (striped when it is a trunk), and the list of
+ * interfaces with the network and address on each; a trunk port has one sub-interface per VLAN
+ * (eth0.10, eth0.20), as router-on-a-stick.
+ */
+export interface RouterPorts {
+  colors: Partial<Record<string, string>>;
+  interfaces: { name: string; network: string; ip?: string; color: string }[];
+}
+
+/** Each machine's addresses (from the engine), by machine name: [network, IPv4][]. */
+export type Addresses = Partial<Record<string, [string, string][]>>;
+
+interface Wiring {
+  nodes: LabNode[];
+  edges: CableEdge[];
+  lans: LanNode[];
+  /** A network's color: a VLAN's own, a LAN's blue, gray for a point-to-point cable. */
+  colorOf: (net: string) => string;
+  /** A switch's LAN name, by its id. */
+  lanOfSwitch: (id: string) => string;
+}
+
+/** One router's interfaces: its cabled ports, an appliance's own names, the LAN it sits on. */
+function portsOf(w: Wiring, r: MachineNode, ips: [string, string][]): RouterPorts {
+  const ipOn = (net: string) => ips.find(([n]) => n === net)?.[1];
+  const view: RouterPorts = { colors: {}, interfaces: [] };
+  const add = (name: string, net: string) => view.interfaces.push({ name, network: net, ip: ipOn(net), color: w.colorOf(net) });
+  for (const e of w.edges) cabledPort(w, r, e, view, add);
+  // Cisco IOL: Isoloom numbers its interfaces in the order of its networks (Ethernet0/0 is
+  // management), which is the order of its addresses.
+  const kind = r.data.appliance;
+  if (kind) view.interfaces = ips.map(([net, ip], k) => ({ name: applianceInterface(kind, k + 1), network: net, ip, color: w.colorOf(net) }));
+  // On a LAN's edge, the LAN is on the first port no cable uses.
+  const under = lanUnder(r, w.lans);
+  if (under) {
+    let i = 0;
+    while (view.colors[routerPort(i)] && i < 63) i++;
+    add(routerPort(i), under.lan.data.name);
+    view.colors[routerPort(i)] = w.colorOf(under.lan.data.name);
+  }
+  view.interfaces.sort((x, y) => x.name.localeCompare(y.name, undefined, { numeric: true }));
+  return view;
+}
+
+/**
+ * The port cable `e` plugs into on router `r`, if it does: on a switch's trunk, one sub-interface
+ * per VLAN, named as Isoloom names them (after the switch's LAN: `sw1.10`), and the port striped
+ * with their colors; otherwise the cable's network.
+ */
+function cabledPort(w: Wiring, r: MachineNode, e: CableEdge, view: RouterPorts, add: (name: string, net: string) => void): void {
+  const mine = e.source === r.id ? e.sourceHandle : e.target === r.id ? e.targetHandle : null;
+  if (!mine) return;
+  const other = w.nodes.find((n) => n.id === (e.source === r.id ? e.target : e.source));
+  const otherHandle = e.source === r.id ? e.targetHandle : e.sourceHandle;
+  if (other && isSwitch(other) && isTrunkPort(other, otherHandle)) {
+    const trunk = trunkInterface(w.lanOfSwitch(other.id));
+    other.data.vlans.forEach((v) => {
+      add(`${trunk}.${String(v.id)}`, vlanName(v.id));
+    });
+    view.colors[mine] = trunkStripes(other.data.vlans);
+    return;
+  }
+  const net = networkOfCable(e.id, w.nodes, w.edges);
+  if (!net) return;
+  add(mine, net);
+  view.colors[mine] = w.colorOf(net);
+}
+
+/**
+ * Each real router's interfaces, by node id: the network on each port, its address there, and a
+ * color. On a LAN's edge, the LAN is on eth0 (or the first port no cable uses).
+ */
+export function routerPortsOf(nodes: LabNode[], edges: CableEdge[], lans: LanNode[], addresses: Addresses): Record<string, RouterPorts> {
+  const lanNames = new Set(lans.map((l) => l.data.name));
+  const colorOf = (net: string) => {
+    const v = vlanOf(net);
+    if (v !== null) return vlanColor(v);
+    return lanNames.has(net) ? "#74c0fc" : "#adb5bd";
+  };
+  const w: Wiring = { nodes, edges, lans, colorOf, lanOfSwitch: switchLans(nodes, edges) };
+  return Object.fromEntries(nodes.filter(isRealRouter).map((r) => [r.id, portsOf(w, r, addresses[r.data.name] ?? [])]));
+}