vizcraft 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 1.7.0
+
+### Minor Changes
+
+- [#98](https://github.com/ChipiKaf/vizcraft/pull/98) [`b513c21`](https://github.com/ChipiKaf/vizcraft/commit/b513c21308d115b0634cf63a0c63b3708684a172) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Add `resolveEdgeGeometry(scene, edgeId)` convenience function that resolves all rendered geometry for an edge in a single call — node lookup, self-loop detection, port/angle/boundary anchors, waypoints, routing, SVG path, midpoint, and label positions. Also exports `resolveEdgeGeometryFromData` for batch processing with a pre-built node map.
+
+## 1.6.0
+
+### Minor Changes
+
+- [`8020286`](https://github.com/ChipiKaf/vizcraft/commit/8020286d96d210f932a493184d820111e8c9ac7d) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Added fromProt and toPort to attach edges to specific edges. Updated documentation to follow Diátaxis structure
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -309,11 +309,16 @@ 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();
 
-// Equidistant port distribution — N evenly spaced ports by perimeter arc length
-import { getEquidistantPorts, toNodePorts } from 'vizcraft';
-const ports = getEquidistantPorts({ kind: 'hexagon', r: 40 }, 6); // 6 ports
+// Equidistant port distribution — stable, location-based IDs
+import { getEquidistantPorts, toNodePorts, findPortNearest } from 'vizcraft';
+const ports = getEquidistantPorts({ kind: 'rect', w: 120, h: 60 }, 8);
+// → [{ id: 'top-0', … }, { id: 'top-1', … }, { id: 'right-0', … }, …]
 const nodePorts = toNodePorts(ports); // → NodePort[] ready for node.ports
 
+// Snap to nearest port (node-local coordinates)
+const nearest = findPortNearest(node, clickX - node.pos.x, clickY - node.pos.y);
+if (nearest) b.edge('a', 'b').toPort(nearest.id);
+
 // Dangling edges — one or both endpoints at a free coordinate
 b.danglingEdge('preview').from('srv').toAt({ x: 300, y: 200 }).arrow().dashed();
 
@@ -321,6 +326,26 @@ b.danglingEdge('preview').from('srv').toAt({ x: 300, y: 200 }).arrow().dashed();
 b.danglingEdge('e1', { from: 'srv', toAt: { x: 300, y: 200 }, arrow: true });
 ```
 
+#### Resolving edge geometry
+
+`resolveEdgeGeometry(scene, edgeId)` resolves all rendered geometry for an edge in a single call — anchor points, SVG path, midpoint, label positions, waypoints, and self-loop detection:
+
+```ts
+import { resolveEdgeGeometry } from 'vizcraft';
+
+const geo = resolveEdgeGeometry(scene, 'edge-1');
+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
+geo.waypoints.forEach(drawDot); // waypoints
+if (geo.isSelfLoop) {
+  /* ... */
+} // self-loop flag
+```
+
 | Method                   | Description                                                                                                                           |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `.straight()`            | Direct line (default). With waypoints → polyline.                                                                                     |

package/dist/edges/index.d.ts

@@ -1,4 +1,5 @@
 export * from './paths';
 export * from './labels';
 export * from './styles';
+export * from './resolveEdgeGeometry';
 export { EdgeBuilderImpl, applyEdgeOptions } from './builder';

package/dist/edges/index.js

@@ -1,4 +1,5 @@
 export * from './paths';
 export * from './labels';
 export * from './styles';
+export * from './resolveEdgeGeometry';
 export { EdgeBuilderImpl, applyEdgeOptions } from './builder';

package/dist/edges/resolveEdgeGeometry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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
+ */
+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.
+ */
+export interface ResolvedEdgeGeometry extends EdgePathResult {
+    /** Source anchor position (alias of `start` from EdgePathResult, ~15% along path). */
+    startAnchor: Vec2;
+    /** Target anchor position (alias of `end` from EdgePathResult, ~85% along path). */
+    endAnchor: Vec2;
+    /** Waypoints used for the path (empty array when none). */
+    waypoints: Vec2[];
+    /** Whether this edge is a self-loop (same source and target node). */
+    isSelfLoop: boolean;
+}
+/**
+ * Resolve all rendered geometry for a single edge in one call.
+ *
+ * Returns `null` when:
+ * - The edge id is not found in the scene.
+ * - A referenced `from` / `to` node id does not exist.
+ * - Both endpoints are missing (no `from`/`to` and no `fromAt`/`toAt`).
+ *
+ * @example
+ * ```ts
+ * import { resolveEdgeGeometry } from 'vizcraft';
+ *
+ * const geo = resolveEdgeGeometry(scene, 'edge-1');
+ * if (!geo) return;
+ * overlay.setAttribute('d', geo.d);
+ * positionToolbar(geo.mid);
+ * ```
+ */
+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.
+ */
+export declare function resolveEdgeGeometryFromData(edge: VizEdge, nodesById: Map<string, VizNode>): ResolvedEdgeGeometry | null;

package/dist/edges/resolveEdgeGeometry.js

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+import { computeEdgeEndpoints, computeEdgePath, computeSelfLoop, } from './paths';
+// ── Implementation ──────────────────────────────────────────────────────────
+/**
+ * Resolve all rendered geometry for a single edge in one call.
+ *
+ * Returns `null` when:
+ * - The edge id is not found in the scene.
+ * - A referenced `from` / `to` node id does not exist.
+ * - Both endpoints are missing (no `from`/`to` and no `fromAt`/`toAt`).
+ *
+ * @example
+ * ```ts
+ * import { resolveEdgeGeometry } from 'vizcraft';
+ *
+ * const geo = resolveEdgeGeometry(scene, 'edge-1');
+ * if (!geo) return;
+ * overlay.setAttribute('d', geo.d);
+ * positionToolbar(geo.mid);
+ * ```
+ */
+export function resolveEdgeGeometry(scene, edgeId) {
+    const edge = scene.edges.find((e) => e.id === edgeId);
+    if (!edge)
+        return null;
+    const nodesById = new Map(scene.nodes.map((n) => [n.id, n]));
+    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.
+ */
+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;
+    if (isSelfLoop) {
+        pathResult = computeSelfLoop(startNode, edge);
+    }
+    else {
+        const endpoints = computeEdgeEndpoints(startNode, endNode, edge);
+        pathResult = computeEdgePath(endpoints.start, endpoints.end, edge.routing, edge.waypoints);
+    }
+    return {
+        ...pathResult,
+        startAnchor: pathResult.start,
+        endAnchor: pathResult.end,
+        waypoints: edge.waypoints ?? [],
+        isSelfLoop,
+    };
+}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './overlays/builder';
 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 * from './animation/spec';
 export * from './animation/builder';

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './overlays/builder';
 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 * from './animation/spec';
 export * from './animation/builder';

package/dist/ports/equidistant/index.d.ts

@@ -1,2 +1,2 @@
 export type { EquidistantPort, PerimeterStrategy } from './types';
-export { getEquidistantPorts, toNodePorts, registerPerimeterStrategy, } from './registry';
+export { getEquidistantPorts, toNodePorts, findPortNearest, registerPerimeterStrategy, } from './registry';

package/dist/ports/equidistant/index.js

@@ -1 +1 @@
-export { getEquidistantPorts, toNodePorts, registerPerimeterStrategy, } from './registry';
+export { getEquidistantPorts, toNodePorts, findPortNearest, registerPerimeterStrategy, } from './registry';

package/dist/ports/equidistant/registry.d.ts

@@ -1,4 +1,4 @@
-import type { NodePort, NodeShape } from '../../types';
+import type { NodePort, NodeShape, VizNode } from '../../types';
 import type { EquidistantPort, PerimeterStrategy } from './types';
 /** Register (or replace) a {@link PerimeterStrategy} for a shape kind. */
 export declare function registerPerimeterStrategy<K extends NodeShape['kind']>(strategy: PerimeterStrategy<K>): void;
@@ -7,9 +7,31 @@ export declare function registerPerimeterStrategy<K extends NodeShape['kind']>(s
  * Delegates to a registered {@link PerimeterStrategy} or falls back to
  * a bounding-box rectangle approximation.
  *
+ * Port IDs are **location-based** and stable across count changes:
+ * - Polygon shapes with named sides: `{side}-{index}` (e.g. `top-0`,
+ *   `right-1`).
+ * - Curved / complex shapes: `{angleBucket}-{index}` (e.g. `0-0`,
+ *   `270-1`).
+ *
  * @param shape - The node shape specification.
  * @param count - Number of ports (uses a shape-specific default when omitted).
  */
 export declare function getEquidistantPorts(shape: NodeShape, count?: number): EquidistantPort[];
 /** Convert equidistant ports to `NodePort[]` with `offset` and `direction`. */
 export declare function toNodePorts(ports: readonly EquidistantPort[]): NodePort[];
+/**
+ * Return the port on `node` closest to the given point (in **node-local
+ * coordinates**, i.e. relative to the node center).
+ *
+ * Uses the node's effective ports ({@link getNodePorts} — explicit
+ * `node.ports` when set, otherwise shape defaults).
+ *
+ * Returns `undefined` when the node has no ports.
+ *
+ * @example
+ * ```ts
+ * const port = findPortNearest(node, clickX - node.x, clickY - node.y);
+ * if (port) edgeBuilder.toPort(port.id);
+ * ```
+ */
+export declare function findPortNearest(node: VizNode, x: number, y: number): NodePort | undefined;

package/dist/ports/equidistant/registry.js

@@ -1,3 +1,4 @@
+import { getNodePorts } from '../../shapes/geometry';
 import { walkPolygonEquidistant } from './utils';
 import { builtInStrategies } from './strategies';
 const FALLBACK_COUNT = 8;
@@ -63,6 +64,7 @@ function shapeBoundingBox(shape) {
             return { hw: 0, hh: 0 };
     }
 }
+const BBOX_SIDES = ['top', 'right', 'bottom', 'left'];
 function boundingBoxFallback(shape, count) {
     const { hw, hh } = shapeBoundingBox(shape);
     return walkPolygonEquidistant([
@@ -70,13 +72,19 @@ function boundingBoxFallback(shape, count) {
         { x: hw, y: -hh },
         { x: hw, y: hh },
         { x: -hw, y: hh },
-    ], count);
+    ], count, BBOX_SIDES);
 }
 /**
  * Compute N equidistant points along a shape's perimeter by arc length.
  * Delegates to a registered {@link PerimeterStrategy} or falls back to
  * a bounding-box rectangle approximation.
  *
+ * Port IDs are **location-based** and stable across count changes:
+ * - Polygon shapes with named sides: `{side}-{index}` (e.g. `top-0`,
+ *   `right-1`).
+ * - Curved / complex shapes: `{angleBucket}-{index}` (e.g. `0-0`,
+ *   `270-1`).
+ *
  * @param shape - The node shape specification.
  * @param count - Number of ports (uses a shape-specific default when omitted).
  */
@@ -102,3 +110,35 @@ export function toNodePorts(ports) {
         direction: p.angle,
     }));
 }
+/**
+ * Return the port on `node` closest to the given point (in **node-local
+ * coordinates**, i.e. relative to the node center).
+ *
+ * Uses the node's effective ports ({@link getNodePorts} — explicit
+ * `node.ports` when set, otherwise shape defaults).
+ *
+ * Returns `undefined` when the node has no ports.
+ *
+ * @example
+ * ```ts
+ * const port = findPortNearest(node, clickX - node.x, clickY - node.y);
+ * if (port) edgeBuilder.toPort(port.id);
+ * ```
+ */
+export function findPortNearest(node, x, y) {
+    const ports = getNodePorts(node);
+    if (ports.length === 0)
+        return undefined;
+    let nearest;
+    let bestDist = Infinity;
+    for (const port of ports) {
+        const dx = port.offset.x - x;
+        const dy = port.offset.y - y;
+        const d = dx * dx + dy * dy;
+        if (d < bestDist) {
+            bestDist = d;
+            nearest = port;
+        }
+    }
+    return nearest;
+}

package/dist/ports/equidistant/strategies/circle.js

@@ -1,4 +1,4 @@
-import { RAD, portFromPoint } from '../utils';
+import { RAD, portFromPoint, assignAngleBucketIds } from '../utils';
 function circleEquidistant(r, count) {
     const ports = [];
     for (let i = 0; i < count; i++) {
@@ -6,7 +6,7 @@ function circleEquidistant(r, count) {
         const aRad = aDeg * RAD;
         ports.push(portFromPoint({ x: r * Math.cos(aRad), y: r * Math.sin(aRad) }, i, i / count));
     }
-    return ports;
+    return assignAngleBucketIds(ports);
 }
 export const circleStrategy = {
     kind: 'circle',

package/dist/ports/equidistant/strategies/diamond.js

@@ -9,4 +9,10 @@ function diamondVertices(w, h) {
         { x: -hw, y: 0 },
     ];
 }
-export const diamondStrategy = polygonStrategy('diamond', 4, (s) => diamondVertices(s.w, s.h));
+const DIAMOND_SIDES = [
+    'top-right',
+    'bottom-right',
+    'bottom-left',
+    'top-left',
+];
+export const diamondStrategy = polygonStrategy('diamond', 4, (s) => diamondVertices(s.w, s.h), () => DIAMOND_SIDES);

package/dist/ports/equidistant/strategies/hexagon.js

@@ -8,4 +8,24 @@ function hexagonVertices(r, orientation) {
     }
     return verts;
 }
-export const hexagonStrategy = polygonStrategy('hexagon', 6, (s) => hexagonVertices(s.r, s.orientation ?? 'pointy'));
+function hexagonSideLabels(orientation) {
+    if (orientation === 'pointy') {
+        return [
+            'top-right',
+            'right',
+            'bottom-right',
+            'bottom-left',
+            'left',
+            'top-left',
+        ];
+    }
+    return [
+        'bottom-right',
+        'bottom',
+        'bottom-left',
+        'top-left',
+        'top',
+        'top-right',
+    ];
+}
+export const hexagonStrategy = polygonStrategy('hexagon', 6, (s) => hexagonVertices(s.r, s.orientation ?? 'pointy'), (s) => hexagonSideLabels(s.orientation ?? 'pointy'));

package/dist/ports/equidistant/strategies/parallelogram.js

@@ -10,4 +10,5 @@ function parallelogramVertices(w, h, skew) {
         { x: -hw - half, y: hh },
     ];
 }
-export const parallelogramStrategy = polygonStrategy('parallelogram', 8, (s) => parallelogramVertices(s.w, s.h, s.skew ?? Math.round(s.w * 0.2)));
+const PARALLELOGRAM_SIDES = ['top', 'right', 'bottom', 'left'];
+export const parallelogramStrategy = polygonStrategy('parallelogram', 8, (s) => parallelogramVertices(s.w, s.h, s.skew ?? Math.round(s.w * 0.2)), () => PARALLELOGRAM_SIDES);

package/dist/ports/equidistant/strategies/rect.js

@@ -9,4 +9,5 @@ function rectVertices(w, h) {
         { x: -hw, y: hh },
     ];
 }
-export const rectStrategy = polygonStrategy('rect', 8, (s) => rectVertices(s.w, s.h));
+const RECT_SIDES = ['top', 'right', 'bottom', 'left'];
+export const rectStrategy = polygonStrategy('rect', 8, (s) => rectVertices(s.w, s.h), () => RECT_SIDES);

package/dist/ports/equidistant/strategies/trapezoid.js

@@ -10,4 +10,5 @@ function trapezoidVertices(topW, bottomW, h) {
         { x: -hbw, y: hh },
     ];
 }
-export const trapezoidStrategy = polygonStrategy('trapezoid', 8, (s) => trapezoidVertices(s.topW, s.bottomW, s.h));
+const TRAPEZOID_SIDES = ['top', 'right', 'bottom', 'left'];
+export const trapezoidStrategy = polygonStrategy('trapezoid', 8, (s) => trapezoidVertices(s.topW, s.bottomW, s.h), () => TRAPEZOID_SIDES);

package/dist/ports/equidistant/strategies/triangle.js

@@ -29,4 +29,16 @@ function triangleVertices(w, h, direction) {
             ];
     }
 }
-export const triangleStrategy = polygonStrategy('triangle', 6, (s) => triangleVertices(s.w, s.h, s.direction ?? 'up'));
+function triangleSideLabels(direction) {
+    switch (direction) {
+        case 'up':
+            return ['right', 'bottom', 'left'];
+        case 'down':
+            return ['left', 'top', 'right'];
+        case 'left':
+            return ['top', 'right', 'bottom'];
+        case 'right':
+            return ['bottom', 'left', 'top'];
+    }
+}
+export const triangleStrategy = polygonStrategy('triangle', 6, (s) => triangleVertices(s.w, s.h, s.direction ?? 'up'), (s) => triangleSideLabels(s.direction ?? 'up'));

package/dist/ports/equidistant/utils.d.ts

@@ -4,15 +4,45 @@ export declare const DEG: number;
 export declare const RAD: number;
 export declare const ARC_SAMPLES = 720;
 export declare function portFromPoint(pt: Vec2, i: number, t: number): EquidistantPort;
-/** Place `count` equidistant points along a closed polygon by arc length. */
-export declare function walkPolygonEquidistant(vertices: Vec2[], count: number): EquidistantPort[];
-/** Create a polygon strategy from a vertex extractor. */
+/**
+ * Assign angle-bucket IDs to ports based on their angle from center.
+ *
+ * Each port is bucketed into a 90° quadrant (0, 90, 180, 270) and given
+ * an index within that quadrant. For example, a port at 45° becomes `0-0`
+ * (first port in the 0°–90° quadrant).
+ *
+ * This scheme is stable across count changes — ports near the same angle
+ * keep the same ID prefix regardless of total port count.
+ */
+export declare function assignAngleBucketIds(ports: readonly EquidistantPort[]): EquidistantPort[];
+/**
+ * Place `count` equidistant points along a closed polygon by arc length.
+ *
+ * When `sideLabels` is provided (one label per edge), each port receives a
+ * location-based ID in the format `{label}-{indexWithinSide}` (e.g.
+ * `top-0`, `right-1`). Without labels, ports fall back to sequential
+ * `p0`–`pN` IDs.
+ */
+export declare function walkPolygonEquidistant(vertices: Vec2[], count: number, sideLabels?: readonly string[]): EquidistantPort[];
+/**
+ * Create a polygon strategy from a vertex extractor.
+ *
+ * When `extractSideLabels` is provided, ports receive location-based IDs
+ * (e.g. `top-0`, `right-1`). Otherwise, angle-bucket IDs are assigned
+ * (e.g. `0-0`, `90-1`).
+ */
 export declare function polygonStrategy<K extends NodeShape['kind']>(kind: K, defaultCount: number | ((shape: Extract<NodeShape, {
     kind: K;
 }>) => number), extractVertices: (shape: Extract<NodeShape, {
     kind: K;
-}>) => Vec2[]): PerimeterStrategy<K>;
-/** Create a curved-shape strategy from a perimeter sampler. */
+}>) => Vec2[], extractSideLabels?: (shape: Extract<NodeShape, {
+    kind: K;
+}>) => readonly string[]): PerimeterStrategy<K>;
+/**
+ * Create a curved-shape strategy from a perimeter sampler.
+ *
+ * Ports receive angle-bucket IDs (e.g. `0-0`, `90-1`).
+ */
 export declare function sampledCurveStrategy<K extends NodeShape['kind']>(kind: K, defaultCount: number, samplePerimeter: (shape: Extract<NodeShape, {
     kind: K;
 }>) => Vec2[]): PerimeterStrategy<K>;

package/dist/ports/equidistant/utils.js

@@ -22,8 +22,34 @@ export function portFromPoint(pt, i, t) {
         y: pt.y,
     };
 }
-/** Place `count` equidistant points along a closed polygon by arc length. */
-export function walkPolygonEquidistant(vertices, count) {
+/**
+ * Assign angle-bucket IDs to ports based on their angle from center.
+ *
+ * Each port is bucketed into a 90° quadrant (0, 90, 180, 270) and given
+ * an index within that quadrant. For example, a port at 45° becomes `0-0`
+ * (first port in the 0°–90° quadrant).
+ *
+ * This scheme is stable across count changes — ports near the same angle
+ * keep the same ID prefix regardless of total port count.
+ */
+export function assignAngleBucketIds(ports) {
+    const bucketCounts = new Map();
+    return ports.map((p) => {
+        const bucket = Math.floor(normalizeAngle(p.angle) / 90) * 90;
+        const idx = bucketCounts.get(bucket) ?? 0;
+        bucketCounts.set(bucket, idx + 1);
+        return { ...p, id: `${bucket}-${idx}` };
+    });
+}
+/**
+ * Place `count` equidistant points along a closed polygon by arc length.
+ *
+ * When `sideLabels` is provided (one label per edge), each port receives a
+ * location-based ID in the format `{label}-{indexWithinSide}` (e.g.
+ * `top-0`, `right-1`). Without labels, ports fall back to sequential
+ * `p0`–`pN` IDs.
+ */
+export function walkPolygonEquidistant(vertices, count, sideLabels) {
     const n = vertices.length;
     if (n === 0 || count <= 0)
         return [];
@@ -38,6 +64,8 @@ export function walkPolygonEquidistant(vertices, count) {
     const segLen = perimeter / count;
     const ports = [];
     let edgeIdx = 0;
+    // Track per-side port counts for side-based IDs
+    const sideCounts = sideLabels ? new Array(n).fill(0) : [];
     for (let i = 0; i < count; i++) {
         const target = i * segLen;
         while (edgeIdx < n - 1 && cumDist[edgeIdx + 1] <= target)
@@ -48,7 +76,24 @@ export function walkPolygonEquidistant(vertices, count) {
         const frac = edgeLen > 0 ? (target - edgeStart) / edgeLen : 0;
         const a = vertices[edgeIdx];
         const b = vertices[(edgeIdx + 1) % n];
-        ports.push(portFromPoint(lerp(a, b, frac), i, target / perimeter));
+        const pt = lerp(a, b, frac);
+        let id;
+        if (sideLabels) {
+            const sideLabel = sideLabels[edgeIdx];
+            const sideIdx = sideCounts[edgeIdx];
+            sideCounts[edgeIdx] = sideIdx + 1;
+            id = `${sideLabel}-${sideIdx}`;
+        }
+        else {
+            id = `p${i}`;
+        }
+        ports.push({
+            id,
+            angle: normalizeAngle(angleDeg(pt)),
+            t: target / perimeter,
+            x: pt.x,
+            y: pt.y,
+        });
     }
     return ports;
 }
@@ -90,19 +135,34 @@ function walkSampledCurveEquidistant(pts, count) {
     }
     return ports;
 }
-/** Create a polygon strategy from a vertex extractor. */
-export function polygonStrategy(kind, defaultCount, extractVertices) {
+/**
+ * Create a polygon strategy from a vertex extractor.
+ *
+ * When `extractSideLabels` is provided, ports receive location-based IDs
+ * (e.g. `top-0`, `right-1`). Otherwise, angle-bucket IDs are assigned
+ * (e.g. `0-0`, `90-1`).
+ */
+export function polygonStrategy(kind, defaultCount, extractVertices, extractSideLabels) {
     return {
         kind,
         defaultCount,
-        computePorts: (shape, count) => walkPolygonEquidistant(extractVertices(shape), count),
+        computePorts: (shape, count) => {
+            const vertices = extractVertices(shape);
+            const labels = extractSideLabels?.(shape);
+            const ports = walkPolygonEquidistant(vertices, count, labels);
+            return labels ? ports : assignAngleBucketIds(ports);
+        },
     };
 }
-/** Create a curved-shape strategy from a perimeter sampler. */
+/**
+ * Create a curved-shape strategy from a perimeter sampler.
+ *
+ * Ports receive angle-bucket IDs (e.g. `0-0`, `90-1`).
+ */
 export function sampledCurveStrategy(kind, defaultCount, samplePerimeter) {
     return {
         kind,
         defaultCount,
-        computePorts: (shape, count) => walkSampledCurveEquidistant(samplePerimeter(shape), count),
+        computePorts: (shape, count) => assignAngleBucketIds(walkSampledCurveEquidistant(samplePerimeter(shape), count)),
     };
 }

package/dist/shapes/geometry.d.ts

@@ -40,6 +40,11 @@ export declare function getDefaultPorts(shape: NodeShape): NodePort[];
 export declare function getNodePorts(node: VizNode): NodePort[];
 /**
  * Find a port on a node by its id. Returns `undefined` if not found.
+ *
+ * **Legacy compatibility:** if `portId` matches the old sequential format
+ * (`p0`, `p1`, …) and no port with that exact ID exists, the port at
+ * that numeric index is returned instead. This eases migration from the
+ * previous `p0`–`pN` naming to the new location-based IDs.
  */
 export declare function findPort(node: VizNode, portId: string): NodePort | undefined;
 /**

package/dist/shapes/geometry.js

@@ -1372,9 +1372,25 @@ export function getNodePorts(node) {
 }
 /**
  * Find a port on a node by its id. Returns `undefined` if not found.
+ *
+ * **Legacy compatibility:** if `portId` matches the old sequential format
+ * (`p0`, `p1`, …) and no port with that exact ID exists, the port at
+ * that numeric index is returned instead. This eases migration from the
+ * previous `p0`–`pN` naming to the new location-based IDs.
  */
 export function findPort(node, portId) {
-    return getNodePorts(node).find((p) => p.id === portId);
+    const ports = getNodePorts(node);
+    const exact = ports.find((p) => p.id === portId);
+    if (exact)
+        return exact;
+    // Legacy fallback: treat 'p3' as "port at index 3"
+    const legacy = /^p(\d+)$/.exec(portId);
+    if (legacy) {
+        const idx = Number(legacy[1]);
+        if (idx >= 0 && idx < ports.length)
+            return ports[idx];
+    }
+    return undefined;
 }
 /**
  * Resolve a port to an absolute position (node center + port offset).

package/package.json

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