feat: flutter gui

.gitignore

@@ -26,4 +26,6 @@ build/
 *.jpg
 *.jpeg
 .idea/
-.vscode/
+.vscode/
+
+.claude

.planning/MILESTONES.md

@@ -0,0 +1,30 @@
+# Milestones: diffusion-rs GUI
+
+## v1.0 MVP — 2026-06-23
+
+**Status:** shipped
+**Phases:** 2 | **Plans:** 5 | **Commits:** 44
+**Timeline:** 2026-06-18 → 2026-06-23 (6 days)
+**Files changed:** 189 (+21,610 lines) | **LOC:** ~4,782 (Dart + Rust)
+
+### Delivered
+
+A full Flutter desktop GUI for diffusion-rs — two-panel Yaru layout with 14-field parameter form exposing all CLI options, real Rust FFI via flutter_rust_bridge, live step-by-step preview during inference, and session-isolated temp directory lifecycle.
+
+### Key Accomplishments
+
+1. Scaffolded Flutter desktop app in gui/ with two-panel Yaru layout and mock generation service
+2. Built complete 14-field parameter form with 41-preset catalog mirroring src/preset.rs
+3. Implemented session-isolated temp directory lifecycle with OS-native save flow
+4. Created gui/rust/ Cargo crate with FRB functions, GuiParams DTO, catch_unwind, and Progress pub fields
+5. Wired Cargokit build integration, RustGenerationService with live preview streaming, and provider swap
+
+### Requirements
+
+- 45/46 v1 requirements validated
+- 1 deferred: FORM-07 (batch count) → v2
+
+### Archive
+
+- `.planning/milestones/v1.0-ROADMAP.md`
+- `.planning/milestones/v1.0-REQUIREMENTS.md`

.planning/PROJECT.md

@@ -0,0 +1,91 @@
+# diffusion-rs GUI
+
+## What This Is
+
+Una GUI desktop Flutter per diffusion-rs che espone tutte le funzionalità della CLI in un'interfaccia grafica a due pannelli: sinistra per i parametri di generazione, destra per la preview live e l'immagine finale. La GUI comunica con la libreria Rust via flutter_rust_bridge (FFI), include un meccanismo di live preview step-by-step durante l'inferenza, e usa file temporanei puliti alla chiusura dell'app. Il progetto vive nella cartella `/gui` del monorepo diffusion-rs esistente.
+
+## Core Value
+
+L'utente può configurare e avviare una vera generazione di immagini con lo stesso set di opzioni della CLI, senza aprire un terminale, con preview live aggiornata ad ogni step di diffusione.
+
+## Requirements
+
+### Validated
+
+- ✓ Generazione immagini con preset multipli (SD 1.x/2.x, SDXL, SD3, Flux, ecc.) — existing
+- ✓ Interfaccia CLI con tutti i parametri di generazione — existing
+- ✓ Supporto multi-platform desktop (macOS, Linux, Windows) — existing
+- ✓ Download modelli da HuggingFace Hub con token opzionale — existing
+- ✓ Preview immagine durante la generazione — existing
+- ✓ Upscaler post-generazione (8 modalità) — existing
+- ✓ Modalità di caching accelerate (UCACHE, EASYCACHE, DBCACHE, TAYLORSEER, CACHEDIT, SPECTRUM) — existing
+- ✓ Generazione batch (Rust backend) — existing
+- ✓ Progetto Flutter in `/gui` come sottocartella del monorepo diffusion-rs — v1.0
+- ✓ Layout a due pannelli ridimensionabile (left: parametri + controlli; right: preview + immagine finale) — v1.0
+- ✓ Dropdown preset (41 varianti da PresetDiscriminants) via Rust FFI — v1.0
+- ✓ Dropdown pesi contestuale al preset via Rust FFI — v1.0
+- ✓ Tutti i 14 campi CLI attivi nel form (prompt, negative, steps, width, height, cache, preview, upscaler, upscaler_scale, seed, low_vram, token) — v1.0
+- ✓ Campo token HuggingFace come campo password (testo oscurato, toggle visibilità) — v1.0
+- ✓ Bottone Generate che disabilita tutti gli input durante la generazione — v1.0
+- ✓ Barra di avanzamento con contatore step durante la generazione — v1.0
+- ✓ Preview live aggiornata ad ogni step di diffusione — v1.0
+- ✓ Immagine finale nel pannello destro con bottone Save — v1.0
+- ✓ File temporanei per immagini (preview e output), ripuliti alla chiusura dell'app — v1.0
+- ✓ Tema visivo Yaru con supporto chiaro/scuro/sistema — v1.0
+- ✓ Scorciatoia Cmd/Ctrl+Enter equivalente al bottone Generate — v1.0
+- ✓ catch_unwind per panic Rust: mostra AlertDialog invece di crashare l'app — v1.0
+- ✓ FRB codegen CI check (diff check per binding sincronizzati) — v1.0
+- ✓ FORM-15 warning: upscaler attivo senza cache — v1.0
+
+### Active
+
+- [ ] Batch count field nel form UI (FORM-07) — generazione di N immagini alla volta
+- [ ] History prompt con recall degli ultimi N prompt usati (UX-01)
+- [ ] Gallery output — pannello che mostra le immagini generate nella sessione corrente (UX-02)
+- [ ] Cancellazione generazione in corso — richiede segnale abort nel backend C++ (UX-03)
+- [ ] Metadata embedding (parametri di generazione) nel PNG salvato (UX-04)
+- [ ] Lista preset raggruppata per famiglia con ricerca (UX-05)
+- [ ] UI per download/gestione modelli da HuggingFace (MDL-01, MDL-02, MDL-03)
+
+### Out of Scope
+
+- Mobile (iOS/Android) — GUI desktop only; non compatibile con flutter_rust_bridge su mobile
+- Web version — non compatibile con FFI nativa e file system access
+- Generazioni concorrenti multiple — backend single-threaded per design
+- Image-to-image / ControlNet / LoRA UI — esposti solo indirettamente tramite parametri CLI standard
+
+## Context
+
+**Shipped v1.0** (2026-06-23): ~4,782 LOC project code (3,662 Dart + 1,120 Rust), 189 files changed.
+
+**Tech stack:** Flutter 3.44.x + Dart, flutter_rust_bridge 2.12.0, Yaru 10.2.0, Riverpod 3.x, Cargokit (CocoaPods-based build integration), multi_split_view 3.6.2, file_picker 11.x, path_provider, uuid.
+
+**Known technical debt:**
+- FRB Dart binding stubs hand-written (codegen requires full C++ build chain); need regeneration after build environment is available
+- Batch count not wired in GUI (backend supports it, UI form does not)
+
+## Constraints
+
+- **Tech stack**: Flutter + Dart per la GUI, flutter_rust_bridge per FFI, Yaru per il design system
+- **Struttura**: sottocartella `/gui` nel monorepo — nessun repo separato
+- **File temporanei**: tutti i path di output usati dalla GUI puntano a una temp dir, pulita all'uscita dell'app
+- **Sequenza**: Fase 1 (mock completo) prima del wiring Rust — consente di sviluppare e testare la UI indipendentemente dalla build Rust
+- **Platform**: desktop only (macOS, Linux, Windows) — stesso target del backend Rust
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| flutter_rust_bridge per FFI | Standard de facto per Dart↔Rust su desktop; genera bindings tipizzati automaticamente | ✓ Good — cargokit integra build automatica; FRB 2.x streaming idiomatico |
+| Fase 1 mock prima del wiring | Disaccoppia sviluppo UI dal build Rust (lungo e dipendente da GPU) | ✓ Good — UI iterata rapidamente senza build Rust; seam FRB-09 funzionò con una riga |
+| Yaru come design system | Aspetto coerente su Linux/macOS/Windows; theme chiaro/scuro built-in | ✓ Good — design system completo con YaruPasswordField e YaruExpansionPanel |
+| Temp dir per output immagini | Evita di sporcare il filesystem dell'utente; path puliti e prevedibili | ✓ Good — lifecycle con session UUID; cleanup crash sessions all'avvio |
+| Sottocartella /gui nel monorepo | Un unico git, dipendenza Rust sempre aggiornata, CI unificato | ✓ Good — path dep su diffusion-rs sempre in sync |
+| gui/rust/ isolato da root workspace | Evita trigger build CMake/GPU quando non necessario | ✓ Good — empty [workspace] in Cargo.toml; nessun side effect sul root workspace |
+| GenerationService abstract seam | Single provider swap per Phase 2 (D-08) | ✓ Good — FRB-09 completato sostituendo una riga in generation_provider.dart |
+| Exhaustive match arms nel bridge Rust | Compiler error su nuovi preset non mappati | ✓ Good — compile-time safety garantita quando diffusion-rs aggiunge preset |
+| Cargokit package name = pod target name | Cargokit costruisce artifact path da package name; deve coincidere con pod target | ✓ Good — `rust_lib_diffusion_rs_gui` corretto; build fallisce altrimenti |
+| previewBytes in-memory in GenerationState | Evita I/O file per ogni preview step | ✓ Good — Uint8List? in GenerationState; Image.memory nel pannello |
+
+---
+*Last updated: 2026-06-23 after v1.0 milestone*

.planning/RETROSPECTIVE.md

@@ -0,0 +1,61 @@
+# Retrospective: diffusion-rs GUI
+
+---
+
+## Milestone: v1.0 MVP
+
+**Shipped:** 2026-06-23
+**Phases:** 2 | **Plans:** 5 | **Commits:** 44
+**Timeline:** 6 days (2026-06-18 → 2026-06-23)
+
+### What Was Built
+
+1. Flutter desktop app in gui/ with two-panel Yaru layout and mock generation service (Phase 1 Plan 01, 24 min)
+2. Complete 14-field parameter form with 41-preset catalog mirroring src/preset.rs (Phase 1 Plan 02, 24 min)
+3. Session-isolated temp directory lifecycle with OS-native save flow (Phase 1 Plan 03, 7 min)
+4. gui/rust/ Cargo crate with FRB functions, GuiParams DTO, catch_unwind, Progress pub fields (Phase 2 Plan 01, 8 min)
+5. Cargokit build integration, RustGenerationService with live preview streaming, provider swap (Phase 2 Plan 02, 13 min)
+
+### What Worked
+
+- **Mock-first sequencing**: Building Phase 1 with a full mock before touching Rust was the right call. It let the form, layout, and save flow be tested end-to-end with zero build chain friction. Phase 2 was then purely about wiring, not UI iteration.
+- **GenerationService abstract seam**: The abstract `GenerationService` with `Stream<ProgressEvent> generate()` made Phase 2 trivially correct — swapping Mock to Rust was literally one line in the provider (FRB-09).
+- **Exhaustive match arms**: Using exhaustive (no catch-all) match on PresetDiscriminants in the Rust bridge gives compile-time safety when new presets are added to diffusion-rs. Zero runtime surprises.
+- **GSD workflow discipline**: The pre-planning research phase for Phase 2 surfaced the cargokit + FRB integration pattern clearly before any code was written.
+
+### What Was Inefficient
+
+- **FRB codegen in worktree**: The flutter_rust_bridge_codegen generate step requires `cargo expand` which triggers the full C++ build of stable-diffusion.cpp. This cannot run in a worktree/CI context without a full environment. Manual binding stubs were created and then regenerated after the build succeeded locally. Detected during Phase 2 UAT when the app showed a black screen (stem mismatch).
+- **Cargokit package name discovery**: The root cause of the build failure (Cargo package name `diffusion-rs-gui` vs pod target `rust_lib_diffusion_rs_gui`) required reading deep into cargokit's `build_pod.dart` and `artifacts_provider.dart` source to understand. This is a gotcha that should be documented upfront for any flutter_rust_bridge project on macOS.
+- **Missing linker flags**: `-lc++ -framework Accelerate` were not included in the initial podspec. Discovered only after the build succeeded but linking failed with undefined C++ stdlib and BLAS symbols. Should be part of any cargokit podspec that wraps a Rust crate depending on stable-diffusion.cpp.
+
+### Patterns Established
+
+- **Cargokit naming rule**: Cargo package name must equal the CocoaPods pod target name exactly (underscores, no hyphens). The pod target is `rust_lib_XXX`; the Cargo `[package] name` must be `rust_lib_XXX`.
+- **FRB stem regeneration**: After any Cargo package rename, always re-run `flutter_rust_bridge_codegen generate` to update the `stem` in `frb_generated.dart`. Stem mismatch causes a black screen (library not found) with no obvious error message.
+- **podspec linker flags for stable-diffusion.cpp**: `OTHER_LDFLAGS[sdk=macosx*]` must include `-lc++ -framework Accelerate`. Without them, hundreds of undefined symbol errors from C++ stdlib and Apple Accelerate.
+- **Two-thread StreamSink relay**: The generate_image_stream pattern — worker thread calls `gen_img_with_progress`, relay thread bridges `mpsc::Receiver<Progress>` to `StreamSink<GuiProgressEvent>` — is the correct FRB 2.x streaming idiom. `executeNormal` (not `executeStream`) handles the sink port serialization.
+- **previewBytes in-memory display**: Pass `previewBytes: Uint8List?` in state instead of writing preview to file and reading back. Cleaner and faster for per-step preview updates.
+- **DropdownButton + InputDecorator pattern**: Flutter 3.44.x deprecated `DropdownButtonFormField.value`; use `DropdownButton` inside `InputDecorator` + `DropdownButtonHideUnderline` for equivalent styling with controlled Riverpod state.
+
+### Key Lessons
+
+1. **Name your Cargo crate after the pod target from the start.** The pod target name comes from `flutter_rust_bridge_codegen integrate` and is `rust_lib_{yourname}`. Set `[package] name = "rust_lib_{yourname}"` in Cargo.toml immediately. Renaming later requires regenerating FRB bindings.
+2. **Document linker flags in the podspec template.** Every project using stable-diffusion.cpp on macOS will need `-lc++ -framework Accelerate`. Add to `rust_builder/macos/*.podspec` as part of the cargokit scaffold.
+3. **FRB codegen needs a live build environment.** The CI diff-check (FRB-08) is the right pattern, but the first generation of bindings must happen locally with a full build chain. Plan for this as a developer setup step.
+4. **catch_unwind is defense-in-depth, not the only safety.** The FRB runtime itself is resilient to errors returned as Err variants. catch_unwind guards against panics; the real reliability comes from returning proper Results from generate_image_stream.
+
+---
+
+## Cross-Milestone Trends
+
+| Metric | v1.0 |
+|--------|------|
+| Phases | 2 |
+| Plans | 5 |
+| Commits | 44 |
+| LOC (project) | ~4,782 |
+| Timeline | 6 days |
+| Requirements validated | 45/46 |
+| UAT pass rate | 15/16 (1 skipped) |
+| Build failures before green | 3 (package name, linker, FRB stem) |

.planning/ROADMAP.md

@@ -0,0 +1,29 @@
+# Roadmap: diffusion-rs GUI
+
+**Project:** diffusion-rs GUI
+**Core Value:** L'utente può configurare e avviare una vera generazione di immagini con lo stesso set di opzioni della CLI, senza aprire un terminale, con preview live aggiornata ad ogni step.
+
+---
+
+## Milestones
+
+- ✅ **v1.0 MVP** — Phases 1-2 (shipped 2026-06-23)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-2) — SHIPPED 2026-06-23</summary>
+
+- [x] Phase 1: Flutter UI Foundation (Mock Mode) — 3/3 plans — completed 2026-06-18
+- [x] Phase 2: Rust Bridge Wiring — 2/2 plans — completed 2026-06-21
+
+See `.planning/milestones/v1.0-ROADMAP.md` for full details.
+
+</details>
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Flutter UI Foundation (Mock Mode) | v1.0 | 3/3 | Complete | 2026-06-18 |
+| 2. Rust Bridge Wiring | v1.0 | 2/2 | Complete | 2026-06-21 |

.planning/STATE.md

@@ -0,0 +1,70 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: MVP
+current_phase: 02
+current_phase_name: rust-bridge-wiring
+status: shipped
+stopped_at: v1.0 milestone complete — archived 2026-06-23
+last_updated: "2026-06-24T00:00:00.000Z"
+progress:
+  total_phases: 2
+  completed_phases: 2
+  total_plans: 5
+  completed_plans: 5
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-06-23 after v1.0 milestone)
+
+**Core value:** L'utente può configurare e avviare una vera generazione di immagini con lo stesso set di opzioni della CLI, senza aprire un terminale, con preview live aggiornata ad ogni step.
+**Current focus:** Planning next milestone (run /gsd-new-milestone)
+
+## Current Position
+
+**Milestone:** v1.0 MVP — SHIPPED 2026-06-23
+**Status:** All phases complete. UAT passed (15/16, 1 skipped). v1.0 archived.
+**Progress:** [██████████] 100%
+
+## Performance Metrics
+
+**Phases complete:** 2/2
+**Plans complete:** 5/5
+**Requirements validated:** 45/46 (FORM-07 deferred to v2)
+
+## Accumulated Context
+
+### Key Decisions
+
+- flutter_rust_bridge 2.x per FFI Dart↔Rust — unica soluzione matura per desktop
+- Phase 1 mock-first per disaccoppiare sviluppo UI da build Rust/GPU
+- Yaru 6.x come design system — light/dark built-in, YaruPasswordField per token
+- Riverpod 2.x (AsyncNotifier) per state management — 4 provider: params, generation lifecycle, progress, theme
+- gui/rust/ NON membro del workspace root Cargo.toml — evita trigger build CMake/GPU
+- Cargokit package name deve corrispondere al pod target name (`rust_lib_diffusion_rs_gui`)
+- previewBytes Uint8List? in GenerationState per preview in-memory (evita file I/O)
+- Exhaustive match arms nel bridge Rust per compile-time safety su nuovi preset
+
+### Blockers
+
+None
+
+### Todos
+
+None — milestone complete. Start next milestone with /gsd-new-milestone.
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 260623-nv0 | Update GUI README with build instructions and project overview | 2026-06-23 | c47d1bd | [260623-nv0-update-gui-readme-with-build-instruction](.planning/quick/260623-nv0-update-gui-readme-with-build-instruction/) |
+| 260623-o38 | Change app titlebar title to DiffusionRS GUI | 2026-06-23 | f40c614 | [260623-o38-change-app-titlebar-title-to-diffusionrs](.planning/quick/260623-o38-change-app-titlebar-title-to-diffusionrs/) |
+| 260623-oer | Fix stale preview bug: clear preview at generation start | 2026-06-23 | fa04541 | [260623-oer-fix-stale-preview-bug-clear-preview-at-g](.planning/quick/260623-oer-fix-stale-preview-bug-clear-preview-at-g/) |
+| 260623-omk | Fix stale preview: force clear on generate (corrected ValueKey + drop gaplessPlayback) | 2026-06-23 | 6bf4f4c | [260623-omk-fix-stale-preview-force-clear-on-generat](.planning/quick/260623-omk-fix-stale-preview-force-clear-on-generat/) |
+| 260623-p1j | Fix Save button: disable when final image not ready | 2026-06-23 | 09b67f1 | [260623-p1j-fix-save-button-disable-when-final-image](.planning/quick/260623-p1j-fix-save-button-disable-when-final-image/) |
+| 260623-p67 | Fix Generate button: keep disabled during intermediate complete phases | 2026-06-23 | 27a2650 | [260623-p67-fix-generate-button-keep-disabled-during](.planning/quick/260623-p67-fix-generate-button-keep-disabled-during/) |
+| 260624-eug | genera una icona per la parte gui flutter. l'icona deve avere una fiamma rossa su background bianco | 2026-06-24 | 2c96c99 | [260624-eug-genera-una-icona-per-la-parte-gui-flutte](.planning/quick/260624-eug-genera-una-icona-per-la-parte-gui-flutte/) |