# 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