Prevent documentation diagram label clipping

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable user-visible changes are recorded here. Versions follow [Semantic Ve
 
 ### Changed
 
+- Prevented Mermaid labels from being clipped by waiting for fonts before
+  layout and reserving consistent padding around every diagram node.
 - Added responsive Mermaid diagrams to the principal documentation guides;
   desktop uses wide flows while phones receive compact top-to-bottom layouts.
 - Added proper inner spacing to the landing page's live phone captures and made

scripts/test-landing-seo.mjs

@@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises";
 
 const repositoryRoot = new URL("../", import.meta.url);
 const readSource = (path) => readFile(new URL(path, repositoryRoot), "utf8");
-const [indexHtml, documentationHtml, landingSource, documentationRenderer, documentationRoutes, viteSource, sitemap, robots, manifestSource, readme, workerSource, docsSource, packageSource] = await Promise.all([
+const [indexHtml, documentationHtml, landingSource, landingStyles, documentationRenderer, documentationRoutes, viteSource, sitemap, robots, manifestSource, readme, workerSource, docsSource, packageSource] = await Promise.all([
   readSource("index.html"),
   readSource("web/documentation.html"),
   readSource("web/main.ts"),
+  readSource("web/landing.css"),
   readSource("web/documentation.ts"),
   readSource("shared/documentation.ts"),
   readSource("vite.config.ts"),
@@ -159,6 +160,9 @@ for (const page of ["docs", "app", "cli", "platforms", "mobile", "refstream", "r
 }
 check(documentationRenderer.includes('import documentationSource from "../docs/content.json"'), "Website must render from the repository documentation source");
 check(documentationRenderer.includes('import("mermaid")'), "Documentation diagrams must load Mermaid only on documentation pages");
+check(documentationRenderer.includes("await document.fonts?.ready"), "Documentation diagrams must wait for fonts before measuring labels");
+check(documentationRenderer.includes("padding: 18"), "Documentation diagrams must leave enough room around labels");
+check(landingStyles.includes(".knowledge-diagram-canvas foreignObject p"), "Mermaid labels must retain their measured font size inside documentation sections");
 const diagramPages = Object.values(docsContent.pages).filter((page) => Array.isArray(page.diagrams));
 check(diagramPages.length >= 7, "The knowledge base should contain responsive diagrams across its principal guides");
 for (const page of diagramPages) {

web/documentation.ts

@@ -111,6 +111,11 @@ async function renderDocumentationDiagrams(): Promise<void> {
   const figures = Array.from(document.querySelectorAll<HTMLElement>(".knowledge-diagram"));
   if (figures.length === 0) return;
 
+  // Mermaid measures labels before it draws their nodes. Waiting here prevents
+  // a fallback font from producing boxes that are too narrow once web fonts
+  // finish loading, which otherwise clips the final characters on slower
+  // browsers and mobile connections.
+  await document.fonts?.ready;
   const { default: mermaid } = await import("mermaid");
   mermaid.initialize({
     startOnLoad: false,
@@ -130,10 +135,17 @@ async function renderDocumentationDiagrams(): Promise<void> {
       tertiaryBorderColor: "#cbd6e2",
       lineColor: "#697386",
       edgeLabelBackground: "#ffffff",
-      fontFamily: "Uncut Sans, system-ui, sans-serif",
+      fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif",
       fontSize: "14px",
     },
-    flowchart: { curve: "basis", htmlLabels: false, useMaxWidth: true },
+    flowchart: {
+      curve: "basis",
+      htmlLabels: false,
+      useMaxWidth: true,
+      padding: 18,
+      nodeSpacing: 34,
+      rankSpacing: 42,
+    },
   });
 
   const compact = window.matchMedia("(max-width: 720px)");

web/landing.css

@@ -275,6 +275,15 @@
   margin: auto;
 }
 
+/* Keep rendered labels at the exact size Mermaid used to measure them. The
+   surrounding documentation article gives paragraphs a larger font, and that
+   otherwise leaks into Mermaid's foreignObject labels after layout. */
+.knowledge-diagram-canvas foreignObject p {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+}
+
 .knowledge-diagram-canvas .node rect,
 .knowledge-diagram-canvas .node polygon,
 .knowledge-diagram-canvas .node circle {