kubbebrowser/ROADMAP.md

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.