# Plan: Meadow Brush Geometry + Color Variant

## Context

HCIE-Rust v4 brush engine’inde `BrushStyle::Meadow` mevcut implementasyonu sadece 3 dikey nokta/dab çiziyor; hedefteki gibi kıvrımlı, farklı açılı, farklı uzunlukta çimen yaprağı demetlerine benzemiyor. Ayrıca kullanıcı, seçilen ana renkin yakınında benzer ama farklı renklerle çizim yapan bir **Color Variant** parametresi istiyor.

## Decisions

| # | Decision | Rationale |
|---|----------|-----------|
| 1 | `color_variant: bool` ve `variant_amount: f32` alanları `BrushTip` içinde **genel** olarak eklenecek. | İleride Leaf, Tree gibi doğal brush’lara kolayca açılabilir; UI başta sadece Meadow için gösterilecek. |
| 2 | Renk varyasyonu **HSL tabanlı** olacak. | Ana renk ailesi korunur: yeşil → farklı yeşiller, mor → farklı morlar. RGB ofsetle kirlenme/gri kayma olmaz. |
| 3 | `variant_amount ∈ [0, 1]`. `amount = 0` hiç varyasyon yok; `amount = 1` için maksimum **±60° hue**, **±40% lightness** sapma. Ara değerler lineer. | Kullanıcıya sezgisel, sınırsız renk ailesi içinde kontrol sunar. |
| 4 | Meadow her stamp (dab) için 7–12 adet kıvrımlı çimen yaprağı çizecek. | Hedef görseldeki doğal, değişken çimen demetini yakalar. |
| 5 | Her yaprağın başlangıç açısı yukarı (−90°) etrafında ±45° rastgele sapacak; uzunluk `0.3 .. 1.1 * effective_size`; kalınlık kökte ~0.15×size, uçta ~0.03×size; quadratic bezier ile 2–3 segment. | Farklı açı, uzunluk ve eğri her stamp’ı benzersiz kılar. |
| 6 | Her yaprağın opasitesi ve rengi ayrı ayrı varyasyonlu olacak. | Tek tip “matbaa” hissi önlenir. |
| 7 | GUI’de Color Variant kontrolleri sadece **Meadow brush aktifken** gösterilecek. | Risk azaltılır, diğer brush’lara sonradan genişletilebilir. |
| 8 | `meadow_grass` preset’i `color_variant: true`, `variant_amount: 0.5` ile güncellenecek. | Kullanıcı varsayılan olarak hedef görsele yakın sonuç alır. |

## Affected Files

1. `hcie-protocol/src/lib.rs` — `BrushTip` struct: `color_variant`, `variant_amount` alanları + `Default`.
2. `hcie-protocol/src/tools.rs` — opsiyonel; değişiklik yok (alanlar zaten `BrushTip` içinde).
3. `hcie-brush-engine/src/lib.rs` — `BrushTip` mirror struct; `draw_meadow_brush` yeniden yazımı; HSL varyasyon helper; `Default` güncellemesi.
4. `hcie-brush-engine/src/presets.rs` — `meadow_grass()` default’ları.
5. `hcie-engine-api/src/dynamic_loader.rs` — `hcie_protocol::BrushTip` ↔ `hcie_brush_engine::BrushTip` dönüşümü.
6. `hcie-engine-api/src/lib.rs` — yeni alanların default/senkronizasyonu (gerekirse).
7. `hcie-egui-app/crates/hcie-gui-egui/src/app/panels.rs` — UI: Meadow aktifken “Color Variant” checkbox + “Variant Amount” slider.
8. `hcie-egui-app/crates/hcie-gui-egui/src/canvas/mod.rs` — brush tip senkronizasyonuna yeni alanları ekle.
9. `hcie-egui-app/crates/hcie-gui-egui/src/app/brushes_panel.rs` — preview’a varyasyon yansıması isteğe bağlı.

## Implementation Tasks

1. **Protocol layer:** `hcie-protocol/src/lib.rs` `BrushTip` içine ekle:
   ```rust
   pub color_variant: bool,
   pub variant_amount: f32,
   ```
   Default: `false`, `0.0`. Serde `default` desteği eski kayıtlı presetlerle uyumluluğu korur.

2. **Brush engine struct:** `hcie-brush-engine/src/lib.rs` `BrushTip` mirror struct’ına aynı alanları ekle ve `Default` güncelle.

3. **Meadow brush renderer:** `draw_meadow_brush` fonksiyonunu yeniden yaz:
   - `effective_size = size * pressure`
   - `blade_count = 7..12` rastgele
   - Her yaprak için:
     - base angle = −π/2 + rng.gen_range(−π/4 .. π/4)
     - length = effective_size * rng.gen_range(0.3 .. 1.1)
     - bend = rng.gen_range(−0.3 .. 0.3) * length
     - thickness root = effective_size * 0.15, tip = effective_size * 0.03
     - quadratic bezier: `base → control → tip`, 3–5 segmentle draw_dab zinciri
     - op = particle_opacity * rng.gen_range(0.6 .. 1.0)
     - renk: eğer `color_variant` true ise `variant_amount`’a göre HSL varyasyon; yoksa `color`

4. **HSL varyasyon helper:** RGB → HSL → hue/lightness rastgele sap → HSL → RGB. Basit bir implementasyon yeterli (doğrusal interpolasyonlu basit HSL). Helper: `vary_color(color: [u8;4], amount: f32, rng: &mut R) -> [u8;4]`.

5. **Dynamic loader dönüşümü:** `hcie-engine-api/src/dynamic_loader.rs` `draw_brush_stroke` içinde `color_variant` ve `variant_amount` alanlarını kopyala.

6. **Preset:** `hcie-brush-engine/src/presets.rs` `meadow_grass()`:
   - `tip.color_variant = true`
   - `tip.variant_amount = 0.5`

7. **GUI Properties panel:** `hcie-egui-app/crates/hcie-gui-egui/src/app/panels.rs` `Tool::Brush` bloğunda, `state.tool_configs.brush.style == Meadow` iken:
   - Checkbox: `Color Variant` → `state.tool_configs.brush.color_variant`
   - Slider: `Variant Amount` → `state.tool_configs.brush.variant_amount`, 0.0..=1.0 (sadece checkbox true ise)

8. **GUI brush config sync:** `ToolConfigs` → `BrushConfig` içine `color_variant` ve `variant_amount` ekle (zaten `BrushTip` içinde tutuluyordu; brush config’e de kullanıcı tarafından ayarlanabilir olması için ekle). Sonra `canvas/mod.rs`’te brush tip oluştururken bu alanları aktar.

9. **Serialization/backward compatibility:** `BrushConfig` ve `BrushTip` Serde `Default` annotation’ları kontrol et; eksik alanlar 0/default olarak deserialze edilsin.

10. **Build/test:**
    - `cargo test -p hcie-brush-engine --test stamp`
    - `cargo test -p hcie-engine-api --test visual_regression`
    - `cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture`
    - `cargo build -p hcie-gui-egui`

11. **Visual validation:**
    - GUI açılışında Meadow brush seç.
    - Birkaç farklı stroke çiz; benzersiz demetler ve renk varyasyonu görülmeli.
    - F12 screenshot al (`target/screenshots/toolbox_*.png`).

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| `BrushTip` serialization format değişikliği eski kaydedilmiş custom presetleri bozar. | Serde `default` attribute ile eksik alanlar `false`/`0.0` olarak doldurulur. |
| GUI testlerinde veya canvas sync’te unutulan yeni alanlar compile hatası/varsayılan davranış yaratır. | Tüm `BrushTip` literal init yerlerini (brushes_panel, canvas, script, import) tarayıp yeni alanları ekle. |
| Meadow her dab daha fazla işlem yapar, 4K performans testini geçemez. | Önce testi çalıştır; eğer regresyon varsa yaprak sayısını ve segment sayısını sınırla veya small-region optimizasyonu koru. |
| HSL helper’ı eklenen yeni crate bağımlılığı gerektirir. | Sadece basit HSL ↔ RGB kodu yaz; dış bağımlılık ekleme. |

## Open Questions / Out of Scope

- Preview panelinde Meadow brush’ın color variant etkisini göstermek isteğe bağlıdır; ilk iterasyonda zorunlu değil.
- Renk varyasyonu ileride Leaf, Tree, Rock gibi brush’lara genişletilebilir; bu plan sadece Meadow UI gösterimini açar.
- Varyasyon algoritması hue/lightness dışında saturation varyasyonunu da içerebilir; şimdilik hue + lightness yeterli.

## Validation Criteria

- [ ] `cargo test -p hcie-brush-engine --test stamp` geçer.
- [ ] `cargo test -p hcie-engine-api --test visual_regression` geçer.
- [ ] `cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture` performans regresyonu göstermez.
- [ ] GUI’de Meadow brush ile çizilen her stroke farklı yaprak demeti görünür.
- [ ] Color Variant aktifken aynı ana renk etrafında farklı tonlar/açıklıklar görünür.
- [ ] F12 screenshot’ta doğal çimen benzeri sonuç gözlemlenir.