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
• a small runtime diagnostics layer for upstream-drift detection
• 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
• runtime diagnostics stay local to align_panel.js rather than living in a separate shared file

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 into app.menu.element, which ComfyUI hosts inside the upstream legacy-topbar-container
• the toolbar uses its own wrapper inside app.menu.element, keeping it in the same flex layout as other legacy menu groups

Diagnostics behavior

The current implementation emits once-per-session console diagnostics when critical upstream assumptions stop matching the expected frontend or LiteGraph contract.

Current diagnostic codes include:

• MOUNT_MENU_ELEMENT_MISSING
• MOUNT_ACTIONBAR_CONTAINER_MISSING
• MOUNT_REINSERT_FAILED
• CANVAS_CONTEXT_UNAVAILABLE
• SELECTION_MODEL_UNSUPPORTED
• GEOMETRY_UNAVAILABLE
• MOVEMENT_API_UNAVAILABLE
• CANVAS_REFRESH_API_UNAVAILABLE

Diagnostics are intentionally grouped by assumption type rather than logged repeatedly for every occurrence.

Upstream-sensitive touchpoints

This feature is currently sensitive to:

• the app.menu.element contract
• the placement of app.menu.element inside legacy-topbar-container 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)
• current canvas refresh hooks (setDirty, graph.change)

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.
• Do not replace the current once-per-session diagnostics with noisy per-occurrence console spam.

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 app.menu.element / legacy topbar host contract
• diagnostic code meanings or reporting thresholds