# PRD: Connection Menu Quick Add Prioritization

Version: 1.0
Last Updated: 2026-05-17
Status: Implementation synced
Scope: `popiart-node-canvas`

## 1. Summary

The connection creation menu has two different user intents:

- Dragging from a handle to blank canvas is an exploration action. It should show the complete list of compatible downstream or upstream node functions.
- Clicking a node-level `+` button is a quick continuation action. It should show a short, high-signal list: up to 5 generally important functions plus up to 2 functions that are strongly related to the source node.

The same `ConnectionDropMenu` component may continue to render both flows, but it must know which mode opened it.

## 2. Product Rule

Core rule:

> Drag shows the full compatible menu. Node `+` shows the best next-step menu.

Detailed behavior:

- Drag from an output handle keeps the complete compatible target-node list.
- Drag from an input handle keeps the complete compatible source-node list.
- Click a node `+` opens quick-add mode.
- Quick-add mode filters the already-compatible options. It must not suggest a node that the current handle cannot connect to.
- Quick-add mode returns at most 7 options:
  - up to 5 common important options for the current handle type
  - up to 2 source-node-related options
- If no source-node-related options are available after compatibility filtering and dedupe, quick-add shows only the common important options.
- Existing action items such as `Split Grid Now` and `Image Multi-Angle` are allowed in quick-add when they are prioritized and compatible.

## 3. Common Important Options

These priorities are intentionally static so the first iteration is predictable and easy to review.

| Handle type | Common quick-add options |
| --- | --- |
| image | Generate Image, Generate Video, Output, Annotate, Image Compare |
| text | Generate Image, Generate Video, LLM Generate, Prompt Constructor, Generate Audio |
| video | Generate Video, Output, Video Trim, Frame Grab, Video Stitch |
| audio | Generate Video, Output, Video Stitch, Router, Switch |
| 3d | 3D Viewer, Output, Generate 3D, Router, Switch |
| easeCurve | Ease Curve, Router, Switch, Generate Video, Video Stitch |

The final rendered list is the intersection of this priority list and the current compatibility list.

## 4. Source-Node-Related Options

Related options are also filtered by handle compatibility and deduped against the common list.

| Source node | Related quick-add options |
| --- | --- |
| Image Input | Image Multi-Angle, Split Grid Now |
| Annotation | Image Multi-Angle, Split Grid Now |
| Generate Image | Image Multi-Angle, Split Grid Now |
| Prompt | Array, Prompt Constructor |
| Prompt Constructor | LLM Generate, Array |
| LLM Generate | Generate Image, Generate Video |
| Video Input | Video Trim, Frame Grab |
| Generate Video | Ease Curve, Frame Grab |
| Video Stitch | Video Trim, Ease Curve |
| Video Trim | Frame Grab, Video Stitch |
| Audio Input | Generate Video, Output |
| Generate Audio | Generate Video, Output |
| Generate 3D | 3D Viewer, Output |
| 3D Viewer | Generate Image, Output |

Nodes without a related mapping fall back to common important options only.

## 5. Implementation Notes

- Add a menu mode: `drag` or `quickAdd`.
- Default mode is `drag` for backward compatibility.
- `WorkflowCanvas` should set `mode: "quickAdd"` and `sourceNodeType` when opening the menu from the node `+` button.
- Existing handle-drag code should keep `mode: "drag"` and preserve full lists.
- Filtering belongs in `ConnectionDropMenu` because it already owns handle-type option lists.
- Do not add new dependencies or dynamic ranking infrastructure for this iteration.

## 6. Acceptance Criteria

- Dragging from an image output still shows the complete image-compatible menu.
- Clicking `+` on an image source shows no more than 7 options.
- Clicking `+` on an image source includes common actions and the image-specific related actions when compatible.
- Clicking `+` for a source node with no related mapping shows common important options only.
- The selected quick-add option still creates and connects the new node exactly as before.
- Keyboard navigation and action item selection continue to work.

## 7. Verification Plan

- Unit test `ConnectionDropMenu` full drag behavior remains unchanged.
- Unit test quick-add image menu is capped and includes related image actions.
- Unit test quick-add without related mapping falls back to common options only.
- Component test `WorkflowCanvas` passes quick-add mode and source node type from the node `+` button.
- Run targeted tests for `ConnectionDropMenu` and `WorkflowCanvas`.
- Run full test suite and production build before publishing.

## 8. Iteration Log

- 2026-05-17: Synced requested behavior into PRD before implementation.
- 2026-05-17: First implementation target is a static priority filter with no new ranking service.
- 2026-05-17: Implemented `drag` and `quickAdd` modes in `ConnectionDropMenu`.
- 2026-05-17: Wired node `+` in `WorkflowCanvas` to pass `mode: "quickAdd"` and `sourceNodeType`.

## 9. Implementation Record

Changed files:

- `src/components/ConnectionDropMenu.tsx`
  - Adds static common and source-related priority maps.
  - Keeps full compatible options in `drag` mode.
  - Filters to common plus related options in `quickAdd` mode.
- `src/components/WorkflowCanvas.tsx`
  - Marks handle-drag menus as `drag`.
  - Marks node `+` menus as `quickAdd`.
  - Passes the clicked source node type into the menu.
- `src/components/__tests__/ConnectionDropMenu.test.tsx`
  - Covers full drag menu preservation.
  - Covers image quick-add cap and related actions.
  - Covers common-only fallback when there is no related mapping.
- `src/components/__tests__/WorkflowCanvas.test.tsx`
  - Covers node `+` passing quick-add mode and source node type.

Verification:

- Passed targeted tests: `npm run test:run -- src/components/__tests__/ConnectionDropMenu.test.tsx src/components/__tests__/WorkflowCanvas.test.tsx`
- Passed full tests: `npm run test:run` (`108` files, `2157` tests)
- Passed production build: `npm run build`
- Lint script did not run because `next lint` is no longer recognized by the installed Next CLI and is treated as a project directory named `lint`.