living-documentation 3.5.0 → 3.7.0

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

@@ -0,0 +1,168 @@
+// ── Network initialisation & vis.js event handlers ────────────────────────────
+// Creates the vis.js Network, patches _drawNodes for canonical z-order,
+// and wires all network-level events.
+
+import { st, markDirty } from './state.js';
+import { visNodeProps, SHAPE_DEFAULTS }   from './node-rendering.js';
+import { visEdgeProps }   from './edge-rendering.js';
+import { showNodePanel, hideNodePanel } from './node-panel.js';
+import { showEdgePanel, hideEdgePanel } from './edge-panel.js';
+import { startLabelEdit, startEdgeLabelEdit, commitLabelEdit, hideLabelInput } from './label-editor.js';
+import { updateSelectionOverlay, hideSelectionOverlay } from './selection-overlay.js';
+import { drawGrid, onDragEnd } from './grid.js';
+import { drawDebugOverlay }    from './debug.js';
+import { updateZoomDisplay }   from './zoom.js';
+
+export function initNetwork(savedNodes, savedEdges) {
+  const container = document.getElementById('vis-canvas');
+
+  st.nodes = new vis.DataSet(
+    savedNodes.map((n) => ({
+      ...n,
+      ...visNodeProps(n.shapeType || 'box', n.colorKey || 'c-gray', n.nodeWidth, n.nodeHeight, n.fontSize, n.textAlign, n.textValign),
+    }))
+  );
+  st.edges = new vis.DataSet(
+    savedEdges.map((e) => ({
+      ...e,
+      ...visEdgeProps(e.arrowDir ?? 'to', e.dashes ?? false),
+      ...(e.fontSize ? { font: { size: e.fontSize, align: 'middle', color: '#6b7280' } } : {}),
+    }))
+  );
+
+  const options = {
+    physics: {
+      enabled: st.physicsEnabled,
+      stabilization: { enabled: false },
+      barnesHut: { gravitationalConstant: -3000, centralGravity: 0.3, springLength: 150, springConstant: 0.04, damping: 0.09 },
+    },
+    interaction: { hover: true, navigationButtons: false, keyboard: false, multiselect: true },
+    nodes: { font: { size: 13, face: 'system-ui,-apple-system,sans-serif' }, borderWidth: 1.5, borderWidthSelected: 2.5, shadow: false, widthConstraint: { minimum: 60 }, heightConstraint: { minimum: 28 } },
+    edges: { smooth: { type: 'continuous' }, color: { color: '#a8a29e', highlight: '#f97316', hover: '#f97316' }, width: 1.5, selectionWidth: 2.5, font: { size: 11, align: 'middle', color: '#6b7280' } },
+    manipulation: {
+      enabled: false,
+      addEdge(data, callback) {
+        data.id       = 'e' + Date.now();
+        data.arrowDir = 'to';
+        data.dashes   = false;
+        Object.assign(data, visEdgeProps('to', false));
+        callback(data);
+        markDirty();
+        setTimeout(() => st.network.addEdgeMode(), 0);
+      },
+    },
+  };
+
+  if (st.network) st.network.destroy();
+  st.network = new vis.Network(container, { nodes: st.nodes, edges: st.edges }, options);
+
+  // ── Z-order patch ──────────────────────────────────────────────────────────
+  // vis.js renders in 3 passes (normal → selected → hovered), which breaks
+  // user-defined stacking. We replace _drawNodes with a single pass in
+  // canonicalOrder so hover/selection never override the user's z-order.
+  st.canonicalOrder = [...st.network.body.nodeIndices];
+  st.network.renderer._drawNodes = function (ctx, alwaysShow = false) {
+    const bodyNodes = this.body.nodes;
+    const margin    = 20;
+    const topLeft     = this.canvas.DOMtoCanvas({ x: -margin, y: -margin });
+    const bottomRight = this.canvas.DOMtoCanvas({ x: this.canvas.frame.canvas.clientWidth + margin, y: this.canvas.frame.canvas.clientHeight + margin });
+    const viewableArea = { top: topLeft.y, left: topLeft.x, bottom: bottomRight.y, right: bottomRight.x };
+    const drawExternalLabelCallbacks = [];
+
+    for (const id of st.canonicalOrder) {
+      const node = bodyNodes[id];
+      if (!node) continue;
+      if (alwaysShow === true || node.isBoundingBoxOverlappingWith(viewableArea) === true) {
+        const r = node.draw(ctx);
+        // All shapes are ctxRenderer (shape:'custom') and draw their own labels.
+        // Skip drawExternalLabel entirely to avoid double-rendering.
+      } else {
+        node.updateBoundingBox(ctx, node.selected);
+      }
+    }
+    return { drawExternalLabels() { for (const draw of drawExternalLabelCallbacks) draw(); } };
+  };
+
+  // Keep canonicalOrder in sync with DataSet add/remove events
+  st.nodes.on('add', (_, { items }) => {
+    const existing = new Set(st.canonicalOrder);
+    items.forEach((id) => { if (!existing.has(id)) st.canonicalOrder.push(id); });
+  });
+  st.nodes.on('remove', (_, { items }) => {
+    const removed = new Set(items);
+    st.canonicalOrder = st.canonicalOrder.filter((id) => !removed.has(id));
+  });
+
+  st.network.on('doubleClick',  onDoubleClick);
+  st.network.on('selectNode',   onSelectNode);
+  st.network.on('deselectNode', onDeselectAll);
+  st.network.on('selectEdge',   onSelectEdge);
+  st.network.on('deselectEdge', onDeselectAll);
+  st.network.on('zoom',         updateZoomDisplay);
+  st.network.on('dragEnd',      onDragEnd);
+  st.network.on('beforeDrawing', drawGrid);
+  st.network.on('afterDrawing',  updateSelectionOverlay);
+  st.network.on('afterDrawing',  () => drawDebugOverlay());
+
+  document.getElementById('emptyState').classList.add('hidden');
+  updateZoomDisplay();
+}
+
+// ── Network event handlers ────────────────────────────────────────────────────
+
+function onDoubleClick(params) {
+  if (params.nodes.length > 0) {
+    st.selectedNodeIds = params.nodes;
+    st.network.selectNodes(st.selectedNodeIds);
+    showNodePanel();
+    startLabelEdit();
+  } else if (params.edges.length > 0 && params.nodes.length === 0) {
+    st.selectedEdgeIds = [params.edges[0]];
+    showEdgePanel();
+    startEdgeLabelEdit();
+  } else if (st.currentTool === 'addNode') {
+    const id       = 'n' + Date.now();
+    const defaults = SHAPE_DEFAULTS[st.pendingShape] || [100, 40];
+    const defaultColor = st.pendingShape === 'post-it' ? 'c-amber' : 'c-gray';
+    st.nodes.add({
+      id, label: st.pendingShape === 'text-free' ? 'Texte' : 'Node',
+      shapeType: st.pendingShape, colorKey: defaultColor,
+      nodeWidth: defaults[0], nodeHeight: defaults[1],
+      fontSize: null, rotation: 0, labelRotation: 0,
+      x: params.pointer.canvas.x, y: params.pointer.canvas.y,
+      ...visNodeProps(st.pendingShape, defaultColor, defaults[0], defaults[1], null, null, null),
+    });
+    markDirty();
+    setTimeout(() => {
+      st.network.selectNodes([id]);
+      st.selectedNodeIds = [id];
+      showNodePanel();
+      startLabelEdit();
+    }, 50);
+  }
+}
+
+function onSelectNode(params) {
+  st.selectedNodeIds = params.nodes;
+  st.selectedEdgeIds = [];
+  hideEdgePanel();
+  showNodePanel();
+}
+
+function onSelectEdge(params) {
+  if (st.selectedNodeIds.length > 0) return; // node takes priority
+  st.selectedEdgeIds = params.edges;
+  st.selectedNodeIds = [];
+  hideNodePanel();
+  showEdgePanel();
+}
+
+function onDeselectAll() {
+  st.selectedNodeIds = [];
+  st.selectedEdgeIds = [];
+  hideNodePanel();
+  hideEdgePanel();
+  commitLabelEdit();
+  hideLabelInput();
+  hideSelectionOverlay();
+}

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

@@ -0,0 +1,171 @@
+// ── Node panel ────────────────────────────────────────────────────────────────
+// Floating formatting toolbar for selected nodes (color, font, alignment, z-order).
+
+import { st, markDirty } from './state.js';
+import { SHAPE_DEFAULTS } from './node-rendering.js';
+
+// All shapes are ctxRenderers — vis-network never re-reads the closure after
+// nodes.update(). Force refreshNeeded + redraw so the new colorKey/fontSize/
+// textAlign/textValign values are picked up on the next draw call via st.nodes.get(id).
+function forceRedraw() {
+  st.selectedNodeIds.forEach((id) => {
+    const bn = st.network && st.network.body.nodes[id];
+    if (bn) bn.refreshNeeded = true;
+  });
+  if (st.network) st.network.redraw();
+}
+
+export function showNodePanel() {
+  document.getElementById('nodePanel').classList.remove('hidden');
+}
+
+export function hideNodePanel() {
+  document.getElementById('nodePanel').classList.add('hidden');
+}
+
+export function setNodeColor(colorKey) {
+  if (!st.selectedNodeIds.length) return;
+  st.selectedNodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (!n) return;
+    st.nodes.update({ id, colorKey });
+  });
+  forceRedraw();
+  markDirty();
+}
+
+export function changeNodeFontSize(delta) {
+  if (!st.selectedNodeIds.length) return;
+  st.selectedNodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (!n) return;
+    const newSize = Math.max(8, Math.min(48, (n.fontSize || 13) + delta));
+    st.nodes.update({ id, fontSize: newSize });
+  });
+  forceRedraw();
+  markDirty();
+}
+
+export function setTextAlign(align) {
+  if (!st.selectedNodeIds.length) return;
+  st.selectedNodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (!n) return;
+    st.nodes.update({ id, textAlign: align });
+  });
+  forceRedraw();
+  markDirty();
+}
+
+export function setTextValign(valign) {
+  if (!st.selectedNodeIds.length) return;
+  st.selectedNodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (!n) return;
+    st.nodes.update({ id, textValign: valign });
+  });
+  forceRedraw();
+  markDirty();
+}
+
+// ── Stamp (format painter) ────────────────────────────────────────────────────
+// Uses a transparent DOM overlay (#stampOverlay) that intercepts canvas clicks
+// during stamp mode. This bypasses vis-network's event system entirely, avoiding
+// the deselectNode/click ordering problems that make st.activeStamp unreliable.
+
+const STAMP_BTNS = { color: 'btnStampColor', rotation: 'btnStampRotation', fontSize: 'btnStampFontSize' };
+
+export function activateStamp(type) {
+  if (!st.stampTargetIds.length) return; // targets were saved on mousedown
+  st.activeStamp = type;
+  const overlay = document.getElementById('stampOverlay');
+  overlay.style.display = 'block';
+  Object.entries(STAMP_BTNS).forEach(([t, id]) =>
+    document.getElementById(id).classList.toggle('tool-active', t === type)
+  );
+}
+
+export function cancelStamp() {
+  st.activeStamp = null;
+  st.stampTargetIds = [];
+  document.getElementById('stampOverlay').style.display = 'none';
+  Object.values(STAMP_BTNS).forEach((id) =>
+    document.getElementById(id).classList.remove('tool-active')
+  );
+}
+
+function applyStamp(sourceId) {
+  const source = st.nodes.get(sourceId);
+  if (!source || !st.activeStamp || !st.stampTargetIds.length) return;
+  const type    = st.activeStamp;
+  const targets = [...st.stampTargetIds]; // snapshot before cancelStamp clears the array
+  cancelStamp();
+
+  targets.forEach((id) => {
+    if (id === sourceId) return;
+    const target = st.nodes.get(id);
+    if (!target) return;
+    if (type === 'color')    st.nodes.update({ id, colorKey: source.colorKey || 'c-gray' });
+    if (type === 'rotation') st.nodes.update({ id, rotation: source.rotation || 0 });
+    if (type === 'fontSize') st.nodes.update({ id, fontSize: source.fontSize || 13 });
+    const bn = st.network && st.network.body.nodes[id];
+    if (bn) bn.refreshNeeded = true;
+  });
+  if (st.network) st.network.redraw();
+  markDirty();
+}
+
+// getNodeAt() is unreliable for shape:'custom' (bounding box near-zero).
+// Manual AABB hit test using DOMtoCanvas + node dimensions, topmost node first.
+function getNodeAtDOMPoint(domX, domY) {
+  if (!st.network || !st.nodes) return undefined;
+  const cp = st.network.DOMtoCanvas({ x: domX, y: domY });
+  for (let i = st.canonicalOrder.length - 1; i >= 0; i--) {
+    const id = st.canonicalOrder[i];
+    const n  = st.nodes.get(id);
+    const bn = st.network.body.nodes[id];
+    if (!n || !bn) continue;
+    const defaults = SHAPE_DEFAULTS[n.shapeType] || [100, 40];
+    const w = n.nodeWidth  || defaults[0];
+    const h = n.nodeHeight || defaults[1];
+    const rot = n.rotation || 0;
+    let hw, hh;
+    if (rot === 0) {
+      hw = w / 2; hh = h / 2;
+    } else {
+      const cos = Math.abs(Math.cos(rot)); const sin = Math.abs(Math.sin(rot));
+      hw = (w * cos + h * sin) / 2;
+      hh = (w * sin + h * cos) / 2;
+    }
+    if (Math.abs(cp.x - bn.x) <= hw && Math.abs(cp.y - bn.y) <= hh) return id;
+  }
+  return undefined;
+}
+
+// Wire the stamp overlay click.
+document.getElementById('stampOverlay').addEventListener('click', (e) => {
+  if (!st.activeStamp || !st.network) return;
+  const rect   = document.getElementById('vis-canvas').getBoundingClientRect();
+  const nodeId = getNodeAtDOMPoint(e.clientX - rect.left, e.clientY - rect.top);
+  if (nodeId !== undefined) {
+    applyStamp(nodeId);
+  } else {
+    cancelStamp();
+  }
+});
+
+export function changeZOrder(direction) {
+  // direction: +1 = bring to front (last in canonicalOrder = drawn on top)
+  //            -1 = send to back   (first in canonicalOrder = drawn below)
+  if (!st.selectedNodeIds.length) return;
+  st.selectedNodeIds.forEach((id) => {
+    const idx = st.canonicalOrder.indexOf(id);
+    if (idx === -1) return;
+    st.canonicalOrder.splice(idx, 1);
+    if (direction > 0) st.canonicalOrder.push(id);
+    else               st.canonicalOrder.unshift(id);
+  });
+  st.network.redraw();
+  st.network.selectNodes(st.selectedNodeIds);
+  markDirty();
+}

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

@@ -0,0 +1,336 @@
+// ── Node rendering ────────────────────────────────────────────────────────────
+// All shapes are ctxRenderers so rotation (ctx.rotate) works uniformly.
+// Each renderer reads live node data from st.nodes.get(id) on every draw call
+// (vis-network caches the ctxRenderer reference and never re-reads it from the
+// DataSet, so dimensions/rotation/alignment must be fetched at draw time).
+
+import { NODE_COLORS } from './constants.js';
+import { st } from './state.js';
+
+// ── Drawing helpers ───────────────────────────────────────────────────────────
+
+// Draw multi-line label centred at (0,0) in the current (possibly rotated) ctx.
+// labelRotation is applied around the label's own centre (independent of shape rotation).
+function drawLabel(ctx, label, fontSize, color, textAlign, textValign, W, H, labelRotation) {
+  if (!label) return;
+  const pad = 8;
+  ctx.save();
+  ctx.font         = `${fontSize}px system-ui,-apple-system,sans-serif`;
+  ctx.fillStyle    = color;
+  ctx.textBaseline = 'middle';
+
+  let xPos = 0;
+  if (textAlign === 'left')       { ctx.textAlign = 'left';   xPos = W ? -W / 2 + pad : -40; }
+  else if (textAlign === 'right') { ctx.textAlign = 'right';  xPos = W ? W / 2  - pad : 40;  }
+  else                            { ctx.textAlign = 'center'; xPos = 0; }
+
+  let yOff = 0;
+  if (W && H) {
+    if (textValign === 'top')         yOff = -(H / 2 - fontSize / 2 - pad);
+    else if (textValign === 'bottom') yOff =   H / 2 - fontSize / 2 - pad;
+  }
+
+  const lines  = String(label).split('\n');
+  const lineH  = fontSize * 1.3;
+  const startY = yOff - (lines.length - 1) * lineH / 2;
+
+  // Apply independent label rotation around the label centre.
+  if (labelRotation) ctx.rotate(labelRotation);
+
+  lines.forEach((line, i) => ctx.fillText(line, xPos, startY + i * lineH));
+  ctx.restore();
+}
+
+// Polyfill-safe rounded rectangle (ctx.roundRect not universally available).
+function roundRect(ctx, x, y, w, h, r) {
+  r = Math.min(r, w / 2, h / 2);
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + w - r, y);
+  ctx.quadraticCurveTo(x + w, y, x + w, y + r);
+  ctx.lineTo(x + w, y + h - r);
+  ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
+  ctx.lineTo(x + r, y + h);
+  ctx.quadraticCurveTo(x, y + h, x, y + h - r);
+  ctx.lineTo(x, y + r);
+  ctx.quadraticCurveTo(x, y, x + r, y);
+  ctx.closePath();
+}
+
+// Read ALL live node data from the DataSet on every draw call.
+// vis-network caches the ctxRenderer closure and never re-reads it after
+// nodes.update(), so colour, font size, dimensions, rotation, and alignment
+// must all be fetched here to reflect the latest values.
+function nodeData(id, defaultW, defaultH, defaultColorKey) {
+  const n        = st.nodes && st.nodes.get(id);
+  const colorKey = (n && n.colorKey) || defaultColorKey || 'c-gray';
+  return {
+    W:             (n && n.nodeWidth)      || defaultW,
+    H:             (n && n.nodeHeight)     || defaultH,
+    rotation:      (n && n.rotation)       || 0,
+    labelRotation: (n && n.labelRotation)  || 0,
+    textAlign:     (n && n.textAlign)      || 'center',
+    textValign:    (n && n.textValign)     || 'middle',
+    fontSize:      (n && n.fontSize)       || 13,
+    colorKey,
+    c: NODE_COLORS[colorKey] || NODE_COLORS['c-gray'],
+  };
+}
+
+// ── Shape renderers ───────────────────────────────────────────────────────────
+
+export function makeBoxRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 100, 40, colorKey);
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 1.5;
+        roundRect(ctx, -W / 2, -H / 2, W, H, 4);
+        ctx.fill(); ctx.stroke();
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, H, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+export function makeEllipseRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 110, 50, colorKey);
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 1.5;
+        ctx.beginPath(); ctx.ellipse(0, 0, W / 2, H / 2, 0, 0, Math.PI * 2);
+        ctx.fill(); ctx.stroke();
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, H, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+export function makeCircleRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 55, 55, colorKey);
+    const R = W / 2;
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 1.5;
+        ctx.beginPath(); ctx.arc(0, 0, R, 0, Math.PI * 2);
+        ctx.fill(); ctx.stroke();
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, W, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: W },
+    };
+  };
+}
+
+export function makeDatabaseRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 50, 70, colorKey);
+    const rx = W / 2;
+    const ry = Math.max(H * 0.12, 6);
+    const bodyTop    = -H / 2 + ry;
+    const bodyBottom =  H / 2 - ry;
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 1.5;
+        ctx.fillRect(-rx, bodyTop, W, bodyBottom - bodyTop);
+        ctx.beginPath(); ctx.ellipse(0, bodyBottom, rx, ry, 0, 0, Math.PI * 2);
+        ctx.fill(); ctx.stroke();
+        ctx.beginPath();
+        ctx.moveTo(-rx, bodyTop); ctx.lineTo(-rx, bodyBottom);
+        ctx.moveTo( rx, bodyTop); ctx.lineTo( rx, bodyBottom);
+        ctx.stroke();
+        ctx.beginPath(); ctx.ellipse(0, bodyTop, rx, ry, 0, 0, Math.PI * 2);
+        ctx.fill(); ctx.stroke();
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, H, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+// Post-IT: sticky note with folded top-right corner.
+export function makePostItRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 120, 100, colorKey || 'c-amber');
+    const fold = Math.min(W, H) * 0.18;
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 1.5;
+        ctx.beginPath();
+        ctx.moveTo(-W / 2,        -H / 2);
+        ctx.lineTo( W / 2 - fold, -H / 2);
+        ctx.lineTo( W / 2,        -H / 2 + fold);
+        ctx.lineTo( W / 2,         H / 2);
+        ctx.lineTo(-W / 2,         H / 2);
+        ctx.closePath();
+        ctx.fill(); ctx.stroke();
+        ctx.globalAlpha = 0.3;
+        ctx.fillStyle   = c.border;
+        ctx.beginPath();
+        ctx.moveTo(W / 2 - fold, -H / 2);
+        ctx.lineTo(W / 2,        -H / 2 + fold);
+        ctx.lineTo(W / 2 - fold, -H / 2 + fold);
+        ctx.closePath();
+        ctx.fill();
+        ctx.globalAlpha = 1;
+        ctx.beginPath();
+        ctx.moveTo(W / 2 - fold, -H / 2);
+        ctx.lineTo(W / 2 - fold, -H / 2 + fold);
+        ctx.lineTo(W / 2,        -H / 2 + fold);
+        ctx.stroke();
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, H, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+// Free Text: no visible border or background — just the label.
+export function makeTextFreeRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, textAlign, textValign, fontSize, c } = nodeData(id, 80, 30, colorKey);
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        if (visState.selected || visState.hover) {
+          ctx.strokeStyle = '#f97316';
+          ctx.lineWidth   = 1;
+          ctx.setLineDash([4, 3]);
+          roundRect(ctx, -W / 2, -H / 2, W, H, 3);
+          ctx.stroke();
+          ctx.setLineDash([]);
+        }
+        drawLabel(ctx, label, fontSize, c.font, textAlign, textValign, W, H, labelRotation);
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+// ── Actor (stick figure) ──────────────────────────────────────────────────────
+const ACTOR_W0 = 30;
+const ACTOR_H0 = 52;
+
+export function makeActorRenderer(colorKey) {
+  return function ({ ctx, x, y, id, state: visState, label }) {
+    const { W, H, rotation, labelRotation, fontSize, c } = nodeData(id, ACTOR_W0, ACTOR_H0, colorKey);
+    const sx = W / ACTOR_W0;
+    const sy = H / ACTOR_H0;
+    return {
+      drawNode() {
+        ctx.save(); ctx.translate(x, y); ctx.rotate(rotation);
+        ctx.strokeStyle = visState.selected ? '#f97316' : c.border;
+        ctx.fillStyle   = visState.selected ? c.hbg     : c.bg;
+        ctx.lineWidth   = 2;
+        ctx.lineCap     = 'round';
+        ctx.beginPath(); ctx.arc(0, -20 * sy, 8 * sy, 0, Math.PI * 2); ctx.fill(); ctx.stroke();
+        ctx.beginPath(); ctx.moveTo(0, -12 * sy); ctx.lineTo(0, 8 * sy); ctx.stroke();
+        ctx.beginPath(); ctx.moveTo(-13 * sx, -3 * sy); ctx.lineTo(13 * sx, -3 * sy); ctx.stroke();
+        ctx.beginPath(); ctx.moveTo(0, 8 * sy); ctx.lineTo(-10 * sx, 24 * sy); ctx.stroke();
+        ctx.beginPath(); ctx.moveTo(0, 8 * sy); ctx.lineTo( 10 * sx, 24 * sy); ctx.stroke();
+        // Label below figure (rotates with the actor)
+        if (label) {
+          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 lines  = String(label).split('\n');
+          const lineH  = fontSize * 1.3;
+          const startY = 24 * sy + 4;
+          lines.forEach((line, i) => ctx.fillText(line, 0, startY + i * lineH));
+          ctx.restore();
+        }
+        ctx.restore();
+      },
+      nodeDimensions: { width: W, height: H },
+    };
+  };
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+// Returns the rendered height from vis-network internals (used by node-panel
+// for vadjust calculations — legacy, kept for API compat).
+export function getActualNodeHeight(id) {
+  if (!st.network) return null;
+  const bn = st.network.body.nodes[id];
+  return bn && bn.shape && bn.shape.height ? bn.shape.height : null;
+}
+
+// Kept for backward compat (called by node-panel but irrelevant for ctxRenderers).
+export function computeVadjust() { return 0; }
+
+const RENDERER_MAP = {
+  box:        makeBoxRenderer,
+  ellipse:    makeEllipseRenderer,
+  circle:     makeCircleRenderer,
+  database:   makeDatabaseRenderer,
+  'post-it':  makePostItRenderer,
+  'text-free':makeTextFreeRenderer,
+  actor:      makeActorRenderer,
+};
+
+// Default dimensions per shape type (used when nodeWidth/nodeHeight are null).
+export const SHAPE_DEFAULTS = {
+  box:        [100, 40],
+  ellipse:    [110, 50],
+  circle:     [55,  55],
+  database:   [50,  70],
+  actor:      [30,  52],
+  'post-it':  [120, 100],
+  'text-free':[80,  30],
+};
+
+// Builds the full vis.js node property object.
+// All shapes are rendered via ctxRenderer so rotation works uniformly.
+export function visNodeProps(shapeType, colorKey, nodeWidth, nodeHeight, fontSize, textAlign, _textValign) {
+  const c    = NODE_COLORS[colorKey] || NODE_COLORS['c-gray'];
+  const size = fontSize  || 13;
+  const align = textAlign || 'center';
+
+  const colorP = {
+    color: {
+      background: c.bg,   border: c.border,
+      highlight:  { background: c.hbg, border: c.hborder },
+      hover:      { background: c.hbg, border: c.hborder },
+    },
+    font: { color: c.font, size, face: 'system-ui,-apple-system,sans-serif', align },
+  };
+
+  const sizeP = {};
+  if (nodeWidth)  sizeP.widthConstraint  = { minimum: nodeWidth,  maximum: nodeWidth  };
+  if (nodeHeight) sizeP.heightConstraint = { minimum: nodeHeight, maximum: nodeHeight };
+
+  const factory = RENDERER_MAP[shapeType];
+  if (factory) {
+    return { shape: 'custom', ctxRenderer: factory(colorKey), ...colorP, ...sizeP };
+  }
+  // Unknown shape — fall back to box
+  return { shape: 'custom', ctxRenderer: makeBoxRenderer(colorKey), ...colorP, ...sizeP };
+}