komlevv-komlevv-Align-ComfyUI/docs/features/align_toolbar.md

Align Toolbar

• Status: stable
• Scope: persistent action bar alignment controls, selection handling, and current behavioral constraints
• Applies to: web/js/align_panel.js, web/js/align_actions.js, web/js/align_panel.css
• Source of truth level: feature
• Last verified commit: 9bb835c68f9a68ecccdbeae32bd41382a1eb3556
• Update when: action set, toolbar behavior, tooltip policy, selection policy, or mounting strategy changes
• Supersedes: none
• Superseded by: none

Purpose

This subsystem owns the persistent alignment toolbar injected into the built-in ComfyUI action bar.

Current scope

The current implementation provides:

• eight layout actions
• persistent mounting into the built-in action bar, to the left of the standard controls
• support for mixed selection of nodes, groups, and reroute dots
• native browser tooltip text using the button title attribute
• flat frontend asset layout under web/js/

Current action set

• Horizontal Align Left
• Horizontal Align Center
• Horizontal Align Right
• Horizontal Distribute Center
• Vertical Align Top
• Vertical Align Center
• Vertical Align Bottom
• Vertical Distribute Center

Current important constraints

The current design intentionally does not:

• provide a toggleable panel UI
• provide hotkey-driven overlay behavior
• maintain disabled-state UI for insufficient selection
• use custom tooltip DOM or theme-specific tooltip components
• use a web/js/align/ subfolder

Current local code organization

• frontend DOM selectors and other frontend-sensitive anchors are centralized at the top of align_panel.js
• upstream type-name checks such as LGraphGroup and Reroute are centralized as constants
• action ids are centralized in the exported ACTION_IDS map in align_actions.js
• ALIGN_ACTIONS is built from ACTION_IDS so action ids are not duplicated across files

Behavioral notes

• align operations work on mixed selections of nodes, groups, and reroute dots
• center-distribute operations keep the first and last items in sorted axis order fixed and distribute the centers of the intermediate items evenly between them
• center-distribute operations are a no-op when fewer than three items are selected
• the toolbar mounts through the upstream legacy-topbar-container expansion slot rather than into the Vue-managed child list inside ComfyActionbar
• the toolbar uses its own wrapper inside legacy-topbar-container so it satisfies the upstream visibility rule for legacy topbar content

Upstream-sensitive touchpoints

This feature is currently sensitive to:

• the legacy-topbar-container mount point in TopMenuSection.vue
• the surrounding actionbar-container structure used for observation and layout
• current LiteGraph selection containers (selectedItems, selected_nodes, selected_group)
• current geometry properties (boundingRect, _bounding, bounding, pos, size)
• current movement methods (move, setPos)

What not to do

• Do not reintroduce a more complex panel implementation unless the task explicitly requires it.
• Do not replace native title tooltips with a custom tooltip system casually.
• Do not move the current flat asset files back into a feature subfolder without a repository-level reason.
• Do not mount back into the Vue-managed child list inside ComfyActionbar unless the upstream integration model changes.
• Do not broaden DOM observation or long-lived selection caching without clear need.

Regression surface

Re-check this subsystem when changing:

• action bar insertion logic
• item type detection for groups or reroutes
• geometry extraction logic
• selection flattening for selected groups and descendants
• tooltip behavior
• the contract exported by align_actions.js
• center distribution behavior for mixed-size items
• the upstream legacy topbar mount contract