vizcraft 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 1.3.1
+
+### Patch Changes
+
+- [`086ef9e`](https://github.com/ChipiKaf/vizcraft/commit/086ef9e7b5d505cbb03f955e8d24297fb60a6b3e) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - The fix prevents commit() from using a stale cached runtimePatchCtx (which could reference detached DOM elements) by always recreating it after \_renderSceneToDOM, and removes the redundant strokeDasharray write from patchRuntime so that base style is owned by a single write path.
+
+## 1.3.0
+
+### Minor Changes
+
+- [`3f55212`](https://github.com/ChipiKaf/vizcraft/commit/3f55212e56557994710d65a99fe339c6826cb2a7) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Add new visual styling options for nodes and edges: a hand-drawn "sketch" rendering mode, configurable drop-shadow support for nodes, and node stroke dasharray (dashed strokes)
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -196,6 +196,16 @@ b.node('n1')
  .image(href, w, h, opts?) // Embed an <image> inside the node
  .icon(id, opts?)         // Embed an icon from the icon registry (see registerIcon)
  .svgContent(svg, opts)   // Embed inline SVG content inside the node
+ .fill('#f0f0f0')          // Fill color
+ .stroke('#333', 2)       // Stroke color and optional width
+ .opacity(0.8)            // Opacity
+ .dashed()                // Dashed border (8, 4)
+ .dotted()                // Dotted border (2, 4)
+ .dash('12, 3, 3, 3')     // Custom dash pattern
+ .shadow()                // Drop shadow (default: dx=2 dy=2 blur=4)
+ .shadow({ dx: 4, dy: 4, blur: 10, color: 'rgba(0,0,0,0.35)' }) // Custom shadow
+ .sketch()                // Sketch / hand-drawn look (SVG turbulence filter)
+ .sketch({ seed: 42 })    // Sketch with explicit seed for deterministic jitter
  .class('css-class')     // Custom CSS class
  .data({ ... })          // Attach custom data
  .port('out', { x: 50, y: 0 }) // Named connection port
@@ -262,6 +272,9 @@ b.edge('a', 'b').dashed().stroke('#6c7086'); // dashed line
 b.edge('a', 'b').dotted(); // dotted line
 b.edge('a', 'b').dash('12, 3, 3, 3').stroke('#cba6f7'); // custom pattern
 
+// Sketch / hand-drawn edges
+b.edge('a', 'b').sketch(); // sketchy look
+
 // Multi-position edge labels (start / mid / end)
 b.edge('a', 'b')
   .label('1', { position: 'start' })

package/dist/builder.d.ts

@@ -37,6 +37,8 @@ export interface VizBuilder extends VizSceneMutator {
         x: number;
         y: number;
     }): VizBuilder;
+    /** Enable global sketch / hand-drawn rendering for all nodes and edges. */
+    sketch(enabled?: boolean, seed?: number): VizBuilder;
     /**
      * Fluent, data-only animation authoring. Compiles immediately to an `AnimationSpec`.
      * The compiled spec is also stored on the built scene as `scene.animationSpecs`.
@@ -209,6 +211,27 @@ interface NodeBuilder {
     fill(color: string): NodeBuilder;
     stroke(color: string, width?: number): NodeBuilder;
     opacity(value: number): NodeBuilder;
+    /** Apply a dashed stroke pattern (`8, 4`). */
+    dashed(): NodeBuilder;
+    /** Apply a dotted stroke pattern (`2, 4`). */
+    dotted(): NodeBuilder;
+    /** Apply a custom SVG `stroke-dasharray` value, or a preset name (`'dashed'`, `'dotted'`, `'dash-dot'`). */
+    dash(pattern: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string): NodeBuilder;
+    /**
+     * Add a drop shadow behind the node shape.
+     *
+     * Call with no arguments for a sensible default, or pass a config object.
+     */
+    shadow(config?: {
+        dx?: number;
+        dy?: number;
+        blur?: number;
+        color?: string;
+    }): NodeBuilder;
+    /** Render this node with a hand-drawn / sketchy appearance. */
+    sketch(config?: {
+        seed?: number;
+    }): NodeBuilder;
     class(name: string): NodeBuilder;
     zIndex(value: number): NodeBuilder;
     animate(type: string, config?: AnimationConfig): NodeBuilder;
@@ -283,6 +306,8 @@ interface EdgeBuilder {
     dotted(): EdgeBuilder;
     /** Apply a custom SVG `stroke-dasharray` value, or a preset name (`'dashed'`, `'dotted'`, `'dash-dot'`). */
     dash(pattern: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string): EdgeBuilder;
+    /** Render this edge with a hand-drawn / sketchy appearance. */
+    sketch(): EdgeBuilder;
     class(name: string): EdgeBuilder;
     hitArea(px: number): EdgeBuilder;
     animate(type: string, config?: AnimationConfig): EdgeBuilder;

package/dist/builder.js

@@ -37,6 +37,74 @@ function markerIdFor(markerType, stroke, position = 'end') {
 function arrowMarkerIdFor(stroke) {
     return markerIdFor('arrow', stroke);
 }
+const SHADOW_DEFAULTS = {
+    dx: 2,
+    dy: 2,
+    blur: 4,
+    color: 'rgba(0,0,0,0.2)',
+};
+/** Apply defaults to a partial shadow config. */
+function resolveShadow(shadow) {
+    return {
+        dx: shadow.dx ?? SHADOW_DEFAULTS.dx,
+        dy: shadow.dy ?? SHADOW_DEFAULTS.dy,
+        blur: shadow.blur ?? SHADOW_DEFAULTS.blur,
+        color: shadow.color ?? SHADOW_DEFAULTS.color,
+    };
+}
+/** Deterministic filter id keyed by config tuple for dedup. */
+function shadowFilterId(cfg) {
+    const colorSuffix = cfg.color.replace(/[^a-zA-Z0-9]/g, '_');
+    return `viz-shadow-${cfg.dx}-${cfg.dy}-${cfg.blur}-${colorSuffix}`;
+}
+/** SVG markup for a drop-shadow `<filter>`. */
+function shadowFilterSvg(id, cfg) {
+    return `<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%"><feDropShadow dx="${cfg.dx}" dy="${cfg.dy}" stdDeviation="${cfg.blur}" flood-color="${escapeXmlAttr(cfg.color)}" flood-opacity="1"/></filter>`;
+}
+/** Deterministic filter id for sketch displacement keyed by seed. */
+function sketchFilterId(seed) {
+    return `viz-sketch-${seed}`;
+}
+/** Simple seeded float in [0, 1) derived from a seed via xorshift-like mix. */
+function sketchRand(seed, salt) {
+    let s = ((seed ^ (salt * 2654435761)) >>> 0) | 1;
+    s ^= s << 13;
+    s ^= s >>> 17;
+    s ^= s << 5;
+    return (s >>> 0) / 4294967296;
+}
+/** Lerp a value between min and max using a seeded random. */
+function sketchLerp(seed, salt, min, max) {
+    return min + sketchRand(seed, salt) * (max - min);
+}
+/** SVG markup for a sketch `<filter>` using dual-pass displacement for a hand-drawn double-stroke look. */
+function sketchFilterSvg(id, seed) {
+    const s2 = seed + 37;
+    // Derive unique per-seed parameters
+    const freq2 = sketchLerp(seed, 1, 0.009, 0.015).toFixed(4);
+    const scale1 = sketchLerp(seed, 2, 2.5, 4).toFixed(1);
+    const scale2 = sketchLerp(seed, 3, 3, 5).toFixed(1);
+    const dx = sketchLerp(seed, 4, 0.3, 1.6).toFixed(2);
+    const dy = sketchLerp(seed, 5, 0.2, 1.3).toFixed(2);
+    return (`<filter id="${id}" filterUnits="userSpaceOnUse" x="-10000" y="-10000" width="20000" height="20000">` +
+        `<feTurbulence type="fractalNoise" baseFrequency="0.008" numOctaves="2" seed="${seed}" result="n1"/>` +
+        `<feTurbulence type="fractalNoise" baseFrequency="${freq2}" numOctaves="2" seed="${s2}" result="n2"/>` +
+        `<feDisplacementMap in="SourceGraphic" in2="n1" scale="${scale1}" xChannelSelector="R" yChannelSelector="G" result="s1"/>` +
+        `<feDisplacementMap in="SourceGraphic" in2="n2" scale="${scale2}" xChannelSelector="G" yChannelSelector="R" result="s2"/>` +
+        `<feOffset in="s2" dx="${dx}" dy="${dy}" result="s2off"/>` +
+        '<feComposite in="s1" in2="s2off" operator="over"/>' +
+        '</filter>');
+}
+/** Resolve the effective sketch seed for a node, falling back to the hash of its id. */
+function resolveSketchSeed(nodeStyle, id) {
+    if (nodeStyle?.sketchSeed !== undefined)
+        return nodeStyle.sketchSeed;
+    let h = 0;
+    for (let i = 0; i < id.length; i++) {
+        h = (Math.imul(31, h) + id.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h);
+}
 /**
  * Generate SVG markup for a single marker definition.
  * @param markerType The type of marker
@@ -251,6 +319,14 @@ function applyNodeOptions(nb, opts) {
     }
     if (opts.opacity !== undefined)
         nb.opacity(opts.opacity);
+    if (opts.dash)
+        nb.dash(opts.dash);
+    if (opts.shadow !== undefined && opts.shadow !== false) {
+        nb.shadow(opts.shadow === true ? {} : opts.shadow);
+    }
+    if (opts.sketch !== undefined && opts.sketch !== false) {
+        nb.sketch(opts.sketch === true ? {} : opts.sketch);
+    }
     if (opts.className)
         nb.class(opts.className);
     if (opts.zIndex !== undefined)
@@ -339,6 +415,8 @@ function applyEdgeOptions(eb, opts) {
         eb.opacity(opts.opacity);
     if (opts.dash)
         eb.dash(opts.dash);
+    if (opts.sketch)
+        eb.sketch();
     if (opts.className)
         eb.class(opts.className);
     // Anchor & ports
@@ -422,6 +500,7 @@ class VizBuilderImpl {
     _nodeOrder = [];
     _edgeOrder = [];
     _gridConfig = null;
+    _sketch = null;
     _animationSpecs = [];
     _mountedContainer = null;
     _panZoomController;
@@ -575,14 +654,13 @@ class VizBuilderImpl {
         // The reconciliation correctly re-uses existing SVG elements, inserts new ones, and deletes missing ones.
         const scene = this.build();
         this._renderSceneToDOM(scene, container);
-        // Apply runtime overrides (if any)
-        let ctx = runtimePatchCtxBySvg.get(svg);
-        if (!ctx) {
-            ctx = createRuntimePatchCtx(svg, {
-                edgePathResolver: this._edgePathResolver,
-            });
-            runtimePatchCtxBySvg.set(svg, ctx);
-        }
+        // Apply runtime overrides (if any).
+        // Always recreate the context after _renderSceneToDOM so patchRuntime
+        // never references stale / detached elements (fixes #81).
+        const ctx = createRuntimePatchCtx(svg, {
+            edgePathResolver: this._edgePathResolver,
+        });
+        runtimePatchCtxBySvg.set(svg, ctx);
         patchRuntime(scene, ctx);
     }
     /**
@@ -656,6 +734,10 @@ class VizBuilderImpl {
         this._gridConfig = { cols, rows, padding };
         return this;
     }
+    sketch(enabled = true, seed) {
+        this._sketch = enabled ? { enabled: true, seed } : null;
+        return this;
+    }
     overlay(arg1, arg2, arg3) {
         if (typeof arg1 === 'function') {
             const overlay = new OverlayBuilder();
@@ -740,6 +822,9 @@ class VizBuilderImpl {
         if (scene.animationSpecs) {
             this._animationSpecs = [...scene.animationSpecs];
         }
+        this._sketch = scene.sketch
+            ? { ...scene.sketch, enabled: scene.sketch.enabled ?? true }
+            : null;
         return this;
     }
     /**
@@ -764,6 +849,7 @@ class VizBuilderImpl {
             edges,
             overlays: this._overlays,
             animationSpecs: this._animationSpecs.length > 0 ? [...this._animationSpecs] : undefined,
+            sketch: this._sketch ?? undefined,
         };
         this._dispatchEvent('build', { scene });
         return scene;
@@ -1100,6 +1186,49 @@ class VizBuilderImpl {
                 }
                 defs.appendChild(markerEl);
             });
+            const neededShadows = new Map();
+            nodes.forEach((n) => {
+                if (n.style?.shadow) {
+                    const cfg = resolveShadow(n.style.shadow);
+                    const fid = shadowFilterId(cfg);
+                    if (!neededShadows.has(fid)) {
+                        neededShadows.set(fid, cfg);
+                    }
+                }
+            });
+            neededShadows.forEach((cfg, fid) => {
+                const tmp = document.createElementNS(svgNS, 'svg');
+                tmp.innerHTML = shadowFilterSvg(fid, cfg);
+                const filterEl = tmp.querySelector('filter');
+                if (filterEl) {
+                    defs.appendChild(filterEl);
+                }
+            });
+            const neededSketchSeeds = new Set();
+            const globalSketch = scene.sketch?.enabled;
+            nodes.forEach((n) => {
+                if (n.style?.sketch || globalSketch) {
+                    neededSketchSeeds.add(resolveSketchSeed(n.style, n.id));
+                }
+            });
+            edges.forEach((e) => {
+                if (e.style?.sketch || globalSketch) {
+                    let h = 0;
+                    for (let i = 0; i < e.id.length; i++) {
+                        h = (Math.imul(31, h) + e.id.charCodeAt(i)) | 0;
+                    }
+                    neededSketchSeeds.add(Math.abs(h));
+                }
+            });
+            neededSketchSeeds.forEach((seed) => {
+                const fid = sketchFilterId(seed);
+                const tmp = document.createElementNS(svgNS, 'svg');
+                tmp.innerHTML = sketchFilterSvg(fid, seed);
+                const filterEl = tmp.querySelector('filter');
+                if (filterEl) {
+                    defs.appendChild(filterEl);
+                }
+            });
             svg.appendChild(defs);
             // Layers
             const viewport = document.createElementNS(svgNS, 'g');
@@ -1162,6 +1291,9 @@ class VizBuilderImpl {
             }
             // Compute Classes & Styles
             let classes = `viz-edge-group ${edge.className || ''}`;
+            const edgeSketched = edge.style?.sketch || scene.sketch?.enabled;
+            if (edgeSketched)
+                classes += ' viz-sketch';
             // Reset styles
             group.removeAttribute('style');
             if (edge.animations) {
@@ -1281,6 +1413,17 @@ class VizBuilderImpl {
             else {
                 line.style.removeProperty('stroke-dasharray');
             }
+            if (edgeSketched) {
+                let h = 0;
+                for (let i = 0; i < edge.id.length; i++) {
+                    h = (Math.imul(31, h) + edge.id.charCodeAt(i)) | 0;
+                }
+                const seed = Math.abs(h);
+                line.setAttribute('filter', `url(#${sketchFilterId(seed)})`);
+            }
+            else {
+                line.removeAttribute('filter');
+            }
             const oldHit = group.querySelector('[data-viz-role="edge-hit"]') ||
                 group.querySelector('.viz-edge-hit');
             if (oldHit)
@@ -1311,6 +1454,10 @@ class VizBuilderImpl {
                 const labelClass = `viz-edge-label ${lbl.className || ''}`;
                 const edgeLabelSvg = renderSvgText(pos.x, pos.y, lbl.rich ?? lbl.text, {
                     className: labelClass,
+                    fill: lbl.fill,
+                    fontSize: lbl.fontSize,
+                    fontWeight: lbl.fontWeight,
+                    fontFamily: lbl.fontFamily,
                     textAnchor: 'middle',
                     dominantBaseline: 'middle',
                     maxWidth: lbl.maxWidth,
@@ -1370,6 +1517,9 @@ class VizBuilderImpl {
             const isContainer = !!node.container;
             // Calculate Anim Classes
             let classes = `viz-node-group${isContainer ? ' viz-container' : ''} ${node.className || ''}`;
+            const nodeSketched = node.style?.sketch || scene.sketch?.enabled;
+            if (nodeSketched)
+                classes += ' viz-sketch';
             group.removeAttribute('style');
             if (node.animations) {
                 node.animations.forEach((spec) => {
@@ -1426,12 +1576,25 @@ class VizBuilderImpl {
                 group.prepend(shape);
             }
             applyShapeGeometry(shape, node.shape, { x, y });
+            const resolvedNodeDash = resolveDasharray(node.style?.strokeDasharray);
+            const nodeShadowFilter = node.style?.shadow
+                ? `url(#${shadowFilterId(resolveShadow(node.style.shadow))})`
+                : undefined;
             setSvgAttributes(shape, {
                 fill: node.style?.fill ?? 'none',
                 stroke: node.style?.stroke ?? '#111',
                 'stroke-width': node.style?.strokeWidth ?? 2,
                 opacity: node.runtime?.opacity ?? node.style?.opacity,
+                'stroke-dasharray': resolvedNodeDash || undefined,
+                filter: nodeShadowFilter,
             });
+            if (nodeSketched) {
+                const seed = resolveSketchSeed(node.style, node.id);
+                group.setAttribute('filter', `url(#${sketchFilterId(seed)})`);
+            }
+            else {
+                group.removeAttribute('filter');
+            }
             // Embedded media (rendered alongside the base shape)
             const existingImg = group.querySelector(':scope > [data-viz-role="node-image"], :scope > .viz-node-image');
             if (existingImg)
@@ -1558,6 +1721,7 @@ class VizBuilderImpl {
                     fill: node.label.fill,
                     fontSize: node.label.fontSize,
                     fontWeight: node.label.fontWeight,
+                    fontFamily: node.label.fontFamily,
                     textAnchor: node.label.textAnchor || 'middle',
                     dominantBaseline: node.label.dominantBaseline || 'middle',
                     maxWidth: node.label.maxWidth,
@@ -1744,6 +1908,38 @@ class VizBuilderImpl {
                 }
             }
         });
+        const exportShadows = new Map();
+        exportNodes.forEach((n) => {
+            if (n.style?.shadow) {
+                const cfg = resolveShadow(n.style.shadow);
+                const fid = shadowFilterId(cfg);
+                if (!exportShadows.has(fid)) {
+                    exportShadows.set(fid, cfg);
+                }
+            }
+        });
+        exportShadows.forEach((cfg, fid) => {
+            svgContent += shadowFilterSvg(fid, cfg);
+        });
+        const exportSketchSeeds = new Set();
+        const globalSketchExport = exportScene.sketch?.enabled;
+        exportNodes.forEach((n) => {
+            if (n.style?.sketch || globalSketchExport) {
+                exportSketchSeeds.add(resolveSketchSeed(n.style, n.id));
+            }
+        });
+        exportEdges.forEach((e) => {
+            if (e.style?.sketch || globalSketchExport) {
+                let h = 0;
+                for (let i = 0; i < e.id.length; i++) {
+                    h = (Math.imul(31, h) + e.id.charCodeAt(i)) | 0;
+                }
+                exportSketchSeeds.add(Math.abs(h));
+            }
+        });
+        exportSketchSeeds.forEach((seed) => {
+            svgContent += sketchFilterSvg(sketchFilterId(seed), seed);
+        });
         svgContent += `
         </defs>`;
         // Render Edges
@@ -1825,7 +2021,9 @@ class VizBuilderImpl {
                 lineRuntimeStyle += `stroke-dashoffset: ${edge.runtime.strokeDashoffset}; `;
                 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}">`;
+            const edgeSketched = edge.style?.sketch || globalSketchExport;
+            const sketchClass = edgeSketched ? ' viz-sketch' : '';
+            svgContent += `<g data-id="${edge.id}" data-viz-role="edge-group" class="viz-edge-group${sketchClass} ${edge.className || ''} ${animClasses}" style="${animStyleStr}${runtimeStyle}">`;
             let edgeInlineStyle = lineRuntimeStyle;
             if (edge.style?.stroke !== undefined)
                 edgeInlineStyle += `stroke: ${edge.style.stroke}; `;
@@ -1841,7 +2039,15 @@ class VizBuilderImpl {
                 if (resolved)
                     edgeInlineStyle += `stroke-dasharray: ${resolved}; `;
             }
-            svgContent += `<path d="${edgePath.d}" class="viz-edge" data-viz-role="edge-line" ${markerEnd} ${markerStart} style="${edgeInlineStyle}"${lineRuntimeAttrs} />`;
+            let edgeSketchFilterAttr = '';
+            if (edgeSketched) {
+                let h = 0;
+                for (let i = 0; i < edge.id.length; i++) {
+                    h = (Math.imul(31, h) + edge.id.charCodeAt(i)) | 0;
+                }
+                edgeSketchFilterAttr = ` filter="url(#${sketchFilterId(Math.abs(h))})"`;
+            }
+            svgContent += `<path d="${edgePath.d}" class="viz-edge" data-viz-role="edge-line" ${markerEnd} ${markerStart} style="${edgeInlineStyle}"${lineRuntimeAttrs}${edgeSketchFilterAttr} />`;
             // Edge Labels (multi-position)
             const allLabels = collectEdgeLabels(edge);
             allLabels.forEach((lbl, idx) => {
@@ -1849,6 +2055,10 @@ class VizBuilderImpl {
                 const labelClass = `viz-edge-label ${lbl.className || ''}`;
                 const edgeLabelSvg = renderSvgText(pos.x, pos.y, lbl.rich ?? lbl.text, {
                     className: labelClass,
+                    fill: lbl.fill,
+                    fontSize: lbl.fontSize,
+                    fontWeight: lbl.fontWeight,
+                    fontFamily: lbl.fontFamily,
                     textAnchor: 'middle',
                     dominantBaseline: 'middle',
                     maxWidth: lbl.maxWidth,
@@ -1913,18 +2123,30 @@ class VizBuilderImpl {
                 });
             }
             const isContainer = !!node.container;
-            const className = `viz-node-group${isContainer ? ' viz-container' : ''} ${node.className || ''} ${animClasses}`;
+            const nodeSketched = node.style?.sketch || globalSketchExport;
+            const className = `viz-node-group${isContainer ? ' viz-container' : ''}${nodeSketched ? ' viz-sketch' : ''} ${node.className || ''} ${animClasses}`;
             const scale = node.runtime?.scale;
             const rotation = node.runtime?.rotation;
+            let groupFilterAttr = '';
+            if (nodeSketched) {
+                const seed = resolveSketchSeed(node.style, node.id);
+                groupFilterAttr = ` filter="url(#${sketchFilterId(seed)})"`;
+            }
             const transformAttr = scale !== undefined || rotation !== undefined
                 ? ` transform="translate(${x} ${y}) rotate(${rotation ?? 0}) scale(${scale ?? 1}) translate(${-x} ${-y})"`
                 : '';
-            content += `<g data-id="${node.id}" data-viz-role="node-group" class="${className}" style="${animStyleStr}"${transformAttr}>`;
+            content += `<g data-id="${node.id}" data-viz-role="node-group" class="${className}" style="${animStyleStr}"${transformAttr}${groupFilterAttr}>`;
+            const resolvedExportNodeDash = resolveDasharray(node.style?.strokeDasharray);
+            const exportShadowFilter = node.style?.shadow
+                ? `url(#${shadowFilterId(resolveShadow(node.style.shadow))})`
+                : undefined;
             const shapeStyleAttrs = svgAttributeString({
                 fill: node.style?.fill ?? 'none',
                 stroke: node.style?.stroke ?? '#111',
                 'stroke-width': node.style?.strokeWidth ?? 2,
                 opacity: node.runtime?.opacity !== undefined ? undefined : node.style?.opacity,
+                'stroke-dasharray': resolvedExportNodeDash || undefined,
+                filter: exportShadowFilter,
             });
             // Shape
             content += shapeSvgMarkup(shape, { x, y }, shapeStyleAttrs);
@@ -1997,6 +2219,7 @@ class VizBuilderImpl {
                     fill: node.label.fill,
                     fontSize: node.label.fontSize,
                     fontWeight: node.label.fontWeight,
+                    fontFamily: node.label.fontFamily,
                     textAnchor: node.label.textAnchor || 'middle',
                     dominantBaseline: node.label.dominantBaseline || 'middle',
                     maxWidth: node.label.maxWidth,
@@ -2297,6 +2520,42 @@ class NodeBuilderImpl {
         };
         return this;
     }
+    dashed() {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            strokeDasharray: 'dashed',
+        };
+        return this;
+    }
+    dotted() {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            strokeDasharray: 'dotted',
+        };
+        return this;
+    }
+    dash(pattern) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            strokeDasharray: pattern,
+        };
+        return this;
+    }
+    shadow(config) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            shadow: config ?? {},
+        };
+        return this;
+    }
+    sketch(config) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            sketch: true,
+            sketchSeed: config?.seed,
+        };
+        return this;
+    }
     class(name) {
         if (this.nodeDef.className) {
             this.nodeDef.className += ` ${name}`;
@@ -2522,6 +2781,13 @@ class EdgeBuilderImpl {
         };
         return this;
     }
+    sketch() {
+        this.edgeDef.style = {
+            ...(this.edgeDef.style || {}),
+            sketch: true,
+        };
+        return this;
+    }
     class(name) {
         if (this.edgeDef.className) {
             this.edgeDef.className += ` ${name}`;

package/dist/runtimePatcher.js

@@ -3,6 +3,146 @@ import { computeEdgePath, computeEdgeEndpoints, computeSelfLoop, } from './edgeP
 import { resolveEdgeLabelPosition, collectEdgeLabels } from './edgeLabels';
 import { resolveDasharray } from './edgeStyles';
 const svgNS = 'http://www.w3.org/2000/svg';
+const SHADOW_DEFAULTS = {
+    dx: 2,
+    dy: 2,
+    blur: 4,
+    color: 'rgba(0,0,0,0.2)',
+};
+function resolveShadow(shadow) {
+    return {
+        dx: shadow.dx ?? SHADOW_DEFAULTS.dx,
+        dy: shadow.dy ?? SHADOW_DEFAULTS.dy,
+        blur: shadow.blur ?? SHADOW_DEFAULTS.blur,
+        color: shadow.color ?? SHADOW_DEFAULTS.color,
+    };
+}
+function shadowFilterId(cfg) {
+    const colorSuffix = cfg.color.replace(/[^a-zA-Z0-9]/g, '_');
+    return `viz-shadow-${cfg.dx}-${cfg.dy}-${cfg.blur}-${colorSuffix}`;
+}
+/** Lazily ensure a shadow `<filter>` definition exists in `<defs>`. */
+function ensureShadowFilter(svg, shadow) {
+    const cfg = resolveShadow(shadow);
+    const fid = shadowFilterId(cfg);
+    if (!svg.querySelector(`#${CSS.escape(fid)}`)) {
+        const defs = svg.querySelector('defs');
+        if (defs) {
+            const filter = document.createElementNS(svgNS, 'filter');
+            filter.setAttribute('id', fid);
+            filter.setAttribute('x', '-50%');
+            filter.setAttribute('y', '-50%');
+            filter.setAttribute('width', '200%');
+            filter.setAttribute('height', '200%');
+            const drop = document.createElementNS(svgNS, 'feDropShadow');
+            drop.setAttribute('dx', String(cfg.dx));
+            drop.setAttribute('dy', String(cfg.dy));
+            drop.setAttribute('stdDeviation', String(cfg.blur));
+            drop.setAttribute('flood-color', cfg.color);
+            drop.setAttribute('flood-opacity', '1');
+            filter.appendChild(drop);
+            defs.appendChild(filter);
+        }
+    }
+    return fid;
+}
+function sketchFilterId(seed) {
+    return `viz-sketch-${seed}`;
+}
+/** Simple seeded float in [0, 1) derived from a seed via xorshift-like mix. */
+function sketchRand(seed, salt) {
+    let s = ((seed ^ (salt * 2654435761)) >>> 0) | 1;
+    s ^= s << 13;
+    s ^= s >>> 17;
+    s ^= s << 5;
+    return (s >>> 0) / 4294967296;
+}
+/** Lerp a value between min and max using a seeded random. */
+function sketchLerp(seed, salt, min, max) {
+    return min + sketchRand(seed, salt) * (max - min);
+}
+/** Lazily ensure a sketch `<filter>` definition exists in `<defs>`. */
+function ensureSketchFilter(svg, seed) {
+    const fid = sketchFilterId(seed);
+    if (!svg.querySelector(`#${CSS.escape(fid)}`)) {
+        const defs = svg.querySelector('defs');
+        if (defs) {
+            const filter = document.createElementNS(svgNS, 'filter');
+            filter.setAttribute('id', fid);
+            filter.setAttribute('filterUnits', 'userSpaceOnUse');
+            filter.setAttribute('x', '-10000');
+            filter.setAttribute('y', '-10000');
+            filter.setAttribute('width', '20000');
+            filter.setAttribute('height', '20000');
+            const s2 = seed + 37;
+            // Derive unique per-seed parameters
+            const freq2 = sketchLerp(seed, 1, 0.009, 0.015).toFixed(4);
+            const scale1 = sketchLerp(seed, 2, 2.5, 4).toFixed(1);
+            const scale2 = sketchLerp(seed, 3, 3, 5).toFixed(1);
+            const dx = sketchLerp(seed, 4, 0.3, 1.6).toFixed(2);
+            const dy = sketchLerp(seed, 5, 0.2, 1.3).toFixed(2);
+            // First noise
+            const turb1 = document.createElementNS(svgNS, 'feTurbulence');
+            turb1.setAttribute('type', 'fractalNoise');
+            turb1.setAttribute('baseFrequency', '0.008');
+            turb1.setAttribute('numOctaves', '2');
+            turb1.setAttribute('seed', String(seed));
+            turb1.setAttribute('result', 'n1');
+            filter.appendChild(turb1);
+            // Second noise (different seed + frequency)
+            const turb2 = document.createElementNS(svgNS, 'feTurbulence');
+            turb2.setAttribute('type', 'fractalNoise');
+            turb2.setAttribute('baseFrequency', freq2);
+            turb2.setAttribute('numOctaves', '2');
+            turb2.setAttribute('seed', String(s2));
+            turb2.setAttribute('result', 'n2');
+            filter.appendChild(turb2);
+            // First stroke pass
+            const disp1 = document.createElementNS(svgNS, 'feDisplacementMap');
+            disp1.setAttribute('in', 'SourceGraphic');
+            disp1.setAttribute('in2', 'n1');
+            disp1.setAttribute('scale', scale1);
+            disp1.setAttribute('xChannelSelector', 'R');
+            disp1.setAttribute('yChannelSelector', 'G');
+            disp1.setAttribute('result', 's1');
+            filter.appendChild(disp1);
+            // Second stroke pass (different channels)
+            const disp2 = document.createElementNS(svgNS, 'feDisplacementMap');
+            disp2.setAttribute('in', 'SourceGraphic');
+            disp2.setAttribute('in2', 'n2');
+            disp2.setAttribute('scale', scale2);
+            disp2.setAttribute('xChannelSelector', 'G');
+            disp2.setAttribute('yChannelSelector', 'R');
+            disp2.setAttribute('result', 's2');
+            filter.appendChild(disp2);
+            // Offset second pass — variable gap
+            const offset = document.createElementNS(svgNS, 'feOffset');
+            offset.setAttribute('in', 's2');
+            offset.setAttribute('dx', dx);
+            offset.setAttribute('dy', dy);
+            offset.setAttribute('result', 's2off');
+            filter.appendChild(offset);
+            // Merge both passes
+            const comp = document.createElementNS(svgNS, 'feComposite');
+            comp.setAttribute('in', 's1');
+            comp.setAttribute('in2', 's2off');
+            comp.setAttribute('operator', 'over');
+            filter.appendChild(comp);
+            defs.appendChild(filter);
+        }
+    }
+    return fid;
+}
+/** Resolve the effective sketch seed for a node, falling back to the hash of its id. */
+function resolveSketchSeed(nodeStyle, id) {
+    if (nodeStyle?.sketchSeed !== undefined)
+        return nodeStyle.sketchSeed;
+    let h = 0;
+    for (let i = 0; i < id.length; i++) {
+        h = (Math.imul(31, h) + id.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h);
+}
 /** Sanitise a CSS color for use as a marker ID suffix. */
 function colorToMarkerSuffix(color) {
     return color.replace(/[^a-zA-Z0-9]/g, '_');
@@ -371,6 +511,35 @@ export function patchRuntime(scene, ctx) {
                 shape.removeAttribute('opacity');
             }
         }
+        // NOTE: strokeDasharray is a static base style — written exclusively by
+        // _renderSceneToDOM via setSvgAttributes.  patchRuntime must NOT duplicate
+        // that write to avoid the stale-context overwrite described in #81.
+        if (node.style?.shadow) {
+            const fid = ensureShadowFilter(ctx.svg, node.style.shadow);
+            shape.setAttribute('filter', `url(#${fid})`);
+        }
+        else {
+            shape.removeAttribute('filter');
+        }
+        const nodeSketched = node.style?.sketch || scene.sketch?.enabled;
+        if (nodeSketched) {
+            const seed = resolveSketchSeed(node.style, node.id);
+            const fid = ensureSketchFilter(ctx.svg, seed);
+            group.setAttribute('filter', `url(#${fid})`);
+            if (!group.classList.contains('viz-sketch')) {
+                group.classList.add('viz-sketch');
+            }
+        }
+        else {
+            if (group.classList.contains('viz-sketch')) {
+                group.classList.remove('viz-sketch');
+            }
+            // Only remove group filter if it was a sketch filter
+            const cur = group.getAttribute('filter');
+            if (cur && cur.startsWith('url(#viz-sketch-')) {
+                group.removeAttribute('filter');
+            }
+        }
         // Transform conflict rule: runtime wins if it writes transform.
         const scale = node.runtime?.scale;
         const rotation = node.runtime?.rotation;
@@ -502,6 +671,28 @@ export function patchRuntime(scene, ctx) {
             line.style.removeProperty('stroke-dashoffset');
             line.removeAttribute('stroke-dashoffset');
         }
+        const edgeSketched = edge.style?.sketch || scene.sketch?.enabled;
+        if (edgeSketched) {
+            let h = 0;
+            for (let i = 0; i < edge.id.length; i++) {
+                h = (Math.imul(31, h) + edge.id.charCodeAt(i)) | 0;
+            }
+            const seed = Math.abs(h);
+            const fid = ensureSketchFilter(ctx.svg, seed);
+            line.setAttribute('filter', `url(#${fid})`);
+            if (!group.classList.contains('viz-sketch')) {
+                group.classList.add('viz-sketch');
+            }
+        }
+        else {
+            const cur = line.getAttribute('filter');
+            if (cur && cur.startsWith('url(#viz-sketch-')) {
+                line.removeAttribute('filter');
+            }
+            if (group.classList.contains('viz-sketch')) {
+                group.classList.remove('viz-sketch');
+            }
+        }
     }
     // Ensure DOM order matches zIndex order for node layer children
     // We use insertBefore to minimize DOM thrashing in the animation loop

package/dist/styles.d.ts

@@ -1 +1 @@
-export declare const DEFAULT_VIZ_CSS = "\n.viz-canvas {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n}\n\n.viz-node-label,\n.viz-edge-label {\n  text-anchor: middle;\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(0);\n}\n\n.viz-canvas svg {\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n\n/* Keyframes */\n@keyframes vizFlow {\n  from {\n    stroke-dashoffset: 20;\n  }\n  to {\n    stroke-dashoffset: 0;\n  }\n}\n\n/* Animation Classes */\n\n/* Flow Animation (Dashed line moving) */\n.viz-anim-flow .viz-edge {\n  stroke-dasharray: 5, 5;\n  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;\n}\n\n/* Edge base styling (path elements need explicit fill:none) */\n.viz-edge {\n  fill: none;\n  stroke: currentColor;\n}\n\n.viz-edge-hit {\n  fill: none;\n}\n\n/* Node Transition */\n.viz-node-group {\n    transition: transform 0.3s ease-out, opacity 0.3s ease-out;\n}\n\n/* Overlay Classes */\n.viz-grid-label {\n  fill: #6B7280;\n  font-size: 14px;\n  font-weight: 600;\n  opacity: 1;\n}\n\n.viz-signal {\n    fill: #3B82F6;\n    cursor: pointer;\n    pointer-events: all; \n    transition: transform 0.2s ease-out, fill 0.2s ease-out;\n}\n\n.viz-signal .viz-signal-shape {\n    fill: inherit;\n}\n\n.viz-signal:hover {\n    fill: #60A5FA;\n    transform: scale(1.5);\n}\n\n.viz-data-point {\n  fill: #F59E0B;\n  transition: cx 0.3s ease-out, cy 0.3s ease-out;\n}\n\n/* Connection ports (hidden by default, shown on node hover) */\n.viz-port {\n  fill: #3B82F6;\n  stroke: white;\n  stroke-width: 1.5;\n  opacity: 0;\n  pointer-events: all;\n  cursor: crosshair;\n  transition: opacity 0.15s ease-out;\n}\n.viz-node-group:hover .viz-port {\n  opacity: 1;\n}\n";
+export declare const DEFAULT_VIZ_CSS = "\n.viz-canvas {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n}\n\n.viz-node-label,\n.viz-edge-label {\n  text-anchor: middle;\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(0);\n}\n\n.viz-canvas svg {\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n\n/* Keyframes */\n@keyframes vizFlow {\n  from {\n    stroke-dashoffset: 20;\n  }\n  to {\n    stroke-dashoffset: 0;\n  }\n}\n\n/* Animation Classes */\n\n/* Flow Animation (Dashed line moving) */\n.viz-anim-flow .viz-edge {\n  stroke-dasharray: 5, 5;\n  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;\n}\n\n/* Edge base styling (path elements need explicit fill:none) */\n.viz-edge {\n  fill: none;\n  stroke: currentColor;\n}\n\n.viz-edge-hit {\n  fill: none;\n}\n\n/* Node Transition */\n.viz-node-group {\n    transition: transform 0.3s ease-out, opacity 0.3s ease-out;\n}\n\n/* Overlay Classes */\n.viz-grid-label {\n  fill: #6B7280;\n  font-size: 14px;\n  font-weight: 600;\n  opacity: 1;\n}\n\n.viz-signal {\n    fill: #3B82F6;\n    cursor: pointer;\n    pointer-events: all; \n    transition: transform 0.2s ease-out, fill 0.2s ease-out;\n}\n\n.viz-signal .viz-signal-shape {\n    fill: inherit;\n}\n\n.viz-signal:hover {\n    fill: #60A5FA;\n    transform: scale(1.5);\n}\n\n.viz-data-point {\n  fill: #F59E0B;\n  transition: cx 0.3s ease-out, cy 0.3s ease-out;\n}\n\n/* Connection ports (hidden by default, shown on node hover) */\n.viz-port {\n  fill: #3B82F6;\n  stroke: white;\n  stroke-width: 1.5;\n  opacity: 0;\n  pointer-events: all;\n  cursor: crosshair;\n  transition: opacity 0.15s ease-out;\n}\n.viz-node-group:hover .viz-port {\n  opacity: 1;\n}\n\n/* Sketch / hand-drawn rendering */\n.viz-sketch {\n  stroke-linecap: round;\n  stroke-linejoin: round;\n  stroke-width: 2;\n}\n";

package/dist/styles.js

@@ -96,4 +96,11 @@ export const DEFAULT_VIZ_CSS = `
 .viz-node-group:hover .viz-port {
   opacity: 1;
 }
+
+/* Sketch / hand-drawn rendering */
+.viz-sketch {
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 2;
+}
 `;

package/dist/textUtils.d.ts

@@ -19,6 +19,7 @@ export interface RenderTextOptions {
     fill?: string;
     fontSize?: number | string;
     fontWeight?: number | string;
+    fontFamily?: string;
     textAnchor?: 'start' | 'middle' | 'end';
     dominantBaseline?: string;
     maxWidth?: number;

package/dist/textUtils.js

@@ -63,7 +63,7 @@ export const DEFAULT_LINE_HEIGHT = 1.2;
  * @param options layout and styling options
  */
 export function renderSvgText(x, y, text, options = {}) {
-    const { className = '', fill, fontSize, fontWeight, textAnchor = 'middle', dominantBaseline = 'middle', maxWidth, lineHeight = DEFAULT_LINE_HEIGHT, verticalAlign = 'middle', overflow, } = options;
+    const { className = '', fill, fontSize, fontWeight, fontFamily, textAnchor = 'middle', dominantBaseline = 'middle', maxWidth, lineHeight = DEFAULT_LINE_HEIGHT, verticalAlign = 'middle', overflow, } = options;
     // Resolve numeric font size for wrapping
     let numericFontSize = 12; // fallback
     if (typeof fontSize === 'number') {
@@ -106,6 +106,8 @@ export function renderSvgText(x, y, text, options = {}) {
         attrs.push(`font-size="${fontSize}"`);
     if (fontWeight !== undefined)
         attrs.push(`font-weight="${fontWeight}"`);
+    if (fontFamily !== undefined)
+        attrs.push(`font-family="${escapeXmlAttr(fontFamily)}"`);
     attrs.push(`text-anchor="${textAnchor}"`);
     // Only apply dominant-baseline if it evaluates to a single line safely,
     // or apply to the group. Usually best on the <text> element.

package/dist/types.d.ts

@@ -188,6 +188,7 @@ export type NodeLabel = {
     fill?: string;
     fontSize?: number | string;
     fontWeight?: number | string;
+    fontFamily?: string;
     textAnchor?: 'start' | 'middle' | 'end';
     dominantBaseline?: string;
     /** Maximum width for text wrapping (in px). If set, text wraps within this width. */
@@ -313,6 +314,31 @@ export interface VizNode {
         stroke?: string;
         strokeWidth?: number;
         opacity?: number;
+        /**
+         * SVG `stroke-dasharray` value.
+         * Use the presets `'dashed'` (`8,4`), `'dotted'` (`2,4`), `'dash-dot'` (`8,4,2,4`),
+         * or pass any valid SVG dasharray string (e.g. `'12, 3, 3, 3'`).
+         * `'solid'` (or omitting the property) renders a continuous stroke.
+         */
+        strokeDasharray?: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string;
+        /**
+         * Drop shadow rendered behind the node shape via an SVG `<filter>`.
+         *
+         * - `dx` — horizontal offset (default `2`)
+         * - `dy` — vertical offset (default `2`)
+         * - `blur` — Gaussian blur radius / stdDeviation (default `4`)
+         * - `color` — shadow color (default `'rgba(0,0,0,0.2)'`)
+         */
+        shadow?: {
+            dx?: number;
+            dy?: number;
+            blur?: number;
+            color?: string;
+        };
+        /** Render the node with a hand-drawn / sketchy appearance. */
+        sketch?: boolean;
+        /** Seed for deterministic sketch jitter (same seed → same wobble). */
+        sketchSeed?: number;
     };
     className?: string;
     data?: unknown;
@@ -344,6 +370,10 @@ export interface EdgeLabel {
     className?: string;
     dx?: number;
     dy?: number;
+    fill?: string;
+    fontSize?: number | string;
+    fontWeight?: number | string;
+    fontFamily?: string;
     /** Maximum width for text wrapping (in px). If set, text wraps within this width. */
     maxWidth?: number;
     /** Line height multiplier (default: 1.2) */
@@ -407,6 +437,8 @@ export interface VizEdge {
          * `'solid'` (or omitting the property) renders a continuous stroke.
          */
         strokeDasharray?: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string;
+        /** Render the edge with a hand-drawn / sketchy appearance. */
+        sketch?: boolean;
     };
     className?: string;
     hitArea?: number;
@@ -561,6 +593,25 @@ export interface NodeOptions {
         width?: number;
     };
     opacity?: number;
+    /** Dash pattern preset or custom SVG dasharray string. */
+    dash?: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string;
+    /**
+     * Drop shadow behind the node shape.
+     * `true` for default shadow, or a config object `{ dx, dy, blur, color }`.
+     */
+    shadow?: boolean | {
+        dx?: number;
+        dy?: number;
+        blur?: number;
+        color?: string;
+    };
+    /**
+     * Hand-drawn / sketchy rendering for this node.
+     * `true` uses a default seed; pass `{ seed }` for deterministic jitter.
+     */
+    sketch?: boolean | {
+        seed?: number;
+    };
     /** Explicit render order. Higher values render on top. Default: 0. */
     zIndex?: number;
     className?: string;
@@ -608,6 +659,8 @@ export interface EdgeOptions {
     opacity?: number;
     /** Dash pattern preset or custom SVG dasharray string. */
     dash?: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string;
+    /** Hand-drawn / sketchy rendering for this edge. */
+    sketch?: boolean;
     className?: string;
     anchor?: 'center' | 'boundary';
     fromPort?: string;
@@ -697,6 +750,11 @@ export type VizScene = {
      * Generated by the fluent AnimationBuilder API.
      */
     animationSpecs?: AnimationSpec[];
+    /** Global sketch / hand-drawn rendering mode. Applies to all nodes and edges. */
+    sketch?: {
+        enabled?: boolean;
+        seed?: number;
+    };
 };
 export interface PanZoomOptions {
     /** Enable pan & zoom (default: false) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A fluent, type-safe SVG scene builder for composing nodes, edges, animations, and overlays with incremental DOM updates and no framework dependency.",
   "keywords": [
     "visualization",