@isothrum/editor 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "vitest";
+import { draftFromTopology, type Topology } from "./layout";
+import { nodeName, type LabNode } from "./model";
+import { byId, compile } from "@/test/lab";
+
+/** Two LANs, a server and a workstation in the first, an automatic router between them, two machines on none. */
+const topology: Topology = {
+  name: "Lab One",
+  nodes: {
+    web: { kind: { container: { image: "nginx" } }, services: [{ port: 80 }, { port: 443, protocol: "https" }], networks: { lan1: 5, lan2: null } },
+    r1: { kind: { router: {} }, networks: { lan1: null, lan2: null } },
+    pc: { kind: { vm: { os: "debian@12", provision: ["a", "b"] } }, access: true, networks: { lan1: null } },
+    loose: { kind: { container: { image: "alpine", idle: true } } },
+    r2: { kind: { router: {} } },
+  },
+  networks: {
+    lan1: { cidr: "10.10.1.0/24", tc: { delay: "40ms", jitter: "5ms", loss: 1, rate: "10mbit" } },
+    lan2: { cidr: "10.10.2.0/24", internet: false },
+  },
+  links: [
+    { a: { node: "web", port: "" }, b: { node: "pc", port: "eth5" }, tc: { rate: "1gbit", loss: 2 } },
+    { a: { node: "ghost", port: "" }, b: { node: "pc", port: "" } },
+  ],
+};
+const { draft } = draftFromTopology(topology);
+/** The node named `name`. */
+const named = (name: string): LabNode => {
+  const n = draft.nodes.find((x) => x.type !== "note" && x.data.name === name);
+  if (!n) throw new Error(`no node ${name}`);
+  return n;
+};
+/** The cables from the node named `from` to LANs, as [handle, the LAN's name, port]. */
+const cablesFrom = (from: string) =>
+  draft.edges.filter((e) => e.source === named(from).id && byId(draft.nodes, e.target).type === "lan").map((e) => [e.sourceHandle, nodeName(byId(draft.nodes, e.target)), e.data?.aPort]);
+
+describe("draftFromTopology", () => {
+  test("names the lab after the topology, cleaned, or 'lab'", () => {
+    expect(draft.name).toBe("labone");
+    expect(draftFromTopology({ name: "", nodes: {} }).draft).toEqual({ name: "lab", nodes: [], edges: [] });
+  });
+
+  test("lays the LANs out side by side, each sized for the machines inside", () => {
+    const lans = draft.nodes.filter((n) => n.type === "lan");
+    expect(lans.map((l) => [l.data.name, l.position.x, l.width, l.height])).toEqual([
+      ["lan1", 0, 420, 265],
+      ["lan2", 580, 340, 265],
+    ]);
+  });
+
+  test("keeps each LAN's block, its internet (on by default) and its conditions", () => {
+    expect(named("lan1").data).toEqual({ name: "lan1", cidr: "10.10.1.0/24", internet: true, tc: { delay: 40, jitter: 5, loss: 1, rate: 10 } });
+    expect(named("lan2").data).toMatchObject({ internet: false, tc: undefined });
+  });
+
+  test("places machines in a grid inside their first LAN", () => {
+    expect([named("web").position, named("pc").position]).toEqual([
+      { x: 40, y: 70 },
+      { x: 210, y: 70 },
+    ]);
+  });
+
+  test("puts an automatic router under the LANs it joins, and machines on no LAN in a row below", () => {
+    expect([named("r1").position, named("loose").position, named("r2").position]).toEqual([
+      { x: 420, y: 375 },
+      { x: 0, y: 610 },
+      { x: 170, y: 610 },
+    ]);
+  });
+
+  test("turns each node into a machine: its kind, icon, image or OS, services and fixed addresses", () => {
+    expect(named("web").data).toMatchObject({ kind: "container", icon: "server", image: "nginx", ports: "80, 443/https", pins: { lan1: 5 } });
+    expect(named("pc").data).toMatchObject({ kind: "vm", icon: "laptop", os: "debian@12", provision: "a\nb", access: true });
+    expect(named("loose").data).toMatchObject({ kind: "container", icon: "container", idle: true });
+    expect(named("r1").data).toMatchObject({ kind: "router", icon: "router" });
+  });
+
+  test("cables a router to each LAN it joins, and a machine to the LANs it doesn't sit in", () => {
+    expect(cablesFrom("r1")).toEqual([
+      ["port", "lan1", "eth0"],
+      ["port", "lan2", "eth1"],
+    ]);
+    expect(cablesFrom("web")).toEqual([["bottom", "lan2", "eth0"]]);
+  });
+
+  test("cables the links between known machines, a port left empty taking the next free one", () => {
+    const link = draft.edges.find((e) => e.target === named("pc").id);
+    expect(link?.data).toEqual({ aPort: "eth1", bPort: "eth5", tc: { loss: 2, rate: 1000 } });
+    expect(draft.edges).toHaveLength(4);
+  });
+
+  test("reads back as the same machines on the same networks", () => {
+    const t = compile(draft.nodes, draft.edges);
+    expect(Object.fromEntries(Object.entries(t.nodes).map(([n, m]) => [n, m.networks]))).toEqual({
+      web: { lan1: 5, lan2: null },
+      pc: { lan1: null },
+      r1: { lan1: null, lan2: null },
+      loose: {},
+      r2: {},
+    });
+  });
+});
+
+describe("draftFromTopology's link conditions", () => {
+  test("keeps a delay written in microseconds or seconds", () => {
+    const slow: Topology = { name: "slow", nodes: {}, networks: { far: { cidr: "10.10.9.0/24", tc: { delay: "1s", jitter: "500us" } } } };
+    expect(draftFromTopology(slow).draft.nodes[0].data).toMatchObject({ tc: { delay: 1000, jitter: 0.5 } });
+  });
+
+  test("reports each condition it can't read, where it is, and draws the rest", () => {
+    const odd: Topology = {
+      name: "odd",
+      nodes: { a: { kind: { container: { image: "alpine" } } }, b: { kind: { container: { image: "alpine" } } } },
+      networks: { far: { cidr: "10.10.9.0/24", tc: { delay: "fast", loss: 1 } } },
+      links: [{ a: { node: "a", port: "eth0" }, b: { node: "b", port: "eth0" }, tc: { rate: "lots" } }],
+    };
+    const { draft: laid, problems } = draftFromTopology(odd);
+    expect(problems).toEqual([
+      "networks.far.tc.delay: `fast` isn't a time like 40ms, 500us or 1s; the drawing leaves it out",
+      "links[0].tc.rate: `lots` isn't a rate like 10mbit or 512kbit; the drawing leaves it out",
+    ]);
+    expect(laid.nodes.find((n) => n.type === "lan")?.data).toMatchObject({ tc: { loss: 1 } });
+    expect(laid.edges[0].data?.tc).toBeUndefined();
+  });
+
+  test("has no problems with a topology whose conditions it all reads", () => {
+    expect(draftFromTopology(topology).problems).toEqual([]);
+  });
+});

package/src/lib/tool/layout.ts

@@ -0,0 +1,229 @@
+/**
+ * A lab given as the engine's topology (what an assistant writes through the MCP server), laid
+ * out on the canvas: LANs side by side with their machines in a grid inside, automatic routers
+ * under the LANs they join (cabled to each), the machines on no LAN in a row below, and the
+ * cables between machines. The inverse of `toTopology`, for labs nobody drew.
+ */
+
+import { migrateEdges, nextPort } from "./cables";
+import { conditionsOf, tcProblemText, type Tc } from "./conditions";
+import { portsText, type Service } from "./ports";
+import {
+  LAN_BEHAVIOR,
+  MACHINE_W,
+  centerOf,
+  cleanName,
+  uid,
+  type CableEdge,
+  type Draft,
+  type IconId,
+  type LabNode,
+  type LanNode,
+  type LinkConditions,
+  type MachineData,
+  type MachineNode,
+  type Side,
+} from "./model";
+
+type TopologyNode = {
+  kind: { container?: { image: string; idle?: boolean }; vm?: { os: string; provision?: string[] }; router?: object };
+  access?: boolean;
+  services?: Service[];
+  networks?: Record<string, number | null>;
+};
+
+export interface Topology {
+  name: string;
+  nodes: Record<string, TopologyNode>;
+  networks?: Record<string, { cidr: string; internet?: boolean; tc?: Tc }>;
+  links?: { a: { node: string; port: string }; b: { node: string; port: string }; tc?: Tc }[];
+}
+
+const COLS = 3;
+const CELL_W = 170;
+const CELL_H = 175;
+const GAP = 160;
+
+function icon(kind: TopologyNode["kind"], access: boolean): IconId {
+  if (kind.router) return "router";
+  if (kind.vm) return access ? "laptop" : "monitor";
+  const image = kind.container?.image ?? "";
+  return /nginx|httpd|apache|caddy|traefik|postgres|mysql|mariadb|redis|mongo|bind|dnsmasq|vsftpd|postfix/.test(image) ? "server" : "container";
+}
+
+/** What the layout builds: the nodes and cables so far, the LANs and machines by topology name,
+ * and what in the topology the drawing can't keep. */
+interface Layout {
+  topo: Topology;
+  nodes: LabNode[];
+  edges: CableEdge[];
+  lans: Map<string, LanNode>;
+  machines: Map<string, MachineNode>;
+  problems: string[];
+}
+
+/** A topology laid out: the draft, and each value in the topology the drawing leaves out. */
+export interface LaidOut {
+  draft: Draft;
+  problems: string[];
+}
+
+/** The editor's numbers for the `tc` at path `at`, each value it can't read kept as a problem. */
+function conditionsAt(layout: Layout, at: string, tc: Tc | undefined): LinkConditions | undefined {
+  const { conditions, problems } = conditionsOf(tc);
+  layout.problems.push(...problems.map((p) => tcProblemText(at, p)));
+  return conditions;
+}
+
+/** The LANs among a machine's networks. */
+const lansOf = (layout: Layout, n: TopologyNode) => Object.keys(n.networks ?? {}).filter((name) => layout.lans.has(name));
+
+/** Each LAN's machines: those that sit in it (their first LAN); routers join theirs by cables. */
+function residents(topo: Topology): Map<string, string[]> {
+  const lanNames = Object.keys(topo.networks ?? {});
+  const inside = new Map<string, string[]>(lanNames.map((l) => [l, []]));
+  for (const [name, n] of Object.entries(topo.nodes)) {
+    const first = Object.keys(n.networks ?? {}).find((l) => lanNames.includes(l));
+    if (!n.kind.router && first) inside.get(first)?.push(name);
+  }
+  return inside;
+}
+
+/** The LANs, in a row, each sized for the grid of machines inside it. */
+function placeLans(layout: Layout, inside: Map<string, string[]>): void {
+  let x = 0;
+  for (const [name, net] of Object.entries(layout.topo.networks ?? {})) {
+    const count = Math.max(1, inside.get(name)?.length ?? 0);
+    const w = Math.max(340, Math.min(COLS, count) * CELL_W + 80);
+    const h = Math.max(240, Math.ceil(count / COLS) * CELL_H + 90);
+    const lan: LanNode = {
+      ...LAN_BEHAVIOR,
+      id: uid("l"),
+      type: "lan",
+      position: { x, y: 0 },
+      width: w,
+      height: h,
+      data: { name: cleanName(name), cidr: net.cidr, internet: net.internet ?? true, tc: conditionsAt(layout, `networks.${name}.tc`, net.tc) },
+    };
+    layout.lans.set(name, lan);
+    layout.nodes.push(lan);
+    x += w + GAP;
+  }
+}
+
+/** A machine from its topology entry, at `position`. */
+function addMachine(layout: Layout, name: string, n: TopologyNode, position: { x: number; y: number }): void {
+  const access = !!n.access;
+  const data: MachineData = {
+    name: cleanName(name),
+    kind: n.kind.router ? "router" : n.kind.vm ? "vm" : "container",
+    icon: icon(n.kind, access),
+    image: n.kind.container?.image ?? "",
+    os: n.kind.vm?.os ?? "",
+    provision: (n.kind.vm?.provision ?? []).join("\n"),
+    ports: portsText(n.services ?? []),
+    access,
+    ...(n.kind.container ? { idle: n.kind.container.idle } : {}),
+  };
+  const pins = Object.fromEntries(Object.entries(n.networks ?? {}).filter((e): e is [string, number] => typeof e[1] === "number"));
+  if (Object.keys(pins).length) data.pins = pins;
+  const m: MachineNode = { id: uid("m"), type: "machine", position, data };
+  layout.machines.set(name, m);
+  layout.nodes.push(m);
+}
+
+/** Machines inside their first LAN, in a grid; routers under the LANs they join; the rest below. */
+function placeMachines(layout: Layout, inside: Map<string, string[]>): void {
+  for (const [lanName, names] of inside) {
+    const lan = layout.lans.get(lanName);
+    if (!lan) continue;
+    names.forEach((name, i) => {
+      const at = { x: lan.position.x + 40 + (i % COLS) * CELL_W, y: lan.position.y + 70 + Math.floor(i / COLS) * CELL_H };
+      addMachine(layout, name, layout.topo.nodes[name], at);
+    });
+  }
+  const lanBottom = Math.max(0, ...[...layout.lans.values()].map((l) => l.height ?? 0));
+  let routerX = 0;
+  let looseX = 0;
+  for (const [name, n] of Object.entries(layout.topo.nodes)) {
+    if (layout.machines.has(name)) continue;
+    const joined = lansOf(layout, n).flatMap((l) => layout.lans.get(l) ?? []);
+    if (n.kind.router && joined.length) {
+      const center = joined.reduce((s, l) => s + l.position.x + (l.width ?? 0) / 2, 0) / joined.length;
+      routerX = Math.max(routerX, center - MACHINE_W / 2);
+      addMachine(layout, name, n, { x: routerX, y: lanBottom + 110 });
+      routerX += MACHINE_W + 60;
+    } else {
+      addMachine(layout, name, n, { x: looseX, y: lanBottom + 110 + CELL_H + 60 });
+      looseX += CELL_W;
+    }
+  }
+}
+
+/** The side of a LAN that faces a machine, relative to the LAN's own proportions. */
+function side(lan: LanNode, m: MachineNode): Side {
+  const d = { x: centerOf(m).x - centerOf(lan).x, y: centerOf(m).y - centerOf(lan).y };
+  if (Math.abs(d.x) / (lan.width ?? 1) > Math.abs(d.y) / (lan.height ?? 1)) return d.x < 0 ? "left" : "right";
+  return d.y < 0 ? "top" : "bottom";
+}
+
+/** Where a cable leaves a machine: an appliance's port, or the top or bottom facing the other end. */
+function handle(m: MachineNode, other: LabNode): string {
+  if (m.data.icon === "router" || m.data.icon === "shield") return "port";
+  return centerOf(other).y < centerOf(m).y ? "top" : "bottom";
+}
+
+/** A cable from each machine to each LAN it joins besides the one it sits in. */
+function cableToLans(layout: Layout): void {
+  for (const [name, n] of Object.entries(layout.topo.nodes)) {
+    const m = layout.machines.get(name);
+    if (!m) continue;
+    const skip = n.kind.router ? undefined : lansOf(layout, n)[0];
+    for (const l of lansOf(layout, n).filter((x) => x !== skip)) {
+      const lan = layout.lans.get(l);
+      if (!lan) continue;
+      layout.edges.push({
+        id: uid("c"),
+        type: "cable",
+        source: m.id,
+        sourceHandle: handle(m, lan),
+        target: lan.id,
+        targetHandle: side(lan, m),
+        data: { aPort: nextPort(m.id, layout.edges), bPort: "" },
+      });
+    }
+  }
+}
+
+/** The links between machines, each with its ports and conditions. */
+function cableLinks(layout: Layout): void {
+  for (const [i, link] of (layout.topo.links ?? []).entries()) {
+    const a = layout.machines.get(link.a.node);
+    const b = layout.machines.get(link.b.node);
+    if (!a || !b) continue;
+    layout.edges.push({
+      id: uid("c"),
+      type: "cable",
+      source: a.id,
+      sourceHandle: handle(a, b),
+      target: b.id,
+      targetHandle: handle(b, a),
+      data: {
+        aPort: link.a.port || nextPort(a.id, layout.edges),
+        bPort: link.b.port || nextPort(b.id, layout.edges),
+        tc: conditionsAt(layout, `links[${String(i)}].tc`, link.tc),
+      },
+    });
+  }
+}
+
+export function draftFromTopology(topo: Topology): LaidOut {
+  const layout: Layout = { topo, nodes: [], edges: [], lans: new Map(), machines: new Map(), problems: [] };
+  const inside = residents(topo);
+  placeLans(layout, inside);
+  placeMachines(layout, inside);
+  cableToLans(layout);
+  cableLinks(layout);
+  const draft = { name: cleanName(topo.name) || "lab", nodes: layout.nodes, edges: migrateEdges(layout.edges, layout.nodes) };
+  return { draft, problems: layout.problems };
+}

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

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import type { LabLive } from "./desktop";
+import { liveViewOf } from "./live";
+import { cable, lan, machine } from "@/test/lab";
+
+const away = { x: 2000, y: 2000 };
+const nodes = [lan("office"), machine("web", {}, away), machine("db", {}, away), machine("cache", {}, away)];
+const edges = [cable("webLan", "web", "office"), cable("dbLan", "db", "office"), cable("webCache", "web", "cache")];
+const live: LabLive = {
+  machines: { web: { state: "running", health: "" }, db: { state: "running", health: "unhealthy" }, cache: { state: "running", health: "" } },
+  ports: [
+    { machine: "web", network: "office", up: true, interface: "eth0" },
+    { machine: "db", network: "office", up: false, interface: null },
+    { machine: "web", network: "link-0", up: null, interface: null },
+  ],
+  probed: true,
+};
+const view = liveViewOf(live, [], nodes, edges);
+
+describe("liveViewOf", () => {
+  test("shows each machine's status, and its state with its health", () => {
+    expect(view.machines.db).toEqual({ status: "unhealthy", detail: "running, unhealthy" });
+    expect(view.machines.web).toEqual({ status: "up", detail: "running" });
+  });
+
+  test("keys each port by machine and network", () => {
+    expect(view.ports).toEqual({ "web/office": true, "db/office": false, "web/link-0": null });
+  });
+
+  test("a cable is up when its ports are, down when one is, unknown when a port isn't known", () => {
+    expect(view.cables).toEqual({ webLan: "up", dbLan: "down", webCache: "unknown" });
+  });
+
+  test("a cable to a machine that is down is down", () => {
+    const stopped = { ...live, machines: { ...live.machines, web: { state: "exited", health: "" } } };
+    expect(liveViewOf(stopped, [], nodes, edges).cables.webLan).toBe("down");
+  });
+
+  test("a suspended link cuts its cable", () => {
+    expect(liveViewOf(live, [{ network: "office", machine: "web" }], nodes, edges).cables.webLan).toBe("cut");
+  });
+
+  test("counts each network's ports up, out of all", () => {
+    expect(view.lans).toEqual({ office: { up: 1, total: 2 }, "link-0": { up: 0, total: 1 } });
+  });
+});

package/src/lib/tool/live.ts

@@ -0,0 +1,49 @@
+import { machineEnds, networkOfCable } from "./cables";
+import { machineStatus, type LabLive, type Status, type SuspendedLink } from "./desktop";
+import type { CableEdge, LabNode } from "./model";
+
+/**
+ * The running lab as the canvas shows it (desktop app; null: not running, or in a browser).
+ * Machines by name; ports by `machine/network` (up, down, or null: unknown); cables by edge id;
+ * LANs by name, with how many of their ports are up.
+ */
+export type CableStatus = "up" | "cut" | "down" | "unknown";
+export interface LiveView {
+  machines: Partial<Record<string, { status: Status; detail: string }>>;
+  ports: Partial<Record<string, boolean | null>>;
+  cables: Partial<Record<string, CableStatus>>;
+  lans: Partial<Record<string, { up: number; total: number }>>;
+}
+
+/** A cable now: cut (suspended), down (a port or a machine is), up (both ports are), or unknown. */
+function cableStatus(view: Pick<LiveView, "machines" | "ports">, network: string, ends: string[], links: SuspendedLink[]): CableStatus {
+  if (links.some((l) => l.network === network && ends.includes(l.machine))) return "cut";
+  const states = ends.map((m) => view.ports[`${m}/${network}`]);
+  if (states.some((s) => s === false) || ends.some((m) => view.machines[m]?.status === "down")) return "down";
+  return states.length && states.every((s) => s === true) ? "up" : "unknown";
+}
+
+/** Each LAN's ports up, out of all. */
+function lansLive(live: LabLive): LiveView["lans"] {
+  const lans: Record<string, { up: number; total: number }> = {};
+  for (const p of live.ports) {
+    const l = (lans[p.network] ??= { up: 0, total: 0 });
+    l.total += 1;
+    if (p.up === true) l.up += 1;
+  }
+  return lans;
+}
+
+export function liveViewOf(live: LabLive, links: SuspendedLink[], nodes: LabNode[], edges: CableEdge[]): LiveView {
+  const ports: Record<string, boolean | null> = {};
+  for (const p of live.ports) ports[`${p.machine}/${p.network}`] = p.up;
+  const machines = Object.fromEntries(
+    Object.entries(live.machines).map(([m, l]) => [m, { status: machineStatus(l), detail: l.health ? `${l.state}, ${l.health}` : l.state }]),
+  );
+  const cables: Record<string, CableStatus> = {};
+  for (const e of edges) {
+    const network = networkOfCable(e.id, nodes, edges);
+    if (network) cables[e.id] = cableStatus({ machines, ports }, network, machineEnds(e, nodes), links);
+  }
+  return { machines, ports, cables, lans: lansLive(live) };
+}

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

@@ -0,0 +1,30 @@
+import { siAlpinelinux, siDocker, siKalilinux, siLinux, siNginx, siPostgresql } from "simple-icons";
+import { describe, expect, test } from "vitest";
+import { dockerLogo, isDark, logoFor } from "./logos";
+
+describe("logoFor", () => {
+  test("a VM takes its OS's logo, the Linux one when its distribution has none", () => {
+    expect(logoFor({ kind: "vm", os: "kali@rolling", image: "" })).toBe(siKalilinux);
+    expect(logoFor({ kind: "vm", os: "unknown", image: "" })).toBe(siLinux);
+  });
+
+  test("a Windows VM has no logo", () => {
+    expect(logoFor({ kind: "vm", os: "windows@11", image: "" })).toBeNull();
+  });
+
+  test("a container takes its image's logo, by the image's name", () => {
+    expect(logoFor({ kind: "container", os: "", image: "library/nginx:1" })).toBe(siNginx);
+    expect(logoFor({ kind: "container", os: "", image: " Postgres:16 " })).toBe(siPostgresql);
+    expect(logoFor({ kind: "container", os: "", image: "alpine" })).toBe(siAlpinelinux);
+  });
+
+  test("an image it doesn't know has none, and falls back to Docker's whale", () => {
+    expect(logoFor({ kind: "container", os: "", image: "foo" })).toBeNull();
+    expect(dockerLogo).toBe(siDocker);
+  });
+});
+
+test("isDark tells the brand colors too dark for a dark background", () => {
+  expect(["000000", "1C1C1C"].map(isDark)).toEqual([true, true]);
+  expect(["FFFFFF", "F97316", "0D597F"].map(isDark)).toEqual([false, false, false]);
+});

package/src/lib/tool/logos.ts

@@ -0,0 +1,99 @@
+import {
+  siAlmalinux,
+  siAlpinelinux,
+  siApache,
+  siCentos,
+  siDebian,
+  siDocker,
+  siElasticsearch,
+  siFedora,
+  siGitlab,
+  siGrafana,
+  siJenkins,
+  siKalilinux,
+  siKibana,
+  siLinux,
+  siMariadb,
+  siMongodb,
+  siMysql,
+  siNginx,
+  siNodedotjs,
+  siPostgresql,
+  siPrometheus,
+  siPython,
+  siRedis,
+  siRockylinux,
+  siTraefikproxy,
+  siUbuntu,
+  siWireshark,
+  type SimpleIcon,
+} from "simple-icons";
+import { imageName, type MachineData } from "./model";
+
+/**
+ * A machine's logo, from what it runs: the VM's OS, or the container's image. Logos are from
+ * Simple Icons (there is none for Windows: Microsoft had theirs removed), so a Windows VM, a
+ * router or an image we don't recognise keeps its generic icon.
+ */
+
+const BY_OS: [prefix: string, icon: SimpleIcon][] = [
+  ["debian", siDebian],
+  ["ubuntu", siUbuntu],
+  ["kali", siKalilinux],
+  ["rocky", siRockylinux],
+  ["alma", siAlmalinux],
+  ["centos", siCentos],
+  ["fedora", siFedora],
+];
+
+/** Image name (its last path segment, without the tag) → logo. */
+const BY_IMAGE: [name: string, icon: SimpleIcon][] = [
+  ["nginx", siNginx],
+  ["alpine", siAlpinelinux],
+  ["postgres", siPostgresql],
+  ["mysql", siMysql],
+  ["mariadb", siMariadb],
+  ["redis", siRedis],
+  ["mongo", siMongodb],
+  ["httpd", siApache],
+  ["node", siNodedotjs],
+  ["python", siPython],
+  ["grafana", siGrafana],
+  ["prometheus", siPrometheus],
+  ["elasticsearch", siElasticsearch],
+  ["kibana", siKibana],
+  ["jenkins", siJenkins],
+  ["gitlab-ce", siGitlab],
+  ["gitlab-ee", siGitlab],
+  ["traefik", siTraefikproxy],
+  ["wireshark", siWireshark],
+  ["kali-rolling", siKalilinux],
+  ["debian", siDebian],
+  ["ubuntu", siUbuntu],
+  ["rockylinux", siRockylinux],
+  ["alma", siAlmalinux],
+  ["centos", siCentos],
+  ["fedora", siFedora],
+];
+
+export function logoFor(m: Pick<MachineData, "kind" | "image" | "os">): SimpleIcon | null {
+  if (m.kind === "vm") {
+    if (m.os.startsWith("windows")) return null;
+    return BY_OS.find(([prefix]) => m.os.startsWith(prefix))?.[1] ?? siLinux;
+  }
+  const name = imageName(m.image);
+  return BY_IMAGE.find(([n]) => name === n)?.[1] ?? null;
+}
+
+/** The fallback for a container whose image we don't know: Docker's whale. */
+export const dockerLogo = siDocker;
+
+/** Brand colors too dark to read on a dark background (AlmaLinux and others use black). */
+export function isDark(hex: string): boolean {
+  const n = parseInt(hex, 16);
+  const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.05;
+}