vizcraft 0.2.2 → 1.0.0

package/dist/builder.js

@@ -1,13 +1,112 @@
+import { OVERLAY_RUNTIME_DIRTY } from './types';
 import { DEFAULT_VIZ_CSS } from './styles';
 import { defaultCoreAnimationRegistry } from './animations';
 import { defaultCoreOverlayRegistry } from './overlays';
+import { OverlayBuilder } from './overlayBuilder';
 import { createRuntimePatchCtx, patchRuntime, } from './runtimePatcher';
+import { computeEdgePath, computeEdgeEndpoints } from './edgePaths';
+import { resolveEdgeLabelPosition, collectEdgeLabels } from './edgeLabels';
+/**
+ * Sanitise a CSS color value for use as a suffix in an SVG marker `id`.
+ * Non-alphanumeric characters are replaced with underscores.
+ */
+function colorToMarkerSuffix(color) {
+    return color.replace(/[^a-zA-Z0-9]/g, '_');
+}
+/** Return the marker id to use for a marker type with an optional custom stroke and position. */
+function markerIdFor(markerType, stroke, position = 'end') {
+    if (markerType === 'none')
+        return '';
+    const base = `viz-${markerType}`;
+    const suffix = position === 'start' ? '-start' : '';
+    return stroke
+        ? `${base}${suffix}-${colorToMarkerSuffix(stroke)}`
+        : `${base}${suffix}`;
+}
+/** @deprecated Use markerIdFor instead. Kept for backward compatibility. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function arrowMarkerIdFor(stroke) {
+    return markerIdFor('arrow', stroke);
+}
+/**
+ * Generate SVG markup for a single marker definition.
+ * @param markerType The type of marker
+ * @param color Fill color for the marker (or stroke for open markers)
+ * @param id The marker element id
+ * @param position Whether this marker is used at the start or end of an edge
+ */
+/** Escape a string for safe use inside an XML/SVG attribute value. */
+function escapeXmlAttr(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function generateMarkerSvg(markerType, color, id, position = 'end') {
+    if (markerType === 'none')
+        return '';
+    // Sanitise color for safe interpolation into SVG attribute strings
+    const safeColor = escapeXmlAttr(color);
+    // Common marker properties
+    const viewBox = '0 0 10 10';
+    // refX=9 positions the marker tip at the path endpoint.
+    // Start markers use orient="auto-start-reverse" which flips the marker,
+    // so the same refX=9 keeps the tip at the node boundary.
+    const refX = '9';
+    const refY = '5'; // Center vertically
+    const markerWidth = '10';
+    const markerHeight = '10';
+    let content = '';
+    switch (markerType) {
+        case 'arrow':
+            // Filled triangle
+            content = `<polygon points="0,2 10,5 0,8" fill="${safeColor}" />`;
+            break;
+        case 'arrowOpen':
+            // Open V-shape triangle (white fill hides the edge line behind the marker)
+            content = `<polyline points="0,2 10,5 0,8" fill="white" stroke="${safeColor}" stroke-width="1.5" stroke-linejoin="miter" />`;
+            break;
+        case 'diamond':
+            // Filled diamond
+            content = `<polygon points="0,5 5,2 10,5 5,8" fill="${safeColor}" />`;
+            break;
+        case 'diamondOpen':
+            // Open diamond (white fill hides the edge line behind the marker)
+            content = `<polygon points="0,5 5,2 10,5 5,8" fill="white" stroke="${safeColor}" stroke-width="1.5" />`;
+            break;
+        case 'circle':
+            // Filled circle
+            content = `<circle cx="5" cy="5" r="3" fill="${safeColor}" />`;
+            break;
+        case 'circleOpen':
+            // Open circle (white fill hides the edge line behind the marker)
+            content = `<circle cx="5" cy="5" r="3" fill="white" stroke="${safeColor}" stroke-width="1.5" />`;
+            break;
+        case 'square':
+            // Filled square
+            content = `<rect x="2" y="2" width="6" height="6" fill="${safeColor}" />`;
+            break;
+        case 'bar':
+            // Perpendicular line (T shape)
+            content = `<line x1="5" y1="1" x2="5" y2="9" stroke="${safeColor}" stroke-width="2" stroke-linecap="round" />`;
+            break;
+        case 'halfArrow':
+            // Single-sided arrow (top half of a filled triangle)
+            content = `<polygon points="0,2 10,5 0,5" fill="${safeColor}" />`;
+            break;
+        default:
+            return '';
+    }
+    const orient = position === 'start' ? 'auto-start-reverse' : 'auto';
+    return `<marker id="${id}" viewBox="${viewBox}" refX="${refX}" refY="${refY}" markerWidth="${markerWidth}" markerHeight="${markerHeight}" orient="${orient}">${content}</marker>`;
+}
 import { buildAnimationSpec, } from './anim/animationBuilder';
 import { createBuilderPlayback, } from './anim/playback';
 import { getAdapterExtensions } from './anim/specExtensions';
 const runtimePatchCtxBySvg = new WeakMap();
 const autoplayControllerByContainer = new WeakMap();
-import { applyShapeGeometry, computeNodeAnchor, effectivePos, getShapeBehavior, shapeSvgMarkup, } from './shapes';
+import { applyShapeGeometry, effectivePos, getShapeBehavior, shapeSvgMarkup, } from './shapes';
 function setSvgAttributes(el, attrs) {
     Object.entries(attrs).forEach(([key, value]) => {
         if (value === undefined) {
@@ -35,15 +134,6 @@ function animFallbackStyleEntries(params) {
         .filter(([, v]) => v !== undefined)
         .map(([k, v]) => [`--viz-anim-${k}`, String(v)]);
 }
-function computeEdgeEndpoints(start, end, edge) {
-    const anchor = edge.anchor ?? 'boundary';
-    // Use effective positions of start/end nodes to calculate anchors
-    const startPos = effectivePos(start);
-    const endPos = effectivePos(end);
-    const startAnchor = computeNodeAnchor(start, endPos, anchor);
-    const endAnchor = computeNodeAnchor(end, startPos, anchor);
-    return { start: startAnchor, end: endAnchor };
-}
 class VizBuilderImpl {
     _viewBox = { w: 800, h: 600 };
     _nodes = new Map();
@@ -75,14 +165,16 @@ class VizBuilderImpl {
         this._gridConfig = { cols, rows, padding };
         return this;
     }
-    /**
-     * Adds an overlay to the scene.
-     * @param id The ID of the overlay
-     * @param params The parameters of the overlay
-     * @param key The key of the overlay
-     * @returns The builder
-     */
-    overlay(id, params, key) {
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function') {
+            const overlay = new OverlayBuilder();
+            arg1(overlay);
+            this._overlays.push(...overlay.build());
+            return this;
+        }
+        const id = arg1;
+        const params = arg2;
+        const key = arg3;
         this._overlays.push({ id, params, key });
         return this;
     }
@@ -274,6 +366,92 @@ class VizBuilderImpl {
             runtimePatchCtxBySvg.set(svg, ctx);
         }
         patchRuntime(scene, ctx);
+        // Keep overlays in sync during animation playback.
+        //
+        // Animations flush via `patchRuntime()` (to avoid full re-mounts). Nodes/edges
+        // are patched via `runtimePatcher`, but overlays are registry-rendered and
+        // need an explicit reconcile pass to reflect animated `spec.params` changes.
+        const overlayLayer = svg.querySelector('[data-viz-layer="overlays"]') ||
+            svg.querySelector('.viz-layer-overlays');
+        if (overlayLayer) {
+            const overlays = scene.overlays ?? [];
+            const nodesById = new Map(scene.nodes.map((n) => [n.id, n]));
+            const edgesById = new Map(scene.edges.map((e) => [e.id, e]));
+            const svgNS = 'http://www.w3.org/2000/svg';
+            // 1) Map existing overlay groups
+            const existingOverlayGroups = Array.from(overlayLayer.children).filter((el) => el.tagName === 'g');
+            const existingOverlaysMap = new Map();
+            existingOverlayGroups.forEach((el) => {
+                const id = el.getAttribute('data-overlay-id');
+                if (id)
+                    existingOverlaysMap.set(id, el);
+            });
+            // Fast decision: if nothing is dirty and keys match, skip overlay work.
+            const overlayKeyCountMatches = overlays.length === existingOverlaysMap.size;
+            let needsOverlayPass = !overlayKeyCountMatches;
+            const dirtyOverlays = [];
+            if (!needsOverlayPass) {
+                for (const spec of overlays) {
+                    const uniqueKey = spec.key || spec.id;
+                    if (!existingOverlaysMap.has(uniqueKey)) {
+                        needsOverlayPass = true;
+                        break;
+                    }
+                    if (spec[OVERLAY_RUNTIME_DIRTY]) {
+                        dirtyOverlays.push(spec);
+                    }
+                }
+            }
+            if (!needsOverlayPass && dirtyOverlays.length === 0)
+                return;
+            const processedOverlayIds = new Set();
+            // 2) Render/update overlays
+            const toUpdate = needsOverlayPass ? overlays : dirtyOverlays;
+            toUpdate.forEach((spec) => {
+                const renderer = defaultCoreOverlayRegistry.get(spec.id);
+                if (!renderer)
+                    return;
+                const uniqueKey = spec.key || spec.id;
+                processedOverlayIds.add(uniqueKey);
+                let group = existingOverlaysMap.get(uniqueKey);
+                if (!group) {
+                    group = document.createElementNS(svgNS, 'g');
+                    group.setAttribute('data-overlay-id', uniqueKey);
+                    group.setAttribute('data-viz-role', 'overlay-group');
+                    overlayLayer.appendChild(group);
+                }
+                // Keep wrapper class in sync even when reusing an existing group.
+                const expectedClass = `viz-overlay-${spec.id}${spec.className ? ` ${spec.className}` : ''}`;
+                const currentClass = group.getAttribute('class');
+                if (currentClass !== expectedClass) {
+                    group.setAttribute('class', expectedClass);
+                }
+                const overlayCtx = {
+                    spec,
+                    nodesById,
+                    edgesById,
+                    scene,
+                    registry: defaultCoreOverlayRegistry,
+                };
+                if (renderer.update) {
+                    renderer.update(overlayCtx, group);
+                }
+                else {
+                    group.innerHTML = renderer.render(overlayCtx);
+                }
+                // Clear dirty flag after successful update.
+                delete spec[OVERLAY_RUNTIME_DIRTY];
+            });
+            // 3) Remove stale overlays only if keys may have changed.
+            if (!overlayKeyCountMatches) {
+                existingOverlayGroups.forEach((el) => {
+                    const id = el.getAttribute('data-overlay-id');
+                    if (id && !processedOverlayIds.has(id)) {
+                        el.remove();
+                    }
+                });
+            }
+        }
     }
     /**
      * Renders the scene to the DOM.
@@ -296,20 +474,49 @@ class VizBuilderImpl {
             const style = document.createElement('style');
             style.textContent = DEFAULT_VIZ_CSS;
             svg.appendChild(style);
-            // Defs
+            // Defs — marker definitions only for marker types/positions actually used
             const defs = document.createElementNS(svgNS, 'defs');
-            const marker = document.createElementNS(svgNS, 'marker');
-            marker.setAttribute('id', 'viz-arrow');
-            marker.setAttribute('markerWidth', '10');
-            marker.setAttribute('markerHeight', '7');
-            marker.setAttribute('refX', '9');
-            marker.setAttribute('refY', '3.5');
-            marker.setAttribute('orient', 'auto');
-            const poly = document.createElementNS(svgNS, 'polygon');
-            poly.setAttribute('points', '0 0, 10 3.5, 0 7');
-            poly.setAttribute('fill', 'currentColor');
-            marker.appendChild(poly);
-            defs.appendChild(marker);
+            // Collect the set of (markerType, color, position) tuples actually needed
+            // and pre-generate their SVG content strings.
+            const neededMarkers = new Set();
+            const markerSvgById = new Map();
+            edges.forEach((e) => {
+                const stroke = e.style?.stroke;
+                if (e.markerEnd && e.markerEnd !== 'none') {
+                    const mid = markerIdFor(e.markerEnd, stroke, 'end');
+                    if (!neededMarkers.has(mid)) {
+                        neededMarkers.add(mid);
+                        markerSvgById.set(mid, generateMarkerSvg(e.markerEnd, stroke ?? 'currentColor', mid, 'end'));
+                    }
+                }
+                if (e.markerStart && e.markerStart !== 'none') {
+                    const mid = markerIdFor(e.markerStart, stroke, 'start');
+                    if (!neededMarkers.has(mid)) {
+                        neededMarkers.add(mid);
+                        markerSvgById.set(mid, generateMarkerSvg(e.markerStart, stroke ?? 'currentColor', mid, 'start'));
+                    }
+                }
+            });
+            neededMarkers.forEach((mid) => {
+                const markerEl = document.createElementNS(svgNS, 'marker');
+                markerEl.setAttribute('id', mid);
+                markerEl.setAttribute('viewBox', '0 0 10 10');
+                markerEl.setAttribute('markerWidth', '10');
+                markerEl.setAttribute('markerHeight', '10');
+                markerEl.setAttribute('refX', '9');
+                markerEl.setAttribute('refY', '5');
+                const isStart = mid.includes('-start');
+                markerEl.setAttribute('orient', isStart ? 'auto-start-reverse' : 'auto');
+                const tmp = document.createElementNS(svgNS, 'svg');
+                tmp.innerHTML = markerSvgById.get(mid) ?? '';
+                const parsed = tmp.querySelector('marker');
+                if (parsed) {
+                    while (parsed.firstChild) {
+                        markerEl.appendChild(parsed.firstChild);
+                    }
+                }
+                defs.appendChild(markerEl);
+            });
             svg.appendChild(defs);
             // Layers
             const edgeLayer = document.createElementNS(svgNS, 'g');
@@ -361,10 +568,10 @@ class VizBuilderImpl {
                 group.setAttribute('data-viz-role', 'edge-group');
                 edgeLayer.appendChild(group);
                 // Initial creation of children
-                const line = document.createElementNS(svgNS, 'line');
-                line.setAttribute('class', 'viz-edge');
-                line.setAttribute('data-viz-role', 'edge-line');
-                group.appendChild(line);
+                const path = document.createElementNS(svgNS, 'path');
+                path.setAttribute('class', 'viz-edge');
+                path.setAttribute('data-viz-role', 'edge-line');
+                group.appendChild(path);
                 // Optional parts created on demand later, but structure expected
             }
             // Compute Classes & Styles
@@ -397,6 +604,7 @@ class VizBuilderImpl {
             group.setAttribute('class', classes);
             // Use effective positions (handles runtime overrides internally via helper)
             const endpoints = computeEdgeEndpoints(start, end, edge);
+            const edgePath = computeEdgePath(endpoints.start, endpoints.end, edge.routing, edge.waypoints);
             // Apply Edge Runtime Overrides
             if (edge.runtime?.opacity !== undefined) {
                 group.style.opacity = String(edge.runtime.opacity);
@@ -404,7 +612,7 @@ class VizBuilderImpl {
             else {
                 group.style.removeProperty('opacity');
             }
-            // Update Line
+            // Update Path
             const line = group.querySelector('[data-viz-role="edge-line"]') ||
                 group.querySelector('.viz-edge');
             if (!line)
@@ -418,29 +626,51 @@ class VizBuilderImpl {
                 line.style.removeProperty('stroke-dashoffset');
                 line.removeAttribute('stroke-dashoffset');
             }
-            line.setAttribute('x1', String(endpoints.start.x));
-            line.setAttribute('y1', String(endpoints.start.y));
-            line.setAttribute('x2', String(endpoints.end.x));
-            line.setAttribute('y2', String(endpoints.end.y));
-            line.setAttribute('stroke', 'currentColor');
-            if (edge.markerEnd === 'arrow') {
-                line.setAttribute('marker-end', 'url(#viz-arrow)');
+            line.setAttribute('d', edgePath.d);
+            // Update marker-end
+            if (edge.markerEnd && edge.markerEnd !== 'none') {
+                const mid = markerIdFor(edge.markerEnd, edge.style?.stroke, 'end');
+                line.setAttribute('marker-end', `url(#${mid})`);
             }
             else {
                 line.removeAttribute('marker-end');
             }
+            // Update marker-start
+            if (edge.markerStart && edge.markerStart !== 'none') {
+                const mid = markerIdFor(edge.markerStart, edge.style?.stroke, 'start');
+                line.setAttribute('marker-start', `url(#${mid})`);
+            }
+            else {
+                line.removeAttribute('marker-start');
+            }
+            // Per-edge style overrides (inline style wins over CSS class defaults)
+            if (edge.style?.stroke !== undefined) {
+                line.style.stroke = edge.style.stroke;
+            }
+            else {
+                line.style.removeProperty('stroke');
+            }
+            if (edge.style?.strokeWidth !== undefined)
+                line.style.strokeWidth = String(edge.style.strokeWidth);
+            else
+                line.style.removeProperty('stroke-width');
+            if (edge.style?.fill !== undefined)
+                line.style.fill = edge.style.fill;
+            else
+                line.style.removeProperty('fill');
+            if (edge.style?.opacity !== undefined)
+                line.style.opacity = String(edge.style.opacity);
+            else
+                line.style.removeProperty('opacity');
             const oldHit = group.querySelector('[data-viz-role="edge-hit"]') ||
                 group.querySelector('.viz-edge-hit');
             if (oldHit)
                 oldHit.remove();
             if (edge.hitArea || edge.onClick) {
-                const hit = document.createElementNS(svgNS, 'line');
+                const hit = document.createElementNS(svgNS, 'path');
                 hit.setAttribute('class', 'viz-edge-hit'); // Add class for selection
                 hit.setAttribute('data-viz-role', 'edge-hit');
-                hit.setAttribute('x1', String(endpoints.start.x));
-                hit.setAttribute('y1', String(endpoints.start.y));
-                hit.setAttribute('x2', String(endpoints.end.x));
-                hit.setAttribute('y2', String(endpoints.end.y));
+                hit.setAttribute('d', edgePath.d);
                 hit.setAttribute('stroke', 'transparent');
                 hit.setAttribute('stroke-width', String(edge.hitArea || 10));
                 hit.style.cursor = edge.onClick ? 'pointer' : '';
@@ -452,24 +682,25 @@ class VizBuilderImpl {
                 }
                 group.appendChild(hit);
             }
-            // Label (Recreate vs Update)
-            const oldLabel = group.querySelector('[data-viz-role="edge-label"]') ||
-                group.querySelector('.viz-edge-label');
-            if (oldLabel)
-                oldLabel.remove();
-            if (edge.label) {
+            // Labels (remove all old, re-create from labels[])
+            group
+                .querySelectorAll('[data-viz-role="edge-label"],.viz-edge-label')
+                .forEach((el) => el.remove());
+            const allLabels = collectEdgeLabels(edge);
+            allLabels.forEach((lbl, idx) => {
+                const pos = resolveEdgeLabelPosition(lbl, edgePath);
                 const text = document.createElementNS(svgNS, 'text');
-                const mx = (endpoints.start.x + endpoints.end.x) / 2 + (edge.label.dx || 0);
-                const my = (endpoints.start.y + endpoints.end.y) / 2 + (edge.label.dy || 0);
-                text.setAttribute('x', String(mx));
-                text.setAttribute('y', String(my));
-                text.setAttribute('class', `viz-edge-label ${edge.label.className || ''}`);
+                text.setAttribute('x', String(pos.x));
+                text.setAttribute('y', String(pos.y));
+                text.setAttribute('class', `viz-edge-label ${lbl.className || ''}`);
                 text.setAttribute('data-viz-role', 'edge-label');
+                text.setAttribute('data-label-index', String(idx));
+                text.setAttribute('data-label-position', lbl.position);
                 text.setAttribute('text-anchor', 'middle');
                 text.setAttribute('dominant-baseline', 'middle');
-                text.textContent = edge.label.text;
+                text.textContent = lbl.text;
                 group.appendChild(text);
-            }
+            });
         });
         // Remove stale edges
         existingEdgeGroups.forEach((el) => {
@@ -479,7 +710,24 @@ class VizBuilderImpl {
             }
         });
         // --- 2. Reconcile Nodes ---
-        const existingNodeGroups = Array.from(nodeLayer.children).filter((el) => el.tagName === 'g');
+        // Build parent→children map for container grouping
+        const childrenByParentDOM = new Map();
+        const rootNodesDOM = [];
+        nodes.forEach((n) => {
+            if (n.parentId) {
+                let arr = childrenByParentDOM.get(n.parentId);
+                if (!arr) {
+                    arr = [];
+                    childrenByParentDOM.set(n.parentId, arr);
+                }
+                arr.push(n);
+            }
+            else {
+                rootNodesDOM.push(n);
+            }
+        });
+        // Collect ALL existing node groups (including nested inside containers)
+        const existingNodeGroups = Array.from(nodeLayer.querySelectorAll('g[data-viz-role="node-group"]'));
         const existingNodesMap = new Map();
         existingNodeGroups.forEach((el) => {
             const id = el.getAttribute('data-id');
@@ -487,17 +735,22 @@ class VizBuilderImpl {
                 existingNodesMap.set(id, el);
         });
         const processedNodeIds = new Set();
-        nodes.forEach((node) => {
+        const reconcileNodeDOM = (node, parentGroup) => {
             processedNodeIds.add(node.id);
             let group = existingNodesMap.get(node.id);
             if (!group) {
                 group = document.createElementNS(svgNS, 'g');
                 group.setAttribute('data-id', node.id);
                 group.setAttribute('data-viz-role', 'node-group');
-                nodeLayer.appendChild(group);
+                parentGroup.appendChild(group);
+            }
+            else if (group.parentElement !== parentGroup) {
+                // Re-parent if the node moved to/from a container
+                parentGroup.appendChild(group);
             }
+            const isContainer = !!node.container;
             // Calculate Anim Classes
-            let classes = `viz-node-group ${node.className || ''}`;
+            let classes = `viz-node-group${isContainer ? ' viz-container' : ''} ${node.className || ''}`;
             group.removeAttribute('style');
             if (node.animations) {
                 node.animations.forEach((spec) => {
@@ -541,8 +794,6 @@ class VizBuilderImpl {
             group.style.cursor = node.onClick ? 'pointer' : '';
             // Shape (Update geometry)
             const { x, y } = effectivePos(node);
-            // Ideally we reuse the shape element if the kind hasn't changed.
-            // Assuming kind rarely changes for same ID.
             let shape = group.querySelector('[data-viz-role="node-shape"]') ||
                 group.querySelector('.viz-node-shape');
             const behavior = getShapeBehavior(node.shape);
@@ -553,9 +804,8 @@ class VizBuilderImpl {
                 shape = document.createElementNS(svgNS, expectedTag);
                 shape.setAttribute('class', 'viz-node-shape');
                 shape.setAttribute('data-viz-role', 'node-shape');
-                group.prepend(shape); // Shape always at bottom
+                group.prepend(shape);
             }
-            // Update Shape Attributes
             applyShapeGeometry(shape, node.shape, { x, y });
             setSvgAttributes(shape, {
                 fill: node.style?.fill ?? 'none',
@@ -563,7 +813,35 @@ class VizBuilderImpl {
                 'stroke-width': node.style?.strokeWidth ?? 2,
                 opacity: node.runtime?.opacity ?? node.style?.opacity,
             });
-            // Label (Recreate for simplicity as usually just text/pos changes)
+            // Container header line
+            if (isContainer &&
+                node.container.headerHeight &&
+                'w' in node.shape &&
+                'h' in node.shape) {
+                const sw = node.shape.w;
+                const sh = node.shape.h;
+                const headerY = y - sh / 2 + node.container.headerHeight;
+                let headerLine = group.querySelector('[data-viz-role="container-header"]');
+                if (!headerLine) {
+                    headerLine = document.createElementNS(svgNS, 'line');
+                    headerLine.setAttribute('class', 'viz-container-header');
+                    headerLine.setAttribute('data-viz-role', 'container-header');
+                    group.appendChild(headerLine);
+                }
+                headerLine.setAttribute('x1', String(x - sw / 2));
+                headerLine.setAttribute('y1', String(headerY));
+                headerLine.setAttribute('x2', String(x + sw / 2));
+                headerLine.setAttribute('y2', String(headerY));
+                headerLine.setAttribute('stroke', node.style?.stroke ?? '#111');
+                headerLine.setAttribute('stroke-width', String(node.style?.strokeWidth ?? 2));
+            }
+            else {
+                // Remove stale header line if no longer a container with headerHeight
+                const staleHeader = group.querySelector('[data-viz-role="container-header"]');
+                if (staleHeader)
+                    staleHeader.remove();
+            }
+            // Label
             let label = group.querySelector('[data-viz-role="node-label"]') ||
                 group.querySelector('.viz-node-label');
             if (!label && node.label) {
@@ -573,13 +851,21 @@ class VizBuilderImpl {
                 group.appendChild(label);
             }
             if (node.label) {
-                const lx = x + (node.label.dx || 0);
-                const ly = y + (node.label.dy || 0);
+                let lx = x + (node.label.dx || 0);
+                let ly = y + (node.label.dy || 0);
+                // If container with headerHeight, center label in header area
+                if (isContainer &&
+                    node.container.headerHeight &&
+                    'h' in node.shape &&
+                    !node.label.dy) {
+                    const sh = node.shape.h;
+                    ly = y - sh / 2 + node.container.headerHeight / 2;
+                    lx = x + (node.label.dx || 0);
+                }
                 label.setAttribute('x', String(lx));
                 label.setAttribute('y', String(ly));
                 label.setAttribute('text-anchor', node.label.textAnchor || 'middle');
                 label.setAttribute('dominant-baseline', node.label.dominantBaseline || 'middle');
-                // Update class carefully to preserve 'viz-node-label'
                 label.setAttribute('class', `viz-node-label ${node.label.className || ''}`);
                 label.setAttribute('data-viz-role', 'node-label');
                 setSvgAttributes(label, {
@@ -592,8 +878,45 @@ class VizBuilderImpl {
             else if (label) {
                 label.remove();
             }
-        });
-        // Remove stale nodes
+            // Ports — render small circles at each explicit port position.
+            // Remove stale ports first, then recreate from current spec.
+            const oldPorts = group.querySelectorAll('[data-viz-role="port"]');
+            oldPorts.forEach((el) => el.remove());
+            if (node.ports && node.ports.length > 0) {
+                node.ports.forEach((port) => {
+                    const portEl = document.createElementNS(svgNS, 'circle');
+                    portEl.setAttribute('cx', String(x + port.offset.x));
+                    portEl.setAttribute('cy', String(y + port.offset.y));
+                    portEl.setAttribute('r', '4');
+                    portEl.setAttribute('class', 'viz-port');
+                    portEl.setAttribute('data-viz-role', 'port');
+                    portEl.setAttribute('data-node', node.id);
+                    portEl.setAttribute('data-port', port.id);
+                    group.appendChild(portEl);
+                });
+            }
+            // Container children
+            const children = childrenByParentDOM.get(node.id);
+            if (children && children.length > 0) {
+                let childrenGroup = group.querySelector(':scope > [data-viz-role="container-children"]');
+                if (!childrenGroup) {
+                    childrenGroup = document.createElementNS(svgNS, 'g');
+                    childrenGroup.setAttribute('class', 'viz-container-children');
+                    childrenGroup.setAttribute('data-viz-role', 'container-children');
+                    group.appendChild(childrenGroup);
+                }
+                children.forEach((child) => reconcileNodeDOM(child, childrenGroup));
+            }
+            else {
+                // Remove stale children group
+                const staleChildren = group.querySelector(':scope > [data-viz-role="container-children"]');
+                if (staleChildren)
+                    staleChildren.remove();
+            }
+        };
+        // Reconcile root nodes only; children are reconciled recursively
+        rootNodesDOM.forEach((node) => reconcileNodeDOM(node, nodeLayer));
+        // Remove stale nodes (from anywhere in the tree)
         existingNodeGroups.forEach((el) => {
             const id = el.getAttribute('data-id');
             if (id && !processedNodeIds.has(id)) {
@@ -620,15 +943,17 @@ class VizBuilderImpl {
                     if (!group) {
                         group = document.createElementNS(svgNS, 'g');
                         group.setAttribute('data-overlay-id', uniqueKey);
-                        group.setAttribute('class', `viz-overlay-${spec.id}`);
                         group.setAttribute('data-viz-role', 'overlay-group');
                         overlayLayer.appendChild(group);
                     }
+                    // Keep wrapper class in sync even when reusing an existing group.
+                    group.setAttribute('class', `viz-overlay-${spec.id}${spec.className ? ` ${spec.className}` : ''}`);
                     const ctx = {
                         spec,
                         nodesById,
                         edgesById: new Map(edges.map((e) => [e.id, e])),
                         scene,
+                        registry: defaultCoreOverlayRegistry,
                     };
                     if (renderer.update) {
                         renderer.update(ctx, group);
@@ -663,12 +988,29 @@ class VizBuilderImpl {
         let svgContent = `<svg viewBox="0 0 ${viewBox.w} ${viewBox.h}" xmlns="http://www.w3.org/2000/svg">`;
         // Inject Styles
         svgContent += `<style>${DEFAULT_VIZ_CSS}</style>`;
-        // Defs (Arrow Marker)
+        // Defs (Marker definitions for all marker types)
+        svgContent += `
+        <defs>`;
+        // Only generate marker defs for types/positions actually used by edges
+        const markerDefinitions = new Set();
+        edges.forEach((e) => {
+            const stroke = e.style?.stroke;
+            if (e.markerEnd && e.markerEnd !== 'none') {
+                const mid = markerIdFor(e.markerEnd, stroke, 'end');
+                if (!markerDefinitions.has(mid)) {
+                    markerDefinitions.add(mid);
+                    svgContent += generateMarkerSvg(e.markerEnd, stroke ?? 'currentColor', mid, 'end');
+                }
+            }
+            if (e.markerStart && e.markerStart !== 'none') {
+                const mid = markerIdFor(e.markerStart, stroke, 'start');
+                if (!markerDefinitions.has(mid)) {
+                    markerDefinitions.add(mid);
+                    svgContent += generateMarkerSvg(e.markerStart, stroke ?? 'currentColor', mid, 'start');
+                }
+            }
+        });
         svgContent += `
-        <defs>
-          <marker id="viz-arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
-            <polygon points="0 0, 10 3.5, 0 7" fill="currentColor" />
-          </marker>
         </defs>`;
         // Render Edges
         svgContent += '<g class="viz-layer-edges" data-viz-layer="edges">';
@@ -704,8 +1046,14 @@ class VizBuilderImpl {
                     }
                 });
             }
-            const markerEnd = edge.markerEnd === 'arrow' ? 'marker-end="url(#viz-arrow)"' : '';
+            const markerEnd = edge.markerEnd && edge.markerEnd !== 'none'
+                ? `marker-end="url(#${markerIdFor(edge.markerEnd, edge.style?.stroke, 'end')})"`
+                : '';
+            const markerStart = edge.markerStart && edge.markerStart !== 'none'
+                ? `marker-start="url(#${markerIdFor(edge.markerStart, edge.style?.stroke, 'start')})"`
+                : '';
             const endpoints = computeEdgeEndpoints(start, end, edge);
+            const edgePath = computeEdgePath(endpoints.start, endpoints.end, edge.routing, edge.waypoints);
             // Runtime overrides for SVG export
             let runtimeStyle = '';
             if (edge.runtime?.opacity !== undefined) {
@@ -718,20 +1066,41 @@ class VizBuilderImpl {
                 lineRuntimeAttrs += ` stroke-dashoffset="${edge.runtime.strokeDashoffset}"`;
             }
             svgContent += `<g data-id="${edge.id}" data-viz-role="edge-group" class="viz-edge-group ${edge.className || ''} ${animClasses}" style="${animStyleStr}${runtimeStyle}">`;
-            svgContent += `<line x1="${endpoints.start.x}" y1="${endpoints.start.y}" x2="${endpoints.end.x}" y2="${endpoints.end.y}" class="viz-edge" data-viz-role="edge-line" ${markerEnd} stroke="currentColor" style="${lineRuntimeStyle}"${lineRuntimeAttrs} />`;
-            // Edge Label
-            if (edge.label) {
-                const mx = (endpoints.start.x + endpoints.end.x) / 2 + (edge.label.dx || 0);
-                const my = (endpoints.start.y + endpoints.end.y) / 2 + (edge.label.dy || 0);
-                const labelClass = `viz-edge-label ${edge.label.className || ''}`;
-                svgContent += `<text x="${mx}" y="${my}" class="${labelClass}" data-viz-role="edge-label" text-anchor="middle" dominant-baseline="middle">${edge.label.text}</text>`;
-            }
+            let edgeInlineStyle = lineRuntimeStyle;
+            if (edge.style?.stroke !== undefined)
+                edgeInlineStyle += `stroke: ${edge.style.stroke}; `;
+            if (edge.style?.strokeWidth !== undefined)
+                edgeInlineStyle += `stroke-width: ${edge.style.strokeWidth}; `;
+            if (edge.style?.fill !== undefined)
+                edgeInlineStyle += `fill: ${edge.style.fill}; `;
+            if (edge.style?.opacity !== undefined)
+                edgeInlineStyle += `opacity: ${edge.style.opacity}; `;
+            svgContent += `<path d="${edgePath.d}" class="viz-edge" data-viz-role="edge-line" ${markerEnd} ${markerStart} style="${edgeInlineStyle}"${lineRuntimeAttrs} />`;
+            // Edge Labels (multi-position)
+            const allLabels = collectEdgeLabels(edge);
+            allLabels.forEach((lbl, idx) => {
+                const pos = resolveEdgeLabelPosition(lbl, edgePath);
+                const labelClass = `viz-edge-label ${lbl.className || ''}`;
+                svgContent += `<text x="${pos.x}" y="${pos.y}" class="${labelClass}" data-viz-role="edge-label" data-label-index="${idx}" data-label-position="${lbl.position}" text-anchor="middle" dominant-baseline="middle">${lbl.text}</text>`;
+            });
             svgContent += '</g>';
         });
         svgContent += '</g>';
-        // Render Nodes
-        svgContent += '<g class="viz-layer-nodes" data-viz-layer="nodes">';
-        nodes.forEach((node) => {
+        // Build parent→children map for container grouping
+        const childrenByParent = new Map();
+        nodes.forEach((n) => {
+            if (n.parentId) {
+                let arr = childrenByParent.get(n.parentId);
+                if (!arr) {
+                    arr = [];
+                    childrenByParent.set(n.parentId, arr);
+                }
+                arr.push(n);
+            }
+        });
+        // Recursive node renderer
+        const renderNodeToSvg = (node) => {
+            let content = '';
             const { x, y } = effectivePos(node);
             const { shape } = node;
             // Animations (Nodes)
@@ -765,8 +1134,9 @@ class VizBuilderImpl {
                     }
                 });
             }
-            const className = `viz-node-group ${node.className || ''} ${animClasses}`;
-            svgContent += `<g data-id="${node.id}" data-viz-role="node-group" class="${className}" style="${animStyleStr}">`;
+            const isContainer = !!node.container;
+            const className = `viz-node-group${isContainer ? ' viz-container' : ''} ${node.className || ''} ${animClasses}`;
+            content += `<g data-id="${node.id}" data-viz-role="node-group" class="${className}" style="${animStyleStr}">`;
             const shapeStyleAttrs = svgAttributeString({
                 fill: node.style?.fill ?? 'none',
                 stroke: node.style?.stroke ?? '#111',
@@ -774,11 +1144,30 @@ class VizBuilderImpl {
                 opacity: node.style?.opacity,
             });
             // Shape
-            svgContent += shapeSvgMarkup(shape, { x, y }, shapeStyleAttrs);
+            content += shapeSvgMarkup(shape, { x, y }, shapeStyleAttrs);
+            // Container header line
+            if (isContainer &&
+                node.container.headerHeight &&
+                'w' in shape &&
+                'h' in shape) {
+                const sw = shape.w;
+                const sh = shape.h;
+                const headerY = y - sh / 2 + node.container.headerHeight;
+                content += `<line x1="${x - sw / 2}" y1="${headerY}" x2="${x + sw / 2}" y2="${headerY}" stroke="${node.style?.stroke ?? '#111'}" stroke-width="${node.style?.strokeWidth ?? 2}" class="viz-container-header" data-viz-role="container-header" />`;
+            }
             // Label
             if (node.label) {
-                const lx = x + (node.label.dx || 0);
-                const ly = y + (node.label.dy || 0);
+                let lx = x + (node.label.dx || 0);
+                let ly = y + (node.label.dy || 0);
+                // If container with headerHeight, center label in header area
+                if (isContainer &&
+                    node.container.headerHeight &&
+                    'h' in shape &&
+                    !node.label.dy) {
+                    const sh = shape.h;
+                    ly = y - sh / 2 + node.container.headerHeight / 2;
+                    lx = x + (node.label.dx || 0);
+                }
                 const labelClass = `viz-node-label ${node.label.className || ''}`;
                 const labelAttrs = svgAttributeString({
                     fill: node.label.fill,
@@ -787,9 +1176,35 @@ class VizBuilderImpl {
                     'text-anchor': node.label.textAnchor || 'middle',
                     'dominant-baseline': node.label.dominantBaseline || 'middle',
                 });
-                svgContent += `<text x="${lx}" y="${ly}" class="${labelClass}" data-viz-role="node-label"${labelAttrs}>${node.label.text}</text>`;
+                content += `<text x="${lx}" y="${ly}" class="${labelClass}" data-viz-role="node-label"${labelAttrs}>${node.label.text}</text>`;
+            }
+            // Ports (small circles on the shape boundary, hidden by default, shown on hover via CSS)
+            if (node.ports && node.ports.length > 0) {
+                node.ports.forEach((port) => {
+                    const px = x + port.offset.x;
+                    const py = y + port.offset.y;
+                    content += `<circle cx="${px}" cy="${py}" r="4" class="viz-port" data-viz-role="port" data-node="${node.id}" data-port="${port.id}" />`;
+                });
+            }
+            // Container children
+            const children = childrenByParent.get(node.id);
+            if (children && children.length > 0) {
+                content +=
+                    '<g class="viz-container-children" data-viz-role="container-children">';
+                children.forEach((child) => {
+                    content += renderNodeToSvg(child);
+                });
+                content += '</g>';
+            }
+            content += '</g>';
+            return content;
+        };
+        // Render Nodes (only root nodes; children are rendered inside their containers)
+        svgContent += '<g class="viz-layer-nodes" data-viz-layer="nodes">';
+        nodes.forEach((node) => {
+            if (!node.parentId) {
+                svgContent += renderNodeToSvg(node);
             }
-            svgContent += '</g>';
         });
         svgContent += '</g>';
         // Render Overlays
@@ -798,7 +1213,13 @@ class VizBuilderImpl {
             overlays.forEach((spec) => {
                 const renderer = defaultCoreOverlayRegistry.get(spec.id);
                 if (renderer) {
-                    svgContent += renderer.render({ spec, nodesById, edgesById, scene });
+                    svgContent += renderer.render({
+                        spec,
+                        nodesById,
+                        edgesById,
+                        scene,
+                        registry: defaultCoreOverlayRegistry,
+                    });
                 }
             });
             svgContent += '</g>';
@@ -808,10 +1229,10 @@ class VizBuilderImpl {
     }
 }
 class NodeBuilderImpl {
-    parent;
+    _builder;
     nodeDef;
     constructor(parent, nodeDef) {
-        this.parent = parent;
+        this._builder = parent;
         this.nodeDef = nodeDef;
     }
     at(x, y) {
@@ -819,12 +1240,12 @@ class NodeBuilderImpl {
         return this;
     }
     cell(col, row, align = 'center') {
-        const grid = this.parent._getGridConfig();
+        const grid = this._builder._getGridConfig();
         if (!grid) {
             console.warn('VizBuilder: .cell() called but no grid configured. Use .grid() first.');
             return this;
         }
-        const view = this.parent._getViewBox();
+        const view = this._builder._getViewBox();
         const availableW = view.w - grid.padding.x * 2;
         const availableH = view.h - grid.padding.y * 2;
         const cellW = availableW / grid.cols;
@@ -855,6 +1276,86 @@ class NodeBuilderImpl {
         this.nodeDef.shape = { kind: 'diamond', w, h };
         return this;
     }
+    cylinder(w, h, arcHeight) {
+        this.nodeDef.shape = { kind: 'cylinder', w, h, arcHeight };
+        return this;
+    }
+    hexagon(r, orientation) {
+        this.nodeDef.shape = { kind: 'hexagon', r, orientation };
+        return this;
+    }
+    ellipse(rx, ry) {
+        this.nodeDef.shape = { kind: 'ellipse', rx, ry };
+        return this;
+    }
+    arc(r, startAngle, endAngle, closed) {
+        this.nodeDef.shape = { kind: 'arc', r, startAngle, endAngle, closed };
+        return this;
+    }
+    blockArrow(length, bodyWidth, headWidth, headLength, direction) {
+        this.nodeDef.shape = {
+            kind: 'blockArrow',
+            length,
+            bodyWidth,
+            headWidth,
+            headLength,
+            direction,
+        };
+        return this;
+    }
+    callout(w, h, opts) {
+        this.nodeDef.shape = {
+            kind: 'callout',
+            w,
+            h,
+            rx: opts?.rx,
+            pointerSide: opts?.pointerSide,
+            pointerHeight: opts?.pointerHeight,
+            pointerWidth: opts?.pointerWidth,
+            pointerPosition: opts?.pointerPosition,
+        };
+        return this;
+    }
+    cloud(w, h) {
+        this.nodeDef.shape = { kind: 'cloud', w, h };
+        return this;
+    }
+    cross(size, barWidth) {
+        this.nodeDef.shape = { kind: 'cross', size, barWidth };
+        return this;
+    }
+    cube(w, h, depth) {
+        this.nodeDef.shape = { kind: 'cube', w, h, depth };
+        return this;
+    }
+    path(d, w, h) {
+        this.nodeDef.shape = { kind: 'path', d, w, h };
+        return this;
+    }
+    document(w, h, waveHeight) {
+        this.nodeDef.shape = { kind: 'document', w, h, waveHeight };
+        return this;
+    }
+    note(w, h, foldSize) {
+        this.nodeDef.shape = { kind: 'note', w, h, foldSize };
+        return this;
+    }
+    parallelogram(w, h, skew) {
+        this.nodeDef.shape = { kind: 'parallelogram', w, h, skew };
+        return this;
+    }
+    star(points, outerR, innerR) {
+        this.nodeDef.shape = { kind: 'star', points, outerR, innerR };
+        return this;
+    }
+    trapezoid(topW, bottomW, h) {
+        this.nodeDef.shape = { kind: 'trapezoid', topW, bottomW, h };
+        return this;
+    }
+    triangle(w, h, direction) {
+        this.nodeDef.shape = { kind: 'triangle', w, h, direction };
+        return this;
+    }
     label(text, opts) {
         this.nodeDef.label = { text, ...opts };
         return this;
@@ -903,7 +1404,7 @@ class NodeBuilderImpl {
             throw new Error('NodeBuilder.animate(cb): node has no id');
         }
         // Compile to a portable AnimationSpec and store on the scene via the parent builder.
-        this.parent.animate((anim) => {
+        this._builder.animate((anim) => {
             anim.node(id);
             typeOrCb(anim);
         });
@@ -922,24 +1423,41 @@ class NodeBuilderImpl {
         this.nodeDef.onClick = handler;
         return this;
     }
+    container(config) {
+        this.nodeDef.container = config ?? { layout: 'free' };
+        return this;
+    }
+    port(id, offset, direction) {
+        if (!this.nodeDef.ports) {
+            this.nodeDef.ports = [];
+        }
+        this.nodeDef.ports.push({ id, offset, direction });
+        return this;
+    }
+    parent(parentId) {
+        this.nodeDef.parentId = parentId;
+        return this;
+    }
     done() {
-        return this.parent;
+        return this._builder;
     }
     // Chaining
     node(id) {
-        return this.parent.node(id);
+        return this._builder.node(id);
     }
     edge(from, to, id) {
-        return this.parent.edge(from, to, id);
+        return this._builder.edge(from, to, id);
     }
-    overlay(id, params, key) {
-        return this.parent.overlay(id, params, key);
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function')
+            return this._builder.overlay(arg1);
+        return this._builder.overlay(arg1, arg2, arg3);
     }
     build() {
-        return this.parent.build();
+        return this._builder.build();
     }
     svg() {
-        return this.parent.svg();
+        return this._builder.svg();
     }
 }
 class EdgeBuilderImpl {
@@ -950,21 +1468,102 @@ class EdgeBuilderImpl {
         this.edgeDef = edgeDef;
     }
     straight() {
-        // No-op for now as it is default
+        this.edgeDef.routing = 'straight';
+        return this;
+    }
+    curved() {
+        this.edgeDef.routing = 'curved';
+        return this;
+    }
+    orthogonal() {
+        this.edgeDef.routing = 'orthogonal';
+        return this;
+    }
+    routing(mode) {
+        this.edgeDef.routing = mode;
+        return this;
+    }
+    via(x, y) {
+        if (!this.edgeDef.waypoints) {
+            this.edgeDef.waypoints = [];
+        }
+        this.edgeDef.waypoints.push({ x, y });
         return this;
     }
     label(text, opts) {
-        this.edgeDef.label = { position: 'mid', text, dy: -10, ...opts };
+        const lbl = { position: 'mid', text, dy: -10, ...opts };
+        // Accumulate into the labels array
+        if (!this.edgeDef.labels) {
+            this.edgeDef.labels = [];
+        }
+        this.edgeDef.labels.push(lbl);
+        // Backwards compat: keep the first mid label in `label`
+        if (lbl.position === 'mid' && !this.edgeDef.label) {
+            this.edgeDef.label = lbl;
+        }
         return this;
     }
     arrow(enabled = true) {
-        this.edgeDef.markerEnd = enabled ? 'arrow' : 'none';
+        if (enabled === 'both') {
+            this.edgeDef.markerStart = 'arrow';
+            this.edgeDef.markerEnd = 'arrow';
+        }
+        else if (enabled === 'start') {
+            this.edgeDef.markerStart = 'arrow';
+        }
+        else if (enabled === 'end') {
+            this.edgeDef.markerEnd = 'arrow';
+        }
+        else if (enabled === true) {
+            this.edgeDef.markerEnd = 'arrow';
+        }
+        else {
+            this.edgeDef.markerEnd = 'none';
+        }
+        return this;
+    }
+    markerEnd(type) {
+        this.edgeDef.markerEnd = type;
+        return this;
+    }
+    markerStart(type) {
+        this.edgeDef.markerStart = type;
         return this;
     }
     connect(anchor) {
         this.edgeDef.anchor = anchor;
         return this;
     }
+    fromPort(portId) {
+        this.edgeDef.fromPort = portId;
+        return this;
+    }
+    toPort(portId) {
+        this.edgeDef.toPort = portId;
+        return this;
+    }
+    fill(color) {
+        this.edgeDef.style = {
+            ...(this.edgeDef.style || {}),
+            fill: color,
+        };
+        return this;
+    }
+    stroke(color, width) {
+        this.edgeDef.style = {
+            ...(this.edgeDef.style || {}),
+            stroke: color,
+            strokeWidth: width ?? this.edgeDef.style?.strokeWidth,
+        };
+        return this;
+    }
+    opacity(value) {
+        this.edgeDef.style = {
+            ...(this.edgeDef.style || {}),
+            opacity: value,
+        };
+        return this;
+    }
     class(name) {
         if (this.edgeDef.className) {
             this.edgeDef.className += ` ${name}`;
@@ -1026,8 +1625,10 @@ class EdgeBuilderImpl {
     edge(from, to, id) {
         return this.parent.edge(from, to, id || `${from}->${to}`); // Default ID to from->to
     }
-    overlay(id, params, key) {
-        return this.parent.overlay(id, params, key);
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function')
+            return this.parent.overlay(arg1);
+        return this.parent.overlay(arg1, arg2, arg3);
     }
     build() {
         return this.parent.build();