---
name: image-editor-tools
description: Architecture and patterns for developing image editor tools and UI in the SwarmUI image editor.
---

# Image Editor Tools

Guide to the image editor tool system in `src/wwwroot/js/genpage/helpers/image_editor.js`.

## When to Use

- Use this skill when adding or modifying image editor tools
- Use this skill when working with layers, color controls, or the image editor toolbar
- Use this skill when adding new helper JS files that interact with the image editor

## Architecture

### Class Hierarchy

- `ImageEditorTool` - Base class. Creates `this.div` (toolbar button) and `this.configDiv` (bottom bar config area) via `makeDivs()`. Has lifecycle methods: `setActive()`, `setInactive()`, `draw()`, mouse handlers, `onLayerChanged()`.
- `ImageEditorTempTool` - Extends base. Overrides `makeDivs()` with a no-op, so `this.div` is **undefined**. Used for hidden sub-tools (e.g., the eyedropper color picker tool). Any code accessing `.div` on a tool must null-check for this case.
- `ImageEditorToolWithColor` - Extends base. Adds color control support: `getColorControlsHTML()`, `wireColorControls()`, `setColor(col)`, and color-aware `onLayerChanged()` with dual mask/image color memory. Tools that need a color picker (Brush, Bucket, Shape) extend this.
- `ImageEditorToolSam2Base` - Extends base. Shared SAM2 warmup/clear-mask/request-tracking logic. Subclasses override `addWarmupGenData(genData, cx, cy)` and optionally `onClearMask()`. SAM2Points and SAM2BBox extend this.
- Concrete tools extend the appropriate base: `ImageEditorToolBrush`/`ImageEditorToolBucket`/`ImageEditorToolShape` extend `ImageEditorToolWithColor`; `ImageEditorToolSam2Points`/`ImageEditorToolSam2BBox` extend `ImageEditorToolSam2Base`; others extend `ImageEditorTool`.

### Tool Registration

Tools are registered in the `ImageEditor` constructor via `this.addTool(new ToolClass(...))`. Order matters for toolbar display. The tool ID string (e.g., `'brush'`, `'paintbucket'`) is used with `this.editor.activateTool(id)`.

### Layer System

- Layers have a boolean `isMask` property.
- `onLayerChanged(oldLayer, newLayer)` is called on every tool when the active layer changes (via `setActiveLayer()`). The old layer is passed directly so tools can compare previous vs new state.
- The base `onLayerChanged` handles `isMaskOnly` tools (hides them when not on a mask).
- Tools with color can override `onLayerChanged` to adapt (e.g., compress color to grayscale for masks, swap stored color based on `oldLayer.isMask` vs `newLayer.isMask`).

### Color Controls Pattern

Tools that use color extend `ImageEditorToolWithColor`, which provides:

1. **`getColorControlsHTML()`**: Returns HTML for a `.image-editor-tool-block` div with hex text input (`.id-col1`), color swatch (`.id-col2`), and eyedrop button (`.id-col3`). Uses `this.color` for the default value.
2. **`wireColorControls()`**: Call after setting `configDiv.innerHTML` to wire up the color picker, swatch click, and eyedropper button. Opens the picker via the singleton `colorPickerHelper` (from `color_picker.js`).
3. **`setColor(col)`**: Updates `this.color`, the text input, and the swatch background.
4. **Dual color memory**: `imageColor` and `maskColor` fields store separate colors for image vs mask layers. The inherited `onLayerChanged` swaps between them (guarded by `this.colorText` existing, so tools like the eraser that skip `wireColorControls()` are unaffected).
5. **Grayscale enforcement**: When on a mask layer, colors are compressed to grayscale via `colorPickerHelper.hexToGrayscale()`, and the picker opens in grayscale mode.

### Bottom Bar Config

Each tool's config UI is in `this.configDiv`, a flex row at the bottom of the editor. Common sub-blocks use `.image-editor-tool-block` with `align-items: center`. Sliders use `enableSliderForBox()` from `site.js`.

## Instructions

- When adding a new tool, extend `ImageEditorTool` (or `ImageEditorTempTool` if it should be hidden).
- Register it in the `ImageEditor` constructor with `this.addTool(new YourTool(this))`.
- If the tool needs a new helper JS file, add it to `src/Pages/Text2Image.cshtml` in the `@section Scripts` block **before** `image_editor.js`.
- Use `createDiv()` from `util.js` for DOM creation.
- Use theme CSS variables (`--popup-back`, `--light-border`, etc.) for styling.
- Always null-check `.div` when working with tools that might be TempTools.
- If adding color controls, extend `ImageEditorToolWithColor`, pass the default color to `super()`, call `this.getColorControlsHTML()` when building config HTML, and call `this.wireColorControls()` after setting `configDiv.innerHTML`. The base class handles `setColor()`, `onLayerChanged()` color swapping, and grayscale enforcement automatically.