jskelet 0.5.5 → 0.6.1

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:
 
 ```
@@ -46,7 +50,7 @@ ayarlamayı düşünmeniz gerekenler:
 | `HOST` | `0.0.0.0` | Yalnızca IPv4 dinlemek gerekiyorsa. Varsayılan `::` zaten çift yığın dinler |
 | `PREWARM_MAX` | Site boyutuna göre | Açılışta ısıtılacak sayfa sayısı |
 | `PREWARM_INTERVAL_SECONDS` | `0` ya da uzun bir değer | Hiç ziyaret edilmeyen sayfaları sıcak tutmak isterseniz |
-| `DEV_TOKEN` | Yalnızca staging'de | Yayına açılmamış ortamı gizler |
+| `DEV_GATE` + `DEV_TOKEN` | Yalnızca staging'de | Yayına açılmamış ortamı gizler. Token tek başına siteyi kilitlemez |
 | `JSKELET_S3_*` | Access log'u S3'e yazıyorsanız | Bucket + credential; ayrıntı [07](./07-yapilandirma.md) |
 
 Production'da dosya veya S3 sink açıldığında HTTP access log middleware
@@ -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
 
@@ -151,15 +156,11 @@ Build aşaması `npx jskelet build` ile bunları kendisi üretir.
 
 Bu depodaki örnekler jskelet'i npm'den değil `"jskelet": "file:../.."` ile
 alıyor. Coolify, Railway, Render gibi araçlarda "base directory" olarak
-`examples/marketing` verilirse build context yalnızca o dizin olur, `../..`
+`examples/blog` verilirse build context yalnızca o dizin olur, `../..`
 context'in dışında kalır ve kurulum `npm ci`de düşer. Doğru ayar: **base
-directory `/`**, Dockerfile konumu `/examples/marketing/Dockerfile`. Çalışan
-örnek `examples/marketing/Dockerfile` içinde ve context'i depo kökü kabul eder:
-
-```bash
-docker build -f examples/marketing/Dockerfile -t jskelet-marketing .
-docker run --rm -p 3000:3000 -e SITE_URL=https://example.com jskelet-marketing
-```
+directory `/`** (depo kökü) ve imajı yukarıdaki çok aşamalı Dockerfile ile
+uygulama dizinine göre uyarlamak — ya da jskelet'i npm bağımlılığı olarak
+kurup context'i uygulamanın kendi dizini yapmak.
 
 Kendi uygulamanızda jskelet normal bir bağımlılık olacağı için bu kısıt yoktur;
 yukarıdaki çok aşamalı imaj yeterli.
@@ -168,8 +169,8 @@ yukarıdaki çok aşamalı imaj yeterli.
 
 Framework hazır bir sağlık kontrolü ucu **eklemez**; kendi route'unuza koymanız
 gerekir. Varsayılan `devGateBypass` listesi `/api/healthcheck` yolunu içerdiği
-için bu adı kullanmak en az sürprizli seçenektir: `DEV_TOKEN` ayarlı bir ortamda
-bile erişilebilir kalır.
+için bu adı kullanmak en az sürprizli seçenektir: dev gate açıkken bile
+erişilebilir kalır.
 
 ```js
 // routes/00-health.mjs
@@ -326,7 +327,7 @@ istek başına iş neredeyse sıfıra iner.
 - [ ] `hooks.prewarmPaths()` en önemli sayfaları başa koyuyor
 - [ ] `headers()` içinde CSP ve güvenlik başlıkları tanımlı
 - [ ] Sağlık kontrolü ucu var ve `devGateBypass` listesinde
-- [ ] Staging'de `DEV_TOKEN` ayarlı, prod'da **ayarlı değil**
+- [ ] Staging'de `DEV_GATE=1` ve `DEV_TOKEN` ayarlı, prod'da gate **kapalı**
 - [ ] Ters proxy `Accept-Encoding`i iletiyor ve kendi sıkıştırmasını yapmıyor
 - [ ] `clientEnv` listesinde gizli anahtar yok
 

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 |
@@ -45,7 +47,7 @@ eşlenik tutuluyor; birini değiştiriyorsan diğerini de değiştir.
 
 ## Çalışan örnekler
 
-Dördü de çalışır durumda; belgelerdeki örneklerin çoğu buralardan alınmıştır.
+Üçü de çalışır durumda; belgelerdeki örneklerin çoğu buralardan alınmıştır.
 
 **`examples/minimal/`** — iki route, bir bileşen, bir island, minimal config.
 Framework'ün en küçük çalışan hâli.
@@ -66,32 +68,7 @@ npm --prefix examples/blog install
 npm --prefix examples/blog run dev
 ```
 
-**`examples/marketing/`** — framework'ün kendi tanıtım sitesi: hero, kıyaslama
-tablosu, canlı gecikme ölçümü, SSS, belgeler dizini, sürüm notları ve indirme
-sayfası. Sayfadaki bayt sayıları `lib/payload.js` içinde sitenin **kendi** build
-çıktısından, sürüm künyesi ise `lib/release.js` içinde kurulu paketin
-`package.json`'ından okunur; gecikme sayıları `latency` island'ında tarayıcıda
-ölçülür. Uzun TTL (bir saat) ve tüm sayfaları ısıtan prewarm ile, cache'in en
-verimli çalıştığı profili gösterir.
-
-Site aynı zamanda **bu belgeleri** servis ediyor: `/docs/<bölüm>` adresleri
-`node_modules/jskelet/docs/` altındaki markdown dosyalarını okuyup sol gezinme,
-"bu sayfada" listesi ve sıralı geçişle basıyor. Çevirici `lib/markdown.js`
-içinde küçük bir modül — bağımlılık yok — ve kaynak paketin kendisi olduğu için
-site kurulu sürümden hiç ayrışmıyor.
-
-Site aynı zamanda **iki dilli**: varsayılan İngilizce kökte, Türkçe `/tr`
-altında ve route adları iki dilde de aynı. Framework'te i18n yok; dil
-çözümlemesi `lib/i18n.js` içinde uygulamanın kendi sözleşmesi olarak duruyor ve
-`hooks.layoutContext` ile bir sözlüğe bağlanıyor. Çok dilli bir siteyi bu
-yüzeyle nasıl kurabileceğinizi görmek için bakılacak yer burası.
-
-```bash
-npm --prefix examples/marketing install
-npm --prefix examples/marketing run dev
-```
-
-**`examples/dashboard/`** — diğer üçünün tersi eksen: kişiye özel sayfalar.
+**`examples/dashboard/`** — diğer ikisinin tersi eksen: kişiye özel sayfalar.
 İmzalı cookie ile giriş, `private: true` korumalı panel, sayfalı tablo
 fragment'i, CSRF'li mutasyon formu ve temizlik fonksiyonu döndüren bir island.
 Public bir tanıtım sayfası da var, böylece aynı uygulamada önbelleklenen ve
@@ -102,5 +79,5 @@ npm --prefix examples/dashboard install
 npm --prefix examples/dashboard run dev
 ```
 
-Her dört örnekte `node smoke.mjs` sunucu ayaktayken uçların beklendiği gibi
+Her üç örnekte `node smoke.mjs` sunucu ayaktayken uçların beklendiği gibi
 yanıt verdiğini doğrular.

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

@@ -36,9 +36,10 @@ Request
  ├─ rewrites(beforeFiles)          config → proxy or a change to req.url
  ├─ compression                    brotli/gzip negotiation (quality 5)
  ├─ headers                        static cache + config headers()
- ├─ devGate                        if DEV_TOKEN is set, 404 without a token
+ ├─ devGate                        if the gate is on, 404 without a token
  ├─ redirects                      config redirects(), first match wins
  ├─ trailingSlash                  308 when config trailingSlash is true
+ ├─ robots.txt                     appends framework Disallow rules to the user's body
  ├─ staticPrecompressed            .br/.gz copies produced at build (quality 11)
  ├─ express.static                 files under public/
  ├─ (dev) devtools                 only when NODE_ENV=development
@@ -51,7 +52,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
 ```
@@ -71,6 +72,11 @@ position has a reason, and moving things around leads to silent breakage.
   leak even its redirect rules to the outside. `trailingSlash` sits after config
   redirects so explicit rules see the requested path first; the canonical slash
   form is enforced as a second step.
+- **`robots.txt` before static, and inside compression.** The body the
+  application wrote is left intact; the framework appends `Disallow` rules
+  for its own endpoints. A response that already has `Content-Encoding` is
+  not rewritten — the block is added to plain text, and compression stays
+  outside.
 - **`staticPrecompressed` before `express.static`.** If there are `.br`/`.gz`
   copies produced at build time, those are served (brotli quality 11);
   otherwise the request falls through to the `static` below it and the
@@ -270,10 +276,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

@@ -158,7 +158,9 @@ stored), but the flag is the right place. Details in
 ## `fragment()` — a partial without the layout
 
 For endpoints that refresh a region. No layout is printed, the response is sent
-with `private, no-store` and no ETag, and it never touches the HTML cache.
+with `private, no-store` and no ETag, and it never touches the HTML cache. The
+`/_fragment/` prefix is appended to `robots.txt`, so partial endpoints are not
+indexed ([04](./04-rendering.md#robotstxt)).
 
 ```js
 app.get(
@@ -213,7 +215,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 +334,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/**`
 
@@ -522,6 +510,30 @@ The `renderHeadMeta(metadata)` function is exported; it can be used when you
 need to produce the same tags outside the layout (for example in a fragment or
 an email).
 
+## robots.txt
+
+The application writes `robots.txt`: `public/robots.txt` or a plain route.
+The framework does not change that body; it appends a JSkelet note and
+`Disallow` rules **under** a successful text response. If there is no file
+and no route, the framework does not invent a `robots.txt`.
+
+Paths added:
+
+- `/_jskelet/` — admin panel, remote image proxy, auth handoff
+- `/__jskelet/` — development tools
+- `/_fragment/` — partial responses without a layout
+
+An endpoint moved off those prefixes is added too, but only when it is
+actually mounted: `admin.basePath`, `images.remote.path`,
+`auth.crossSubdomainHandoff.path`. `brand.devBasePath` is written only in
+development; in production that path may be the application's own page.
+
+The note starts with the configured brand name (`brand.name`, default
+`JSkelet`). The trailing group repeats `User-agent: *` together with every
+other agent already named in the file. Google does not merge a
+crawler-specific group with `*`; it does merge a second group for the same
+agent. If the note is already in the file, it is not appended again.
+
 ## Dynamic OG images
 
 Counterpart to Next.js `ImageResponse` / `opengraph-image.tsx`. There is no JSX: