@diagrammo/dgmo 0.8.22 → 0.8.25

package/src/cli.ts

@@ -1,12 +1,16 @@
 /* eslint-disable no-console */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { homedir } from 'node:os';
+import { homedir, platform } from 'node:os';
 import { resolve, join, basename, extname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Resvg } from '@resvg/resvg-js';
 import { render } from './render';
-import { parseDgmo, getAllChartTypes } from './dgmo-router';
+import {
+  parseDgmo,
+  getAllChartTypes,
+  CHART_TYPE_DESCRIPTIONS,
+} from './dgmo-router';
 import { parseDgmoChartType } from './dgmo-router';
 import { formatDgmoError } from './diagnostics';
 import { getPalette, getAvailablePalettes } from './palettes';
@@ -19,40 +23,6 @@ const PALETTES = getAvailablePalettes().map((p) => p.id);
 
 const THEMES = ['light', 'dark', 'transparent'] as const;
 
-const CHART_TYPE_DESCRIPTIONS: Record<string, string> = {
-  bar: 'Bar chart — categorical comparisons',
-  line: 'Line chart — trends over time',
-  'multi-line': 'Multi-line chart — multiple series trends',
-  area: 'Area chart — filled line chart',
-  pie: 'Pie chart — part-to-whole proportions',
-  doughnut: 'Doughnut chart — ring-style pie chart',
-  radar: 'Radar chart — multi-dimensional metrics',
-  'polar-area': 'Polar area chart — radial bar chart',
-  'bar-stacked': 'Stacked bar chart — multi-series categorical',
-  scatter: 'Scatter plot — 2D data points or bubble chart',
-  sankey: 'Sankey diagram — flow/allocation visualization',
-  chord: 'Chord diagram — circular flow relationships',
-  function: 'Function plot — mathematical expressions',
-  heatmap: 'Heatmap — matrix intensity visualization',
-  funnel: 'Funnel chart — conversion pipeline',
-  slope: 'Slope chart — change between two periods',
-  wordcloud: 'Word cloud — term frequency visualization',
-  arc: 'Arc diagram — network relationships',
-  timeline: 'Timeline — events, eras, and date ranges',
-  venn: 'Venn diagram — set overlaps',
-  quadrant: 'Quadrant chart — 2x2 positioning matrix',
-  sequence: 'Sequence diagram — message/interaction flows',
-  flowchart: 'Flowchart — decision trees and process flows',
-  class: 'Class diagram — UML class hierarchies',
-  er: 'ER diagram — database schemas and relationships',
-  org: 'Org chart — hierarchical tree structures',
-  kanban: 'Kanban board — task/workflow columns',
-  c4: 'C4 diagram — system architecture (context, container, component, deployment)',
-  infra: 'Infra chart — infrastructure traffic flow with rps computation',
-  'boxes-and-lines':
-    'Boxes and lines — general-purpose node-edge diagrams with groups and tags',
-};
-
 const CLAUDE_SKILL_CONTENT = `# dgmo — Diagrammo Diagram Assistant
 
 You are helping the user author, render, and share diagrams using the \`dgmo\` CLI and \`.dgmo\` file format.
@@ -497,10 +467,6 @@ Options:
                        With stdin and no -o, PNG is written to stdout
   --theme <theme>      Theme: ${THEMES.join(', ')} (default: light)
   --palette <name>     Palette: ${PALETTES.join(', ')} (default: nord)
-  --c4-level <level>   C4 render level: context (default), containers, components, deployment
-  --c4-system <name>   System to drill into (with --c4-level containers or components)
-  --c4-container <name> Container to drill into (with --c4-level components)
-  --tag-group <name>   Pre-select a tag group for static export coloring
   --copy               Copy URL to clipboard (only with -o url)
   --json               Output structured JSON to stdout
   --chart-types        List all supported chart types
@@ -512,6 +478,11 @@ Options:
   --install-codex-integration
                        Full Codex CLI setup: write AGENTS.md to the project and configure
                        the dgmo MCP server in .codex/config.toml (project) or ~/.codex/config.toml (global)
+  --install-claude-desktop-integration
+                       Full Claude Desktop setup: install @diagrammo/dgmo-mcp if needed,
+                       then merge the dgmo MCP entry into Claude Desktop's config file
+                       (~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
+                       %APPDATA%/Claude/... on Windows, ~/.config/Claude/... on Linux)
   --help               Show this help
   --version            Show version`);
 }
@@ -538,10 +509,7 @@ function parseArgs(argv: string[]): {
   installClaudeSkill: boolean;
   installClaudeCodeIntegration: boolean;
   installCodexIntegration: boolean;
-  c4Level: 'context' | 'containers' | 'components' | 'deployment';
-  c4System: string | undefined;
-  c4Container: string | undefined;
-  tagGroup: string | undefined;
+  installClaudeDesktopIntegration: boolean;
 } {
   const result = {
     input: undefined as string | undefined,
@@ -558,14 +526,7 @@ function parseArgs(argv: string[]): {
     installClaudeSkill: false,
     installClaudeCodeIntegration: false,
     installCodexIntegration: false,
-    c4Level: 'context' as
-      | 'context'
-      | 'containers'
-      | 'components'
-      | 'deployment',
-    c4System: undefined as string | undefined,
-    c4Container: undefined as string | undefined,
-    tagGroup: undefined as string | undefined,
+    installClaudeDesktopIntegration: false,
   };
 
   const args = argv.slice(2); // skip node + script
@@ -609,30 +570,6 @@ function parseArgs(argv: string[]): {
       }
       result.palette = val;
       i++;
-    } else if (arg === '--c4-level') {
-      const val = args[++i];
-      if (
-        val !== 'context' &&
-        val !== 'containers' &&
-        val !== 'components' &&
-        val !== 'deployment'
-      ) {
-        console.error(
-          `Error: Invalid C4 level "${val}". Valid levels: context, containers, components, deployment`
-        );
-        process.exit(1);
-      }
-      result.c4Level = val;
-      i++;
-    } else if (arg === '--c4-system') {
-      result.c4System = args[++i];
-      i++;
-    } else if (arg === '--c4-container') {
-      result.c4Container = args[++i];
-      i++;
-    } else if (arg === '--tag-group') {
-      result.tagGroup = args[++i];
-      i++;
     } else if (arg === '--json') {
       result.json = true;
       i++;
@@ -648,6 +585,9 @@ function parseArgs(argv: string[]): {
     } else if (arg === '--install-codex-integration') {
       result.installCodexIntegration = true;
       i++;
+    } else if (arg === '--install-claude-desktop-integration') {
+      result.installClaudeDesktopIntegration = true;
+      i++;
     } else if (arg === '--copy') {
       result.copy = true;
       i++;
@@ -673,12 +613,19 @@ function inferFormat(outputPath: string | undefined): 'svg' | 'png' | 'url' {
   return 'png';
 }
 
+const BUNDLED_FONTS = [
+  join(__dirname, '..', 'fonts', 'Inter-Regular.ttf'),
+  join(__dirname, '..', 'fonts', 'Inter-Bold.ttf'),
+];
+
 function svgToPng(svg: string, background?: string): Buffer {
+  const fontFiles = BUNDLED_FONTS.filter((f) => existsSync(f));
   const resvg = new Resvg(svg, {
     fitTo: { mode: 'zoom', value: 2 },
     ...(background ? { background } : {}),
     font: {
-      loadSystemFonts: true,
+      loadSystemFonts: fontFiles.length === 0,
+      ...(fontFiles.length > 0 ? { fontFiles } : {}),
       defaultFontFamily: DEFAULT_FONT_NAME,
       sansSerifFamily: DEFAULT_FONT_NAME,
     },
@@ -745,7 +692,7 @@ async function main(): Promise<void> {
     } else {
       for (const id of types) {
         const desc = CHART_TYPE_DESCRIPTIONS[id];
-        console.log(desc ? `${id} — ${desc.split(' — ')[1]}` : id);
+        console.log(desc ? `${id} — ${desc}` : id);
       }
     }
     return;
@@ -1068,6 +1015,133 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (opts.installClaudeDesktopIntegration) {
+    const ask = (prompt: string): Promise<string> =>
+      new Promise((resolve) => {
+        const rl = createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+        rl.question(prompt, (answer) => {
+          rl.close();
+          resolve(answer);
+        });
+      });
+
+    // Check / install dgmo-mcp binary
+    let dgmoMcpInstalled = false;
+    try {
+      execSync('which dgmo-mcp', { stdio: 'pipe' });
+      dgmoMcpInstalled = true;
+    } catch {
+      /* not found */
+    }
+    if (!dgmoMcpInstalled) {
+      const ans = await ask(
+        '\ndgmo-mcp not found. Install @diagrammo/dgmo-mcp globally now? [Y/n] '
+      );
+      const yes =
+        ans === '' || ans.toLowerCase() === 'y' || ans.toLowerCase() === 'yes';
+      if (yes) {
+        console.log('Installing @diagrammo/dgmo-mcp...');
+        try {
+          execSync('npm install -g @diagrammo/dgmo-mcp', { stdio: 'inherit' });
+          console.log('✓ @diagrammo/dgmo-mcp installed');
+        } catch {
+          console.error('Error: Failed to install @diagrammo/dgmo-mcp.');
+          console.error('Try manually: npm install -g @diagrammo/dgmo-mcp');
+        }
+      } else {
+        console.log(
+          '  Skipped. Install later with: npm install -g @diagrammo/dgmo-mcp'
+        );
+      }
+    } else {
+      console.log('✓ dgmo-mcp already installed');
+    }
+
+    // Resolve the Claude Desktop config path for the current platform.
+    // macOS and Windows use the documented Claude Desktop paths; Linux
+    // doesn't have a first-party build yet, but community installs follow
+    // the XDG config convention.
+    const os = platform();
+    let configPath: string;
+    if (os === 'darwin') {
+      configPath = join(
+        homedir(),
+        'Library',
+        'Application Support',
+        'Claude',
+        'claude_desktop_config.json'
+      );
+    } else if (os === 'win32') {
+      const appData =
+        process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+      configPath = join(appData, 'Claude', 'claude_desktop_config.json');
+    } else {
+      configPath = join(
+        homedir(),
+        '.config',
+        'Claude',
+        'claude_desktop_config.json'
+      );
+    }
+
+    // Read existing config (or start fresh). Non-JSON contents are treated
+    // as corruption and we bail — the user needs to resolve it manually so
+    // we don't silently overwrite something they care about.
+    type ClaudeDesktopConfig = {
+      mcpServers?: Record<
+        string,
+        { command: string; args?: string[]; env?: Record<string, string> }
+      >;
+      [key: string]: unknown;
+    };
+    let config: ClaudeDesktopConfig = {};
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, 'utf-8');
+      if (raw.trim().length > 0) {
+        try {
+          config = JSON.parse(raw) as ClaudeDesktopConfig;
+        } catch {
+          console.error(
+            `Error: ${configPath} exists but is not valid JSON. Fix it manually and re-run, or remove the file to regenerate.`
+          );
+          process.exit(1);
+        }
+      }
+    }
+
+    const existingDgmo = config.mcpServers?.dgmo;
+    if (existingDgmo && existingDgmo.command === 'dgmo-mcp') {
+      console.log(`✓ dgmo MCP server already configured in ${configPath}`);
+    } else {
+      if (existingDgmo) {
+        const ans = await ask(
+          `\nA "dgmo" entry already exists in ${configPath}. Overwrite? [y/N] `
+        );
+        if (ans.toLowerCase() !== 'y' && ans.toLowerCase() !== 'yes') {
+          console.log('  Skipped.');
+          return;
+        }
+      }
+      config.mcpServers = {
+        ...(config.mcpServers ?? {}),
+        dgmo: { command: 'dgmo-mcp' },
+      };
+      mkdirSync(join(configPath, '..'), { recursive: true });
+      writeFileSync(
+        configPath,
+        JSON.stringify(config, null, 2) + '\n',
+        'utf-8'
+      );
+      console.log(`✓ dgmo MCP server configured: ${configPath}`);
+    }
+
+    console.log('\nRestart Claude Desktop to activate the MCP server.');
+    return;
+  }
+
   // Determine input source
   let content: string;
   let inputBasename: string | undefined;
@@ -1225,32 +1299,9 @@ async function main(): Promise<void> {
     }
   }
 
-  // Validate C4 options
-  if (opts.c4Level === 'containers' && !opts.c4System) {
-    exitWithJsonError(
-      'Error: --c4-system is required when --c4-level is containers'
-    );
-  }
-  if (opts.c4Level === 'components') {
-    if (!opts.c4System) {
-      exitWithJsonError(
-        'Error: --c4-system is required when --c4-level is components'
-      );
-    }
-    if (!opts.c4Container) {
-      exitWithJsonError(
-        'Error: --c4-container is required when --c4-level is components'
-      );
-    }
-  }
-
   const { svg } = await render(content, {
     theme: opts.theme,
     palette: opts.palette,
-    c4Level: opts.c4Level,
-    c4System: opts.c4System,
-    c4Container: opts.c4Container,
-    tagGroup: opts.tagGroup,
   });
 
   if (!svg) {

package/src/completion.ts

@@ -16,6 +16,7 @@ import { extractSymbols as extractFlowchartSymbols } from './graph/flowchart-par
 import { extractSymbols as extractInfraSymbols } from './infra/parser';
 import { extractSymbols as extractClassSymbols } from './class/parser';
 import { parseFirstLine, ALL_CHART_TYPES } from './utils/parsing';
+import { CHART_TYPE_DESCRIPTIONS } from './dgmo-router';
 
 // ============================================================
 // Symbol extraction
@@ -237,10 +238,6 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
         description: 'Show activation bars',
         values: ['on', 'off'],
       },
-      'collapse-notes': {
-        description: 'Collapse note blocks',
-        values: ['yes', 'no'],
-      },
       'active-tag': { description: 'Active tag group name' },
     }),
   ],
@@ -381,56 +378,20 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
       persona: { description: 'Define the journey persona' },
     }),
   ],
+  [
+    'pyramid',
+    withGlobals({
+      inverted: { description: 'Flip apex to the bottom (funnel orientation)' },
+      color: { description: 'Override layer color (pipe metadata)' },
+      description: { description: 'Layer description (pipe or indented body)' },
+    }),
+  ],
 ]);
 
 // ============================================================
 // Chart types array (for chart type completion popup)
 // ============================================================
 
-const CHART_TYPE_DESCRIPTIONS: Record<string, string> = {
-  // Data charts
-  bar: 'Bar chart',
-  line: 'Line chart',
-  pie: 'Pie chart',
-  doughnut: 'Doughnut chart',
-  area: 'Area chart',
-  'polar-area': 'Polar area chart',
-  radar: 'Radar chart',
-  'bar-stacked': 'Stacked bar chart',
-  // Extended charts
-  scatter: 'Scatter plot',
-  heatmap: 'Heatmap',
-  sankey: 'Sankey flow diagram',
-  chord: 'Chord diagram',
-  funnel: 'Funnel chart',
-  function: 'Mathematical function plot',
-  // Visualizations
-  slope: 'Slope chart',
-  wordcloud: 'Word cloud',
-  arc: 'Arc diagram',
-  timeline: 'Timeline',
-  venn: 'Venn diagram',
-  quadrant: 'Quadrant chart',
-  // Diagrams
-  sequence: 'Sequence diagram',
-  flowchart: 'Flowchart',
-  class: 'Class diagram',
-  er: 'Entity-relationship diagram',
-  org: 'Organization chart',
-  kanban: 'Kanban board',
-  c4: 'C4 architecture diagram',
-  state: 'State diagram',
-  sitemap: 'Sitemap diagram',
-  infra: 'Infrastructure diagram',
-  gantt: 'Gantt chart',
-  'boxes-and-lines': 'Boxes and lines diagram',
-  mindmap: 'Mindmap diagram',
-  wireframe: 'UI wireframe diagram',
-  'tech-radar': 'Technology adoption radar (ThoughtWorks style)',
-  cycle: 'Cycle diagram (circular process flow)',
-  'journey-map': 'User journey map with emotion curve',
-};
-
 /** All chart types with descriptions, for chart type autocomplete. Excludes `multi-line` alias. */
 export const CHART_TYPES: ReadonlyArray<{ name: string; description: string }> =
   [...ALL_CHART_TYPES]

package/src/cycle/layout.ts

@@ -2,11 +2,14 @@
 // Cycle Diagram — Layout Engine
 // ============================================================
 
-import type {
-  ParsedCycle,
-  CycleLayoutNode,
-  CycleLayoutEdge,
-  CycleLayoutResult,
+import {
+  DEFAULT_EDGE_WIDTH,
+  MIN_EDGE_WIDTH,
+  arrowHeadLength,
+  type ParsedCycle,
+  type CycleLayoutNode,
+  type CycleLayoutEdge,
+  type CycleLayoutResult,
 } from './types';
 
 /** Minimum arc angle in radians (~15°) to keep arcs readable. */
@@ -519,11 +522,6 @@ function circleRectExitAngle(
   return (insideAngle + outsideAngle) / 2;
 }
 
-/** Default edge stroke width (must match renderer). */
-const DEFAULT_EDGE_WIDTH = 3;
-/** Arrowhead marker width in stroke-width units (must match renderer). */
-const ARROWHEAD_MARKER_W = 8;
-
 /** Compute edge paths for all edges in the parsed diagram. */
 function computeEdgePaths(
   layoutNodes: CycleLayoutNode[],
@@ -536,9 +534,13 @@ function computeEdgePaths(
   return parsed.edges.map((edge) => {
     const src = layoutNodes[edge.sourceIndex];
     const tgt = layoutNodes[edge.targetIndex];
-    const strokeWidth = edge.width ?? DEFAULT_EDGE_WIDTH;
-    // Arrowhead rendered length in pixels (markerUnits = strokeWidth)
-    const arrowLen = ARROWHEAD_MARKER_W * strokeWidth;
+    const strokeWidth = Math.max(
+      edge.width ?? DEFAULT_EDGE_WIDTH,
+      MIN_EDGE_WIDTH
+    );
+    // Arrowhead effective reach: full length minus the 10% overlap that
+    // slides the marker back to cover the stroke/arrowhead junction line.
+    const arrowLen = arrowHeadLength(strokeWidth) * 0.9;
     const { path, labelX, labelY, labelAngle } = buildEdgeArc(
       src,
       tgt,
@@ -578,7 +580,7 @@ function fitToCanvas(
   height: number,
   _isClockwise: boolean
 ): { radius: number } | null {
-  const PADDING = 10;
+  const PADDING = 30;
   let contentMinX = Infinity,
     contentMaxX = -Infinity;
   let contentMinY = Infinity,
@@ -672,20 +674,9 @@ function buildEdgeArc(
 ): { path: string; labelX: number; labelY: number; labelAngle: number } {
   const dir = isClockwise ? 1 : -1;
 
-  // Find where the cycle circle exits the source node
-  const startAngle = src.isCircle
-    ? circleNodeExitAngle(src.width / 2, radius, src.angle, dir)
-    : circleRectExitAngle(
-        src.x,
-        src.y,
-        src.width / 2,
-        src.height / 2,
-        cx,
-        cy,
-        radius,
-        src.angle,
-        dir
-      );
+  // Start arc from the source node's center angle — the node renders on top
+  // of the edge, so the overlap is hidden and there's no visible gap.
+  const startAngle = src.angle;
 
   // Find where the cycle circle exits the target node
   const nodeEndAngle = tgt.isCircle

package/src/cycle/renderer.ts

@@ -23,13 +23,15 @@ import { renderInlineText } from '../utils/inline-markdown';
 import type { PaletteColors } from '../palettes';
 import type { D3ExportDimensions } from '../utils/d3-types';
 import type { CompactViewState } from '../sharing';
-import type { ParsedCycle } from './types';
+import {
+  DEFAULT_EDGE_WIDTH,
+  MIN_EDGE_WIDTH,
+  arrowHeadLength,
+  type ParsedCycle,
+} from './types';
 import { computeCycleLayout } from './layout';
 
 // ── Constants ────────────────────────────────────────────────
-const DEFAULT_EDGE_WIDTH = 3;
-const ARROWHEAD_W = 8;
-const ARROWHEAD_H = 8;
 const NODE_FONT_SIZE = 13;
 const DESC_FONT_SIZE = 11;
 const EDGE_LABEL_FONT_SIZE = 11;
@@ -183,22 +185,28 @@ export function renderCycle(
   // Resolve default node color: first palette color (uniform)
   const defaultNodeColor = palette.primary;
 
-  // ── Arrowhead markers ──
-  const arrowColors = new Set<string>();
-  for (let i = 0; i < parsed.edges.length; i++) {
-    const edge = parsed.edges[i];
+  // ── Arrowhead markers (per color+width, markerUnits=strokeWidth) ──
+  const markerKeys = new Set<string>();
+  for (const edge of parsed.edges) {
     const color = resolveEdgeColor(edge, parsed, palette, defaultNodeColor);
-    arrowColors.add(color);
+    const sw = Math.max(edge.width ?? DEFAULT_EDGE_WIDTH, MIN_EDGE_WIDTH);
+    const key = `${color}|${sw}`;
+    if (!markerKeys.has(key)) {
+      markerKeys.add(key);
+      ensureArrowMarker(defs, color, sw);
+    }
   }
-  ensureArrowMarkers(defs, arrowColors);
 
   // ── Render edges (below nodes) ──
   for (let i = 0; i < layout.edges.length; i++) {
     const le = layout.edges[i];
     const edge = parsed.edges[i];
     const color = resolveEdgeColor(edge, parsed, palette, defaultNodeColor);
-    const strokeWidth = edge.width ?? DEFAULT_EDGE_WIDTH;
-    const markerId = `cycle-arrow-${color.replace('#', '')}`;
+    const strokeWidth = Math.max(
+      edge.width ?? DEFAULT_EDGE_WIDTH,
+      MIN_EDGE_WIDTH
+    );
+    const markerId = arrowMarkerId(color, strokeWidth);
 
     const edgeG = g.append('g').attr('class', 'cycle-edge');
 
@@ -514,26 +522,45 @@ function resolveEdgeColor(
   return defaultNodeColor;
 }
 
-function ensureArrowMarkers(
+/** Stable marker ID for a (color, strokeWidth) pair. */
+function arrowMarkerId(color: string, strokeWidth: number): string {
+  return `cycle-arrow-${color.replace('#', '')}-w${strokeWidth}`;
+}
+
+/**
+ * Create an arrowhead marker using markerUnits="strokeWidth" (SVG default)
+ * with per-edge dimensions.  The marker base automatically equals the stroke
+ * width — no gaps or lollipop effects.  Marker dimensions are computed so
+ * the rendered arrowhead length follows a sublinear formula:
+ *
+ *   rendered length = markerWidth × strokeWidth = arrowHeadLength(sw)
+ *   → markerWidth = arrowHeadLength(sw) / sw
+ *
+ * The height is fixed at 1 strokeWidth unit so the base = stroke width.
+ */
+function ensureArrowMarker(
   defs: d3Selection.Selection<SVGDefsElement, unknown, null, undefined>,
-  colors: Set<string>
+  color: string,
+  strokeWidth: number
 ): void {
-  for (const color of colors) {
-    const id = `cycle-arrow-${color.replace('#', '')}`;
-    defs
-      .append('marker')
-      .attr('id', id)
-      .attr('viewBox', `0 0 ${ARROWHEAD_W * 2} ${ARROWHEAD_H * 2}`)
-      .attr('refX', 0)
-      .attr('refY', ARROWHEAD_H)
-      .attr('markerWidth', ARROWHEAD_W)
-      .attr('markerHeight', ARROWHEAD_H)
-      .attr('orient', 'auto')
-      .append('polygon')
-      .attr(
-        'points',
-        `0,0 ${ARROWHEAD_W * 2},${ARROWHEAD_H} 0,${ARROWHEAD_H * 2}`
-      )
-      .attr('fill', color);
-  }
+  const id = arrowMarkerId(color, strokeWidth);
+  // Marker dimensions in strokeWidth units.
+  // Rendered size = mw × sw  (length)  and  mh × sw  (height).
+  const mw = arrowHeadLength(strokeWidth) / strokeWidth;
+  // Height proportional to length (½ ratio) but at least 1.5× stroke width
+  // so the arrowhead is always visibly wider than the stroke.
+  const mh = Math.max(1.5, mw * 0.5);
+
+  defs
+    .append('marker')
+    .attr('id', id)
+    .attr('viewBox', `0 0 ${mw} ${mh}`)
+    .attr('refX', mw * 0.1)
+    .attr('refY', mh / 2)
+    .attr('markerWidth', mw)
+    .attr('markerHeight', mh)
+    .attr('orient', 'auto')
+    .append('polygon')
+    .attr('points', `0,0 ${mw},${mh / 2} 0,${mh}`)
+    .attr('fill', color);
 }

package/src/cycle/types.ts

@@ -64,6 +64,27 @@ export interface CycleLayoutEdge {
   label?: string;
 }
 
+// ============================================================
+// Shared arrow-sizing helpers (used by both layout + renderer)
+// ============================================================
+
+/** Default edge stroke width. */
+export const DEFAULT_EDGE_WIDTH = 3;
+/** Minimum rendered stroke width — thinner strokes produce unusable arrowheads. */
+export const MIN_EDGE_WIDTH = 2;
+
+/**
+ * Compute the desired arrowhead length in user-space pixels using sublinear
+ * scaling.  The renderer uses markerUnits="strokeWidth" with computed marker
+ * dimensions so the arrowhead base always matches the stroke width (no gaps,
+ * no lollipop effect) while the rendered length follows this formula.
+ */
+const BASE_ARROW_SIZE = 8;
+const ARROW_SCALE = 6;
+export function arrowHeadLength(strokeWidth: number): number {
+  return BASE_ARROW_SIZE + ARROW_SCALE * Math.sqrt(strokeWidth);
+}
+
 export interface CycleLayoutResult {
   nodes: CycleLayoutNode[];
   edges: CycleLayoutEdge[];