vizcraft 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # vizcraft
 
+## 1.4.0
+
+### Minor Changes
+
+- [#86](https://github.com/ChipiKaf/vizcraft/pull/86) [`04df81d`](https://github.com/ChipiKaf/vizcraft/commit/04df81dfa0e2f6f4a54232f28382d285de3030c6) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Support dangling edges with free endpoints (source-only or target-only) for interactive diagrams. Added `danglingEdge()` builder method, `fromAt()`/`toAt()` on `EdgeBuilder`, and made `VizEdge.from`/`VizEdge.to` optional. Dangling edges work with all edge features including routing, markers, labels, styling, hit testing, SVG export, and DOM mounting.
+
+- [#88](https://github.com/ChipiKaf/vizcraft/pull/88) [`28390fc`](https://github.com/ChipiKaf/vizcraft/commit/28390fc49d614dbb5c5f3c6a576b52a527a2b4dc) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - - Add freeform perimeter anchors for edges (`fromAngle` / `toAngle`). Edges can now leave or arrive at a fixed angle on any node shape, overriding the default boundary projection. Supported via fluent `.fromAngle(deg)` / `.toAngle(deg)` methods and declarative `EdgeOptions`. Also exports `computeNodeAnchorAtAngle(node, angleDeg)` for advanced use.
+  - Support dangling edges with free endpoints (source-only or target-only) for interactive diagrams. Added `danglingEdge()` builder method, `fromAt()`/`toAt()` on `EdgeBuilder`, and made `VizEdge.from`/`VizEdge.to` optional. Dangling edges work with all edge features including routing, markers, labels, styling, hit testing, SVG export, and DOM mounting.
+
 ## 1.3.1
 
 ### Patch Changes

package/README.md

@@ -20,6 +20,7 @@ VizCraft is designed to make creating beautiful, animated node-link diagrams and
 - **Two Animation Systems**: Lightweight registry/CSS animations (e.g. edge `flow`) and data-only timeline animations (`AnimationSpec`).
 - **Framework Agnostic**: The core logic is pure TypeScript and can be used with any framework or Vanilla JS.
 - **Custom Overlays**: Create complex, custom UI elements that float on top of your visualization.
+- **Dangling Edges**: Create edges with free endpoints for drag-to-connect interactions.
 
 ## 📦 Installation
 
@@ -307,6 +308,12 @@ b.edge('srv', 'db').fromPort('out-1').toPort('in').arrow();
 
 // Default ports (no .port() needed) — every shape has built-in ports
 b.edge('a', 'b').fromPort('right').toPort('left').arrow();
+
+// Dangling edges — one or both endpoints at a free coordinate
+b.danglingEdge('preview').from('srv').toAt({ x: 300, y: 200 }).arrow().dashed();
+
+// Declarative dangling edge
+b.danglingEdge('e1', { from: 'srv', toAt: { x: 300, y: 200 }, arrow: true });
 ```
 
 | Method                   | Description                                                                                                                           |
@@ -323,6 +330,12 @@ b.edge('a', 'b').fromPort('right').toPort('left').arrow();
 | `.markerStart(type)`     | Set marker type at the source end. See `EdgeMarkerType`.                                                                              |
 | `.fromPort(portId)`      | Connect from a specific named port on the source node.                                                                                |
 | `.toPort(portId)`        | Connect to a specific named port on the target node.                                                                                  |
+| `.fromAngle(deg)`        | Set a fixed perimeter angle (degrees, 0 = right, 90 = down) on the source node.                                                       |
+| `.toAngle(deg)`          | Set a fixed perimeter angle (degrees, 0 = right, 90 = down) on the target node.                                                       |
+| `.from(nodeId)`          | Attach the source end to an existing node (useful with `danglingEdge()`).                                                             |
+| `.to(nodeId)`            | Attach the target end to an existing node (useful with `danglingEdge()`).                                                             |
+| `.fromAt(pos)`           | Set the free-endpoint coordinate for the source end (`{ x, y }`).                                                                     |
+| `.toAt(pos)`             | Set the free-endpoint coordinate for the target end (`{ x, y }`).                                                                     |
 | `.stroke(color, width?)` | Set stroke color and optional width.                                                                                                  |
 | `.fill(color)`           | Set fill color.                                                                                                                       |
 | `.opacity(value)`        | Set opacity (0–1).                                                                                                                    |

package/dist/builder.d.ts

@@ -1,4 +1,4 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, RichText, RichTextToken, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, EdgePathResolver, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator, VizPlugin, VizEventMap, LayoutAlgorithm, SvgExportOptions } from './types';
+import type { Vec2, VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, RichText, RichTextToken, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, EdgePathResolver, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator, VizPlugin, VizEventMap, LayoutAlgorithm, SvgExportOptions } from './types';
 import { OverlayBuilder } from './overlayBuilder';
 import type { AnimationSpec } from './anim/spec';
 import { type AnimationBuilder, type AnimatableProps, type TweenOptions } from './anim/animationBuilder';
@@ -56,6 +56,13 @@ export interface VizBuilder extends VizSceneMutator {
     edge(from: string, to: string, id?: string): EdgeBuilder;
     /** Create a fully-configured edge declaratively and return the parent VizBuilder. */
     edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
+    /**
+     * Create a dangling edge with at least one free endpoint.
+     * The free end renders at a canvas coordinate (`fromAt`/`toAt`) rather than a node.
+     */
+    danglingEdge(id: string, opts?: EdgeOptions): EdgeBuilder;
+    /** Declarative overload — returns the parent VizBuilder. */
+    danglingEdge(id: string, opts: EdgeOptions): VizBuilder;
     /** Hydrates the builder from an existing VizScene. */
     fromScene(scene: VizScene): VizBuilder;
     build(): VizScene;
@@ -257,6 +264,8 @@ interface NodeBuilder {
     node(id: string, opts: NodeOptions): VizBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
     edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
+    danglingEdge(id: string, opts?: EdgeOptions): EdgeBuilder;
+    danglingEdge(id: string, opts: EdgeOptions): VizBuilder;
     overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
     overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
@@ -269,6 +278,14 @@ interface EdgeBuilder {
     orthogonal(): EdgeBuilder;
     routing(mode: EdgeRouting): EdgeBuilder;
     via(x: number, y: number): EdgeBuilder;
+    /** Set the source node id (useful with `danglingEdge()`). */
+    from(nodeId: string): EdgeBuilder;
+    /** Set the target node id (useful with `danglingEdge()`). */
+    to(nodeId: string): EdgeBuilder;
+    /** Set the free-endpoint source position (when `from` is omitted). */
+    fromAt(pos: Vec2): EdgeBuilder;
+    /** Set the free-endpoint target position (when `to` is omitted). */
+    toAt(pos: Vec2): EdgeBuilder;
     label(text: string, opts?: Partial<EdgeLabel>): EdgeBuilder;
     /**
      * Create a rich text label (mixed formatting) using nested SVG <tspan> spans.
@@ -293,6 +310,10 @@ interface EdgeBuilder {
     fromPort(portId: string): EdgeBuilder;
     /** Connect the edge to a specific port on the target node. */
     toPort(portId: string): EdgeBuilder;
+    /** Set a fixed perimeter angle (degrees, 0 = right, 90 = down) on the source node. */
+    fromAngle(deg: number): EdgeBuilder;
+    /** Set a fixed perimeter angle (degrees, 0 = right, 90 = down) on the target node. */
+    toAngle(deg: number): EdgeBuilder;
     connect(anchor: 'center' | 'boundary'): EdgeBuilder;
     /** Sets the fill color of the edge path. */
     fill(color: string): EdgeBuilder;
@@ -333,6 +354,8 @@ interface EdgeBuilder {
     node(id: string, opts: NodeOptions): VizBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
     edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
+    danglingEdge(id: string, opts?: EdgeOptions): EdgeBuilder;
+    danglingEdge(id: string, opts: EdgeOptions): VizBuilder;
     overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
     overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;

package/dist/builder.js

@@ -43,6 +43,21 @@ const SHADOW_DEFAULTS = {
     blur: 4,
     color: 'rgba(0,0,0,0.2)',
 };
+/**
+ * Resolves edge endpoints for dangling edges.
+ * Returns `null` when a referenced node id doesn't exist.
+ */
+function resolveDanglingEdge(edge, nodesById) {
+    const start = edge.from ? (nodesById.get(edge.from) ?? null) : null;
+    const end = edge.to ? (nodesById.get(edge.to) ?? null) : null;
+    if (edge.from && !start)
+        return null;
+    if (edge.to && !end)
+        return null;
+    if (!start && !edge.fromAt && !end && !edge.toAt)
+        return null;
+    return { start, end };
+}
 /** Apply defaults to a partial shadow config. */
 function resolveShadow(shadow) {
     return {
@@ -382,8 +397,16 @@ function applyNodeOptions(nb, opts) {
     if (opts.parent)
         nb.parent(opts.parent);
 }
-/** Apply an `EdgeOptions` object to an `EdgeBuilder` (sugar over chaining). */
+/** Applies an `EdgeOptions` object to an `EdgeBuilder`. */
 function applyEdgeOptions(eb, opts) {
+    if (opts.from)
+        eb.from(opts.from);
+    if (opts.to)
+        eb.to(opts.to);
+    if (opts.fromAt)
+        eb.fromAt(opts.fromAt);
+    if (opts.toAt)
+        eb.toAt(opts.toAt);
     // Routing
     if (opts.routing)
         eb.routing(opts.routing);
@@ -426,6 +449,10 @@ function applyEdgeOptions(eb, opts) {
         eb.fromPort(opts.fromPort);
     if (opts.toPort)
         eb.toPort(opts.toPort);
+    if (opts.fromAngle !== undefined)
+        eb.fromAngle(opts.fromAngle);
+    if (opts.toAngle !== undefined)
+        eb.toAngle(opts.toAngle);
     // Labels
     if (opts.label) {
         if (typeof opts.label === 'string') {
@@ -786,6 +813,22 @@ class VizBuilderImpl {
         applyEdgeOptions(eb, idOrOpts);
         return this;
     }
+    danglingEdge(id, opts) {
+        if (!this._edges.has(id)) {
+            const edgeDef = { id };
+            if (opts?.fromAt)
+                edgeDef.fromAt = opts.fromAt;
+            if (opts?.toAt)
+                edgeDef.toAt = opts.toAt;
+            this._edges.set(id, edgeDef);
+            this._edgeOrder.push(id);
+        }
+        const eb = new EdgeBuilderImpl(this, this._edges.get(id));
+        if (!opts)
+            return eb;
+        applyEdgeOptions(eb, opts);
+        return this;
+    }
     /**
      * Hydrates the builder from an existing VizScene.
      * @param scene The scene to hydrate from
@@ -833,10 +876,12 @@ class VizBuilderImpl {
      */
     build() {
         this._edges.forEach((edge) => {
-            if (!this._nodes.has(edge.from)) {
+            // Only warn about missing nodes when a node id is specified
+            // (dangling edges intentionally omit from/to).
+            if (edge.from && !this._nodes.has(edge.from)) {
                 console.warn(`VizBuilder: Edge ${edge.id} references missing source node ${edge.from}`);
             }
-            if (!this._nodes.has(edge.to)) {
+            if (edge.to && !this._nodes.has(edge.to)) {
                 console.warn(`VizBuilder: Edge ${edge.id} references missing target node ${edge.to}`);
             }
         });
@@ -1271,10 +1316,10 @@ class VizBuilderImpl {
         });
         const processedEdgeIds = new Set();
         edges.forEach((edge) => {
-            const start = nodesById.get(edge.from);
-            const end = nodesById.get(edge.to);
-            if (!start || !end)
+            const resolved = resolveDanglingEdge(edge, nodesById);
+            if (!resolved)
                 return;
+            const { start, end } = resolved;
             processedEdgeIds.add(edge.id);
             let group = existingEdgesMap.get(edge.id);
             if (!group) {
@@ -1322,7 +1367,7 @@ class VizBuilderImpl {
             group.setAttribute('class', classes);
             // Use effective positions (handles runtime overrides internally via helper)
             let edgePath;
-            if (start === end) {
+            if (start && end && start === end) {
                 edgePath = computeSelfLoop(start, edge);
             }
             else {
@@ -1332,13 +1377,12 @@ class VizBuilderImpl {
             // Allow consumer override of the SVG path `d` string.
             if (this._edgePathResolver) {
                 const defaultResolver = (e) => {
-                    const s = nodesById.get(e.from);
-                    const t = nodesById.get(e.to);
-                    if (!s || !t)
+                    const r = resolveDanglingEdge(e, nodesById);
+                    if (!r)
                         return '';
-                    if (s === t)
-                        return computeSelfLoop(s, e).d;
-                    const endpoints = computeEdgeEndpoints(s, t, e);
+                    if (r.start && r.end && r.start === r.end)
+                        return computeSelfLoop(r.start, e).d;
+                    const endpoints = computeEdgeEndpoints(r.start, r.end, e);
                     return computeEdgePath(endpoints.start, endpoints.end, e.routing, e.waypoints).d;
                 };
                 try {
@@ -1945,10 +1989,10 @@ class VizBuilderImpl {
         // Render Edges
         svgContent += '<g class="viz-layer-edges" data-viz-layer="edges">';
         exportEdges.forEach((edge) => {
-            const start = nodesById.get(edge.from);
-            const end = nodesById.get(edge.to);
-            if (!start || !end)
+            const resolved = resolveDanglingEdge(edge, nodesById);
+            if (!resolved)
                 return;
+            const { start, end } = resolved;
             // Animations
             let animClasses = '';
             let animStyleStr = '';
@@ -1983,7 +2027,7 @@ class VizBuilderImpl {
                 ? `marker-start="url(#${markerIdFor(edge.markerStart, edge.style?.stroke, 'start')})"`
                 : '';
             let edgePath;
-            if (start === end) {
+            if (start && end && start === end) {
                 edgePath = computeSelfLoop(start, edge);
             }
             else {
@@ -1992,13 +2036,12 @@ class VizBuilderImpl {
             }
             if (this._edgePathResolver) {
                 const defaultResolver = (e) => {
-                    const s = nodesById.get(e.from);
-                    const t = nodesById.get(e.to);
-                    if (!s || !t)
+                    const r = resolveDanglingEdge(e, nodesById);
+                    if (!r)
                         return '';
-                    if (s === t)
-                        return computeSelfLoop(s, e).d;
-                    const endpoints = computeEdgeEndpoints(s, t, e);
+                    if (r.start && r.end && r.start === r.end)
+                        return computeSelfLoop(r.start, e).d;
+                    const endpoints = computeEdgeEndpoints(r.start, r.end, e);
                     return computeEdgePath(endpoints.start, endpoints.end, e.routing, e.waypoints).d;
                 };
                 try {
@@ -2625,6 +2668,9 @@ class NodeBuilderImpl {
     edge(from, to, idOrOpts) {
         return this._builder.edge(from, to, idOrOpts);
     }
+    danglingEdge(id, opts) {
+        return this._builder.danglingEdge(id, opts);
+    }
     overlay(arg1, arg2, arg3) {
         if (typeof arg1 === 'function')
             return this._builder.overlay(arg1);
@@ -2667,6 +2713,22 @@ class EdgeBuilderImpl {
         this.edgeDef.waypoints.push({ x, y });
         return this;
     }
+    from(nodeId) {
+        this.edgeDef.from = nodeId;
+        return this;
+    }
+    to(nodeId) {
+        this.edgeDef.to = nodeId;
+        return this;
+    }
+    fromAt(pos) {
+        this.edgeDef.fromAt = pos;
+        return this;
+    }
+    toAt(pos) {
+        this.edgeDef.toAt = pos;
+        return this;
+    }
     label(text, opts) {
         const lbl = { position: 'mid', text, dy: -10, ...opts };
         // Accumulate into the labels array
@@ -2738,6 +2800,14 @@ class EdgeBuilderImpl {
         this.edgeDef.toPort = portId;
         return this;
     }
+    fromAngle(deg) {
+        this.edgeDef.fromAngle = deg;
+        return this;
+    }
+    toAngle(deg) {
+        this.edgeDef.toAngle = deg;
+        return this;
+    }
     fill(color) {
         this.edgeDef.style = {
             ...(this.edgeDef.style || {}),
@@ -2854,6 +2924,9 @@ class EdgeBuilderImpl {
     edge(from, to, idOrOpts) {
         return this.parent.edge(from, to, idOrOpts);
     }
+    danglingEdge(id, opts) {
+        return this.parent.danglingEdge(id, opts);
+    }
     overlay(arg1, arg2, arg3) {
         if (typeof arg1 === 'function')
             return this.parent.overlay(arg1);

package/dist/edgePaths.d.ts

@@ -24,11 +24,13 @@ export interface EdgePathResult {
  * to the port's absolute position. Otherwise the legacy `anchor` mode
  * (`'center'` | `'boundary'`) is used.
  *
+ * Accepts `null` for either node to support dangling edges.
+ *
  * This replicates the logic used internally by the core builder and
  * runtime patcher so that external renderers (e.g. React) can
  * resolve boundary anchors consistently.
  */
-export declare function computeEdgeEndpoints(start: VizNode, end: VizNode, edge: VizEdge): {
+export declare function computeEdgeEndpoints(start: VizNode | null, end: VizNode | null, edge: VizEdge): {
     start: Vec2;
     end: Vec2;
 };

package/dist/edgePaths.js

@@ -6,7 +6,7 @@
  *   1. An SVG `d` attribute string (for `<path>` elements).
  *   2. A midpoint along the path (for label positioning).
  */
-import { computeNodeAnchor, effectivePos, effectiveShape, resolvePortPosition, } from './shapes';
+import { computeNodeAnchor, computeNodeAnchorAtAngle, effectivePos, effectiveShape, resolvePortPosition, } from './shapes';
 /**
  * Compute anchor-resolved start/end points for an edge.
  *
@@ -14,23 +14,53 @@ import { computeNodeAnchor, effectivePos, effectiveShape, resolvePortPosition, }
  * to the port's absolute position. Otherwise the legacy `anchor` mode
  * (`'center'` | `'boundary'`) is used.
  *
+ * Accepts `null` for either node to support dangling edges.
+ *
  * This replicates the logic used internally by the core builder and
  * runtime patcher so that external renderers (e.g. React) can
  * resolve boundary anchors consistently.
  */
 export function computeEdgeEndpoints(start, end, edge) {
     const anchor = edge.anchor ?? 'boundary';
-    const startPos = effectivePos(start);
-    const endPos = effectivePos(end);
-    // Port-based resolution takes precedence over anchor mode.
-    const startAnchor = edge.fromPort
-        ? (resolvePortPosition(start, edge.fromPort) ??
-            computeNodeAnchor(start, endPos, anchor))
-        : computeNodeAnchor(start, endPos, anchor);
-    const endAnchor = edge.toPort
-        ? (resolvePortPosition(end, edge.toPort) ??
-            computeNodeAnchor(end, startPos, anchor))
-        : computeNodeAnchor(end, startPos, anchor);
+    const freeStart = edge.fromAt;
+    const freeEnd = edge.toAt;
+    // Determine the "other" position for anchor resolution.
+    const endTarget = end ? effectivePos(end) : (freeEnd ?? { x: 0, y: 0 });
+    const startTarget = start
+        ? effectivePos(start)
+        : (freeStart ?? { x: 0, y: 0 });
+    // Source endpoint
+    let startAnchor;
+    if (start) {
+        if (edge.fromAngle !== undefined) {
+            startAnchor = computeNodeAnchorAtAngle(start, edge.fromAngle);
+        }
+        else {
+            startAnchor = edge.fromPort
+                ? (resolvePortPosition(start, edge.fromPort) ??
+                    computeNodeAnchor(start, endTarget, anchor))
+                : computeNodeAnchor(start, endTarget, anchor);
+        }
+    }
+    else {
+        startAnchor = freeStart ?? { x: 0, y: 0 };
+    }
+    // Target endpoint
+    let endAnchor;
+    if (end) {
+        if (edge.toAngle !== undefined) {
+            endAnchor = computeNodeAnchorAtAngle(end, edge.toAngle);
+        }
+        else {
+            endAnchor = edge.toPort
+                ? (resolvePortPosition(end, edge.toPort) ??
+                    computeNodeAnchor(end, startTarget, anchor))
+                : computeNodeAnchor(end, startTarget, anchor);
+        }
+    }
+    else {
+        endAnchor = freeEnd ?? { x: 0, y: 0 };
+    }
     return { start: startAnchor, end: endAnchor };
 }
 /**

package/dist/hitTest.js

@@ -264,19 +264,31 @@ export function hitTestRect(scene, rect) {
     // Check edges
     // Roughly test if the edge's bounding box intersects the rect
     for (const edge of scene.edges) {
-        const startNode = scene.nodes.find((n) => n.id === edge.from);
-        const endNode = scene.nodes.find((n) => n.id === edge.to);
-        if (!startNode || !endNode)
+        const startNode = edge.from
+            ? scene.nodes.find((n) => n.id === edge.from)
+            : undefined;
+        const endNode = edge.to
+            ? scene.nodes.find((n) => n.id === edge.to)
+            : undefined;
+        if (edge.from && !startNode)
+            continue;
+        if (edge.to && !endNode)
+            continue;
+        if (!startNode && !edge.fromAt && !endNode && !edge.toAt)
             continue;
         // Simplistic edge bounding box
-        const startPos = {
-            x: startNode.runtime?.x ?? startNode.pos.x,
-            y: startNode.runtime?.y ?? startNode.pos.y,
-        };
-        const endPos = {
-            x: endNode.runtime?.x ?? endNode.pos.x,
-            y: endNode.runtime?.y ?? endNode.pos.y,
-        };
+        const startPos = startNode
+            ? {
+                x: startNode.runtime?.x ?? startNode.pos.x,
+                y: startNode.runtime?.y ?? startNode.pos.y,
+            }
+            : (edge.fromAt ?? { x: 0, y: 0 });
+        const endPos = endNode
+            ? {
+                x: endNode.runtime?.x ?? endNode.pos.x,
+                y: endNode.runtime?.y ?? endNode.pos.y,
+            }
+            : (edge.toAt ?? { x: 0, y: 0 });
         const minX = Math.min(startPos.x, endPos.x) - 10;
         const maxX = Math.max(startPos.x, endPos.x) + 10;
         const minY = Math.min(startPos.y, endPos.y) - 10;
@@ -328,11 +340,17 @@ export function edgeDistance(scene, edgeId, point) {
     const edge = scene.edges.find((e) => e.id === edgeId);
     if (!edge)
         return Infinity;
-    const startNode = scene.nodes.find((n) => n.id === edge.from);
-    const endNode = scene.nodes.find((n) => n.id === edge.to);
-    if (!startNode || !endNode)
+    const startNode = edge.from
+        ? scene.nodes.find((n) => n.id === edge.from)
+        : null;
+    const endNode = edge.to ? scene.nodes.find((n) => n.id === edge.to) : null;
+    if (edge.from && !startNode)
+        return Infinity;
+    if (edge.to && !endNode)
+        return Infinity;
+    if (!startNode && !edge.fromAt && !endNode && !edge.toAt)
         return Infinity;
-    const { start, end } = computeEdgeEndpoints(startNode, endNode, edge);
+    const { start, end } = computeEdgeEndpoints(startNode ?? null, endNode ?? null, edge);
     const pathData = computeEdgePath(start, end, edge.routing, edge.waypoints);
     const polyline = samplePath(pathData.d, 10);
     return distToPolyline(point, polyline);

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from './overlayBuilder';
 export * from './edgePaths';
 export * from './edgeLabels';
 export * from './edgeStyles';
-export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, } from './shapes';
+export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, } from './shapes';
 export * from './anim/spec';
 export * from './anim/animationBuilder';
 export * from './anim/playback';

package/dist/index.js

@@ -8,7 +8,7 @@ export * from './overlayBuilder';
 export * from './edgePaths';
 export * from './edgeLabels';
 export * from './edgeStyles';
-export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, } from './shapes';
+export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, } from './shapes';
 export * from './anim/spec';
 export * from './anim/animationBuilder';
 export * from './anim/playback';

package/dist/runtimePatcher.js

@@ -571,12 +571,16 @@ export function patchRuntime(scene, ctx) {
         const line = ctx.edgeLinesById.get(edge.id);
         if (!group || !line)
             continue;
-        const start = nodesById.get(edge.from);
-        const end = nodesById.get(edge.to);
-        if (!start || !end)
+        const start = edge.from ? (nodesById.get(edge.from) ?? null) : null;
+        const end = edge.to ? (nodesById.get(edge.to) ?? null) : null;
+        if (edge.from && !start)
+            continue;
+        if (edge.to && !end)
+            continue;
+        if (!start && !edge.fromAt && !end && !edge.toAt)
             continue;
         let edgePath;
-        if (start === end) {
+        if (start && end && start === end) {
             edgePath = computeSelfLoop(start, edge);
         }
         else {
@@ -585,11 +589,15 @@ export function patchRuntime(scene, ctx) {
         }
         if (edgePathResolver) {
             const defaultResolver = (e) => {
-                const s = nodesById.get(e.from);
-                const t = nodesById.get(e.to);
-                if (!s || !t)
+                const s = e.from ? (nodesById.get(e.from) ?? null) : null;
+                const t = e.to ? (nodesById.get(e.to) ?? null) : null;
+                if (e.from && !s)
+                    return '';
+                if (e.to && !t)
+                    return '';
+                if (!s && !e.fromAt && !t && !e.toAt)
                     return '';
-                if (s === t)
+                if (s && t && s === t)
                     return computeSelfLoop(s, e).d;
                 const endpoints = computeEdgeEndpoints(s, t, e);
                 return computeEdgePath(endpoints.start, endpoints.end, e.routing, e.waypoints).d;

package/dist/shapes.d.ts

@@ -12,6 +12,10 @@ export interface ShapeBehavior<K extends NodeShape['kind']> {
     anchorBoundary(pos: Vec2, target: Vec2, shape: Extract<NodeShape, {
         kind: K;
     }>): Vec2;
+    /** Resolve a perimeter point at the given angle (degrees, 0 = right, 90 = down). */
+    anchorAtAngle(pos: Vec2, angleDeg: number, shape: Extract<NodeShape, {
+        kind: K;
+    }>): Vec2;
 }
 export declare function effectivePos(node: VizNode): Vec2;
 export declare function effectiveShape(node: VizNode): NodeShape;
@@ -19,6 +23,8 @@ export declare function getShapeBehavior(shape: NodeShape): ShapeBehavior<"circl
 export declare function applyShapeGeometry(el: SVGElement, shape: NodeShape, pos: Vec2): void;
 export declare function shapeSvgMarkup(shape: NodeShape, pos: Vec2, attrs: string): string;
 export declare function computeNodeAnchor(node: VizNode, target: Vec2, anchor: AnchorMode): Vec2;
+/** Resolve the perimeter point on a node's shape at the given angle (degrees, 0 = right, 90 = down). */
+export declare function computeNodeAnchorAtAngle(node: VizNode, angleDeg: number): Vec2;
 /**
  * Return the default (implicit) ports for a node shape.
  *

package/dist/shapes.js

@@ -30,6 +30,17 @@ export function effectiveShape(node) {
     }
     return shape;
 }
+const DEG_TO_RAD = Math.PI / 180;
+/** Resolve a rect boundary point at the given angle (degrees). */
+function rectAnchorAtAngle(pos, angleDeg, hw, hh) {
+    const rad = angleDeg * DEG_TO_RAD;
+    const dx = Math.cos(rad);
+    const dy = Math.sin(rad);
+    if (dx === 0 && dy === 0)
+        return { ...pos };
+    const scale = Math.min(hw / Math.abs(dx || 1e-6), hh / Math.abs(dy || 1e-6));
+    return { x: pos.x + dx * scale, y: pos.y + dy * scale };
+}
 function diamondPoints(pos, w, h) {
     const hw = w / 2;
     const hh = h / 2;
@@ -58,6 +69,13 @@ const circleBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        return {
+            x: pos.x + shape.r * Math.cos(rad),
+            y: pos.y + shape.r * Math.sin(rad),
+        };
+    },
 };
 const rectBehavior = {
     kind: 'rect',
@@ -87,6 +105,9 @@ const rectBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 const diamondBehavior = {
     kind: 'diamond',
@@ -112,6 +133,18 @@ const diamondBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        const dx = Math.cos(rad);
+        const dy = Math.sin(rad);
+        if (dx === 0 && dy === 0)
+            return { ...pos };
+        const hw = shape.w / 2;
+        const hh = shape.h / 2;
+        const denom = Math.abs(dx) / hw + Math.abs(dy) / hh;
+        const scale = denom === 0 ? 0 : 1 / denom;
+        return { x: pos.x + dx * scale, y: pos.y + dy * scale };
+    },
 };
 function cylinderGeometry(shape, pos) {
     const rx = shape.w / 2;
@@ -199,6 +232,9 @@ const cylinderBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 function hexagonPoints(pos, r, orientation) {
     const pts = [];
@@ -238,6 +274,13 @@ const hexagonBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        return {
+            x: pos.x + shape.r * Math.cos(rad),
+            y: pos.y + shape.r * Math.sin(rad),
+        };
+    },
 };
 const ellipseBehavior = {
     kind: 'ellipse',
@@ -262,6 +305,13 @@ const ellipseBehavior = {
             y: pos.y + (shape.rx * shape.ry * dy) / denom,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        return {
+            x: pos.x + shape.rx * Math.cos(rad),
+            y: pos.y + shape.ry * Math.sin(rad),
+        };
+    },
 };
 function arcPathD(shape, pos) {
     const toRad = Math.PI / 180;
@@ -303,6 +353,13 @@ const arcBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        return {
+            x: pos.x + shape.r * Math.cos(rad),
+            y: pos.y + shape.r * Math.sin(rad),
+        };
+    },
 };
 function blockArrowPoints(shape, pos) {
     const halfBody = shape.bodyWidth / 2;
@@ -360,6 +417,12 @@ const blockArrowBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const dir = shape.direction ?? 'right';
+        const hw = dir === 'up' || dir === 'down' ? shape.headWidth / 2 : shape.length / 2;
+        const hh = dir === 'up' || dir === 'down' ? shape.length / 2 : shape.headWidth / 2;
+        return rectAnchorAtAngle(pos, angleDeg, hw, hh);
+    },
 };
 function calloutPathD(shape, pos) {
     const hw = shape.w / 2;
@@ -461,6 +524,9 @@ const calloutBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 /**
  * Compute the SVG path for a cloud shape that fits within a w×h bounding box
@@ -514,6 +580,12 @@ const cloudBehavior = {
             y: pos.y + (a * b * dy) / denom,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        const a = shape.w / 2;
+        const b = shape.h / 2;
+        return { x: pos.x + a * Math.cos(rad), y: pos.y + b * Math.sin(rad) };
+    },
 };
 function crossPoints(shape, pos) {
     const hs = shape.size / 2;
@@ -556,6 +628,9 @@ const crossBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.size / 2, shape.size / 2);
+    },
 };
 function cubeVertices(shape, pos) {
     const hw = shape.w / 2;
@@ -628,6 +703,10 @@ const cubeBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const d = shape.depth ?? Math.round(shape.w * 0.2);
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2 + d / 2, shape.h / 2 + d / 2);
+    },
 };
 const pathBehavior = {
     kind: 'path',
@@ -654,6 +733,9 @@ const pathBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 function documentPathD(shape, pos) {
     const hw = shape.w / 2;
@@ -693,6 +775,9 @@ const documentBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 function noteVertices(shape, pos) {
     const hw = shape.w / 2;
@@ -748,6 +833,9 @@ const noteBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 function parallelogramPoints(shape, pos) {
     const hw = shape.w / 2;
@@ -785,6 +873,10 @@ const parallelogramBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const sk = shape.skew ?? Math.round(shape.w * 0.2);
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2 + sk / 2, shape.h / 2);
+    },
 };
 function starPoints(shape, pos) {
     const n = shape.points;
@@ -820,6 +912,13 @@ const starBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const rad = angleDeg * DEG_TO_RAD;
+        return {
+            x: pos.x + shape.outerR * Math.cos(rad),
+            y: pos.y + shape.outerR * Math.sin(rad),
+        };
+    },
 };
 function trapezoidPoints(shape, pos) {
     const htw = shape.topW / 2;
@@ -855,6 +954,10 @@ const trapezoidBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        const hw = Math.max(shape.topW, shape.bottomW) / 2;
+        return rectAnchorAtAngle(pos, angleDeg, hw, shape.h / 2);
+    },
 };
 function trianglePoints(shape, pos) {
     const hw = shape.w / 2;
@@ -910,6 +1013,9 @@ const triangleBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 const imageBehavior = {
     kind: 'image',
@@ -955,6 +1061,9 @@ const imageBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 const iconBehavior = {
     kind: 'icon',
@@ -1006,6 +1115,9 @@ const iconBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 const svgBehavior = {
     kind: 'svg',
@@ -1044,6 +1156,9 @@ const svgBehavior = {
             y: pos.y + dy * scale,
         };
     },
+    anchorAtAngle(pos, angleDeg, shape) {
+        return rectAnchorAtAngle(pos, angleDeg, shape.w / 2, shape.h / 2);
+    },
 };
 const shapeBehaviorRegistry = {
     circle: circleBehavior,
@@ -1089,6 +1204,13 @@ export function computeNodeAnchor(node, target, anchor) {
     const behavior = getShapeBehavior(shape);
     return behavior.anchorBoundary(pos, target, shape);
 }
+/** Resolve the perimeter point on a node's shape at the given angle (degrees, 0 = right, 90 = down). */
+export function computeNodeAnchorAtAngle(node, angleDeg) {
+    const pos = effectivePos(node);
+    const shape = effectiveShape(node);
+    const behavior = getShapeBehavior(shape);
+    return behavior.anchorAtAngle(pos, angleDeg, shape);
+}
 // ── Connection Ports ────────────────────────────────────────────────────────
 /**
  * Return the default (implicit) ports for a node shape.

package/dist/types.d.ts

@@ -402,8 +402,18 @@ export type EdgeRouting = 'straight' | 'curved' | 'orthogonal';
 export type EdgeMarkerType = 'none' | 'arrow' | 'arrowOpen' | 'diamond' | 'diamondOpen' | 'circle' | 'circleOpen' | 'square' | 'bar' | 'halfArrow';
 export interface VizEdge {
     id: string;
-    from: string;
-    to: string;
+    /** Source node id. Optional for dangling edges (use `fromAt` instead). */
+    from?: string;
+    /** Target node id. Optional for dangling edges (use `toAt` instead). */
+    to?: string;
+    /** Free-endpoint coordinate for the source end (when `from` is omitted). */
+    fromAt?: Vec2;
+    /** Free-endpoint coordinate for the target end (when `to` is omitted). */
+    toAt?: Vec2;
+    /** Angle (degrees) for the source perimeter anchor. 0 = right, 90 = down. */
+    fromAngle?: number;
+    /** Angle (degrees) for the target perimeter anchor. 0 = right, 90 = down. */
+    toAngle?: number;
     /** Arbitrary consumer-defined metadata associated with the edge. */
     meta?: Record<string, unknown>;
     /** @deprecated Use `labels` for multi-position support. Kept for backwards compatibility. */
@@ -642,6 +652,18 @@ export interface NodeOptions {
 export interface EdgeOptions {
     /** Custom edge id (defaults to `"from->to"`). */
     id?: string;
+    /** Source node id. Use with `danglingEdge()` to attach one end to a node. */
+    from?: string;
+    /** Target node id. Use with `danglingEdge()` to attach one end to a node. */
+    to?: string;
+    /** Free-endpoint coordinate for the source end (when `from` is omitted). */
+    fromAt?: Vec2;
+    /** Free-endpoint coordinate for the target end (when `to` is omitted). */
+    toAt?: Vec2;
+    /** Angle (degrees) for the source perimeter anchor. 0 = right, 90 = down. */
+    fromAngle?: number;
+    /** Angle (degrees) for the target perimeter anchor. 0 = right, 90 = down. */
+    toAngle?: number;
     routing?: EdgeRouting;
     waypoints?: Vec2[];
     /** Convenience for arrow markers. `true` = markerEnd arrow, `'both'` = both ends. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "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",