jskelet 0.1.1

package/docs/08-build.md

@@ -0,0 +1,366 @@
+# 08 — Build
+
+Bu belge `jskelet build`in yaptığı her işi ve sırasını anlatır: font kopyalama,
+ikon sprite üretimi, Tailwind CSS derlemesi, esbuild ile island bundle'ı, görsel
+optimizasyonu, manifest yazımı ve önceden sıkıştırma. Ayrıca hash'li varlıkların
+`asset()`/`hasAsset()` ile şablonlara nasıl ulaştığı, Tailwind'in `@source`
+direktiflerinin neden zorunlu olduğu ve opsiyonel peer bağımlılıklarının
+davranışı burada. Çıktının çalışma anında nasıl servis edildiği
+[02-mimari.md](./02-mimari.md)'de, build'i tetikleyen watch akışı
+[09-dev-araclari.md](./09-dev-araclari.md)'de.
+
+## Hat ve sırası
+
+```
+1. Fonts          config.fonts varsa
+2. Icon sprite    config.icons !== false ise
+3. CSS            styles giriş dosyası varsa
+4. Client JS      client/entries/ varsa
+5. Images         config.images !== false, watch değil ve sharp kurulu ise
+6. Manifest       .jskelet/manifest.json
+7. Precompress    watch değilse
+```
+
+Sıra rastgele değil:
+
+- **CSS ikon sprite'ından sonra gelir.** Sprite bir varlıktır ve sınıf üretmez,
+  ama manifest anahtarı verir.
+- **Precompress en sonda:** sıkıştırılacak her şey üretilmiş olmalı.
+- **Görseller watch turunda hiç çalışmaz:** `sharp` ile yeniden kodlama pahalı.
+
+Görevler yalnızca ilgili yapılandırma varsa çalışır. Font tanımlamayan bir proje
+font adımını hiç görmez; bu, "framework her projeye kendi varsayımlarını
+dayatmaz" ilkesinin build tarafındaki karşılığı.
+
+Terminal çıktısı hizalı adım satırları ve sonunda bir `output` bloğu verir: her
+varlığın ham ve brotli boyutu, büyükten küçüğe.
+
+## Manifest ve hash'li varlıklar
+
+Build çıktısı `public/assets/` altına **içerik hash'li** adlarla yazılır ve
+mantıksal ad → public URL eşlemesi `.jskelet/manifest.json` dosyasına konur:
+
+```json
+{
+  "app.css": "/assets/app.4f2a1b9c07.css",
+  "sprite.svg": "/assets/sprite.dc973997bd.svg",
+  "main.js": "/assets/js/main.9E1AB2C3.js",
+  "inter-400.woff2": "/fonts/inter-400.woff2"
+}
+```
+
+Hash sha256'nın ilk 10 hex karakteridir: çakışma için fazlasıyla yeterli ve
+dosya adlarını okunur tutuyor. Hash'li olmaları sayesinde bu dosyalara
+`Cache-Control: public, max-age=31536000, immutable` yazılabilir.
+
+### `asset(name)` ve `hasAsset(name)`
+
+Şablonlara otomatik geçer; sunucu kodunda `import { asset, hasAsset } from "jskelet"`.
+
+```ejs
+<% if (hasAsset('app.css')) { %>
+<link rel="stylesheet" href="<%= asset('app.css') %>">
+<% } %>
+```
+
+- `asset(name)` manifest'te varsa hash'li URL'i, yoksa `/assets/<name>` döner.
+- `hasAsset(name)` manifest'te olup olmadığını söyler.
+
+Build çalışmadıysa uygulama yine ayağa kalkar: `hasAsset()` false olur, layout
+stylesheet ve script etiketlerini hiç basmaz. `jskelet build` unutulduğunda hata
+yerine stilsiz ama çalışan bir sayfa görürsünüz. Manifest hiç yoksa bir kez uyarı
+basılır: `[assets] manifest yok — 'jskelet build' çalıştırın.`
+
+Manifest **dev'de her istekte** yeniden okunur (watch build hash'leri
+değiştirir), prod'da bir kez.
+
+### Watch modunda manifest tutarlılığı
+
+Watch turunda yeniden derlenen varlık yeni bir hash'e yazılıp eskisi silinir. Bu
+yüzden manifest de güncellenmek zorunda (`patchManifest`): aksi hâlde HTML
+silinmiş dosyayı isteyip 404 alır ve sayfa dev oturumunun kalanında stilsiz ya
+da JS'siz kalır. CSS ve client görevlerinin ikisi de her turda kendi anahtarını
+yamalar; diğer anahtarlar korunur.
+
+## CSS — Tailwind v4
+
+Giriş dosyası `paths.styles` (varsayılan `styles/globals.css`). Dosya yoksa adım
+uyarıyla atlanır.
+
+Boru hattı: PostCSS + `@tailwindcss/postcss` → (varsa) lightningcss ile
+minifikasyon → `writeAsset("app.css", …)`.
+
+- **PostCSS boru hattı bir kez kurulur:** Tailwind'in kendi önbelleği plugin
+  örneğinde yaşıyor; her derlemede yeniden oluşturmak watch turlarını belirgin
+  şekilde yavaşlatıyor.
+- **lightningcss opsiyoneldir:** yoksa Tailwind'in kendi çıktısı kullanılır,
+  yalnızca birkaç kB daha büyük olur.
+- Çıktı tek bir dosyadır ve layout onu render-blocking olarak yükler. Ayrı bir
+  "critical CSS" üretilmemesinin ölçüm gerekçesi
+  [02-mimari.md](./02-mimari.md)'de.
+
+### `@source` direktifleri zorunludur
+
+Tailwind v4'ün sınıf taraması `globals.css` içindeki `@source` direktiflerine
+bağlıdır. Otomatik tespit yalnızca stylesheet'in bulunduğu dizini tarar, bu
+yüzden şablonlarda geçen varyantlar (`data-[active=false]:…` gibi) **sessizce
+düşer**.
+
+```css
+@import "tailwindcss" source(none);
+
+@source "../views";
+@source "../client";
+@source "../routes";
+
+.wrapper {
+  max-width: 48rem;
+  margin-inline: auto;
+  padding-inline: 1rem;
+  padding-block: 2rem;
+}
+```
+
+`source(none)` otomatik tespiti kapatır ve taramayı tamamen açık hâle getirir.
+**Yeni bir üst dizin eklediğinizde `@source` satırını da ekleyin** — sınıfların
+"bazen çalışmaması"nın en yaygın sebebi budur.
+
+### CSS watch kapsamı
+
+Watch modunda üç hedef izlenir: stylesheet'in bulunduğu dizin, `views` ve
+`client`. Şablon ve island dosyaları da izlenir çünkü Tailwind sınıfları oradan
+geliyor; yalnızca `styles/` izlemek yeni bir utility yazıldığında rebuild
+etmezdi. Değişiklikler 120 ms birleştirilir.
+
+## Client JS — esbuild
+
+`client/entries/*.js` içindeki her `.js` dosyası bir entry'dir. Dizin yoksa ya da
+boşsa adım atlanır.
+
+esbuild ayarları:
+
+| Ayar | Değer | Sebebi |
+| --- | --- | --- |
+| `bundle`, `splitting` | `true` | Ortak modüller paylaşılan chunk'a çıkar |
+| `format` | `esm` | `type="module"` script'ler |
+| `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | ESM + dinamik import + `IntersectionObserver` island modelinin alt sınırı; daha eskisine transpile etmek çıktıyı büyütüp hiçbir ziyaretçi kazandırmıyor |
+| `minify` | `true` | — |
+| `sourcemap` | `true` | Tarayıcıda teşhis |
+| `entryNames` | `[name].[hash]` | `immutable` cache |
+| `chunkNames` | `chunks/[name].[hash]` | — |
+| `legalComments` | `none` | — |
+
+Çıktı `public/assets/js/` altına düşer ve her turda önce temizlenir.
+`browserslist` okunmaz; hedef listesi kod içinde sabittir.
+
+### `@/` alias'ı
+
+esbuild tarafında `@/` proje köküne çözülür ve uzantı tamamlama yapılır
+(`.js`, `.mjs`, `.json`, `/index.js`). Node tarafındaki `alias-hooks.mjs` ile
+aynı davranış, böylece `lib/` altındaki modüller hem sunucuda hem tarayıcıda
+aynı import stilini kullanabilir.
+
+### `clientEnv` gömülmesi
+
+Tarayıcıda `process` yoktur; sunucuyla paylaşılan modüller yine de `process.env`
+okur. `config.clientEnv` ile bildirilen anahtarlar ve `NODE_ENV` build zamanında
+tek nesne olarak define edilir, yani listede olmayan bir anahtar okunduğunda
+çökme yerine `undefined` döner. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
+
+### Manifest anahtarları
+
+Yalnızca **gerçek entry'ler** manifest'e girer: dinamik import'lar da
+`entryPoint` taşır ve filtrelenmezse her island ayrı bir manifest anahtarı
+olurdu. Anahtar dosya adının kendisidir (`main.js`, `chart.js`), değer hash'li
+URL.
+
+Bu yüzden controller `entries: ["chart.js"]` yazarken hash'i bilmek zorunda
+değildir ([05-islands.md](./05-islands.md)).
+
+### `metafile.json`
+
+esbuild metafile'ı `.jskelet/metafile.json` dosyasına yazılır; dev panelindeki
+chunk analizi giriş/çıkış kırılımını buradan okur. Yazma başarısız olursa build
+düşmez — analiz verisi en iyi çabadır. **Çalışma zamanı bu dosyaya bağımlı
+değildir.**
+
+## Fontlar
+
+`next/font/google` yerine self-host font dosyaları.
+
+Dosyalar `public/fonts/` altında **sabit isimlerle** durur (hash yok), çünkü
+`@font-face` içindeki `url()` yolları elle yazılıyor; hash'lemek her build'de
+stylesheet'i de değiştirmek zorunda bırakırdı.
+
+Dosya yoksa **bir kez** Google Fonts'tan indirilir ve **commit edilmesi
+beklenir**: build'in ağa bağımlı olması CI'da kırılgan. İndirme başarısız olursa
+uyarı basılır ve sayfa sistem font yığınına düşer — build durmaz.
+
+Yalnızca latin subset'i (`U+0000-00FF`) indirilir: diğerleri çoğu site için ölü
+ağırlık ve `unicode-range` olmadan hepsini indirmek font boyutunu katlar.
+
+Kullanımı stylesheet'te elle yazılır:
+
+```css
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/fonts/inter-400.woff2") format("woff2");
+}
+```
+
+`.woff2` uzantısı ve `/fonts/` öneki varsayılan `static` kurallarında olduğu için
+bu dosyalara otomatik olarak `immutable` cache yazılır.
+
+## İkon sprite
+
+`@phosphor-icons/core` içindeki tek tek SVG'lerden, **yalnızca kaynakta
+kullanılan** ikonlar için `<symbol>` seti üretir. Tüm seti göndermek 1500+ ikon,
+yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak 10-30 sembolde
+tutuyor.
+
+- Sembol id'si: `<kebab-ad>-<weight>`, örn. `arrow-right-bold`.
+- Paket **uygulamanın** `node_modules`'ünden çözülür (ikon seti uygulamanın
+  devDependency'si); kurulu değilse adım sessizce atlanır.
+- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`;
+  `icons.scan` ile değiştirilebilir. Taranan uzantılar: `.ejs`, `.js`, `.mjs`.
+- Ağırlıklar: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. Tanınmayan
+  bir ağırlık `regular` sayılır.
+
+### Tarama neyi bulur
+
+| Kaynaktaki biçim | Bulunur mu |
+| --- | --- |
+| `icon({ name: "ArrowRight", weight: "bold" })` | ✓ ad + ağırlık |
+| `icon({ name: cond ? "A" : "B" })` | ✓ her iki sabit ad |
+| `data-icon="flag:fill"` ya da `"data-icon": "flag:fill"` | ✓ |
+| `icon: "XLogo"` / `iconName: "XLogo"` (yapılandırma listelerinde) | ✓ ad; ağırlıklar dolaylı çağrılardan toplananlar |
+| `icon({ name: item.icon })` | ✗ ad statik görünmez |
+
+Son satır için iki güvenlik ağı var: ad taşıyan yapılandırma alanları
+(`icon: "XLogo"`) ayrıca aranır, ve development'ta `icon()` sprite'taki
+sembolleri okuyup eksik olan için tek seferlik uyarı basar:
+
+```
+[icon] sprite'ta yok: x-logo-regular — adı sabit yazın ya da
+build/tasks/icons.mjs taramasına ekleyin.
+```
+
+Bu uyarıyı görürseniz ya adı sabit yazın, ya `icons.scan` listesine ilgili
+dizini ekleyin, ya da adı bir yapılandırma alanında `icon: "XLogo"` biçiminde
+tutun.
+
+Phosphor'da bulunamayan adlar build sonunda özet olarak uyarılır:
+`N icons missing → …`
+
+## Görsel optimizasyonu
+
+`next/image` optimizer'ının build zamanı karşılığı. `public/` altındaki elle
+konmuş png/jpg dosyaları için birkaç genişlikte webp üretir ve
+`.jskelet/images.json` manifest'ine yazar. `image()` bu manifest'e bakıp
+`srcset` + intrinsic `width`/`height` ekler; çağıran taraf hiçbir şey
+değiştirmez ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
+
+- Çıktılar hash'li olarak `public/assets/img/` altına düşer, yani `immutable`
+  cache ve precompress kapsamına girerler.
+- **Kaynak dosyalar olduğu yerde kalır:** manifest'te olmayan bir görsel her
+  zaman orijinaliyle servis edilir.
+- `assets` ve `fonts` dizinleri her zaman atlanır; ek dizinler `images.skip` ile.
+- Genişlikler kaynaktan büyük olanlar elenerek kullanılır ve kaynağın kendi
+  genişliği (en fazla 1920) her zaman listeye girer. Retina ekranlarda bile
+  1920'nin üstü israf.
+- Varyant hash'i **kaynak + genişlikten** türetilir: aynı içerik her build'de
+  aynı dosya adını verir, `immutable` cache bayatlamaz.
+- Manifest'e kodlayıcı imzası yazılır (`webp-q78-e4`). Kalite ayarı değişince
+  imza da değişir ve tüm görseller yeniden kodlanır; aksi hâlde eski ayarla
+  üretilmiş çıktılar sessizce kalırdı.
+- Kaynak değişmediyse ve çıktılar hâlâ yerindeyse yeniden kodlanmaz. Büyük bir
+  `public/` dizininde bu, build süresini dakikalardan saniyelere indirir.
+- Bozuk/okunamayan tek bir görsel build'i düşürmez: uyarı basılır ve manifest'te
+  yer almadığı için orijinal dosya servis edilmeye devam eder.
+- Manifest'te artık geçmeyen eski çıktılar silinir.
+
+Bu adım `sharp` gerektirir. Kurulu değilse adım sessizce atlanır ve `image()`
+orijinal dosyaya döner. Watch turunda hiç çalışmaz.
+
+## Precompress
+
+Build çıktısı varlıkların brotli (kalite 11) ve gzip (seviye 9) kopyalarını
+üretir: `app.<hash>.css.br`, `app.<hash>.css.gz`, …
+
+- Yalnızca `public/assets/` kapsanır: oradaki dosyalar hash'li ve `immutable`,
+  yani içerikleri hiç değişmiyor ve her istekte yeniden sıkıştırmak boşa CPU.
+  Build'de bir kez kalite 11 ile sıkıştırmak hem sunucu yükünü sıfırlar hem de
+  çalışma anında göze alınamayacak bir oran verir (istek anındaki kalite 5'e
+  karşı).
+- `public/` altındaki elle konmuş dosyalar küçük ve seyrek istendiği için
+  çalışma anındaki sıkıştırmaya bırakılır.
+- Sıkıştırılan uzantılar: `.css`, `.js`, `.mjs`, `.svg`, `.json`, `.xml`,
+  `.txt`, `.map`. Zaten sıkışık formatlar (woff2, png, jpg, webp) atlanır.
+- 1 KB altındaki dosyalar atlanır: kazanç başlık maliyetini karşılamıyor.
+- Önceki turdan kalan `.br`/`.gz` kopyalar önce silinir, bayatlamasın.
+- Watch modunda çalışmaz: her değişiklikte kalite-11 brotli yavaş.
+
+Bu dosyaları `staticPrecompressed` middleware'i servis eder; kopya yoksa istek
+`express.static`e devredilir ([02-mimari.md](./02-mimari.md)).
+
+## Opsiyonel peer bağımlılıkları
+
+| Paket | Gerekli olduğu adım | Yoksa ne olur |
+| --- | --- | --- |
+| `postcss` | CSS | CSS adımı **hata verir** (zorunlu import) |
+| `@tailwindcss/postcss` | CSS | CSS adımı **hata verir** |
+| `tailwindcss` | CSS (peer) | Tailwind direktifleri çözülemez |
+| `lightningcss` | CSS minifikasyonu | Tailwind çıktısı kullanılır, birkaç kB daha büyük |
+| `sharp` | Görsel optimizasyonu | Adım atlanır; `image()` orijinali kullanır |
+| `@phosphor-icons/core` | İkon sprite | Adım atlanır; `icon()` boş `<use>` üretir |
+
+CSS kullanmayacaksanız `paths.styles` dosyasını hiç oluşturmayın: adım uyarıyla
+atlanır ve postcss'e ihtiyaç kalmaz.
+
+Paketler **uygulamanın** `node_modules`'ünden çözülür, framework'ün kendisinden
+değil. Framework `file:` ya da workspace bağlantısıyla kuruluysa kaynak
+dosyaları kendi dizininde çalışır ve düz bir `import "postcss"` framework'ün
+ağacına bakar — uygulamanınkine değil. Bu yüzden çözümleme uygulama kökünden
+başlatılır.
+
+## `.gitignore` önerisi
+
+```
+node_modules/
+.jskelet/
+public/assets/
+.env
+```
+
+`public/fonts/` **commit edilmelidir** (build'in ağa bağımlı olmaması için),
+`public/assets/` edilmemelidir (her build'de yeniden üretilir).
+
+## `jskelet start` ve eksik build
+
+`jskelet start` önce `.jskelet/manifest.json` dosyasına bakar; yoksa build'i
+kendisi çalıştırır. Docker imajında build zaten yapıldığı için bu bir no-op;
+amaç `npm start`ı doğrudan çalıştıran birinin stilsiz bir sayfayla
+karşılaşmaması.
+
+## Teşhis: sık görülen durumlar
+
+- **Stil hiç yok.** Build çalışmamış (`hasAsset('app.css')` false) ya da
+  `paths.styles` dosyası mevcut değil. Build çıktısındaki `CSS` satırını
+  kontrol edin.
+- **Bazı Tailwind sınıfları çalışmıyor.** `@source` direktifi eksik olan bir
+  dizinde yazılmışlar.
+- **İkon boş görünüyor.** Sprite'ta o sembol yok; dev'de `[icon] sprite'ta yok`
+  uyarısına bakın.
+- **Island'lar hiç açılmıyor.** `main.js` manifest'te yok (entry dizini boş ya
+  da build atlanmış) veya bir build hatası var.
+- **Dev'de sayfa aniden stilsiz kaldı.** Manifest ile diskteki dosya
+  ayrışmıştır; `jskelet dev`i yeniden başlatmak yeterli.
+
+## Sırada ne var
+
+- Watch akışı ve CSS hot-swap: [09-dev-araclari.md](./09-dev-araclari.md)
+- Prod build + start ve Docker: [10-dagitim.md](./10-dagitim.md)
+- `entries` ve island bundle'ının kullanımı: [05-islands.md](./05-islands.md)

package/docs/09-dev-araclari.md

@@ -0,0 +1,302 @@
+# 09 — Geliştirme araçları
+
+Bu belge `jskelet dev`in ne yaptığını ve neden böyle yaptığını anlatır: iki alt
+sürecin yönetimi, terminal çıktısının biçimi, izlenen dizinler ve `node --watch`
+yerine kendi watcher'ının yazılma sebebi, CSS hot-swap ile tam yenileme ayrımı,
+`Alt+D` ile açılan devtools overlay'i, detaylı rapor sayfası ve `DEV_TOKEN` ile
+kurulan dev gate. Build adımlarının kendisi [08-build.md](./08-build.md)'de.
+
+## `jskelet dev` akışı
+
+Komut tek terminalde iki uzun ömürlü alt süreç yönetir:
+
+```
+jskelet dev
+├─ build watch   node src/build/build.mjs --watch
+└─ sunucu        node [--env-file=.env] --import <register.mjs> src/start.mjs
+```
+
+`NODE_ENV=development` ataması platformdan bağımsız olarak burada yapılır —
+`cross-env` gerekmez. Alt süreçlere ayrıca `JSKELET_CHILD=1` (build banner'ını
+bastırır) ve TTY varsa `JSKELET_COLOR=1` (borulanmış çıktıda renk zorlar)
+geçirilir.
+
+Açılış sırası: banner → build adımları → sunucu hazır → `Ready` özeti. Özet hem
+build hem sunucu hazır olduğunda basılır; aksi hâlde arkadan gelen build
+satırlarının arasında kalıyordu.
+
+Sunucunun hazır olduğu, `startServer` içindeki tek satırdan anlaşılır:
+
+```
+jskelet → http://localhost:3000 (development)
+```
+
+Bu satırın biçimi bir sözleşmedir; dev script'i onu ayrıştırıp özet satırını ona
+göre basar.
+
+### Terminal çıktısının biçimi
+
+Alt süreçlerin çıktısı olduğu gibi akmaz. İki bölge vardır ve karışmazlar:
+
+1. **Başlangıç:** banner, hizalı build satırları, `Ready` özeti.
+2. **Çalışma anı:** zaman damgalı, tek satırlık olaylar (HTTP istekleri, CSS
+   rebuild, sunucu restart).
+
+Hata yığınları çerçeveli bir kutuya dönüşür: yığın satırları parça parça geldiği
+için kısa bir sessizlikten (60 ms) sonra toplanır, hata adı ve mesajı
+ayrıştırılır, ilk üç frame gösterilir ve proje kökü `.` ile kısaltılır. Kendi
+framework'ünü geliştirirken hatanın akış içinde kaybolmaması gerçekten fark
+yaratan ayrıntı.
+
+Renk anlam taşır: `✓` yeşil, `✖` kırmızı, `⚠` sarı, `↻` cyan; süre ve yol gri.
+Dekoratif renk kullanılmaz. `NO_COLOR` ayarlıysa renk hiç kullanılmaz.
+
+`Ctrl+C` (SIGINT/SIGTERM) tüm alt süreçleri kapatır. Bir alt süreç sıfır dışı
+kodla çıkarsa (beklenen restart hariç) hata basılır ve dev süreci de kapanır.
+
+## Watch dizinleri
+
+Sunucu yeniden başlatma framework'ün kendi watcher'ıyla yönetilir.
+
+```js
+WATCH_DIRS = [
+  config.dirs.routes,
+  config.dirs.views,
+  <root>/lib,
+  ...config.watch,   // jskelet.config.mjs → watch
+]
+```
+
+Ayrıca `jskelet.config.mjs` dosyasının kendisi izlenir: config değişince hem
+sunucu hem build yeni ayarlarla açılmalı.
+
+İzlenen uzantılar: `.js`, `.mjs`, `.json`, `.ejs`.
+
+`views` de izlenir çünkü bileşenlerin çoğu `views/components/**.js` içinde ve bu
+modüller sunucuya bir kez import edildiği için, restart olmadan yapılan
+değişiklik tarayıcıya hiç yansımıyordu (şablon düzenleyip "hiçbir şey değişmedi"
+hissi buradan geliyor).
+
+`client/` ve `styles/` bu listede **yoktur**: onları esbuild ve CSS watcher'ları
+kendi içinde hallediyor ([08-build.md](./08-build.md)).
+
+Bir dizin izlenemezse uyarı basılır ve o dizinde otomatik restart olmaz; gerisi
+çalışır.
+
+### Neden `node --watch` kullanılmadı
+
+`--watch-path` verilse bile Node bu kurulumda proje kökünü izliyordu. Build
+çıktısı (`public/assets`, `manifest.json`) ya da dev araçlarının günlüğü
+yazıldığında sunucu boşuna yeniden başlıyor, hatta kendini besleyen bir döngü
+kuruluyordu: restart → açılış uyarısı → yazma → restart.
+
+Kendi watcher'ı üç şey yapar:
+
+1. **Yalnızca sunucu kaynaklarını izler.**
+2. **Değişiklikleri birleştirir** (250 ms) ve hangi dosyaların değiştiğini
+   bildirir.
+3. **Sahte olayları eler.** Windows'ta `fs.watch` bir dosya yazıldığında
+   komşuları için de olay üretebiliyor; `mtime` karşılaştırılmazsa tek kaydetme
+   iki restart'a dönüşüyordu. Açılışta mevcut zamanlar önden okunur, böylece ilk
+   sahte olay da elenir.
+
+Restart satırı değişen dosyayı ya da sayısını gösterir:
+
+```
+21:04:12 ↻ server  restarting…  routes/10-pages.mjs
+21:04:12   server  restarted    412ms
+```
+
+`JSKELET_VERBOSE=1` ayarlıysa birden fazla dosya değiştiğinde tamamı listelenir.
+
+## CSS hot-swap ve tam yenileme
+
+Dev sunucusu `.jskelet/manifest.json` dosyasını izler ve bir SSE kanalı
+(`<devBasePath>/events`) üzerinden tarayıcıya olay yayınlar. Manifest her build
+turunda yeniden yazıldığı için değişiklik tespiti manifest üzerinden yapılır.
+
+| Değişen | Davranış |
+| --- | --- |
+| Yalnızca `app.css` | **CSS hot-swap:** stylesheet takas edilir, sayfa yenilenmez. Durum ve kaydırma korunur. |
+| `main.js`, sprite, başka bir varlık ya da birden fazla anahtar | **Tam yenileme** |
+
+Her iki durumda önce HTML önbelleği temizlenir: saklanan HTML eski hash'li varlık
+URL'lerini taşıyor olur ve temizlenmezse sayfa silinmiş dosyayı istemeye devam
+eder.
+
+Manifest olayları 120 ms birleştirilir. Watch desteklenmiyorsa live reload devre
+dışı kalır ve gerisi çalışır.
+
+Sunucu yeniden başladığında overlay bunu **boot kimliğinden** anlar: her süreç
+kendine özgü bir `boot` değeri yayınlar, overlay değişikliği görüp "restarted"
+bilgisini gösterir ve kendi durumunu sıfırlamaz.
+
+## Devtools overlay
+
+Sağ altta yüzen bir baloncuk; `Alt+D` ile açılır, `Esc` ya da karartma alanına
+tıklamak kapatır. Yalnızca `NODE_ENV=development` iken layout tarafından
+basılır:
+
+```ejs
+<% if (devtools) { %>
+<script type="module" src="<%= devBasePath %>/overlay.js"></script>
+<% } %>
+```
+
+Overlay dosyası **build'e dâhil değildir.** Sunucu onu framework paketinden ham
+olarak servis eder; bu yüzden içinde bundler yoktur, tek dosya olarak çalışır ve
+prod çıktısına hiçbir şey eklemez. Tüm arayüz shadow DOM içinde durur, sayfanın
+CSS'i ile karışmaz.
+
+Gösterdikleri:
+
+- **Hatalar:** tarayıcı tarafındaki JS hataları, kaynak yükleme hataları
+  (`img`/`script`/`link`), ve sunucudaki `console.error` / `console.warn`
+  çıktıları. Sunucu tarafında `console` sarılır, böylece uyarılar terminalde
+  kaybolmaz.
+- **İstekler:** her HTML isteğinin metodu, yolu, durumu, süresi ve
+  `X-JSkelet-Cache` değeri. Aynı satırlar terminale de basılır.
+- **Web Vitals:** TTFB, FCP, LCP, CLS, INP, DCL, load, uzun task sayısı ve
+  bloke süresi.
+- **Prewarm:** ısıtma turunun ilerlemesi; panelden elle tetiklenebilir, tek tek
+  yollar tekrar denenebilir.
+- **Süreç:** pid, Node sürümü, uptime, RSS ve heap kullanımı.
+
+Isıtma istekleri (`user-agent: jskelet-prewarm`) hem terminalden hem istek
+listesinden filtrelenir: yüzlerce istek görünümü doldurmasın. İlerleme baloncuğun
+yanındaki rozette görünür.
+
+### Durum neden `os.tmpdir()`'e yazılıyor
+
+İstek ve hata kayıtları süreç belleğinde durursa her yeniden başlatmada geçmiş
+silinir ve overlay boşalır. Bu yüzden kayıtlar restart'lar arasında bir dosyada
+taşınır.
+
+Dosya **proje ağacına yazılmaz**: her yazma watcher'ı tetikleyip sunucuyu
+yeniden başlatıyordu ve bu kendini besleyen bir döngü kuruyordu (restart →
+açılış uyarısı → yazma → restart). Bunun yerine dosya
+`os.tmpdir()/jskelet-devtools-<proje kökünün hash'i>.json` yoluna yazılır;
+hash sayesinde aynı makinede birden fazla JSKelet projesi birbirinin kaydını
+ezmez.
+
+Yazma her istekte değil, 300 ms sessizlikten sonra yapılır ve başarısızlığı dev
+akışını durdurmaz. En fazla 50 istek ve 50 hata tutulur.
+
+Panelin açık/kapalı durumu, aktif sekmesi ve tarayıcı hata günlüğü ise sekme
+belleğinde (`sessionStorage`) saklanır, böylece yenileme sonrası panel aynı
+sekmeyle geri gelir.
+
+## Rapor sayfası
+
+Baloncuk anlık durumu gösterir; rapor sayfası sitenin tamamına bakan bir görünüm
+üretir. Adres:
+
+```
+http://localhost:3000/__jskelet/dev/report
+```
+
+(`brand.devBasePath` değiştirilmişse ona göre.)
+
+İçeriği:
+
+- **Sayfalar:** gezilen her sayfanın Web Vitals ölçümleri, kaynak sayısı ve
+  toplam bayt (tür kırılımıyla), island durumu (kaç tanesi hazır, adları),
+  tarayıcıdaki API çağrıları ve SSR çıktısının boyutu/süresi/cache durumu. Hiç
+  gezilmemiş ama ısıtılmış sayfalar da listelenir: SSR tarafı bilinir, istemci
+  ölçümleri boş kalır.
+- **Sunucu API çağrıları:** SSR sırasında yapılan dış `fetch` çağrıları — URL,
+  host, metot, durum, süre, bayt. `globalThis.fetch` yalnızca development'ta
+  sarılır; üretim yolu dokunulmaz kalır. Kendi sunucumuza yapılan istekler
+  (ısıtma, sağlık kontrolü) API sayılmaz.
+- **Build çıktısı:** manifest'teki her varlığın ham/gzip/brotli boyutu, ve
+  esbuild metafile'ından chunk analizi — her çıktının boyutu, hangi kaynaklardan
+  oluştuğu, hangi chunk'ları import ettiği. Kaynaklar okunur gruplara indirgenir
+  (paket adı ya da üst klasör), böylece "bu chunk'ın 40 kB'ı hangi kütüphaneden"
+  sorusu yanıtlanabilir.
+- **HTML önbelleği:** girdi sayısı ve döküm (anahtar, bayt, durum, bayat mı, kaç
+  saniye sonra dolacak, hangi encoding'ler saklanmış).
+- **Prewarm:** son turun tam sonucu.
+- **İstek ve hata günlükleri.**
+
+Ölçümler tarayıcı sekmesinde değil sunucuda durur; sıfırlama da sunucudan
+yapılır. Boyut hesapları dosya değişmedikçe tekrarlanmaz.
+
+Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç girmez.
+
+## Dev uçları
+
+`brand.devBasePath` (varsayılan `/__jskelet/dev`) altında:
+
+| Yol | Metot | İşi |
+| --- | --- | --- |
+| `/overlay.js` | GET | Overlay script'i |
+| `/logo.png` | GET | Overlay logosu |
+| `/events` | GET | SSE: live reload ve CSS hot-swap olayları |
+| `/stats` | GET | Anlık istatistikler (overlay 2 saniyede bir çeker) |
+| `/report` | GET | Rapor sayfası (HTML) |
+| `/report.js` | GET | Rapor sayfasının script'i |
+| `/report/data` | GET | Raporun tek veri kaynağı (JSON) |
+| `/vitals` | POST | Overlay'in gönderdiği ölçüm paketi |
+| `/report/clear` | POST | Sayfa ölçümlerini ve sunucu API kayıtlarını sıfırlar |
+| `/prewarm` | POST | Isıtmayı elle tetikler. Gövdede `paths` varsa yalnızca o yollar; ısıtma zaten çalışıyorsa 409. |
+| `/clear` | POST | İstek ve hata günlüklerini sıfırlar |
+
+Bu uçların tamamı `mountDevtools()` tarafından yalnızca
+`NODE_ENV=development` iken bağlanır; prod sürecine dinamik import sayesinde
+hiçbir şey yüklenmez.
+
+## Dev gate — `DEV_TOKEN`
+
+Yayına açılmamış bir ortamı gizlemek için: `DEV_TOKEN` ayarlıyken token
+taşımayan **her** isteğe 404 döner.
+
+```bash
+DEV_TOKEN=uzun-rastgele-bir-dize npm start
+```
+
+Erişim:
+
+```
+https://staging.ornek.com/?dev_token=uzun-rastgele-bir-dize
+```
+
+Davranış:
+
+- **403 değil 404.** 403 ortamın var olduğunu doğrular; 404 hiç yokmuş gibi
+  davranır.
+- Token bir kez query parametresiyle gelirse çereze yazılır (`Path=/`,
+  `SameSite=Lax`, 14 gün), böylece link paylaşımı yeterli olur. Çerez ve
+  parametre adı `brand.devTokenCookie` (varsayılan `dev_token`).
+- `devGateBypass` listesindeki **tam** yollar her koşulda açıktır. Varsayılan:
+  `/api/healthcheck`, `/robots.txt`, `/sitemap.xml`, `/site.webmanifest`,
+  `/favicon.ico`. Sağlık kontrolünüz farklı bir yolda ise bu listeye eklemeyi
+  unutmayın, aksi hâlde orkestratör 404 görür.
+- `DEV_TOKEN` yoksa middleware tamamen devre dışıdır ve üretimde hiçbir maliyeti
+  olmaz.
+- Isıtma kendi sunucusuna istek attığı için token'ı çerez olarak taşır; yoksa tüm
+  sayfalar 404 alır ve önbellek hiç dolmaz ([06-cache.md](./06-cache.md)).
+
+Gate middleware zincirinde `headers`tan sonra, `redirects`ten **önce** durur:
+yayına açılmamış bir ortam yönlendirme kurallarını bile dışarıya sızdırmamalı.
+
+## Development ile production farkları
+
+| Konu | Development | Production |
+| --- | --- | --- |
+| EJS şablon cache'i | Kapalı | Açık |
+| Manifest okuma | Her istekte | Bir kez |
+| Görsel manifest'i | Her çağrıda | Bir kez |
+| Bozuk route modülü | Uyarı + atla | Fırlat |
+| Devtools ve rapor | Mount edilir | Hiç yüklenmez |
+| `globalThis.fetch` | Sarılır (ölçüm) | Dokunulmaz |
+| Prewarm paralelliği | 2 | 4 |
+| Prewarm gecikmesi | 3000 ms | 500 ms |
+| Eksik ikon uyarısı | Verilir | Verilmez |
+| Precompress | Watch'ta çalışmaz | Çalışır |
+| Görsel optimizasyonu | Watch'ta çalışmaz | Çalışır |
+
+## Sırada ne var
+
+- Build adımlarının ayrıntısı: [08-build.md](./08-build.md)
+- Prod'a alma: [10-dagitim.md](./10-dagitim.md)
+- Önbelleği okumak ve temizlemek: [06-cache.md](./06-cache.md)