hcie-rust-v3.05/.kilo/plans/1784128529941-iced-gui-parity-vector-plan.md

# ICED GUI Parity: Scored Migration and Vector Tool Plan

## Goal
Bring every retained user-facing ICED editor feature to **at least 9/10 relative to egui**. Work proceeds in scored cycles. A cycle is incomplete until the complete scorecard is rerun and touched features reach target without regressing earlier work.

## Constraints
- GUI changes only under `hcie-iced-app/crates/`; `hcie-engine-api` remains the sole engine entry point.
- Preserve persistent wgpu textures, dirty-region uploads, viewport mapping, nearest filtering, and the `RefCell` dirty accumulator.
- Theme changes are UI-only. They must never invoke image/viewer loading, imports, dialogs, document replacement, or pixel mutation.
- Reachable `NoOp`, static fake controls, wrong menu aliases, and materially incorrect fallbacks score at most 2/10.
- Add ICED screenshot capture first; inspect screenshots after every visual change.
- Preserve unrelated working-tree changes.

## Scoring
| Score | Meaning |
|---|---|
| 0 | Absent/unusable |
| 1-2 | Placeholder; no real action |
| 3-4 | Partial, major paths missing |
| 5-6 | Basic workflow, substantial defects |
| 7 | Main workflow works, notable gaps |
| 8 | Near parity, minor gaps |
| 9 | Production parity: correct UI/action/undo/persistence as applicable, tested and visually verified |
| 10 | No known gap under covered scenarios |

## Baseline Inventory
Scores reflect the current working tree; the old vector `2.5/10` assessment is obsolete.

### Shell, Menus, Docking
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| Shell/title/tabs/window controls | 7 | Document close is `NoOp`; title drag overlaps menu region | 9 |
| Menu typography | 5 | Dropdown labels are thin/mixed contrast | 9 |
| Dropdown placement/event capture | 4 | Character-count X estimate; shifted/click-through risk | 9 |
| Menu command coverage | 3 | Most enabled-looking commands are labels/comments | 9 |
| Theme switching | 6 | Reported image-load side effect untested; no persistence | 9 |
| Dock resize/maximize/close | 8 | Main behavior works | 9 |
| Dock relocation | 6 | Drop only swaps; directional drop regions ignored | 9 |
| Dock profile/layout persistence | 5 | Does not serialize exact split tree/order/ratios | 9 |
| Panel reopen/focus | 7 | Coarse hardcoded placement | 9 |
| Settings persistence | 6 | Theme/toolbox/exact dock state missing | 9 |
| Internationalization | 3 | Most strings bypass i18n | 9 |
| ICED screenshot harness | 1 | F12 only refreshes | 9 |

### Canvas and Tools
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| GPU canvas/checkerboard/partial upload | 9 | Protected path active | 9 |
| Pan/zoom/100% | 8 | True fit-to-area incomplete | 9 |
| Fit/navigation/pinch/space-pan | 5 | Ctrl+0 sets 1.0; missing expected navigation | 9 |
| Brush/pressure | 8 | Modifier UX/cursor footprint | 9 |
| Pen | 5 | Mostly treated as Brush unlike egui pen segments | 9 |
| Eraser | 8 | Per-tool config/cursor polish | 9 |
| Spray | 7 | Verify density/particle settings reach engine | 9 |
| Flood fill | 7 | Contiguous/AA/history validation | 9 |
| Gradient | 5 | Stroke approximation, not true linear/radial gradient | 9 |
| Eyedropper | 7 | Ctrl-click temporary pick missing | 9 |
| Brush cursor/Shift resize HUD | 3 | Fixed crosshair only | 9 |
| Canvas context menu | 5 | Cut maps to Copy; partial actions | 9 |
| Rulers/grid/guides/snap/pixel grid | 1 | Menu shells only | 9 |
| Status/coordinates/pressure | 7 | Needs live cross-theme verification | 9 |
| Retouch tools | 2 | Selectable toolbox entries, incomplete execution/options | 9 |

### Selection, Transform, Clipboard
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| Rectangle selection | 8 | Minor parity/tests | 9 |
| Lasso/polygon | 7 | Preview/edge/close behavior | 9 |
| Magic wand | 7 | AA/contiguous partially `NoOp` | 9 |
| SmartSelect/SAM | 3 | Magic-wand fallback, no real backend flow | 9 |
| VisionSelect | 3 | Rectangle fallback, no model/task flow | 9 |
| Marching ants/fill | 5 | Bounds, not irregular mask edges | 9 |
| Raster transform | 7 | Undo/aspect/handles verification | 9 |
| Crop | 8 | Minor parity/tests | 9 |
| Copy/paste | 7 | External/internal selection tests | 9 |
| Cut/clear | 2 | Cut is Copy; Clear incomplete | 9 |
| Selection modify/load/save/quick mask | 4 | Some operations exist; exposed gaps remain | 9 |

### Vector and Text
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| Creation, 15 shape types | 8 | Verify layer safety/undo | 9 |
| Accurate previews | 7 | Several shapes remain approximate | 9 |
| VectorSelect/cycling | 7 | Implemented but insufficiently tested | 9 |
| Handles/hit testing | 7 | Rotated/hover/zoom behavior needs hardening | 9 |
| Move/8-way resize/rotate | 7 | Constraints, undo, edge cases | 9 |
| Apply/Cancel/snapshot | 7 | Verify exact restoration and overlay UX | 9 |
| Flip H/V | 6 | Verify supported shapes/output | 9 |
| Delete | 8 | Main path exists | 9 |
| Geometry list/selection | 8 | Main path exists | 9 |
| Bounds/fill/stroke/opacity/hardness | 8 | Precision/sync/tests | 9 |
| Line caps | 7 | Always-expanded list, weak selector UX | 9 |
| Boolean operations | 7 | Validation/failure/undo/result selection | 9 |
| Tool↔shape sync | 6 | Properties/Geometry/toolbar can diverge | 9 |
| Text create/inline edit | 6 | Focus/multiline/existing-layer edit/cancel | 9 |
| Text properties/effects | 6 | Full egui parity missing | 9 |

### Panels and Workflows
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| Layers | 8 | Hierarchy/duplicate/masks/fill opacity verification | 9 |
| History | 7 | Every operation needs correct undo boundary | 9 |
| Brushes & Tips | 7 | Category filter `NoOp`; advanced editor gaps | 9 |
| Color/palette/recent/alpha | 7 | Continuous wheel/recent UX/vector sync | 9 |
| Filters/preview | 8 | Audit every schema/default/apply/reset | 9 |
| Properties | 7 | Duplicate state surfaces may diverge | 9 |
| Tool Settings/toolbar | 7 | AA toggles/buttons remain `NoOp` | 9 |
| Layer Styles | 8 | Add-style placeholder/undo validation | 9 |
| Layer Details | 7 | Field/action parity audit | 9 |
| Script | 8 | Diagnostics/integration tests | 9 |
| AI Chat | 7 | Cancel/error/model discovery tests | 9 |
| AI Script | 7 | Provider/error/validation robustness | 9 |
| Viewer/browser | 7 | Cache/fullscreen/error/open-edit tests | 9 |
| Dialogs | 8 | Focus/validation/modal behavior | 9 |
| Plugins/actions/channels/histogram/navigator exposed by More | 1 | Labels only | 9 |

### Files and Documents
| Feature | Current | Key gap | Target |
|---|---:|---|---:|
| New/open/recent/import | 8 | Error and format coverage | 9 |
| Save/save-as/export | 6 | Unsupported menu claims/export paths | 9 |
| Multi-document tabs/dirty close | 6 | Tab close `NoOp`; dirty coverage | 9 |
| Image/canvas size/crop/merge/flatten | 8 | Regression tests | 9 |
| Layer duplicate/group/masks/rasterize/smart object | 3 | Menu shells/TODOs | 9 |
| Print/share/file-info/automation | 1 | Menu shells | 9 |

## Score Evidence Rules
A score may rise only when:
- UI is reachable and correctly positioned.
- A semantic message and real handler exist; no `NoOp` or wrong alias.
- State/engine output is correct.
- Undo/dirty state and persistence are correct where expected.
- Automated test passes.
- Visual behavior has an inspected screenshot.

Generate after every cycle under `target/iced-audit/`: full score table, failing evidence, test output, and screenshots. Add `tests/feature_scorecard.rs` with stable feature IDs and evidence test names.

## Cycle 0: Audit and Verification Infrastructure
1. Build a canonical registry from egui panes, tools, menus, dialogs, shortcuts and canvas interactions.
2. Add tests that fail for reachable `NoOp`, Cut→Copy aliases, enabled menu items without semantic handlers, or menu definition/index drift.
3. Add ICED screenshot CLI: `--screenshot output.png` and `--screenshot-panel "Panel" output.png`; settle layout/texture then crop from measured pane bounds.
4. Capture baseline full viewport, all menus, collapsed/expanded toolbox, Geometry, Properties, Layers, Color, and selected-vector canvas.
5. Run build/tests and record baseline scores. Do not raise scores without evidence.
6. **Recheck all scores.**

## Cycle 1: Requested UX Fixes
### Menus
Files: `panels/title_bar.rs`, `panels/menus.rs`, `app.rs`.
1. Replace approximate character-width offsets with measured menu-button anchor rectangles or an overlay anchored in the same layout subtree.
2. Place each dropdown at `anchor.x/anchor.bottom`, clamp to viewport, and make its outside-click layer fill/capture the viewport.
3. Separate draggable title space from menu buttons; menu clicks must not emit `WindowDrag` or reach underlying canvas/viewer.
4. Use a bundled readable UI font and Medium/Semibold weight for dropdown labels, shortcuts and arrows; use theme contrast tokens.
5. Replace raw `(menu_idx,item_idx)` dispatch with semantic `MenuCommand` generated from the menu definition.
6. Test all nine anchors at multiple widths/DPI; screenshot every dropdown in dark/light themes.

### Theme side-effect regression
1. Make theme commands synchronous: set colors, persist preset, close menu, repaint only.
2. Instrument file/import/viewer-preview/dialog/document replacement calls.
3. Test all themes preserve document ID/path/layers/composite hash/viewer selection/recent files/file-dialog state.
4. Switch themes while drawing and with viewer active/inactive; prove no image load or texture reset.

### Movable/reconfigurable panels
Files: `dock/state.rs`, `dock/view.rs`, `app.rs`, `settings.rs`, dock-profile dialog.
1. Handle full PaneGrid drop target: center swap; left/right/top/bottom close-and-split in requested side/order.
2. Preserve exactly one Canvas and one instance per utility pane; prevent closing/moving away the last Canvas.
3. Serialize actual dock tree recursively: pane type, split axis, ratio, child order, maximized/focused state.
4. Restore defensively with dedupe, ratio clamps, unknown-pane tolerance and default fallback.
5. Save/load/rename/delete exact profile layouts; add Painting, Vector, AI and Viewer presets.
6. Test every panel move/resize/close/reopen/maximize/save/reload.

### Expandable two-column toolbox
Files: `sidebar/mod.rs`, `app.rs`, `settings.rs`.
1. Persist collapsed 36px one-column and expanded ~72px two-column mode.
2. Add accessible chevron and shortcut.
3. Short click activates last-used subtool; secondary click/long press opens subtools; outside/Escape closes.
4. Expanded mode exposes all tools via a scrollable grouped two-column grid.
5. Every selectable tool must execute a real action or be visibly disabled with explanation.
6. Verify all 15 vector shapes, VectorSelect, Smart/Vision selection and retouch tools.
7. Screenshot both modes and popups at minimum height.

### Cycle 1 gate
Recheck the complete scorecard. Do not proceed until menu readability/placement, theme isolation, docking relocation/persistence and toolbox mode are each ≥9.

## Cycle 2: Vector Completion
1. Test selection, deselection, overlap cycling and active-layer changes.
2. Make handle hit areas screen-constant across zoom/pan. Render rotated geometry handles with hover/active styles and correct cursors.
3. Test move, all eight resize handles and rotation for every shape; prevent NaN/min-size/inversion errors; add Shift aspect and Alt center constraints.
4. Use one undo transaction per drag.
5. Render viewport-clamped Apply, Cancel, Flip H/V and Delete controls. Snapshot once; Apply commits once; Cancel restores exact state.
6. Centralize `sync_tool_from_shape` and `sync_shape_from_tool` so Geometry, Properties, toolbar, Tool Settings and color picker agree.
7. Replace always-expanded Geometry selectors with pick lists/popovers; add precise numeric inputs and shape-specific controls.
8. Validate boolean operands, failures, one undo entry and result selection for Union/Intersect/Subtract/Xor.
9. Share geometry generation between live preview and committed shape for all 15 variants plus FreePath; preserve anti-alias density.
10. Verify safe auto-vector-layer creation on raster/locked layers.
11. **Recheck every vector row; none below 9.**

## Cycle 3: Canvas, Selection, Raster, Text, Clipboard
1. Extract/cache actual mask edges for marching ants and fill irregular selected pixels, not bounds.
2. Complete lasso/polygon previews, MagicWand AA/contiguous and selection modify/load/save/quick-mask.
3. Make raster transform fully undoable with aspect lock and on-canvas Apply/Cancel.
4. Implement real Cut/Clear and selection-aware internal/external clipboard.
5. Add Ctrl-click eyedropper, Shift brush resize, space-pan, true fit-to-area and actual brush footprint cursor.
6. Give Pen distinct egui behavior; prove Spray settings reach engine; implement true linear/radial gradients.
7. Complete inline text focus/multiline/live preview/rotated caret/edit-existing/Accept/Cancel/properties/effects.
8. Wire real SmartSelect/VisionSelect/retouch backends; fake fallbacks cannot score 9. Disable with explanation only as a temporary state.
9. Implement exposed rulers/grid/guides/snap/pixel-grid states and rendering.
10. **Recheck all scores; no Cycle 3 row below 9.**

## Cycle 4: Panels
1. Layers: duplicate, grouping/hierarchy, reorder, fill opacity, masks/rasterize where API exists, context actions and history.
2. Brushes: category filter, presets/editing/imports/thumbnails/per-tool isolation.
3. Color: continuous wheel/SL drag, 40 recent wrapping/collapse/right-click-background, theme style and vector sync.
4. Filters: audit every FilterType schema/default/range/reset/preview/apply/error.
5. Establish one authoritative tool/property state; remove contradictory duplicates and all reachable `NoOp`.
6. Complete Layer Styles/Details/History undo/empty/selection behavior.
7. Complete dialog validation/focus/Enter/Escape/modal capture/responsiveness.
8. Add panel UI tests/screenshots in every theme.
9. **Recheck all scores; no panel row below 9.**

## Cycle 5: Menus, Files, Viewer, Script, AI, Remaining Features
1. Derive menu labels and semantic dispatch from one source; implement every enabled item.
2. Where support truly does not exist, disable with tooltip rather than presenting an enabled no-op. Retained egui features still require implementation.
3. Complete document close/dirty prompts, recent failures, save/export format selection/errors.
4. Complete viewer cache/navigation/fullscreen/open-edit/malformed-file behavior.
5. Script/AI: cancellation, provider/model discovery, network errors, diagnostics, execution confirmation, history/refresh.
6. Add real egui-supported More panels/actions (notably Plugins and Layer Styles); remove unsupported Photopea-only claims.
7. Apply i18n keys to every visible string and persist language.
8. Ensure menu and shortcut dispatch the same semantic command.
9. **Recheck the complete inventory; repeat Cycle 5 for every row below 9.**

## Final Regression Cycle
Run:
- `cargo fmt --check`
- `cargo build -p hcie-iced-gui`
- `cargo test -p hcie-iced-gui`
- scorecard/UI/integration tests
- `cargo test -p hcie-engine-api --test visual_regression` for engine-visible pixels
- `cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture` for stroke/canvas work

Then launch ICED, exercise every scorecard scenario, compare final screenshots to Cycle 0, prove theme composite hashes are unchanged, verify dock restart recovery, and rescore everything. **Stop only when every retained feature is ≥9/10.**

## Mandatory Scenarios
- Every menu anchor, narrow/wide viewport, DPI scales, dark/light themes.
- Six themes with active drawing and viewer active/inactive; no document mutation.
- Every pane moved to every region, resized, closed/reopened, maximized, persisted.
- Toolbox one/two columns, all subtools, minimum height, Escape/outside click.
- Every vector shape create/select/move/8-resize/rotate/apply/cancel/delete/flip/properties/boolean.
- Rect/lasso/polygon/magic/AI selection, irregular ants, transform, crop, clipboard, undo.
- Multi-document open/switch/close/dirty, import/export failures.
- 4K continuous stroke, pan/zoom, vector drag and theme switch without full-upload regressions.

## Risks
- PaneGrid may not support floating windows/tabs directly. Required acceptance is arbitrary split relocation and exact persistence; floating windows are optional unless added without state/event duplication.
- Some menu claims exceed egui/engine support. Honest disabled states are preferable to fake enabled actions, but egui parity features must be implemented.
- Document engine API gaps before any locked-crate proposal; never import internal crates into GUI.
- Re-read files before patches because the working tree has concurrent/uncommitted changes.

## Done Definition
- No retained feature below 9.
- No reachable production `NoOp` or wrong semantic alias.
- No enabled menu item without a tested handler.
- Panels relocate, resize and restore exactly.
- Menus are readable and exactly anchored.
- Theme changes cannot load/mutate images.
- Toolbox has persisted one/two-column modes and all vector tools are connected.
- Vector handles/editing are accurate, undoable and visually verified.
- Protected GPU optimizations remain intact.