Frontend Becerisi

Bu beceriyi, atopile'de frontend özelliklerini oluştururken veya değiştirirken kullanın. Varsayılan hedef, extension webview'leridir (ui-server + vscode-atopile).

Hızlı Başlangıç

Bağımlılık yüklemesi:

cd src/ui-server
bun install

Frontend-only döngüsü (backend entegrasyonu olmadan):

cd src/ui-server
bun run dev
bun run test
bun run build

Webview entegrasyonu döngüsü (backend + Vite):

cd src/ui-server
./dev.sh

Extension paketleme/yükleme döngüsü:

ato dev compile && ato dev install cursor
# veya
ato dev compile && ato dev install vscode

Komut referansı:

• bun install: JS bağımlılıklarını yükleyin/senkronize edin.
• bun run dev: yerel Vite dev sunucusunu başlatın (frontend-only iterasyon).
• bun run test: yerel Vitest paketi bir kez çalıştırın.
• bun run build: yerel tsc && vite build çalıştırın.
• ./dev.sh: tarayıcıda entegrasyon testi için backend + Vite çalıştırın.
• ato dev compile: extension yapılarını derleyin (varsayılan hedef all).
• ato dev install cursor|vscode: en son derlenmiş extension .vsix yükleyin.
• ato dev ui: paylaşılan component kütüphanesi bileşenlerini gösteren bir web sayfası açın.

İlgili Dosyalar

Ana Extension Webview Uygulaması

• Kök: src/ui-server/src/
• Transport: src/ui-server/src/api/
• Global state: src/ui-server/src/store/
• Özellik hooks'ları: src/ui-server/src/hooks/
• Özellik bileşenleri: src/ui-server/src/components/
• Paylaşılan bileşenler: src/ui-server/src/components/shared/
• Yardımcı fonksiyonlar: src/ui-server/src/utils/
• Stiller/tokenlar: src/ui-server/src/styles/
• Sözleşmeler: src/ui-server/src/types/
• Testler: src/ui-server/src/__tests__/

Extension Host Köprüsü

• Kök: src/vscode-atopile/src/
• IDE komutları/webview kablolama/host entegrasyonu için kullanın.
• Çekirdek React UI mantığını bu katman dışında tutun.

Özelleştirilmiş Bağımsız Uygulama Örneği

• Kök: src/atopile/visualizer/web/src/
• Compute/canvas/worker desenleri için referans olarak kullanın.

Layout Editörü (Özelleştirilmiş)

• Kök: src/atopile/layout_server/frontend/src/
• Özelleştirilmiş layout editörü frontend'i; webview'ler için varsayılan mimari değildir.

Bağımlılar (Çağrı Siteleri)

• Extension webview'leri src/ui-server'dan oluşturulur ve src/vscode-atopile tarafından yüklenir.
• ato dev compile ve ato dev install yaygın extension geliştirici döngüsüdür.
• src/atopile/visualizer/web ayrı bir uygulamadır ve referans desenidir, varsayılan hedef değildir.

Nasıl Çalışılır / Geliştirme / Test Edilir

Tipik Değişim Yolları

Değişiklikleri kapsam içinde ve tahmin edilebilir tutmak için bu desenleri kullanın.

1. Yalnızca UI değişikliği (sözleşme değişiklikleri yok)

• components/, styles/, küçük hooks/ kullanımına dokunun
• taşıma/store karmaşıklığından kaçının (gerekli olmadığı sürece)
• tarayıcı-ilk akış + odaklanmış bileşen testleri aracılığıyla doğrulayın

2. UI + state değişikliği

• store alanları/aksiyonları/seçicileri ekleyin/ayarlayın
• yük şekli değişmediği sürece taşımayı olduğu gibi tutun
• store geçiş testleri ve UI etkileşim testleri ekleyin

3. UI + sözleşme/taşıma değişikliği

• önce Pydantic sözleşmelerini güncelleyin
• TS türlerini yeniden oluşturun
• api/ eşlemesi + store state geçişleri + UI'ı güncelleyin
• taşıma ve state testleri ekleyin, sonra tarayıcı akışı doğrulamasını yapın

Mimari Standart

Varsayılan mimari:

• Backend: FastAPI (domain, API'lar, etkinlikler)
• Frontend: React + Vite
• Gerçek zamanlı: WebSocket-ilk taşıma

Katman sınırları:

• api/: HTTP + WS taşıması ve yük eşlemesi
• store/: yazılı uygulama state'i, aksiyonları, seçicileri
• components/: render/oluşturma
• utils/lib: saf dönüşümler/mantık

Sözleşme Standartı (Gerekli)

Schema-ilk sözleşme iş akışı:

1. Backend Pydantic modelini tanımlayın/değiştirin.
2. Frontend TS schema/türlerini yeniden oluşturun.
3. Oluşturulan türleri kullanan frontend taşıması/store/bileşenleri güncelleyin.
4. Değişen sözleşme davranışı için testleri ekleyin/güncelleyin.

Yapmayın:

• oluşturulan türler varsa yinelenen el yazısı arayüzleri korumayın
• yazılı sözleşmeler varken string tabanlı protokol yükleri kullanmayın

Tek Akış Kuralı (Gerekli)

Özellik başına bir kanonik kullanıcı akışı uygulayın.

Fallback akış dalları eklemeyin. Bağımlılık/state kullanılamıyorsa, aynı akış bağlamında açık bir dur-state hatası gösterin.

WebSocket Standartı

WebSocket'i şunlar için kullanın:

• etkileşimli state senkronizasyonu
• aksiyon dispatch'i + aksiyon sonuçları
• uzun süreli iş akışı güncellemeleri

HTTP'yi şunlar için kullanın:

• bootstrap okumaları
• doğrudan idempotent okumaları
• dosya/yapı alma

Gerekli WS istemci davranışı:

• sınırlandırılmış backoff ile yeniden bağlanın
• store'da açık bağlı/bağlı olmayan state
• bekleme isteği timeout/iptal yönetimi
• yeniden bağlandıktan sonra resync

Önerilen WS istemci davranışı:

• WS bağlantısını api/ modülünde merkezi hale getirin
• ileti dekodlamayı/tür korumasını bileşenlerin dışında tutun
• yeniden bağlanma ve ayrıştırma başarısızlıkları için minimal telemetri/günlüğe kaydet
• yeniden bağlanırken eski async sonuçlara karşı korunun

Örnek zarf şekli:

type WsMessage =
  | { type: "state"; data: AppState }
  | { type: "event"; event: EventType; data: EventPayload }
  | {
      type: "action_result";
      action: string;
      requestId?: string;
      result: { success: boolean; error?: string };
    };

Yeniden Kullanım Kuralları

Yeni ilkel öğeler oluşturmadan önce:

1. src/ui-server/src/components/shared/ kontrol edin.
2. src/ui-server/src/utils/ içinde mevcut mantığı kontrol edin.
3. Compute/canvas davranışı ekliyorsanız src/atopile/visualizer/web/src/lib/ ve src/atopile/visualizer/web/src/workers/ kontrol edin.
4. Davranış IDE-host'a özgü ise, onu src/vscode-atopile/src/ içinde tutun.

Paylaşılan'a taşıyın:

• 2+ özellik yüzeyi tarafından kullanılıyorsa, veya
• tekrarlanan etkileşim semantiği çoğaltılırsa driftle olur.

Paylaşılan Varlıklar Referansı

Paylaşılan Bileşenler (ui-server)

Eşdeğerler oluşturmadan önce src/ui-server/src/components/shared/ içindeki bileşenleri yeniden kullanmayı tercih edin. Yeni bir bileşen gerekiyorsa, onu src/ui-server/src/components/shared/ içinde oluşturun ve özellikte yeniden kullanın. Mümkünse, karmaşık bileşenleri mevcut paylaşılan bileşenlerden oluşturun.

Paylaşılan Yardımcı Fonksiyonlar (ui-server)

Bu yardımcıları genişletmeyi tercih edin:

• src/ui-server/src/utils/codeHighlight.tsx
• src/ui-server/src/utils/nameValidation.ts
• src/ui-server/src/utils/packageUtils.ts
• src/ui-server/src/utils/searchUtils.ts

Özelleştirilmiş Yardımcı Referansı (visualizer)

Yararlı bağımsız referans:

• src/atopile/visualizer/web/src/lib/exportUtils.ts

En İyi Uygulamalar

Frontend Kod Kalitesi

• Katı TS ve yazılı state geçişlerini koruyun.
• Side effect'leri yaprak bileşenlerde değil taşıma/hooks'larda yalıtın.
• Seçiciler kullanın, geniş tam-store abonelikleri değil.
• Açık yükleme/hata/boş state'leri uygulayın.

Yazılı API sınırı örneği:

export async function fetchBuilds(
  projectRoot: string,
): Promise<BuildSummary[]> {
  const res = await fetch(
    `/api/builds?project_root=${encodeURIComponent(projectRoot)}`,
  );
  if (!res.ok) throw new APIError(res.status, "Failed to fetch builds");
  const data = (await res.json()) as { builds: BuildSummary[] };
  return data.builds;
}

Tasarım Sistemi

Tüm yüzeylerde uygulayın:

• host-native tipografi/renkler ilk olarak
• marka aksanları yalnızca semantik olarak yararlı yerlerde
• eksiksiz etkileşim state'leri (default/hover/focus-visible/active/disabled/loading)
• tutarlı boşluk/satır yüksekliği/tipografi ritimleri
• tokenleştirilmiş renkler/boşluk/yarıçap/z-index, ad-hoc semantik sabit kodlama yok

Tokenleştirilmiş kontrol örneği:

.btn-default {
  background: var(--accent);
  color: var(--text-on-accent);
  border: 1px solid var(--accent);
  border-radius: var(--radius-md);
  padding: 0 var(--spacing-md);
}
.btn-default:hover:not(:disabled) {
  background: var(--accent-hover);
  border-color: var(--accent-hover);
}
.btn-default:focus-visible {
  outline: 2px solid var(--info);
  outline-offset: 1px;
}
.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

Erişilebilirlik Temeli

Gerekli:

• klavye işlemi yapılabilir kontroller
• deterministik odak sırası
• ARIA yalnızca yerel semantik yetersiz olduğunda
• görünür odak state'leri
• açık/koyu modlarda okunabilir kontrast

Performans Temeli

Gerekli:

• sıcak yollarda pahalı türetilmiş veri/callback'leri eşleştirin
• drag/resize animasyon yolları için requestAnimationFrame kullanın
• ağır layout/geometry/compute işini gerektiğinde worker'a taşıyın
• aktif olay akışlarında WS güncelleme yönetimini verimli tutun

Operasyonel kontroller:

• yüksek frekanslı bileşenlerde tam-store abonelikleri önleyin
• render döngülerinde kullanılan türetilmiş koleksiyonları eşleştirin
• drag/scroll/güncelleme akışları sırasında kaçınılabilir setState zinciri olmadığını doğrulayın
• uzun süreli dönüşümleri bileşen render gövdelerinin dışında tutun

Uygulama Oyun Planları

Oyun Planı A: Yeni Extension Webview Paneli (ui-server)

1. Sözleşmeleri ekleyin/onaylayın

• backend şekli değişirse: Pydantic'i güncelleyin + türleri yeniden oluşturun

2. Taşıma eşlemesi ekleyin

• src/ui-server/src/api/ içinde veri/aksiyon yöntemleri uygulayın

3. Store state/aksiyonları ekleyin

• store'da minimal yeni alanlar/aksiyonlar ekleyin
• bileşen kullanımı için seçicileri gösterin

4. UI'ı oluşturun

• components/ içinde paneli oluşturun
• mümkün olduğunda components/shared/ ilkelleri yeniden kullanın

5. Doğrulayın

• testleri çalıştırın
• tarayıcı-ilk akışını çalıştırın
• ekran görüntüsü alın + ui günlüklerini inceleyin

Oyun Planı B: Compute/Canvas-yoğun Özellik

1. Çekirdek dönüşümleri utils/ veya özelleştirilmiş lib/ modülüne koyun.
2. Ana-thread gecikmesi görünür olursa worker offload ekleyin.
3. Render bileşenlerini ince ve eşleştirilmiş tutun.
4. Etkileşim yumuşaklığını aktif güncellemeler altında doğrulayın.

Oyun Planı C: Uzun Süreli İş Akışı UI'ı

Bir kanonik akış kullanın:

• tetikle
• sürüyor
• tamamlama veya aynı bağlamda hata

Gerekli:

• sürüyor state'i sırasında çakışan kontrolleri devre dışı bırakın
• yazılı WS etkinlikleri aracılığıyla ilerleme güncellemeleri yayın
• store'da deterministik terminal state sağlayın

Ayrıntılı Test Notları

Katman Başına Test Kapsamı

1. Unit testler

• saf utils/lib dönüşümleri

2. Store testleri

• aksiyon geçişleri ve türetilmiş seçici doğruluğu

3. Taşıma testleri

• API/WS eşlemesi, hata yönetimi, istek korelasyon davranışı

4. UI testleri

• kullanıcı etkileşimi + state rendering davranışı

5. Tarayıcı otomasyon kontrolleri

• anahtar akış etkileşimi + ekran görüntüsü + ui günlükleri

WebSocket Özellik Test Senaryoları

En azından test edin:

• ilk bağlanma yolu
• bağlantı kesilmiş state güncellemesi
• yeniden bağlanma ve resync yolu
• bekleme isteği timeout/iptal yolu

Önerilen:

• geç veya yinelenen olay toleransı
• UI crash olmadan kötü biçimlendirilmiş ileti yönetimi

Test Standartı

Özellik başına minimum:

1. Store/aksiyon testi
2. API/taşıma testi
3. UI etkileşim testi
4. Hata/yükleme/boş-state testi

Örnek matris (build sırası):

• store: sıraya al + geçişleri tamamla
• API: build start hatası -> yazılı API hatası
• UI: iptal tıklaması iptal aksiyonunu dispatch eder
• state: bağlantısı kesilmiş WS state'i görünür

Tarayıcı-İlk Dev Viewer Akışı (Gerekli)

Aracılar tarayıcı akışında önce kendi kendini test etmelidir:

cd src/ui-server
./dev.sh

Sonra:

1. Etkileşim akışını tarayıcı webview sayfasında doğrulayın.
2. Anahtar-state ekran görüntüleri alın.
3. UI günlüklerini inceleyin.
4. Sorunları düzeltin.
5. Tarayıcı akışı temiz olduktan sonra kullanıcıdan extension host'ta test etmesini isteyin.

İlgili sayfalar:

• http://127.0.0.1:5173/
• http://127.0.0.1:5173/log-viewer.html
• http://127.0.0.1:5173/migrate.html
• http://127.0.0.1:5173/test-explorer.html

Puppeteer + Vite Ekran Görüntüsü API'ları

Bu yerleşik dev uç noktalarını kullanın:

curl -sS -X POST http://127.0.0.1:5173/api/screenshot \
  -H 'Content-Type: application/json' \
  -d '{"path":"/","name":"default","waitMs":1200}'

curl -sS -X POST http://127.0.0.1:5173/api/screenshot \
  -H 'Content-Type: application/json' \
  -d '{"path":"/","name":"projects-expanded","uiActions":[{"type":"openSection","sectionId":"projects"}],"uiActionWaitMs":600}'

curl -sS http://127.0.0.1:5173/api/ui-logs

Otomasyon korkuluğu:

• stabil seçiciler (data-testid veya semantik roller)
• diffler için sabit viewport
• keyfi uyku yerine hazırlık tabanlı bekleme tercih edilir
• runtime hataları izin verilen listede olmadıkça hatalar olarak kabul edilir

Yapılma Tanımı

Bir özellik ancak tüm bunlar doğru olduğunda yapılmış olur:

• [ ] bir kanonik akış uygulanır (fallback dalı yok)
• [ ] sözleşme değişiklikleri Pydantic'te modellenir + oluşturulan TS tüketilir
• [ ] WS davranışı doğrulanır (bağlanma/yeniden bağlanma/resync)
• [ ] testler eklenir/güncellenir (store + taşıma + UI + state yönetimi)
• [ ] tarayıcı-ilk dev viewer kontrolleri tamamlanır
• [ ] tarayıcı doğrulaması yapıldıktan sonra kullanıcıdan extension host'ta test etmesi istenir
• [ ] derle/test komutları dokunulan uygulama için geçer
• [ ] bileşen/util yerleşimi repo yapısını ve yeniden kullanım kurallarını izler

PR Kontrol Listesi (Kopyala/Yapıştır)

- [ ] Tek kanonik akış korunur (fallback yolu eklenmemiş)
- [ ] API/WS değişiklikleri için Pydantic modelleri güncellenmiş
- [ ] Oluşturulan TS schema/türleri yeniden oluşturulmuş ve işlenmiş
- [ ] WS yeniden bağlanma/resync davranışı doğrulanmış
- [ ] Tarayıcı dev viewer akışı doğrulanmış (`./dev.sh`)
- [ ] Ekran görüntüleri + UI günlükleri gözden geçirilmiş (onaylanmamış runtime hatası yok)
- [ ] Eklenen/güncellenen: store testi, taşıma testi, UI etkileşim testi
- [ ] Tarayıcı kontrolleri yapıldıktan sonra kullanıcıdan extension host'ta test etmesi istenir