popiart-node-canvas

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.

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.

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.

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.

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.

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.

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.

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.

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.