fix(canvas): stop phantom ports and a latched-open action bar

Ports surface on hover from a swell painted on the card border, and that
swell was raised with no regard for whether a handle exists behind it. A
Response block mounts no source handle, so hovering its edge raised a
knob no edge could ever leave from. A trigger mounts no target handle,
yet still swelled under a connection dragged from another card, offering
a drop it cannot accept. Gate each direction on the handle that backs it,
and limit a trigger's own swell to its source edge the way the subflow
start node already does.

The action bar latched open for the same interaction. Leaving the card
arms a retract and installs a pointermove listener to track the pointer
across the gap up to the bar; re-entering the bar's band called
openHover(), which cancelled the retract AND removed that listener. No
further pointerleave can arrive once the pointer is off the node, so
nothing was left to close the bar. Keep the listener installed and re-arm
the retract when the pointer moves back out.

Also clear the magnetized port when the pointer leaves the tracking band
onto the action bar: only the in-band path recomputed it, so the last
knob stayed pinned at hover amplitude with the pointer nowhere near it.

Author: waleedlatif1

packages/workflow-renderer/src/workflow-block/use-action-menu-swell.test.tsx

@@ -0,0 +1,159 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * The action bar floats above the card, so the pointer crosses a gap to reach
+ * it and the card's own `pointerleave` fires on the way out. The hook tracks
+ * the pointer across that gap — and the tracking listener is the only thing
+ * still watching once the pointer is off the node, because no further
+ * `pointerleave` can arrive.
+ */
+import { act, useEffect } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { useActionMenuSwell } from './use-action-menu-swell'
+
+beforeAll(() => {
+  globalThis.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver
+})
+
+const ACTION_MENU_RECT = { left: 100, right: 240, top: 40, bottom: 70 }
+/** Comfortably outside the bar's hover band, which extends 28px above `top`. */
+const AWAY_POINT = { clientX: 600, clientY: 400 }
+
+let container: HTMLDivElement | null = null
+let root: Root | null = null
+
+interface HarnessProps {
+  onState: (state: { swellOpen: boolean }) => void
+}
+
+/**
+ * Mounts the hook under a `.react-flow__node` ancestor, since the hook binds
+ * its hover listeners to that element rather than to its own root.
+ */
+function Harness({ onState }: HarnessProps) {
+  const { rootRef, swellOpen } = useActionMenuSwell({ enabled: true, forceOpen: false })
+
+  useEffect(() => {
+    onState({ swellOpen })
+  }, [onState, swellOpen])
+
+  return (
+    <div className='react-flow__node'>
+      <div ref={rootRef} data-testid='action-menu' />
+    </div>
+  )
+}
+
+function mount(onState: (state: { swellOpen: boolean }) => void) {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+  act(() => {
+    root?.render(<Harness onState={onState} />)
+  })
+
+  const node = container.querySelector<HTMLElement>('.react-flow__node')
+  const menu = container.querySelector<HTMLElement>('[data-testid="action-menu"]')
+  if (!node || !menu) throw new Error('harness did not mount')
+
+  menu.getBoundingClientRect = () =>
+    ({
+      ...ACTION_MENU_RECT,
+      width: ACTION_MENU_RECT.right - ACTION_MENU_RECT.left,
+      height: ACTION_MENU_RECT.bottom - ACTION_MENU_RECT.top,
+      x: ACTION_MENU_RECT.left,
+      y: ACTION_MENU_RECT.top,
+      toJSON: () => ({}),
+    }) as DOMRect
+
+  return { node, menu }
+}
+
+function pointerEvent(type: string, init: PointerEventInit) {
+  return new MouseEvent(type, { bubbles: true, ...init }) as unknown as PointerEvent
+}
+
+/**
+ * Drains the two chained timers the retract runs on: the 100ms hover-leave
+ * delay, then the 40ms swell close that its state change schedules. They need
+ * separate `act` passes — effects only flush when `act` exits, so the second
+ * timer is not even created until the first pass is over.
+ */
+async function settle() {
+  for (let pass = 0; pass < 2; pass++) {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 160))
+    })
+  }
+}
+
+afterEach(() => {
+  act(() => {
+    root?.unmount()
+  })
+  root = null
+  container?.remove()
+  container = null
+})
+
+describe('useActionMenuSwell', () => {
+  it('retracts after the pointer crosses the bar and keeps going', async () => {
+    let state = { swellOpen: false }
+    const { node } = mount((next) => {
+      state = next
+    })
+
+    act(() => {
+      node.dispatchEvent(pointerEvent('pointerenter', {}))
+    })
+    expect(state.swellOpen).toBe(true)
+
+    /* Leaving the card arms the retract and installs the gap tracker. */
+    act(() => {
+      node.dispatchEvent(pointerEvent('pointerleave', {}))
+    })
+
+    /*
+     * One move lands inside the bar's hover band on the way out. This is the
+     * regression: it used to cancel the retract AND tear down the tracker, so
+     * nothing was left to close the bar once the pointer carried on.
+     */
+    act(() => {
+      window.dispatchEvent(pointerEvent('pointermove', { clientX: 150, clientY: 50 }))
+    })
+    expect(state.swellOpen).toBe(true)
+
+    act(() => {
+      window.dispatchEvent(pointerEvent('pointermove', AWAY_POINT))
+    })
+
+    await settle()
+
+    expect(state.swellOpen).toBe(false)
+  })
+
+  it('stays open while the pointer rests on the bar', async () => {
+    let state = { swellOpen: false }
+    const { node } = mount((next) => {
+      state = next
+    })
+
+    act(() => {
+      node.dispatchEvent(pointerEvent('pointerenter', {}))
+      node.dispatchEvent(pointerEvent('pointerleave', {}))
+    })
+
+    act(() => {
+      window.dispatchEvent(pointerEvent('pointermove', { clientX: 150, clientY: 50 }))
+    })
+
+    await settle()
+
+    expect(state.swellOpen).toBe(true)
+  })
+})

packages/workflow-renderer/src/workflow-block/use-action-menu-swell.ts

@@ -59,11 +59,15 @@ export function useActionMenuSwell({
   useEffect(() => {
     if (!enabled || suspendInteraction) return
 
-    const clearHoverLeave = () => {
+    const cancelHoverLeaveTimeout = () => {
       if (hoverLeaveTimeoutRef.current !== null) {
         window.clearTimeout(hoverLeaveTimeoutRef.current)
         hoverLeaveTimeoutRef.current = null
       }
+    }
+
+    const clearHoverLeave = () => {
+      cancelHoverLeaveTimeout()
       if (hoverMoveRef.current) {
         window.removeEventListener('pointermove', hoverMoveRef.current)
         hoverMoveRef.current = null
@@ -111,33 +115,56 @@ export function useActionMenuSwell({
       openHover()
     }
 
+    /**
+     * Arms the retract timer, unless one is already counting down. Never
+     * touches the tracking listener: once the pointer has left the node, that
+     * listener is the only thing still watching it, so tearing it down here
+     * would strand the menu open with nothing left to close it.
+     */
+    const armHoverLeave = () => {
+      if (hoverLeaveTimeoutRef.current !== null) return
+      hoverLeaveTimeoutRef.current = window.setTimeout(() => {
+        hoverLeaveTimeoutRef.current = null
+        if (hoverMoveRef.current) {
+          window.removeEventListener('pointermove', hoverMoveRef.current)
+          hoverMoveRef.current = null
+        }
+        setIsHovered(false)
+      }, ACTION_MENU_HOVER_LEAVE_DELAY_MS)
+    }
+
     const scheduleHoverLeave = (event: PointerEvent) => {
       if (isOtherNodeTarget(event.relatedTarget)) {
         closeHoverImmediately()
         return
       }
-      if (hoverLeaveTimeoutRef.current !== null) {
-        window.clearTimeout(hoverLeaveTimeoutRef.current)
-      }
       if (!hoverMoveRef.current) {
-        const onMove = (event: PointerEvent) => {
-          if (isOtherNodeTarget(event.target)) {
+        /*
+         * The bar floats above the card, so the pointer crosses a gap to reach
+         * it and the card's own `pointerleave` fires on the way. This tracks
+         * the pointer across that gap: inside the bar's hover band the retract
+         * is cancelled, outside it is re-armed. Both directions matter — no
+         * further `pointerleave` can arrive once the pointer is off the node,
+         * so re-arming here is the only way the menu ever closes again.
+         */
+        const onMove = (moveEvent: PointerEvent) => {
+          if (isOtherNodeTarget(moveEvent.target)) {
             closeHoverImmediately()
             return
           }
-          if (isPointerOverActionMenu(event)) openHover()
+          if (isPointerOverActionMenu(moveEvent)) {
+            cancelHoverLeaveTimeout()
+            setIsHovered(true)
+            setSwellOpen(true)
+            return
+          }
+          armHoverLeave()
         }
         hoverMoveRef.current = onMove
         window.addEventListener('pointermove', onMove, { passive: true })
       }
-      hoverLeaveTimeoutRef.current = window.setTimeout(() => {
-        hoverLeaveTimeoutRef.current = null
-        if (hoverMoveRef.current) {
-          window.removeEventListener('pointermove', hoverMoveRef.current)
-          hoverMoveRef.current = null
-        }
-        setIsHovered(false)
-      }, ACTION_MENU_HOVER_LEAVE_DELAY_MS)
+      cancelHoverLeaveTimeout()
+      armHoverLeave()
     }
 
     /*

packages/workflow-renderer/src/workflow-block/workflow-block-border.tsx

@@ -150,6 +150,18 @@ interface WorkflowBlockBorderProps {
   cursorSwellEnabled?: boolean
   /** Limits pointer-following swells to specific card sides. */
   cursorSwellSides?: readonly WorkflowCardSide[]
+  /**
+   * Whether hovering this card may raise a swell to drag a connection OUT of
+   * it. False for cards that mount no source handle, so the swell never
+   * promises an edge the card cannot start.
+   */
+  canStartConnection?: boolean
+  /**
+   * Whether this card may raise a swell while a connection dragged from
+   * another card passes over it. False for cards that mount no target handle,
+   * so the swell never promises a drop the card cannot accept.
+   */
+  canReceiveConnection?: boolean
   radius?: number
   hasRing: boolean
   ringStyles: string
@@ -879,6 +891,8 @@ export function WorkflowBlockBorder({
   ports,
   cursorSwellEnabled = true,
   cursorSwellSides,
+  canStartConnection = true,
+  canReceiveConnection = true,
   radius = 16,
   hasRing,
   ringStyles,
@@ -1435,6 +1449,13 @@ export function WorkflowBlockBorder({
         // Still over the node chrome (action tab / bridge) — keep listening so
         // returning to an edge immediately restores the swell.
         if (isPointerOverTrackingRoot(clientX, clientY)) {
+          /*
+           * Drop the magnetized port too. Only the in-band path below
+           * recomputes it, so leaving the band upward onto the action bar left
+           * the last knob pinned at hover amplitude — the card kept a port
+           * puffed out with the pointer nowhere near it.
+           */
+          hoveredPortRef.current = null
           cursorHoverAllowedRef.current = false
           cursorAmplitudeRef.current.target = 0
           startAnimation()
@@ -1568,7 +1589,7 @@ export function WorkflowBlockBorder({
 
     updatePointerTargetRef.current = updatePointerTarget
     resetPointerTrackingRef.current = stopPointerTracking
-    if (cursorSwellEnabled) {
+    if (cursorSwellEnabled && canStartConnection) {
       trackingRoot.addEventListener('pointerenter', onPointerEnter)
       trackingRoot.addEventListener('pointerleave', onPointerLeave)
       trackingRoot.addEventListener('pointerdown', onPointerDown, true)
@@ -1609,10 +1630,10 @@ export function WorkflowBlockBorder({
       if (frameRef.current !== null) cancelAnimationFrame(frameRef.current)
       frameRef.current = null
     }
-  }, [cursorSwellEnabled, cursorSwellSides])
+  }, [canStartConnection, cursorSwellEnabled, cursorSwellSides])
 
   useEffect(() => {
-    if (!cursorSwellEnabled) {
+    if (!cursorSwellEnabled || !canReceiveConnection) {
       resetPointerTrackingRef.current()
       return
     }
@@ -1675,7 +1696,7 @@ export function WorkflowBlockBorder({
       }
       resetPointerTrackingRef.current()
     }
-  }, [cursorSwellEnabled, getConnectionNodeId, nodeId])
+  }, [canReceiveConnection, cursorSwellEnabled, getConnectionNodeId, nodeId])
 
   const ring = resolveRing(ringStyles)
   const { d: path } = renderedPath

packages/workflow-renderer/src/workflow-block/workflow-block-view.tsx

@@ -64,6 +64,12 @@ const TAB_LENGTH_HEADER_ONLY_PX = 10
 /** The error knob is deliberately the shortest of the connection knobs — it is
  *  a secondary output, and a full-length tab crowds the card's bottom corner. */
 const TAB_HEIGHT_RATIO = 0.5
+/**
+ * Cursor-swell sides for a card that takes no input. Matching the subflow
+ * start node, only the source edge may swell, so a trigger never raises a knob
+ * on the edge where every other card shows its input.
+ */
+const SOURCE_ONLY_CURSOR_SIDES = ['right'] as const
 const CARD_CORNER_RADIUS_PX = 16
 const CORNER_SLACK_PX = 4
 const ACTION_MENU_RIGHT_INSET_PX = 24
@@ -874,6 +880,9 @@ export function WorkflowBlockView({
           }
           isSelected={usesSelectedVisuals}
           height={blockHeight}
+          cursorSwellSides={shouldShowDefaultHandles ? undefined : SOURCE_ONLY_CURSOR_SIDES}
+          canStartConnection={supportsCursorHandle}
+          canReceiveConnection={shouldShowDefaultHandles}
           onCursorHandleChange={supportsCursorHandle ? onCursorHandleChange : undefined}
           onActionMenuReadyChange={setActionMenuSwellReady}
         />