@ogabrielluiz/patchflow 0.1.0 → 0.1.3

package/dist/{chunk-B7DUSPQH.js → chunk-4VUBNFI4.js}

@@ -39,4 +39,4 @@ export {
   __toESM,
   SIGNAL_OPERATORS
 };
-//# sourceMappingURL=chunk-B7DUSPQH.js.map
+//# sourceMappingURL=chunk-4VUBNFI4.js.map

package/dist/{chunk-B7DUSPQH.js.map → chunk-4VUBNFI4.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// ── Signal Types ──\n\nexport type SignalType = 'audio' | 'cv' | 'pitch' | 'gate' | 'trigger' | 'clock';\n\nexport const SIGNAL_OPERATORS: Record<string, SignalType> = {\n  '->': 'audio',\n  '>>': 'cv',\n  'p>': 'pitch',\n  'g>': 'gate',\n  't>': 'trigger',\n  'c>': 'clock',\n};\n\n// ── Graph Primitives ──\n\nexport interface Port {\n  id: string;          // normalized key (lowercase, trimmed)\n  display: string;     // original form for rendering\n  direction: 'in' | 'out';\n}\n\nexport interface Param {\n  key: string;\n  value: string;\n}\n\nexport interface Block {\n  id: string;\n  label: string;\n  subLabel: string | null;\n  params: Param[];\n  ports: Port[];\n  parentModule: string | null;  // null for top-level modules, module name for sections\n  voice: string | null;\n}\n\nexport interface ConnectionEndpoint {\n  blockId: string;\n  portId: string;       // normalized key\n  portDisplay: string;  // original form\n}\n\nexport interface Connection {\n  id: string;\n  source: ConnectionEndpoint;\n  target: ConnectionEndpoint;\n  signalType: SignalType;\n  annotation: string | null;\n  graphvizExtras: Record<string, string> | null;\n}\n\n// ── Patch Graph (Parser Output) ──\n\nexport interface PatchGraph {\n  declaredBlocks: Block[];\n  stubBlocks: Block[];\n  connections: Connection[];\n  feedbackEdges: Connection[];\n  signalTypeStats: Partial<Record<SignalType, number>>;\n  voices: string[];\n}\n\n// ── Layout Types ──\n\nexport interface Point {\n  x: number;\n  y: number;\n}\n\nexport interface LayoutPort extends Port {\n  position: Point;\n  signalType: SignalType | null;\n}\n\nexport interface LayoutBlock {\n  id: string;\n  label: string;\n  subLabel: string | null;\n  params: Param[];\n  ports: LayoutPort[];\n  parentModule: string | null;\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface LayoutConnection {\n  id: string;\n  source: ConnectionEndpoint;\n  target: ConnectionEndpoint;\n  signalType: SignalType;\n  annotation: string | null;\n  path: string;            // SVG path d attribute\n  isFeedback: boolean;\n  sourcePoint: Point;\n  targetPoint: Point;\n}\n\nexport interface LayoutResult {\n  blocks: LayoutBlock[];\n  connections: LayoutConnection[];\n  width: number;\n  height: number;\n  signalTypeStats: Partial<Record<SignalType, number>>;\n}\n\n// ── Theme Types ──\n\nexport interface CableColor {\n  stroke: string;\n  plugTip: string;\n}\n\nexport interface SocketColors {\n  bezel: string;\n  bezelStroke: string;\n  ring: string;\n  hole: string;\n  pin: string;\n}\n\nexport interface Theme {\n  background: string;\n  panel: {\n    fill: string;\n    stroke: string;\n    highlight: string;\n    shadow: string;\n    cornerRadius: number;\n    shadowBlur: number;\n    shadowOpacity: number;\n    bevelWidth: number;\n  };\n  label: {\n    fontFamily: string;\n    color: string;\n    subColor: string;\n    plateFill: string;\n    plateStroke: string;\n  };\n  param: {\n    plateFill: string;\n    plateStroke: string;\n    textColor: string;\n  };\n  port: {\n    fontFamily: string;\n    fontSize: number;\n    colors: SocketColors;\n    hideSocket: boolean;\n    labelColor: string;\n    pill: {\n      show: boolean;\n      fontSize: number;\n      textColor: string;\n      cornerRadius: number;\n    };\n  };\n  cable: {\n    width: number;\n    colors: Record<SignalType, CableColor>;\n    plugTipRadius: number;\n  };\n  annotation: {\n    fontFamily: string;\n    fontSize: number;\n    color: string;\n    haloColor: string;\n  };\n  grid: {\n    dotColor: string;\n    dotRadius: number;\n    spacing: number;\n    opacity: number;\n  } | null;\n}\n\n// ── Options ──\n\nexport interface RenderOptions {\n  theme?: DeepPartial<Theme>;\n  maxWidth?: number;\n  padding?: number;\n  legend?: boolean | 'auto';\n}\n\nexport interface LayoutOptions {\n  direction?: 'LR' | 'TB';\n  nodeSep?: number;\n  rankSep?: number;\n  feedbackSide?: 'top' | 'bottom';\n}\n\n// ── Parse Result ──\n\nexport type ErrorCode =\n  | 'SYNTAX_ERROR'\n  | 'UNKNOWN_OPERATOR'\n  | 'MISSING_PORT'\n  | 'UNCLOSED_PAREN'\n  | 'DUPLICATE_MODULE'\n  | 'UNKNOWN_MODULE'\n  | 'INVALID_PORT';\n\nexport type ErrorSeverity = 'error' | 'warning';\n\nexport interface ParseDiagnostic {\n  code: ErrorCode;\n  message: string;\n  line: number;\n  column: number;\n  length: number;\n  severity: ErrorSeverity;\n}\n\nexport interface ParseResult {\n  graph: PatchGraph;\n  errors: ParseDiagnostic[];\n  warnings: ParseDiagnostic[];\n}\n\n// ── Utility Types ──\n\nexport type DeepPartial<T> = {\n  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAIO,IAAM,mBAA+C;AAAA,EAC1D,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AACR;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// ── Signal Types ──\n\nexport type SignalType = 'audio' | 'cv' | 'pitch' | 'gate' | 'trigger' | 'clock';\n\nexport const SIGNAL_OPERATORS: Record<string, SignalType> = {\n  '->': 'audio',\n  '>>': 'cv',\n  'p>': 'pitch',\n  'g>': 'gate',\n  't>': 'trigger',\n  'c>': 'clock',\n};\n\n// ── Graph Primitives ──\n\nexport interface Port {\n  id: string;          // normalized key (lowercase, trimmed)\n  display: string;     // original form for rendering\n  direction: 'in' | 'out';\n}\n\nexport interface Param {\n  key: string;\n  value: string;\n}\n\nexport interface Block {\n  id: string;\n  label: string;\n  subLabel: string | null;\n  params: Param[];\n  ports: Port[];\n  parentModule: string | null;  // null for top-level modules, module name for sections\n  voice: string | null;\n}\n\nexport interface ConnectionEndpoint {\n  blockId: string;\n  portId: string;       // normalized key\n  portDisplay: string;  // original form\n}\n\nexport interface Connection {\n  id: string;\n  source: ConnectionEndpoint;\n  target: ConnectionEndpoint;\n  signalType: SignalType;\n  annotation: string | null;\n  graphvizExtras: Record<string, string> | null;\n}\n\n// ── Patch Graph (Parser Output) ──\n\nexport interface PatchGraph {\n  declaredBlocks: Block[];\n  stubBlocks: Block[];\n  connections: Connection[];\n  feedbackEdges: Connection[];\n  signalTypeStats: Partial<Record<SignalType, number>>;\n  voices: string[];\n}\n\n// ── Layout Types ──\n\nexport interface Point {\n  x: number;\n  y: number;\n}\n\nexport interface LayoutPort extends Port {\n  position: Point;\n  signalType: SignalType | null;\n}\n\nexport interface LayoutBlock {\n  id: string;\n  label: string;\n  subLabel: string | null;\n  params: Param[];\n  ports: LayoutPort[];\n  parentModule: string | null;\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface LayoutConnection {\n  id: string;\n  source: ConnectionEndpoint;\n  target: ConnectionEndpoint;\n  signalType: SignalType;\n  annotation: string | null;\n  path: string;            // SVG path d attribute\n  isFeedback: boolean;\n  sourcePoint: Point;\n  targetPoint: Point;\n}\n\nexport interface LayoutResult {\n  blocks: LayoutBlock[];\n  connections: LayoutConnection[];\n  width: number;\n  height: number;\n  signalTypeStats: Partial<Record<SignalType, number>>;\n}\n\n// ── Theme Types ──\n\nexport interface CableColor {\n  stroke: string;\n  plugTip: string;\n}\n\nexport interface SocketColors {\n  bezel: string;\n  bezelStroke: string;\n  ring: string;\n  hole: string;\n  pin: string;\n}\n\nexport interface Theme {\n  background: string;\n  panel: {\n    fill: string;\n    stroke: string;\n    highlight: string;\n    shadow: string;\n    cornerRadius: number;\n    shadowBlur: number;\n    shadowOpacity: number;\n    bevelWidth: number;\n  };\n  label: {\n    fontFamily: string;\n    color: string;\n    subColor: string;\n    plateFill: string;\n    plateStroke: string;\n  };\n  param: {\n    plateFill: string;\n    plateStroke: string;\n    textColor: string;\n  };\n  port: {\n    fontFamily: string;\n    fontSize: number;\n    colors: SocketColors;\n    hideSocket: boolean;\n    labelColor: string;\n    pill: {\n      show: boolean;\n      fontSize: number;\n      textColor: string;\n      cornerRadius: number;\n    };\n  };\n  cable: {\n    width: number;\n    colors: Record<SignalType, CableColor>;\n    plugTipRadius: number;\n  };\n  annotation: {\n    fontFamily: string;\n    fontSize: number;\n    color: string;\n    haloColor: string;\n  };\n  grid: {\n    dotColor: string;\n    dotRadius: number;\n    spacing: number;\n    opacity: number;\n  } | null;\n}\n\n// ── Options ──\n\nexport interface RenderOptions {\n  theme?: DeepPartial<Theme>;\n  maxWidth?: number;\n  padding?: number;\n  legend?: boolean | 'auto';\n}\n\nexport interface LayoutOptions {\n  direction?: 'LR' | 'TB';\n  nodeSep?: number;\n  rankSep?: number;\n  feedbackSide?: 'top' | 'bottom';\n}\n\n// ── Parse Result ──\n\nexport type ErrorCode =\n  | 'SYNTAX_ERROR'\n  | 'UNKNOWN_OPERATOR'\n  | 'MISSING_PORT'\n  | 'UNCLOSED_PAREN'\n  | 'DUPLICATE_MODULE'\n  | 'UNKNOWN_MODULE'\n  | 'INVALID_PORT'\n  | 'AMBIGUOUS_PORT_DIRECTION';\n\nexport type ErrorSeverity = 'error' | 'warning';\n\nexport interface ParseDiagnostic {\n  code: ErrorCode;\n  message: string;\n  line: number;\n  column: number;\n  length: number;\n  severity: ErrorSeverity;\n}\n\nexport interface ParseResult {\n  graph: PatchGraph;\n  errors: ParseDiagnostic[];\n  warnings: ParseDiagnostic[];\n}\n\n// ── Utility Types ──\n\nexport type DeepPartial<T> = {\n  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAIO,IAAM,mBAA+C;AAAA,EAC1D,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AACR;","names":[]}

package/dist/index.cjs

@@ -3591,7 +3591,8 @@ var errorMessages = {
   duplicateModule: (name) => `Module "${name}" declared more than once.`,
   didYouMean: (got, suggestion) => `Module "${got}" is not declared. Did you mean "${suggestion}"?`,
   syntaxError: (detail) => `Syntax error: ${detail}`,
-  emptyDiagram: () => `Diagram is empty \u2014 no connections found.`
+  emptyDiagram: () => `Diagram is empty \u2014 no connections found.`,
+  ambiguousPortDirection: (port, module2) => `Port "${port}" on module "${module2}" is used as both input and output. Use distinct names like "In ${port}"/"Out ${port}" to disambiguate.`
 };
 function editDistance(a, b) {
   const la = a.length;
@@ -3901,6 +3902,39 @@ function parse(input) {
       }
     }
   }
+  const portUsageMap = /* @__PURE__ */ new Map();
+  const allConns = [...forward, ...feedback];
+  for (const conn of allConns) {
+    const srcBlock = conn.source.blockId;
+    if (!portUsageMap.has(srcBlock)) portUsageMap.set(srcBlock, /* @__PURE__ */ new Map());
+    const srcPorts = portUsageMap.get(srcBlock);
+    if (!srcPorts.has(conn.source.portId)) srcPorts.set(conn.source.portId, { asSource: [], asTarget: [] });
+    srcPorts.get(conn.source.portId).asSource.push(0);
+    const tgtBlock = conn.target.blockId;
+    if (!portUsageMap.has(tgtBlock)) portUsageMap.set(tgtBlock, /* @__PURE__ */ new Map());
+    const tgtPorts = portUsageMap.get(tgtBlock);
+    if (!tgtPorts.has(conn.target.portId)) tgtPorts.set(conn.target.portId, { asSource: [], asTarget: [] });
+    tgtPorts.get(conn.target.portId).asTarget.push(0);
+  }
+  for (const [blockId, portMap] of portUsageMap) {
+    for (const [portId, usage] of portMap) {
+      if (usage.asSource.length > 0 && usage.asTarget.length > 0) {
+        const block = allBlocks.get(blockId);
+        const blockLabel = block ? block.label : blockId;
+        const srcConn = allConns.find((c) => c.source.blockId === blockId && c.source.portId === portId);
+        const tgtConn = allConns.find((c) => c.target.blockId === blockId && c.target.portId === portId);
+        const portDisplay = srcConn ? srcConn.source.portDisplay : tgtConn ? tgtConn.target.portDisplay : portId;
+        warnings.push({
+          code: "AMBIGUOUS_PORT_DIRECTION",
+          message: errorMessages.ambiguousPortDirection(portDisplay, blockLabel),
+          line: 0,
+          column: 1,
+          length: 1,
+          severity: "warning"
+        });
+      }
+    }
+  }
   const graph = {
     declaredBlocks: declaredBlocksList,
     stubBlocks,
@@ -4117,23 +4151,33 @@ function collectPorts(blocks, connections) {
   }
   return result;
 }
+function startYForFace(blockY, blockHeight, portCount) {
+  const topMargin = 40;
+  const bottomMargin = 30;
+  const topY = blockY + topMargin;
+  const bottomY = blockY + blockHeight - bottomMargin;
+  const availableHeight = bottomY - topY;
+  const clusterHeight = Math.max(0, (portCount - 1) * 24);
+  return topY + (availableHeight - clusterHeight) / 2;
+}
 function placePorts(block, ports) {
   const inPorts = ports.filter((p) => p.direction === "in");
   const outPorts = ports.filter((p) => p.direction === "out");
   const layoutPorts = [];
-  const startY = block.y + 40 + (block.subLabel ? 18 : 0);
   const spacing = 24;
+  const inStartY = startYForFace(block.y, block.height, inPorts.length);
   inPorts.forEach((p, i) => {
     layoutPorts.push({
       ...p,
-      position: { x: block.x, y: startY + i * spacing },
+      position: { x: block.x, y: inStartY + i * spacing },
       signalType: null
     });
   });
+  const outStartY = startYForFace(block.y, block.height, outPorts.length);
   outPorts.forEach((p, i) => {
     layoutPorts.push({
       ...p,
-      position: { x: block.x + block.width, y: startY + i * spacing },
+      position: { x: block.x + block.width, y: outStartY + i * spacing },
       signalType: null
     });
   });
@@ -4176,7 +4220,7 @@ function findPortPosition(block, portId, direction) {
 }
 function layout(graph, options = {}) {
   const direction = options.direction ?? "LR";
-  const rankSep = options.rankSep ?? 160;
+  const rankSep = options.rankSep ?? 120;
   const nodeSep = options.nodeSep ?? 40;
   const allBlocks = [...graph.declaredBlocks, ...graph.stubBlocks];
   const allConnections = [...graph.connections, ...graph.feedbackEdges];
@@ -4421,7 +4465,28 @@ var SIGNAL_PILL_LABEL = {
   trigger: "trig",
   clock: "clk"
 };
-function buildLabels(theme, blocks) {
+var UPWARD_CABLE_THRESHOLD = 20;
+function computeLabelBelowMap(connections) {
+  const map = /* @__PURE__ */ new Map();
+  for (const conn of connections) {
+    const srcKey = `${conn.source.blockId}:${conn.source.portId}:out`;
+    const srcDy = conn.targetPoint.y - conn.sourcePoint.y;
+    if (srcDy < -UPWARD_CABLE_THRESHOLD) {
+      map.set(srcKey, true);
+    } else if (!map.has(srcKey)) {
+      map.set(srcKey, false);
+    }
+    const tgtKey = `${conn.target.blockId}:${conn.target.portId}:in`;
+    const tgtDy = conn.sourcePoint.y - conn.targetPoint.y;
+    if (conn.isFeedback || tgtDy > UPWARD_CABLE_THRESHOLD) {
+      map.set(tgtKey, true);
+    } else if (!map.has(tgtKey)) {
+      map.set(tgtKey, false);
+    }
+  }
+  return map;
+}
+function buildLabels(theme, blocks, connections) {
   const parts = [];
   const fontFamily = sanitizeForSvg(theme.port.fontFamily);
   const pillShow = theme.port.pill.show;
@@ -4430,79 +4495,89 @@ function buildLabels(theme, blocks) {
   const pillRadius = theme.port.pill.cornerRadius;
   const pillPadX = 3;
   const pillHeight = 11;
-  const pillGap = 6;
   const charWidth = 6.5;
+  const pillOffsetAbove = 20;
+  const nameOffsetAbove = 32;
+  const pillOffsetBelow = 20;
+  const nameOffsetBelow = 32;
+  const belowMap = computeLabelBelowMap(connections);
+  const labelOffsetX = 6;
   for (const block of blocks) {
     for (const port of block.ports) {
       const { x, y } = port.position;
-      const isOut = port.direction === "out";
-      const labelX = isOut ? x + 14 : x - 14;
-      const labelY = y + 3;
-      const anchor = isOut ? "start" : "end";
+      const key = `${block.id}:${port.id}:${port.direction}`;
+      const below = belowMap.get(key) === true;
       const display = sanitizeForSvg(port.display);
-      const labelWidth = port.display.length * charWidth;
+      const isOutput = port.direction === "out";
+      const textY = below ? y + nameOffsetBelow : y - nameOffsetAbove;
+      const textX = isOutput ? x + labelOffsetX : x - labelOffsetX;
+      const textAnchor = isOutput ? "start" : "end";
       parts.push(
-        `<text x="${labelX}" y="${labelY}" font-family="${fontFamily}" font-size="${theme.port.fontSize}" fill="${theme.port.labelColor}" font-weight="600" text-anchor="${anchor}">${display}</text>`
+        `<text x="${textX}" y="${textY}" font-family="${fontFamily}" font-size="${theme.port.fontSize}" fill="${theme.port.labelColor}" font-weight="600" text-anchor="${textAnchor}" dominant-baseline="central">${display}</text>`
       );
       if (pillShow && port.signalType) {
         const pillText = SIGNAL_PILL_LABEL[port.signalType];
         const pillWidth = pillText.length * charWidth + pillPadX * 2;
         const pillColor = theme.cable.colors[port.signalType].stroke;
-        let pillX;
-        if (isOut) {
-          pillX = labelX + labelWidth + pillGap;
-        } else {
-          pillX = labelX - labelWidth - pillGap - pillWidth;
-        }
-        const pillY = y - pillHeight / 2;
-        const textX = pillX + pillWidth / 2;
-        const textY = pillY + pillHeight / 2 + pillFontSize / 2 - 1;
+        const pillCenterY = below ? y + pillOffsetBelow : y - pillOffsetAbove;
+        const pillX = isOutput ? x + labelOffsetX : x - labelOffsetX - pillWidth;
+        const pillY = pillCenterY - pillHeight / 2;
+        const pillTextX = pillX + pillWidth / 2;
         parts.push(
           `<rect class="pf-port-pill" x="${pillX}" y="${pillY}" width="${pillWidth}" height="${pillHeight}" rx="${pillRadius}" fill="${pillColor}" data-signal="${port.signalType}"/>`
         );
         parts.push(
-          `<text class="pf-port-pill-text" x="${textX}" y="${textY}" text-anchor="middle" font-family="${fontFamily}" font-size="${pillFontSize}" fill="${pillTextColor}" font-weight="600">${sanitizeForSvg(pillText)}</text>`
+          `<text class="pf-port-pill-text" x="${pillTextX}" y="${pillCenterY}" text-anchor="middle" dominant-baseline="central" font-family="${fontFamily}" font-size="${pillFontSize}" fill="${pillTextColor}" font-weight="600">${sanitizeForSvg(pillText)}</text>`
         );
       }
     }
   }
   return parts.join("");
 }
-function buildAnnotations(theme, connections) {
+function buildAnnotations(theme, connections, layoutHeight) {
+  const annotated = connections.filter((c) => c.annotation);
+  if (annotated.length === 0) return "";
   const parts = [];
   const fontFamily = sanitizeForSvg(theme.annotation.fontFamily);
-  const fontSize = theme.annotation.fontSize;
-  const charWidth = fontSize * 0.55;
-  for (const conn of connections) {
-    if (!conn.annotation) continue;
+  const noteFontSize = theme.annotation.fontSize + 2;
+  const markerFontFamily = fontFamily;
+  annotated.forEach((conn, i) => {
+    const num = i + 1;
     const sx = conn.sourcePoint.x;
     const sy = conn.sourcePoint.y;
     const tx = conn.targetPoint.x;
     const ty = conn.targetPoint.y;
-    let x;
-    let y;
+    let mx;
+    let my;
     if (conn.isFeedback) {
-      x = (sx + tx) / 2;
-      y = Math.max(sy, ty) + 30;
+      mx = (sx + tx) / 2;
+      const match = conn.path.match(/L\s+\S+\s+\S+\s+L\s+\S+\s+(\S+)/);
+      my = match ? parseFloat(match[1]) : Math.max(sy, ty) + 30;
     } else {
-      x = (sx + tx) / 2;
-      y = (sy + ty) / 2 - 14;
+      mx = (sx + tx) / 2;
+      my = (sy + ty) / 2;
     }
-    const prefix = conn.isFeedback ? "\u21BB " : "";
-    let raw = conn.annotation;
-    if (!conn.isFeedback) {
-      const available = Math.abs(tx - sx);
-      const prefixWidth = prefix.length * charWidth;
-      const maxChars = Math.max(0, Math.floor((available - prefixWidth) / charWidth));
-      if (maxChars > 0 && raw.length > maxChars) {
-        raw = maxChars > 1 ? raw.slice(0, maxChars - 1) + "\u2026" : raw.slice(0, maxChars);
-      }
-    }
-    const text = prefix + sanitizeForSvg(raw);
+    const markerStroke = conn.isFeedback ? theme.cable.colors[conn.signalType].stroke : theme.annotation.color;
     parts.push(
-      `<text x="${x}" y="${y}" text-anchor="middle" font-family="${fontFamily}" font-size="${fontSize}" fill="${theme.annotation.color}" paint-order="stroke fill" stroke="${theme.annotation.haloColor}" stroke-width="3" stroke-linejoin="round">${text}</text>`
+      `<circle cx="${mx}" cy="${my}" r="8" fill="${theme.panel.highlight}" stroke="${markerStroke}" stroke-width="0.5" data-annotation-marker="${num}"/>`
     );
-  }
+    parts.push(
+      `<text x="${mx}" y="${my + 3}" text-anchor="middle" font-family="${markerFontFamily}" font-size="9" fill="${theme.annotation.color}">${num}</text>`
+    );
+  });
+  const panelX = -120;
+  const lineGap = 16;
+  const noteCount = annotated.length;
+  const bottomY = layoutHeight - 10;
+  const firstNoteY = bottomY - (noteCount - 1) * lineGap;
+  annotated.forEach((conn, i) => {
+    const num = i + 1;
+    const noteText = `${num}. ${sanitizeForSvg(conn.annotation)}`;
+    const noteY = firstNoteY + i * lineGap;
+    parts.push(
+      `<text x="${panelX}" y="${noteY}" font-family="${fontFamily}" font-size="${noteFontSize}" font-weight="600" fill="${theme.annotation.color}">${noteText}</text>`
+    );
+  });
   return parts.join("");
 }
 function buildLegend(theme, layoutResult) {
@@ -4512,16 +4587,18 @@ function buildLegend(theme, layoutResult) {
   const parts = [];
   const fontFamily = sanitizeForSvg(theme.annotation.fontFamily);
   const itemWidth = 70;
+  const totalWidth = used.length * itemWidth;
+  const legendStartX = layoutResult.width - totalWidth;
   const y = layoutResult.height - 20;
-  let x = 20;
-  for (const sig of used) {
+  for (let i = 0; i < used.length; i++) {
+    const sig = used[i];
     const color = theme.cable.colors[sig].stroke;
+    const x = legendStartX + i * itemWidth;
     let g = `<g transform="translate(${x}, ${y})">`;
     g += `<line x1="0" y1="0" x2="20" y2="0" stroke="${color}" stroke-width="3" stroke-linecap="round"/>`;
     g += `<text x="26" y="3" font-family="${fontFamily}" font-size="9" fill="${theme.annotation.color}">${sig}</text>`;
     g += `</g>`;
     parts.push(g);
-    x += itemWidth;
   }
   return parts.join("");
 }
@@ -4550,14 +4627,19 @@ function renderSvg(layoutResult, theme) {
     `<g class="pf-layer-panels" >${buildPanels(theme, idPrefix, layoutResult.blocks)}</g>`,
     `<g class="pf-layer-params">${buildParams(layoutResult.blocks, theme)}</g>`,
     `<g class="pf-layer-jacks">${buildJacks(theme, idPrefix, layoutResult.blocks)}</g>`,
-    `<g class="pf-layer-labels">${buildLabels(theme, layoutResult.blocks)}</g>`,
-    `<g class="pf-layer-annotations">${buildAnnotations(theme, layoutResult.connections)}</g>`,
+    `<g class="pf-layer-labels">${buildLabels(theme, layoutResult.blocks, layoutResult.connections)}</g>`,
+    `<g class="pf-layer-annotations">${buildAnnotations(theme, layoutResult.connections, height)}</g>`,
     `<g class="pf-layer-legend">${buildLegend(theme, layoutResult)}</g>`
   ].join("");
   const style = `<style>@media print { .pf-panel, .pf-jack { filter: none; } }</style>`;
   const labelPadX = 130;
   const vbWidth = width + labelPadX * 2;
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${-labelPadX} 0 ${vbWidth} ${height}" width="100%" data-pf-min-width="${minWidth + labelPadX * 2}" role="img" aria-labelledby="${idPrefix}-title ${idPrefix}-desc"><title id="${idPrefix}-title">Patch diagram</title><desc id="${idPrefix}-desc">${desc}</desc>` + style + `<defs>${defsParts.join("")}</defs>` + layers + `</svg>`;
+  const topPad = 40;
+  const noteCount = layoutResult.connections.filter((c) => c.annotation).length;
+  const notesHeight = noteCount > 0 ? noteCount * 16 + 10 : 0;
+  const bottomPad = Math.max(40, notesHeight + 10);
+  const vbHeight = height + topPad + bottomPad;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${-labelPadX} ${-topPad} ${vbWidth} ${vbHeight}" width="100%" data-pf-min-width="${minWidth + labelPadX * 2}" role="img" aria-labelledby="${idPrefix}-title ${idPrefix}-desc"><title id="${idPrefix}-title">Patch diagram</title><desc id="${idPrefix}-desc">${desc}</desc>` + style + `<defs>${defsParts.join("")}</defs>` + layers + `</svg>`;
   return svg;
 }
 
@@ -4620,7 +4702,7 @@ var defaultTheme = {
   annotation: {
     fontFamily: "'SF Mono', 'Fira Code', Consolas, 'Courier New', monospace",
     fontSize: 9,
-    color: "#888888",
+    color: "#4a4a4a",
     haloColor: "#f7f5f0"
   },
   grid: {