hcie-rust-v3.05/.kilo/plans/1784597466971-iced-gui-ux-improvements-plan.md

Iced GUI UX Improvements Plan

Goal

Implement five requested UI/UX and functional improvements in the hcie-iced-gui workspace, plus fix the reported regression where the first brush stroke does not appear in the History panel.

Scope & Boundaries

• Open layer: hcie-iced-app/crates/hcie-iced-gui/, plus the new SVG asset.
• Locked layers touched only for history fixes: hcie-engine-api and hcie-document must be unlocked with the repo scripts, edited, and re-locked.
• All other improvements are GUI-only.
• Preserve protected GPU/dirty-region, partial-upload, and shader-layering behavior.

Out of Scope

• egui GUI changes (except if a trivial parity icon is needed, noted below).
• New brush engine styles or engine-side brush changes.
• Layer duplicate / mask / rasterize functionality (toolbar placeholders stay as-is; only iconography changes).

---

1. History Panel Enhancements + First-Brush-Stroke Fix

1.1 Bug: first brush stroke missing from History

Root cause: end_stroke() creates the undo snapshot on a background thread and stores it in pending_history. The GUI calls commit_pending_history() once immediately after end_stroke(), but the thread may not have finished, so the snapshot is never committed and cached_history is never refreshed.

Fix (engine side):

• In hcie-engine-api/src/stroke_cache.rs:
  • Change commit_pending_history() to return bool — true if it committed at least one pending snapshot, false otherwise.
  • Add pub fn has_pending_history(&self) -> bool that returns whether the pending_history mutex still has uncommitted items.
• In hcie-document/src/lib.rs:
  • Ensure push_draw_snapshot_subrect and push_draw_snapshot still skip no-change snapshots (preserve existing behaviour); no new logic needed.

Fix (GUI side):

• In hcie-iced-gui/src/app.rs Message::CanvasPointerReleased brush-stroke cleanup block:
  • After end_stroke, call commit_pending_history().
  • If commit_pending_history() returned false and engine.has_pending_history() is true, schedule a delayed CompositeRefresh chain (e.g. 8 ms, 16 ms, 32 ms) using tokio::time::sleep inside Task::perform, each time re-checking and re-committing until pending is drained.
  • Always finish with refresh_composite_if_needed() so cached_history is updated.

Regression test:

• Add a new engine test hcie-engine-api/tests/brush_stroke_history.rs:
  • Create a 16×16 engine, set a Round brush, begin_stroke, stroke_to to a different pixel, end_stroke, commit_pending_history().
  • Assert history_len() increased by exactly one and history_description(...) is "Brush Stroke" (or the enhanced description after 1.2).
  • Assert undo restores the blank layer.
• Add an iced-level test in hcie-iced-app/crates/hcie-iced-gui/tests/ (or extend feature_scorecard.rs) that simulates the message sequence CanvasPointerPressed → CanvasPointerMoved → CanvasPointerReleased for a brush stroke and asserts cached_history grows.

1.2 Rich history descriptions

Engine side:

• In hcie-engine-api/src/stroke_brush.rs:
  • draw_stroke() currently pushes "Brush Stroke". Change it to include the brush style label, e.g. "Brush Stroke (Round)", "Brush Stroke (Watercolor)", etc.
  • draw_line() → "Line", draw_rect() → "Rectangle", draw_filled_rect_rgba() → "Fill Rectangle", draw_ellipse() → "Ellipse".
• In hcie-engine-api/src/stroke_cache.rs background thread:
  • The interactive end_stroke() path currently hard-codes "Brush Stroke". Replace with a description that includes self.current_tip.style label (e.g. "Brush Stroke (Oil)").
• In hcie-engine-api/src/lib.rs vector mutators:
  • add_vector_shape: keep "Add Vector Shape" but append the shape kind/name when known: "Add Vector Shape (Rect)", "Add Vector Shape (Path 12 pts)", etc.
  • delete_vector_shape: push a vector snapshot with description "Delete Vector Shape (<kind>)".
  • set_vector_shape_bounds: "Resize Vector Shape (<kind>)".
  • set_vector_shape_angle: "Rotate Vector Shape (<kind>)".
  • set_vector_shape_color: "Set Stroke Color".
  • set_vector_shape_fill_color: "Set Fill Color".
  • set_vector_shape_fill: "Toggle Fill".
  • set_vector_shape_stroke: "Set Stroke Width".
  • set_vector_shape_opacity: "Set Shape Opacity".
  • set_vector_shape_hardness: "Set Shape Hardness".
  • reorder_vector_shape: "Reorder Vector Shape".
  • boolean_vector_shapes: already has "Path Boolean ({op})"; keep.

Helper to add in hcie-engine-api/src/lib.rs:

• fn vector_shape_kind(shape: &VectorShape) -> &'static str mapping each VectorShape variant to a short label.
• fn vector_shape_name_or_kind(shape: &VectorShape) -> String returning shape.name() if non-empty, else the kind label.

Note: vector property mutators currently do not push snapshots, so undo does not cover them. Adding snapshots here fixes both the history description and makes these operations undoable, which is required for a 9/10 History score.

GUI side:

• In hcie-iced-gui/src/panels/history.rs:
  • Keep the list layout but widen the text column so longer descriptions are not clipped. Reduce index prefix formatting noise: keep "{}: {}" but ensure the container does not hard-wrap at 30 chars.
  • Add a subtle muted style for future entries and accent style for current (already exists); verify contrast.

---

2. Clipboard: Paste as New Layer

Goal

Add a workflow to paste clipboard pixels directly as a new raster layer, instead of always entering floating transform mode.

Changes

Menu / command:

• In hcie-iced-gui/src/panels/menus.rs:
  • Add MenuCommand::PasteAsNewLayer.
  • Add a menu item under Edit: "Paste as New Layer" with shortcut Ctrl+Shift+V (replace the existing Paste Special shortcut mapping; keep Paste Special label as a placeholder or map it to the same command if preferred).
  • Add the same item to canvas_context_menu between Paste and New Layer.

Message:

• In hcie-iced-gui/src/app.rs Message enum:
  • Add PasteAsNewLayer.

Handler (in Message dispatch):

• On PasteAsNewLayer:
  1. Prefer internal_clipboard if present; otherwise read system clipboard via io/clipboard::paste_image_from_clipboard().
  2. If clipboard image exceeds canvas, show the existing ExpandCanvas dialog first, then proceed.
  3. Compute target size:
     • If oversized and user accepted expand: use clipboard width/height as new canvas size.
     • Otherwise: keep current canvas size.
  4. Create a new layer via engine.add_layer("Pasted Layer").
  5. Center the clipboard pixels in the new layer using engine.set_layer_pixels(new_layer_id, centered_pixels).
  6. Push an undo snapshot on the new layer with description "Paste as New Layer".
  7. Set the new layer as active.
  8. Call refresh_composite_if_needed() and return CompositeRefresh.

Helper to add:

• In hcie-iced-gui/src/selection/clipboard.rs or a new hcie-iced-gui/src/clipboard.rs:
  • fn centered_layer_pixels(pixels: &[u8], img_w: u32, img_h: u32, canvas_w: u32, canvas_h: u32) -> Vec<u8> that returns a full canvas-sized RGBA buffer with the image centered.

Note: avoid changing the existing PasteImage floating-transform path; add the new path in parallel.

---

3. Layers Panel Iconography

Goal

Replace text-only controls in the Layers panel with intuitive icon buttons, and specifically fix the visibility toggle to use a standard eye/eye-slash icon.

Changes

New SVG asset:

• Create hcie-iced-app/assets/icons/eye_closed.svg for hidden layers.
• Existing hcie-iced-app/assets/icons/visible.svg can be reused as the open eye.

Helper for small SVG buttons:

• In hcie-iced-gui/src/panels/layers.rs (or styles.rs):
  • Add a helper fn svg_icon_btn<'a>(icon_path: &str, tip: &str, msg: Message, colors: ThemeColors, enabled: bool) -> Element<'a, Message> that loads the SVG from the absolute assets path (falling back to text) and wraps it in a small flat button with a tooltip.

Row controls:

• Replace the visibility text button ("\u{1F441}") with visible.svg / eye_closed.svg based on info.visible.
• Replace the lock text ("L" / "-") with lock.svg for locked and a subtle open-lock or empty placeholder for unlocked.
• Keep the same Message::LayerToggleVisibility / LayerToggleLock messages.

Toolbar controls:

• Replace text toolbar buttons with icon buttons:
  • +Layer → new_file.svg or panel-layers.svg plus tooltip
  • +Group → a folder/group SVG (use panel-layers.svg if no group icon exists)
  • Flatten → a merge/layers SVG (keep text if no icon)
  • ▲ / ▼ move arrows keep unicode arrows but use consistent size
  • X delete keep unicode but ensure visible
  • fx keep as text because it's a convention
• Wrap each in the same svg_icon_btn helper where an icon exists; for missing icons keep compact text buttons.

No engine changes.

---

4. Vector Transform Preview Performance

Goal

Eliminate latency during vector rotate/scale so the preview updates in real time.

Root cause

VectorSelectDragMove throttles preview updates to ~60 FPS and draws only the rotated bounding box of the preview shape, not the actual shape geometry. The 60 FPS throttle intentionally drops pointer events, which feels laggy, and the wireframe box is a weak visual proxy.

Changes (all in GUI)

Remove throttle:

• In hcie-iced-gui/src/app.rs Message::VectorSelectDragMove:
  • Remove the vector_drag_last_render 60 FPS throttle block. Update vector_drag_preview on every DragMove.
  • Keep vector_drag_last for pointer tracking.

Draw actual shape geometry in overlay:

• In hcie-iced-gui/src/canvas/mod.rs OverlayProgram::draw():
  • Where vector_drag_preview is rendered (around line 1297), replace the simple rotated rectangle stroke with a shape-specific renderer:
    • For VectorShape::Rect, Circle, Line, Arrow, Star, Polygon, Rhombus, Cylinder, Heart, Bubble, Gear, Cross, Crescent, Bolt, Arrow4, SvgShape:
      • Draw the same geometry as vector_draw preview already does for in-progress shapes (ellipse, line, star, polygon, rounded rect paths).
      • Apply the preview's angle and normalized_bounds() transform so the preview exactly matches the committed shape.
    • For VectorShape::FreePath:
      • Draw the path points transformed by the preview bounds/angle.
  • Use the same bright green stroke style ([0.2, 0.9, 0.4, 0.95]) and keep the edit handles drawn over it.

Shared preview renderer:

• Extract the existing vector-shape preview drawing code from vector_draw block in canvas/mod.rs into a helper fn draw_vector_shape_preview(frame: &mut Frame, shape: &VectorShape, origin_x: f32, origin_y: f32, zoom: f32, stroke_color: iced::Color, line_width: f32).
• Reuse it both for in-progress vector_draw and for vector_drag_preview.

No engine changes.

---

5. Brush Panel: Distinct Watercolor Icon

Goal

Replace the Watercolor category tab icon so it is not identical to the Painting tab.

Changes

New SVG asset:

• Create hcie-iced-app/assets/icons/watercolor.svg — a droplet/splat shape, using fill="currentColor" like the other icons.

GUI change:

• In hcie-iced-app/crates/hcie-iced-gui/src/panels/brushes.rs category tabs array:
  • Change Watercolor tab from "icons/brush.svg" to "icons/watercolor.svg".

No engine changes.

---

Implementation Order

1. Vector transform preview (#4) — pure GUI, safe to start.
2. Layers panel icons (#3) — pure GUI.
3. Watercolor icon (#5) — pure asset + one-line GUI change.
4. Paste as new layer (#2) — pure GUI, can be done in parallel with #1–#3.
5. History enhancements + first-stroke fix (#1) — requires unlocking engine crates; do this last to minimize locked-crate exposure.

Validation

• cargo check -p hcie-iced-gui
• cargo test -p hcie-iced-gui
• cargo test -p hcie-engine-api --test visual_regression
• cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture
• cargo test --test feature_scorecard
• Manual / screenshot verification:
  • Draw one brush dab with no drag → History panel shows the entry.
  • Draw a second stroke with a different brush style → description includes style name.
  • Create a vector shape, change its fill/color/rotate/resize → each appears in History with shape kind and action.
  • Copy a selection, use "Paste as New Layer" → new layer appears with pasted pixels.
  • Toggle layer visibility → eye icon changes between open/closed.
  • Rotate/scale a vector shape → preview follows pointer without frame drops.
  • Open Brushes panel, select Watercolor category → new droplet icon is visible.

Risks & Guardrails

• Locked crates: Only unlock hcie-engine-api and hcie-document for history changes. Re-lock immediately after.
• Background thread race: The first-stroke fix relies on delayed CompositeRefresh tasks; ensure tasks are cancelled or no-op if the document/engine state changes before they fire.
• Performance: Removing the vector drag throttle increases overlay redraws, but overlay drawing is cheap vector geometry on a small canvas; verify no regression on 4K docs.
• Icon fallback: SVG icon helper must fall back to text if the icon file is missing, matching toolbar.rs behaviour.
• No protocol changes: Do not add new VectorShape variants or new BrushStyle variants.