# 4K Çok Katmanlı PSD Çizim Performans Regresyonu — Plan

## Hedef
4K çözünürlükte, çok katmanlı PSD üzerine fırça/pen çizimi yapılırken yaşanan yavaşlamanın **kök nedenini** bulmak, daha önce çalışan ama sonradan bozulan/basıitleştirilen optimizasyonları **git geçmişinden geri getirmek** ve bu tür regresyonların tekrar etmesini önlemek.

## Mevcut Durum Özeti
- Kilitli engine crate'leri kullanıcı tarafından geçici olarak açıldı.
- Şu anki `main` (HEAD `dfef0de`) içinde var olan optimizasyonlar:
  - `hcie-engine-api/src/lib.rs`: `active_stroke_mask`, `composite_scratch`, `below_cache` pooling/partial update (sonradan eklenmiş).
  - `hcie-egui-app/crates/hcie-gui-egui/src/canvas/render.rs`: dirty-region texture upload.
- Ancak git geçmişi incelendiğinde daha önce var olan ama şu an eksik/zayıflamış özellikler var:
  - `hcie-composite/src/tiled.rs`: `a257e66` mesajı **"tile render iptal"** — tile rendering daha önce devre dışı bırakılmış/geri alınmış.
  - `hcie-tile/src/lib.rs`: tek commit (`6f3fe5d`) ile hiç güncellenmemiş; tile motoru eskimiş olabilir.
  - `hcie-engine-api/src/lib.rs`: sadece 2 commit; daha önce başka bir yerde/dalda (örn. `hcie-core-app` veya v3) daha gelişmiş partial composite kodu olabilir.

## Kritik Hipotezler

### 1. Daha Önce Tile Rendering Vardı, Şimdi İptal Edilmiş/Daralmış
- Commit `a257e66` ("layer visibility çözüldü . renk sorunları var, blend fx sorunlu eksik, **tile render iptal**") tiled composite üzerinde clipping mask desteği eklerken tile rendering’i kısmen iptal etmiş veya gerilemiş olabilir.
- Şu anki `hcie-composite/src/tiled.rs` hâlâ `par_chunks_exact_mut` ile her satır için thread başlatıyor; küçük dirty region’larda bu ağır.
- **Eylem:** `a257e66` öncesi ve sonrası `tiled.rs`’i karşılaştır; eksik tile fast-path’leri bul.

### 2. `hcie-tile/src/lib.rs` Eski ve Yetersiz
- `TiledLayer::update_tiles_in_region()` muhtemelen tüm tile’ları değil, sadece dirty bölgeye denk gelen tile’ları güncellemesi lazım ama implementation detaylarına bakılmalı.
- Sparse tile’ların hafıza kullanımı ve erişim deseni optimize edilebilir.
- **Eylem:** Tile update fonksiyonunu incele; gereksiz kopya ve sıfırlama varsa kaldır.

### 3. Engine API `effects_dirty` Gereksiz Set
- `stroke_to()` ve `draw_pen_segment()` her çizimde `layer.effects_dirty.store(true)` yapıyor.
- Effects olmayan layerlarda bu, sonraki composite’te effects pass’i tetikliyor; 4K’da 33MB clone + `apply_layer_effects` maliyeti.
- **Eylem:** Sadece effects/styles varsa flag set et.

### 4. Tile Cache Over-Clear
- `set_layer_opacity`, `set_layer_visible`, `set_layer_blend_mode`, `set_layer_parent` gibi değişiklikler `tile_layers.clear()` yapıyor.
- Opacity/blend/visibility sadece composite sırasında uygulanıyor; tile pikselleri değişmiyor. Tile cache’i silmek gereksiz.
- **Eylem:** Bu fonksiyonlarda `tile_layers.clear()` yerine sadece dirty flag/composite_dirty set et.

### 5. `render_composite_region` Full-Canvas Fallback
- `has_dirty && dirty.is_none()` durumunda tüm canvas dirty işaretleniyor.
- `stroke_to` içinde `expand_dirty` çağrılmadığı veya yanlış çağrıldığı için partial region kayboluyor olabilir.
- **Eylem:** `stroke_to` içinde dirty bounds genişletmeyi doğrula; fallback neden oluşuyor bul.

### 6. `below_cache` Her `begin_stroke`’ta Yeniden Hesaplanıyor
- Aktif layer en üstteyse her stroke başlangıcında N-1 katman full composited.
- Alt katmanlar değişmediyse `below_cache` reuse edilebilir.
- **Eylem:** Alt katmanlarda değişiklik olmadıkça `below_cache`’i yeniden hesaplama.

### 7. GUI Tarafında Thumbnail + Selection + Pointer Downsampling
- `canvas/render.rs` her karede dirty layer thumbnail’larını yeniliyor.
- `draw_selection_overlay` her karede tüm canvası (4K ≈ 8M piksel) tarıyor.
- Tablet/winit yüksek frekanslı event’ler smoothing yapılmadan engine’e gönderiliyor.
- **Eylem:** Thumbnail cache, selection edge cache, pointer distance threshold ekle.

## Yapılacaklar

### A. Git Geçmişi Arkeolojisi
1. `a257e66` öncesi `hcie-composite/src/tiled.rs` halini çıkar (`git show a257e66^:hcie-composite/src/tiled.rs`).
2. `6f3fe5d` sonrası `hcie-tile/src/lib.rs` değişiklikleri ara; varsa branch/stash geçmişinde daha gelişmiş versiyon olup olmadığını kontrol et.
3. `hcie-core-app` geçmişinde (silinmiş dizin) tile rendering / GPU acceleration / partial update kodu araştır.
4. `hcie-engine-api-orig` crate’ini incele; orijinal engine API’de daha iyi partial composite var mı?
5. Eski iyi hal ile şu anki hal arasındaki farkları listele.

### B. Kök Neden Tespiti
1. `hcie-engine-api/src/lib.rs` içine detaylı TRACE logları ekle:
   - `render_composite_region` giriş/çıkış süresi, dirty rect boyutu, cache hit/miss.
   - `begin_stroke` below_cache build süresi.
   - `sync_dirty_tiles` süresi ve kaç layer/tile güncellediği.
   - effects pass tetiklenip tetiklenmediği, neden tetiklendiği.
2. `hcie-composite/src/tiled.rs` içine TRACE ekle:
   - tile path vs dense path seçimi, region boyutu, thread path seçimi.
3. Kullanıcıdan `RUST_LOG=trace` ile 10 saniyelik çizim oturumu logu al.
4. Log analizi ile en ağır maliyetli bölgeyi tespit et.

### C. Eski İyi Optimizasyonları Geri Getir
1. `hcie-composite/src/tiled.rs` içindeki tile fast-path’i güçlendir:
   - Küçük region’larda sequential path seç.
   - Clipping mask lookup’u layer başına bir kez ön hesapla.
   - Effects olan layerlar için `effects_cache` reuse et.
2. `hcie-tile/src/lib.rs` tile update’ini optimize et:
   - Sadece dirty bölgeye denk gelen tile’ları güncelle.
   - Gereksiz dense→tile kopya ve sıfırlama varsa kaldır.
3. `hcie-engine-api/src/lib.rs` içinde:
   - `effects_dirty` yalnızca effects/styles varsa set et.
   - `set_layer_opacity/visible/blend_mode/parent` içinde `tile_layers.clear()` kaldır.
   - `below_cache` alt katman değişmedikçe reuse et.
   - `render_composite_region` full-canvas fallback nedenlerini ortadan kaldır.
4. `hcie-brush-engine` / `hcie-draw` içinde geçici allocation varsa azalt.

### D. GUI Optimizasyonları
1. Layer thumbnail cache: `AppDocument` içinde dirty flag tut, sadece değişiklikte yenile.
2. Selection overlay edge cache: mask değiştiğinde marching-ants edge listesi hesapla.
3. Pointer downsampling: iki `stroke_to` arası minimum mesafe koşulu.

### E. Regresyon Önlemleri
1. Performans regresyon testi ekle:
   - `hcie-engine-api/tests/performance_stroke_4k.rs`: 3840×2160, 10 katman, 100 stroke segment, `stroke_to` + `render_composite_region` süre ölçüm.
   - CI threshold olmadan, manuel karşılaştırma için log çıktısı.
2. Pre-commit/post-commit hook’lara opsiyonel benchmark adımı ekle:
   - `logs/functional_regression_check.sh --benchmark` modu.
3. AGENTS.md / plan dosyasına kritik performans kodlarının (tile rendering, partial composite, dirty rect, effects cache, below_cache) korunması gerektiği notu ekle; gelecekteki değişikliklerde bu alanlara dokunulmadan önce review/benchmark zorunluluğu.

### F. Doğrulama
1. `cargo test -p hcie-engine-api --test visual_regression` — golden hash’ler değişmemeli.
2. `logs/functional_regression_check.sh --fast`.
3. Yeni benchmark’ı önce eski haliyle (HEAD öncesi stash veya geçici branch), sonra değişikliklerle çalıştır; kazanımı ölç.

## Uygulama Sırası
1. **Git arkeolojisi**: eski iyi kodu bul ve karşılaştır.
2. **Kök neden tanısı**: TRACE logları ve log analizi.
3. **En büyük kazanımı hedefle**: tile cache over-clear + effects_dirty fix.
4. **Tile composite engine güçlendir**: sequential small-region path + effects cache reuse.
5. **Engine below_cache reuse**.
6. **GUI thumbnail/selection/pointer optimizasyonları**.
7. **Benchmark + regresyon önlemleri**.
8. **Kilitleri geri kilitle (`./lock.sh all`)**.

## Kısıtlar
- `hcie-engine-api` public API’sini değiştirmeden optimize et; GUI kodu derlenmeye devam etmeli.
- Mevcut işlevselliği bozmadan optimize et; golden hash’ler değişmemeli.
- Her seansta en fazla 5 dosya değişikliği; fazla ise görev bölünecek.
- Değişiklikler bitince `./lock.sh all` ile kilitleri geri kilitle.

## Başarı Kriteri
- 4K çok katmanlı PSD üzerinde fırça/pen çizimi sırasında hissedilir lag azalır.
- `cargo test -p hcie-engine-api --test visual_regression` geçmeye devam eder.
- `logs/functional_regression_check.sh --fast` geçmeye devam eder.
- Performans benchmark’ında ortalama frame/segment süresi önceki haline göre düşer.
- Eski çalışan optimizasyonlar geri getirilmiş ve korunmak üzere belgelenmiştir.