feat(excalidraw): improve diagram quality with canvas measurement, validation, and conventions

Replace the charCount * fontSize * 0.55 text sizing heuristic with canvas-based
measurement (graceful fallback when native deps unavailable). Add validate.mjs for
automated spatial checks (text overflow, arrow-text collisions, element overlap).
Update element format reference with sizing rules, label guidelines, and arrow routing
conventions. Add verification step to SKILL.md workflow.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Lamb
2026-02-26 17:19:14 -06:00
parent 36ae861046
commit f524c1b9d8
8 changed files with 824 additions and 0 deletions

View File

@@ -0,0 +1,2 @@
.export-runtime/
.export-tmp/

View File

@@ -0,0 +1,171 @@
#!/usr/bin/env node
/**
* Convert raw Excalidraw MCP checkpoint JSON into a valid .excalidraw file.
* Filters pseudo-elements, adds required defaults, expands labels into bound text.
*/
import { readFileSync, writeFileSync } from 'fs';
// Canvas-based text measurement with graceful fallback to heuristic.
// Excalidraw renders with Virgil (hand-drawn font); system sans-serif
// is a reasonable proxy. The 1.1x multiplier accounts for Virgil being wider.
let measureText;
try {
const { createCanvas } = await import('canvas');
const cvs = createCanvas(1, 1);
const ctx = cvs.getContext('2d');
measureText = (text, fontSize) => {
ctx.font = `${fontSize}px sans-serif`;
const lines = text.split('\n');
const widths = lines.map(line => ctx.measureText(line).width * 1.1);
return {
width: Math.max(...widths),
height: lines.length * (fontSize * 1.25),
};
};
} catch {
console.warn('WARN: canvas not available, using heuristic text sizing (install canvas for accurate measurement)');
measureText = (text, fontSize) => {
const lines = text.split('\n');
return {
width: Math.max(...lines.map(l => l.length)) * fontSize * 0.55,
height: lines.length * (fontSize + 4),
};
};
}
const [,, inputFile, outputFile] = process.argv;
if (!inputFile || !outputFile) {
console.error('Usage: node convert.mjs <input.json> <output.excalidraw>');
process.exit(1);
}
const raw = JSON.parse(readFileSync(inputFile, 'utf8'));
const elements = raw.elements || raw;
let seed = 1000;
const nextSeed = () => seed++;
const processed = [];
for (const el of elements) {
if (['cameraUpdate', 'delete', 'restoreCheckpoint'].includes(el.type)) continue;
const base = {
angle: 0,
roughness: 1,
opacity: el.opacity ?? 100,
groupIds: [],
seed: nextSeed(),
version: 1,
versionNonce: nextSeed(),
isDeleted: false,
boundElements: null,
link: null,
locked: false,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: el.backgroundColor || 'transparent',
fillStyle: el.fillStyle || 'solid',
strokeWidth: el.strokeWidth ?? 2,
strokeStyle: el.strokeStyle || 'solid',
};
if (el.type === 'text') {
const fontSize = el.fontSize || 16;
const measured = measureText(el.text, fontSize);
processed.push({
...base,
type: 'text',
id: el.id,
x: el.x,
y: el.y,
width: measured.width,
height: measured.height,
text: el.text,
fontSize, fontFamily: 1,
textAlign: 'left',
verticalAlign: 'top',
baseline: fontSize,
containerId: null,
originalText: el.text,
});
} else if (el.type === 'arrow') {
const arrowEl = {
...base,
type: 'arrow',
id: el.id,
x: el.x,
y: el.y,
width: el.width || 0,
height: el.height || 0,
points: el.points || [[0, 0]],
startArrowhead: el.startArrowhead || null,
endArrowhead: el.endArrowhead ?? 'arrow',
startBinding: el.startBinding ? { ...el.startBinding, focus: 0, gap: 5 } : null,
endBinding: el.endBinding ? { ...el.endBinding, focus: 0, gap: 5 } : null,
roundness: { type: 2 },
boundElements: [],
};
processed.push(arrowEl);
if (el.label) {
const labelId = el.id + '_label';
const text = el.label.text || '';
const fontSize = el.label.fontSize || 14;
const { width: w, height: h } = measureText(text, fontSize);
const midPt = el.points[Math.floor(el.points.length / 2)] || [0, 0];
processed.push({
...base,
type: 'text', id: labelId,
x: el.x + midPt[0] - w / 2,
y: el.y + midPt[1] - h / 2 - 12,
width: w, height: h,
text, fontSize, fontFamily: 1,
textAlign: 'center', verticalAlign: 'middle',
baseline: fontSize, containerId: el.id, originalText: text,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: 'transparent',
});
arrowEl.boundElements = [{ id: labelId, type: 'text' }];
}
} else if (['rectangle', 'ellipse', 'diamond'].includes(el.type)) {
const shapeEl = {
...base,
type: el.type, id: el.id,
x: el.x, y: el.y, width: el.width, height: el.height,
roundness: el.roundness || null,
boundElements: [],
};
processed.push(shapeEl);
if (el.label) {
const labelId = el.id + '_label';
const text = el.label.text || '';
const fontSize = el.label.fontSize || 16;
const { width: w, height: h } = measureText(text, fontSize);
processed.push({
...base,
type: 'text', id: labelId,
x: el.x + (el.width - w) / 2,
y: el.y + (el.height - h) / 2,
width: w, height: h,
text, fontSize, fontFamily: 1,
textAlign: 'center', verticalAlign: 'middle',
baseline: fontSize, containerId: el.id, originalText: text,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: 'transparent',
});
shapeEl.boundElements = [{ id: labelId, type: 'text' }];
}
}
}
writeFileSync(outputFile, JSON.stringify({
type: 'excalidraw', version: 2, source: 'claude-code',
elements: processed,
appState: { exportBackground: true, viewBackgroundColor: '#ffffff' },
files: {},
}, null, 2));
console.log(`Wrote ${processed.length} elements to ${outputFile}`);

View File

@@ -0,0 +1,61 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body { margin: 0; background: white; }
#root { width: 900px; height: 400px; }
</style>
<script>
window.EXCALIDRAW_ASSET_PATH = "https://esm.sh/@excalidraw/excalidraw/dist/prod/";
</script>
</head>
<body>
<div id="root"></div>
<script type="importmap">
{
"imports": {
"react": "https://esm.sh/react@18",
"react-dom": "https://esm.sh/react-dom@18",
"react-dom/client": "https://esm.sh/react-dom@18/client",
"react/jsx-runtime": "https://esm.sh/react@18/jsx-runtime",
"@excalidraw/excalidraw": "https://esm.sh/@excalidraw/excalidraw@0.18.0?external=react,react-dom"
}
}
</script>
<script type="module">
import { exportToBlob } from "@excalidraw/excalidraw";
async function run() {
const resp = await fetch("./diagram.excalidraw");
const data = await resp.json();
const validTypes = ["rectangle","ellipse","diamond","text","arrow","line","freedraw","image","frame"];
const elements = data.elements.filter(el => validTypes.includes(el.type));
const blob = await exportToBlob({
elements,
appState: {
exportBackground: true,
viewBackgroundColor: data.appState?.viewBackgroundColor || "#ffffff",
exportWithDarkMode: data.appState?.exportWithDarkMode || false,
},
files: data.files || {},
getDimensions: (w, h) => ({ width: w * 2, height: h * 2, scale: 2 }),
});
const reader = new FileReader();
reader.onload = () => {
window.__PNG_DATA__ = reader.result;
document.title = "READY";
};
reader.readAsDataURL(blob);
}
run().catch(e => {
console.error("EXPORT ERROR:", e);
document.title = "ERROR:" + e.message;
});
</script>
</body>
</html>

View File

@@ -0,0 +1,90 @@
#!/usr/bin/env node
/**
* Export an Excalidraw JSON file to PNG using Playwright + the official Excalidraw library.
*
* Usage: node export_png.mjs <input.excalidraw> [output.png]
*
* All rendering happens locally. Diagram data never leaves the machine.
* The Excalidraw JS library is fetched from esm.sh CDN (code only, not user data).
*/
import { createRequire } from "module";
import { readFileSync, writeFileSync, copyFileSync } from "fs";
import { createServer } from "http";
import { join, extname, dirname } from "path";
import { fileURLToPath } from "url";
const __dirname = dirname(fileURLToPath(import.meta.url));
const RUNTIME_DIR = join(__dirname, ".export-runtime");
const HTML_PATH = join(__dirname, "export.html");
// Resolve playwright from the runtime directory, not the script's location
const require = createRequire(join(RUNTIME_DIR, "node_modules", "playwright", "index.mjs"));
const { chromium } = await import(join(RUNTIME_DIR, "node_modules", "playwright", "index.mjs"));
const inputPath = process.argv[2];
if (!inputPath) {
console.error("Usage: node export_png.mjs <input.excalidraw> [output.png]");
process.exit(1);
}
const outputPath = process.argv[3] || inputPath.replace(/\.excalidraw$/, ".png");
// Set up a temp serving directory
const SERVE_DIR = join(__dirname, ".export-tmp");
const { mkdirSync, rmSync } = await import("fs");
mkdirSync(SERVE_DIR, { recursive: true });
copyFileSync(HTML_PATH, join(SERVE_DIR, "export.html"));
copyFileSync(inputPath, join(SERVE_DIR, "diagram.excalidraw"));
const MIME = {
".html": "text/html",
".json": "application/json",
".excalidraw": "application/json",
};
const server = createServer((req, res) => {
const file = join(SERVE_DIR, req.url === "/" ? "export.html" : req.url);
try {
const data = readFileSync(file);
res.writeHead(200, { "Content-Type": MIME[extname(file)] || "application/octet-stream" });
res.end(data);
} catch {
res.writeHead(404);
res.end("Not found");
}
});
server.listen(0, "127.0.0.1", async () => {
const port = server.address().port;
let browser;
try {
browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
page.on("pageerror", err => console.error("Page error:", err.message));
await page.goto(`http://127.0.0.1:${port}`);
await page.waitForFunction(
() => document.title.startsWith("READY") || document.title.startsWith("ERROR"),
{ timeout: 30000 }
);
const title = await page.title();
if (title.startsWith("ERROR")) {
console.error("Export failed:", title);
process.exit(1);
}
const dataUrl = await page.evaluate(() => window.__PNG_DATA__);
const base64 = dataUrl.replace(/^data:image\/png;base64,/, "");
writeFileSync(outputPath, Buffer.from(base64, "base64"));
console.log(outputPath);
} finally {
if (browser) await browser.close();
server.close();
rmSync(SERVE_DIR, { recursive: true, force: true });
}
});

View File

@@ -0,0 +1,37 @@
#!/bin/bash
# First-time setup for excalidraw-png-export skill.
# Installs playwright and chromium headless into a dedicated directory.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
EXPORT_DIR="$SCRIPT_DIR/.export-runtime"
if [ -d "$EXPORT_DIR/node_modules/playwright" ]; then
echo "Runtime already installed at $EXPORT_DIR"
exit 0
fi
echo "Installing excalidraw-png-export runtime..."
mkdir -p "$EXPORT_DIR"
cd "$EXPORT_DIR"
# Initialize package.json with ESM support
cat > package.json << 'PACKAGEEOF'
{
"name": "excalidraw-export-runtime",
"version": "1.0.0",
"type": "module",
"private": true
}
PACKAGEEOF
npm install playwright 2>&1
npx playwright install chromium 2>&1
# canvas provides accurate text measurement for convert.mjs.
# Requires Cairo native library: brew install pkg-config cairo pango libpng jpeg giflib librsvg
# Falls back to heuristic sizing if unavailable.
npm install canvas 2>&1 || echo "WARN: canvas install failed (missing Cairo?). Heuristic text sizing will be used."
echo "Setup complete. Runtime installed at $EXPORT_DIR"

View File

@@ -0,0 +1,173 @@
#!/usr/bin/env node
/**
* Spatial validation for .excalidraw files.
* Checks text overflow, arrow-text collisions, and element overlap.
* Usage: node validate.mjs <input.excalidraw>
*/
import { readFileSync } from 'fs';
const MIN_PADDING = 15;
const inputFile = process.argv[2];
if (!inputFile) {
console.error('Usage: node validate.mjs <input.excalidraw>');
process.exit(1);
}
const data = JSON.parse(readFileSync(inputFile, 'utf8'));
const elements = data.elements || data;
// Build element map
const elMap = new Map();
for (const el of elements) {
if (el.isDeleted) continue;
elMap.set(el.id, el);
}
let warnings = 0;
let errors = 0;
const checked = elements.filter(el => !el.isDeleted).length;
// --- Check 1: Text overflow within containers ---
// Skip arrow-bound labels — arrows are lines, not spatial containers.
for (const el of elements) {
if (el.isDeleted || el.type !== 'text' || !el.containerId) continue;
const parent = elMap.get(el.containerId);
if (!parent || parent.type === 'arrow') continue;
const textRight = el.x + el.width;
const textBottom = el.y + el.height;
const parentRight = parent.x + parent.width;
const parentBottom = parent.y + parent.height;
const paddingLeft = el.x - parent.x;
const paddingRight = parentRight - textRight;
const paddingTop = el.y - parent.y;
const paddingBottom = parentBottom - textBottom;
const overflows = [];
if (paddingLeft < MIN_PADDING) overflows.push(`left=${paddingLeft.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingRight < MIN_PADDING) overflows.push(`right=${paddingRight.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingTop < MIN_PADDING) overflows.push(`top=${paddingTop.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingBottom < MIN_PADDING) overflows.push(`bottom=${paddingBottom.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (overflows.length > 0) {
const label = (el.text || '').replace(/\n/g, '\\n');
const truncated = label.length > 40 ? label.slice(0, 37) + '...' : label;
console.log(`WARN: text "${truncated}" (id=${el.id}) tight/overflow in container (id=${el.containerId})`);
console.log(` text_bbox=[${el.x.toFixed(0)},${el.y.toFixed(0)}]->[${textRight.toFixed(0)},${textBottom.toFixed(0)}]`);
console.log(` container_bbox=[${parent.x.toFixed(0)},${parent.y.toFixed(0)}]->[${parentRight.toFixed(0)},${parentBottom.toFixed(0)}]`);
console.log(` insufficient padding: ${overflows.join(', ')}`);
console.log();
warnings++;
}
}
// --- Check 2: Arrow-text collisions ---
/** Check if line segment (p1->p2) intersects axis-aligned rectangle. */
function segmentIntersectsRect(p1, p2, rect) {
// rect = {x, y, w, h} -> min/max
const rxMin = rect.x;
const rxMax = rect.x + rect.w;
const ryMin = rect.y;
const ryMax = rect.y + rect.h;
// Cohen-Sutherland-style clipping
let [x1, y1] = [p1[0], p1[1]];
let [x2, y2] = [p2[0], p2[1]];
function outcode(x, y) {
let code = 0;
if (x < rxMin) code |= 1;
else if (x > rxMax) code |= 2;
if (y < ryMin) code |= 4;
else if (y > ryMax) code |= 8;
return code;
}
let code1 = outcode(x1, y1);
let code2 = outcode(x2, y2);
for (let i = 0; i < 20; i++) {
if (!(code1 | code2)) return true; // both inside
if (code1 & code2) return false; // both outside same side
const codeOut = code1 || code2;
let x, y;
if (codeOut & 8) { y = ryMax; x = x1 + (x2 - x1) * (ryMax - y1) / (y2 - y1); }
else if (codeOut & 4) { y = ryMin; x = x1 + (x2 - x1) * (ryMin - y1) / (y2 - y1); }
else if (codeOut & 2) { x = rxMax; y = y1 + (y2 - y1) * (rxMax - x1) / (x2 - x1); }
else { x = rxMin; y = y1 + (y2 - y1) * (rxMin - x1) / (x2 - x1); }
if (codeOut === code1) { x1 = x; y1 = y; code1 = outcode(x1, y1); }
else { x2 = x; y2 = y; code2 = outcode(x2, y2); }
}
return false;
}
// Collect text bounding boxes (excluding arrow-bound labels for their own arrow)
const textBoxes = [];
for (const el of elements) {
if (el.isDeleted || el.type !== 'text') continue;
textBoxes.push({
id: el.id,
containerId: el.containerId,
text: (el.text || '').replace(/\n/g, '\\n'),
rect: { x: el.x, y: el.y, w: el.width, h: el.height },
});
}
for (const el of elements) {
if (el.isDeleted || el.type !== 'arrow') continue;
if (!el.points || el.points.length < 2) continue;
// Compute absolute points
const absPoints = el.points.map(p => [el.x + p[0], el.y + p[1]]);
for (const tb of textBoxes) {
// Skip this arrow's own label
if (tb.containerId === el.id) continue;
for (let i = 0; i < absPoints.length - 1; i++) {
if (segmentIntersectsRect(absPoints[i], absPoints[i + 1], tb.rect)) {
const truncated = tb.text.length > 30 ? tb.text.slice(0, 27) + '...' : tb.text;
const seg = `[${absPoints[i].map(n => n.toFixed(0)).join(',')}]->[${absPoints[i + 1].map(n => n.toFixed(0)).join(',')}]`;
console.log(`WARN: arrow (id=${el.id}) segment ${seg} crosses text "${truncated}" (id=${tb.id})`);
console.log(` text_bbox=[${tb.rect.x.toFixed(0)},${tb.rect.y.toFixed(0)}]->[${(tb.rect.x + tb.rect.w).toFixed(0)},${(tb.rect.y + tb.rect.h).toFixed(0)}]`);
console.log();
warnings++;
break; // one warning per arrow-text pair
}
}
}
}
// --- Check 3: Element overlap (non-child, same depth) ---
const topLevel = elements.filter(el =>
!el.isDeleted && !el.containerId && el.type !== 'text' && el.type !== 'arrow'
);
for (let i = 0; i < topLevel.length; i++) {
for (let j = i + 1; j < topLevel.length; j++) {
const a = topLevel[i];
const b = topLevel[j];
const aRight = a.x + a.width;
const aBottom = a.y + a.height;
const bRight = b.x + b.width;
const bBottom = b.y + b.height;
if (a.x < bRight && aRight > b.x && a.y < bBottom && aBottom > b.y) {
const overlapX = Math.min(aRight, bRight) - Math.max(a.x, b.x);
const overlapY = Math.min(aBottom, bBottom) - Math.max(a.y, b.y);
console.log(`WARN: overlap between (id=${a.id}) and (id=${b.id}): ${overlapX.toFixed(0)}x${overlapY.toFixed(0)}px`);
console.log();
warnings++;
}
}
}
// --- Summary ---
console.log(`OK: ${checked} elements checked, ${warnings} warning(s), ${errors} error(s)`);
process.exit(warnings > 0 ? 1 : 0);