vizcraft 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # vizcraft
 
+## 1.7.1
+
+### Patch Changes
+
+- [#101](https://github.com/ChipiKaf/vizcraft/pull/101) [`c5084ad`](https://github.com/ChipiKaf/vizcraft/commit/c5084ad12a36b545df987cd425fd431cfb9903d4) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Fix `resolveEdgeGeometry`: `startAnchor`/`endAnchor` now return the true boundary/port positions where the edge exits/enters each node, instead of the ~15%/~85% label positions. Added `startLabel` and `endLabel` fields as explicit aliases for the label positions. For self-loops, anchors correspond to the exit/entry points on the node boundary.
+
 ## 1.7.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,7 @@ VizCraft is designed to make creating beautiful, animated node-link diagrams and
 
 - **Fluent Builder API**: Define your visualization scene using a readable, chainable API.
 - **Grid System**: Built-in 2D grid system for easy, structured layout of nodes.
+- **Auto-Layout Algorithms**: Built-in circular and grid layouts, custom sync/async algorithm support (e.g. ELK), and a `getNodeBoundingBox` utility for robust layout integration.
 - **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.
@@ -338,8 +339,10 @@ if (!geo) return; // edge not found or unresolvable
 
 overlayPath.setAttribute('d', geo.d); // SVG path
 positionToolbar(geo.mid); // midpoint
-drawHandle(geo.startAnchor); // source anchor
-drawHandle(geo.endAnchor); // target anchor
+drawHandle(geo.startAnchor); // true boundary exit point
+drawHandle(geo.endAnchor); // true boundary entry point
+positionSourceLabel(geo.startLabel); // ~15% along path
+positionTargetLabel(geo.endLabel); // ~85% along path
 geo.waypoints.forEach(drawDot); // waypoints
 if (geo.isSelfLoop) {
   /* ... */

package/dist/builder.d.ts

@@ -1,4 +1,4 @@
-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 type { Vec2, VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, RichText, RichTextToken, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, EdgePathResolver, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator, VizPlugin, VizEventMap, SyncLayoutAlgorithm, LayoutAlgorithm, SvgExportOptions } from './types';
 import { OverlayBuilder } from './overlays/builder';
 import type { AnimationSpec } from './animation/spec';
 import { type AnimationBuilder, type AnimatableProps, type TweenOptions } from './animation/builder';
@@ -12,12 +12,19 @@ export interface VizBuilder extends VizSceneMutator {
      */
     use<O>(plugin: VizPlugin<O>, options?: O): VizBuilder;
     /**
-     * Applies a layout algorithm to the current nodes and edges.
-     * @param algorithm The layout function to execute
+     * Applies a **synchronous** layout algorithm to the current nodes and edges.
+     * @param algorithm The layout function to execute (must return synchronously)
      * @param options Optional configuration for the layout algorithm
      * @returns The builder, for fluent chaining
      */
-    layout<O>(algorithm: LayoutAlgorithm<O>, options?: O): VizBuilder;
+    layout<O>(algorithm: SyncLayoutAlgorithm<O>, options?: O): VizBuilder;
+    /**
+     * Applies a layout algorithm that may be asynchronous (e.g. ELK via web workers).
+     * @param algorithm The layout function to execute (may return a Promise)
+     * @param options Optional configuration for the layout algorithm
+     * @returns A Promise that resolves to the builder, for fluent chaining
+     */
+    layoutAsync<O>(algorithm: LayoutAlgorithm<O>, options?: O): Promise<VizBuilder>;
     /**
      * Listen for lifecycle events (e.g. 'build', 'mount').
      * @param event The event name

package/dist/builder.js

@@ -17,6 +17,15 @@ import { getEffectiveNodeBounds } from './interaction/hitTest';
 import { defaultCoreIconRegistry } from './shapes/icons';
 import { NodeBuilderImpl, applyNodeOptions } from './nodes/builder';
 import { EdgeBuilderImpl, applyEdgeOptions } from './edges/builder';
+/**
+ * Runtime check for Promise-like values without `as any` casting.
+ */
+function isPromiseLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
 /**
  * Sanitise a CSS color value for use as a suffix in an SVG marker `id`.
  * Non-alphanumeric characters are replaced with underscores.
@@ -494,6 +503,26 @@ class VizBuilderImpl {
             edges: scene.edges,
         };
         const result = algorithm(graph, options);
+        // Guard: if the algorithm returned a Promise-like, throw a helpful error
+        if (isPromiseLike(result)) {
+            throw new Error('VizBuilder.layout: received a Promise from the layout algorithm. ' +
+                'Use .layoutAsync() for async layout engines.');
+        }
+        this._applyLayoutResult(result);
+        return this;
+    }
+    async layoutAsync(algorithm, options) {
+        const scene = this.build();
+        const graph = {
+            nodes: scene.nodes,
+            edges: scene.edges,
+        };
+        const result = await algorithm(graph, options);
+        this._applyLayoutResult(result);
+        return this;
+    }
+    /** @internal Apply positions and waypoints from a layout result. */
+    _applyLayoutResult(result) {
         // Apply computed node positions
         for (const [id, pos] of Object.entries(result.nodes)) {
             this.updateNode(id, { pos });
@@ -506,7 +535,6 @@ class VizBuilderImpl {
                 }
             }
         }
-        return this;
     }
     setEdgePathResolver(resolver) {
         this._edgePathResolver = resolver;

package/dist/edges/paths.d.ts

@@ -43,11 +43,15 @@ export declare function computeEdgeEndpoints(start: VizNode | null, end: VizNode
  * @param waypoints Optional intermediate points.
  */
 export declare function computeEdgePath(start: Vec2, end: Vec2, routing?: EdgeRouting, waypoints?: Vec2[]): EdgePathResult;
+/** Extends EdgePathResult with true boundary exit/entry points for self-loops. */
+export interface SelfLoopResult extends EdgePathResult {
+    /** Boundary point where the loop departs the node. */
+    exitPoint: Vec2;
+    /** Boundary point where the loop returns to the node. */
+    entryPoint: Vec2;
+}
 /**
- * Compute the SVG path and label positions for a self-loop edge.
- * A self-loop exits and enters the same node on the specified side.
- *
- * @param node The target node
- * @param edge The self-referencing VizEdge
+ * Compute the SVG path and positions for a self-loop edge.
+ * Exits and enters the same node on the specified side.
  */
-export declare function computeSelfLoop(node: VizNode, edge: VizEdge): EdgePathResult;
+export declare function computeSelfLoop(node: VizNode, edge: VizEdge): SelfLoopResult;

package/dist/edges/paths.js

@@ -297,11 +297,8 @@ function estimateNodeDims(shape) {
     return { w: 60, h: 60 };
 }
 /**
- * Compute the SVG path and label positions for a self-loop edge.
- * A self-loop exits and enters the same node on the specified side.
- *
- * @param node The target node
- * @param edge The self-referencing VizEdge
+ * Compute the SVG path and positions for a self-loop edge.
+ * Exits and enters the same node on the specified side.
  */
 export function computeSelfLoop(node, edge) {
     const c = effectivePos(node);
@@ -314,6 +311,7 @@ export function computeSelfLoop(node, edge) {
     const spread = Math.min(20, (side === 'top' || side === 'bottom' ? w : h) * 0.8);
     let d = '';
     let start, mid, end;
+    let exitPt, entryPt;
     switch (side) {
         case 'top': {
             const sx = c.x - spread / 2;
@@ -322,6 +320,8 @@ export function computeSelfLoop(node, edge) {
             const ey = c.y - h / 2;
             const cpY = sy - size * 1.5;
             d = `M ${sx} ${sy} C ${sx - spread / 2} ${cpY}, ${ex + spread / 2} ${cpY}, ${ex} ${ey}`;
+            exitPt = { x: sx, y: sy };
+            entryPt = { x: ex, y: ey };
             start = { x: sx, y: sy - size * 0.2 };
             mid = { x: c.x, y: sy - size };
             end = { x: ex, y: ey - size * 0.2 };
@@ -334,6 +334,8 @@ export function computeSelfLoop(node, edge) {
             const ey = c.y + h / 2;
             const cpY = sy + size * 1.5;
             d = `M ${sx} ${sy} C ${sx - spread / 2} ${cpY}, ${ex + spread / 2} ${cpY}, ${ex} ${ey}`;
+            exitPt = { x: sx, y: sy };
+            entryPt = { x: ex, y: ey };
             start = { x: sx, y: sy + size * 0.2 };
             mid = { x: c.x, y: sy + size };
             end = { x: ex, y: ey + size * 0.2 };
@@ -346,6 +348,8 @@ export function computeSelfLoop(node, edge) {
             const ey = c.y + spread / 2;
             const cpX = sx - size * 1.5;
             d = `M ${sx} ${sy} C ${cpX} ${sy - spread / 2}, ${cpX} ${ey + spread / 2}, ${ex} ${ey}`;
+            exitPt = { x: sx, y: sy };
+            entryPt = { x: ex, y: ey };
             start = { x: sx - size * 0.2, y: sy };
             mid = { x: sx - size, y: c.y };
             end = { x: ex - size * 0.2, y: ey };
@@ -358,11 +362,13 @@ export function computeSelfLoop(node, edge) {
             const ey = c.y + spread / 2;
             const cpX = sx + size * 1.5;
             d = `M ${sx} ${sy} C ${cpX} ${sy - spread / 2}, ${cpX} ${ey + spread / 2}, ${ex} ${ey}`;
+            exitPt = { x: sx, y: sy };
+            entryPt = { x: ex, y: ey };
             start = { x: sx + size * 0.2, y: sy };
             mid = { x: sx + size, y: c.y };
             end = { x: ex + size * 0.2, y: ey };
             break;
         }
     }
-    return { d, start, mid, end };
+    return { d, start, mid, end, exitPoint: exitPt, entryPoint: entryPt };
 }

package/dist/edges/resolveEdgeGeometry.d.ts

@@ -1,26 +1,19 @@
-/**
- * Convenience function that resolves the full rendered geometry for an edge
- * in a single call. Handles node lookup, dangling edges, self-loop detection,
- * port/angle/boundary anchors, waypoints, and routing.
- *
- * @module
- */
+/** Resolves full rendered geometry for an edge in a single call. @module */
 import type { Vec2, VizScene, VizEdge, VizNode } from '../types';
 import type { EdgePathResult } from './paths';
-/**
- * Fully resolved edge geometry returned by {@link resolveEdgeGeometry}.
- *
- * Extends `EdgePathResult` with extra convenience fields so consumers
- * never need to orchestrate multiple helpers manually.
- */
+/** Fully resolved edge geometry. Extends `EdgePathResult` with anchor and label positions. */
 export interface ResolvedEdgeGeometry extends EdgePathResult {
-    /** Source anchor position (alias of `start` from EdgePathResult, ~15% along path). */
+    /** Boundary/port position where the edge exits the source node. */
     startAnchor: Vec2;
-    /** Target anchor position (alias of `end` from EdgePathResult, ~85% along path). */
+    /** Boundary/port position where the edge enters the target node. */
     endAnchor: Vec2;
+    /** Label position ~15% along the path (alias of `start`). */
+    startLabel: Vec2;
+    /** Label position ~85% along the path (alias of `end`). */
+    endLabel: Vec2;
     /** Waypoints used for the path (empty array when none). */
     waypoints: Vec2[];
-    /** Whether this edge is a self-loop (same source and target node). */
+    /** Whether this edge is a self-loop. */
     isSelfLoop: boolean;
 }
 /**
@@ -43,12 +36,8 @@ export interface ResolvedEdgeGeometry extends EdgePathResult {
  */
 export declare function resolveEdgeGeometry(scene: VizScene, edgeId: string): ResolvedEdgeGeometry | null;
 /**
- * Lower-level helper: resolve geometry from an edge + a node lookup map.
- *
- * Useful when the caller already has a `Map` built (e.g. inside a render loop
- * processing many edges).
- *
- * @internal exported for advanced consumers and testing — prefer
- * {@link resolveEdgeGeometry} for typical usage.
+ * Resolve geometry from an edge + a pre-built node map.
+ * Prefer {@link resolveEdgeGeometry} unless you already hold the map.
+ * @internal
  */
 export declare function resolveEdgeGeometryFromData(edge: VizEdge, nodesById: Map<string, VizNode>): ResolvedEdgeGeometry | null;

package/dist/edges/resolveEdgeGeometry.js

@@ -1,12 +1,5 @@
-/**
- * Convenience function that resolves the full rendered geometry for an edge
- * in a single call. Handles node lookup, dangling edges, self-loop detection,
- * port/angle/boundary anchors, waypoints, and routing.
- *
- * @module
- */
+/** Resolves full rendered geometry for an edge in a single call. @module */
 import { computeEdgeEndpoints, computeEdgePath, computeSelfLoop, } from './paths';
-// ── Implementation ──────────────────────────────────────────────────────────
 /**
  * Resolve all rendered geometry for a single edge in one call.
  *
@@ -33,40 +26,41 @@ export function resolveEdgeGeometry(scene, edgeId) {
     return resolveEdgeGeometryFromData(edge, nodesById);
 }
 /**
- * Lower-level helper: resolve geometry from an edge + a node lookup map.
- *
- * Useful when the caller already has a `Map` built (e.g. inside a render loop
- * processing many edges).
- *
- * @internal exported for advanced consumers and testing — prefer
- * {@link resolveEdgeGeometry} for typical usage.
+ * Resolve geometry from an edge + a pre-built node map.
+ * Prefer {@link resolveEdgeGeometry} unless you already hold the map.
+ * @internal
  */
 export function resolveEdgeGeometryFromData(edge, nodesById) {
-    // ── Node lookup (null-safe for dangling edges) ──────────────────────────
     const startNode = edge.from ? (nodesById.get(edge.from) ?? null) : null;
     const endNode = edge.to ? (nodesById.get(edge.to) ?? null) : null;
-    // Bail out if a referenced node id doesn't exist.
     if (edge.from && !startNode)
         return null;
     if (edge.to && !endNode)
         return null;
-    // Bail out if both endpoints are entirely unresolvable.
     if (!startNode && !edge.fromAt && !endNode && !edge.toAt)
         return null;
-    // ── Self-loop detection ─────────────────────────────────────────────────
     const isSelfLoop = !!(startNode && endNode && startNode === endNode);
     let pathResult;
+    let anchorStart;
+    let anchorEnd;
     if (isSelfLoop) {
-        pathResult = computeSelfLoop(startNode, edge);
+        const selfLoop = computeSelfLoop(startNode, edge);
+        pathResult = selfLoop;
+        anchorStart = selfLoop.exitPoint;
+        anchorEnd = selfLoop.entryPoint;
     }
     else {
         const endpoints = computeEdgeEndpoints(startNode, endNode, edge);
         pathResult = computeEdgePath(endpoints.start, endpoints.end, edge.routing, edge.waypoints);
+        anchorStart = endpoints.start;
+        anchorEnd = endpoints.end;
     }
     return {
         ...pathResult,
-        startAnchor: pathResult.start,
-        endAnchor: pathResult.end,
+        startAnchor: anchorStart,
+        endAnchor: anchorEnd,
+        startLabel: pathResult.start,
+        endLabel: pathResult.end,
         waypoints: edge.waypoints ?? [],
         isSelfLoop,
     };

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from './edges/paths';
 export * from './edges/labels';
 export * from './edges/styles';
 export * from './edges/resolveEdgeGeometry';
-export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, } from './shapes/geometry';
+export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, getNodeBoundingBox, } from './shapes/geometry';
 export * from './animation/spec';
 export * from './animation/builder';
 export * from './animation/playback';

package/dist/index.js

@@ -9,7 +9,7 @@ export * from './edges/paths';
 export * from './edges/labels';
 export * from './edges/styles';
 export * from './edges/resolveEdgeGeometry';
-export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, } from './shapes/geometry';
+export { getDefaultPorts, getNodePorts, findPort, resolvePortPosition, computeNodeAnchorAtAngle, getNodeBoundingBox, } from './shapes/geometry';
 export * from './animation/spec';
 export * from './animation/builder';
 export * from './animation/playback';

package/dist/shapes/geometry.d.ts

@@ -52,3 +52,15 @@ export declare function findPort(node: VizNode, portId: string): NodePort | unde
  * Returns `undefined` if the port id is not found.
  */
 export declare function resolvePortPosition(node: VizNode, portId: string): Vec2 | undefined;
+/**
+ * Compute the tight axis-aligned bounding-box size of a node shape.
+ *
+ * Returns `{ width, height }` that enclose the rendered shape, accounting for
+ * orientation, direction, pointer height, and other shape-specific parameters.
+ * Intended as a convenience helper for layout algorithms and collision
+ * detection, to avoid duplicating per-shape switch logic.
+ */
+export declare function getNodeBoundingBox(shape: NodeShape): {
+    width: number;
+    height: number;
+};

package/dist/shapes/geometry.js

@@ -1404,7 +1404,7 @@ export function resolvePortPosition(node, portId) {
     return { x: pos.x + port.offset.x, y: pos.y + port.offset.y };
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-/** Approximate half-width / half-height for shapes that have a bounding box. */
+/** Axis-aligned half-width / half-height for each node shape. */
 function shapeBoundingBox(shape) {
     switch (shape.kind) {
         case 'circle':
@@ -1415,16 +1415,32 @@ function shapeBoundingBox(shape) {
             return { hw: shape.w / 2, hh: shape.h / 2 };
         case 'ellipse':
             return { hw: shape.rx, hh: shape.ry };
-        case 'hexagon':
-            return { hw: shape.r, hh: shape.r };
+        case 'hexagon': {
+            const orientation = shape.orientation ?? 'pointy';
+            // pointy-top: width = r·√3, height = 2r
+            // flat-top:   width = 2r,   height = r·√3
+            const SQRT3_2 = Math.sqrt(3) / 2;
+            return orientation === 'pointy'
+                ? { hw: shape.r * SQRT3_2, hh: shape.r }
+                : { hw: shape.r, hh: shape.r * SQRT3_2 };
+        }
         case 'cylinder':
             return { hw: shape.w / 2, hh: shape.h / 2 };
         case 'arc':
             return { hw: shape.r, hh: shape.r };
-        case 'blockArrow':
-            return { hw: shape.length / 2, hh: shape.headWidth / 2 };
-        case 'callout':
-            return { hw: shape.w / 2, hh: shape.h / 2 };
+        case 'blockArrow': {
+            const dir = shape.direction ?? 'right';
+            return dir === 'up' || dir === 'down'
+                ? { hw: shape.headWidth / 2, hh: shape.length / 2 }
+                : { hw: shape.length / 2, hh: shape.headWidth / 2 };
+        }
+        case 'callout': {
+            const side = shape.pointerSide ?? 'bottom';
+            const pH = shape.pointerHeight ?? Math.round(shape.h * 0.25);
+            const hw = shape.w / 2 + (side === 'left' || side === 'right' ? pH : 0);
+            const hh = shape.h / 2 + (side === 'top' || side === 'bottom' ? pH : 0);
+            return { hw, hh };
+        }
         case 'cloud':
             return { hw: shape.w / 2, hh: shape.h / 2 };
         case 'cross':
@@ -1458,3 +1474,15 @@ function shapeBoundingBox(shape) {
             return { hw: 0, hh: 0 };
     }
 }
+/**
+ * Compute the tight axis-aligned bounding-box size of a node shape.
+ *
+ * Returns `{ width, height }` that enclose the rendered shape, accounting for
+ * orientation, direction, pointer height, and other shape-specific parameters.
+ * Intended as a convenience helper for layout algorithms and collision
+ * detection, to avoid duplicating per-shape switch logic.
+ */
+export function getNodeBoundingBox(shape) {
+    const { hw, hh } = shapeBoundingBox(shape);
+    return { width: hw * 2, height: hh * 2 };
+}

package/dist/types.d.ts

@@ -862,6 +862,16 @@ export interface LayoutResult {
     }>;
 }
 /**
- * A layout algorithm computes positions for nodes in a graph.
+ * A synchronous layout algorithm that computes positions for nodes in a graph.
+ *
+ * Use this type for algorithms that return results immediately.
+ * See also {@link LayoutAlgorithm} for algorithms that may be async.
+ */
+export type SyncLayoutAlgorithm<Options = any> = (graph: LayoutGraph, options?: Options) => LayoutResult;
+/**
+ * A layout algorithm that may be synchronous or asynchronous.
+ *
+ * Use with {@link VizBuilder.layoutAsync} for async engines (e.g. ELK via
+ * web workers). For the sync-only variant, see {@link SyncLayoutAlgorithm}.
  */
-export type LayoutAlgorithm<Options = any> = (graph: LayoutGraph, options?: Options) => LayoutResult;
+export type LayoutAlgorithm<Options = any> = (graph: LayoutGraph, options?: Options) => LayoutResult | Promise<LayoutResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "1.7.0",
+  "version": "1.7.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",