jskelet 0.1.1

package/docs/01-baslangic.md

@@ -0,0 +1,285 @@
+# 01 — Başlangıç
+
+Bu belge JSkelet'i sıfırdan çalıştırmayı anlatır: paket kurulumu, `jskelet init`
+ile iskeletin oluşturulması, ilk route ve ilk island'ın yazılması, oluşan dizin
+yapısının ne anlama geldiği ve CLI'ın dört komutu. Sonunda tarayıcıda sunucuda
+render edilmiş, önbelleğe alınmış ve island'ı görünürlükte hidre olan bir sayfa
+olacak. Kararların *nedenleri* için [02-mimari.md](./02-mimari.md)'ye, buradaki
+her config alanının tam referansı için
+[07-yapilandirma.md](./07-yapilandirma.md)'ye bakın.
+
+## Gereksinimler
+
+- **Node.js 22 veya üstü.** `package.json` → `engines` bunu zorunlu tutuyor.
+  Framework `node:async_hooks`, `fs.readdirSync(..., { recursive: true })`,
+  `--env-file-if-exists` ve `module.register()` gibi yeni Node yüzeylerini
+  doğrudan kullanıyor.
+- Tailwind CSS kullanacaksanız `postcss`, `@tailwindcss/postcss` ve
+  `tailwindcss` paketleri. Bunlar framework'ün **opsiyonel peer
+  bağımlılıkları**dır; kurulu değilse CSS adımı atlanır ve site stilsiz ama
+  çalışır durumda kalır (ayrıntı: [08-build.md](./08-build.md)).
+
+## Kurulum
+
+```bash
+mkdir benim-sitem && cd benim-sitem
+npm init -y
+npm pkg set type=module
+npm install jskelet
+npm install -D postcss @tailwindcss/postcss tailwindcss lightningcss
+```
+
+`type: "module"` şart: route modülleri, bileşenler ve config dosyası ESM olarak
+yüklenir.
+
+Ardından `package.json` içine script'leri ekleyin:
+
+```json
+{
+  "scripts": {
+    "dev": "jskelet dev",
+    "build": "jskelet build",
+    "start": "jskelet start"
+  }
+}
+```
+
+## `jskelet init`
+
+```bash
+npx jskelet init
+```
+
+Bu komut bulunduğunuz dizine çalışan bir minimum iskelet kurar. **Var olan
+dosyaların üzerine yazmaz**: ikinci kez çalıştırmak yalnızca eksikleri
+tamamlar, atlanan dosyaların sayısını uyarı olarak basar. Amaç, "kurulumu
+yaptım ama hiçbir şey çalışmıyor" aşamasını tamamen atlamak — `jskelet dev`
+hemen ardından çalışır.
+
+Oluşturulan dosyalar:
+
+```
+jskelet.config.mjs          config: brand, preconnect, cache(), hooks
+routes/10-pages.mjs         "/" route'u
+views/pages/home.ejs        ana sayfa şablonu
+views/pages/not-found.ejs   404 şablonu
+views/components/button.js  örnek bileşen (HTML string döndüren fonksiyon)
+client/entries/main.js      island bootstrap'ı
+client/islands/counter.js   örnek island
+styles/globals.css          Tailwind girişi + @source direktifleri
+jsconfig.json               checkJs + "@/*" alias'ı
+.gitignore                  node_modules/, .jskelet/, public/assets/, .env
+```
+
+Sonra:
+
+```bash
+npm run dev
+```
+
+Terminalde banner, hizalı build satırları ve bir `Ready` özeti görürsünüz;
+`http://localhost:3000` sayfayı verir. Sağ altta dev overlay baloncuğu durur,
+`Alt+D` ile açılır ([09-dev-araclari.md](./09-dev-araclari.md)).
+
+## Dizin yapısı
+
+Dizin adlarının hiçbiri sabit değildir; hepsi `jskelet.config.mjs` → `paths`
+ile ezilebilir. Aşağıdaki değerler varsayılanlardır (`src/config/defaults.js`).
+
+| Dizin | Varsayılan | İçeriği |
+| --- | --- | --- |
+| `views` | `views` | EJS layout, sayfalar ve bileşenler |
+| `public` | `public` | Statik dosyalar; build çıktısı da buraya yazılır |
+| `client` | `client` | Island runtime kaynakları ve entry'ler |
+| `routes` | `routes` | Route modülleri |
+| `styles` | `styles/globals.css` | Tailwind/PostCSS giriş **dosyası** |
+| `generated` | `.jskelet` | Build ara çıktıları: `manifest.json`, `metafile.json`, `images.json` |
+
+Bunlara ek olarak framework iki yolu her zaman türetir ve ayrı ayar kabul
+etmez: `public/assets` (hash'li build çıktısı) ve `public/fonts` (self-host
+fontlar).
+
+Tipik bir proje:
+
+```
+benim-sitem/
+├── jskelet.config.mjs
+├── jsconfig.json
+├── routes/
+│   ├── 10-pages.mjs
+│   └── 90-catch-all.mjs
+├── views/
+│   ├── layout.ejs
+│   ├── pages/
+│   │   ├── home.ejs
+│   │   └── not-found.ejs
+│   └── components/
+│       └── card.js
+├── client/
+│   ├── entries/
+│   │   └── main.js
+│   └── islands/
+│       └── counter.js
+├── styles/
+│   └── globals.css
+├── public/
+│   └── (statik dosyalar; build → public/assets)
+└── .jskelet/
+    └── manifest.json
+```
+
+## İlk route
+
+Route modülleri **dosya sistemine dayalı otomatik URL türetmez**; her modül
+kendi yollarını `app.get(...)` ile açıkça yazar. Modül sözleşmesi: default
+export ya da `register` adlı named export, `(app, api)` imzasıyla.
+
+```js
+// routes/10-pages.mjs
+export default function register(app, { route }) {
+  app.get(
+    "/",
+    route(
+      async () => ({
+        view: "pages/home",
+        metadata: { title: "Ana sayfa" },
+        data: { heading: "JSkelet çalışıyor", items: ["Bir", "İki"] },
+      }),
+      { revalidate: 60 },
+    ),
+  );
+}
+```
+
+`api` nesnesi içinde `route`, `renderView`, `renderPage`, `notFound`, `redirect`
+ve `permanentRedirect` hazır gelir; route dosyaları framework'ten tek tek import
+yapmak zorunda kalmaz. `route()` controller'ı sarar: HTML cache'i,
+notFound/redirect kontrol akışı, sıkıştırma ve `X-JSkelet-Cache` başlığı ondan
+gelir. Controller'ın tek işi bir sayfa tanımı döndürmektir.
+
+Dosya adındaki `10-` öneki yükleme sırasını belirler. `routes/` alfabetik
+tarandığı için `/:slug` gibi yakalayıcı route'ları daha yüksek numaralı bir
+dosyaya koymalısınız; aksi hâlde `/hakkinda` bir slug sanılır. Ayrıntı:
+[03-routing.md](./03-routing.md).
+
+Şablon tarafı düz EJS:
+
+```ejs
+<%# views/pages/home.ejs %>
+<section class="wrapper">
+  <h1 class="text-3xl font-bold"><%= heading %></h1>
+  <%- list({ items }) %>
+  <div data-island="counter" data-island-props='{"start":5}'></div>
+</section>
+```
+
+`list` burada `views/components/list.js` içinde tanımlı bir fonksiyondur ve
+import edilmemiştir: `views/components/**` altındaki her named export otomatik
+olarak şablon local'i olur ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
+
+## İlk island
+
+Island, sunucunun ürettiği HTML'e davranış ekleyen küçük bir modüldür. Sözleşme
+iki parçadan oluşur.
+
+**1. Şablonda işaret:** bir elemente `data-island="ad"` verin. Props JSON olarak
+`data-island-props` içinde taşınır.
+
+```ejs
+<div data-island="counter" data-island-props='{"start":5}'></div>
+```
+
+**2. Modülde `mount`:** island `mount(element, props)` adlı bir named export
+verir.
+
+```js
+// client/islands/counter.js
+/**
+ * @param {HTMLElement} element
+ * @param {{ start?: number }} props
+ */
+export function mount(element, props) {
+  let value = props.start ?? 0;
+
+  const button = document.createElement("button");
+  button.type = "button";
+
+  const paint = () => {
+    button.textContent = `Tıklama: ${value}`;
+  };
+
+  button.addEventListener("click", () => {
+    value += 1;
+    paint();
+  });
+
+  paint();
+  element.append(button);
+}
+```
+
+**3. Kayıt:** `client/entries/main.js` island adını dinamik import'a bağlar ve
+runtime'ı başlatır.
+
+```js
+import { registerAll, start } from "jskelet/client";
+
+registerAll({
+  counter: () => import("../islands/counter.js"),
+});
+
+start();
+```
+
+Değerlerin dinamik import olması kritik: modül yalnızca sayfada o island
+gerçekten varsa **ve** element görünür hâle geldiğinde indirilir. Yani bu
+haritayı büyütmek ilk yükü büyütmez. Hidrasyon stratejileri
+(`data-island-eager`, `data-island-idle`) ve runtime API'sinin tamamı
+[05-islands.md](./05-islands.md)'de.
+
+## CLI komutları
+
+`bin/jskelet.mjs` dört alt komut sunar. Her biri ayrı bir Node sürecinde
+çalışır; sebebi `dev`in iki uzun ömürlü süreci yönetmesi ve sunucunun ESM
+resolve hook'larına (`--import`) süreç başlangıcında ihtiyaç duyması.
+
+| Komut | Ne yapar |
+| --- | --- |
+| `jskelet dev` | Build watch + sunucu, tek terminalde. Canlı yenileme, CSS hot-swap, dev overlay. `NODE_ENV=development`. |
+| `jskelet build` | Tek seferlik prod build: fontlar → ikon sprite → CSS → client JS → görseller → manifest → precompress. `NODE_ENV` verilmemişse `production`. |
+| `jskelet start` | Prod sunucu. Build çıktısı yoksa önce üretir. `NODE_ENV` verilmemişse `production`. |
+| `jskelet init` | Bulunduğun dizine minimal iskelet kurar; var olan dosyalara dokunmaz. |
+
+Bilinmeyen bir komut ya da argümansız çağrı kullanım metnini basar.
+
+Her komut iki Node bayrağıyla çalışır:
+
+- `--env-file=.env` — yalnızca dosya gerçekten varsa geçilir; yoksa hiçbir
+  bayrak eklenmez ve uyarı basılmaz.
+- `--import <register.mjs>` — `jsconfig.json` / `tsconfig.json` içindeki
+  `compilerOptions.paths` alias'larını (`@/lib/x`) ve uzantısız göreli
+  import'ları (`./cache` → `./cache.js`) çözen ESM hook'larını kurar.
+  (`jskelet dev` bu hook'ları kendi alt süreçlerinde kurar, dış süreçte kurmaz.)
+
+## İthal yolları
+
+`package.json` → `exports` haritası kararlı yüzeyi tanımlar. Örneklerde
+yalnızca bu belirteçleri kullanın:
+
+| Belirteç | İçeriği |
+| --- | --- |
+| `jskelet` | Sunucu API'si: `route`, `renderPage`, `renderView`, `renderNotFound`, `createApp`, `startServer`, `notFound`, `redirect`, `permanentRedirect`, `cache`, `withRequestCache`, `reportUpstreamFailure`, `asset`, `hasAsset`, `optimizedImage`, `getSpriteIds`, `headHints`, `renderHeadMeta`, HTML cache fonksiyonları, `prewarm`, `createProxy`, `getConfig`, `loadConfig` ve html/tag yardımcıları |
+| `jskelet/server` | `jskelet` ile aynı modül (okunurluk için takma ad) |
+| `jskelet/client` | Tarayıcı runtime'ı: `register`, `registerAll`, `hydrate`, `observeDocument`, `start`, `createStore`, DOM yardımcıları, `startSafeImages` |
+| `jskelet/html` | `esc`, `attrs`, `cx`, `cn`, `jsonScript` |
+| `jskelet/tags` | `link`, `image`, `icon`, `preloadImage`, `toKebab` |
+| `jskelet/log` | Konsol çıktısı yardımcıları (`banner`, `event`, `task`, `size`, `ms`, …) |
+| `jskelet/register` | `node --import jskelet/register` ile alias + uzantı hook'ları |
+| `jskelet/layout` | Framework'ün varsayılan `layout.ejs` dosyasının yolu |
+
+## Sırada ne var
+
+- Neden bu şekilde çalışıyor: [02-mimari.md](./02-mimari.md)
+- Daha fazla route ve yakalayıcı desenler: [03-routing.md](./03-routing.md)
+- Layout'u devralmak ve metadata: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)
+- Önbelleği ayarlamak: [06-cache.md](./06-cache.md)

package/docs/02-mimari.md

@@ -0,0 +1,287 @@
+# 02 — Mimari ve kararların gerekçeleri
+
+Bu belge JSkelet'in nasıl çalıştığını değil, **neden böyle çalıştığını**
+anlatır. Bir isteğin sunucudan tarayıcıya kadar izlediği yol, island modelinin
+neden görünürlüğe bağlı olduğu, HTML'in neden tam üretildiği, önbelleğin neden
+süreç belleğinde durduğu ve middleware sırasının neden yer değiştirmemesi
+gerektiği burada. Gerekçelerin çoğu kaynak dosyaların başlıklarındaki ölçüm
+notlarından geliyor; API'lerin kendisi için [03](./03-routing.md),
+[04](./04-render-ve-sablonlar.md), [05](./05-islands.md) ve
+[06](./06-cache.md) numaralı belgelere bakın.
+
+## Temel önerme
+
+Bir haber ya da içerik sitesinde ziyaretçinin gördüğü şeyin neredeyse tamamı
+sunucuda hazırdır. Etkileşim ise nokta nokta dağılmıştır: bir arama kutusu, bir
+drawer, bir grafik, bir yorum formu. Bu profilde tüm sayfayı istemcide yeniden
+kurmak (hidrasyon) ödediğiniz en büyük maliyettir ve karşılığında ziyaretçi
+hiçbir şey kazanmaz.
+
+JSkelet bu gözlemi mimarinin merkezine alır:
+
+1. **Sunucu HTML'i tamdır.** JS çalışmasa bile sayfa okunur, gezilebilir ve
+   indekslenebilir.
+2. **JS yalnızca davranış ekler.** Her etkileşimli parça bağımsız bir "island"
+   olarak, kendi modülüyle, kendi zamanında bağlanır.
+3. **Sayfa üretimi önbelleklenir.** Aynı HTML'i her istekte yeniden üretmenin
+   anlamı yok; TTL'li bir bellek önbelleği ISR'nin yerini tutar.
+
+## Bir isteğin yolu
+
+```
+İstek
+ ├─ rewrites(beforeFiles)          config → proxy ya da req.url değişimi
+ ├─ compression                    brotli/gzip pazarlığı (kalite 5)
+ ├─ headers                        statik cache + config headers()
+ ├─ devGate                        DEV_TOKEN varsa token yoksa 404
+ ├─ redirects                      config redirects(), ilk eşleşen kazanır
+ ├─ staticPrecompressed            build'de üretilmiş .br/.gz kopyalar (kalite 11)
+ ├─ express.static                 public/ altındaki dosyalar
+ ├─ (dev) devtools                 yalnızca NODE_ENV=development
+ ├─ body parser'lar                urlencoded 64kb + json 256kb
+ ├─ rewrites(afterFiles)           statik denendikten sonra
+ ├─ route'lar
+ │   └─ route(controller)
+ │       └─ withHtmlCache          TTL + stale-while-revalidate
+ │           └─ withUpstreamTracking
+ │               └─ withRequestCache
+ │                   └─ controller → renderPage → EJS
+ ├─ 404 → hooks.notFound()
+ └─ hata yönetimi                  redirect/notFound + 500 fallback
+```
+
+## Middleware sırası neden bu sıra
+
+`src/server/create-app.js` dosyasının asıl değeri sıradır; her konumun bir
+sebebi var ve yer değiştirmek sessiz bozulmalara yol açıyor.
+
+- **`rewrites(beforeFiles)` statik dosyalardan da önce.** Aksi hâlde
+  `/assets/x.js` yolunu başka bir yere taşıyan bir kural hiç işlemez, çünkü
+  `express.static` isteği önce yanıtlar.
+- **`compression`, static'ten önce.** Sonra gelirse statik dosyalar hiç
+  sıkışmaz.
+- **`headers` → `devGate` → `redirects`.** Gate'in 404'ü redirect'ten önce
+  gelmeli: yayına açılmamış bir ortam, yönlendirme kurallarını bile dışarıya
+  sızdırmamalı.
+- **`staticPrecompressed`, `express.static`ten önce.** Build'de üretilmiş
+  `.br`/`.gz` kopyalar varsa onlar servis edilir (brotli kalite 11); yoksa
+  istek altındaki `static`e düşer ve middleware anında sıkıştırır (kalite 5).
+  Hash'li ve `immutable` bir dosyayı her istekte yeniden sıkıştırmak boşa CPU.
+- **Body parser'lar statikten sonra.** Görsel isteklerinde gövde ayrıştırma
+  maliyeti ödenmesin.
+- **`rewrites(afterFiles)`, statik denendikten sonra ve sayfalardan önce.**
+  Next.js'teki iki fazlı rewrite semantiğinin karşılığı.
+- **404 ve hata yönetimi en sonda.** Hata yöneticisi `notFound`/`redirect`
+  kontrol akışını da yakalar, çünkü bunlar bir controller dışında (ör. bir
+  middleware içinde) da fırlatılabilir.
+
+Framework `x-powered-by`'ı kapatır ve yerine markalanabilir bir başlık yazar,
+`etag`i `strong` yapar ve `trust proxy`yi açar. `trust proxy` ters proxy
+arkasında doğru protokol ve istemci IP'si için gerekli
+([10-dagitim.md](./10-dagitim.md)).
+
+## Island modeli: neden görünürlüğe bağlı hidrasyon
+
+`src/client/registry.js` her `[data-island]` elementini bir
+`IntersectionObserver`'a verir (`rootMargin: "200px 0px"`). Ekranda olanlar
+zaten ilk gözlemde tetiklenir; ekran dışındakiler kaydırılana kadar **hiç
+indirilmez**. Ana sayfadaki grafik kütüphanesi gibi ağır modüller böylece ilk
+yükten tamamen çıkar.
+
+Üç davranış var, hepsi HTML'den kontrol edilir:
+
+- **Varsayılan:** görünürlüğe bağlı.
+- **`data-island-eager`:** görünürlükten bağımsız, hemen bağlanır. Header,
+  çerez bandı gibi global davranışlar için.
+- **`data-island-idle`:** görünür olsa bile `load` tamamlanıp ana iş parçacığı
+  boşalana kadar bekler. İlk ekranda görünen ama kritik olmayan ağır modüller
+  (ör. grafik kütüphanesi çeken mini grafik) LCP ile yarışmasın diye.
+
+İki ek ayrıntı ölçümden geldi:
+
+- **Bağlama işi boş zamana kaydırılır** (`requestIdleCallback`, `timeout: 500`).
+  Aynı anda görünen çok sayıda island tek bir uzun task'a dönüşürse TBT ve INP
+  bozulur.
+- **Düzen kutusu olmayan elementler doğrudan bağlanır.** `hidden` bir
+  drawer/dialog'un düzen kutusu yoktur ve `IntersectionObserver` onu asla
+  bildirmez; bu yüzden `hydrate()` ölçümleri tek seferde okur
+  (`getClientRects().length`) ve kutusu olmayanları gözlemciye vermek yerine
+  hemen bağlar.
+
+Buradan çıkan bir sonuç: **görsel hata yönetimi island değildir.** Görsel
+ağırlıklı bir sayfada 80+ `<img>` olabiliyor ve her birine ayrı island bağlamak
+(gözlemci + dinamik import + mount) sırf hata ihtimali için ciddi bir hidrasyon
+yükü. `startSafeImages()` bunun yerine belgeye tek bir yakalama fazı
+dinleyicisi kurar ([05-islands.md](./05-islands.md)).
+
+## Sunucu HTML'i neden tam
+
+Layout ve sayfa şablonu, ziyaretçinin göreceği içeriğin tamamını üretir.
+İstemci tarafında "iskelet göster, sonra doldur" deseni yoktur. Bunun üç
+karşılığı var:
+
+1. **SEO:** kazıyıcı JS beklemek zorunda kalmaz.
+2. **LCP:** en büyük içerik öğesi ilk HTML yanıtında gelir; JS'in indirilmesi,
+   ayrıştırılması ve çalıştırılması LCP yolunda değildir.
+3. **CLS:** içerik sonradan enjekte edilmediği için düzen kaymaz.
+
+Aynı ilke `<head>` tarafında da uygulanır. Layout kaynak ipuçlarını
+(`preconnect`, LCP `preload`) `<head>`in **en başına** basar; bunları
+geciktirmek doğrudan LCP'ye yazılır.
+
+### Neden tek, render-blocking stylesheet
+
+Ayrı bir "critical CSS" üretilmez. Ölçümde inline kritik CSS ilk ekranı tam
+kapsamadığı için sheet gelince sayfa yeniden akıyordu (bir liste sayfasında CLS
+0.307) ve aynı ~27 KB her HTML yanıtında tekrar ediyordu. Sıkıştırılmış tek
+sheet'i render-blocking bırakmak hem daha hızlı hem CLS'siz; ikinci ziyarette
+zaten `immutable` önbellekten geliyor.
+
+Aynı mantık ikonlarda da var: her ikon için ayrı istek yerine, build zamanında
+yalnızca kaynakta kullanılan sembollerden bir SVG sprite üretilir. Tüm Phosphor
+setini göndermek 1500+ ikon, yani birkaç megabayt; tarama sprite'ı tipik olarak
+10-30 sembolde tutuyor ([08-build.md](./08-build.md)).
+
+## Cache stratejisi: ISR yerine bellek içi TTL
+
+`src/server/html-cache.js` route + query anahtarlı, TTL'li, LRU bir HTML
+önbelleği tutar (en fazla 500 girdi). TTL dolduğunda girdi hemen atılmaz: `stale`
+pencerede eski HTML anında döner ve tazeleme arkada çalışır
+(stale-while-revalidate, `STALE_FACTOR = 1`, yani stale penceresi TTL kadar).
+
+Kazanç: ilk ısıtmadan sonra hiçbir istek render'ı beklemez. Bedel: HTML'deki
+veri en fazla `revalidate + bir tazeleme turu` kadar geride olabilir. Bu bedel
+kabul edilebilir, çünkü fiyat gibi canlı alanlar istemcide WebSocket'ten
+güncelleniyor ve gecikme ekranda görünmüyor.
+
+Diske yazmama kararı bilinçli. Next'teki build-time prerender'ın karşılığı
+prewarm'dır ama çıktı diske yazılmaz: önbellek süreç belleğinde yaşadığı için
+ısıtma da süreç ayağa kalkınca yapılır. Kazanç aynı — ilk ziyaretçi soğuk
+render'ı beklemez — fakat veri dondurulmaz; her girdi route'un `revalidate`
+süresiyle yaşlanır ([06-cache.md](./06-cache.md)).
+
+### Sıkıştırılmış gövdenin önbellekte durması
+
+Önbelleğe alınan her girdi, brotli/gzip çıktısını HTML ile birlikte saklar
+(`encoded` haritası, HTML ile aynı ömrü paylaşır). Aynı sayfa her istekte
+yeniden brotli'lenmez. `Content-Encoding` bu yolda `route()` içinde ayarlandığı
+için sıkıştırma middleware'i devreye girmez.
+
+### Neden geçici ve kalıcı upstream hataları farklı ele alınır
+
+Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir ve böyle
+bir HTML önbelleğe **yazılmaz**: sonraki istek yeniden dener.
+
+Ancak bu yalnızca *geçici* hatalar için geçerli (ağ hatası, 408, 425, 429 ve tüm
+5xx). 400/403/404 gibi deterministik cevaplar tekrar denemekle düzelmez; onlar
+yüzünden önbelleği kapatmak sayfayı her ziyarette baştan render etmek olur —
+içerik yine aynı eksik hâliyle döner, ziyaretçi sadece render süresini öder. Bu
+yüzden kalıcı hatalar yalnızca loglanır, önbelleği engellemez.
+
+Bu bilginin framework'e ulaşma yönü de bilinçli olarak terstir: framework veri
+katmanını tanımaz, veri katmanı framework'e haber verir
+(`reportUpstreamFailure()`). Hiç çağıran olmazsa maliyet boş bir dizidir.
+
+### Üç kapsamın iç içe sırası
+
+`route()` şu sırayı kurar:
+
+```
+withHtmlCache( withUpstreamTracking( withRequestCache( controller ) ) )
+```
+
+Sıra önemli: **istek içi cache en içte** olmalı ki aynı render'daki iki çağrı
+tek upstream isteğine düşsün; **upstream takibi HTML cache'in içinde** olmalı ki
+eksik veriyle üretilen çıktı önbelleğe yazılmasın.
+
+## Hata toleransı: hiçbir eksik siteyi indirmez
+
+Framework boyunca tekrarlanan bir ilke var: eksik yapılandırma ya da eksik build
+çıktısı, hata yerine bozulmuş ama çalışan bir sayfa üretir.
+
+- **Config dosyası yoksa ya da okunamıyorsa** uyarı basılır ve sunucu
+  varsayılanlarla ayağa kalkar. Bozuk bir düzenleme siteyi açılamaz hâle
+  getirmemeli. Aynı şekilde `headers()`/`redirects()`/`rewrites()`/`cache()`
+  bölümlerinden biri hata verirse yalnızca o bölüm yok sayılır.
+- **Hook'lar hata verirse** framework kendi varsayılanına döner ve uyarır.
+- **Build çalışmadıysa** `asset()` `/assets/<isim>` döner, `hasAsset()` false
+  olur ve layout stylesheet/script etiketlerini hiç basmaz. `jskelet build`
+  unutulduğunda hata yerine stilsiz ama çalışan bir sayfa görürsünüz.
+- **Dev'de bozuk bir route modülü** uyarı basıp atlanır; **üretimde fırlatır.**
+  Yarım route tablosuyla yayına çıkmak, sessizce 404 dönen sayfalar demek.
+- **404 render'ı da patlarsa** şablonsuz, minimal bir HTML döner; ziyaretçi boş
+  yanıt görmesin.
+- **Tek bir istek hatası süreci düşürmez:** `unhandledRejection` ve
+  `uncaughtException` loglanır ve süreç ayakta kalır. Bir haber sitesinde tek
+  sayfanın hatası tüm siteyi indirmemeli.
+
+## Neden dosya sistemi tabanlı routing yok
+
+Sıra önemli. `/:slug` gibi tek segmentli bir yakalayıcı `/about` rotasından önce
+kaydedilirse "about" bir slug sanılır. Sırayı dosya adına gizlemek yerine
+görünür kılmak teşhisi kolaylaştırıyor: ya `jskelet.config.mjs` → `routes` ile
+açık bir liste verirsiniz, ya da `routes/` dizinini alfabetik taratıp dosya
+adlarına sayısal önek koyarsınız (`10-pages.js`, `50-blog.js`,
+`99-catch-all.js`). Ayrıntı: [03-routing.md](./03-routing.md).
+
+## Neden tek bir config gerçek kaynağı
+
+`src/config/index.js` proje kökünü, dizin yollarını, markalamayı, hook'ları ve
+kuralları normalize eder. Diğer modüller yol hesaplamaz, `getConfig()` çağırır.
+Sebebi somut: framework `node_modules/` içine girdiğinde `../..` sayarak kök
+bulmaya çalışan her dosya bozulur. Aynı gerekçeyle build tarafında da tek bir
+mutasyon noktası var (`initBuildPaths()`).
+
+`getConfig()` `loadConfig()` çağrılmadan kullanılırsa boş bir proje kökü
+varsaymak yerine hata verir: sessiz yanlış yol, "stylesheet neden yok" gibi
+teşhisi zor sorunlara dönüşüyor.
+
+## Neden bu bağımlılık listesi
+
+Çalışma zamanı bağımlılıkları dörttür: `express`, `ejs`, `esbuild`,
+`tailwind-merge`. Geri kalan her şey (Tailwind, PostCSS, lightningcss, sharp,
+Phosphor ikonları) **opsiyonel peer bağımlılığıdır** ve yoksa ilgili build adımı
+atlanır.
+
+İki karar ayrıca açıklanmayı hak ediyor:
+
+- **`compression` paketi yerine `node:zlib`.** Paket brotli desteklemiyor ve
+  yedi geçişli bir bağımlılık ağacı getiriyor; brotli + gzip pazarlığını elle
+  yapmak yeterli. Brotli tercih edilir: ana sayfa HTML'inde gzip'e göre ~%35
+  daha küçük.
+- **`tailwind-merge` çalışma zamanında kalır.** Sınıf hesabı yalnızca sunucuda
+  yapılır, client bundle'a hiç girmez, dolayısıyla sayfa ağırlığına etkisi
+  yoktur. Elle yazılmış bir grup tablosu ise `border-2` + `border-transparent`
+  gibi genişlik/renk çiftlerini birbirine karıştırıp sınıf düşürdüğü için
+  görsel regresyon üretiyordu.
+
+Opsiyonel paketler **uygulamanın** `node_modules`'ünden çözülür, framework'ün
+kendisinden değil. Framework `file:` ya da workspace bağlantısıyla kuruluysa düz
+bir `import "postcss"` framework'ün ağacına bakar — uygulamanınkine değil.
+
+## Neden alias ve uzantı hook'ları
+
+`node --import jskelet/register` iki iş yapar:
+
+1. `jsconfig.json` / `tsconfig.json` içindeki `compilerOptions.paths`
+   alias'larını çözer (`@/lib/x` → `<root>/lib/x`). Editör ve çalışma zamanı aynı
+   dosyadan beslendiği için ikisi birbirinden ayrışmaz.
+2. Uzantısız göreli import'lara uzantı ekler (`./cache` → `./cache.js`). Node ESM
+   bunu yapmaz ve bundler'dan taşınan kodda en sık karşılaşılan kırılma noktası
+   budur.
+
+esbuild tarafındaki `@/` çözümü de aynı davranışı taklit eder, böylece `lib/`
+altındaki modüller hem sunucuda hem tarayıcıda aynı import stilini kullanabilir.
+
+`--import` bir modül **belirteci** bekler, dosya yolu değil. Windows'ta `H:\...`
+mutlak yolu `h:` şemalı bir URL sanılıp reddediliyor; bu yüzden framework her
+yerde `pathToFileURL(...).href` kullanır. Aynı sebeple config, route modülleri
+ve bileşenler de `file://` URL'le import edilir.
+
+## Sırada ne var
+
+- Route ve controller sözleşmesi: [03-routing.md](./03-routing.md)
+- Şablon katmanı ve metadata: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)
+- Island runtime API'si: [05-islands.md](./05-islands.md)
+- Önbelleğin ayarları ve prewarm: [06-cache.md](./06-cache.md)
+- Dev akışının iç işleyişi: [09-dev-araclari.md](./09-dev-araclari.md)