docs(website): theme Mermaid diagrams and add inline code formatting (#875)

## Summary

- **Inline code formatting**: Post-render JS scans Mermaid SVG text
nodes for backtick-delimited segments and replaces them with
monospace-styled `<tspan>` elements (JetBrains Mono). Function calls,
API endpoints, CLI commands, and SQL keywords get monospace; prose stays
in Source Serif 4.
- **CSS custom property theming**: All diagram colors — sequence
diagrams (actors, arrows, notes, lifelines, labels, activations) and ER
diagrams (entity boxes, relationship lines, markers, edge labels) — are
overridden via external CSS using `var(--linen)`, `var(--terracotta)`,
`var(--charcoal-soft)`, etc. with `!important`. Theme toggles update CSS
variables instantly with zero JS re-rendering.
- **Rect group backgrounds**: Post-processing replaces hardcoded `fill`
attributes with `style.fill = "var(--linen)"` so they adapt to theme
toggles.
- **Actor labels**: DM Serif Display font via CSS to match site
headings.
- Applied to all three sequence diagrams in relay architecture docs.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cpcloud

docs/content/docs/development/relay-architecture.md

@@ -49,11 +49,11 @@ sequenceDiagram
     participant A as Device A
     participant R as Relay
     participant B as Device B
-    A->>R: secretbox.Seal(op, hhKey) then push
+    A->>R: `secretbox.Seal(op, hhKey)` then push
     R->>R: store ciphertext
     B->>R: pull after seq N
     R->>B: serve ciphertext
-    B->>B: secretbox.Open(op, hhKey)
+    B->>B: `secretbox.Open(op, hhKey)`
 ```
 
 ### Device tokens at rest ([AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode))
@@ -78,20 +78,20 @@ sequenceDiagram
     participant R as Relay
     participant J as Joiner
 
-    I->>R: POST /households/{id}/invite
+    I->>R: `POST /households/{id}/invite`
     R-->>I: invite code
 
     Note over I,J: share code out-of-band
 
-    J->>R: POST /households/{id}/join (code)
+    J->>R: `POST /households/{id}/join` (code)
     R-->>J: exchange ID
 
-    I->>R: GET /households/{id}/pending-exchanges
+    I->>R: `GET /households/{id}/pending-exchanges`
     R-->>I: joiner public key
 
-    I->>R: POST /key-exchange/complete (encrypted household key)
+    I->>R: `POST /key-exchange/complete` (encrypted household key)
 
-    J->>R: GET /key-exchange
+    J->>R: `GET /key-exchange`
     R-->>J: encrypted key + device token
     Note over R: credentials scrubbed
 ```
@@ -162,13 +162,13 @@ sequenceDiagram
     participant R as Relay (Postgres)
     participant B as Device B
 
-    Note over A: User runs micasa pro init
+    Note over A: User runs `micasa pro init`
 
     rect rgb(240, 235, 228)
     Note over A,R: Household creation
-    A->>A: GenerateDeviceKeyPair()
-    A->>A: GenerateHouseholdKey()
-    A->>R: POST /households (public key)
+    A->>A: `GenerateDeviceKeyPair()`
+    A->>A: `GenerateHouseholdKey()`
+    A->>R: `POST /households` (public key)
     R-->>A: household ID + device token
     A->>A: save keys to secrets directory
     end
@@ -178,46 +178,46 @@ sequenceDiagram
 
     rect rgb(240, 235, 228)
     Note over A,R: Push
-    A->>A: secretbox.Seal(op, hhKey) per entry
-    A->>R: POST /sync/push (encrypted ops)
+    A->>A: `secretbox.Seal(op, hhKey)` per entry
+    A->>R: `POST /sync/push` (encrypted ops)
     R->>R: assign sequence numbers, store ciphertext
     end
 
-    Note over A,B: User runs micasa pro invite, shares code
+    Note over A,B: User runs `micasa pro invite`, shares code
 
     rect rgb(240, 235, 228)
     Note over A,B: Key exchange
-    A->>R: POST /households/{id}/invite
+    A->>R: `POST /households/{id}/invite`
     R-->>A: invite code (4h expiry)
-    B->>R: POST /households/{id}/join (invite code + public key)
+    B->>R: `POST /households/{id}/join` (invite code + public key)
     R-->>B: exchange ID
-    A->>R: GET /households/{id}/pending-exchanges
+    A->>R: `GET /households/{id}/pending-exchanges`
     R-->>A: joiner public key
-    A->>A: box.Seal(hhKey, joinerPubKey)
-    A->>R: POST /key-exchange/complete
-    R->>R: encryptToken(deviceToken, serverKey)
-    B->>R: GET /key-exchange (15min expiry)
-    R->>R: decryptToken(stored, serverKey)
+    A->>A: `box.Seal(hhKey, joinerPubKey)`
+    A->>R: `POST /key-exchange/complete`
+    R->>R: `encryptToken(deviceToken, serverKey)`
+    B->>R: `GET /key-exchange` (15min expiry)
+    R->>R: `decryptToken(stored, serverKey)`
     R-->>B: encrypted household key + device token
     R->>R: scrub credentials
-    B->>B: box.Open(encKey, privateKey) = household key
+    B->>B: `box.Open(encKey, privateKey)` = household key
     end
 
     rect rgb(240, 235, 228)
     Note over B,R: Pull
-    B->>R: GET /sync/pull?after=0
+    B->>R: `GET /sync/pull?after=0`
     R-->>B: all encrypted ops
-    B->>B: secretbox.Open(op, hhKey) per op
-    B->>B: apply INSERT/UPDATE/DELETE to local SQLite
+    B->>B: `secretbox.Open(op, hhKey)` per op
+    B->>B: apply `INSERT`/`UPDATE`/`DELETE` to local SQLite
     end
 
     rect rgb(240, 235, 228)
     Note over A,B: Blob sync
-    A->>A: secretbox.Seal(docData, hhKey)
-    A->>R: PUT /blobs/{household}/{sha256}
-    B->>R: GET /blobs/{household}/{sha256}
+    A->>A: `secretbox.Seal(docData, hhKey)`
+    A->>R: `PUT /blobs/{household}/{sha256}`
+    B->>R: `GET /blobs/{household}/{sha256}`
     R-->>B: encrypted blob
-    B->>B: secretbox.Open(blob, hhKey)
+    B->>B: `secretbox.Open(blob, hhKey)`
     end
 
     Note over A,B: Both devices now have identical data

docs/layouts/_default/baseof.html

@@ -172,49 +172,68 @@
 </script>
 
 <script type="module">
-import mermaid from 'mermaid';
-
-function getMermaidTheme() {
-  var dark = document.documentElement.getAttribute('data-theme') === 'dark';
-  return {
-    startOnLoad: false,
-    theme: 'base',
-    themeVariables: dark ? {
-      fontFamily: '"Source Serif 4", Georgia, serif',
-      fontSize: '14px',
-      primaryColor: '#3d3730',
-      primaryBorderColor: '#d4764e',
-      primaryTextColor: '#e8ddd0',
-      lineColor: '#706760',
-      secondaryColor: '#242019',
-      tertiaryColor: '#242019'
-    } : {
-      fontFamily: '"Source Serif 4", Georgia, serif',
-      fontSize: '14px',
-      primaryColor: '#f0ebe4',
-      primaryBorderColor: '#c05e3c',
-      primaryTextColor: '#2d2a26',
-      lineColor: '#9e958a',
-      secondaryColor: '#faf6f1',
-      tertiaryColor: '#faf6f1'
+import mermaid from "mermaid";
+
+mermaid.initialize({
+  startOnLoad: false,
+  theme: "base",
+  themeVariables: {
+    fontFamily: '"Source Serif 4", Georgia, serif',
+    fontSize: "14px",
+    background: "transparent"
+  }
+});
+await mermaid.run();
+
+// Yield one frame so the browser commits rendered SVGs to the DOM
+// before we walk their text nodes.
+await new Promise(function(resolve) { requestAnimationFrame(resolve); });
+
+// Post-process rendered SVGs once — CSS custom properties in docs.css
+// handle all color changes on theme toggle without re-rendering.
+document.querySelectorAll(".mermaid svg").forEach(function(svg) {
+  // Replace backtick-delimited text with monospace tspans
+  var walker = document.createTreeWalker(svg, NodeFilter.SHOW_TEXT, null);
+  var nodes = [];
+  var node;
+  while ((node = walker.nextNode())) {
+    if (node.textContent.includes("`")) {
+      nodes.push(node);
     }
-  };
-}
-
-mermaid.initialize(getMermaidTheme());
-mermaid.run();
-
-document.addEventListener('theme-changed', async function () {
-  mermaid.initialize(getMermaidTheme());
-  var els = document.querySelectorAll('.mermaid[data-processed]');
-  for (var i = 0; i < els.length; i++) {
-    var el = els[i];
-    var source = el.getAttribute('data-original-source');
-    if (!source) continue;
-    el.removeAttribute('data-processed');
-    el.innerHTML = source;
   }
-  await mermaid.run();
+  var mono = '"JetBrains Mono", "Fira Code", "Consolas", monospace';
+  nodes.forEach(function(textNode) {
+    var parts = textNode.textContent.split(/`([^`]+)`/g);
+    if (parts.length <= 1) {
+      return;
+    }
+    var parent = textNode.parentNode;
+    var frag = document.createDocumentFragment();
+    for (var i = 0; i < parts.length; i++) {
+      if (parts[i] === "") {
+        continue;
+      }
+      if (i % 2 === 0) {
+        frag.appendChild(document.createTextNode(parts[i]));
+      } else {
+        var tspan = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+        tspan.style.fontFamily = mono;
+        tspan.textContent = parts[i];
+        frag.appendChild(tspan);
+      }
+    }
+    parent.replaceChild(frag, textNode);
+  });
+
+  // Replace hardcoded rect group fills with a CSS variable so they
+  // adapt to theme toggles without re-rendering.
+  svg.querySelectorAll("rect").forEach(function(rect) {
+    var fill = (rect.getAttribute("fill") || "").replace(/\s/g, "");
+    if (fill === "rgb(240,235,228)") {
+      rect.removeAttribute("fill");
+      rect.style.fill = "var(--linen)";
+    }
+  });
 });
 </script>
 

docs/static/css/docs.css

@@ -746,6 +746,119 @@ h2:hover .badge-experimental .badge-label {
   font-size: 0.9em;
 }
 
+/* Sequence diagram colors — CSS custom properties auto-update on theme
+   toggle, eliminating the need to re-render Mermaid diagrams. */
+
+.docs-main pre.mermaid .actor {
+  stroke: var(--terracotta) !important;
+  fill: var(--linen) !important;
+}
+
+.docs-main pre.mermaid text.actor > tspan {
+  fill: var(--charcoal) !important;
+  font-family: "DM Serif Display", Georgia, serif !important;
+}
+
+.docs-main pre.mermaid .actor-line {
+  stroke: var(--rule) !important;
+}
+
+.docs-main pre.mermaid .messageLine0,
+.docs-main pre.mermaid .messageLine1 {
+  stroke: var(--charcoal-soft) !important;
+}
+
+.docs-main pre.mermaid [id^="arrowhead"] path,
+.docs-main pre.mermaid [id^="crosshead"] path {
+  fill: var(--charcoal-soft) !important;
+  stroke: var(--charcoal-soft) !important;
+}
+
+.docs-main pre.mermaid .messageText {
+  fill: var(--charcoal) !important;
+}
+
+.docs-main pre.mermaid .labelBox {
+  stroke: var(--rule) !important;
+  fill: var(--cream) !important;
+}
+
+.docs-main pre.mermaid .labelText,
+.docs-main pre.mermaid .labelText > tspan,
+.docs-main pre.mermaid .loopText,
+.docs-main pre.mermaid .loopText > tspan {
+  fill: var(--charcoal-soft) !important;
+}
+
+.docs-main pre.mermaid .loopLine {
+  stroke: var(--rule) !important;
+  fill: var(--rule) !important;
+}
+
+.docs-main pre.mermaid .note {
+  stroke: var(--rule) !important;
+  fill: var(--cream) !important;
+}
+
+.docs-main pre.mermaid .noteText,
+.docs-main pre.mermaid .noteText > tspan {
+  fill: var(--charcoal) !important;
+}
+
+.docs-main pre.mermaid .activation0,
+.docs-main pre.mermaid .activation1,
+.docs-main pre.mermaid .activation2 {
+  fill: var(--linen) !important;
+  stroke: var(--terracotta) !important;
+}
+
+/* ER diagram colors */
+
+.docs-main pre.mermaid .entityBox,
+.docs-main pre.mermaid .node rect,
+.docs-main pre.mermaid .node circle,
+.docs-main pre.mermaid .node ellipse,
+.docs-main pre.mermaid .node polygon {
+  fill: var(--linen) !important;
+  stroke: var(--terracotta) !important;
+}
+
+.docs-main pre.mermaid .relationshipLabelBox {
+  fill: transparent !important;
+  opacity: 1 !important;
+}
+
+.docs-main pre.mermaid .labelBkg {
+  background-color: transparent !important;
+}
+
+.docs-main pre.mermaid .relationshipLine {
+  stroke: var(--warm-gray) !important;
+}
+
+.docs-main pre.mermaid .marker {
+  stroke: var(--charcoal-soft) !important;
+}
+
+.docs-main pre.mermaid .marker path {
+  stroke: var(--charcoal-soft) !important;
+  stroke-width: 2 !important;
+}
+
+.docs-main pre.mermaid .marker circle {
+  fill: var(--cream) !important;
+  stroke: var(--charcoal-soft) !important;
+  stroke-width: 2 !important;
+}
+
+.docs-main pre.mermaid .edgeLabel .label {
+  fill: var(--charcoal) !important;
+}
+
+.docs-main pre.mermaid .label {
+  color: var(--charcoal) !important;
+}
+
 /* ── Screenshots ───────────────────────────────────────────── */
 
 .docs-main img,