# KRA Optimize Plan — Krita .kra İthalat ve İhracat Optimizasyonu

## Hedef

Krita tarafından yazılmış/beklenen `.kra` dosyaları için hem **ihracat (export)** hem de **ithalat (import)** performansını, boyutunu ve açılış doğruluğunu optimize etmek. Ayrıca Krita’da açılan PSD-benzeri layer stillerinin (drop shadow, inner shadow, outer glow, inner glow, bevel/emboss, stroke, color/gradient/pattern overlay, satin) HCIE içinde Photoshop referansına yakın görünmesini sağlamak.

## Kapsam

- `hcie-kra/src/lib.rs` — KRA ithalatı (maindoc.xml + VERS tile decoder + layerstyles.asl)
- `hcie-kra/src/kra_saver.rs` — KRA ihracatı (maindoc.xml + VERS tile encoder + SVG shapelayer)
- `hcie-io/examples/` — referans KRA seti üreten/tune eden yeni örnekler
- Gerekirse `hcie-fx` ASL parser’ı genişletmeleri (ama `hcie-fx` locked crate; sadece gerekirse unlock)
- Gerekirse `hcie-protocol::effects::LayerEffect` renk/birim haritalamaları için eşleme güncellemeleri (locked crate; sadece gerekirse unlock)

## Bugünkü Durum

`hcie-kra` çift yönlü çalışıyor fakat birkaç zayıf noktası var:

### İthalat Zafiyetleri

1. **Tile decoder sınırlı**:
   - Sadece `LZF` ve raw tile compression destekliyor; Krita’nın bazı yeni varyantları (`DATA`, `RAW`, `RLE`, deflate, zlib, store) desteklenmiyor.
   - `parse_vers_tiles` her satırı `from_utf8_lossy` ile tarıyor; bu yavaş ve binary-tolerant değil.
   - Header parsing header string üzerinden yapılıyor; DATA offset hesabı hataya açık.
2. **Layer file discovery kırılgan**:
   - `find_layer_file` çok fazla aday suffix deniyor; `filename` bazen XML’de tam yol (`layers/xxx.png`) veriliyor, bazen de göreli.
   - VERS tile’ın `.defaultpixel` dosyası olmayınca tile tamamen 0 doluyor; default pixel hesabı hatalı.
3. **ASL layerstyle parse**:
   - `hcie_fx::parse_asl_styles` KRA’daki `layerstyles.asl` üzerinden dönüyor.
   - Renk değerleri, teknik (technique), soften, v.b. protokole aktarılıyor; bazı enum mapping’ler `format!("{:?}", ...)` ile string yapılıyor ve `hcie-engine-api` içinde tekrar parse ediliyor, bu hata kaynağı.
4. **Bellek**:
   - Her layer tam canvas boyutunda `Vec<u8>` oluşturuyor (canvas_w * canvas_h * 4). Büyük dosyalarda çok pahalı.
5. **Shape/Text layer**:
   - `vectorlayer`/`shapelayer` farkı parse edilmiyor; Krita’nın SVG layer’ları sadece `LayerType::Vector` olarak alınıyor, Krita’ya export edilirken `content.svg` yazılıyor fakat import edilirken okunmuyor.

### İhracat Zafiyetleri

1. **Tile format**:
   - Her tile 64×64, sadece LZF v1 (literaller 32 bayt) kullanılıyor; Krita 5/6 bazı durumlarda farklı tile boyutu, farklı sıkıştırma bekleyebilir.
   - Tile’lar `has_content` kontrolüyle atılıyor; default pixel dolu olmayan transparent layer’lar Krita’da eksik görünebilir.
2. **Layer attributes**:
   - `x="0" y="0"` sabit; orijinal layer offsetleri kayboluyor.
   - `parent_id` / grouplayer hiyerarşisi KRA’ya yazılmıyor.
   - `fill_opacity`, `clipping_mask`, `locked`, `collapsed` vb. XML’e aktarılmıyor.
3. **Layer styles export**:
   - `hcie-kra` layer styles ihracatı yapmıyor (`layerstyles.asl` üretilmiyor).
   - Krita’da açıldığında HCIE’de ayarlanan drop shadow / bevel emboss gibi efektler kaybolur.
4. **Sıkıştırma**:
   - Tüm ZIP içeriği `Stored` (sıkıştırılmamış). KRA dosyaları gereksiz yere büyük.

### Genel Doğruluk

- KRA ↔ HCIE ↔ PSD üçgeninde round-trip test yok.
- `hcie-fx` MAE tune scriptleri sadece PSD üzerinden çalışıyor; KRA referansları yok.

## Yapılacaklar

### Aşama 1: İthalat Optimizasyonu ve Robustluk

**Hedef:** Daha büyük, daha çeşitli KRA dosyalarını hızlı ve doğru açmak.

1. **Tile decoder yeniden yazımı**
   - `parse_vers_tiles` binary-safe hale getir: header satırlarını `
` üzerinden ayır ama ardından `DATA` sonrası binary blokları doğrudan oku.
   - `TILEWIDTH`/`TILEHEIGHT`/ `PIXELSIZE` / `DATA` parse mantığını ayrı bir `VersHeader` struct’ına çek.
   - Hatalı tile’ları atlayıp geri kalanını decode et (graceful degradation).
2. **Compression desteği genişletme**
   - `LZF` zaten var; `RAW` (literal copy) ve `RLE`-benzeri varyantları ekle.
   - Zlib/deflate tile payload’larına destek ekle (Krita 5 bazen kullanıyor).
3. **Default pixel mantığı**
   - Eğer layer’ın `.defaultpixel` dosyası yoksa ve hiç tile yoksa, layer’ı tamamen transparent kabul et; canvas boyutunda 0 buffer yerine lazy olarak bir solid renk maskesi üret.
4. **Layer file discovery hızlandırma**
   - `find_layer_file` yerine önce XML’deki `filename`’ı olduğu gibi dene, sonra normalize et.
   - `archive.file_names()` HashSet’e çevir; `O(1)` lookup.
5. **Memory optimization**
   - `Layer::from_rgba` canvas boyutunda allocate ediyor; KRA importunda bu gerekli ama sparse tile layer’lar için tile-based `LayerData` kullanmak daha iyi. Protokole dokunmadan `hcie-kra` içinde tile cache’den doğrudan `hcie-tile` formatına dönüştürme seçeneği ekle (opsiyonel).
6. **Shape/Text import**
   - `shapelayer` nodetype için SVG parse desteği ekle: `content.svg` dosyasını oku, `VectorShape` listesine çevir (basit `<path>`, `<rect>`, `<ellipse>`, `<text>` tagleri).
   - `textlayer`/`adjustmentlayer` için uygun placeholder behavior belirle (şimdilik rasterize veya skip).

### Aşama 2: İhracat Optimizasyonu ve Boyut

**Hedef:** Daha küçük, Krita uyumlu KRA dosyaları üretmek.

1. **ZIP compression**
   - `zip::CompressionMethod::Deflated` kullan; en hızlı/iyi oran için compression level 6 (Krita default).
2. **Tile sıkıştırma iyileştirmesi**
   - LZF encoder’ı daha büyük literallerle (64 bayt+) çalışacak şekilde güncelle; tekrarlayan satırlar için back-ref kullan.
3. **Layer offset ve hiyerarşi**
   - `x`, `y` değerlerini layer boundary’den hesapla ve XML’e yaz.
   - `parent_id`’ye göre `grouplayer` ve iç içe layer yapısını `maindoc.xml`’e yaz.
4. **Layer styles export (ASL üretimi)**
   - `hcie-fx` ASL writer yok. Eğer KRA’daki efektleri Krita’da görmek istiyorsak, `hcie-kra` içinde basit bir ASL binary writer implemente et veya `hcie-fx`’e yeni writer ekle.
   - Öncelik: Drop Shadow, Inner Shadow, Outer Glow, Inner Glow, Stroke, Color Overlay, BevelEmboss.
   - Her effect için UUID üret, `<layer layerstyle="{uuid}" ... />` yaz, `layerstyles.asl` olarak ZIP’e ekle.
5. **Default pixel**
   - Tamamen tek renk (solid) layer’lar için tile yerine sadece `.defaultpixel` yaz; Krita bunu destekliyor.
6. **Merged image / preview**
   - `mergedimage.png` ve `preview.png` zaten yazılıyor; preview 256×256 thumbnail olarak scale edilebilir.

### Aşama 3: Krita Efekt Doğruluğu (MAE Döngüsü)

**Hedef:** KRA formatı üzerinden Krita’ya yazılan HCIE efektleri, Krita tarafından render edilip tekrar açıldığında Photoshop referansına yakın olsun. Bu aynı zamanda HCIE’nin kendi renderer’ını da doğrulayan bir çapraz test olacak.

1. **Referans KRA seti üretimi**
   - `hcie-io/examples/generate_drop_shadow_kra_set.rs` gibi örnekler yaz.
   - Aynı parametreleri (açı, mesafe, size, spread, renk, blend) hem PSD hem KRA olarak üret; sonra Krita ve Photoshop’ta açıp transparent PNG export al.
2. **Ground-truth PNG pipeline**
   - Krita batch render için `krita --export` CLI kullanılabilir (sistemde Krita yüklüyse).
   - Eğer Krita CLI yoksa, manuel açma/kaydetme talimatları + dosya bekleyen bir `tune_mae_*_kra_grid.rs` scripti yaz.
3. **MAE tune scriptleri**
   - `hcie-io/examples/tune_mae_drop_shadow_kra_grid.rs`
   - `hcie-io/examples/tune_mae_inner_shadow_kra_grid.rs`
   - `hcie-io/examples/tune_mae_outer_glow_kra_grid.rs`
   - `hcie-io/examples/tune_mae_inner_glow_kra_grid.rs`
   - `hcie-io/examples/tune_mae_stroke_kra_grid.rs`
   - `hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs`
   - Bunlar PSD tune scriptlerinin KRA varyantları olacak; `hcie-kra::export_kra` + `hcie-kra::import_kra` + `hcie-engine-api` composite kullanarak HCIE render’ını Krita referansıyla karşılaştıracak.
4. **Teknik haritalama**
   - Krita’nın ASL/Photoshop efekt parametrelerini HCIE `LayerEffect` değerlerine doğru çevir:
     - `distance` / `size` / `spread` / `choke` aynı.
     - `angle` aynı.
     - `opacity` 0..1 ↔ Krita 0..255.
     - Renkler RGBA8, doğrudan passthrough.
     - Blend mode isimleri Krita’nın `compositeop` namespace’inden alınacak.
   - Bevel/Emboss için `style`, `technique`, `direction` enum mapping’lerini netleştir.

### Aşama 4: Test ve Validasyon

1. **Round-trip testleri**
   - `hcie-kra/tests/roundtrip.rs`: rastgele layer’ları KRA’ya yaz, tekrar oku, piksel / stil / blend / opacity / visibility eşitliğini kontrol et.
   - Büyük boyutlu (4K, çok katmanlı) test ekle.
2. **Krita açılış testi**
   - Eğer sistemde Krita varsa: `examples/verify_krita_opens.rs` ile üretilen KRA’yı Krita’da açma komutunu çalıştır ve `mergedimage.png` karşılaştır.
3. **Regresyon testleri**
   - `cargo test -p hcie-kra`
   - `cargo test -p hcie-engine-api --test visual_regression`
   - `cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture`

## Kilitleme / Unlock Notları

- `hcie-kra` şu an locked crate değil (Cargo.toml root workspace’te listeli; `AGENTS.md`’de `hcie-kra/src/*.rs` locked listesinde yok). Ancak `hcie-fx/src/parser.rs`, `hcie-protocol/src/*.rs`, `hcie-engine-api/src/*.rs` locked. Aşağıdaki durumlarda unlock gerekebilir:
  - `hcie-fx` ASL writer eklenirse: `unlock.sh hcie-fx`
  - Yeni `LayerEffect` varyant veya alan gerekirse: `unlock.sh hcie-protocol`
  - Engine API’de yeni bir import/export helper gerekirse: `unlock.sh hcie-engine-api`

## Riskler

- Krita’nın ASL formatı Photoshop’unkindan hafifçe farklı; writer yazarken Krita’nın beklediği farklılıklar (örneğin ekstra Unicode name prefix) gözden kaçabilir.
- ZIP deflated kullanmak build zamanını hafifçe artırır ama dosya boyutunu ciddi azaltır.
- Tile-based layer data geçişi protokol değişikliği gerektirebilir; bu planın ilk fazında yapılmayacak.

## Çıktılar (Deliverables)

- Optimize edilmiş `hcie-kra/src/lib.rs` ve `hcie-kra/src/kra_saver.rs`.
- Yeni `hcie-io/examples/generate_*_kra_set.rs` dosyaları.
- Yeni `hcie-io/examples/tune_mae_*_kra_grid.rs` dosyaları (örnek olarak 2-3 efekt, sonra gerisi kopyalanabilir).
- `hcie-kra/tests/roundtrip.rs` round-trip testleri.
- Güncellenmiş `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs` KRA aç/kaydet yollarında hata raporlama iyileştirmeleri (opsiyonel).
- Performans/boyut ölçüm raporu (örnek: 4K 10 layer dosyanın eski/yeni boyutu ve açma süresi).

## Öncelik Sırası

1. ZIP deflate + tile encoder iyileştirmesi (hızlı kazanım, dosya boyutu düşer).
2. Tile decoder robustluk ve hız (import hatası azalır).
3. Layer offset / grouplayer / basic attributes (doğruluk artar).
4. Layer styles export ASL writer (Krita’da efektler görünür).
5. Referans KRA setleri + MAE tune scriptleri (doğruluk ölçülebilir hale gelir).
6. Shape/Text import desteği.
7. Tile-based bellek optimizasyonu (gelecek aşama).