pi-studio 0.9.36 → 0.9.37

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.37] — 2026-08-01
+
+### Added
+- Added lazy Lucide and Logos icon-pack support for Mermaid diagrams in live previews, standalone HTML exports, and PDF exports through Mermaid CLI.
+- Added browser regression coverage for real SVG icon rendering and dark/light contrast correction.
+
+### Changed
+- Pinned browser Mermaid rendering to 11.16.0 and pinned the icon-pack data used by browser and PDF exports.
+- Made Mermaid icon paints and node labels meet a 4.5:1 contrast target against their rendered surfaces while retaining readable semantic colours; PDF preprocessing now corrects `classDef`/`style` label colours and targets literal Logos SVG fills over solid custom fills.
+- Resolve Mermaid CLI from `MERMAID_CLI_PATH`, Pi's shared npm binary directory, or `PATH`, in that order.
+
+### Fixed
+- Surface Mermaid icon-pack load failures as visible diagram errors instead of silently rendering empty icon nodes.
+
 ## [0.9.36] — 2026-07-13
 
 ### Changed

package/README.md

@@ -50,7 +50,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
   - shows/hides annotation markers in preview
   - strips markers before send (optional)
   - saves `.annotated.md`
-- Renders Markdown/LaTeX/code previews (math + Mermaid) plus lightweight CSV/TSV table previews, theme-synced with pi, with copy buttons for code blocks and blockquotes
+- Renders Markdown/LaTeX/code previews (math + Mermaid) plus lightweight CSV/TSV table previews, theme-synced with pi, with copy buttons for code blocks and blockquotes; Mermaid previews include Lucide/Logos icon nodes and accessible label contrast over custom fills
 - Renders straight, unfenced interactive HTML in preview via a sandboxed browser iframe with zoom controls, while fenced `html` blocks remain source code
 - Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks, with a Focus action for temporarily enlarging the embedded viewer
 - Ships optional `pi-studio-dark` and `pi-studio-light` themes tuned for Studio's browser workspace
@@ -122,6 +122,30 @@ caption: Optional caption
 
 `path` must point to a local `.pdf` within the current Studio resource directory. Relative paths resolve from the opened document's directory, or from Studio's working dir for non-file-backed content. `page` is an initial page hint for the browser PDF viewer, and `height` controls the embedded frame height in pixels. Use normal Markdown links for PDFs when embedding is not useful.
 
+### Mermaid icons
+
+Studio's live previews and standalone HTML exports support Mermaid's `lucide:*` and `logos:*` icon nodes. The corresponding Iconify packs load lazily, so Studio does not fetch either pack unless a diagram uses it. Mermaid and the browser icon-pack URLs are pinned to tested versions.
+
+````md
+```mermaid
+flowchart LR
+  source@{ icon: "lucide:file-code-2", form: "rounded", label: "Source", pos: "b", h: 56 }
+  github@{ icon: "logos:github-icon", form: "rounded", label: "GitHub", pos: "b", h: 56 }
+  source -->|publish| github
+```
+````
+
+Studio also corrects low-contrast Mermaid icon paints and node labels after browser rendering while preserving authored colours that already meet a 4.5:1 contrast ratio. For PDF output, Studio adds or corrects label colours on `classDef` and `style` declarations with solid hex/RGB fills and supplies targeted icon CSS to Mermaid CLI; this also covers Logos icons whose SVG paths use literal fills.
+
+PDF icon nodes require Mermaid CLI 11.12+ so Studio can use pinned icon-pack URLs. Install a current CLI, or set `MERMAID_CLI_PATH` to one:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli@11.16.0
+mmdc --version
+```
+
+Studio only passes icon-pack arguments when a diagram actually references `lucide:` or `logos:`, so ordinary Mermaid PDF diagrams remain compatible with older CLI versions.
+
 ## Notes
 
 - Local-only server (`127.0.0.1`) with tokenized Studio URLs.
@@ -135,7 +159,7 @@ caption: Optional caption
   - `brew install pandoc`
   - install TeX Live/MacTeX for PDF export
 - Export subprocess timeouts default to bounded values and can be tuned with `PI_STUDIO_PANDOC_TIMEOUT_MS`, `PI_STUDIO_LATEX_TIMEOUT_MS`, `PI_STUDIO_MERMAID_TIMEOUT_MS`, and `PI_STUDIO_HTML_RENDER_OUTPUT_MAX_BYTES` for unusually large embedded-asset HTML exports.
-- Mermaid diagrams in exported PDFs may also require Mermaid CLI (`mmdc` / `@mermaid-js/mermaid-cli`) when you want diagram blocks rendered as diagrams rather than left as code.
+- Mermaid diagrams in exported PDFs require Mermaid CLI (`mmdc` / `@mermaid-js/mermaid-cli`) when you want diagram blocks rendered as diagrams rather than left as code; PDF icon nodes require Mermaid CLI 11.12+.
 
 ## License
 

package/client/studio-client.js

@@ -2731,7 +2731,10 @@
         throw new Error("Studio annotation helpers failed to load.");
       }
       const EMPTY_OVERLAY_LINE = "\u200b";
-      const MERMAID_CDN_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      const mermaidHelpers = globalThis.PiStudioMermaidHelpers || null;
+      const MERMAID_CDN_URL = mermaidHelpers && mermaidHelpers.MERMAID_CDN_URL
+        ? mermaidHelpers.MERMAID_CDN_URL
+        : "https://cdn.jsdelivr.net/npm/mermaid@11.16.0/dist/mermaid.esm.min.mjs";
       const MATHJAX_CDN_URL = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js";
       const PDFJS_CDN_URL = "https://cdn.jsdelivr.net/npm/pdfjs-dist@4.10.38/legacy/build/pdf.min.mjs";
       const PDFJS_WORKER_CDN_URL = "https://cdn.jsdelivr.net/npm/pdfjs-dist@4.10.38/legacy/build/pdf.worker.min.mjs";
@@ -2749,6 +2752,9 @@
       const PDF_PREVIEW_RENDER_FAIL_MESSAGE = "PDF figure preview could not be rendered.";
       let mermaidModulePromise = null;
       let mermaidInitialized = false;
+      const mermaidIconRegistry = mermaidHelpers && typeof mermaidHelpers.createIconPackRegistry === "function"
+        ? mermaidHelpers.createIconPackRegistry()
+        : null;
       let mathJaxPromise = null;
       let pdfJsPromise = null;
 
@@ -8243,8 +8249,12 @@
             if (!mermaidApi) {
               throw new Error("Mermaid module did not expose a default export.");
             }
+            if (!mermaidHelpers || !mermaidIconRegistry) {
+              throw new Error("Studio Mermaid helpers failed to load.");
+            }
 
             if (!mermaidInitialized) {
+              mermaidIconRegistry.register(mermaidApi);
               mermaidApi.initialize(MERMAID_CONFIG);
               mermaidInitialized = true;
             }
@@ -8274,7 +8284,7 @@
           return;
         }
 
-        mermaidBlocks.forEach((preEl) => {
+        const wrappers = Array.from(mermaidBlocks).map((preEl) => {
           const codeEl = preEl.querySelector("code");
           const source = codeEl ? codeEl.textContent : preEl.textContent;
 
@@ -8309,20 +8319,29 @@
           wrapper.appendChild(toolbarEl);
           wrapper.appendChild(diagramEl);
           preEl.replaceWith(wrapper);
+          return wrapper;
         });
 
-        const diagramNodes = Array.from(targetEl.querySelectorAll(".mermaid"));
+        const diagramNodes = wrappers
+          .map((wrapper) => wrapper.querySelector(".mermaid"))
+          .filter(Boolean);
         if (diagramNodes.length === 0) return;
 
         try {
+          mermaidIconRegistry.clearError();
           await mermaidApi.run({ nodes: diagramNodes });
+          const iconPackError = mermaidIconRegistry.getError();
+          if (iconPackError) throw iconPackError;
+          mermaidHelpers.applyAccessibleColors(targetEl);
         } catch (error) {
           try {
-            await mermaidApi.run();
-          } catch (fallbackError) {
-            console.error("Mermaid render failed:", fallbackError || error);
-            appendMermaidNotice(targetEl, MERMAID_RENDER_FAIL_MESSAGE);
+            mermaidHelpers.applyAccessibleColors(targetEl);
+          } catch (contrastError) {
+            console.warn("Mermaid contrast correction failed after a partial render:", contrastError);
           }
+          mermaidHelpers.renderFailures(wrappers, error);
+          console.error("Mermaid render failed:", error);
+          appendMermaidNotice(targetEl, MERMAID_RENDER_FAIL_MESSAGE);
         }
       }
 

package/client/studio-mermaid-helpers.js

@@ -0,0 +1,267 @@
+(() => {
+  const MERMAID_VERSION = "11.16.0";
+  const MERMAID_CDN_URL = "https://cdn.jsdelivr.net/npm/mermaid@" + MERMAID_VERSION + "/dist/mermaid.esm.min.mjs";
+  const ICON_PACKS = Object.freeze([
+    Object.freeze({
+      name: "lucide",
+      url: "https://cdn.jsdelivr.net/npm/@iconify-json/lucide@1.2.120/icons.json",
+    }),
+    Object.freeze({
+      name: "logos",
+      url: "https://cdn.jsdelivr.net/npm/@iconify-json/logos@1.2.11/icons.json",
+    }),
+  ]);
+  const MINIMUM_TEXT_CONTRAST = 4.5;
+
+  function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+
+  function parseRgb(value) {
+    const match = String(value || "").match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  }
+
+  function isOpaqueColor(value) {
+    if (!parseRgb(value)) return false;
+    const alphaMatch = String(value || "").match(/^rgba\(\s*[\d.]+\s*,\s*[\d.]+\s*,\s*[\d.]+\s*,\s*([\d.]+)\s*\)$/);
+    return !alphaMatch || Number(alphaMatch[1]) >= 1;
+  }
+
+  function relativeLuminance(color) {
+    const linear = color.map(function(channel) {
+      const value = channel / 255;
+      return value <= 0.04045 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+  }
+
+  function contrastRatio(foreground, background) {
+    const foregroundRgb = Array.isArray(foreground) ? foreground : parseRgb(foreground);
+    const backgroundRgb = Array.isArray(background) ? background : parseRgb(background);
+    if (!foregroundRgb || !backgroundRgb) return 1;
+    const lighter = Math.max(relativeLuminance(foregroundRgb), relativeLuminance(backgroundRgb));
+    const darker = Math.min(relativeLuminance(foregroundRgb), relativeLuminance(backgroundRgb));
+    return (lighter + 0.05) / (darker + 0.05);
+  }
+
+  function toRgb(color) {
+    return "rgb(" + color.map(function(channel) { return Math.round(channel); }).join(", ") + ")";
+  }
+
+  function ensureReadableColor(foregroundCss, backgroundCss, minimumContrast) {
+    const foreground = parseRgb(foregroundCss);
+    const background = parseRgb(backgroundCss);
+    const targetContrast = Number.isFinite(minimumContrast) ? minimumContrast : MINIMUM_TEXT_CONTRAST;
+    if (!foreground || !background || contrastRatio(foreground, background) >= targetContrast) {
+      return foregroundCss;
+    }
+
+    const readableCandidates = [[0, 0, 0], [255, 255, 255]].flatMap(function(target) {
+      for (let step = 1; step <= 20; step += 1) {
+        const amount = step / 20;
+        const color = foreground.map(function(channel, index) {
+          return channel + (target[index] - channel) * amount;
+        });
+        if (contrastRatio(color, background) >= targetContrast) return [{ amount: amount, color: color }];
+      }
+      return [];
+    });
+    readableCandidates.sort(function(left, right) { return left.amount - right.amount; });
+    if (readableCandidates.length > 0) return toRgb(readableCandidates[0].color);
+
+    const black = [0, 0, 0];
+    const white = [255, 255, 255];
+    return toRgb(contrastRatio(black, background) >= contrastRatio(white, background) ? black : white);
+  }
+
+  function createIconPackRegistry(options) {
+    const config = options && typeof options === "object" ? options : {};
+    const packs = Array.isArray(config.packs) ? config.packs : ICON_PACKS;
+    const fetchImpl = typeof config.fetch === "function"
+      ? config.fetch
+      : (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : null);
+    const pending = new Map();
+    let loadError = null;
+    let registeredApi = null;
+
+    function load(pack) {
+      if (!fetchImpl) {
+        const error = new Error("Browser fetch API is unavailable for Mermaid icon packs.");
+        loadError = error;
+        return Promise.reject(error);
+      }
+      if (!pending.has(pack.name)) {
+        const request = Promise.resolve()
+          .then(function() { return fetchImpl(pack.url); })
+          .then(function(response) {
+            if (!response || !response.ok) {
+              const status = response && Number.isFinite(response.status) ? response.status : "unknown";
+              throw new Error("Failed to load Mermaid icon pack " + pack.name + ": HTTP " + status);
+            }
+            return response.json();
+          })
+          .catch(function(error) {
+            const normalized = normalizeError(error);
+            loadError = normalized;
+            pending.delete(pack.name);
+            throw normalized;
+          });
+        pending.set(pack.name, request);
+      }
+      return pending.get(pack.name);
+    }
+
+    function register(mermaidApi) {
+      if (registeredApi === mermaidApi) return;
+      if (!mermaidApi || typeof mermaidApi.registerIconPacks !== "function") {
+        throw new Error("This Mermaid build does not support registered icon packs.");
+      }
+      mermaidApi.registerIconPacks(packs.map(function(pack) {
+        return { name: pack.name, loader: function() { return load(pack); } };
+      }));
+      registeredApi = mermaidApi;
+    }
+
+    return Object.freeze({
+      clearError: function() { loadError = null; },
+      getError: function() { return loadError; },
+      register: register,
+    });
+  }
+
+  function getDomContext(root) {
+    const documentRef = root && root.ownerDocument
+      ? root.ownerDocument
+      : (typeof document === "object" ? document : null);
+    const windowRef = documentRef && documentRef.defaultView
+      ? documentRef.defaultView
+      : (typeof window === "object" ? window : null);
+    if (!documentRef || !windowRef || typeof windowRef.getComputedStyle !== "function") return null;
+    return {
+      documentRef: documentRef,
+      windowRef: windowRef,
+      ElementCtor: windowRef.Element,
+      HTMLElementCtor: windowRef.HTMLElement,
+      getStyle: windowRef.getComputedStyle.bind(windowRef),
+    };
+  }
+
+  function findOpaqueFill(root, context) {
+    if (!context || !(root instanceof context.ElementCtor)) return null;
+    const shape = Array.from(root.querySelectorAll("rect, polygon, path, circle, ellipse")).find(function(candidate) {
+      return isOpaqueColor(context.getStyle(candidate).fill);
+    });
+    return shape ? context.getStyle(shape).fill : null;
+  }
+
+  function findOpaqueBackground(element, fallback, context) {
+    if (!context) return fallback;
+    let current = element instanceof context.ElementCtor ? element : null;
+    while (current) {
+      const background = context.getStyle(current).backgroundColor;
+      if (current instanceof context.HTMLElementCtor && isOpaqueColor(background)) return background;
+      current = current.parentElement;
+    }
+    return fallback;
+  }
+
+  function applyAccessibleColors(root) {
+    if (!root || typeof root.querySelectorAll !== "function") return { iconNodes: 0, shapeNodes: 0 };
+    const context = getDomContext(root);
+    if (!context) return { iconNodes: 0, shapeNodes: 0 };
+    const body = context.documentRef.body;
+    const pageBackground = body ? context.getStyle(body).backgroundColor : "rgb(255, 255, 255)";
+    let iconNodes = 0;
+    let shapeNodes = 0;
+
+    root.querySelectorAll(".mermaid-container .icon-shape").forEach(function(node) {
+      const icon = node.querySelector("svg");
+      if (!icon) return;
+      iconNodes += 1;
+      const semanticColor = context.getStyle(icon).color;
+      const iconSurface = findOpaqueFill(node.firstElementChild, context)
+        || findOpaqueBackground(icon, pageBackground, context);
+      const iconColor = ensureReadableColor(semanticColor, iconSurface);
+      icon.style.setProperty("color", iconColor, "important");
+      icon.querySelectorAll("g, path, rect, polygon, circle, ellipse, line, polyline").forEach(function(paintedElement) {
+        const paintedStyle = context.getStyle(paintedElement);
+        if (isOpaqueColor(paintedStyle.fill)) {
+          paintedElement.style.setProperty("fill", ensureReadableColor(paintedStyle.fill, iconSurface), "important");
+        }
+        if (isOpaqueColor(paintedStyle.stroke)) {
+          paintedElement.style.setProperty("stroke", ensureReadableColor(paintedStyle.stroke, iconSurface), "important");
+        }
+      });
+      node.querySelectorAll(".labelBkg, .nodeLabel").forEach(function(label) {
+        if (!(label instanceof context.HTMLElementCtor)) return;
+        const labelSurface = findOpaqueBackground(label, pageBackground, context);
+        const labelColor = ensureReadableColor(semanticColor, labelSurface);
+        label.style.setProperty("color", labelColor, "important");
+      });
+    });
+
+    root.querySelectorAll(".mermaid-container .node:not(.icon-shape)").forEach(function(node) {
+      const shape = Array.from(node.querySelectorAll("rect, polygon, path, circle, ellipse")).find(function(candidate) {
+        const fill = context.getStyle(candidate).fill;
+        return fill && fill !== "none" && fill !== "rgba(0, 0, 0, 0)";
+      });
+      if (!shape) return;
+      shapeNodes += 1;
+      const shapeFill = context.getStyle(shape).fill;
+      node.querySelectorAll(".nodeLabel").forEach(function(label) {
+        if (!(label instanceof context.HTMLElementCtor)) return;
+        const labelColor = ensureReadableColor(context.getStyle(label).color, shapeFill);
+        label.style.setProperty("color", labelColor, "important");
+      });
+    });
+
+    return { iconNodes: iconNodes, shapeNodes: shapeNodes };
+  }
+
+  function getFailedIconPackName(message) {
+    const match = String(message || "").match(/Mermaid icon pack\s+(lucide|logos)\b/i);
+    return match ? match[1].toLowerCase() : null;
+  }
+
+  function sourceUsesIconPack(source, packName) {
+    if (!packName) return false;
+    const escapedName = packName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp("\\bicon\\s*:\\s*[\\\"']" + escapedName + ":", "i").test(String(source || ""));
+  }
+
+  function renderFailures(wrappers, error) {
+    const message = normalizeError(error).message;
+    const failedIconPack = getFailedIconPackName(message);
+    Array.from(wrappers || []).forEach(function(wrapper) {
+      if (!wrapper || typeof wrapper.querySelector !== "function") return;
+      const diagram = wrapper.querySelector(".mermaid");
+      const documentRef = wrapper.ownerDocument || (typeof document === "object" ? document : null);
+      if (!diagram || !documentRef) return;
+      const source = wrapper.dataset && typeof wrapper.dataset.mermaidSource === "string"
+        ? wrapper.dataset.mermaidSource
+        : "";
+      const hasRenderedSvg = Boolean(diagram.querySelector("svg"));
+      if (hasRenderedSvg && !sourceUsesIconPack(source, failedIconPack)) return;
+      const failure = documentRef.createElement("pre");
+      failure.className = "mermaid-error";
+      failure.setAttribute("role", "alert");
+      failure.textContent = "Mermaid render failed: " + message + (source ? "\n\n" + source : "");
+      diagram.replaceWith(failure);
+    });
+    return message;
+  }
+
+  globalThis.PiStudioMermaidHelpers = Object.freeze({
+    ICON_PACKS: ICON_PACKS,
+    MERMAID_CDN_URL: MERMAID_CDN_URL,
+    MERMAID_VERSION: MERMAID_VERSION,
+    MINIMUM_TEXT_CONTRAST: MINIMUM_TEXT_CONTRAST,
+    applyAccessibleColors: applyAccessibleColors,
+    contrastRatio: contrastRatio,
+    createIconPackRegistry: createIconPackRegistry,
+    ensureReadableColor: ensureReadableColor,
+    parseRgb: parseRgb,
+    renderFailures: renderFailures,
+  });
+})();

package/client/studio.css

@@ -2819,6 +2819,18 @@
       height: auto;
     }
 
+    .rendered-markdown .mermaid-error {
+      margin: 0;
+      padding: 12px 14px;
+      border: 1px solid var(--error);
+      border-radius: 8px;
+      background: var(--panel-2);
+      color: var(--error);
+      text-align: left;
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+    }
+
     .plain-markdown {
       margin: 0;
       white-space: pre-wrap;

package/index.ts

@@ -31,6 +31,11 @@ import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js"
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
 import { buildStudioForwardingHint, buildStudioSshTunnelHint, isStudioSshSession as isSshSession } from "./shared/studio-ssh-hint.js";
 import { renderStudioAnnotationInlineHtml } from "./shared/studio-annotation-render.js";
+import {
+	buildStudioMermaidCliIconArgs,
+	buildStudioMermaidPdfIconContrastCss,
+	ensureStudioMermaidSourceContrast,
+} from "./shared/studio-mermaid.js";
 
 type Lens = "writing" | "code";
 type RequestedLens = Lens | "auto";
@@ -48,6 +53,7 @@ type StudioPiThinkingLevel = ModelThinkingLevel | "max";
 
 const STUDIO_CSS_URL = new URL("./client/studio.css", import.meta.url);
 const STUDIO_ANNOTATION_HELPERS_URL = new URL("./client/studio-annotation-helpers.js", import.meta.url);
+const STUDIO_MERMAID_HELPERS_URL = new URL("./client/studio-mermaid-helpers.js", import.meta.url);
 const STUDIO_CLIENT_URL = new URL("./client/studio-client.js", import.meta.url);
 
 interface StudioServerState {
@@ -644,6 +650,13 @@ const STUDIO_PROMPT_METADATA_CUSTOM_TYPE = "pi-studio/direct-prompt";
 const STUDIO_DEFAULT_SCRATCHPAD_DOCUMENT_KEY = "doc:blank:blank";
 const STUDIO_PERSISTENT_STATE_DIR = join(getAgentDir(), "pi-studio");
 const STUDIO_PERSISTENT_STATE_PATH = join(STUDIO_PERSISTENT_STATE_DIR, "local-state.json");
+const PI_STUDIO_MERMAID_CLI_PATH = join(
+	getAgentDir(),
+	"npm",
+	"node_modules",
+	".bin",
+	process.platform === "win32" ? "mmdc.cmd" : "mmdc",
+);
 
 type StudioSubprocessResult = {
 	code: number | null;
@@ -5820,14 +5833,25 @@ function getStudioMermaidPdfTheme(): "default" | "forest" | "dark" | "neutral" {
 	return "default";
 }
 
+function getStudioMermaidCliCommand(): string {
+	return process.env.MERMAID_CLI_PATH?.trim()
+		|| (existsSync(PI_STUDIO_MERMAID_CLI_PATH) ? PI_STUDIO_MERMAID_CLI_PATH : "mmdc");
+}
+
 async function renderStudioMermaidDiagramForPdf(source: string, workDir: string, blockNumber: number): Promise<string> {
-	const mermaidCommand = process.env.MERMAID_CLI_PATH?.trim() || "mmdc";
+	const mermaidCommand = getStudioMermaidCliCommand();
 	const mermaidTheme = getStudioMermaidPdfTheme();
 	const inputPath = join(workDir, `mermaid-diagram-${blockNumber}.mmd`);
 	const outputPath = join(workDir, `mermaid-diagram-${blockNumber}.pdf`);
+	const iconCssPath = join(workDir, `mermaid-diagram-${blockNumber}.css`);
 
-	await writeFile(inputPath, source, "utf-8");
+	const preparedSource = ensureStudioMermaidSourceContrast(source);
+	const iconContrastCss = buildStudioMermaidPdfIconContrastCss(preparedSource);
+	await writeFile(inputPath, preparedSource, "utf-8");
+	if (iconContrastCss) await writeFile(iconCssPath, iconContrastCss, "utf-8");
 	const args = ["-i", inputPath, "-o", outputPath, "-t", mermaidTheme, "-f"];
+	if (iconContrastCss) args.push("-C", iconCssPath);
+	args.push(...buildStudioMermaidCliIconArgs(preparedSource));
 	const result = await runStudioSubprocess(mermaidCommand, args, {
 		timeoutMs: STUDIO_MERMAID_TIMEOUT_MS,
 		label: "Mermaid CLI",
@@ -6317,10 +6341,18 @@ function buildStudioHtmlMermaidConfig(vars: Record<string, string>): Record<stri
 
 function buildStudioStandaloneHtmlMermaidScript(vars: Record<string, string>): string {
 	const mermaidConfigJson = JSON.stringify(buildStudioHtmlMermaidConfig(vars)).replace(/</g, "\\u003c");
+	const mermaidHelpersSource = readFileSync(STUDIO_MERMAID_HELPERS_URL, "utf-8").replace(/<\/script/gi, "<\\/script");
 	return `<script>
+${mermaidHelpersSource}
+</script>
+<script>
 (() => {
-  const MERMAID_CDN_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
   const MERMAID_CONFIG = ${mermaidConfigJson};
+  const mermaidHelpers = globalThis.PiStudioMermaidHelpers || null;
+
+  function setMermaidRenderResult(status, error) {
+    window.__piStudioMermaidRenderResult = error ? { status, error } : { status };
+  }
 
   function appendMermaidWarning(message) {
     const documentEl = document.querySelector(".studio-export-document") || document.body;
@@ -6332,32 +6364,56 @@ function buildStudioStandaloneHtmlMermaidScript(vars: Record<string, string>): s
   }
 
   function prepareMermaidBlocks() {
-    const preBlocks = Array.from(document.querySelectorAll("pre.mermaid"));
-    preBlocks.forEach((preEl) => {
-      const source = preEl.querySelector("code") ? preEl.querySelector("code").textContent : preEl.textContent;
+    return Array.from(document.querySelectorAll("pre.mermaid")).map((preEl) => {
+      const codeEl = preEl.querySelector("code");
+      const source = codeEl ? codeEl.textContent : preEl.textContent;
       const wrapper = document.createElement("div");
       wrapper.className = "mermaid-container";
+      wrapper.dataset.mermaidSource = source || "";
       const diagramEl = document.createElement("div");
       diagramEl.className = "mermaid";
       diagramEl.textContent = source || "";
       wrapper.appendChild(diagramEl);
       preEl.replaceWith(wrapper);
+      return wrapper;
     });
-    return Array.from(document.querySelectorAll(".mermaid"));
   }
 
   async function renderMermaid() {
-    const nodes = prepareMermaidBlocks();
-    if (nodes.length === 0) return;
+    const wrappers = prepareMermaidBlocks();
+    if (wrappers.length === 0) {
+      setMermaidRenderResult("skipped");
+      return;
+    }
+    setMermaidRenderResult("pending");
     try {
-      const module = await import(MERMAID_CDN_URL);
+      if (!mermaidHelpers) throw new Error("Studio Mermaid helpers failed to load.");
+      const module = await import(mermaidHelpers.MERMAID_CDN_URL);
       const mermaidApi = module && module.default ? module.default : null;
       if (!mermaidApi) throw new Error("Mermaid module did not expose a default export.");
+      const iconRegistry = mermaidHelpers.createIconPackRegistry();
+      iconRegistry.register(mermaidApi);
       mermaidApi.initialize(MERMAID_CONFIG);
-      await mermaidApi.run({ nodes });
+      iconRegistry.clearError();
+      await mermaidApi.run({ nodes: wrappers.map((wrapper) => wrapper.querySelector(".mermaid")) });
+      const iconPackError = iconRegistry.getError();
+      if (iconPackError) throw iconPackError;
+      mermaidHelpers.applyAccessibleColors(document);
+      setMermaidRenderResult("success");
     } catch (error) {
+      if (mermaidHelpers) {
+        try {
+          mermaidHelpers.applyAccessibleColors(document);
+        } catch (contrastError) {
+          console.warn("Mermaid contrast correction failed after a partial render:", contrastError);
+        }
+      }
+      const message = mermaidHelpers
+        ? mermaidHelpers.renderFailures(wrappers, error)
+        : (error instanceof Error ? error.message : String(error));
+      setMermaidRenderResult("failed", message);
       console.error("Mermaid render failed:", error);
-      appendMermaidWarning("Mermaid renderer unavailable. Showing mermaid source text.");
+      appendMermaidWarning("Mermaid render failed. Showing diagram source text.");
     }
   }
 
@@ -10362,6 +10418,7 @@ function buildStudioHtml(
 	const cssVarsBlock = Object.entries(vars).map(([k, v]) => `      ${k}: ${v};`).join("\n");
 	const stylesheetHref = `/studio.css?token=${encodeURIComponent(studioToken ?? "")}`;
 	const annotationHelpersScriptHref = `/studio-annotation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
+	const mermaidHelpersScriptHref = `/studio-mermaid-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const clientScriptHref = `/studio-client.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const faviconHref = buildStudioFaviconDataUri(style);
 	const bootConfigJson = JSON.stringify({ mermaidConfig }).replace(/</g, "\\u003c");
@@ -10778,6 +10835,7 @@ ${cssVarsBlock}
     window.__PI_STUDIO_BOOT__ = ${bootConfigJson};
   </script>
   <script src="${annotationHelpersScriptHref}"></script>
+  <script src="${mermaidHelpersScriptHref}"></script>
   <script src="${clientScriptHref}"></script>
 </body>
 </html>`;
@@ -13962,7 +14020,7 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		if (requestUrl.pathname === "/studio-annotation-helpers.js" || requestUrl.pathname === "/studio-client.js") {
+		if (requestUrl.pathname === "/studio-annotation-helpers.js" || requestUrl.pathname === "/studio-mermaid-helpers.js" || requestUrl.pathname === "/studio-client.js") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
 				respondText(res, 403, "Invalid or expired studio token. Re-run /studio.");
@@ -13978,10 +14036,14 @@ export default function (pi: ExtensionAPI) {
 
 			const targetUrl = requestUrl.pathname === "/studio-annotation-helpers.js"
 				? STUDIO_ANNOTATION_HELPERS_URL
-				: STUDIO_CLIENT_URL;
+				: requestUrl.pathname === "/studio-mermaid-helpers.js"
+					? STUDIO_MERMAID_HELPERS_URL
+					: STUDIO_CLIENT_URL;
 			const targetLabel = requestUrl.pathname === "/studio-annotation-helpers.js"
 				? "studio annotation helper script"
-				: "studio client script";
+				: requestUrl.pathname === "/studio-mermaid-helpers.js"
+					? "studio Mermaid helper script"
+					: "studio client script";
 
 			try {
 				const clientScript = readFileSync(targetUrl, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.36",
+  "version": "0.9.37",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",
@@ -50,8 +50,12 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@iconify-json/logos": "1.2.11",
+    "@iconify-json/lucide": "1.2.120",
     "@types/node": "^24.3.0",
     "@types/ws": "^8.18.1",
+    "mermaid": "11.16.0",
+    "puppeteer-core": "24.22.3",
     "typescript": "^5.7.3"
   }
 }

package/shared/studio-mermaid.js

@@ -0,0 +1,254 @@
+export const STUDIO_MERMAID_ICON_PACKS = Object.freeze([
+  Object.freeze({
+    name: "lucide",
+    packageName: "@iconify-json/lucide",
+    url: "https://cdn.jsdelivr.net/npm/@iconify-json/lucide@1.2.120/icons.json",
+  }),
+  Object.freeze({
+    name: "logos",
+    packageName: "@iconify-json/logos",
+    url: "https://cdn.jsdelivr.net/npm/@iconify-json/logos@1.2.11/icons.json",
+  }),
+]);
+
+export function usesSupportedStudioMermaidIconPack(source) {
+  return /@\{(?:(?!\}).)*\bicon\s*:\s*["'](?:lucide|logos):[^"']+["'](?:(?!\}).)*\}/is.test(String(source || ""));
+}
+
+export function buildStudioMermaidCliIconArgs(source) {
+  return usesSupportedStudioMermaidIconPack(source)
+    ? [
+        "--iconPacksNamesAndUrls",
+        ...STUDIO_MERMAID_ICON_PACKS.map((pack) => `${pack.name}#${pack.url}`),
+      ]
+    : [];
+}
+
+function parseStudioMermaidCssColor(value) {
+  const source = String(value || "").trim().replace(/\s*!important\s*$/i, "");
+  const hex = source.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (hex) {
+    const digits = hex[1].length === 3
+      ? hex[1].split("").map((digit) => digit + digit).join("")
+      : hex[1];
+    return [
+      Number.parseInt(digits.slice(0, 2), 16),
+      Number.parseInt(digits.slice(2, 4), 16),
+      Number.parseInt(digits.slice(4, 6), 16),
+    ];
+  }
+  const rgb = source.match(/^rgb\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*\)$/i);
+  return rgb
+    ? [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])].map((channel) => Math.max(0, Math.min(255, channel)))
+    : null;
+}
+
+function studioMermaidRelativeLuminance(color) {
+  const linear = color.map((channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+}
+
+function studioMermaidContrastRatio(foreground, background) {
+  const lighter = Math.max(studioMermaidRelativeLuminance(foreground), studioMermaidRelativeLuminance(background));
+  const darker = Math.min(studioMermaidRelativeLuminance(foreground), studioMermaidRelativeLuminance(background));
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function formatStudioMermaidHexColor(color) {
+  return `#${color.map((channel) => Math.round(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+
+function ensureStudioMermaidReadableColor(foreground, background) {
+  if (studioMermaidContrastRatio(foreground, background) >= 4.5) return foreground;
+  const candidates = [[0, 0, 0], [255, 255, 255]].flatMap((target) => {
+    for (let step = 1; step <= 20; step += 1) {
+      const amount = step / 20;
+      const color = foreground.map((channel, index) => channel + (target[index] - channel) * amount);
+      if (studioMermaidContrastRatio(color, background) >= 4.5) return [{ amount, color }];
+    }
+    return [];
+  });
+  candidates.sort((left, right) => left.amount - right.amount);
+  if (candidates.length > 0) return candidates[0].color;
+  const black = [0, 0, 0];
+  const white = [255, 255, 255];
+  return studioMermaidContrastRatio(black, background) >= studioMermaidContrastRatio(white, background)
+    ? black
+    : white;
+}
+
+function splitStudioMermaidStyleDeclarations(source) {
+  source = String(source || "");
+  const declarations = [];
+  let start = 0;
+  let depth = 0;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "(") depth += 1;
+    if (char === ")" && depth > 0) depth -= 1;
+    if ((char === "," || char === ";") && depth === 0) {
+      const declaration = source.slice(start, index).trim();
+      if (declaration) declarations.push(declaration);
+      start = index + 1;
+    }
+  }
+  const tail = source.slice(start).trim();
+  if (tail) declarations.push(tail);
+  return declarations;
+}
+
+function getStudioMermaidStyleDeclaration(declarations, property) {
+  const propertyLower = property.toLowerCase();
+  return declarations.find((declaration) => {
+    const separator = declaration.indexOf(":");
+    return separator >= 0 && declaration.slice(0, separator).trim().toLowerCase() === propertyLower;
+  }) || null;
+}
+
+function getStudioMermaidStyleValue(declaration) {
+  if (!declaration) return "";
+  const separator = declaration.indexOf(":");
+  return separator >= 0 ? declaration.slice(separator + 1).trim() : "";
+}
+
+function upsertStudioMermaidStyleDeclaration(declarations, property, value) {
+  const existing = getStudioMermaidStyleDeclaration(declarations, property);
+  const corrected = `${property}:${value}`;
+  if (existing) {
+    declarations[declarations.indexOf(existing)] = corrected;
+  } else {
+    declarations.push(corrected);
+  }
+}
+
+function correctStudioMermaidStyleContrast(styleSource, options = {}) {
+  const hadSemicolon = /;\s*$/.test(styleSource);
+  const declarations = splitStudioMermaidStyleDeclarations(styleSource);
+  const fillDeclaration = getStudioMermaidStyleDeclaration(declarations, "fill");
+  const background = parseStudioMermaidCssColor(getStudioMermaidStyleValue(fillDeclaration));
+  if (!background) return styleSource;
+
+  const colorDeclaration = getStudioMermaidStyleDeclaration(declarations, "color");
+  const authoredForeground = colorDeclaration
+    ? parseStudioMermaidCssColor(getStudioMermaidStyleValue(colorDeclaration))
+    : null;
+  if (colorDeclaration && !authoredForeground) return styleSource;
+
+  const fallbackForeground = studioMermaidContrastRatio([0, 0, 0], background) >= studioMermaidContrastRatio([255, 255, 255], background)
+    ? [0, 0, 0]
+    : [255, 255, 255];
+  const readable = ensureStudioMermaidReadableColor(authoredForeground || fallbackForeground, background);
+  upsertStudioMermaidStyleDeclaration(declarations, "color", formatStudioMermaidHexColor(readable));
+
+  if (options.correctIconStroke) {
+    const strokeDeclaration = getStudioMermaidStyleDeclaration(declarations, "stroke");
+    const authoredStroke = parseStudioMermaidCssColor(getStudioMermaidStyleValue(strokeDeclaration));
+    if (!strokeDeclaration || authoredStroke) {
+      const readableStroke = ensureStudioMermaidReadableColor(authoredStroke || readable, background);
+      upsertStudioMermaidStyleDeclaration(declarations, "stroke", formatStudioMermaidHexColor(readableStroke));
+    }
+  }
+
+  return declarations.join(",") + (hadSemicolon ? ";" : "");
+}
+
+function collectStudioMermaidIconStyleTargets(source) {
+  const iconNodeIds = new Set();
+  const iconNodePattern = /\b([A-Za-z_][\w-]*)\s*@\{(?:(?!\}).)*\bicon\s*:\s*["'](?:lucide|logos):[^"']+["'](?:(?!\}).)*\}/gis;
+  let iconNodeMatch;
+  while ((iconNodeMatch = iconNodePattern.exec(source)) !== null) {
+    iconNodeIds.add(iconNodeMatch[1]);
+  }
+
+  const iconClassNames = new Set();
+  const classNamesByNode = new Map();
+  for (const line of source.split(/\r?\n/)) {
+    const classMatch = line.match(/^\s*class\s+(\S+)\s+(\S+)\s*;?\s*$/i);
+    if (!classMatch) continue;
+    const nodeIds = classMatch[1].split(",").map((value) => value.trim()).filter(Boolean);
+    const classNames = classMatch[2].replace(/;$/, "").split(",").map((value) => value.trim()).filter(Boolean);
+    nodeIds.forEach((nodeId) => {
+      const assigned = classNamesByNode.get(nodeId) || [];
+      classNamesByNode.set(nodeId, [...assigned, ...classNames]);
+    });
+    if (!nodeIds.some((nodeId) => iconNodeIds.has(nodeId))) continue;
+    classNames.forEach((className) => {
+      iconClassNames.add(className);
+    });
+  }
+  return { iconNodeIds, iconClassNames, classNamesByNode };
+}
+
+export function ensureStudioMermaidSourceContrast(source) {
+  const text = String(source || "");
+  const { iconNodeIds, iconClassNames } = collectStudioMermaidIconStyleTargets(text);
+  return text
+    .split(/(\r?\n)/)
+    .map((part) => {
+      if (/^\r?\n$/.test(part)) return part;
+      const match = part.match(/^(\s*)(classDef|style)\s+(\S+)\s+(.*?)(\s*)$/i);
+      if (!match) return part;
+      const targets = match[3].replace(/;$/, "").split(",").map((value) => value.trim()).filter(Boolean);
+      const correctIconStroke = match[2].toLowerCase() === "classdef"
+        ? targets.some((target) => iconClassNames.has(target))
+        : targets.some((target) => iconNodeIds.has(target));
+      const correctedStyles = correctStudioMermaidStyleContrast(match[4], { correctIconStroke });
+      return `${match[1]}${match[2]} ${match[3]} ${correctedStyles}${match[5]}`;
+    })
+    .join("");
+}
+
+function collectStudioMermaidStylesByTarget(source, directiveName) {
+  const stylesByTarget = new Map();
+  for (const line of source.split(/\r?\n/)) {
+    const match = line.match(/^\s*(classDef|style)\s+(\S+)\s+(.*?)\s*$/i);
+    if (!match || match[1].toLowerCase() !== directiveName.toLowerCase()) continue;
+    const targets = match[2].replace(/;$/, "").split(",").map((value) => value.trim()).filter(Boolean);
+    targets.forEach((target) => stylesByTarget.set(target, match[3]));
+  }
+  return stylesByTarget;
+}
+
+function getStudioMermaidIconPaintColor(styleSource) {
+  const declarations = splitStudioMermaidStyleDeclarations(styleSource);
+  const fill = parseStudioMermaidCssColor(getStudioMermaidStyleValue(getStudioMermaidStyleDeclaration(declarations, "fill")));
+  if (!fill) return null;
+  const stroke = parseStudioMermaidCssColor(getStudioMermaidStyleValue(getStudioMermaidStyleDeclaration(declarations, "stroke")));
+  const color = parseStudioMermaidCssColor(getStudioMermaidStyleValue(getStudioMermaidStyleDeclaration(declarations, "color")));
+  return stroke || color ? formatStudioMermaidHexColor(stroke || color) : null;
+}
+
+function buildStudioMermaidIconPaintRule(selector, color) {
+  const paintedElements = ["g", "path", "rect", "polygon", "circle", "ellipse", "line", "polyline"];
+  const fillSelectors = paintedElements.map((element) => `${selector} svg ${element}[fill]:not([fill="none"])`).join(",\n");
+  const strokeSelectors = paintedElements.map((element) => `${selector} svg ${element}[stroke]:not([stroke="none"])`).join(",\n");
+  return [
+    `${selector} svg { color: ${color} !important; }`,
+    `${fillSelectors} { fill: ${color} !important; }`,
+    `${strokeSelectors} { stroke: ${color} !important; }`,
+  ].join("\n");
+}
+
+export function buildStudioMermaidPdfIconContrastCss(source) {
+  const preparedSource = ensureStudioMermaidSourceContrast(source);
+  const { iconNodeIds, classNamesByNode } = collectStudioMermaidIconStyleTargets(preparedSource);
+  if (iconNodeIds.size === 0) return "";
+  const classStyles = collectStudioMermaidStylesByTarget(preparedSource, "classDef");
+  const directStyles = collectStudioMermaidStylesByTarget(preparedSource, "style");
+  const rulesBySelector = new Map();
+
+  for (const iconNodeId of iconNodeIds) {
+    const classNames = classNamesByNode.get(iconNodeId) || [];
+    const classPaint = [...classNames].reverse()
+      .map((className) => getStudioMermaidIconPaintColor(classStyles.get(className)))
+      .find(Boolean);
+    const directPaint = getStudioMermaidIconPaintColor(directStyles.get(iconNodeId));
+    const paint = directPaint || classPaint;
+    if (paint) rulesBySelector.set(`.icon-shape[id*="flowchart-${iconNodeId}-"]`, paint);
+  }
+
+  return Array.from(rulesBySelector, ([selector, color]) => buildStudioMermaidIconPaintRule(selector, color)).join("\n");
+}