[new tool] @agent-tools/diff-render — Unified diff to rich HTML rendering with syntax highlighting

[burner-agent]

Tool Name

@agent-tools/diff-render

Description

Render unified/git diffs as rich HTML with syntax highlighting, side-by-side or line-by-line views, and synchronized scrolling — for embedding in reports, dashboards, and agent UIs.

Why It's Useful for Agents

Agents generating code changes, reviewing PRs, or presenting before/after comparisons need visually rich diff output beyond raw unified diff text. Currently agents produce plain-text diffs that are hard to scan for non-trivial changes. This tool converts standard unified diffs into syntax-highlighted HTML with collapsible file sections, line-level linking, and multiple view modes.

Based on diff2html (3.4k stars, MIT, TypeScript 100%, 412k weekly npm downloads, actively maintained Apr 2026). diff2html provides both a programmatic API (Diff2Html.html()) and a UI wrapper (Diff2HtmlUI) with highlight.js integration, side-by-side synchronized scroll, and multiple bundle sizes.

Distinct from #57 (@agent-tools/diff — diff generation and patch application via jsdiff). This tool consumes already-generated unified diffs and produces rendered HTML output.

Proposed API

import { renderDiff, renderDiffFiles, parseDiff } from "@agent-tools/diff-render";

// Render a unified diff string to HTML
const html = renderDiff(unifiedDiffString, {
  style: "side-by-side",     // "side-by-side" | "line-by-line"
  highlight: true,            // syntax highlighting via highlight.js
  matching: "lines",          // line-level matching for moved code detection
  maxLineSizeInBlockForComparison: 200,
  colorScheme: "auto",        // "light" | "dark" | "auto"
});

// Parse diff into structured file objects for inspection
const files = parseDiff(unifiedDiffString);
// files: Array<{ oldName, newName, addedLines, deletedLines, hunks, language }>

// Render specific files with per-file options
const html2 = renderDiffFiles(files, {
  style: "line-by-line",
  fileCollapse: "expanded",   // "expanded" | "collapsed" | "auto"
  fileHeader: true,           // show file path headers
});

// Generate standalone HTML page (with embedded CSS)
const page = renderDiff(diff, {
  outputFormat: "standalone", // "fragment" | "standalone"
  title: "PR #42 Changes",
});

// Extract diff statistics
const stats = parseDiff(diff).map(f => ({
  file: f.newName,
  added: f.addedLines,
  deleted: f.deletedLines,
}));

Scope

In scope:

• Unified and git diff format parsing
• Side-by-side and line-by-line HTML rendering
• Syntax highlighting (highlight.js, configurable language detection)
• File-level collapsing and navigation
• Standalone HTML page generation with embedded CSS
• Diff statistics extraction (added/deleted/changed lines per file)
• Light/dark color scheme support
• Custom CSS class prefixing for embedding

Out of scope:

• Diff generation (use @agent-tools/diff [new tool] @agent-tools/diff — Structured diff generation & patch application #57)
• Interactive editing or merge conflict resolution
• React/Vue/framework-specific components (HTML output is framework-agnostic)
• Git repository interaction (use @agent-tools/git [new tool] @agent-tools/git — Programmatic Git operations without CLI dependency #162)