living-documentation 7.42.0 → 7.43.0

package/dist/src/frontend/diagram/custom-shapes.js

@@ -0,0 +1,96 @@
+import { st } from './state.js';
+
+export const CUSTOM_SHAPE_TYPE = 'custom-shape';
+export const CUSTOM_SHAPE_TOOL_PREFIX = 'custom-shape:';
+
+export const DEFAULT_CUSTOM_ANCHORS = [
+  { id: 'N',  x: 0.5, y: 0   },
+  { id: 'NE', x: 1,   y: 0   },
+  { id: 'E',  x: 1,   y: 0.5 },
+  { id: 'SE', x: 1,   y: 1   },
+  { id: 'S',  x: 0.5, y: 1   },
+  { id: 'SW', x: 0,   y: 1   },
+  { id: 'W',  x: 0,   y: 0.5 },
+  { id: 'NW', x: 0,   y: 0   },
+];
+
+export function isCustomShapeTool(shape) {
+  return typeof shape === 'string' && shape.startsWith(CUSTOM_SHAPE_TOOL_PREFIX);
+}
+
+export function customShapeIdFromTool(shape) {
+  return isCustomShapeTool(shape) ? shape.slice(CUSTOM_SHAPE_TOOL_PREFIX.length) : null;
+}
+
+export function getCustomShapeDefinition(id) {
+  if (!id) return null;
+  return st.customShapeDefs && st.customShapeDefs.get(id) || null;
+}
+
+export function getCustomShapeDefaultSize(id) {
+  const def = getCustomShapeDefinition(id);
+  return [def && def.width || 96, def && def.height || 96];
+}
+
+export function getCustomShapeAnchors(id) {
+  const def = getCustomShapeDefinition(id);
+  return def && Array.isArray(def.anchors) && def.anchors.length
+    ? def.anchors
+    : DEFAULT_CUSTOM_ANCHORS;
+}
+
+export function getCustomShapeLabelPlacement(id) {
+  const def = getCustomShapeDefinition(id);
+  return def && def.labelPlacement === 'center' ? 'center' : 'below';
+}
+
+export async function loadCustomShapeLibraries() {
+  try {
+    const res = await fetch('/api/shape-libraries');
+    if (!res.ok) throw new Error('shape libraries unavailable');
+    const store = await res.json();
+    const libraries = Array.isArray(store.libraries) ? store.libraries : [];
+    st.customShapeLibraries = libraries;
+    st.customShapeDefs = new Map();
+    libraries.forEach((library) => {
+      (library.shapes || []).forEach((shape) => st.customShapeDefs.set(shape.id, shape));
+    });
+  } catch {
+    st.customShapeLibraries = [];
+    st.customShapeDefs = new Map();
+  }
+}
+
+export function renderCustomShapeBar() {
+  const bar = document.getElementById('customShapeBar');
+  const body = document.getElementById('customShapeBarBody');
+  if (!bar || !body) return;
+
+  body.innerHTML = '';
+  const libraries = st.customShapeLibraries || [];
+  const shapes = libraries.flatMap((library) =>
+    (library.shapes || []).map((shape) => ({ ...shape, libraryName: library.name })),
+  );
+  bar.classList.toggle('hidden', shapes.length === 0);
+
+  shapes.forEach((shape) => {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'custom-shape-btn';
+    btn.title = `${shape.libraryName || ''}${shape.libraryName ? ' · ' : ''}${shape.name}`;
+    btn.dataset.customShapeId = shape.id;
+
+    const img = document.createElement('img');
+    img.src = shape.imageSrc;
+    img.alt = '';
+    img.draggable = false;
+    btn.appendChild(img);
+
+    btn.addEventListener('click', () => {
+      window.dispatchEvent(new CustomEvent('diagram:setTool', {
+        detail: { tool: 'addNode', shape: `${CUSTOM_SHAPE_TOOL_PREFIX}${shape.id}` },
+      }));
+    });
+    body.appendChild(btn);
+  });
+}

package/dist/src/frontend/diagram/main.js

@@ -22,6 +22,7 @@ import { promptImageName } from './image-name-modal.js';
 import { showToast }       from './toast.js';
 import { t }               from './t.js';
 import { initEvidenceMode, toggleEvidenceMode } from './evidence.js';
+import { customShapeIdFromTool, isCustomShapeTool } from './custom-shapes.js';
 
 // ── Tool management ───────────────────────────────────────────────────────────
 
@@ -36,6 +37,12 @@ function setTool(tool, shape) {
   const key = tool === 'addNode' ? `addNode:${shape || st.pendingShape}` : tool;
   const btn = document.getElementById(TOOL_BTN_MAP[key]);
   if (btn) btn.classList.add('tool-active');
+  document.querySelectorAll('.custom-shape-btn').forEach((b) => {
+    b.classList.toggle(
+      'tool-active',
+      tool === 'addNode' && isCustomShapeTool(shape || st.pendingShape) && b.dataset.customShapeId === customShapeIdFromTool(shape || st.pendingShape),
+    );
+  });
 
   document.getElementById('vis-canvas').classList.toggle('cursor-crosshair', tool === 'addNode' || tool === 'addEdge');
 

package/dist/src/frontend/diagram/network.js

@@ -24,6 +24,7 @@ import { getNearestPort, getPortPosition, drawPortDots, drawPortEdge, distanceTo
 import { getLastFreeArrowStyle } from './edge-panel.js';
 import { getLastNodeStyle } from './node-panel.js';
 import { installUnlockHold } from './unlock-hold.js';
+import { CUSTOM_SHAPE_TYPE, customShapeIdFromTool, getCustomShapeDefaultSize, getCustomShapeDefinition } from './custom-shapes.js';
 
 // Module-level port-hover state — shared between initNetwork event handlers and
 // module-level helpers (_onAnchorSnapConnect).
@@ -102,14 +103,13 @@ export function initNetwork(savedNodes, savedEdges, edgesStraight = false) {
       enabled: false,
       addEdge(data, callback) {
         // Block edges from/to locked nodes or anchors (free-arrow endpoints).
-        // Also block when the target sits below the source in z-order — the
-        // mouseup handler turns that case into a free-arrow endpoint instead.
+        // Also block when the source sits on top of a lower-z target that
+        // contains it: that target is acting as a background surface, and the
+        // mouseup handler turns the gesture into a free-arrow endpoint instead.
         const fromNode = st.nodes.get(data.from) || {};
         const toNode   = st.nodes.get(data.to)   || {};
-        const fromZ    = st.canonicalOrder.indexOf(data.from);
-        const toZ      = st.canonicalOrder.indexOf(data.to);
-        const toBelow  = fromZ !== -1 && toZ !== -1 && toZ < fromZ;
-        if (fromNode.locked || toNode.locked || fromNode.shapeType === 'anchor' || toNode.shapeType === 'anchor' || toBelow) {
+        const targetContainsSource = lowerZTargetContainsSource(data.from, data.to);
+        if (fromNode.locked || toNode.locked || fromNode.shapeType === 'anchor' || toNode.shapeType === 'anchor' || targetContainsSource) {
           _addEdgeFromPort = null;
           setTimeout(() => { if (st.currentTool === 'addEdge') st.network.addEdgeMode(); }, 0);
           return;
@@ -761,14 +761,11 @@ export function initNetwork(savedNodes, savedEdges, edgesStraight = false) {
     // Locked targets are non-interactive: treat them exactly like empty canvas
     // so a free-arrow endpoint is created at the release point — matches the
     // behaviour of free arrows drawn over a locked shape (Path B).
-    // Also: if the target sits BELOW the source in z-order (e.g. a post-it on
-    // top of a background image), don't bind to it — the user is aiming at a
-    // point on top of the source's layer, not at the underlying shape.
+    // Also: if the source sits on top of a lower-z target that contains it
+    // (e.g. a post-it on a background image), don't bind to that background.
     const targetLocked = !!(targetData && targetData.locked);
-    const sourceZ      = st.canonicalOrder.indexOf(_addEdgeFromId);
-    const targetZ      = targetId ? st.canonicalOrder.indexOf(targetId) : -1;
-    const targetBelow  = targetId && sourceZ !== -1 && targetZ !== -1 && targetZ < sourceZ;
-    if (!targetId || targetLocked || targetBelow) {
+    const targetContainsSource = targetId && lowerZTargetContainsSource(_addEdgeFromId, targetId);
+    if (!targetId || targetLocked || targetContainsSource) {
       pushSnapshot();
       const cp       = st.network.DOMtoCanvas(pos);
       const anchorId = 'a' + Date.now();
@@ -1142,6 +1139,15 @@ function nodeContainsCanvasPoint(id, canvasPos) {
   return Math.abs(lx) <= W / 2 && Math.abs(ly) <= H / 2;
 }
 
+function lowerZTargetContainsSource(sourceId, targetId) {
+  if (!sourceId || !targetId) return false;
+  const sourceZ = st.canonicalOrder.indexOf(sourceId);
+  const targetZ = st.canonicalOrder.indexOf(targetId);
+  if (sourceZ === -1 || targetZ === -1 || targetZ >= sourceZ) return false;
+  const sourcePos = st.network && st.network.getPositions([sourceId])[sourceId];
+  return !!(sourcePos && nodeContainsCanvasPoint(targetId, sourcePos));
+}
+
 // Returns the topmost (highest z-order) node containing canvasPos.
 // Ignores anchor nodes and respects st.canonicalOrder.
 function topmostNodeAt(canvasPos) {
@@ -1269,29 +1275,34 @@ function onDoubleClick(params) {
   const srcEvent = params.event && params.event.srcEvent;
   const clientPos = srcEvent ? { x: srcEvent.clientX, y: srcEvent.clientY } : null;
   const labelEdgeId = edgeLabelAtCanvasPoint(params.pointer.canvas);
-  const nativeEdgeId = clientPos ? st.network.getEdgeAt(clientPos) : null;
-  const portEdge = nearestPortEdgeAt(params.pointer.canvas);
-  const edgeCandidates = [labelEdgeId, nativeEdgeId, portEdge && portEdge.id, ...params.edges]
-    .filter((id, index, list) => id && list.indexOf(id) === index)
-    .filter((id) => isEdgeInteractive(st.edges.get(id)));
-  const edgeId = edgeCandidates.reduce((bestId, id) => {
-    if (!bestId) return id;
-    return edgeDrawLevel(st.edges.get(id)) >= edgeDrawLevel(st.edges.get(bestId)) ? id : bestId;
-  }, null);
-
   const topNodeId = topmostNodeAt(params.pointer.canvas);
   const topNode = topNodeId && st.nodes.get(topNodeId);
   const canEditTopNode = topNode && !topNode.locked && topNode.shapeType !== 'anchor';
-  const topNodeWins = canEditTopNode && !labelEdgeId && (!edgeId || st.canonicalOrder.indexOf(topNodeId) >= edgeDrawLevel(st.edges.get(edgeId)));
 
-  if (topNodeWins) {
+  // Direct node double-clicks must edit the node. Dense port-edge diagrams can
+  // have many visual edges crossing a node; those should not steal the edit.
+  // The only exception is an actual edge-label hit, which is intentional.
+  if (canEditTopNode && !labelEdgeId) {
     st.selectedNodeIds = [topNodeId];
     st.selectedEdgeIds = [];
     st.network.setSelection({ nodes: st.selectedNodeIds, edges: [] });
     showNodePanel();
     hideEdgePanel();
     startLabelEdit();
-  } else if (edgeId) {
+    return;
+  }
+
+  const nativeEdgeId = clientPos ? st.network.getEdgeAt(clientPos) : null;
+  const portEdge = nearestPortEdgeAt(params.pointer.canvas);
+  const edgeCandidates = [labelEdgeId, nativeEdgeId, portEdge && portEdge.id, ...params.edges]
+    .filter((id, index, list) => id && list.indexOf(id) === index)
+    .filter((id) => isEdgeInteractive(st.edges.get(id)));
+  const edgeId = edgeCandidates.reduce((bestId, id) => {
+    if (!bestId) return id;
+    return edgeDrawLevel(st.edges.get(id)) >= edgeDrawLevel(st.edges.get(bestId)) ? id : bestId;
+  }, null);
+
+  if (edgeId) {
     st.selectedNodeIds = [];
     st.selectedEdgeIds = [edgeId];
     st.network.setSelection({ nodes: [], edges: [edgeId] });
@@ -1304,9 +1315,12 @@ function onDoubleClick(params) {
   } else if (st.currentTool === 'addNode') {
     pushSnapshot();
     const id         = 'n' + Date.now();
-    const defaults   = SHAPE_DEFAULTS[st.pendingShape] || [100, 40];
-    const fallbackColor = st.pendingShape === 'post-it' ? 'c-amber' : 'c-gray';
-    const lastStyle  = getLastNodeStyle(st.pendingShape);
+    const customShapeId = customShapeIdFromTool(st.pendingShape);
+    const shapeType = customShapeId ? CUSTOM_SHAPE_TYPE : st.pendingShape;
+    const customDef = customShapeId ? getCustomShapeDefinition(customShapeId) : null;
+    const defaults   = customShapeId ? getCustomShapeDefaultSize(customShapeId) : SHAPE_DEFAULTS[shapeType] || [100, 40];
+    const fallbackColor = shapeType === 'post-it' ? 'c-amber' : 'c-gray';
+    const lastStyle  = getLastNodeStyle(shapeType);
     const colorKey   = lastStyle.colorKey  || fallbackColor;
     const fontSize   = lastStyle.fontSize  || null;
     const textAlign  = lastStyle.textAlign  || null;
@@ -1314,13 +1328,13 @@ function onDoubleClick(params) {
     const rawPos     = params.pointer.canvas;
     const pos        = st.gridEnabled ? snapToGrid(rawPos.x, rawPos.y) : rawPos;
     st.nodes.add({
-      id, label: st.pendingShape === 'text-free' ? t('diagram.label_input.placeholder') : 'Node',
-      shapeType: st.pendingShape, colorKey,
+      id, label: shapeType === 'text-free' ? t('diagram.label_input.placeholder') : (customDef ? customDef.name : 'Node'),
+      shapeType, customShapeId: customShapeId || null, colorKey,
       nodeWidth: defaults[0], nodeHeight: defaults[1],
       fontSize, textAlign, textValign,
       rotation: 0, labelRotation: 0,
       x: pos.x, y: pos.y,
-      ...visNodeProps(st.pendingShape, colorKey, defaults[0], defaults[1], fontSize, textAlign, textValign),
+      ...visNodeProps(shapeType, colorKey, defaults[0], defaults[1], fontSize, textAlign, textValign),
     });
     markDirty();
     setTimeout(() => {
@@ -1467,28 +1481,22 @@ function onClickNode(params) {
   // passing it to getEdgeAt() causes a double-subtraction of the container rect and
   // returns null. Passing clientX/Y lets vis-network do its own pixel-perfect detection.
   if (params.nodes.length > 0) {
-    const clientPos = { x: params.event.srcEvent.clientX, y: params.event.srcEvent.clientY };
-    const nativeEdgeId = st.network.getEdgeAt(clientPos);
-    const portEdge = nearestPortEdgeAt(params.pointer.canvas);
-    const edgeId = nativeEdgeId || (portEdge && portEdge.id);
-
-    // First honour the app-managed z-order. vis-network may report an edge or a
-    // lower node at the click point; compare draw levels so the visibly top
-    // element gets the click.
+    const labelEdgeId = edgeLabelAtCanvasPoint(params.pointer.canvas);
     const top = topmostNodeAt(params.pointer.canvas);
     if (top) {
       const topNode = st.nodes.get(top);
-      const topLevel = st.canonicalOrder.indexOf(top);
-      const edgeLevel = edgeId ? edgeDrawLevel(st.edges.get(edgeId)) : -1;
-      if (topNode && !topNode.locked && topNode.shapeType !== 'anchor') {
-        if (!edgeId || topLevel >= edgeLevel) {
-          setTimeout(() => {
-            selectNodesFromClick(top, params.event.srcEvent);
-          }, 0);
-          return;
-        }
+      if (topNode && !topNode.locked && topNode.shapeType !== 'anchor' && !labelEdgeId) {
+        setTimeout(() => {
+          selectNodesFromClick(top, params.event.srcEvent);
+        }, 0);
+        return;
       }
     }
+
+    const clientPos = { x: params.event.srcEvent.clientX, y: params.event.srcEvent.clientY };
+    const nativeEdgeId = st.network.getEdgeAt(clientPos);
+    const portEdge = nearestPortEdgeAt(params.pointer.canvas);
+    const edgeId = labelEdgeId || nativeEdgeId || (portEdge && portEdge.id);
     if (edgeId) {
       const edge  = st.edges.get(edgeId);
       const fromN = edge && st.nodes.get(edge.from);

package/dist/src/frontend/diagram/node-rendering.js

@@ -6,6 +6,7 @@
 
 import { NODE_COLORS } from "./constants.js";
 import { st } from "./state.js";
+import { CUSTOM_SHAPE_TYPE, getCustomShapeDefinition } from "./custom-shapes.js";
 
 // Returns the color object for a key, checking runtime overrides first.
 function getNodeColor(colorKey) {
@@ -182,6 +183,19 @@ function nodeData(id, defaultW, defaultH, defaultColorKey) {
   };
 }
 
+function textLines(label) {
+  return label ? String(label).split("\n") : [];
+}
+
+export function customShapeImageOffsetY(node, label) {
+  const def = getCustomShapeDefinition(node && node.customShapeId);
+  if (!def || def.labelPlacement !== "below" || !label) return 0;
+  const fontSize = (node && node.fontSize) || 13;
+  const lines = textLines(label);
+  if (!lines.length) return 0;
+  return -(lines.length * fontSize * 1.3 + 8) / 2;
+}
+
 // ── Shape renderers ───────────────────────────────────────────────────────────
 
 export function makeBoxRenderer(colorKey) {
@@ -653,6 +667,86 @@ export function makeImageRenderer(colorKey) {
   };
 }
 
+export function makeCustomShapeRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const n = st.nodes && st.nodes.get(id);
+    const def = getCustomShapeDefinition(n && n.customShapeId);
+    const defaultW = def && def.width || 96;
+    const defaultH = def && def.height || 96;
+    const {
+      W,
+      H,
+      rotation,
+      labelRotation,
+      textAlign,
+      textValign,
+      fontSize,
+      c,
+    } = nodeData(id, defaultW, defaultH, colorKey || "c-gray");
+    const img = getCachedImage(def && def.imageSrc, () => st.network && st.network.redraw());
+    const labelBelow = def && def.labelPlacement === "below";
+    const lines = textLines(label);
+    const belowLabelH = labelBelow && lines.length ? lines.length * fontSize * 1.3 + 8 : 0;
+    const imageOffsetY = labelBelow ? -belowLabelH / 2 : 0;
+    const totalH = H + belowLabelH;
+    return {
+      drawNode() {
+        ctx.save();
+        ctx.translate(x, y);
+        ctx.rotate(rotation);
+
+        if (img) {
+          ctx.drawImage(img, -W / 2, imageOffsetY - H / 2, W, H);
+        } else {
+          ctx.fillStyle = visState.selected ? c.hbg : c.bg;
+          ctx.strokeStyle = visState.selected ? "#f97316" : c.border;
+          ctx.lineWidth = 1.5;
+          roundRect(ctx, -W / 2, imageOffsetY - H / 2, W, H, 4);
+          ctx.fill();
+          ctx.stroke();
+        }
+
+        if (visState.selected || visState.hover) {
+          ctx.strokeStyle = visState.selected ? "#f97316" : c.border;
+          ctx.lineWidth = visState.selected ? 2 : 1;
+          ctx.setLineDash([4, 3]);
+          roundRect(ctx, -W / 2, -totalH / 2, W, totalH, 4);
+          ctx.stroke();
+          ctx.setLineDash([]);
+        }
+
+        if (labelBelow && lines.length) {
+          ctx.save();
+          if (labelRotation) ctx.rotate(labelRotation);
+          ctx.font = `${fontSize}px system-ui,-apple-system,sans-serif`;
+          ctx.fillStyle = c.font;
+          ctx.textAlign = "center";
+          ctx.textBaseline = "top";
+          const lineH = fontSize * 1.3;
+          const startY = imageOffsetY + H / 2 + 4;
+          lines.forEach((line, i) => ctx.fillText(line, 0, startY + i * lineH));
+          ctx.restore();
+        } else {
+          drawLabel(
+            ctx,
+            label,
+            fontSize,
+            c.font,
+            textAlign,
+            textValign,
+            W,
+            H,
+            labelRotation,
+          );
+        }
+        drawLinkIndicator(ctx, id, W, H);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: totalH },
+    };
+  };
+}
+
 // ── Public API ────────────────────────────────────────────────────────────────
 
 // Returns the rendered height from vis-network internals (used by node-panel
@@ -703,6 +797,7 @@ const RENDERER_MAP = {
   "text-free": makeTextFreeRenderer,
   actor: makeActorRenderer,
   image: makeImageRenderer,
+  [CUSTOM_SHAPE_TYPE]: makeCustomShapeRenderer,
   anchor: makeAnchorRenderer,
 };
 
@@ -716,6 +811,7 @@ export const SHAPE_DEFAULTS = {
   "post-it": [120, 100],
   "text-free": [80, 30],
   image: [160, 120],
+  [CUSTOM_SHAPE_TYPE]: [96, 96],
   anchor: [8, 8],
 };
 

package/dist/src/frontend/diagram/persistence.js

@@ -126,6 +126,7 @@ export async function saveDiagram() {
     .map((n) => ({
       id: n.id, label: n.label,
       shapeType: n.shapeType || 'box', colorKey: n.colorKey || 'c-gray',
+      customShapeId: n.customShapeId || null,
       kind: n.kind || null, renderAs: n.renderAs || null,
       description: n.description || null,
       evidence: Array.isArray(n.evidence) ? n.evidence : null,

package/dist/src/frontend/diagram/ports.js

@@ -7,7 +7,8 @@
 // vis-network's native rendering unchanged.
 
 import { st } from './state.js';
-import { SHAPE_DEFAULTS } from './node-rendering.js';
+import { customShapeImageOffsetY, SHAPE_DEFAULTS } from './node-rendering.js';
+import { CUSTOM_SHAPE_TYPE, getCustomShapeAnchors } from './custom-shapes.js';
 
 /**
  * Splits `text` into lines that each fit within `maxWidth` canvas units.
@@ -83,20 +84,52 @@ function nodeGeometry(nodeId) {
   const W = n.nodeWidth  || defaults[0];
   // 'circle' is always square (H = W); 'ellipse' uses its own height.
   const H = shapeType === 'circle' ? W : (n.nodeHeight || defaults[1]);
-  return { cx: pos.x, cy: pos.y, W, H, rotation: n.rotation || 0, shapeType };
+  const imageOffsetY = shapeType === CUSTOM_SHAPE_TYPE ? customShapeImageOffsetY(n, n.label) : 0;
+  return { cx: pos.x, cy: pos.y, W, H, rotation: n.rotation || 0, shapeType, customShapeId: n.customShapeId || null, imageOffsetY };
+}
+
+export function getPortKeys(nodeId) {
+  const n = st.nodes && st.nodes.get(nodeId);
+  if (n && n.shapeType === CUSTOM_SHAPE_TYPE) {
+    return getCustomShapeAnchors(n.customShapeId).map((anchor) => anchor.id);
+  }
+  return PORT_KEYS;
+}
+
+function customPortOffset(customShapeId, portKey) {
+  const anchor = getCustomShapeAnchors(customShapeId).find((item) => item.id === portKey);
+  if (!anchor) return null;
+  return [(anchor.x - 0.5) * 2, (anchor.y - 0.5) * 2];
+}
+
+function normalForPort(shapeType, customShapeId, portKey) {
+  if (shapeType === CUSTOM_SHAPE_TYPE) {
+    const offset = customPortOffset(customShapeId, portKey) || [0, -1];
+    const len = Math.hypot(offset[0], offset[1]) || 1;
+    return [offset[0] / len, offset[1] / len];
+  }
+  return PORT_NORMALS[portKey] || [0, -1];
+}
+
+function controlNormalForEdge(nodeId, portKey) {
+  const n = st.nodes && st.nodes.get(nodeId);
+  return normalForPort(n && n.shapeType, n && n.customShapeId, portKey);
 }
 
 /** Returns the world-space {x, y} of a port on a node. */
 export function getPortPosition(nodeId, portKey) {
   const geo = nodeGeometry(nodeId);
   if (!geo) return null;
-  const { cx, cy, W, H, rotation, shapeType } = geo;
-  const offsets = shapeType === 'database'      ? PORT_OFFSETS_DATABASE
+  const { cx, cy, W, H, rotation, shapeType, customShapeId, imageOffsetY } = geo;
+  const offsets = shapeType === CUSTOM_SHAPE_TYPE ? null
+               : shapeType === 'database'      ? PORT_OFFSETS_DATABASE
                : CIRCULAR_SHAPES.has(shapeType) ? PORT_OFFSETS_CIRC
                : PORT_OFFSETS_RECT;
-  const [ox, oy] = offsets[portKey] || [0, 0];
+  const [ox, oy] = shapeType === CUSTOM_SHAPE_TYPE
+    ? customPortOffset(customShapeId, portKey) || [0, 0]
+    : offsets[portKey] || [0, 0];
   let dx = ox * W / 2;
-  let dy = oy * H / 2;
+  let dy = oy * H / 2 + imageOffsetY;
   if (rotation) {
     const cos = Math.cos(rotation), sin = Math.sin(rotation);
     [dx, dy] = [dx * cos - dy * sin, dx * sin + dy * cos];
@@ -107,7 +140,7 @@ export function getPortPosition(nodeId, portKey) {
 /** Returns the port key whose position is closest to `canvasPos` (world coords). */
 export function getNearestPort(nodeId, canvasPos) {
   let minD2 = Infinity, nearest = 'N';
-  for (const key of PORT_KEYS) {
+  for (const key of getPortKeys(nodeId)) {
     const p = getPortPosition(nodeId, key);
     if (!p) continue;
     const d2 = (canvasPos.x - p.x) ** 2 + (canvasPos.y - p.y) ** 2;
@@ -119,12 +152,12 @@ export function getNearestPort(nodeId, canvasPos) {
 // ── Port dot visualisation ────────────────────────────────────────────────────
 
 /**
- * Draws 8 port hint dots for `nodeId` in the vis-network afterDrawing context.
+ * Draws port hint dots for `nodeId` in the vis-network afterDrawing context.
  * `highlightedPort` (if any) is rendered larger and fully orange.
  */
 export function drawPortDots(ctx, nodeId, highlightedPort) {
   if (st.exportingPng) return;
-  for (const key of PORT_KEYS) {
+  for (const key of getPortKeys(nodeId)) {
     const p = getPortPosition(nodeId, key);
     if (!p) continue;
     const hl = key === highlightedPort;
@@ -219,8 +252,8 @@ export function drawPortEdge(ctx, edgeData) {
   if (useBezier) {
     const dist    = Math.hypot(toPos.x - fromPos.x, toPos.y - fromPos.y);
     const tension = Math.max(60, dist * 0.4);
-    const fn = PORT_NORMALS[edgeData.fromPort];
-    const tn = PORT_NORMALS[edgeData.toPort];
+    const fn = controlNormalForEdge(edgeData.from, edgeData.fromPort);
+    const tn = controlNormalForEdge(edgeData.to, edgeData.toPort);
     cp1 = { x: fromPos.x + fn[0] * tension, y: fromPos.y + fn[1] * tension };
     cp2 = { x: toPos.x   + tn[0] * tension, y: toPos.y   + tn[1] * tension };
   }
@@ -358,8 +391,8 @@ export function distanceToPortEdge(edgeData, p) {
   if (!st.edgesStraight && edgeData.fromPort && !fromIsAnch && edgeData.toPort && !toIsAnch) {
     const dist    = Math.hypot(toPos.x - fromPos.x, toPos.y - fromPos.y);
     const tension = Math.max(60, dist * 0.4);
-    const fn = PORT_NORMALS[edgeData.fromPort];
-    const tn = PORT_NORMALS[edgeData.toPort];
+    const fn = controlNormalForEdge(edgeData.from, edgeData.fromPort);
+    const tn = controlNormalForEdge(edgeData.to, edgeData.toPort);
     const cp1 = { x: fromPos.x + fn[0] * tension, y: fromPos.y + fn[1] * tension };
     const cp2 = { x: toPos.x   + tn[0] * tension, y: toPos.y   + tn[1] * tension };
     return _distToBezier(p, fromPos, cp1, cp2, toPos);

package/dist/src/frontend/diagram/state.js

@@ -28,6 +28,8 @@ export const st = {
   edgesStraight: false,  // when true, all edges use smooth: disabled (straight lines)
   resizeSymmetric: false, // when true, center is fixed during resize; when false, opposite corner is fixed
   nodeColorOverrides: {}, // colorKey → {bg, border, font, hbg, hborder} — set from config at boot
+  customShapeLibraries: [], // loaded from /api/shape-libraries
+  customShapeDefs: new Map(), // shape id → custom shape definition
   edgeLabelCanvasPos: {}, // edgeId → {x, y} canvas coords of last drawn label, used by label editor
   edgeLabelBBox: {},     // edgeId → {cx, cy, w, h, rotation} canvas world coords, used by label resize
   freeArrowFirstPoint: null, // addEdge two-click flow: {x, y} canvas coords of first click, or null

package/dist/src/frontend/diagram.html

@@ -286,6 +286,57 @@
         background: #082f49;
         color: #e0f2fe;
       }
+      #customShapeBar {
+        position: absolute;
+        left: 0.75rem;
+        bottom: 0.75rem;
+        z-index: 9;
+        display: flex;
+        align-items: center;
+        max-width: min(42rem, calc(100% - 1.5rem));
+        padding: 0.35rem;
+        gap: 0.25rem;
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        background: rgba(255, 255, 255, 0.96);
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.10);
+      }
+      .dark #customShapeBar {
+        border-color: #374151;
+        background: rgba(31, 41, 55, 0.96);
+      }
+      #customShapeBar.hidden {
+        display: none;
+      }
+      #customShapeBarBody {
+        display: flex;
+        gap: 0.25rem;
+        overflow-x: auto;
+        scrollbar-width: thin;
+      }
+      .custom-shape-btn {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 2.25rem;
+        height: 2.25rem;
+        border-radius: 0.375rem;
+        border: 1px solid transparent;
+        background: transparent;
+        flex: 0 0 auto;
+      }
+      .custom-shape-btn:hover {
+        background: #f3f4f6;
+      }
+      .dark .custom-shape-btn:hover {
+        background: #111827;
+      }
+      .custom-shape-btn img {
+        max-width: 1.7rem;
+        max-height: 1.7rem;
+        object-fit: contain;
+        pointer-events: none;
+      }
     </style>
   </head>
   <body
@@ -445,6 +496,13 @@
           <path d="M1 9.5 L4 6.5 L6.5 9 L9 7 L13 10.5"/>
         </svg>
       </button>
+      <a
+        href="/shape-editor"
+        class="tool-btn"
+        data-i18n-title="diagram.toolbar.shape_editor"
+      >
+        ✦
+      </a>
       <div class="w-px h-6 bg-gray-200 dark:bg-gray-700 mx-0.5"></div>
 
       <button
@@ -641,6 +699,10 @@
       <div class="relative flex-1 overflow-hidden bg-gray-50 dark:bg-gray-950">
         <div id="vis-canvas" class="w-full h-full"></div>
 
+        <div id="customShapeBar" class="hidden">
+          <div id="customShapeBarBody"></div>
+        </div>
+
         <!-- Debug overlay layer -->
         <div id="debugLayer"></div>
 
@@ -1308,6 +1370,7 @@
       import { NODE_COLORS, NODE_L_RATIOS, DEFAULT_NODE_PALETTE, DEFAULT_EDGE_PALETTE, deriveNodeColors } from '/diagram/constants.js';
       import { st } from '/diagram/state.js';
       import { loadDiagramList } from '/diagram/persistence.js';
+      import { loadCustomShapeLibraries, renderCustomShapeBar } from '/diagram/custom-shapes.js';
       (async () => {
         // diagramNodePalette: array of 15 bg hex strings (positional, matching DEFAULT_NODE_PALETTE)
         // diagramEdgePalette: array of hex strings
@@ -1355,6 +1418,8 @@
           btn.title = hex;
           ec.appendChild(btn);
         });
+        await loadCustomShapeLibraries();
+        renderCustomShapeBar();
         window.applyI18n();
         loadDiagramList();
       })();

package/dist/src/frontend/i18n/en.json

@@ -409,6 +409,7 @@
   "diagram.toolbar.postit": "Post-it (P)",
   "diagram.toolbar.text_free": "Free text (T)",
   "diagram.toolbar.image": "Image — double-click on canvas to select a file, or paste (⌘V) from clipboard",
+  "diagram.toolbar.shape_editor": "Custom shape editor",
   "diagram.toolbar.arrow": "Arrow (F)",
   "diagram.toolbar.delete": "Delete (Del)",
   "diagram.toolbar.align_guides": "Alignment guides — highlights same-type shape alignment",