kubbebrowser/github-issues.md

# GitHub Issues — abdussamedulutas/kubbe

---

## Issue #1 — ADR-001: İç modüller, artımlı derleme ve grafik doğrulama temeli

- **Durum**: OPEN
- **Etiketler**: ADR
- **Oluşturulma**: 2026-07-27T22:37:56Z
- **Güncellenme**: 2026-07-28T11:51:49Z

### Body

## Durum

Kabul edildi.

## Bağlam

Kubbe; C++22, SDL3, Skia ve ilerleyen aşamalarda V8 üzerinde gelişecek büyük bir gömülü web motorudur.
HTML, DOM, CSS, layout, grafik, JavaScript ve WASM gibi katmanların tek bir derleme ve debug birimine
dönüşmesi; geliştirme süresi ilerledikçe gereksiz yeniden derlemelere ve hataların kaynağının
belirlenmesinde zorluklara yol açacaktır.

## Karar

Kubbe ana kod tabanı iç modüllere ayrılacaktır. Her modül kendi CMake hedefine sahip olacak ve
yalnızca doğrudan bağımlı olduğu diğer modülleri include edebilecektir. Her modülün kendine ait
bir test hedefi bulunacaktır. Grafik çıktısı gerektiren modüllerin testleri, mevcut sistemde
bir SDL penceresine ve GPU'ya ihtiyaç duymadan, CPU üzerinde Skia'nın raster backend'ini
kullanarak framebuffer dizisine çizecek ve referans görüntülerle karşılaştırma yapacaktır.

İlk modül yapısı:

```
kubbe/
├── modules/
│   ├── platform/  (SDL3 pencere, olaylar, yüzey)
│   ├── gfx/       (Skia GPU context yönetimi, swapchain)
│   └── paint/     (CSS stil temel şekilleri, gradient, border)
├── tests/
│   ├── platform-test/
│   ├── gfx-test/
│   └── paint-test/
└── main/
    └── main.cpp   (yalnızca startup, event loop, cleanup)
```

Her test hedefi, modülle aynı CMakeLists.txt içinde `add_test` ile kaydedilecek ve
`ctest` ile çalıştırılabilecektir.

İlk uygulanacak iş SDL3 pencere döngüsü ve Skia çizim köprüsüdür. Hedef: C++22 tabanlı
minimal `main.cpp`, boş pencere, event loop, kırmızı dikdörtgen renderı ve temiz shutdown
akışı. HTML/DOM/CSS/V8 katmanlarına şimdilik girilmeyecek.

## Test ve debug ilkesi

- Her modül ana tarayıcı çalıştırılmadan test edilebilecek.
- Parser ve layout gibi deterministik katmanlar metinsel/strüktürel golden testlerle sınanacak.
- Grafik katmanı sabit sahneleri framebuffer veya ekran görüntüsüne çizerek referans
  görüntülerle karşılaştırılacak.
- GPU doğrulama katmanları, sanitizers ve sembollü debug build'leri geliştirme sürecinin
  parçası olacak.
- Modüller arası bağımlılıklar tek yönlü ve build sistemi tarafından görünür tutulacak.

## Sonuçlar

Bu karar runtime plugin sistemi getirmez. Kazanım; değişmeyen kodun yeniden derlenmemesi,
her katmanın ayrı çalıştırılıp gözlemlenebilmesi ve hatanın ait olduğu modülün daha erken
belirlenebilmesidir. İç API değişiklikleri bağımlı hedefleri yeniden derletebilir; bu kabul
edilen bir maliyettir.

### Comments

**abdussamedulutas** (2026-07-28T11:37:18Z):
Bu issue için ilk uygulanacak iş SDL3 pencere döngüsü ve Skia çizim köprüsüdür.
Hedef: C++22 tabanlı minimal main.cpp, boş pencere, event loop, kırmızı dikdörtgen renderı
ve temiz shutdown akışı. HTML/DOM/CSS/V8 katmanlarına şimdilik girilmeyecek.

---

## Issue #2 — Analiz: Skia, SDL3, GPU backendleri ve geliştirme ortamı

- **Durum**: OPEN
- **Etiketler**: analiz
- **Oluşturulma**: 2026-07-28T12:08:52Z
- **Güncellenme**: 2026-07-28T12:08:52Z

### Body

## Amaç

Skia'nın SDL3, OpenGL ve Vulkan ile ilişkisini; modern CSS çizimleri için yeterliliğini
ve mevcut geliştirme ortamının Kubbe'nin derleme/debug ihtiyaçlarına uygunluğunu kaydetmek.

## 1. SDL3, Skia ve GPU API'lerinin görevleri

SDL3 ve Skia birbirinin alternatifi değildir:

```
SDL3
├── pencere ve platform yaşam döngüsü
├── klavye/fare olayları
└── OpenGL context veya Vulkan surface

Skia
├── şekil, path, görüntü ve glyph çizimi
├── gradient, blend, blur ve filtreler
├── CPU rasterizasyonu
└── OpenGL/Vulkan üzerinde GPU rasterizasyonu
```

Bağlantı katmanları:

```
SDL_Window
    ↓
OpenGL context veya Vulkan surface/swapchain
    ↓
Skia GPU context
    ↓
SkSurface → SkCanvas
    ↓
CSS paint komutları
```

Skia'nın doğrudan SDL backend'i yoktur. SDL pencereyi ve işletim sistemi bağlantısını sağlar;
Skia, bu pencereye ait OpenGL/Vulkan render target'ına çizim yapar.

### OpenGL yolu

- SDL OpenGL context oluşturur ve aktif hale getirir.
- Skia mevcut OpenGL context üzerinde GPU context oluşturur.
- Skia çizimi tamamladıktan sonra SDL buffer swap ile kareyi gösterir.

### Vulkan yolu

- SDL platforma uygun `VkSurfaceKHR` oluşturur.
- Vulkan instance, physical device, logical device, queue ve swapchain Kubbe tarafından yönetilir.
- Swapchain image Skia `SkSurface` nesnesine bağlanır.
- Skia çizimi üretir; senkronizasyon ve present işlemini Kubbe tamamlar.

## 2. Modern CSS çizimleri için Skia'nın yeterliliği

Skia, Kubbe'nin paint/raster katmanı için yeterlidir. Ancak CSS ayrıştırma, layout ve CSS
semantiğini kendisi uygulamaz.

| CSS ihtiyacı | Skia yapı taşı |
|---|---|
| Background ve border | Rect, rounded rect ve path |
| `border-radius` | Rounded rect/path |
| `linear-gradient` | Linear gradient shader |
| `radial-gradient` | Radial gradient shader |
| `conic-gradient` | Sweep gradient shader |
| Repeating gradient | Tile mode ve koordinat dönüşümü |
| `box-shadow`, `text-shadow` | Mask/image filter ve blur |
| Opacity | Alpha ve save layer |
| CSS transforms | Matrix |
| `clip-path` | Path ve clipping |
| Blend/compositing | `SkBlendMode` |
| Görseller | `SkImage` |
| Özel karmaşık efektler | SkSL runtime shader |

Kubbe'nin kendisinin uygulaması gerekenler:

- CSS gradient sözdizimi ve color-stop hesapları
- CSS renk uzayı ve interpolation kuralları
- Layout koordinatları ve paint sırası
- Background/border katmanları
- CSS clipping ve compositing semantiği
- Device scale factor ve piksel hizalaması

## 3. Yerel geliştirme ortamı

Denetim tarihi: 28 Temmuz 2026.

### Toolchain

| Bileşen | Mevcut durum |
|---|---|
| İşletim sistemi | Manjaro Linux, x86-64, kernel 7.1.3 |
| GCC/G++ | 16.1.1 |
| GNU Make | 4.4.1 |
| CMake | 4.3.4 |
| Ninja | 1.13.2 |
| Clang | 22.1.6 |
| GDB | 17.2 |
| clang-tidy | 22.1.6 |
| llvm-symbolizer | 22.1.6 |
| SDL3 | 3.4.12 |
| Vulkan loader/headers | 1.4.350 |
| OpenGL | 4.6 |
| shaderc | 2026.2 |

### Sanitizer doğrulaması

Geçici bir C++23 probe hem GCC hem Clang ile `-fsanitize=address,undefined` kullanılarak
derlendi.

- ASan kasıtlı heap-buffer-overflow'u doğru dosya ve satır bilgisiyle yakaladı.
- UBSan kasıtlı signed integer overflow'u doğru dosya ve satır bilgisiyle yakaladı.

Sonuç: ASan ve UBSan mevcut ortamda bugün kullanılabilir durumdadır.

### Donanım

| Bileşen | Durum |
|---|---|
| CPU | Intel Core i5-10200H, 4 çekirdek/8 thread |
| RAM | 15 GiB |
| Swap | 32 GiB |
| Boş disk | Yaklaşık 294 GiB |
| Dahili GPU | Intel UHD Graphics, OpenGL 4.6 |
| Harici GPU | NVIDIA GTX 1650 Ti 4 GiB, Vulkan 1.4/OpenGL 4.6 |

## 4. Eksik veya daha sonra eklenecek araçlar

Mevcut denetimde bulunmayanlar:

- Skia build çıktısı
- `ccache`
- LLD
- LLDB
- `VK_LAYER_KHRONOS_validation`
- RenderDoc
- `perf`
- Valgrind
- Xvfb/Weston headless test ortamı

## 5. Projeye özel ve portable debug toolchain

Önerilen build dizinleri:

```
out/debug/
out/asan-ubsan/
out/tsan/
out/release/
```

## Sonuç

- Skia, modern CSS paint/raster ihtiyaçları için uygun temel motordur.
- SDL3, Skia'nın alternatifi değil; pencere ve platform köprüsüdür.
- OpenGL ve Vulkan birlikte desteklenebilir; backend seçimi soyutlanmalıdır.
- Mevcut sistem Kubbe geliştirmeye uygundur ve ASan/UBSan fiilen doğrulanmıştır.
- Skia ile Vulkan validation layer ilk grafik milestone'undan önce hazırlanmalıdır.