docs: add roadmap and V8 d8 wrapper

ROADMAP.md

@@ -0,0 +1,475 @@
+# Kubbe Roadmap
+
+Son güncelleme: 2026-07-28
+
+Kubbe, Chromium/CEF ağırlığını taşımayan, C++22 ile yazılan, SDL3 + Skia + V8 tabanlı gömülü web işleme motoru olarak tasarlanıyor. Hedef son kullanıcı tarayıcısı değil; uygulamaların içine gömülebilen, modüler, test edilebilir ve gerektiğinde ayrı executable/shared-library artifactleriyle çalışabilen bir toolbox/engine mimarisi.
+
+## Ne yaptık
+
+### Git ve repo düzeni
+
+- Git geçmişi sıfırlandı ve temiz `main` geçmişiyle remote güncellendi.
+- Büyük kaynak ağaçları doğrudan commitlenmeyecek şekilde `.gitignore` düzenlendi.
+- Şu klasörler bilinçli olarak ignore edildi:
+  - `vendor/source/`
+  - `vendor/cache/`
+  - `vendor/tools/`
+  - `vendor/work/`
+  - `out/`
+  - `.toolchains/`
+  - `spec/`
+  - `scripts/`
+  - `.codewhale/`
+- Commit batch sınırı fiilen uygulandı: 700 MiB üstü staged içerik commitlenmeyecek.
+
+### Proje iskeleti
+
+- CMake tabanlı C++ proje iskeleti oluşturuldu.
+- CMake presetleri, vendor bağlama dosyaları, compiler cache, warning ve sanitizer hazırlıkları eklendi.
+- `modules/` ve `tests/` ayrımı oluşturuldu.
+- `tools/doctor.sh` ve vendor doğrulama/script altyapısı eklendi.
+
+### Vendor kaynakları
+
+Kaynak ağaçları yerelde tutuluyor, ancak Git’e alınmıyor.
+
+- SDL3 kaynakları indirildi.
+- Vulkan headers/loader kaynakları indirildi.
+- Skia kaynakları indirildi.
+- V8 kaynakları indirildi.
+- ccache, Valgrind ve test araçları için yerel hazırlık yapıldı.
+- Vendor doğrulama script’i çalıştırıldı ve vendor setinin yerelde var olduğu doğrulandı.
+
+### Derlenmiş artifactler
+
+Derlenmiş çıktılar kaynak ağaçlarının dışına, `vendor/artifacts/` altına taşındı ve Git’e alındı.
+
+Mevcut artifact boyutları:
+
+- `vendor/artifacts/sdl`: yaklaşık 8.5 MiB
+- `vendor/artifacts/vulkan`: yaklaşık 40 MiB
+- `vendor/artifacts/skia`: yaklaşık 36 MiB
+- `vendor/artifacts/v8`: yaklaşık 233 MiB
+
+Tamamlanan artifact commitleri:
+
+- `719abce` — SDL3 ve Vulkan artifactleri
+- `d3d1643` — Skia shared artifact
+- `d51f105` — V8 shared artifact
+
+### SDL3
+
+- SDL3 Release/shared olarak derlendi.
+- Header, shared library, CMake config ve pkg-config çıktıları `vendor/artifacts/sdl` altına paketlendi.
+
+### Vulkan
+
+- Vulkan headers kuruldu.
+- Vulkan loader Release olarak derlendi.
+- Header, loader shared library ve CMake config çıktıları `vendor/artifacts/vulkan` altına paketlendi.
+
+### Skia
+
+- Skia Release/component build olarak derlendi.
+- OpenGL, EGL, Vulkan, X11, SVG ve PDF destekleri açık derlendi.
+- `libskia.so`, public include dosyaları ve build argümanları `vendor/artifacts/skia` altına paketlendi.
+- Not: Skia şu an bazı sistem kütüphanelerine dinamik bağlıdır. Tam taşınabilir paket için ileride fontconfig/freetype/png/jpeg/webp/harfbuzz vb. bağımlılık stratejisi ayrıca kararlaştırılacak.
+
+### V8
+
+- V8 Release/component build olarak derlendi.
+- `d8` hedefi başarıyla üretildi.
+- V8 sandbox gereksinimi nedeniyle bundled libc++ ile derlendi.
+- V8 tarafında standart release özellikleri varsayılan olarak açık kabul edilecek; JIT, Maglev, Sparkplug, TurboFan, Wasm ve modern ECMAScript özellikleri bilinçli bir karar olmadan kapatılmayacak.
+- Runtime test yapıldı:
+  - `vendor/artifacts/v8/bin/d8 -e 'console.log("kubbe-v8-ok")'`
+  - Çıktı: `kubbe-v8-ok`
+- `libv8.so`, V8 yardımcı shared libraryleri, `d8`, headerlar, ICU data ve snapshot dosyaları `vendor/artifacts/v8` altına paketlendi.
+
+## Ne yapmadık
+
+### Henüz motor kodu yazmadık
+
+Şu aşamada bilinçli olarak `main.cpp` veya rendering loop kodu yazılmadı. Önce ağır altyapı ve vendor/artifact stratejisi sabitlendi.
+
+Henüz yapılmayanlar:
+
+- SDL3 pencere açma kodu
+- OpenGL/Vulkan context kurulumu
+- Skia surface/context bağlama
+- Kırmızı dikdörtgen smoke test’i
+- Event loop ve kapanma sinyali yönetimi
+
+### HTML/CSS/DOM katmanlarına başlamadık
+
+Alt seviye piksel/render köprüsü kurulmadan üst katmanlara girilmeyecek.
+
+Henüz yapılmayanlar:
+
+- HTML tokenizer
+- DOM node modeli
+- CSS parser
+- CSS cascade/computed style
+- Flexbox layout
+- Grid layout
+- Painting pipeline
+- Hit testing
+- Event dispatch
+- JavaScript DOM binding
+
+### V8 entegrasyonu yapılmadı
+
+V8 derlendi ve paketlendi, ancak Kubbe koduna bağlanmadı.
+
+Henüz yapılmayanlar:
+
+- CMake tarafında V8 import target doğrulaması
+- Minimal V8 embed smoke test
+- Isolate/context lifecycle
+- C++ object ↔ JavaScript wrapper modeli
+- DOM binding stratejisi
+- Script execution scheduling
+
+### Skia entegrasyonu yapılmadı
+
+Skia derlendi ve paketlendi, ancak Kubbe runtime’a bağlanmadı.
+
+Henüz yapılmayanlar:
+
+- OpenGL/Vulkan backend seçimi
+- SDL3 native window handle alma
+- Skia GPU context kurulumu
+- Render surface lifecycle
+- Resize handling
+- Frame begin/end/discard akışı
+
+### Modül mimarisi henüz uygulanmadı
+
+Modüler build hedefi kabul edildi, ancak kod tarafında uygulanmadı.
+
+Henüz yapılmayanlar:
+
+- Her ana modülün ayrı shared library/executable olması
+- İç modüller arası link/import düzeni
+- Test edilebilir modül sınırları
+- Runtime plugin ABI tasarımı
+- Debug symbol/symbol visibility politikası
+
+Not: Kubbe modülleri dış dünyaya public plugin sistemi olarak açılmayacak. Modüller Kubbe’nin iç parçaları olacak; aynı versiyonda birlikte değişebilirler.
+
+### Spec kaynakları Git’e alınmadı
+
+WHATWG HTML, WHATWG DOM ve Servo gibi referans kaynaklar çalışma materyali olarak düşünülüyor. Bunların tam kaynak ağaçları Git’e alınmadı.
+
+Sebep:
+
+- Repo boyutunu kontrol altında tutmak.
+- Kubbe kodu ile referans/spec kaynaklarını karıştırmamak.
+- İleride spec kaynakları için ayrı fetch/update mekanizması kullanmak.
+
+## Mimari hedefler
+
+### Genel yön
+
+- C++22
+- CMake + Ninja öncelikli build
+- Modüler shared-library/executable artifact yaklaşımı
+- Her aşama kendi içinde test edilebilir olacak
+- Önce pencere/grafik/piksel güvenilirliği, sonra HTML/CSS/JS
+- Modern standartlara odaklanma:
+  - modern HTML
+  - modern DOM
+  - modern CSS
+  - flexbox
+  - grid
+  - gradient, border radius, transform, opacity gibi pratik çizim ihtiyaçları
+
+### Başlangıç ilkesi
+
+İlk gerçek motor kodu şu işi yapmalı:
+
+1. SDL3 başlat.
+2. Boş pencere aç.
+3. OpenGL veya Vulkan context kur.
+4. Skia’yı bu context’e bağla.
+5. Ekrana kırmızı bir dikdörtgen çiz.
+6. Sonsuz event loop içinde pencere kapanma sinyalini dinle.
+7. Temiz kapan.
+
+Bu aşama geçmeden HTML, CSS veya V8 entegrasyonuna geçilmeyecek.
+
+## Yakın plan
+
+### Faz 0 — Build ve artifact doğrulama
+
+Amaç: Vendor artifactlerinin Kubbe CMake projesi tarafından doğru import edildiğini kanıtlamak.
+
+Yapılacaklar:
+
+- SDL3 import target doğrulaması.
+- Vulkan import target doğrulaması.
+- Skia import target doğrulaması.
+- V8 import target doğrulaması.
+- `tests/vendor_smoke` altında küçük build/link testleri.
+- `LD_LIBRARY_PATH`/rpath stratejisinin netleştirilmesi.
+- Linux debug/release presetlerinin ayrıştırılması.
+
+Çıkış kriteri:
+
+- Temiz clone + artifactler ile CMake configure/build başarılı olmalı.
+- SDL3, Skia ve V8 için ayrı smoke executablelar çalışmalı.
+
+### Faz 1 — Platform ve pencere modülü
+
+Amaç: Kubbe’nin işletim sistemiyle konuşan en alt katmanını kurmak.
+
+Önerilen modül:
+
+- `modules/platform`
+
+Yapılacaklar:
+
+- SDL3 lifecycle wrapper.
+- Window abstraction.
+- Event pump.
+- Resize, close, keyboard/mouse eventlerinin temel modeli.
+- Hata/log raporlama.
+
+Çıkış kriteri:
+
+- `kubbe_platform_smoke` boş pencere açıp kapanabilmeli.
+
+### Faz 2 — Grafik backend köprüsü
+
+Amaç: SDL3 penceresi ile Skia arasında güvenilir çizim köprüsü kurmak.
+
+Önerilen modül:
+
+- `modules/graphics`
+
+Yapılacaklar:
+
+- İlk backend tercihini netleştir:
+  - kısa yol: OpenGL
+  - daha uzun vadeli yol: Vulkan
+- Skia GPU context oluşturma.
+- Surface oluşturma/yok etme.
+- Swap/present akışı.
+- Resize sonrası surface yenileme.
+- Kırmızı dikdörtgen smoke test.
+
+Çıkış kriteri:
+
+- `kubbe_graphics_smoke` pencere açıp Skia ile kırmızı dikdörtgen çizmeli.
+- Pencere kapanırken crash/leak olmamalı.
+
+### Faz 3 — Test ve debug standardı
+
+Amaç: Proje büyümeden hata yakalama alışkanlığını sabitlemek.
+
+Yapılacaklar:
+
+- ASan preset.
+- UBSan preset.
+- Debug symbol politikası.
+- ccache entegrasyonu.
+- Valgrind kullanım notları.
+- Render smoke testlerinde görüntü doğrulama yaklaşımı:
+  - framebuffer readback
+  - golden image
+  - toleranslı pixel diff
+  - headless/CI uygunluğu
+
+Çıkış kriteri:
+
+- En az bir sanitizer build çalışmalı.
+- En az bir render test otomatik doğrulanmalı.
+
+### Faz 4 — Çekirdek veri modelleri
+
+Amaç: HTML/CSS’e geçmeden önce engine iç veri modellerini ayırmak.
+
+Önerilen modüller:
+
+- `modules/base`
+- `modules/dom`
+- `modules/html`
+- `modules/css`
+- `modules/layout`
+- `modules/paint`
+- `modules/js`
+
+Yapılacaklar:
+
+- Ortak string/encoding stratejisi.
+- Arena/allocator stratejisi.
+- Node ownership modeli.
+- Error/result tipi.
+- Logging/tracing formatı.
+
+Çıkış kriteri:
+
+- Her modül tek başına build edilebilir ve minimal test edilebilir olmalı.
+
+### Faz 5 — HTML tokenizer ve DOM
+
+Amaç: Modern HTML’i bellekte DOM düğümlerine çevirmek.
+
+Yapılacaklar:
+
+- Basit tokenizer.
+- Element/text/comment node modeli.
+- Attribute modeli.
+- Minimal parser tree construction.
+- WHATWG HTML spec ile test senaryoları seçimi.
+
+Çıkış kriteri:
+
+- Basit HTML string’i parse edilip DOM ağacı snapshot olarak test edilebilmeli.
+
+### Faz 6 — CSS ve layout
+
+Amaç: DOM düğümlerini CSS kurallarına göre ölçüp konumlandırmak.
+
+Yapılacaklar:
+
+- CSS tokenizer/parser.
+- Selector matching.
+- Cascade.
+- Computed style.
+- Box tree.
+- Block layout.
+- Flexbox.
+- Grid.
+
+Çıkış kriteri:
+
+- Test HTML/CSS girdisinden beklenen box tree/layout snapshot’ı üretilebilmeli.
+
+### Faz 7 — Paint pipeline
+
+Amaç: Layout sonuçlarını Skia komutlarına çevirmek.
+
+Yapılacaklar:
+
+- Display list.
+- Background/border çizimi.
+- Text çizimi.
+- Gradient.
+- Border radius.
+- Clip.
+- Transform.
+- Opacity/layering.
+
+Çıkış kriteri:
+
+- Basit HTML/CSS dokümanı Skia ile görsel olarak çizilebilmeli.
+- Golden image testleri başlamalı.
+
+### Faz 8 — V8 binding
+
+Amaç: C++ DOM dünyasını JavaScript dünyasına bağlamak.
+
+Yapılacaklar:
+
+- V8 isolate/context lifecycle.
+- Script execution API.
+- DOM wrapper prototipi.
+- Event loop ile microtask entegrasyonu.
+- Basit `document.createElement`/`appendChild` benzeri API prototipi.
+
+Çıkış kriteri:
+
+- JavaScript kodu DOM ağacını değiştirebilmeli ve render çıktısı değişmeli.
+
+### Faz 9 — JavaScript debugging ve Inspector
+
+Amaç: Kubbe içinde çalışan JavaScript’i harici debug araçlarıyla gözlenebilir hale getirmek.
+
+Notlar:
+
+- V8 native olarak DAP sunmaz.
+- V8 tarafındaki temel debug entegrasyonu `v8-inspector` ve Chrome DevTools Protocol/CDP modelidir.
+- VS Code/DAP entegrasyonu gerekiyorsa DAP doğrudan V8’den değil, CDP ile konuşan ayrı bir debug adapter üzerinden sağlanır.
+
+Yapılacaklar:
+
+- `v8_inspector` entegrasyonunu araştır.
+- Script origin, source URL, breakpoint, pause/resume, step-over/step-into akışlarını prototiple.
+- Inspector mesajlarını taşıyacak minimal WebSocket endpoint tasarla.
+- DevTools frontend veya CDP uyumlu araçlarla bağlantı denemesi yap.
+- Event loop duraklatma/devam ettirme davranışını Kubbe runtime ile uyumlu hale getir.
+
+Çıkış kriteri:
+
+- Kubbe içinde çalışan basit bir script’e breakpoint konulabilmeli.
+- Stack trace, local/global değişkenler ve console mesajları debug aracı tarafından görülebilmeli.
+
+## Açık teknik kararlar
+
+### OpenGL mi Vulkan mı?
+
+İlk smoke test için OpenGL daha hızlı sonuç verir. Vulkan daha modern ve kontrollü yol olabilir, ancak başlangıç maliyeti daha yüksek.
+
+Pragmatik öneri:
+
+- İlk kırmızı dikdörtgen testini OpenGL + Skia ile yapmak.
+- Vulkan backend’i ikinci grafik backend olarak eklemek.
+
+### Artifact paketleme stratejisi
+
+Şu an artifactler Git’e alınıyor. Batch sınırı 700 MiB.
+
+İleride karar verilecek:
+
+- Artifactler Git içinde kalacak mı?
+- Ayrı release asset sistemi kurulacak mı?
+- Local bootstrap script artifactleri indirecek mi?
+- Platform başına artifact dizini ayrılacak mı?
+
+### Spec kaynakları
+
+Spec kaynakları çalışma referansı olarak gerekli, ancak repo içine tam kaynak olarak alınmamalı.
+
+Öneri:
+
+- `tools/spec/sync-*` scriptleri yazmak.
+- Spec kaynaklarını `spec/` altında local-only tutmak.
+- Gerekli notları/çıkarımları Kubbe dokümanlarına taşımak.
+
+### Modül sınırları
+
+Her modül ayrı derlenebilir olmalı, ancak dışarıya stabil ABI sözü verilmeyecek.
+
+Öneri:
+
+- İç modüller shared library olabilir.
+- Smoke/test executableları ayrı olmalı.
+- Ortak sembol/export politikası erken belirlenmeli.
+- Cross-module ownership mümkün olduğunca açık tutulmalı.
+
+## Kısa vadeli yapılacaklar
+
+1. `ROADMAP.md` sonrası CMake import targetlarını doğrula.
+2. SDL3 smoke executable yaz.
+3. Skia + OpenGL smoke executable yaz.
+4. V8 embed smoke executable yaz.
+5. Runtime path/rpath stratejisini sabitle.
+6. ASan/UBSan presetlerini çalışır hale getir.
+7. Render output için golden image test altyapısını tasarla.
+8. İlk gerçek `main.cpp` için karar ver:
+   - sadece demo executable mı?
+   - yoksa `kubbe_shell` gibi ayrı runtime mı?
+
+## Başarı tanımı
+
+Bu roadmap’in ilk büyük kilometre taşı:
+
+- Temiz CMake build alınacak.
+- SDL3 pencere açacak.
+- Skia pencereye kırmızı dikdörtgen çizecek.
+- Event loop stabil kapanacak.
+- V8 ayrı smoke test olarak JavaScript çalıştıracak.
+- Bu üç parça birbirine karıştırılmadan test edilecek.
+
+Bu tamamlanmadan HTML/CSS/DOM/V8 binding gibi üst katmanlara geçilmeyecek.

vendor/artifacts/v8/bin/d8-wrapper

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+v8_root=$(CDPATH= cd -- "$script_dir/.." && pwd)
+
+export LD_LIBRARY_PATH="$v8_root/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+
+exec "$script_dir/d8" "$@"