hcie-rust-v3.05/.kilo/plans/1784456713003-iced-gui-visual-polish-plan.md

ICED GUI Visual & Behavioral Polish Plan

Context

This plan addresses the visual and functional issues surfaced during recent ICED GUI testing. The focus is on the Iced build (hcie-iced-app/crates/hcie-iced-gui/). Items are grouped by theme and ordered to minimize code conflicts.

---

Tasks

1. Fix theme-inconsistent blue accent buttons

Problem: Dialogs like New Image show preset buttons as solid blue (#3355cc), which clashes with the dark theme and looks unnatural.

Files:

• hcie-iced-app/crates/hcie-iced-gui/src/dialogs/new_image.rs
• hcie-iced-app/crates/hcie-iced-gui/src/dialogs/mod.rs (primary/secondary helpers)

Changes:

• Add a preset_btn helper in dialogs/mod.rs that uses theme colors (bg_hover/accent border/text) rather than the default blue.
• Use it for all preset rows.
• Ensure primary button (Create) remains theme-accent but with hover/pressed states.

---

2. Fix color-picker persistence / session recall

Problem: The user reports that foreground/background colors are identical on startup and recent colors are not added/persisted.

Observed code:

• load_colors() is called in app.rs:1719 and applied.
• add_recent_color() exists and is called by FgColorChanged/SwapColors.
• save_colors() is called when colors_dirty is true.

Likely issues:

• load_colors returns PersistedColors with #[serde(default)], but if any field is absent it becomes Default, which is None/empty. This is fine.
• Root cause candidates:
  • Message::ResetColors exists, but there may be no UI button mapped to it in the color picker panel.
  • The saved colors file may not be written because colors_dirty is only set on FgColorChanged/BgColorChanged/SwapColors/ResetColors. Some popup color changes may not route through those messages.
  • When the app starts, fg_color and bg_color are initialized to the same default ([0,0,0,255]) before load_colors() runs, and then load_colors overrides them. This should be correct, but verify.

Changes:

• Ensure PopupColorChanged routed to Foreground/Background actually triggers add_recent_color and sets colors_dirty. It does via FgColorChanged/BgColorChanged.
• Add a Reset button in the color picker panel (color_picker.rs) that emits Message::ResetColors.
• Verify load_colors() correctly falls back when file is missing; add debug log if parsing fails.
• Ensure save_colors() stores alpha and recent list (already does).
• Remove or explain why fg_color/bg_color default to the same value in IcedDocument / HcieIcedApp::new before loading.

---

3. Right-click to pick secondary color in color palette panel

Problem: Right-click on palette/recent colors should set the background color.

Observed code:

• color_picker.rs already has .on_right_press(Message::BgColorChanged(...)) on palette grid cells and recent colors.
• However, the wheel canvas only handles right-click inside ColorWheel::update and sends Message::BgColorChanged(color).

Changes:

• Verify right-click events are not swallowed by the panel/container.
• If Iced does not deliver right-clicks on mouse_area children reliably, wrap the whole color picker content in a mouse_area with on_right_press to set background color from current foreground? No — user expects picking the swatch under cursor.
• Prefer: keep per-swatch right-click handlers and add a test or visual verification.
• If still broken, investigate whether mouse_area in Iced 0.13 requires an explicit background hit; add a transparent container around each swatch.

---

4. Enforce color palette panel minimum height so content stays visible

Problem: Color Palette panel can be collapsed too short; its contents become hidden.

File: hcie-iced-app/crates/hcie-iced-gui/src/dock/sizing.rs

Change:

• Raise PaneType::ColorPicker minimum height from 300.0 to 420.0.
• Consider also raising min width from 180.0 to 200.0.
• Ensure the color picker view uses scrollable(content) so overflow remains usable.

---

5. Filters panel: parameter sliders should fill ~80% of panel width

Problem: Filter parameter sliders are too narrow and leave large unused space.

File: hcie-iced-app/crates/hcie-iced-gui/src/panels/filter_params.rs

Changes:

• Audit all float_slider / int_slider calls and ensure the underlying plain_slider width is Length::Fill inside a container with width(Length::Fill).
• In filters.rs, wrap the parameter section in a container with width(Length::Fill) and ensure scrollable(params_panel) does not clamp width.
• Add width(Length::Fill) to the column! returned by filter_params::view if not already present.

---

6. Filter operations should integrate with history / undo

Problem: Filter Apply is not undoable via the History panel.

File: hcie-iced-app/crates/hcie-iced-gui/src/app.rs

Change:

• Before engine.apply_filter(...) in Message::FilterApply, call engine.push_active_layer_snapshot(...) (or the appropriate engine history API) with a description like "Apply <filter_name>".
• After apply, refresh history cache (refresh_history) so the new entry appears in the History panel.
• Ensure undo (Message::HistoryJump) and redo paths still work after the snapshot is pushed.

---

7. Brush button should reveal Brushes panel if closed

Problem: User says brush button does not open the Brushes panel.

Observed code: Message::ToolSelected(Tool::Brush) already calls self.dock.reopen_pane(PaneType::Brushes) at app.rs:2289.

Possible issue: reopen_pane may silently fail when the pane is auto-hidden or floating; or the brush tool can also be selected via slot click without this path.

Changes:

• Verify ToolSlotClicked/SubtoolsToggle also triggers reopen_pane(PaneType::Brushes) when the resulting tool is Tool::Brush.
• Add a helper ensure_brushes_panel() and call it wherever the active tool becomes Tool::Brush.
• Test with panel closed, auto-hidden, and in a different tab group.

---

8. Selecting a filter from the Filters menu should reveal the Filters panel

Problem: Filter menu selection should open/raise the Filters panel.

Observed code: Message::FilterSelect(filter) already calls self.dock.reopen_pane(PaneType::Filters) at app.rs:4628.

Possible issue: Same as above — reopen_pane may not handle auto-hide/floating states.

Changes:

• Audit DockState::reopen_pane to ensure it restores auto-hidden panels, focuses existing floating panels, and brings the pane to front if stacked.
• If reopen_pane is already correct, add visual verification; otherwise fix it.

---

9. Menu bar vertical padding (+2 px already planned, verify in final screenshot)

File: hcie-iced-app/crates/hcie-iced-gui/src/panels/title_bar.rs

Already changed: MENU_BAR_HEIGHT 28→30 and menu button widths increased.

Remaining: Confirm no clipping occurs with the new widths; adjust further if "Image" still truncates.

---

10. Prevent zero-size document creation (wgpu crash)

Problem: The New Image dialog allows width or height to be set to 0. Creating a 0×N document causes the renderer to request a texture with zero height (resize_texture 800×600 → 4096×0), which triggers a wgpu validation error and panic.

Files:

• hcie-iced-app/crates/hcie-iced-gui/src/dialogs/new_image.rs
• hcie-iced-app/crates/hcie-iced-gui/src/app.rs (DialogNewImageCreate handler)

Changes:

• Clamp the width/height sliders to a minimum of 1 in new_image.rs.
• In DialogNewImageCreate, validate dialog_new_width >= 1 && dialog_new_height >= 1 before creating the engine; if invalid, keep the dialog open and log a warning (or show inline validation text).
• Optionally disable the Create button when either dimension is zero.
• Remove or ignore the Custom preset with width: 0, height: 0 since it is not a valid document size.

---

11. Expose spray particle size / density in the UI

Problem: Spray tool radius/density settings are present in tool_settings.rs but not visible in the merged toolbar or Properties panel.

Observed code:

• tool_settings.rs:132-179 already has spray_settings() with Particle Size and Density sliders.
• properties.rs:134 groups Tool::Spray with brush properties, which only shows Size/Opacity/Hardness.
• toolbar.rs:95 also groups Spray with Brush and only shows Size/Hardness.

Changes:

• In properties.rs, when active_tool == Tool::Spray, call a new spray_properties(...) helper that includes Size, Particle Size, Density, Opacity, and Hardness.
• In toolbar.rs, add a Spray-specific branch that shows Size, Particle Size, and Density (or move the existing spray controls from the Tool Settings panel into the merged toolbar if that is the intended UX).
• Ensure the values are read from settings.tool_settings.spray_particle_size / spray_density and emit the existing Message::SprayParticleSizeChanged / SprayDensityChanged messages.

---

12. Add a custom-shape slot / panel so user SVGs under ~/.local/share/hcie/shapes/ are usable

Problem: The user copied extra SVG files into /home/dev-user/.local/share/hcie/shapes/, but they did not appear in the UI and could not be used.

Observed code:

• Engine::new() initializes shape_catalog from dirs::data_local_dir()/hcie/shapes (matches ~/.local/share/hcie/shapes) in hcie-engine-api/src/lib.rs:558-562.
• ShapeCatalog::refresh() in hcie-engine-api/src/shape_catalog.rs scans *.svg files there and assigns them indices.
• Tool::CustomShape(idx) exists and is handled in app.rs:5945-5966, using a snapshot of shape_catalog.all() during VectorDrawEnd.
• sidebar/mod.rs TOOL_SLOTS does not contain a slot for Tool::CustomShape. The vector-shapes slot only lists built-in VectorArrow, VectorStar, etc.
• There is no panel or popup listing the catalog entries for selection.

Root cause: The ICED sidebar has no entry point for Tool::CustomShape, so even though the engine loads custom SVGs from ~/.local/share/hcie/shapes/, the user cannot select or draw them.

Decision: New dock panel with real SVG previews via iced::widget::svg::Handle::from_memory.

Changes:

• Add PaneType::CustomShapes to dock/state.rs with label "Custom Shapes".
• Create hcie-iced-app/crates/hcie-iced-gui/src/panels/custom_shapes.rs.
  • Accept shapes: &[ShapeEntry] and selected_index: Option<usize>.
  • Render each entry as a small card (e.g. 56×56 preview + label below).
  • Use iced::widget::Svg::new(Handle::from_memory(entry.svg.into_bytes())) for the preview, sized to fit the card.
  • On click, emit Message::ToolSelected(Tool::CustomShape(index)).
  • Highlight the selected card with colors.accent border.
• Wire the new panel in dock/view.rs.
• Add the panel to settings.rs default visible_panels / panel_order so it appears in the initial dock layout.
• Add a "Refresh" button in the panel that emits Message::RefreshCustomShapes; handler calls engine.shape_catalog.refresh() and updates app.cached_custom_shapes.
• Store a cached Vec<(String, String)> of custom shapes in HcieIcedApp so the panel can be rebuilt cheaply; refresh it whenever the panel is shown or when Refresh is pressed.
• Ensure Tool::CustomShape(idx) out-of-range cases return None in VectorDrawEnd (already mostly true; add explicit guard).
• Verify that copied SVGs are valid — ShapeCatalog silently skips unreadable / non-SVG files.

12b. Custom Shape drawing not triggering on canvas

Problem: Selecting a custom shape in the Custom Shapes panel does not actually draw it on the canvas when dragging.

Root cause: The shared vector-shape drag flow is gated by is_vector_shape_tool() and an explicit match arm in the CanvasPointerPressed handler. Both locations enumerate the built-in Tool::Vector* variants but omit Tool::CustomShape(_), so the custom-shape tool never enters VectorDrawStart/VectorDrawMove/VectorDrawEnd and therefore never reaches the existing VectorDrawEnd handler that already knows how to build a VectorShape::SvgShape from the catalog.

Files:

• hcie-iced-app/crates/hcie-iced-gui/src/app.rs
• hcie-iced-app/crates/hcie-iced-gui/src/sidebar/mod.rs (icon support already present; no change)

Changes:

1. In app.rs helper is_vector_shape_tool() (around line 1287), add Tool::CustomShape(_) to the matches! pattern.
2. In app.rs CanvasPointerPressed handler (around line 2824), add Tool::CustomShape(_) to the arm that starts Message::VectorDrawStart.
3. Keep VectorDrawEnd unchanged; it already snapshots shape_catalog.all() (line 5528-5539) and builds a VectorShape::SvgShape for Tool::CustomShape(idx) with correct bounds.

Edge cases to consider:

• Out-of-range Tool::CustomShape(idx) already returns None from VectorDrawEnd and produces no shape.
• If the active layer is a locked vector layer, the shape-flow first switches to a safe non-vector layer before drawing, just like built-in vector shapes.

Validation:

1. Build: cargo check -p hcie-iced-gui and cargo test -p hcie-iced-gui.
2. Run the Iced GUI.
3. Window → Custom Shapes → select a shape.
4. Drag on the canvas → a new vector layer containing the custom SVG shape appears.
5. Undo reverts the inserted shape (history snapshot is pushed by engine.add_vector_shape).

---

Validation Plan

1. cargo check -p hcie-iced-gui
2. cargo test -p hcie-iced-gui
3. Manual launch and visual checks:
   • New Image dialog presets look theme-aware (not bright blue).
   • Set width or height to 0 → Create button disabled; preset ignores 0-size values.
   • Create documents with valid sizes → no wgpu panic.
   • Spray tool selected → Particle Size / Density sliders visible in Tool Settings panel.
   • Pick colors, close app, reopen — colors and recent list restored.
   • Right-click a palette swatch sets background color.
   • Color Palette panel cannot be resized below content height.
   • Select Brush tool → Brushes panel appears.
   • Filter menu → Filters panel appears and parameter sliders are wide.
   • Apply a filter → History panel gains an "Apply …" entry; Undo reverts it.
   • Custom SVG files in ~/.local/share/hcie/shapes/ appear in the new Custom Shapes panel and can be drawn.

---

Open Questions

• Is there a reference image or exact hex for the desired preset button style? (Current theme tokens: bg_hover, accent, text_primary.)
• Should the New Image dialog enforce a single minimum (e.g. 1×1) or a practical minimum (e.g. 8×8) to avoid 1-pixel-high canvases?
• Should custom shapes be rendered as small SVG previews in the panel, or is a text label list acceptable as a first pass? (Recommended: text list first, SVG preview later.)