@zoneflow/editor-dom 0.0.15 → 0.0.17

package/dist/floatingLayout.d.ts

@@ -0,0 +1,59 @@
+import { type Point, type UniverseLayoutModel, type UniverseModel, type Zone, type ZoneId } from "@zoneflow/core";
+/**
+ * Per-zone velocity vectors carried between simulation steps.
+ */
+export type FloatingVelocities = Record<ZoneId, Point>;
+export type FloatingLayoutOptions = {
+    /**
+     * Flow direction. Zoneflow flows left→right by default ("x"); "y" lays the
+     * flow out top→bottom. Connected zones are spaced along this axis and aligned
+     * along the perpendicular one.
+     */
+    flowAxis?: "x" | "y";
+    /** Target spacing (px) between a source and its target along the flow axis. */
+    layerGap?: number;
+    /** Stiffness of the flow-axis spacing force (the dominant ordering force). */
+    flowStrength?: number;
+    /**
+     * Stiffness of the cross-axis force that aligns a target with its source,
+     * keeping each chain reading as a straight flow line.
+     */
+    alignStrength?: number;
+    /** Strength of the inverse-square push that keeps mobile zones apart. */
+    repulsionStrength?: number;
+    /** Gentle pull toward the mobile cluster's centroid (prevents drift). */
+    centeringStrength?: number;
+    /** Velocity retention per step (0..1). Lower = settles faster. */
+    damping?: number;
+    /** Overall multiplier applied to velocity when moving (lower = slower). */
+    speed?: number;
+    /** Max distance (px) a zone may move in a single step. Keeps motion gentle. */
+    maxStep?: number;
+    /** Inner padding (px) kept between a child zone and its container's edges. */
+    containerPadding?: number;
+    /** Decides which zones drift. Defaults to action zones. */
+    isMobile?: (zone: Zone) => boolean;
+};
+export type FloatingStepResult = {
+    layoutModel: UniverseLayoutModel;
+    velocities: FloatingVelocities;
+    /** Total kinetic energy (sum of |v|²). Near zero once the layout settles. */
+    energy: number;
+};
+/**
+ * Advances a force-directed layout by one frame. Pure: given the same inputs
+ * it always returns the same output, so the caller (a RAF loop) owns all
+ * mutable state via the returned `velocities`.
+ *
+ * Forces are computed in world space; deltas are written back to each zone's
+ * local layout coordinates. Because only action zones are mobile and their
+ * container parents stay fixed, a world-space delta equals the local-space
+ * delta, so no coordinate conversion is needed on write-back.
+ */
+export declare function stepFloatingLayout(params: {
+    model: UniverseModel;
+    layoutModel: UniverseLayoutModel;
+    velocities?: FloatingVelocities;
+    pinnedZoneIds?: ReadonlySet<ZoneId>;
+    options?: FloatingLayoutOptions;
+}): FloatingStepResult;

package/dist/floatingLayout.js

@@ -0,0 +1,226 @@
+import { getPaths, resolvePathTarget, updateZoneLayout, } from "@zoneflow/core";
+import { resolveWorldZoneOrigin } from "./zoneGeometry";
+import { roundCoordinate } from "./moveEditorShared";
+const DEFAULTS = {
+    flowAxis: "x",
+    layerGap: 200,
+    flowStrength: 0.03,
+    alignStrength: 0.014,
+    repulsionStrength: 130000,
+    // Very weak — just enough to stop unbounded drift. Stronger values compact
+    // the whole graph toward the centroid and fight the left→right spread.
+    centeringStrength: 0.0015,
+    damping: 0.8,
+    speed: 0.9,
+    maxStep: 6,
+    containerPadding: 12,
+};
+const MIN_DISTANCE = 1;
+function isActionZone(zone) {
+    return zone.zoneType === "action";
+}
+/**
+ * Advances a force-directed layout by one frame. Pure: given the same inputs
+ * it always returns the same output, so the caller (a RAF loop) owns all
+ * mutable state via the returned `velocities`.
+ *
+ * Forces are computed in world space; deltas are written back to each zone's
+ * local layout coordinates. Because only action zones are mobile and their
+ * container parents stay fixed, a world-space delta equals the local-space
+ * delta, so no coordinate conversion is needed on write-back.
+ */
+export function stepFloatingLayout(params) {
+    const { model, layoutModel, velocities = {}, pinnedZoneIds, options } = params;
+    const flowAxis = options?.flowAxis ?? DEFAULTS.flowAxis;
+    const layerGap = options?.layerGap ?? DEFAULTS.layerGap;
+    const flowStrength = options?.flowStrength ?? DEFAULTS.flowStrength;
+    const alignStrength = options?.alignStrength ?? DEFAULTS.alignStrength;
+    const repulsionStrength = options?.repulsionStrength ?? DEFAULTS.repulsionStrength;
+    const centeringStrength = options?.centeringStrength ?? DEFAULTS.centeringStrength;
+    const damping = options?.damping ?? DEFAULTS.damping;
+    const speed = options?.speed ?? DEFAULTS.speed;
+    const maxStep = options?.maxStep ?? DEFAULTS.maxStep;
+    const containerPadding = options?.containerPadding ?? DEFAULTS.containerPadding;
+    const isMobile = options?.isMobile ?? isActionZone;
+    // 1. Sample world-space centers for every laid-out zone.
+    const originCache = new Map();
+    const samples = [];
+    const sampleById = new Map();
+    for (const zone of Object.values(model.zonesById)) {
+        const layout = layoutModel.zoneLayoutsById[zone.id];
+        if (!layout)
+            continue;
+        const origin = resolveWorldZoneOrigin({
+            model,
+            layoutModel,
+            zoneId: zone.id,
+            cache: originCache,
+        });
+        const center = {
+            x: origin.x + (layout.width ?? 0) / 2,
+            y: origin.y + (layout.height ?? 0) / 2,
+        };
+        const sample = {
+            zoneId: zone.id,
+            center,
+            mobile: isMobile(zone) && !pinnedZoneIds?.has(zone.id),
+        };
+        samples.push(sample);
+        sampleById.set(zone.id, sample);
+    }
+    const mobileSamples = samples.filter((sample) => sample.mobile);
+    if (mobileSamples.length === 0) {
+        return { layoutModel, velocities, energy: 0 };
+    }
+    // Accumulated force per mobile zone.
+    const forces = new Map();
+    for (const sample of mobileSamples) {
+        forces.set(sample.zoneId, { x: 0, y: 0 });
+    }
+    const addForce = (zoneId, fx, fy) => {
+        const force = forces.get(zoneId);
+        if (!force)
+            return; // not mobile — ignore
+        force.x += fx;
+        force.y += fy;
+    };
+    // 2. Flow forces along every path edge (source → target). The flow axis
+    //    carries a directional spacing force (target sits one `layerGap`
+    //    downstream of its source); the cross axis carries a gentle alignment
+    //    force so each chain reads as a straight flow line.
+    for (const zone of Object.values(model.zonesById)) {
+        const source = sampleById.get(zone.id);
+        if (!source)
+            continue;
+        for (const path of getPaths(zone)) {
+            const targetZone = resolvePathTarget(model, path);
+            if (!targetZone || targetZone.id === zone.id)
+                continue;
+            const target = sampleById.get(targetZone.id);
+            if (!target)
+                continue;
+            if (!source.mobile && !target.mobile)
+                continue;
+            // Flow axis: drive the gap toward +layerGap (target downstream).
+            const flowGap = flowAxis === "x"
+                ? target.center.x - source.center.x
+                : target.center.y - source.center.y;
+            const flowForce = (layerGap - flowGap) * flowStrength;
+            // Cross axis: pull the target onto the source's line.
+            const crossDelta = flowAxis === "x"
+                ? target.center.y - source.center.y
+                : target.center.x - source.center.x;
+            const alignForce = -crossDelta * alignStrength;
+            if (flowAxis === "x") {
+                addForce(targetZone.id, flowForce, alignForce);
+                addForce(zone.id, -flowForce, -alignForce);
+            }
+            else {
+                addForce(targetZone.id, alignForce, flowForce);
+                addForce(zone.id, -alignForce, -flowForce);
+            }
+        }
+    }
+    // 3. Inverse-square repulsion between every pair of mobile zones.
+    for (let i = 0; i < mobileSamples.length; i += 1) {
+        for (let j = i + 1; j < mobileSamples.length; j += 1) {
+            const a = mobileSamples[i];
+            const b = mobileSamples[j];
+            let dx = a.center.x - b.center.x;
+            let dy = a.center.y - b.center.y;
+            let distanceSq = dx * dx + dy * dy;
+            if (distanceSq < MIN_DISTANCE) {
+                // Perfectly overlapping — nudge deterministically by index so the
+                // pair separates without relying on randomness.
+                dx = (i - j) || 1;
+                dy = 1;
+                distanceSq = dx * dx + dy * dy;
+            }
+            const distance = Math.sqrt(distanceSq);
+            const magnitude = repulsionStrength / distanceSq;
+            const ux = dx / distance;
+            const uy = dy / distance;
+            addForce(a.zoneId, ux * magnitude, uy * magnitude);
+            addForce(b.zoneId, -ux * magnitude, -uy * magnitude);
+        }
+    }
+    // 4. Centering pull toward the mobile cluster's centroid.
+    let centroidX = 0;
+    let centroidY = 0;
+    for (const sample of mobileSamples) {
+        centroidX += sample.center.x;
+        centroidY += sample.center.y;
+    }
+    centroidX /= mobileSamples.length;
+    centroidY /= mobileSamples.length;
+    for (const sample of mobileSamples) {
+        addForce(sample.zoneId, (centroidX - sample.center.x) * centeringStrength, (centroidY - sample.center.y) * centeringStrength);
+    }
+    // 5. Integrate velocities and write displaced positions back to the layout,
+    //    clamping each child zone inside its parent container's bounds.
+    const nextVelocities = {};
+    let nextLayoutModel = layoutModel;
+    let energy = 0;
+    for (const sample of mobileSamples) {
+        const force = forces.get(sample.zoneId) ?? { x: 0, y: 0 };
+        const prev = velocities[sample.zoneId] ?? { x: 0, y: 0 };
+        let vx = (prev.x + force.x) * damping;
+        let vy = (prev.y + force.y) * damping;
+        // Clamp the per-step displacement so motion stays slow and gentle.
+        const stepDistance = Math.hypot(vx * speed, vy * speed);
+        if (stepDistance > maxStep) {
+            const scale = maxStep / stepDistance;
+            vx *= scale;
+            vy *= scale;
+        }
+        const layout = layoutModel.zoneLayoutsById[sample.zoneId];
+        if (!layout) {
+            nextVelocities[sample.zoneId] = { x: vx, y: vy };
+            energy += vx * vx + vy * vy;
+            continue;
+        }
+        let nextX = layout.x + vx * speed;
+        let nextY = layout.y + vy * speed;
+        // Containment: keep a child fully within its parent container. Local
+        // coordinates are relative to the parent origin, so the valid box is
+        // [pad, parentSize - childSize - pad] on each axis. Velocity on a clamped
+        // axis is zeroed so the zone rests against the wall without jitter.
+        const parentId = model.zonesById[sample.zoneId]?.parentZoneId;
+        const parentLayout = parentId
+            ? layoutModel.zoneLayoutsById[parentId]
+            : undefined;
+        if (parentLayout) {
+            const childW = layout.width ?? 0;
+            const childH = layout.height ?? 0;
+            const parentW = parentLayout.width;
+            const parentH = parentLayout.height;
+            if (parentW !== undefined) {
+                const maxX = Math.max(containerPadding, parentW - childW - containerPadding);
+                const clampedX = Math.min(Math.max(nextX, containerPadding), maxX);
+                if (clampedX !== nextX) {
+                    nextX = clampedX;
+                    vx = 0;
+                }
+            }
+            if (parentH !== undefined) {
+                const maxY = Math.max(containerPadding, parentH - childH - containerPadding);
+                const clampedY = Math.min(Math.max(nextY, containerPadding), maxY);
+                if (clampedY !== nextY) {
+                    nextY = clampedY;
+                    vy = 0;
+                }
+            }
+        }
+        nextVelocities[sample.zoneId] = { x: vx, y: vy };
+        energy += vx * vx + vy * vy;
+        nextLayoutModel = updateZoneLayout(nextLayoutModel, sample.zoneId, {
+            x: roundCoordinate(nextX),
+            y: roundCoordinate(nextY),
+        });
+    }
+    return {
+        layoutModel: nextLayoutModel,
+        velocities: nextVelocities,
+        energy,
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./zoneMoveEditor";
 export * from "./pathCreateEditor";
 export * from "./zOrderEditor";
+export * from "./floatingLayout";
 export { alignPathsByMode, alignZonesByMode, commitZoneGroupReparentAtCurrentPosition, commitZoneReparentAtCurrentPosition, distributePathsByMode, distributeZonesByMode, resolveGroupPathDragOrigin, resolveGroupZoneDragOrigin, resolveZonePlacementAtWorldRect, resolvePathResizeOrigin, resizePathNodeByScreenDelta, } from "./zoneMoveEditor";
 export type { PathResizeOrigin } from "./zoneMoveEditor";
 export { resolvePathOutputAnchorScreenRect, retargetPathFromOutputAnchorDrag, } from "./pathCreateEditor";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./zoneMoveEditor";
 export * from "./pathCreateEditor";
 export * from "./zOrderEditor";
+export * from "./floatingLayout";
 export { alignPathsByMode, alignZonesByMode, commitZoneGroupReparentAtCurrentPosition, commitZoneReparentAtCurrentPosition, distributePathsByMode, distributeZonesByMode, resolveGroupPathDragOrigin, resolveGroupZoneDragOrigin, resolveZonePlacementAtWorldRect, resolvePathResizeOrigin, resizePathNodeByScreenDelta, } from "./zoneMoveEditor";
 export { resolvePathOutputAnchorScreenRect, retargetPathFromOutputAnchorDrag, } from "./pathCreateEditor";

package/dist/pathCreateEditor.d.ts

@@ -1,5 +1,5 @@
 import { type Path, type PathId, type Point, type UniverseLayoutModel, type UniverseModel, type Zone, type ZoneId } from "@zoneflow/core";
-import { type CameraState, type Rect, type RendererFrame } from "@zoneflow/renderer-dom";
+import { type CameraState, type Rect, type RendererFrame, type ResolveZoneShape } from "@zoneflow/renderer-dom";
 import type { GridSnapOptions } from "./zoneMoveEditor";
 export type CanConnectPathParams = {
     mode: "create" | "retarget";
@@ -18,6 +18,7 @@ export declare function resolveZoneAnchorScreenRect(params: {
     camera: CameraState;
     zoneId: ZoneId;
     kind: "inlet" | "outlet";
+    resolveZoneShape?: ResolveZoneShape;
 }): Rect | undefined;
 export declare function resolveInputAnchorTargetZoneId(params: {
     model: UniverseModel;
@@ -26,6 +27,7 @@ export declare function resolveInputAnchorTargetZoneId(params: {
     point: Point;
     excludeZoneIds?: ZoneId[];
     canConnect?: (targetZoneId: ZoneId) => boolean;
+    resolveZoneShape?: ResolveZoneShape;
 }): ZoneId | null;
 export declare function resolvePathOutputAnchorScreenRect(params: {
     frame: RendererFrame;

package/dist/pathCreateEditor.js

@@ -1,4 +1,5 @@
 import { addPath, createPathId, isZoneInputEnabled, isZoneOutputEnabled, setPathTarget, updatePathLayout, } from "@zoneflow/core";
+import { normalizeZoneShape, } from "@zoneflow/renderer-dom";
 function typedValues(record) {
     return Object.values(record);
 }
@@ -8,6 +9,9 @@ const DEFAULT_PATH_NODE_OFFSET_X = 32;
 const DEFAULT_PATH_NODE_GAP_Y = 40;
 const DEFAULT_ANCHOR_WIDTH = 24;
 const DEFAULT_ANCHOR_ATTACH_DEPTH = 10;
+// Square hit area for vertex-mode anchors (circle/diamond/…), centered on the
+// shape's left/right vertex to match the vertex dot drawn by the renderer.
+const VERTEX_ANCHOR_HIT_SIZE = 28;
 const DEFAULT_PATH_OUTPUT_HANDLE_WIDTH = 18;
 const DEFAULT_PATH_OUTPUT_HANDLE_MIN_HEIGHT = 22;
 const DEFAULT_PATH_OUTPUT_HANDLE_MAX_HEIGHT = 40;
@@ -57,7 +61,20 @@ function projectWorldRectToScreenRect(rect, camera) {
     };
 }
 function resolveZoneAnchorRect(params) {
-    const { zoneRect, anchor, kind } = params;
+    const { zoneRect, anchor, kind, mode = "edge" } = params;
+    if (mode === "vertex") {
+        // Non-rectangular zones expose their anchor only at the shape vertex, so
+        // the grab/drop hit area is a compact square centered on the anchor point
+        // instead of the full-height edge band used for rectangular zones.
+        // `anchor.point` is already in world coordinates (zone position + offset),
+        // so it is used directly — do NOT add zoneRect again.
+        return {
+            x: anchor.point.x - VERTEX_ANCHOR_HIT_SIZE / 2,
+            y: anchor.point.y - VERTEX_ANCHOR_HIT_SIZE / 2,
+            width: VERTEX_ANCHOR_HIT_SIZE,
+            height: VERTEX_ANCHOR_HIT_SIZE,
+        };
+    }
     if (anchor.rect) {
         return {
             x: anchor.rect.x,
@@ -82,7 +99,7 @@ export function screenPointToWorldPoint(point, camera) {
     };
 }
 export function resolveZoneAnchorScreenRect(params) {
-    const { frame, camera, zoneId, kind } = params;
+    const { frame, camera, zoneId, kind, resolveZoneShape } = params;
     const zoneVisual = frame.pipeline.graphLayout.zonesById[zoneId];
     if (!zoneVisual)
         return undefined;
@@ -90,15 +107,17 @@ export function resolveZoneAnchorScreenRect(params) {
         return undefined;
     if (kind === "outlet" && !isZoneOutputEnabled(zoneVisual.zone))
         return undefined;
+    const mode = normalizeZoneShape(resolveZoneShape?.(zoneVisual.zone)).anchors;
     const anchorRect = resolveZoneAnchorRect({
         zoneRect: zoneVisual.rect,
         anchor: zoneVisual.anchors[kind],
         kind,
+        mode,
     });
     return projectWorldRectToScreenRect(anchorRect, camera);
 }
 export function resolveInputAnchorTargetZoneId(params) {
-    const { model, frame, camera, point, excludeZoneIds, canConnect } = params;
+    const { model, frame, camera, point, excludeZoneIds, canConnect, resolveZoneShape, } = params;
     const excluded = new Set(excludeZoneIds ?? []);
     let bestZoneId = null;
     let bestArea = Number.POSITIVE_INFINITY;
@@ -117,6 +136,7 @@ export function resolveInputAnchorTargetZoneId(params) {
             camera,
             zoneId: zoneVisual.zoneId,
             kind: "inlet",
+            resolveZoneShape,
         });
         if (!rect || !containsPoint(rect, point))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoneflow/editor-dom",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "license": "MIT",
   "description": "Low-level editor geometry and interaction helpers for Zoneflow.",
   "type": "module",
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@zoneflow/core": "0.0.15",
-    "@zoneflow/renderer-dom": "0.0.15"
+    "@zoneflow/core": "0.0.17",
+    "@zoneflow/renderer-dom": "0.0.17"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",