jskelet 0.5.5 → 0.6.0

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ı
 
@@ -274,7 +278,7 @@ Yerel dosya adları:
   (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`.
+  `.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.
 
@@ -339,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
 

package/docs/09-dev-araclari.md

@@ -21,6 +21,10 @@ jskelet dev
 bastırır) ve TTY varsa `JSKELET_COLOR=1` (borulanmış çıktıda renk zorlar)
 geçirilir.
 
+Port (`PORT`, varsayılan `3000`) doluysa sunucu **başlamaz**; hata satırında
+PID ve `--murder` ipucu vardır. `jskelet dev --murder` dinleyiciyi öldürüp aynı
+porta bağlanır (başka bir terminalde unutulmuş süreç için).
+
 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.
@@ -70,7 +74,7 @@ WATCH_DIRS = [
 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`.
+İzlenen uzantılar: `.js`, `.mjs`, `.json`, `.jsk`, `.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

package/docs/10-dagitim.md

@@ -23,6 +23,10 @@ kendisi çalıştırır. Docker imajında build zaten yapıldığı için bu bir
 amaç `npm start`ı doğrudan çalıştıran birinin stilsiz bir sayfayla
 karşılaşmaması.
 
+Port doluysa süreç **başlamaz** (PID + ipucu). `jskelet start --murder` o
+porttaki dinleyiciyi öldürüp bağlar — geliştirmede unutulmuş bir süreç için;
+üretim orkestratöründe genelde gerekmez.
+
 Sunucu hazır olduğunda tek satır basar:
 
 ```
@@ -63,7 +67,8 @@ değerin geçerli olduğunu belirsizleştirir; prod imajında `.env` bulundurmam
 temizidir.
 
 **Gizli anahtarlar `clientEnv` listesine konmamalıdır:** oradaki değerler client
-bundle'a düz metin olarak gömülür ([08-build.md](./08-build.md)).
+bundle'a düz metin olarak gömülür ([08-build.md](./08-build.md)). Secret benzeri
+isimler (`SECRET`, `API_KEY`, …) artık build'i düşürür.
 
 ## Docker
 

package/docs/11-tasima.md

@@ -7,6 +7,29 @@ alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()
 `revalidate`, `cache()` gibi kavramlar tanıdık gelecek. Farkların *nedenleri*
 [02-mimari.md](./02-mimari.md)'de.
 
+## `jskelet migrate` (codemod)
+
+App Router ağacına karşı codemod'u çalıştırın. Babel (`@babel/parser`,
+`@babel/types`) JSkelet ile birlikte gelir — ek kurulum yok.
+
+```bash
+npx jskelet migrate scan ../my-next-app
+npx jskelet migrate apply ../my-next-app --out . --write
+npx jskelet migrate config ../my-next-app --write
+```
+
+| Komut | Ne yapar |
+| --- | --- |
+| `migrate` / `migrate scan` | Sayfa, layout, `"use client"` modülleri ve engelleri (iç içe layout, Server Actions, Suspense) listeler. |
+| `migrate apply` | **Otomatik çeviri:** `page.*` → feature controller + `.jsk`; presentational bileşenler → `views/components/*.js`; client → island `mount()` iskeleti. Varsayılan dry-run; yazmak için `--write`. Üzerine yazmaz (çakışmada `.migrate` soneki). |
+| `migrate config` | `next.config`'ten `jskelet.config.mjs` taslağı (`headers` / `redirects` / `rewrites`, `images.widths`, `NEXT_PUBLIC_*` → `clientEnv`). |
+
+Bayraklar: `--out <dir>`, `--only pages,components,islands`, `--json`, `--strict` (partial/skipped → exit 1).
+
+**Otomatik çevrilenler:** `className`, `{{ }}` / `{{{ }}}`, `{#if}` / `{#each}`, `next/image` → `<Image />`, `next/link` → `<Link />`, `dangerouslySetInnerHTML`, `revalidate`, basit controller prelude.
+
+**Çevrilmeyenler (raporlanır):** React hooks, Server Actions, iç içe layout düzleştirme, Streaming/Suspense, client routing. Dosya başına `ok` / `partial` / `skipped`.
+
 ## Karşılık tablosu
 
 ### Yapılandırma
@@ -30,8 +53,8 @@ alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()
 | `app/page.js` (dosya bazlı routing) | `routes/*.mjs` içinde `app.get(...)` | Sıra açık yazılır ([03](./03-routing.md)) |
 | `app/[slug]/page.js` | `app.get("/:slug", route(...))` | Express desen sözdizimi |
 | `params`, `searchParams` | `ctx.params`, `ctx.query` | Controller'ın tek argümanı |
-| `layout.js` | `views/layout.ejs` + `hooks.layoutContext()` | Tek layout; iç içe layout yok |
-| Sunucu bileşeni (RSC) | Controller + EJS şablonu + `views/components/**` | Fonksiyon HTML string döndürür |
+| `layout.js` | `views/layout.jsk` + `hooks.layoutContext()` | Tek layout; iç içe layout yok |
+| Sunucu bileşeni (RSC) | Controller + `.jsk` şablonu + `views/components/**` | Fonksiyon HTML string döndürür |
 | İstemci bileşeni (`"use client"`) | Island (`data-island` + `mount`) | Sayfanın tamamı hidre edilmez ([05](./05-islands.md)) |
 | `notFound()` | `notFound()` | Aynı ad, aynı kontrol akışı |
 | `redirect()` | `redirect()` (307) | Kalıcı için `permanentRedirect()` (308) |
@@ -87,10 +110,13 @@ Bunları taşıma planında baştan hesaba katın:
 
 - **React'in kendisi.** Bileşenler HTML string döndüren fonksiyonlara dönüşür.
   JSX yok, hook yok, sanal DOM yok.
-- **TypeScript.** Proje düz JS + JSDoc. `jsconfig.json` içinde `checkJs: true`
-  ile editörden tip kontrolü alırsınız.
-- **İç içe layout'lar.** Tek bir layout var; ortak bölümleri EJS `include` ya da
-  bileşen fonksiyonlarıyla paylaşırsınız.
+- **TypeScript.** Framework kaynağı düz JS + JSDoc'tur ve tüketiciler için
+  `.d.ts` yayınlar. Client entry/island'lar `.ts` / `.mts` olabilir (esbuild tip
+  siler; manifest anahtarı `*.js` kalır). Sunucu route, hook ve
+  `jskelet.config.mjs` Node ESM JavaScript kalır — orada editör denetimi için
+  `jsconfig.json` içinde `checkJs: true` kullanın.
+- **İç içe layout'lar.** Tek bir layout var; ortak bölümleri `{#include}` ya da
+  bileşen fonksiyonlarıyla paylaşırsınız (legacy EJS’te `include`).
 - **Streaming / Suspense / kısmi prerender.** Yanıt tek parça üretilir.
 - **İstemci tarafı yönlendirme.** Gezinme gerçek sayfa yüklemesidir. Sunucu HTML'i
   önbellekten geldiği için pratikte çok hızlıdır, ama SPA geçişleri yoktur.
@@ -169,12 +195,12 @@ export default function register(app, { route, notFound }) {
 }
 ```
 
-```ejs
-<%# views/pages/article.ejs %>
+```jsk
+{# views/pages/article.jsk #}
 <article class="wrapper">
-  <h1 class="text-3xl font-bold"><%= article.title %></h1>
-  <%- image({ src: article.cover, alt: article.title, priority: true, width: 1200, height: 630 }) %>
-  <div><%- article.body %></div>
+  <h1 class="text-3xl font-bold">{{ article.title }}</h1>
+  <Image :src="article.cover" :alt="article.title" priority :width="1200" :height="630" />
+  <div>{{{ article.body }}}</div>
 </article>
 ```
 
@@ -188,12 +214,16 @@ de aynı yazıyı isterse tek upstream isteği yapılmasını sağlar
 
 Yeni bir dizinde `npx jskelet init` çalıştırın ve `jskelet dev`in açıldığını
 görün. Mevcut Next projesini olduğu gibi bırakın; taşıma paralel yürüsün.
+İsterseniz önce `jskelet migrate scan <next-root>` ile sayfa ve engel listesine bakın.
 
 `jsconfig.json` içindeki `paths` alias'larınızı taşıyın — `@/` gibi önekler hem
 sunucuda hem bundle'da aynı şekilde çalışır ([02-mimari.md](./02-mimari.md)).
 
 ### 2. `next.config.mjs`'i çevir (1-2 saat)
 
+`jskelet migrate config <next-root> --write` çoğunu taslaklar; ardından gözden
+geçirin:
+
 `headers()`, `redirects()` ve `rewrites()` bölümleri neredeyse birebir kopyalanır.
 Desen sözdizimini kontrol edin: JSkelet `:slug`, `:path*`, `/a-:b` ve
 `/:path*.svg` biçimlerini destekler; daha karmaşık `path-to-regexp` ifadeleri
@@ -214,9 +244,9 @@ değildir; olduğu gibi kopyalanır. İki değişiklik yapın:
 
 ### 4. Layout'u kur (yarım gün)
 
-`app/layout.jsx`'i `views/layout.ejs`'e çevirin. Framework'ün varsayılan
-layout'unu (`node_modules/jskelet/src/templates/layout.ejs`) kopyalayıp
-üzerine yazmak en hızlı yol.
+`app/layout.jsx`'i `views/layout.jsk`'e çevirin (veya `migrate apply` taslağını
+kullanın). Framework'ün varsayılan layout'unu (`jskelet/layout` → `.jsk`)
+kopyalayıp üzerine yazmak en hızlı yol.
 
 `layout.jsx` içinde veri çekiyorsanız (navigasyon, site ayarları) bunu
 `hooks.layoutContext()` içine taşıyın: gövde render'ıyla paralel çalışır ve
@@ -227,6 +257,9 @@ Global metadata varsayılanlarını (`titleTemplate`, `siteUrl`, `description`)
 
 ### 5. Bileşenleri çevir (en uzun adım)
 
+`jskelet migrate apply --only components --write` hooks'suz presentational
+bileşenleri çevirir. Gerisini elle bitirin:
+
 Her React bileşeni bir fonksiyona dönüşür:
 
 ```jsx
@@ -260,8 +293,9 @@ Bileşenleri küçük ve saf tutun; veri çekmeyi controller'da bırakın.
 
 ### 6. Sayfaları taşı (sayfa başına saatler)
 
-Her `page.jsx` bir controller + bir EJS şablonuna bölünür. Sırayı düşünerek
-dosyalayın:
+`jskelet migrate apply --only pages --write` her `page.*` dosyasını feature
+controller + `.jsk` şablonuna böler. `partial` / `skipped` satırlarını gözden
+geçirip TODO'ları bitirin. Sırayı düşünerek dosyalayın:
 
 ```
 routes/
@@ -337,7 +371,7 @@ redirect kurallarının doğruluğunu ölçmek için işe yarar.
 ## Taşıma sırasında sık yapılan hatalar
 
 - **`esc()` unutmak.** JSX'ten gelen alışkanlıkla `${value}` yazmak XSS demektir.
-  Şablonlarda `<%= %>` (kaçışlı) ile `<%- %>` (ham) ayrımına dikkat edin.
+  `.jsk`'de `{{ }}` (kaçışlı) / `{{{ }}}` (ham); bileşenlerde `esc()` kendiniz.
 - **`@source` eklemeden yeni bir dizin açmak.** Sınıflar sessizce düşer.
 - **Yakalayıcı route'u yanlış sıraya koymak.** `/:slug` her zaman en sonda.
 - **Sayfanın tamamını island yapmak.** Kazanç sunucu HTML'inin tam olmasından

package/docs/12-panel-ve-oturum.md

@@ -143,7 +143,9 @@ export default {
     sharedCookieRoots: [".investvio.com", ".localhost"],
   },
   auth: {
-    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+    crossSubdomainHandoff: {
+      allowedCookieNames: ["sid"], // zorunlu allowlist
+    },
   },
 };
 ```
@@ -207,15 +209,19 @@ okunur. Yazımdan sonra **read-back** yapılır; tarayıcı Domain'i reddettiyse
 
 `auth.crossSubdomainHandoff` açıkken:
 
-1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (`?handoff=` ekli)
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (`?handoff=` ekli).
+   Mint, CSRF middleware'inden **sonra** mount edilir; `name`
+   `allowedCookieNames` içinde ve RFC 6265 token olmalı.
 2. Hedef host'ta GET middleware bileti tek kullanımlık tüketir, cookie yazar
    (önce shared Domain, olmazsa host-only), `handoff` query'siz 303
 
 `next` yalnızca aynı `sharedCookieRoots` altındaki host'lara izinli. Bilet
-~60 sn, süreç belleğinde. JWT URL'ye konmaz.
+~60 sn, süreç belleğinde; bekleyen bilet ve IP başına mint sınırı vardır.
+JWT URL'ye konmaz.
 
 `window.name` köprüsü cookie'siz yedek: kaynakta `handoffViaWindowName`,
-hedeefte `consumeWindowNameHandoff`.
+hedeefte `consumeWindowNameHandoff`. Cross-origin tab'da `window.name`
+okunabilir kalır — mümkünse sunucu handoff tercih edin.
 
 ## CSRF
 

package/docs/README.md

@@ -1,10 +1,12 @@
 # JSkelet belgeleri
 
 JSkelet, SEO ve hız odaklı siteler için "framework'süz hissettiren" bir
-framework: Express 5 + EJS ile sunucuda tam HTML üretir, etkileşimi vanilla JS
-island'larla ekler, CSS'i Tailwind v4 ile tek bir stylesheet'e derler ve ISR
-yerine süreç belleğinde yaşayan, stale-while-revalidate'li bir HTML TTL cache
-kullanır. React yok, TypeScript yok; düz JavaScript ve JSDoc.
+framework: Express 5 + build-time `.jsk` ile sunucuda tam HTML üretir (EJS
+opsiyonel legacy peer), etkileşimi vanilla JS island'larla ekler, CSS'i
+Tailwind v4 ile tek bir stylesheet'e derler ve ISR yerine süreç belleğinde
+yaşayan, stale-while-revalidate'li bir HTML TTL cache kullanır. React yok;
+framework kaynağı düz JavaScript + JSDoc'tur. Uygulama tarafında client
+island/entry'ler TypeScript yazılabilir ve paket `.d.ts` yayınlar.
 
 Bu dizin framework'ün tam referansıdır. Sıralı okumak için baştan başlayın;
 belirli bir konuyu arıyorsanız doğrudan ilgili başlığa gidin.
@@ -19,7 +21,7 @@ eşlenik tutuluyor; birini değiştiriyorsan diğerini de değiştir.
 | [01-baslangic.md](./01-baslangic.md) | Kurulum, `jskelet init`, ilk route, ilk island, dizin yapısı, CLI komutları |
 | [02-mimari.md](./02-mimari.md) | Mimari kararlar ve gerekçeleri: island modeli, tam sunucu HTML'i, cache stratejisi, middleware sırası |
 | [03-routing.md](./03-routing.md) | Route modülü sözleşmesi, yükleme sırası, controller sözleşmesi, `ctx`, `notFound`/`redirect`, config redirects/rewrites |
-| [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md) | EJS layout, sayfalar, otomatik bileşen kaydı, `html`/`tags` yardımcıları, metadata → `<head>`, hook'lar |
+| [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md) | `.jsk` layout/sayfalar, otomatik bileşen kaydı, `html`/`tags`, metadata → `<head>`, hook'lar; EJS legacy |
 | [05-islands.md](./05-islands.md) | `data-island` sözleşmesi, hidrasyon stratejileri, `client/entries/*`, `createStore`, DOM yardımcıları, `startSafeImages` |
 | [06-cache.md](./06-cache.md) | `withHtmlCache`, `revalidate`, stale-while-revalidate, cache anahtarı, `X-JSkelet-Cache`, istek içi cache, degraded render, prewarm |
 | [07-yapilandirma.md](./07-yapilandirma.md) | `jskelet.config.mjs` tam referansı, `source` desen sözdizimi, ortam değişkenleri tablosu |

package/docs/en/01-getting-started.md

@@ -255,11 +255,12 @@ ESM resolve hooks (`--import`) at process start.
 
 | Command | What it does |
 | --- | --- |
-| `jskelet dev` | Build watch + server, in a single terminal. Live reload, CSS hot-swap, dev overlay. `NODE_ENV=development`. |
+| `jskelet dev` | Build watch + server, in a single terminal. Live reload, CSS hot-swap, dev overlay. `NODE_ENV=development`. Refuses to start if the port is busy; `--murder` kills the listener and binds. |
 | `jskelet build` | One-shot prod build: fonts → icon sprite → CSS → client JS → images → manifest → precompress. `production` if `NODE_ENV` is not given. |
-| `jskelet start` | Prod server. If there is no build output it produces it first. `production` if `NODE_ENV` is not given. |
+| `jskelet start` | Prod server. If there is no build output it produces it first. `production` if `NODE_ENV` is not given. Same port behaviour as `dev` (`--murder`). |
 | `jskelet init` | Installs a feature-first `.jsk` skeleton into the current directory; leaves existing files alone. |
 | `jskelet generate` | Scaffolds a `feature` / `page` / `island`. |
+| `jskelet migrate` | Next.js App Router → JSkelet codemod (`scan` / `apply` / `config`). See [11-migration.md](./11-migration.md). |
 
 An unknown command, or a call with no arguments, prints the usage text.
 
@@ -287,7 +288,7 @@ only these specifiers:
 | `jskelet/tags` | `link`, `image`, `icon`, `preloadImage`, `toKebab` |
 | `jskelet/log` | Console output helpers (`banner`, `event`, `task`, `size`, `ms`, …) |
 | `jskelet/register` | Alias + extension hooks via `node --import jskelet/register` |
-| `jskelet/layout` | The path to the framework's default `layout.ejs` file |
+| `jskelet/layout` | The path to the framework's default `layout.jsk` file |
 
 ## What's next
 

package/docs/en/02-architecture.md

@@ -51,7 +51,7 @@ Request
  │       └─ withHtmlCache          TTL + stale-while-revalidate
  │           └─ withUpstreamTracking
  │               └─ withRequestCache
- │                   └─ controller → renderPage → EJS
+ │                   └─ controller → renderPage → .jsk (or legacy EJS)
  ├─ 404 → hooks.notFound()
  └─ error handling                 redirect/notFound + 500 fallback
 ```
@@ -270,10 +270,10 @@ hard-to-diagnose problems like "why is there no stylesheet".
 
 ## Why this dependency list
 
-There are four runtime dependencies: `express`, `ejs`, `esbuild`,
-`tailwind-merge`. Everything else (Tailwind, PostCSS, lightningcss, sharp, the
-Phosphor icons) is an **optional peer dependency**, and if it is absent the
-corresponding build step is skipped.
+There are three runtime dependencies: `express`, `esbuild`, `tailwind-merge`.
+`ejs` is an optional peer only for legacy `.ejs` templates. Everything else
+(Tailwind, PostCSS, lightningcss, sharp, the Phosphor icons) is an **optional
+peer dependency**, and if it is absent the corresponding build step is skipped.
 
 Two decisions deserve a separate explanation:
 

package/docs/en/03-routing.md

@@ -213,7 +213,7 @@ fields:
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `view` | `string` | — | The template path under `views/`, without the extension: `"pages/home"` → `views/pages/home.ejs`. |
+| `view` | `string` | — | The template path under `views/`, without the extension: `"pages/home"` → `views/pages/home.jsk` (else legacy `.ejs`). |
 | `data` | `object` | `{}` | Data passed to the template as locals. |
 | `metadata` | `object` | `{}` | Turned into `<head>` tags; it overrides the output of `hooks.metadata()`. Schema: [04-rendering.md](./04-rendering.md). |
 | `status` | `number` | `200` | The HTTP status code. Only 200 is written to the cache. |
@@ -332,13 +332,18 @@ handler kicks in, logs the error and returns the framework's own error page with
 `Cache-Control: no-store`. The status code is read from the error's `statusCode`
 (or `status`) field; if it is not in the 400–599 range, 500 is used.
 
-The framework's page is deliberately plain: the status code, a one-line heading
-and a one-line description. It carries no brand name, no navigation and no error
-detail — the innards of the server are not opened up to the visitor. The
-language comes from `brand.lang` (`tr` and `en` are built in, others fall back
-to `en`).
+**Development** (`NODE_ENV=development`, i.e. `jskelet dev`): for 5xx responses
+the built-in 500 page and `hooks.error()` are skipped; a diagnostic page with
+the message, stack trace, and any `cause` chain is returned instead. 4xx (404
+and friends) still use the usual status page in development.
 
-To provide your own page, `hooks.error()`:
+**Production**: the framework's page is deliberately plain — status code, a
+one-line heading and a one-line description. It carries no brand name, no
+navigation and no error detail; the innards of the server are not opened up to
+the visitor. The language comes from `brand.lang` (`tr` and `en` are built in,
+others fall back to `en`).
+
+To provide your own page, `hooks.error()` (production / 4xx only):
 
 ```js
 // jskelet.config.mjs

package/docs/en/04-rendering.md

@@ -52,7 +52,7 @@ controller data → imported 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" />
@@ -68,7 +68,7 @@ controller data → imported render(data, helpers) → HTML
 | Loop | `{#each list as item}` or `as item, i` |
 | Include | `{#include "partials/header"}` (compiled `.jsk`) |
 | Component | PascalCase tag; `:prop="expr"`, `prop="literal"`, boolean `disabled` |
-| Built-ins | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage` |
+| Built-ins | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage`, `Stylesheets`, `BodyScripts`, `JsonLd` |
 
 The expression language is intentionally small (access, compare, ternary,
 `.length`). No assignments, object literals, or arbitrary calls — keep logic in
@@ -104,12 +104,15 @@ See the extension README for details.
 
 If a compiled `.jsk` exists for a view id it wins; otherwise `.ejs` is rendered
 with EJS. Existing apps keep working unchanged. `jskelet init` scaffolds `.jsk`.
+Legacy `.ejs` needs the optional `ejs` peer installed in the application
+(`npm install ejs`); without it only `.jsk` templates run.
 
 ## The EJS engine (legacy)
 
-EJS remains supported. The engine is set up once on the first render; the
-component scan touches the file system, so it cannot be done on every request
-and cannot be computed before the config is loaded.
+EJS remains supported as an **optional peer dependency** for legacy templates.
+The engine is set up once on the first render; the component scan touches the
+file system, so it cannot be done on every request and cannot be computed
+before the config is loaded.
 
 Settings:
 
@@ -130,66 +133,54 @@ normal flow because the dev server restarts the process.
 
 1. `jskelet.config.mjs` → if `layout` is given, it is used. The path is
    resolved relative to the **parent directory of the views directory**: if
-   `views` is the default, `layout: "views/custom.ejs"` → `<root>/views/custom.ejs`.
+   `views` is the default, `layout: "views/custom.jsk"` → `<root>/views/custom.jsk`.
 2. If it is not given and `views/layout.jsk` exists (compiled), that is used.
-3. Else if `views/layout.ejs` exists, that is used.
+3. Else if `views/layout.ejs` exists (legacy), that is used.
 4. If that does not exist either, the framework's own minimal layout is used
-   (`node_modules/jskelet/src/templates/layout.ejs`, also reachable through the
+   (`node_modules/jskelet/src/templates/layout.jsk`, also reachable through the
    `jskelet/layout` specifier).
 
 These fallbacks exist so that a new project can work with a single route. The
 most practical way to move to your own layout is to copy that file to
-`views/layout.ejs` or author `views/layout.jsk`.
+`views/layout.jsk`.
 
 ### The framework's default layout
 
-```ejs
+```html
 <!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>
 ```
 
+The `.jsk` expression language has no function calls, so asset loops live in the
+built-in `<Stylesheets />`, `<BodyScripts />` and `<JsonLd />` tags instead of
+inline `hasAsset` / `asset` / `forEach` in the layout.
+
 Points to watch:
 
 - **`extraHead` comes first.** Delaying resource hints (`preconnect`, LCP
   `preload`) writes straight into LCP.
-- **Global `app.css` is render-blocking**, with the reasoning in
-  [02-architecture.md](./02-architecture.md). Controller `styles: [...]` adds
-  page sheets the same way. If the build has not run, `hasAsset` is false and
-  the tag is never emitted.
-- **The `hasAsset` checks** keep the page from requesting files that 404 when
-  the build is missing.
-- **The devtools script** is emitted only when `NODE_ENV=development`; it does
-  not exist at all in production output.
+- **`<Stylesheets />` emits global `app.css` (render-blocking)** plus controller
+  `styles: [...]`, with the reasoning in
+  [02-architecture.md](./02-architecture.md). If the build has not run,
+  `hasAsset` is false inside the tag and nothing is emitted.
+- **`<BodyScripts />` emits `main.js`, page `entries`, and the
+  development-only overlay.** The overlay script exists only when
+  `NODE_ENV=development`; it is absent from production output.
+- **`<JsonLd />` turns `structuredData` into safe
+  `application/ld+json` scripts.**
 
 ### Layout locals
 
@@ -219,30 +210,27 @@ of bug where every page thinks it is the home page and renders the logo as an
 ## Page templates
 
 The `view` field gives the path under `views/` without an extension:
-`"pages/home"` → `views/pages/home.ejs`. The locals passed to the template are
-the contents of the `data` field plus `metadata` — **not** the layout locals.
-The page template still has access to all helpers and components.
+`"pages/home"` → `views/pages/home.jsk` (else legacy `home.ejs`). The locals
+passed to the template are the contents of the `data` field plus `metadata` —
+**not** the layout locals. The page template still has access to all helpers
+and components.
 
-```ejs
-<%# views/pages/home.ejs %>
+```html
+{# views/pages/home.jsk #}
 <section class="wrapper">
-  <h1 class="text-3xl font-bold"><%= heading %></h1>
+  <h1 class="text-3xl font-bold">{{ heading }}</h1>
 
-  <%# `list` is defined in views/components/list.js; no import needed. %>
-  <%- list({ items }) %>
+  {# `list` is defined in views/components/list.js; no import needed. #}
+  <List :items="items" />
 
   <div class="mt-8" data-island="counter" data-island-props='{"start":5}'></div>
 </section>
 ```
 
-Do not mix up the two output forms in EJS:
-
-- `<%= value %>` — HTML escaped. **Always** this for user/upstream data.
-- `<%- html %>` — raw. Only for HTML strings you produced yourself and know to
-  be safe (component calls, `headMeta`, `body`).
-
-Because `async: true` is on, `await` can also be used inside a template, but
-keeping data fetching in the controller makes diagnosis easier.
+In `.jsk`, `{{ }}` escapes and `{{{ }}}` emits raw HTML (trusted strings only).
+Legacy EJS keeps `<%= %>` / `<%- %>` with the same meaning; because `async: true`
+is on there, `await` can also be used inside an `.ejs` template, but keeping
+data fetching in the controller makes diagnosis easier.
 
 ## Components: `views/components/**`
 

package/docs/en/05-islands.md

@@ -123,25 +123,30 @@ will still mount.
 ```
 client/
 ├── entries/
-│   ├── main.js       the shared bootstrap loaded on every page
+│   ├── main.js       shared bootstrap on every page (or main.ts)
 │   └── chart.js      only on the pages that ask for it
 └── islands/
-    ├── counter.js
+    ├── counter.ts    .js or .ts
     └── chart.js
 ```
 
-**Every file** under `client/entries/*.js` **is an esbuild entry**. `main.js`
-is loaded by the layout on every page (if it is in the manifest). Extra entries
-are loaded only on the pages that ask for them:
+**Every file** under `client/entries/*.{js,ts,mts}` **is an esbuild entry**.
+`main.js` (or `main.ts`) is loaded by the layout on every page (if it is in the
+manifest). Extra entries are loaded only on the pages that ask for them. Two
+extensions for the same stem (`main.js` + `main.ts`) fail the build.
 
 ```js
-// controller
+// controller — the manifest key is always *.js
 return { view: "pages/markets", entries: ["chart.js"] };
 ```
 
 The layout resolves every name in the `entries` array with `asset(entry)` and
-emits a `<script type="module">`. The name is the manifest key, that is, the
-file name itself (`chart.js`), not its hashed form.
+emits a `<script type="module">`. The name is the manifest key (`chart.js`);
+even when the source is `chart.ts`, the unhashed key stays `.js`.
+
+Shared `@/lib` modules imported on the server must stay **`.js`** — the Node
+runtime does not resolve `.ts`; TypeScript is compiled only on the esbuild
+client path.
 
 Code splitting (`splitting: true`) is on: modules shared by two entries end up
 in a common chunk and are not downloaded twice.