jskelet 0.1.1 → 0.1.2

package/AGENTS.md

@@ -24,6 +24,11 @@ zaten tartışılmış:
 | `src/config/**` | [07-yapilandirma.md](./docs/07-yapilandirma.md) |
 | `src/dev-server.mjs`, `src/server/dev/**` | [09-dev-araclari.md](./docs/09-dev-araclari.md) |
 
+Belgeler iki dilde: Türkçesi `docs/`, İngilizcesi `docs/en/` altında ve
+dosyalar birebir eşlenik. Bir belgeyi değiştirdiysen karşılığını da güncelle;
+pazarlama sitesi (`examples/marketing`) bu dosyaları doğrudan `/docs` altında
+servis ettiği için eksik kalan çeviri kullanıcıya görünür.
+
 ## Doğrulama
 
 **Lint yeterli, tam build zorunlu değil.**

package/CHANGELOG.md

@@ -10,8 +10,71 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- `route(fn, { private: true })` for pages that depend on the visitor. The HTML
+  cache is bypassed, `cache.html` patterns can no longer turn caching on for
+  that route, and the response is sent with `private, no-store`, `Vary: Cookie`
+  and no ETag.
+- A runtime guard against identity leaks: when a cacheable route reads
+  `Cookie`, `Authorization` or a session field, the rendered HTML is never
+  stored. In development the request fails with an explanation, in production it
+  is served with `no-store` and logged.
+- `fragment()` for layout-less partial responses, with `no-store` and cache
+  bypass built in.
+- CSRF protection. Cross-site state-changing requests are rejected based on
+  `Origin` and `Sec-Fetch-Site`; requests carrying neither header still pass, so
+  webhooks keep working. An optional double-submit token layer is enabled with
+  `security.csrf.token` and rendered into forms by the new `csrfField()` helper.
+- Signed cookie helpers under `jskelet/cookies`: `parseCookies()`,
+  `setCookie()`, `clearCookie()`, `setSignedCookie()`, `getSignedCookie()`,
+  `randomToken()` and `safeEqual()`. Defaults are `HttpOnly`, `SameSite=Lax` and
+  `Secure` outside development.
+- A `security` configuration section: `trustProxy`, `cookieSecret` and `csrf`.
+- `seeOther()` for the post/redirect/get flow, which needs 303 rather than the
+  method-preserving 307 that `redirect()` sends.
+- Island cleanup. A `mount()` function may return a teardown callback; it is now
+  stored and called by the new `unmount(root)` export when the subtree leaves
+  the DOM.
+- Client helpers for partial updates: `swap()` and `startSwapLinks()` for
+  fetching and replacing a region, `enhanceForm()` and `startForms()` for
+  submitting forms without a full page load while keeping the no-JavaScript
+  path working.
+- A fourth example, `examples/dashboard`: sign-in with a signed cookie session,
+  a private page, a paginated table fragment, a CSRF-protected mutation and an
+  island with cleanup, covered by its own `smoke.mjs`.
+- An npm version badge in the `README`, linking to the package page.
 - English `README`, plus `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`,
   a `LICENSE` file, issue and pull request templates, and a CI workflow.
+- An English edition of the documentation under `docs/en/`, mirroring every
+  chapter of the Turkish `docs/`.
+- The dev overlay now compares the installed version against the `latest` tag on
+  npm: the Server tab shows the version, marks an `update` chip when a newer
+  release exists and offers the upgrade command. The lookup is cached for six
+  hours, never blocks the server and can be turned off with
+  `JSKELET_VERSION_CHECK=0`.
+
+### Changed
+
+- `trust proxy` is now configurable through `security.trustProxy` instead of
+  being always on. The default is unchanged, but a server exposed directly to
+  the internet should turn it off: while it is on, a client can forge its own
+  `X-Forwarded-For` and rate limiting or audit logs see the wrong address.
+- Every message the framework prints is now English: config, router, render,
+  cache, prewarm, asset and build warnings, CLI output, the project `jskelet
+  init` scaffolds, and the devtools overlay and report interfaces. Visitor-facing
+  status pages still follow `brand.lang` and keep their Turkish translations.
+- The dev overlay and report now show the current JSkelet logo, served with a
+  cacheable response instead of being re-fetched on every navigation.
+
+### Fixed
+
+- A page rendered without `revalidate` used to be sent with no `Cache-Control`
+  at all, while still carrying a strong ETag. HTTP treats such a response as
+  heuristically cacheable, so an intermediate proxy or the browser's back button
+  could store a response meant for a single visitor. Dynamic pages now send
+  `private, no-store` and no ETag.
+- A redirect thrown from a route that reads the session is no longer cacheable
+  either; a stored "you need to sign in" redirect used to follow the visitor
+  even after signing in.
 
 ## [0.1.0]
 

package/README.md

@@ -9,6 +9,7 @@ Tailwind v4 stylesheet**, and instead of ISR keeps an in-process **HTML TTL
 cache** with stale-while-revalidate. No React, no TypeScript — plain JavaScript
 with JSDoc.
 
+[![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)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
@@ -171,10 +172,15 @@ client.
   everything".
 - **No global state management** beyond the small island store.
 
-If you are building an app-shaped interface behind a login — a dashboard, an
-editor, an admin panel — page HTML cannot be cached and this framework is the
-wrong tool. The reasoning and a feature-by-feature comparison with Next.js live
-in [docs/11-tasima.md](./docs/11-tasima.md).
+An app-shaped interface behind a login — a dashboard, an editor, an admin panel
+— cannot benefit from the HTML cache, which is the main reason to pick this
+framework. It is supported rather than recommended: `route(fn, { private: true })`
+keeps per-visitor pages out of the cache, and signed cookies, CSRF, fragment
+endpoints and region swapping cover the rest
+([docs/12-panel-ve-oturum.md](./docs/12-panel-ve-oturum.md)). Live data
+transport is deliberately left to you; pick SSE, WebSocket or polling yourself.
+A feature-by-feature comparison with Next.js is in
+[docs/11-tasima.md](./docs/11-tasima.md).
 
 ## Project layout
 
@@ -260,10 +266,11 @@ Only the specifiers in the `exports` map are supported:
 
 | Specifier | Contents |
 | --- | --- |
-| `jskelet` | `route`, `createApp`, `startServer`, `notFound`, `redirect`, `cache`, `asset`, `getConfig`, HTML cache and prewarm helpers |
-| `jskelet/client` | `register`, `registerAll`, `hydrate`, `start`, `createStore`, DOM helpers |
+| `jskelet` | `route`, `fragment`, `createApp`, `startServer`, `notFound`, `redirect`, `seeOther`, `cache`, `asset`, `getConfig`, cookie helpers, HTML cache and prewarm helpers |
+| `jskelet/client` | `register`, `registerAll`, `hydrate`, `unmount`, `start`, `swap`, `startForms`, `createStore`, DOM helpers |
 | `jskelet/html` | `attrs`, `cn`, `cx`, `esc`, `jsonScript` |
-| `jskelet/tags` | `icon`, `image`, `link`, `preloadImage` |
+| `jskelet/tags` | `icon`, `image`, `link`, `preloadImage`, `csrfField` |
+| `jskelet/cookies` | `parseCookies`, `setCookie`, `clearCookie`, `setSignedCookie`, `getSignedCookie`, `randomToken`, `safeEqual` |
 
 Anything reachable by a deeper path is internal and may change without notice.
 
@@ -295,6 +302,7 @@ written in Turkish; translations are a welcome contribution.
 | [09-dev-araclari](./docs/09-dev-araclari.md) | Dev workflow, overlay, report page, dev gate |
 | [10-dagitim](./docs/10-dagitim.md) | Production, Docker, reverse proxy, health checks |
 | [11-tasima](./docs/11-tasima.md) | Migrating from Next.js: mapping table and plan |
+| [12-panel-ve-oturum](./docs/12-panel-ve-oturum.md) | Per-visitor pages: `private: true`, sessions, CSRF, fragments, swapping |
 
 If you work with AI agents, [AGENTS.md](./AGENTS.md) summarizes the rules that
 apply to this repository.
@@ -305,6 +313,7 @@ apply to this repository.
 npm --prefix examples/minimal   install && npm --prefix examples/minimal   run dev
 npm --prefix examples/blog      install && npm --prefix examples/blog      run dev
 npm --prefix examples/marketing install && npm --prefix examples/marketing run dev
+npm --prefix examples/dashboard install && npm --prefix examples/dashboard run dev
 ```
 
 - **`examples/minimal`** — two routes, one component, one island. The smallest
@@ -319,6 +328,11 @@ npm --prefix examples/marketing install && npm --prefix examples/marketing run d
   are measured in the browser; there are no invented benchmarks. It is also
   bilingual — English at the root, Turkish under `/tr` — which shows how to build
   a multi-language site on a framework that ships no i18n of its own.
+- **`examples/dashboard`** — the opposite axis: per-visitor pages. A signed
+  cookie session, a `private: true` page that never enters the HTML cache, a
+  paginated table fragment, a CSRF-protected form that still works without
+  JavaScript, and an island with cleanup. A public landing page sits next to it,
+  so a cached response and a `no-store` one are visible side by side.
 
 With a server running, `node smoke.mjs` inside an example verifies that its
 endpoints respond as expected.

package/bin/jskelet.mjs

@@ -91,13 +91,13 @@ switch (command) {
   }
 
   default: {
-    const known = command ? `bilinmeyen komut: ${command}\n\n` : "";
+    const known = command ? `unknown command: ${command}\n\n` : "";
     process.stderr.write(
-      `${known}kullanım: jskelet <dev|build|start|init>\n\n` +
-        "  dev     build watch + sunucu (canlı yenileme, dev overlay)\n" +
-        "  build   prod build\n" +
-        "  start   prod sunucu\n" +
-        "  init    bulunduğun dizine minimal iskelet kurar\n",
+      `${known}usage: jskelet <dev|build|start|init>\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",
     );
     process.exit(command ? 1 : 0);
   }

package/docs/03-routing.md

@@ -28,11 +28,13 @@ gerekmez:
 | Alan | Karşılığı |
 | --- | --- |
 | `route` | `jskelet` → `route` |
+| `fragment` | `jskelet` → `fragment` |
 | `renderView` | `jskelet` → `renderView` |
 | `renderPage` | `jskelet` → `renderPage` |
 | `notFound` | `jskelet` → `notFound` |
 | `redirect` | `jskelet` → `redirect` |
 | `permanentRedirect` | `jskelet` → `permanentRedirect` |
+| `seeOther` | `jskelet` → `seeOther` |
 
 İstersen doğrudan import da edebilirsin; `api` yalnızca kolaylık:
 
@@ -45,7 +47,7 @@ export function register(app) {
 ```
 
 Modül geçerli bir fonksiyon açmazsa uyarı basılır ve atlanır:
-`[router] <dosya> default ya da 'register' fonksiyonu dışa açmıyor, atlandı`.
+`[router] <file> exports neither a default nor a 'register' function, skipped`.
 
 ## Yükleme sırası
 
@@ -97,8 +99,8 @@ Hiç route modülü bulunamazsa uyarı basılır ve sunucu yalnızca statik dosy
 - `ctx` nesnesini kurar ve controller'ı çağırır.
 - HTML TTL cache'ini uygular (`revalidate` varsa ve metot `GET` ise).
 - `notFound()` / `redirect()` kontrol akışını yakalar.
-- Yanıt başlıklarını yazar: `Content-Type`, cache'lenebilir yanıtlarda
-  `Cache-Control`, ve her zaman `X-JSkelet-Cache`.
+- Yanıt başlıklarını yazar: `Content-Type` ve cache durumuna göre
+  `Cache-Control` (+ önbelleklenebilir yanıtlarda `X-JSkelet-Cache`).
 - Önbellekte saklanan sıkıştırılmış gövdeyi kullanarak yanıtı gönderir.
 
 ```js
@@ -114,11 +116,42 @@ app.get(
 );
 ```
 
-`options` tek bir alan kabul eder:
+`options` iki alan kabul eder:
 
 | Alan | Tip | Anlamı |
 | --- | --- | --- |
 | `revalidate` | `number` (saniye) | HTML önbellek TTL'i. Verilmezse ya da 0 ise bu route önbelleklenmez. `jskelet.config.mjs` → `cache().html` içindeki eşleşen bir kural bu değeri **ezer**. |
+| `private` | `boolean` | Sayfa ziyaretçiye bağlı. Önbellek devre dışı kalır, `cache().html` deseni bunu **ezemez**, yanıt `private, no-store` ve `Vary: Cookie` ile ETag'siz gider. |
+
+Oturuma bağlı her sayfa `private: true` almalı; önbellek anahtarında kimlik
+olmadığı için bayrak olmadan bir kullanıcının HTML'i bir başkasına servis
+edilir. Framework bu hatayı çalışma zamanında da yakalıyor (controller cookie
+okuduğunda render önbelleğe yazılmaz), ama doğru yer bayrak. Ayrıntılar
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de.
+
+## `fragment()` — layout'suz parça
+
+Bir bölgeyi tazeleyen uçlar için. Layout basılmaz, yanıt `private, no-store` ve
+ETag'siz gider, HTML önbelleğine hiç uğramaz.
+
+```js
+app.get(
+  "/_fragment/satirlar",
+  fragment(async ({ query }) => ({
+    view: "partials/rows",
+    data: { rows: getRows(Number(query.sayfa ?? 1)) },
+  })),
+);
+```
+
+Controller `{ view, data?, status? }` ya da doğrudan bir HTML string döner.
+Hata durumunda tüm sayfa yerine küçük bir uyarı parçası döner
+(`<div role="alert" data-fragment-error>`), çünkü takas edilen bölge bir hata
+sayfasının tamamını içine almamalı.
+
+`fragment()` POST için de kullanılabilir: form gönderiminin cevabı olarak
+güncellenmiş parçayı döndürmenin yolu bu, ve şablonda `csrfField()`
+çalışabilmesi için gereken istek bağlamını da kuruyor.
 
 ## `ctx` — controller bağlamı
 
@@ -200,18 +233,24 @@ fonksiyon `throw` eder, framework yakalar. Böylece veri katmanındaki bir
 fonksiyon, controller'a dönüş değeri taşımak zorunda kalmadan 404 üretebilir.
 
 ```js
-import { notFound, redirect, permanentRedirect } from "jskelet";
+import { notFound, redirect, permanentRedirect, seeOther } from "jskelet";
 
 notFound();                    // 404 → hooks.notFound() sayfası
-redirect("/yeni-adres");       // 307 (geçici)
-permanentRedirect("/yeni");    // 308 (kalıcı)
+redirect("/yeni-adres");       // 307 (geçici, metodu korur)
+permanentRedirect("/yeni");    // 308 (kalıcı, metodu korur)
+seeOther("/panel");            // 303 (POST sonrası)
 ```
 
-Üçü de `never` döner (her zaman fırlatır). Ayrıntı:
+Dördü de `never` döner (her zaman fırlatır). Ayrıntı:
 
 - `notFound()` → `NotFoundError` (`statusCode: 404`)
 - `redirect(location)` → `RedirectError` (`statusCode: 307`)
 - `permanentRedirect(location)` → `RedirectError` (`statusCode: 308`)
+- `seeOther(location)` → `RedirectError` (`statusCode: 303`)
+
+Bir POST handler'ında `redirect()` değil `seeOther()` kullanılır: 307 metodu
+koruyor, yani tarayıcı hedefe yeniden POST ediyor. "Post/redirect/get" akışı —
+geri tuşunun formu yeniden göndermediği akış — 303 gerektiriyor.
 
 Özel bir durum kodu gerekiyorsa sınıfı doğrudan kullanabilirsin:
 
@@ -424,7 +463,7 @@ Yakalanan değerler `destination` içindeki aynı adlı `:param`'lara yazılır.
 Parametre adı `[A-Za-z_][A-Za-z0-9_]*` kalıbına uymalıdır.
 
 `source` mutlaka `/` ile başlamalı; başlamazsa kural yok sayılır ve uyarı
-basılır (`[config] geçersiz source (\`/\` ile başlamalı): …`). Tanınmayan bir
+basılır (``[config] invalid source (must start with `/`): …``). Tanınmayan bir
 sözdizimi sessizce literal kabul edilmez.
 
 Tam desen listesi ve config referansı: [07-yapilandirma.md](./07-yapilandirma.md).

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

@@ -194,8 +194,8 @@ Kurallar:
   önce yüklenir. Tek amacı `lib/` yeniden ihraçlarını şablon local'i yapmak;
   bileşenlerin kendi dosyaları sonradan gelip sessizce üzerine yazar.
 - Aynı ad iki farklı bileşen dosyasında tanımlıysa uyarı basılır ve **ikincisi
-  kazanır**: `[components] 'card' iki kez tanımlı: a.js ve b.js — ikincisi
-  kazanıyor.`
+  kazanır**: `[components] 'card' is defined twice: a.js and b.js — the second
+  one wins.`
 - `views/components` dizini yoksa bileşen kaydı boş kalır; bileşen kullanmayan
   bir proje de çalışır.
 

package/docs/05-islands.md

@@ -205,14 +205,67 @@ start();
 - Bir element aynı island adıyla **iki kez bağlanmaz**; kayıt element bazında
   `WeakMap` içinde tutulur.
 - Kayıtlı olmayan bir ad için konsola uyarı basılır:
-  `[island] kayıtlı değil: <ad>`.
+  `[island] not registered: <name>`.
 - Modül import'u ya da `mount()` hata verirse konsola hata basılır
-  (`[island] <ad> yüklenemedi`) ve **sayfanın kalanı etkilenmez**.
+  (`[island] <name> failed to load`) ve **sayfanın kalanı etkilenmez**.
 - `mount()` başarıyla dönerse elemente `data-island-ready="true"` yazılır.
-- `mount()` bir fonksiyon döndürebilir; sözleşmede temizlik için ayrılmıştır.
-  Framework bu fonksiyonu şu anda kendiliğinden çağırmaz — island'ın ömrünü
-  kendisi yönetiyorsa (ör. bir fragment'ı değiştirirken) dönen fonksiyonu
-  saklayıp kendisi çağırmalıdır.
+- `mount()` bir temizlik fonksiyonu döndürebilir; framework onu saklar ve
+  `unmount()` çağrıldığında işletir (aşağıya bakın).
+
+### `unmount(root?)`
+
+`root` altındaki island'ları söker: saklanan temizlik fonksiyonlarını çağırır,
+`data-island-ready` işaretini kaldırır ve kaydı siler, böylece aynı düğüm
+tekrar DOM'a girerse yeniden bağlanabilir. `root`'un kendisi de island olabilir.
+
+DOM'un bir bölgesini değiştirirken çağrılması **zorunlu**:
+
+```js
+import { hydrate, unmount } from "jskelet/client";
+
+unmount(container);
+container.innerHTML = html;
+hydrate(container);
+```
+
+Atlanması en kolay gözden kaçan sızıntı biçimini üretiyor. `innerHTML` ile
+değiştirilen bir bölgenin island'ları DOM'dan çıkar, ama `document`/`window`
+üzerine kurdukları dinleyiciler ve `setInterval`'ları yaşamaya devam eder;
+birkaç takastan sonra aynı iş onlarca kez çalışır.
+
+```js
+export function mount(element) {
+  const timer = setInterval(() => tick(element), 1000);
+  const onResize = () => layout(element);
+  window.addEventListener("resize", onResize);
+
+  return () => {
+    clearInterval(timer);
+    window.removeEventListener("resize", onResize);
+  };
+}
+```
+
+`swap()` ve form yardımcıları `unmount()`u kendileri çağırıyor; elle DOM
+değiştirdiğiniz yerlerde siz çağırıyorsunuz.
+
+### `swap(target, url, options?)` ve `startSwapLinks(root?)`
+
+Bir bölgeyi sunucudan gelen parçayla değiştirir: eski alt ağacı söker, içeriği
+yazar, yeniden hidre eder ve odağı kaybolmuşsa geri getirir.
+
+```html
+<a href="/_fragment/satirlar?sayfa=2" data-swap="#satirlar">Sonraki</a>
+```
+
+Sunucu tarafı ve tüm seçenekler
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de.
+
+### `enhanceForm(form)` ve `startForms(root?)`
+
+`data-enhance` taşıyan formları sayfa yenilemeden gönderir; JS kapalıyken
+normal POST + yönlendirme akışı çalışmaya devam eder. Sözleşmenin tamamı
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de.
 
 ## Durum paylaşımı: `createStore`
 

package/docs/06-cache.md

@@ -23,6 +23,29 @@ Sıra önemli: **istek içi cache en içte** olmalı ki aynı render'daki iki ç
 tek upstream isteğine düşsün; **upstream takibi HTML cache'in içinde** olmalı ki
 eksik veriyle üretilen çıktı önbelleğe yazılmasın.
 
+## Public ve kişiye özel ayrımı
+
+Bu belgedeki her şey **herkese aynı gidebilen** HTML için geçerli. Cache
+anahtarında kimlik yok (yalnızca yol + query), yani önbellekteki bir sayfa onu
+ilk isteyen kişinin değil, o yolun cevabıdır.
+
+Kullanıcıya bağlı bir sayfa bu yüzden ayrı bir yoldan geçer:
+
+```js
+app.get("/panel", route(async ({ req }) => { … }, { private: true }));
+```
+
+`private: true` üç şeyi birden yapar: önbellek devre dışı kalır, config'in
+`cache.html` deseni bu kararı **ezemez** ve yanıt `private, no-store`,
+`Vary: Cookie` ile, ETag'siz gider. Ayrıntılar ve oturum/CSRF tarafı
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de.
+
+Bayrağı unutursanız framework sessiz kalmaz: controller `Cookie`,
+`Authorization` ya da `req.session`/`req.user` okuduğu anda render işaretlenir
+ve önbelleğe **yazılmaz**. Dev'de istek bir hatayla düşer, üretimde `no-store`
+ile servis edilip loglanır. Koruma bir mazeret değil son savunma — doğru yer
+`private: true`.
+
 ## `revalidate` — TTL nereden gelir
 
 Bir route'un TTL'i iki kaynaktan gelebilir ve **config kazanır**:
@@ -31,6 +54,9 @@ Bir route'un TTL'i iki kaynaktan gelebilir ve **config kazanır**:
 2. `jskelet.config.mjs` → `cache().html` içindeki eşleşen desen. Varsa
    route'unkini ezer.
 
+Tek istisna `private: true`: desen eşleşse bile yok sayılır. Kilit tek yönlü,
+çünkü ters yönde bir hata sessiz veri sızıntısı anlamına geliyor.
+
 ```js
 // jskelet.config.mjs
 export default {
@@ -53,8 +79,14 @@ mümkün kılar; route dosyalarını dolaşmak gerekmez.
 yapılmaz. Hiç `cache().html` kuralı yoksa doğrudan route'un değeri kullanılır.
 
 `revalidate` verilmemişse ya da 0 ise sayfa **hiç önbelleklenmez**: her istek
-render edilir ve yanıta `Cache-Control` yazılmaz (yalnızca
-`X-JSkelet-Cache: MISS`).
+render edilir ve yanıt `Cache-Control: private, no-store` ile, ETag'siz gider.
+`X-JSkelet-Cache` başlığı da yazılmaz — önbellek yolu hiç çalışmadı, `MISS`
+demek yanıltıcı olurdu.
+
+Dinamik bir sayfaya `no-store` yazılması bilinçli. Hiç direktif taşımayan bir
+yanıtı HTTP "sezgisel olarak önbelleklenebilir" sayıyor; araya giren bir proxy
+ya da tarayıcının geri tuşu, tek bir ziyaretçi için üretilmiş HTML'i
+saklayabiliyordu.
 
 Önbellek ayrıca yalnızca `GET` istekleri için devreye girer.
 
@@ -92,7 +124,7 @@ Okuma davranışı:
 
 Stale penceresinde tazelemenin hatası isteği etkilemez: eski HTML pencere
 boyunca geçerli kalır ve hata yalnızca loglanır
-(`[html-cache] arka plan tazelemesi başarısız: …`).
+(`[html-cache] background refresh failed: …`).
 
 Aynı anahtar için eşzamanlı tazelemeler tek bir çalışmada birleştirilir
 (`inflight` haritası): yüz eşzamanlı istek tek render'a düşer.
@@ -220,8 +252,8 @@ export async function apiGet(path) {
 
 | Durum | Sayılır | Sonuç |
 | --- | --- | --- |
-| `0` (ağ hatası), `408`, `425`, `429`, `>= 500` | **Geçici** | Sayfa önbelleğe yazılmaz, uyarı: `[render] <yol> eksik veriyle üretildi, önbelleğe alınmıyor (…)` |
-| Diğerleri (`400`, `403`, `404`, …) | **Kalıcı** | Yalnızca uyarı: `[render] <yol> eksik veriyle üretildi, upstream kalıcı hata veriyor (…)`. Önbellek engellenmez. |
+| `0` (ağ hatası), `408`, `425`, `429`, `>= 500` | **Geçici** | Sayfa önbelleğe yazılmaz, uyarı: `[render] <path> was produced with missing data, not caching it (…)` |
+| Diğerleri (`400`, `403`, `404`, …) | **Kalıcı** | Yalnızca uyarı: `[render] <path> was produced with missing data, upstream is failing permanently (…)`. Önbellek engellenmez. |
 
 Kalıcı hataların önbelleği engellememesi bilinçli: deterministik cevaplar tekrar
 denemekle düzelmez. Onlar yüzünden önbelleği kapatmak sayfayı her ziyarette
@@ -319,7 +351,7 @@ Kurallar:
    anda çekerken API'yi zorluyor. Tekrar turu bu sayfaların önbelleğe girmesini
    sağlıyor; aksi hâlde ziyaretçi soğuk render'ı öder.
 4. Özet loglanır:
-   `[prewarm] 128/130 sayfa ısıtıldı, 2 hata, 5 sayfa tekrar turunda kurtarıldı (12.4s)`
+   `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
 İstekler `user-agent: jskelet-prewarm` (`brand.prewarmUserAgent`) ve
 `accept-encoding: br, gzip` başlıklarıyla gider; ikincisi sıkıştırılmış gövdenin
@@ -392,7 +424,7 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   `cache().html` içindeki desen 0 saniye veriyor. Veya sayfa `status: 200`
   dışında bir kod dönüyor.
 - **Sayfa `MISS` dönüyor ama upstream sağlam.** Geçici bir upstream hatası
-  bildirilmiş olabilir; logda `eksik veriyle üretildi, önbelleğe alınmıyor`
+  bildirilmiş olabilir; logda `was produced with missing data, not caching it`
   satırını arayın.
 - **Sürekli eski veri.** `revalidate` çok yüksek; unutmayın ki gerçek gecikme en
   fazla `revalidate` + bir tazeleme turudur.

package/docs/07-yapilandirma.md

@@ -25,7 +25,7 @@ düz değer** olabilir; fonksiyon olmaları hâlinde `async` olabilirler ve `thi
 config nesnesine bağlıdır. Bir bölüm hata verirse yalnızca o bölüm yok sayılır.
 
 Config başarıyla yüklendiğinde bir özet basılır:
-`[config] jskelet.config.mjs yüklendi — 3 header, 2 redirect, 1 cache kuralı`
+`[config] jskelet.config.mjs loaded — 3 headers, 2 redirects, 1 cache rule`
 
 ## Tam örnek
 
@@ -62,6 +62,20 @@ export default {
   devGateBypass: ["/api/healthcheck", "/robots.txt"],
   preconnect: ["https://cdn.ornek.com"],
 
+  security: {
+    trustProxy: true,
+    cookieSecret: process.env.JSKELET_SECRET,
+    csrf: {
+      enabled: true,
+      token: false,
+      allowedOrigins: [],
+      exclude: ["/webhook/:path*"],
+      cookieName: "csrf_token",
+      fieldName: "_csrf",
+      headerName: "x-csrf-token",
+    },
+  },
+
   navigation: {
     prefetch: "moderate",
     prerender: "conservative",
@@ -239,6 +253,37 @@ bir yapılandırmadır.
 preconnect: ["https://cdn.ornek.com", "https://api.ornek.com"]
 ```
 
+## `security`
+
+**Tip:** `object` — **Varsayılan:**
+`{ trustProxy: true, cookieSecret: null, csrf: { enabled: true, token: false, … } }`
+
+Kişiye özel sayfaların tamamı ve gerekçeleri
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de; burada alanların referansı
+var.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `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.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ı. |
+| `csrf.fieldName` | `string` | `"_csrf"` | `csrfField()`in bastığı alan adı. |
+| `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.
+
+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.
+
 ## `navigation`
 
 **Tip:** `object` — **Varsayılan:**
@@ -521,6 +566,10 @@ html: {
 }
 ```
 
+Tek istisna `route(fn, { private: true })`: bu route'ta desen eşleşse bile yok
+sayılır. Kilidin tek yönlü olması bilinçli — ters yönde bir hata, bir
+kullanıcının HTML'inin bir başkasına servis edilmesi anlamına geliyor.
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |
@@ -622,6 +671,7 @@ basılmaz.
 | `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 |
 | `HOST` | `startServer` | `0.0.0.0` | Bağlanılacak arayüz |
+| `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) |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |

package/docs/08-build.md

@@ -69,7 +69,7 @@ dosya adlarını okunur tutuyor. Hash'li olmaları sayesinde bu dosyalara
 Build çalışmadıysa uygulama yine ayağa kalkar: `hasAsset()` false olur, layout
 stylesheet ve script etiketlerini hiç basmaz. `jskelet build` unutulduğunda hata
 yerine stilsiz ama çalışan bir sayfa görürsünüz. Manifest hiç yoksa bir kez uyarı
-basılır: `[assets] manifest yok — 'jskelet build' çalıştırın.`
+basılır: ``[assets] no manifest — run `jskelet build`.``
 
 Manifest **dev'de her istekte** yeniden okunur (watch build hash'leri
 değiştirir), prod'da bir kez.
@@ -244,8 +244,8 @@ Son satır için iki güvenlik ağı var: ad taşıyan yapılandırma alanları
 sembolleri okuyup eksik olan için tek seferlik uyarı basar:
 
 ```
-[icon] sprite'ta yok: x-logo-regular — adı sabit yazın ya da
-build/tasks/icons.mjs taramasına ekleyin.
+[icon] missing from sprite: x-logo-regular — write the name as a literal or add
+it to the build/tasks/icons.mjs scan.
 ```
 
 Bu uyarıyı görürseniz ya adı sabit yazın, ya `icons.scan` listesine ilgili
@@ -352,7 +352,7 @@ karşılaşmaması.
   kontrol edin.
 - **Bazı Tailwind sınıfları çalışmıyor.** `@source` direktifi eksik olan bir
   dizinde yazılmışlar.
-- **İkon boş görünüyor.** Sprite'ta o sembol yok; dev'de `[icon] sprite'ta yok`
+- **İkon boş görünüyor.** Sprite'ta o sembol yok; dev'de `[icon] missing from sprite`
   uyarısına bakın.
 - **Island'lar hiç açılmıyor.** `main.js` manifest'te yok (entry dizini boş ya
   da build atlanmış) veya bir build hatası var.

package/docs/09-dev-araclari.md

@@ -161,6 +161,11 @@ Gösterdikleri:
 - **Prewarm:** ısıtma turunun ilerlemesi; panelden elle tetiklenebilir, tek tek
   yollar tekrar denenebilir.
 - **Süreç:** pid, Node sürümü, uptime, RSS ve heap kullanımı.
+- **Sürüm:** kurulu JSkelet sürümü ve npm'deki `latest` ile karşılaştırması.
+  Yeni bir sürüm varsa **Server** sekmesinde `update` rozeti ve yükseltme
+  komutunu kopyalayan bir satır çıkar. Yoklama açılıştan 1,5 saniye sonra bir
+  kez yapılır, sonucu 6 saat boyunca `os.tmpdir()` içinde saklanır ve ağ yoksa
+  sessizce atlanır. `JSKELET_VERSION_CHECK=0` ile tamamen kapatılır.
 
 Isıtma istekleri (`user-agent: jskelet-prewarm`) hem terminalden hem istek
 listesinden filtrelenir: yüzlerce istek görünümü doldurmasın. İlerleme baloncuğun