jskelet 0.5.4 → 0.6.0

package/README.md

@@ -4,11 +4,13 @@
 the product.
 
 JSkelet renders **complete HTML** on an Express 5 server from build-time
-**`.jsk` templates** (EJS still works), adds interactivity through vanilla JS
-**islands**, compiles CSS into a **single Tailwind v4 stylesheet**, and instead
-of ISR keeps an in-process **HTML TTL cache** with stale-while-revalidate — plus
-optional Redis sharing and path-based invalidation. No React, no TypeScript —
-plain JavaScript with JSDoc.
+**`.jsk` templates** (optional EJS peer for legacy `.ejs`), adds interactivity
+through vanilla JS **islands**, compiles CSS into a **single Tailwind v4
+stylesheet**, and instead of ISR keeps an in-process **HTML TTL cache** with
+stale-while-revalidate — plus optional Redis sharing and path-based
+invalidation. No React — the framework source is plain JavaScript with JSDoc;
+apps can write client islands and entries in TypeScript, and the published
+package ships declaration files.
 
 [![npm version](https://img.shields.io/npm/v/jskelet)](https://www.npmjs.com/package/jskelet)
 [![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
@@ -282,9 +284,9 @@ The complete reference — every field, default and failure mode — is
 
 | Command | What it does |
 | --- | --- |
-| `jskelet dev` | Watch build plus server, live reload, devtools overlay |
+| `jskelet dev` | Watch build plus server, live reload, devtools overlay. `--murder` kills whatever already holds `PORT` and starts. |
 | `jskelet build` | Production build: templates → fonts → sprite → CSS → JS → images → manifest → precompress |
-| `jskelet start` | Production server; builds first if output is missing |
+| `jskelet start` | Production server; builds first if output is missing. `--murder` same as for `dev`. |
 | `jskelet init` | Scaffolds a feature-first `.jsk` skeleton into the current directory |
 | `jskelet generate` | Scaffolds a `feature` / `page` / `island` |
 

package/bin/jskelet.mjs

@@ -1,12 +1,13 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * JSkelet CLI.
  *
- *   jskelet dev      build watch + sunucu, canlı yenileme, dev overlay
- *   jskelet build    tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
- *   jskelet start    prod sunucu (build eksikse önce üretir)
+ *   jskelet dev [--murder]   build watch + sunucu, canlı yenileme, dev overlay
+ *   jskelet build            tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
+ *   jskelet start [--murder] prod sunucu (build eksikse önce üretir)
  *   jskelet init       bulunduğun dizine minimal iskelet kurar
  *   jskelet generate   feature / page / island iskeleti
+ *   jskelet migrate    Next.js App Router → JSkelet codemod
  *
  * Alt komutlar ayrı süreçlerde çalışır. Sebep: `dev` iki uzun ömürlü süreci
  * (build watch + sunucu) yönetiyor ve sunucunun ESM resolve hook'larına
@@ -102,15 +103,28 @@ switch (command) {
     break;
   }
 
+  case "migrate": {
+    const { migrate } = await import("../src/migrate.mjs");
+    try {
+      await migrate(process.cwd(), rest);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+      process.exit(1);
+    }
+    break;
+  }
+
   default: {
     const known = command ? `unknown command: ${command}\n\n` : "";
     process.stderr.write(
-      `${known}usage: jskelet <dev|build|start|init|generate>\n\n` +
-        "  dev       build watch + server (live reload, dev overlay)\n" +
-        "  build     production build\n" +
-        "  start     production server\n" +
-        "  init      scaffold a minimal skeleton in the current directory\n" +
-        "  generate  scaffold feature | page | island\n",
+      `${known}usage: jskelet <dev|build|start|init|generate|migrate> [options]\n\n` +
+        "  dev [--murder]    build watch + server (live reload, dev overlay)\n" +
+        "  build             production build\n" +
+        "  start [--murder]  production server\n" +
+        "  init              scaffold a minimal skeleton in the current directory\n" +
+        "  generate          scaffold feature | page | island\n" +
+        "  migrate           Next.js App Router → JSkelet codemod (scan | apply | config)\n\n" +
+        "  --murder          if the listen port is busy, kill the listener and start\n",
     );
     process.exit(command ? 1 : 0);
   }

package/docs/01-baslangic.md

@@ -249,11 +249,12 @@ 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 dev` | Build watch + sunucu, tek terminalde. Canlı yenileme, CSS hot-swap, dev overlay. `NODE_ENV=development`. Port doluysa başlamaz; `--murder` dinleyiciyi öldürüp bağlar. |
 | `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 start` | Prod sunucu. Build çıktısı yoksa önce üretir. `NODE_ENV` verilmemişse `production`. Port davranışı `dev` ile aynı (`--murder`). |
 | `jskelet init` | Bulunduğun dizine feature-first `.jsk` iskeleti kurar; var olan dosyalara dokunmaz. |
 | `jskelet generate` | `feature` / `page` / `island` iskeleti üretir. |
+| `jskelet migrate` | Next.js App Router → JSkelet codemod (`scan` / `apply` / `config`). [11-tasima.md](./11-tasima.md). |
 
 Bilinmeyen bir komut ya da argümansız çağrı kullanım metnini basar.
 
@@ -280,7 +281,7 @@ yalnızca bu belirteçleri kullanın:
 | `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 |
+| `jskelet/layout` | Framework'ün varsayılan `layout.jsk` dosyasının yolu |
 
 ## Sırada ne var
 

package/docs/02-mimari.md

@@ -51,7 +51,7 @@ JSkelet bu gözlemi mimarinin merkezine alır:
  │       └─ withHtmlCache          TTL + stale-while-revalidate
  │           └─ withUpstreamTracking
  │               └─ withRequestCache
- │                   └─ controller → renderPage → EJS
+ │                   └─ controller → renderPage → .jsk (veya legacy EJS)
  ├─ 404 → hooks.notFound()
  └─ hata yönetimi                  redirect/notFound + 500 fallback
 ```
@@ -254,8 +254,9 @@ 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,
+Çalışma zamanı bağımlılıkları üçtür: `express`, `esbuild`,
+`tailwind-merge`. `ejs` yalnızca legacy `.ejs` şablonları için opsiyonel peer'dır.
+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.
 

package/docs/03-routing.md

@@ -210,7 +210,7 @@ Controller `async (ctx) => sayfa` biçimindedir ve şu alanları döndürebilir:
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `view` | `string` | — | `views/` altındaki şablon yolu, uzantısız: `"pages/home"` → `views/pages/home.ejs`. |
+| `view` | `string` | — | `views/` altındaki şablon yolu, uzantısız: `"pages/home"` → `views/pages/home.jsk` (yoksa legacy `.ejs`). |
 | `data` | `object` | `{}` | Şablona local olarak geçen veriler. |
 | `metadata` | `object` | `{}` | `<head>` etiketlerine çevrilir; `hooks.metadata()` çıktısının üzerine biner. Şema: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md). |
 | `status` | `number` | `200` | HTTP durum kodu. Yalnızca 200 önbelleğe yazılır. |
@@ -326,12 +326,17 @@ hata yöneticisi devreye girer, hatayı loglar ve framework'ün kendi hata sayfa
 `Cache-Control: no-store` ile döner. Durum kodu hatanın `statusCode` (ya da
 `status`) alanından okunur; 400–599 aralığında değilse 500 kullanılır.
 
-Framework'ün sayfası bilinçli olarak yalın: durum kodu, tek satır başlık ve tek
-satır açıklama. Marka adı, gezinme ya da hata ayrıntısı taşımaz — sunucunun içi
-ziyaretçiye açılmaz. Dil `brand.lang`ten gelir (`tr` ve `en` hazır, diğerleri
-`en`e düşer).
+**Development** (`NODE_ENV=development`, yani `jskelet dev`): 5xx yanıtlarında
+gömülü 500 sayfası ve `hooks.error()` atlanır; mesaj, yığın izi ve varsa
+`cause` zinciri içeren bir teşhis sayfası döner. 4xx (404 vb.) development'ta
+da her zamanki gibi durum sayfasıdır.
 
-Kendi sayfanı vermek için `hooks.error()`:
+**Production**: framework'ün sayfası bilinçli olarak yalın — durum kodu, tek
+satır başlık ve tek satır açıklama. Marka adı, gezinme ya da hata ayrıntısı
+taşımaz; sunucunun içi ziyaretçiye açılmaz. Dil `brand.lang`ten gelir (`tr` ve
+`en` hazır, diğerleri `en`e düşer).
+
+Kendi sayfanı vermek için `hooks.error()` (yalnızca production / 4xx):
 
 ```js
 // jskelet.config.mjs

package/docs/04-render-ve-sablonlar.md

@@ -51,7 +51,7 @@ controller data → import edilmiş render(data, helpers) → HTML
   {/if}
 
   {#each items as item, i}
-    <li data-i="{{ i }}">{{ item }}</li>
+    <li :data-i="i">{{ item }}</li>
   {/each}
 
   <Link href="/" text="Home" />
@@ -99,19 +99,30 @@ code --install-extension extensions/vscode-jsk
 
 Ayrıntılar uzantı README'sinde.
 
+### Yerleşik layout etiketleri
+
+`.jsk` ifade dilinde `asset()` / `hasAsset()` çağrılamaz. Layout’ta stylesheet,
+script ve JSON-LD döngüleri için yerleşikler:
+
+| Etiket | Props | Çıktı |
+| --- | --- | --- |
+| `Stylesheets` | `styles` | `app.css` + sayfa sheet’leri (`data-jskelet-css`) |
+| `BodyScripts` | `entries`, `devtools`, `devBasePath` | `main.js`, entry’ler, isteğe bağlı overlay |
+| `JsonLd` | `items` (`structuredData`) | `application/ld+json` script’leri |
+
 ### EJS ile birlikte yaşam
 
 Aynı `view` id için derlenmiş `.jsk` varsa o kullanılır; yoksa `.ejs` dosyası
-EJS ile render edilir. Mevcut uygulamalar değişmeden çalışır. `jskelet init`
-yeni iskeleti `.jsk` ile kurar.
+**yalnızca `ejs` peer’i kuruluysa** render edilir. `jskelet init` yeni iskeleti
+`.jsk` ile kurar.
 
-## EJS motoru (legacy)
+## EJS motoru (legacy peer)
 
-EJS hâlâ desteklenir. Motor ilk render'da bir kez kurulur; bileşen taraması
-dosya sistemine dokunduğu için her istekte yapılamaz ve config yüklenmeden
-hesaplanamaz.
+EJS opsiyonel peer bağımlılıktır (`npm i ejs`). `.jsk`-only uygulamalar kurmak
+zorunda değildir. Bir `.ejs` view veya layout istendiğinde paket uygulamadan
+yüklenir; yoksa göç yolunu gösteren bir hata fırlatılır.
 
-Ayarlar:
+Motor ilk EJS render’da bir kez kurulur. Ayarlar:
 
 | Ayar | Değer | Sebebi |
 | --- | --- | --- |
@@ -120,9 +131,7 @@ Ayarlar:
 | `rmWhitespace` | `true` | çıktı boyutu |
 | `async` | `true` | şablon içinde `await` kullanılabilir |
 
-Gömülü kullanımlar (test, script) için `resetRenderEngine()` dışa açık: bileşen
-dosyaları değişince kaydı yeniler. Dev sunucusu süreci yeniden başlattığı için
-normal akışta gerekmez.
+Gömülü kullanımlar (test, script) için `resetRenderEngine()` dışa açık.
 
 ## Layout
 
@@ -130,50 +139,33 @@ normal akışta gerekmez.
 
 1. `jskelet.config.mjs` → `layout` verilmişse o kullanılır. Yol, **views
    dizininin üst dizinine** göre çözülür: `views` varsayılansa
-   `layout: "views/ozel.ejs"` → `<root>/views/ozel.ejs`.
+   `layout: "views/ozel.jsk"` → `<root>/views/ozel.jsk`.
 2. Verilmemişse `views/layout.jsk` (derlenmiş) varsa o kullanılır.
-3. Yoksa `views/layout.ejs` varsa o kullanılır.
+3. Yoksa `views/layout.ejs` varsa o kullanılır (EJS peer gerekir).
 4. O da yoksa framework'ün kendi minimal layout'u kullanılır
-   (`node_modules/jskelet/src/templates/layout.ejs`, ayrıca
-   `jskelet/layout` belirteciyle de erişilebilir).
+   (`node_modules/jskelet/src/templates/layout.jsk`, `jskelet/layout`;
+   legacy kopya `jskelet/layout/ejs`).
 
 Üçüncü seçenek yeni bir projenin tek route ile çalışabilmesi için var. Kendi
-layout'unuza geçmenin en pratik yolu o dosyayı `views/layout.ejs` olarak
+layout'unuza geçmenin en pratik yolu o dosyayı `views/layout.jsk` olarak
 kopyalamaktır.
 
 ### Framework'ün varsayılan layout'u
 
-```ejs
+```jsk
 <!DOCTYPE html>
-<html lang="<%= lang %>">
+<html :lang="lang">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <%- extraHead %>
-    <% if (hasAsset('app.css')) { %>
-    <link rel="stylesheet" href="<%= asset('app.css') %>" data-jskelet-css="app.css">
-    <% } %>
-    <% styles.forEach(function (sheet) { %>
-      <% if (hasAsset(sheet)) { %>
-    <link rel="stylesheet" href="<%= asset(sheet) %>" data-jskelet-css="<%= sheet %>">
-      <% } %>
-    <% }); %>
-    <%- headMeta %>
-    <% structuredData.forEach(function (item) { %>
-    <script type="application/ld+json"><%- jsonScript(item) %></script>
-    <% }); %>
+    {{{ extraHead }}}
+    <Stylesheets :styles="styles" />
+    {{{ headMeta }}}
+    <JsonLd :items="structuredData" />
   </head>
-  <body class="<%= bodyClass %>">
-    <%- body %>
-    <% if (hasAsset('main.js')) { %>
-    <script type="module" src="<%= asset('main.js') %>"></script>
-    <% } %>
-    <% entries.forEach(function (entry) { %>
-    <script type="module" src="<%= asset(entry) %>"></script>
-    <% }); %>
-    <% if (devtools) { %>
-    <script type="module" src="<%= devBasePath %>/overlay.js"></script>
-    <% } %>
+  <body :class="bodyClass">
+    {{{ body }}}
+    <BodyScripts :entries="entries" :devtools="devtools" :devBasePath="devBasePath" />
   </body>
 </html>
 ```
@@ -187,7 +179,7 @@ Dikkat edilecek noktalar:
   sheet'leri de aynı şekilde basılır. Build çalışmadıysa `hasAsset` false olur
   ve etiket hiç basılmaz.
 - **`hasAsset` kontrolleri** build eksikken sayfanın 404 veren dosyaları
-  istememesini sağlar.
+  istememesini sağlar (`Stylesheets` / `BodyScripts` içinde).
 - **Devtools script'i** yalnızca `NODE_ENV=development` iken basılır; prod
   çıktısında hiç yoktur.
 

package/docs/05-islands.md

@@ -118,25 +118,29 @@ Pratik sonucu: bir modal'ı `hidden` başlatabilirsiniz, island'ı yine bağlan
 ```
 client/
 ├── entries/
-│   ├── main.js       her sayfada yüklenen ortak bootstrap
+│   ├── main.js       her sayfada yüklenen ortak bootstrap (veya main.ts)
 │   └── chart.js      yalnızca isteyen sayfalarda
 └── islands/
-    ├── counter.js
+    ├── counter.ts    .js veya .ts
     └── chart.js
 ```
 
-`client/entries/*.js` içindeki **her dosya bir esbuild entry'sidir**. `main.js`
-layout tarafından her sayfada yüklenir (manifest'te varsa). Ek entry'ler
-yalnızca onları isteyen sayfalarda yüklenir:
+`client/entries/*.{js,ts,mts}` içindeki **her dosya bir esbuild entry'sidir**.
+`main.js` (veya `main.ts`) layout tarafından her sayfada yüklenir (manifest'te
+varsa). Ek entry'ler yalnızca onları isteyen sayfalarda yüklenir. Aynı stem için
+iki uzantı (`main.js` + `main.ts`) build hatasıdır.
 
 ```js
-// controller
+// controller — manifest anahtarı her zaman *.js kalır
 return { view: "pages/markets", entries: ["chart.js"] };
 ```
 
 Layout `entries` dizisindeki her adı `asset(entry)` ile çözüp bir
-`<script type="module">` basar. Ad manifest anahtarıdır, yani dosya adının
-kendisi (`chart.js`), hash'li hâli değil.
+`<script type="module">` basar. Ad manifest anahtarıdır (`chart.js`), kaynak
+dosya `chart.ts` olsa bile hash'siz anahtar `.js` kalır.
+
+Paylaşılan `@/lib` modülleri sunucuda da import ediliyorsa **`.js` kalsın** —
+Node runtime `.ts` çözmez; `.ts` yalnızca esbuild client hattında derlenir.
 
 Kod bölme (`splitting: true`) açık: iki entry'nin paylaştığı modüller ortak bir
 chunk'a çıkar ve iki kez indirilmez.

package/docs/07-yapilandirma.md

@@ -51,7 +51,7 @@ export default {
     lang: "tr",
   },
 
-  layout: "views/layout.ejs",
+  layout: "views/layout.jsk",
   routes: ["./routes/10-pages.mjs", "./routes/99-catch-all.mjs"],
   trailingSlash: false,
 
@@ -88,7 +88,7 @@ export default {
   watch: ["data"],
 
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["indirmeler"] },
   clientEnv: ["PUBLIC_WS_URL"],
 
@@ -208,26 +208,32 @@ session id taşımak için handoff köprüsünü açar.
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` veya `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | Açıkken `POST /_jskelet/auth/handoff` + `?handoff=` redeem. Object: `allowedCookieNames` (zorunlu), `ttlSeconds?`, `path?`, `maxValueBytes?`, `maxPendingTickets?`, `maxMintsPerIpPerMinute?` |
 
 ```js
 auth: {
-  crossSubdomainHandoff: { ttlSeconds: 60 },
+  crossSubdomainHandoff: {
+    allowedCookieNames: ["sid"],
+    ttlSeconds: 60,
+  },
 },
 ```
 
-Ayrıntı ve `window.name` yedeği: [12-panel-ve-oturum.md](./12-panel-ve-oturum.md).
+Mint uç noktası CSRF middleware'inden **sonra** mount edilir (origin kontrolü).
+Cookie adı allowlist dışındaysa veya RFC 6265 token değilse 400. Ayrıntı:
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md).
 
 ## `layout`
 
 **Tip:** `string` — **Varsayılan:** yok (otomatik çözüm)
 
-Layout `.ejs` dosyasının yolu. Verilen değer **views dizininin üst dizinine**
-göre çözülür, yani varsayılan `views` ile `"views/ozel.ejs"` →
-`<root>/views/ozel.ejs`.
+Layout dosyasının yolu (`.jsk` veya legacy `.ejs`). Verilen değer **views
+dizininin üst dizinine** göre çözülür, yani varsayılan `views` ile
+`"views/ozel.jsk"` → `<root>/views/ozel.jsk`.
 
-Verilmezse sırayla: `views/layout.jsk`, `views/layout.ejs`, yoksa framework'ün
-minimal layout'u. Ayrıntı: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md).
+Verilmezse sırayla: `views/layout.jsk`, `views/layout.ejs` (legacy), yoksa
+framework'ün `src/templates/layout.jsk` varsayılanı. Ayrıntı:
+[04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md).
 
 ## `routes`
 
@@ -328,7 +334,7 @@ var.
 | `trustProxy` | `boolean` | `true` | Express'in `trust proxy` ayarı. Ters proxy arkasında doğru protokol ve istemci IP'si için gerekli. |
 | `cookieSecret` | `string \| null` | `null` | İmzalı cookie sırrı. Verilmezse `JSKELET_SECRET` okunur. |
 | `csrf.enabled` | `boolean` | `true` | Origin/`Sec-Fetch-Site` kontrolü. |
-| `csrf.token` | `boolean` | `false` | Çift gönderim token'ı katmanı. |
+| `csrf.token` | `boolean` | `false` | Çift gönderim token'ı katmanı. Cookie oturumlu formlarda **açın**. |
 | `csrf.allowedOrigins` | `string[]` | `[]` | Kendi host'umuzun yanında kabul edilen origin'ler. |
 | `csrf.exclude` | `string[]` | `[]` | Kontrolden muaf yollar; `source` desen sözdizimi. |
 | `csrf.cookieName` | `string` | `"csrf_token"` | Token cookie'sinin adı. |
@@ -336,14 +342,17 @@ var.
 | `csrf.headerName` | `string` | `"x-csrf-token"` | Token'ın kabul edildiği başlık. |
 
 `trustProxy` doğrudan internete açık bir sunucuda **kapatılmalı**: açıkken
-istemci kendi `X-Forwarded-For` başlığını uydurabilir ve rate limit ile audit
-log yanlış adresi görür.
+istemci kendi `X-Forwarded-For` / `X-Forwarded-Proto` / Host başlığını
+uydurabilir; rate limit, admin IP allowlist, Secure cookie ve cache `vary.host`
+yanlış adresi görür. Ters proxy (nginx, Caddy, Cloudflare) arkasındaysa `true`
+doğru varsayılandır.
 
 CSRF kontrolü yalnızca çapraz site olduğu **belli** olan istekleri reddeder —
 `Origin` uyuşmuyorsa ya da `Sec-Fetch-Site: cross-site` geldiyse. İkisi de yoksa
 istek geçer, çünkü tarayıcılar çapraz origin bir POST'ta `Origin`'i her zaman
-gönderirken webhook'lar hiç göndermez. Yine de tarayıcıdan gelmeyen uçları
-`csrf.exclude` listesine yazmak niyeti okunur kılıyor.
+gönderirken webhook'lar hiç göndermez. Cookie ile oturum açan panel/form
+uygulamalarında `csrf.token: true` + `csrfField()` ikinci katmandır; webhook
+uçlarını `csrf.exclude` listesine yazın.
 
 ## `navigation`
 
@@ -487,21 +496,27 @@ fonts: [
 
 ## `icons`
 
-**Tip:** `{ scan?: string[] } | false` — **Varsayılan:** `{}`
+**Tip:** `{ scan?: string[], dir?: string } | false` — **Varsayılan:** `{ dir: "icons" }`
 
-Phosphor SVG sprite üretimi.
+SVG ikon sprite üretimi. Kaynak **XOR** seçilir: `icons.dir` dizini varsa
+yalnızca oradaki düz SVG'ler; yoksa `@phosphor-icons/core` (kuruluysa).
 
 | Değer | Sonuç |
 | --- | --- |
-| `{}` (varsayılan) | Sprite üretilir; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{}` (varsayılan) | `dir: "icons"`; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Yerel SVG kökü değiştirilir |
 | `{ scan: [...] }` | Taranan dizinler değiştirilir |
 | `false` | Sprite adımı tamamen atlanır |
 
-`@phosphor-icons/core` uygulamanın `node_modules`'ünde yoksa adım sessizce
-atlanır. Ayrıntı: [08-build.md](./08-build.md).
+Yerel dizin (varsa) düz dosya adları kullanır: `house.svg` → `house:regular`,
+`house-bold.svg` → `house:bold`. Boş bir `icons/` dizini Phosphor'a düşmez —
+dizini silmek fallback'i açar. Ayrıntı: [08-build.md](./08-build.md).
 
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 
 ## `images`
@@ -534,7 +549,9 @@ icons: { scan: ["views", "client", "routes", "lib", "content"] }
 
 `false` verilirse görsel adımı hiç çalışmaz. Build adımı `sharp` gerektirir ve
 watch turunda hiç çalışmaz. Remote açıksa `sharp` **runtime**'da da gerekir;
-yoksa optimizer kaynak URL'ye 302 yönlendirir. Ayrıntı: [08-build.md](./08-build.md).
+yoksa optimizer kaynak URL'ye 302 yönlendirir. Fetch, redirect'leri otomatik
+takip etmez: her hop `allowHosts` ve private adres kontrolünden geçer.
+Ayrıntı: [08-build.md](./08-build.md).
 
 ```js
 images: {
@@ -567,6 +584,9 @@ clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 ```
 
 **Buraya gizli anahtar koymayın** — değerler bundle'da düz metin olarak durur.
+İsimlerinde `SECRET`, `PASSWORD`, `TOKEN`, `API_KEY`, `PRIVATE` vb. geçen
+anahtarlar build sırasında **reddeder** (`PUBLIC` / `PUBLISHABLE` içerenler
+muaf).
 
 ## `headers()`
 
@@ -575,7 +595,8 @@ clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 
 Yol desenine göre yanıt başlıkları. Framework yalnızca statik dosyalara uzun
 ömürlü cache yazar; bunun dışındaki her başlık (CSP, COOP, HSTS,
-X-Frame-Options…) buradan gelir ve varsayılanların üstüne biner.
+X-Frame-Options…) buradan gelir ve varsayılanların üstüne biner. Üretim
+sitelerinde en azından aşağıdaki güvenlik başlıklarını tanımlayın.
 
 Eşleşen **tüm** kurallar uygulanır (redirect'lerin aksine ilk eşleşmede
 durulmaz), sırayla; aynı başlığı iki kural yazarsa sonraki kazanır.
@@ -590,11 +611,18 @@ async headers() {
       source: "/:path*",
       headers: [
         { key: "X-Frame-Options", value: "SAMEORIGIN" },
+        { key: "X-Content-Type-Options", value: "nosniff" },
         { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
         {
           key: "Content-Security-Policy",
-          value: "default-src 'self'; img-src 'self' https://cdn.ornek.com data:",
+          value: "default-src 'self'; img-src 'self' https://cdn.ornek.com data:; script-src 'self'",
         },
+        // Yalnızca HTTPS terminasyonu sizin kontrolünüzdeyse:
+        // { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains" },
       ],
     },
     {
@@ -1075,7 +1103,7 @@ basılmaz.
 | Değişken | Kim okur | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
 | `NODE_ENV` | her yer | `production` (start/build), `development` (dev) | Dev overlay, EJS cache, manifest yeniden okuma, route hata davranışı ve prewarm varsayılanlarını belirler. `jskelet dev` bunu kendisi ayarlar — `cross-env` gerekmez. |
-| `PORT` | `startServer` | `3000` | Dinlenecek port |
+| `PORT` | `startServer` | `3000` | Dinlenecek port. Doluysa süreç başlamaz; `jskelet start|dev --murder` dinleyiciyi öldürür |
 | `HOST` | `startServer` | `::` | Bağlanılacak arayüz. Varsayılan çift yığın dinler (IPv6 + IPv4); IPv6 yoksa `0.0.0.0`'a düşer |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | İmzalı cookie sırrı. `security.cookieSecret` verilmediğinde buradan okunur; ikisi de yoksa imzalı cookie API'si hata verir. [12](./12-panel-ve-oturum.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |

package/docs/08-build.md

@@ -167,8 +167,9 @@ 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.
+`client/entries/*.{js,ts,mts}` içindeki her kaynak dosya bir entry'dir (`.tsx`
+yok). Manifest anahtarı her zaman `*.js` olur (`main.ts` → `main.js`). Aynı stem
+için birden fazla uzantı build hatasıdır. Dizin yoksa ya da boşsa adım atlanır.
 
 esbuild ayarları:
 
@@ -178,7 +179,7 @@ esbuild ayarları:
 | `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 |
+| `sourcemap` | yalnızca `NODE_ENV=development` | Prod'da `.map` dosyaları `public/assets` altında yayınlanmaz |
 | `entryNames` | `[name].[hash]` | `immutable` cache |
 | `chunkNames` | `chunks/[name].[hash]` | — |
 | `legalComments` | `none` | — |
@@ -189,16 +190,19 @@ esbuild ayarları:
 ### `@/` 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.
+(`.js`, `.mjs`, `.ts`, `.mts`, `.json`, `/index.js`, `/index.ts`). Node
+`alias-hooks.mjs` sunucuda yalnızca `.js` / `.mjs` / `.json` çözer; paylaşılan
+`@/lib` dosyaları bu yüzden `.js` kalmalıdır. Client-only `.ts` import'ları
+esbuild hattında çalışır.
 
 ### `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).
+çökme yerine `undefined` döner. İsimleri secret benzeri olan anahtarlar
+(`SECRET`, `API_KEY`, …) build'i düşürür; `PUBLIC` / `PUBLISHABLE` içerenler
+muaf. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ### Manifest anahtarları
 
@@ -249,16 +253,32 @@ 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.
+**Yalnızca kaynakta kullanılan** ikonlar için bir `<symbol>` seti üretir. Tüm
+seti göndermek 1500+ ikon, yani birkaç megabayt; kullanım taraması sprite'ı
+tipik olarak 10-30 sembolde tutuyor. Çıktı hash'li `sprite.svg` olarak
+`public/assets/` altına yazılır ve precompress kapsamına girer.
+
+Kaynak **XOR** seçilir — ikisi birleştirilmez:
+
+1. `icons.dir` (varsayılan `icons/`) **dizin olarak varsa** yalnızca oradaki
+   düz SVG'ler. Boş dizin Phosphor'a düşmez; fallback için dizini silin.
+2. Aksi hâlde `@phosphor-icons/core` (uygulamanın `node_modules`'ünden). Kurulu
+   değilse adım sessizce atlanır.
+
+Yerel dosya adları:
+
+| Dosya | Sprite anahtarı |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 
 - 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`.
+- `viewBox` kaynak SVG'den `<symbol>`'e taşınır; yoksa `0 0 256 256`
+  (Phosphor ve `icon()` ile uyum için önerilen kutu).
+- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; `icons.scan` ile değiştirilebilir. Taranan uzantılar:
+  `.ejs`, `.jsk`, `.js`, `.mjs`, `.ts`, `.mts`.
 - Ağırlıklar: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. Tanınmayan
   bir ağırlık `regular` sayılır.
 
@@ -285,7 +305,7 @@ 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:
+Kaynakta bulunamayan adlar build sonunda özet olarak uyarılır:
 `N icons missing → …`
 
 ## Görsel optimizasyonu
@@ -323,7 +343,9 @@ orijinal dosyaya döner. Watch turunda hiç çalışmaz.
 `images.remote.allowHosts` verilirse `createApp` `/_jskelet/image` ucunu
 mount eder. CMS / CDN kapakları build'e girmediği için `image()` bu host'lardaki
 URL'leri `?url=&w=` biçiminde yeniden yazar; uç sharp ile webp üretir ve
-`.jskelet/image-cache/` altına yazar. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
+`.jskelet/image-cache/` altına yazar. Upstream fetch redirect'leri elle takip
+edilir: her hop allowlist + private IP / DNS kontrolünden geçer (açık redirect
+SSRF kapalı). Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ## Precompress
 
@@ -355,7 +377,7 @@ Bu dosyaları `staticPrecompressed` middleware'i servis eder; kopya yoksa istek
 | `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 |
+| `@phosphor-icons/core` | İkon sprite (yerel `icons/` yoksa) | 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.