From ee6ad2dc2055c52ddf9cf83011c33171112faadf Mon Sep 17 00:00:00 2001
From: Your Name <you@email.name>
Date: Fri, 24 Jul 2026 18:42:53 +0300
Subject: [PATCH] chore: configure criterion benchmarking for hcie-engine-api
 and update benchmark dependency handling

---
 criterion.md                            | 41 +++++++++++++++++++++++++
 hcie-engine-api/Cargo.toml              |  1 +
 hcie-engine-api/benches/effects_skip.rs |  2 +-
 notlar.txt                              | 14 +++++++++
 4 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 criterion.md

diff --git a/criterion.md b/criterion.md
new file mode 100644
index 0000000..cc0d05a
--- /dev/null
+++ b/criterion.md
@@ -0,0 +1,41 @@
+# Canvas Performance Regression Protection — Walkthrough
+
+HCIE v4 engine API'si üzerindeki 4K tuval optimizasyonlarının yanlışlıkla bozulmasını (regresyon) engellemek için `criterion` kütüphanesi entegre edildi ve dört kritik mekanizma için kalıcı benchmark testleri yazıldı.
+
+## Neler Yapıldı?
+
+1. **`hcie-engine-api/Cargo.toml` Güncellemesi**
+   - `criterion` kütüphanesi dev-dependency olarak eklendi.
+   - Her benchmark için özel `[[bench]]` kayıtları tanımlandı.
+
+2. **`active_stroke_mask` Pooling Koruması** 
+   - [benches/stroke_mask_pooling.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/stroke_mask_pooling.rs)
+   - Brush engine'in kullandığı ~8 MB mask buffer'ın `end_stroke()` sırasında serbest bırakılıp bırakılmadığını kontrol eder.
+   - İlk tahsis (cold) ile sonraki ardışık strokların (warm) sürelerini karşılaştırır.
+
+3. **`composite_scratch` Pooling Koruması**
+   - [benches/composite_scratch_pooling.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/composite_scratch_pooling.rs)
+   - ~33 MB composite render buffer'ın `render_composite_region()` içinde yeniden kullanıldığını doğrular.
+
+4. **`below_cache` Ardışık Stroke Reuse Koruması**
+   - [benches/below_cache_reuse.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/below_cache_reuse.rs)
+   - Aynı katmanda birden çok stroke atıldığında alttaki katmanların yeniden derlenmek yerine (cache rebuild) mevcut cache'in kullanıldığını test eder.
+   - 4K çözünürlükte, 10 katmanlı senaryoda cache build (ilk vuruş) ve cache reuse (ikinci vuruş) maliyetlerini ayırır.
+
+5. **`effects_dirty` Conditional Skip Koruması**
+   - [benches/effects_skip.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/effects_skip.rs)
+   - Efekt/stili olmayan katmanlarda pahalı effects pipeline (ve 33 MB buffer kopyası) adımının bypass edildiğinden emin olur.
+
+## Doğrulama Sonuçları
+
+- Yeni criterion testlerinin API erişimleri (özellikle `update_layer_style` fonksiyon imzası) ve bağımlılıkları derlenip onaylandı.
+- Eski golden testler olan `visual_regression.rs` çalıştırılarak yeni performans testlerinin deterministik render sonuçlarını (pixel-perfect) bozmadığı **doğrulandı** (8/8 başarılı).
+- Eski performans testi `performance_stroke_4k.rs` de sorunsuz çalıştırıldı.
+
+> [!TIP]
+> **Tüm Benchmark'ları Çalıştırmak İçin:**
+> Terminal üzerinden engine dizinine giderek şu komutu kullanabilirsiniz:
+> ```bash
+> cargo bench -p hcie-engine-api
+> ```
+> _Not: Bu testler 4K ve çok katmanlı benchmarklar içerdiğinden belleği yoğun kullanır. Sonuçlar `./target/criterion/report/index.html` olarak dökülecektir._
diff --git a/hcie-engine-api/Cargo.toml b/hcie-engine-api/Cargo.toml
index d8a911d..1dcfc5c 100644
--- a/hcie-engine-api/Cargo.toml
+++ b/hcie-engine-api/Cargo.toml
@@ -34,6 +34,7 @@ usvg        = { workspace = true }
 
 [lib]
 crate-type = ["rlib", "staticlib"]
+bench = false
 
 [dev-dependencies]
 rstest = "0.23"
diff --git a/hcie-engine-api/benches/effects_skip.rs b/hcie-engine-api/benches/effects_skip.rs
index fae7203..fed8952 100644
--- a/hcie-engine-api/benches/effects_skip.rs
+++ b/hcie-engine-api/benches/effects_skip.rs
@@ -145,7 +145,7 @@ fn bench_effects_skip(c: &mut Criterion) {
                 spread: 0.0,
                 size: 10.0,
                 color: [0, 0, 0, 255],
-                blend_mode: hcie_engine_api::BlendMode::Normal,
+                blend_mode: "Normal".to_string(),
             },
         );
 
diff --git a/notlar.txt b/notlar.txt
index d6f0563..899a5a9 100755
--- a/notlar.txt
+++ b/notlar.txt
@@ -4,6 +4,19 @@ cargo run --example gui
 cargo run -p hcie-iced-gui
 cargo build -p hcie-iced-gui --bin hcie-iced
 scripts/cargo-with-build-id.sh run -p hcie-iced-gui
+#######
+criterion Benchmark
+cargo bench -p hcie-engine-api
+
+# Mevcut mükemmel performansı kalıcı bir baseline (referans) olarak kaydetmek için:
+# (Not: Hata almamak için hcie-engine-api/Cargo.toml'da [lib] altına bench = false eklendi)
+cargo bench -p hcie-engine-api -- --save-baseline gold_standard
+
+# Kaydedilen 'gold_standard' baseline'ı ile karşılaştırma (regresyon testi) yapmak için:
+cargo bench -p hcie-engine-api -- --baseline gold_standard
+
+criterion.md
+
 
 ##test
 Running the Tests Automatically
@@ -13,6 +26,7 @@ cargo test -p hcie-iced-gui -- proximate
 To run all cycle_one_ux_tests (including the new ones):
 cargo test -p hcie-iced-gui -- cycle_one_ux_tests
 
+###########
 To run the FULL test suite for the iced GUI crate:
 cargo test -p hcie-iced-gui