@yassimba/pi-loom-mermaid 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yassin Chibrani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# Colored Mermaid diagrams for Pi
+
+Render Mermaid blocks as Unicode terminal diagrams with per-node colors.
+
+## Install
+
+```bash
+pi install npm:@yassimba/pi-loom-mermaid
+```
+
+Disable Pi's built-in Mermaid transformer in `~/.pi/agent/settings.json` so this extension receives the original Mermaid source:
+
+```json
+{
+  "markdown": {
+    "mermaid": "off"
+  }
+}
+```
+
+Run `/reload`, then mark diff nodes with the built-in `red`, `orange`, and `green` classes:
+
+```mermaid
+flowchart LR
+  A[Removed]:::red --> B[Changed]:::orange --> C[Added]:::green
+```
+
+The built-in classes dim and color only the box border; backgrounds and text keep Pi's normal theme. Standard Mermaid `classDef` declarations can override these defaults or add other colors. Diagrams wider than the terminal remain Mermaid source blocks.

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@yassimba/pi-loom-mermaid",
+  "version": "0.2.0",
+  "description": "Loom's advanced Mermaid renderer for Pi, with better routing and color.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "mermaid",
+    "terminal"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "LOVELY-MERMAID-LICENSE",
+    "UPSTREAM.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yassimba/loom.git",
+    "directory": "plugins/pi-loom-mermaid"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "loom": {
+    "catalog": {
+      "label": "Colored Mermaid diagrams",
+      "description": "Render Mermaid diagrams with per-node colors in Pi using classDef styles.",
+      "nextAction": "Set markdown.mermaid to off in Pi settings, run /reload, then use classDef styles in a Mermaid block."
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Marked, type Token } from "@earendil-works/pi-tui";
+import { render, toAnsi } from "./loom-mermaid/index.ts";
+
+const markdownParser = new Marked();
+const diffClasses = {
+  red: { definition: "classDef red stroke:#9f5555", sgr: "38;2;159;85;85" },
+  orange: { definition: "classDef orange stroke:#9a7438", sgr: "38;2;154;116;56" },
+  green: { definition: "classDef green stroke:#4f8560", sgr: "38;2;79;133;96" },
+};
+
+type TransformContext = {
+  messageType: "user" | "assistant" | "assistant-thinking";
+  availableWidth: number;
+  /** The message is still arriving; an unclosed fence shows as source until it closes. */
+  isStreaming?: boolean;
+};
+
+/**
+ * Rendered blocks by source and width. Pi runs the transformer on the whole
+ * message for every streamed chunk and every redraw, so a diagram would be
+ * laid out again for each token after it. Layout is deterministic, so the
+ * first render is the only one needed.
+ */
+const rendered = new Map<string, string>();
+const CACHE_SIZE = 64;
+
+function renderBlock(text: string, availableWidth: number): string | null {
+  const key = `${availableWidth}\0${text}`;
+  const hit = rendered.get(key);
+  if (hit !== undefined) {
+    rendered.delete(key);
+    rendered.set(key, hit);
+    return hit;
+  }
+  const styledSource = withDiffClasses(text);
+  const art = render(styledSource.source, { maxWidth: availableWidth });
+  if (!art || art.width > availableWidth) return null;
+  const out = `${dimDefaultBorders(toAnsi(art), styledSource.dimSgr).map(codeSpan).join("  \n")}\n`;
+  rendered.set(key, out);
+  if (rendered.size > CACHE_SIZE) rendered.delete(rendered.keys().next().value as string);
+  return out;
+}
+
+/** A fenced block whose closing fence has arrived. */
+const isClosed = (token: { raw: string }): boolean => /\n\s*(`{3,}|~{3,})\s*$/.test(token.raw);
+
+function isMermaid(token: Token): token is Token & { type: "code"; text: string; lang?: string } {
+  return (
+    token.type === "code" && token.lang?.trim().split(/\s+/, 1)[0]?.toLowerCase() === "mermaid"
+  );
+}
+
+function withDiffClasses(source: string): { source: string; dimSgr: string[] } {
+  const defaults = Object.entries(diffClasses).filter(([name]) => {
+    const used = new RegExp(`:::\\s*${name}\\b|\\bclass\\s+[^\\n]+\\s+${name}\\b`).test(source);
+    return used && !new RegExp(`\\bclassDef\\s+${name}\\b`).test(source);
+  });
+  return {
+    source:
+      defaults.length > 0
+        ? `${source}\n${defaults.map(([, style]) => style.definition).join("\n")}`
+        : source,
+    dimSgr: defaults.map(([, style]) => style.sgr),
+  };
+}
+
+function dimDefaultBorders(lines: string[], sgrValues: string[]): string[] {
+  return lines.map((line) =>
+    sgrValues.reduce(
+      (result, sgr) => result.replaceAll(`\u001b[${sgr}m`, `\u001b[2;${sgr}m`),
+      line,
+    ),
+  );
+}
+
+function codeSpan(line: string): string {
+  const content = line || "\u00a0";
+  const longestRun = Math.max(
+    0,
+    ...Array.from(content.matchAll(/`+/g), (match) => match[0].length),
+  );
+  const fence = "`".repeat(longestRun + 1);
+  const padding = content.startsWith("`") || content.endsWith("`") ? " " : "";
+  return `${fence}${padding}${content}${padding}${fence}`;
+}
+
+export function transformMermaidMarkdown(markdown: string, context: TransformContext): string {
+  if (context.messageType === "assistant-thinking") return markdown;
+
+  return markdownParser
+    .lexer(markdown)
+    .map((token) => {
+      if (!isMermaid(token)) return token.raw;
+      if (context.isStreaming === true && !isClosed(token)) return token.raw;
+      return renderBlock(token.text, context.availableWidth) ?? token.raw;
+    })
+    .join("");
+}
+
+export default function piLovelyMermaid(pi: ExtensionAPI): void {
+  pi.registerMarkdownTransformer(transformMermaidMarkdown);
+}

package/src/loom-mermaid/ansi.ts

@@ -0,0 +1,65 @@
+import { type ClassStyle, contrastOn, resolveClassStyle } from './class-style.ts'
+import type { MermaidArt, Role } from './types.ts'
+
+const ESC = String.fromCharCode(27)
+const OSC8 = `${ESC}]8;;`
+const ST = `${ESC}\\`
+
+/**
+ * SGR parameter per role, e.g. `'2'` for dim, `'36'` for cyan,
+ * `'38;5;244'` for a 256-colour index. A role left out is printed unstyled.
+ */
+export type AnsiTheme = Partial<Record<Role, string>>
+
+/** Dim frame, plain labels, cyan connectors. Readable on light and dark. */
+export const DEFAULT_THEME: AnsiTheme = {
+  border: '2',
+  edge: '36',
+  edgeLabel: '2;36',
+  title: '1',
+}
+
+const rgb = (hex: string, sgr: 38 | 48): string =>
+  `${sgr};2;${[1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16)).join(';')}`
+
+/**
+ * The truecolor SGR a class style gives a span of the given role, or
+ * undefined when the style says nothing about it (fall back to the theme).
+ * `stroke` colors borders, `color` text; `fill` backs every painted cell,
+ * with a black/white foreground picked for contrast when none was declared.
+ * A style that colors nothing for this role keeps `fallback` (the theme's
+ * SGR), so a bold-only class bolds the themed look instead of replacing it.
+ */
+export function classSgr(st: ClassStyle, role: Role, fallback?: string): string | undefined {
+  const p: string[] = []
+  const fg = role === 'border' ? (st.stroke ?? st.color) : role === 'edge' ? undefined : st.color
+  const backed = fg ?? (st.fill === undefined ? undefined : contrastOn(st.fill))
+  if (backed !== undefined) p.push(rgb(backed, 38))
+  if (st.fill !== undefined) p.push(rgb(st.fill, 48))
+  if (p.length === 0 && fallback !== undefined) p.push(fallback)
+  if (st.bold === true) p.unshift('1')
+  return p.length > 0 ? p.join(';') : undefined
+}
+
+/**
+ * Render art to ANSI-coloured lines. Spans that carry author classes are
+ * styled from `art.classDefs` (best effort — see `resolveClassStyle`),
+ * overriding the role theme; everything else follows `theme`.
+ *
+ * A convenience over mapping `art.styled` yourself — reach for that directly
+ * when your TUI has its own styling model.
+ */
+export function toAnsi(art: MermaidArt, theme: AnsiTheme = DEFAULT_THEME): string[] {
+  return art.styled.map((row) =>
+    row
+      .map((span) => {
+        const cls = resolveClassStyle(span.classes, art.classDefs)
+        const sgr = cls !== null ? classSgr(cls, span.role, theme[span.role]) : theme[span.role]
+        const text = sgr === undefined ? span.text : `${ESC}[${sgr}m${span.text}${ESC}[0m`
+        // OSC 8 hyperlink around the whole run; terminals without support
+        // ignore the sequences and print the text unchanged.
+        return span.href === undefined ? text : `${OSC8}${span.href}${ST}${text}${OSC8}${ST}`
+      })
+      .join(''),
+  )
+}