jskelet 0.6.16 → 0.7.0

package/CHANGELOG.md

@@ -17,6 +17,16 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Dev tools **Server** tab can clear the HTML cache for the open page, every
+  HTML entry, or the data cache. Live stats include HTML/data entry counts;
+  new endpoints under `devBasePath`: `POST /cache/clear-html`,
+  `/cache/clear-data`, and `/cache/invalidate`.
+- On-demand HTML cache via `cache().prewarm: false`: visited pages still
+  write to L1 and Redis/disk L2 with the usual `html` TTLs, but classic
+  prewarm, `onVisit` link warming, and early-expiry HTTP refresh stay off
+  (`PREWARM=1` does not override). Mutually exclusive with
+  `hooks.prewarmPaths`. Resolved `prewarm.mode` is `"off"` | `"classic"` |
+  `"onVisit"`.
 - When `build.assets.prefix` is set, the CSS build rewrites root-absolute
   `url()` paths under `static.prefixes` (e.g. `/fonts/…`) to the CDN
   prefix so they match the S3 key (`…/js/fonts/…`). Default upload

package/docs/06-cache.md

@@ -1173,10 +1173,34 @@ loopback yalnızca o host'un anahtarını ısıtır — locale sitelerinde
 `origins: ["http://localhost", "http://tr.localhost"]` gibi çoklu origin
 gerekir.
 
-İki mod **karşılıklı dışlayıcıdır**. `cache().prewarm.onVisit` açıksa klasik
-alanlar (`max`, `priority`, `rotate`, `intervalSeconds`, …) ve
-`hooks.prewarmPaths` birlikte verilemez — config yüklenirken hata fırlar.
-Tersi de geçerli: klasik liste ısıtması kullanıyorsanız `onVisit` yazmayın.
+Üç yüzey **karşılıklı dışlayıcıdır**: klasik (`hooks.prewarmPaths` + alanlar),
+`onVisit` ve on-demand (`prewarm: false`). Birini seçmek diğerini config
+yüklenirken reddeder.
+
+### Mod: on-demand — `prewarm: false`
+
+Arka plan ısıtması yok; yalnızca gerçek trafikle gelen sayfa önbelleğe yazılır.
+TTL `cache().html` (veya route `revalidate`) ile verilir. Redis açıksa L2'ye,
+değilse `.jskelet/cache/<buildId>/` disk L2'ye yazılır — ziyaret yazımı zaten
+böyle çalışır; bu mod klasik turu, `onVisit` link crawl'ını ve TTL öncesi
+early-expiry HTTP rewarm'ı kapatır. `PREWARM=1` bunu ezmez.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/": 60, "/haber/:slug": 300 },
+      redis: { enabled: true, url: process.env.REDIS_URL },
+      prewarm: false,
+    };
+  },
+};
+```
+
+`hooks.prewarmPaths` ile birlikte **yasaktır**. `prewarm: { enabled: false }`
+farklıdır: klasik turu keser ama early-expiry drain açık kalır; tamamen pasif
+mod için `prewarm: false` kullanın.
 
 ### Mod: `onVisit` — ziyaret edilen sayfanın linkleri
 
@@ -1442,12 +1466,13 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   `cache().vary.host: true` yoksa ilk locale'in HTML'i diğer host'a servis
   edilir. Prewarm yalnızca `127.0.0.1` ile ısınıyorsa `prewarm.origins` ile
   locale host'larını ekleyin.
-- **Isıtma hiç çalışmıyor.** Klasik modda `hooks.prewarmPaths` tanımlı değil,
-  `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
+- **Isıtma hiç çalışmıyor.** `prewarm: false` (on-demand) bilinçli olarak
+  hiçbir arka plan ısıtması kurmaz. Klasik modda `hooks.prewarmPaths` tanımlı
+  değil, `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
   modunda `listen` sonrası logda `onVisit mode` satırını ve public cache'li
   bir sayfa gezildiğini doğrulayın.
-- **Config `onVisit` + `max` / `prewarmPaths` ile düşüyor.** İki mod karşılıklı
-  dışlayıcı; yalnızca birini kullanın.
+- **Config `onVisit` / `prewarm: false` + `max` / `prewarmPaths` ile düşüyor.**
+  Üç yüzey karşılıklı dışlayıcı; yalnızca birini kullanın.
 - **Isıtma turu API'yi 429'a sokuyor.** `rps` verilmemiş. `concurrency`
   düşürmek yeterli değil; kotayı koruyan ayar toplam hız. Kalıcı çözüm veri
   önbelleği: ikinci turdan sonra ısıtma upstream'e gitmez.

package/docs/07-yapilandirma.md

@@ -770,9 +770,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: false | object }` —
 **Varsayılan:**
-`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0, origins: [] } }`
+`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (veya `prewarm: false` → `mode: "off"`)
 
 ### `cache().html`
 
@@ -1084,14 +1084,28 @@ tam cevabı olmadığı — [06-cache.md](./06-cache.md) içinde.
 
 ### `cache().prewarm`
 
-İki mod: **klasik** (liste + açılış turu) veya **`onVisit`** (ziyaret edilen
-sayfadaki linkler). Birlikte verilemez — config yüklenirken hata.
+Üç yüzey: **`false`** (on-demand — yalnızca ziyaret yazımı), **klasik** (liste
++ açılış turu) veya **`onVisit`** (ziyaret edilen sayfadaki linkler). Birlikte
+verilemez — config yüklenirken hata. Çözümlenen `prewarm.mode`: `"off"` |
+`"classic"` | `"onVisit"`.
+
+#### On-demand — `prewarm: false`
+
+Arka plan ısıtması yok (klasik tur, `onVisit`, early-expiry HTTP rewarm).
+Ziyaret edilen sayfa `html` TTL'i ile L1 + Redis/disk L2'ye yazılır.
+`PREWARM=1` bunu ezmez. `hooks.prewarmPaths` ile **yasak**.
+`{ enabled: false }` klasik turu keser ama early-expiry açık kalır — tamamen
+pasif mod için `false` kullanın.
+
+```js
+prewarm: false,
+```
 
 #### Klasik alanlar
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
+| `enabled` | `boolean` | `true` | `false` ise klasik tur yapılmaz (`PREWARM=1` ile ezilebilir); early-expiry drain açık kalır |
 | `max` | `number` | `400` | Bir turda en fazla kaç yol ısıtılır |
 | `concurrency` | `number` | prod 4, dev 1 | Paralel işçi sayısı |
 | `rps` | `number` | prod `0`, dev 4 | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. Dev'deki varsayılan fren, ısıtmanın sayfa isteklerini bekletmemesi için. |
@@ -1135,8 +1149,8 @@ prewarm: {
 }
 ```
 
-`hooks.prewarmPaths` ve klasik alanlar (`max`, `priority`, …) `onVisit` ile
-**yasaktır**. Ayrıntı: [06-cache.md](./06-cache.md).
+`hooks.prewarmPaths` ve klasik alanlar (`max`, `priority`, …) `onVisit` veya
+`prewarm: false` ile **yasaktır**. Ayrıntı: [06-cache.md](./06-cache.md).
 
 Sayısal alanların her biri aynı adı taşıyan ortam değişkeniyle ezilebilir; env
 önceliklidir. Ayrıntı: [06-cache.md](./06-cache.md).
@@ -1154,7 +1168,7 @@ varsayılanına döner ve uyarır — sayfa düşmez.
 | `layoutContext` | `({ pathname, metadata }) => object` | Layout local'leri; `lang`, `structuredData`, `extraHead`, `bodyClass` özel yorumlanır | [04](./04-render-ve-sablonlar.md) |
 | `notFound` | `() => object \| null` | 404 sayfa tanımı; `null` ise framework'ün hata sayfası | [03](./03-routing.md) |
 | `error` | `({ status, error }) => object \| string \| null` | 404 dışındaki hata sayfaları (ve `notFound` yoksa 404); sayfa tanımı ya da doğrudan HTML | [03](./03-routing.md) |
-| `prewarmPaths` | `() => string[]` | Klasik ısıtmada ısıtılacak yollar; tanımlı değilse klasik tur kurulmaz. `onVisit` ile birlikte **yasak** | [06](./06-cache.md) |
+| `prewarmPaths` | `() => string[]` | Klasik ısıtmada ısıtılacak yollar; tanımlı değilse klasik tur kurulmaz. `onVisit` ve `prewarm: false` ile **yasak** | [06](./06-cache.md) |
 
 ```js
 hooks: {
@@ -1247,7 +1261,7 @@ basılmaz.
 | `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache yüzeyi | — | API token. Verilene kadar CDN purge'ü ve edge analitiği kapalıdır; config'teki `apiToken`'ı ezer. Token hiçbir cevapta dönmez. [06](./06-cache.md) |
 | `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache yüzeyi | — | Zone kimliği. Token'la birlikte verilmedikçe hiçbir Cloudflare ucu çağrılmaz |
 | `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache yüzeyi | — | Purge URL'lerinin kökü. Panel iç bir adresten açılıyorsa gerekir |
-| `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
+| `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar. `prewarm: false` (on-demand) ezilmez |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Paralel işçi sayısı |
 | `PREWARM_RPS` | `prewarm` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız |

package/docs/09-dev-araclari.md

@@ -208,6 +208,11 @@ Gösterdikleri:
   bloke süresi.
 - **Prewarm:** ısıtma turunun ilerlemesi; panelden elle tetiklenebilir, tek tek
   yollar tekrar denenebilir.
+- **Önbellek (Server sekmesi):** HTML ve veri girdisi sayıları; **Clear this
+  page** açık yolun bütün varyantlarını sert düşürüp sayfayı yeniler, **Clear
+  all HTML** / **Clear data cache** süreç önbelleğini boşaltır (onay ister).
+  Aynı işlemler admin panelindeki `html:invalidate` / `html:clear` /
+  `data:clear` ile paylaşılır.
 - **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
@@ -297,6 +302,9 @@ Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç gi
 | `/report/clear` | POST | Sayfa ölçümlerini ve sunucu API kayıtlarını sıfırlar |
 | `/prewarm` | POST | Isıtmayı elle tetikler. Gövdede `paths` varsa yalnızca o yollar; ısıtma zaten çalışıyorsa 409. |
 | `/clear` | POST | İstek ve hata günlüklerini sıfırlar |
+| `/cache/clear-html` | POST | Tüm HTML önbelleğini boşaltır; `{ cleared }` döner |
+| `/cache/clear-data` | POST | Veri önbelleğini boşaltır. Gövdede isteğe bağlı `prefix`; `{ cleared }` döner |
+| `/cache/invalidate` | POST | Gövdede `path` (zorunlu, `/` ile başlamalı) ve isteğe bağlı `hard` (varsayılan `true`). Etkilenen girdi sayısıyla `{ count }` döner |
 
 Bu uçların tamamı `mountDevtools()` tarafından yalnızca
 `NODE_ENV=development` iken bağlanır; prod sürecine dinamik import sayesinde

package/docs/en/06-caching.md

@@ -1175,10 +1175,35 @@ traffic. With `vary.host`, the default loopback only warms that host's key —
 locale sites need multiple origins such as
 `origins: ["http://localhost", "http://tr.localhost"]`.
 
-The two modes are **mutually exclusive**. If `cache().prewarm.onVisit` is on,
-classic fields (`max`, `priority`, `rotate`, `intervalSeconds`, …) and
-`hooks.prewarmPaths` must not be set together — config load throws. The reverse
-holds too: if you use classic list warming, do not set `onVisit`.
+Three surfaces are **mutually exclusive**: classic (`hooks.prewarmPaths` +
+fields), `onVisit`, and on-demand (`prewarm: false`). Choosing one rejects the
+others at config load.
+
+### Mode: on-demand — `prewarm: false`
+
+No background warming; only pages hit by real traffic are written to the cache.
+TTL comes from `cache().html` (or the route `revalidate`). With Redis on, the
+entry goes to L2 Redis; otherwise to the `.jskelet/cache/<buildId>/` disk L2 —
+visit writes already work that way; this mode turns off the classic pass,
+`onVisit` link crawling, and early-expiry HTTP refresh before TTL. `PREWARM=1`
+does not override it.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/": 60, "/news/:slug": 300 },
+      redis: { enabled: true, url: process.env.REDIS_URL },
+      prewarm: false,
+    };
+  },
+};
+```
+
+**Forbidden** together with `hooks.prewarmPaths`. `prewarm: { enabled: false }`
+is different: it stops the classic pass but leaves the early-expiry drain on —
+use `prewarm: false` for fully passive mode.
 
 ### Mode: `onVisit` — links from the page just visited
 
@@ -1449,12 +1474,13 @@ filled the cache.
   without `cache().vary.host: true` the first locale's HTML is served to the
   other host. If prewarm only hits `127.0.0.1`, add the locale hosts via
   `prewarm.origins`.
-- **The warm-up never runs.** In classic mode `hooks.prewarmPaths` is not
+- **The warm-up never runs.** `prewarm: false` (on-demand) intentionally
+  installs no background warming. In classic mode `hooks.prewarmPaths` is not
   defined, `PREWARM=0` is set, or `cache().prewarm.enabled === false`. In
   `onVisit` mode check the `onVisit mode` log line after `listen` and that a
   public cacheable page was visited.
-- **Config fails with `onVisit` + `max` / `prewarmPaths`.** The two modes are
-  mutually exclusive; use only one.
+- **Config fails with `onVisit` / `prewarm: false` + `max` / `prewarmPaths`.**
+  The three surfaces are mutually exclusive; use only one.
 - **The warm-up round pushes the API into 429.** No `rps` was given. Lowering
   `concurrency` is not enough; the setting that protects the quota is the total
   rate. The lasting fix is the data cache: after the second round the warm-up

package/docs/en/07-configuration.md

@@ -784,9 +784,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: false | object }` —
 **Default:**
-`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0, origins: [] } }`
+`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (or `prewarm: false` → `mode: "off"`)
 
 ### `cache().html`
 
@@ -1106,14 +1106,28 @@ edges hold this page" has no exact answer — is in
 
 ### `cache().prewarm`
 
-Two modes: **classic** (list + startup pass) or **`onVisit`** (links from the
-page just visited). They cannot be combined — config load throws.
+Three surfaces: **`false`** (on-demand — visit writes only), **classic** (list
++ startup pass), or **`onVisit`** (links from the page just visited). They
+cannot be combined — config load throws. Resolved `prewarm.mode`: `"off"` |
+`"classic"` | `"onVisit"`.
+
+#### On-demand — `prewarm: false`
+
+No background warming (classic pass, `onVisit`, early-expiry HTTP refresh).
+Visited pages still write to L1 + Redis/disk L2 with the `html` TTLs.
+`PREWARM=1` does not override. **Forbidden** with `hooks.prewarmPaths`.
+`{ enabled: false }` stops the classic pass but leaves early-expiry on — use
+`false` for fully passive mode.
+
+```js
+prewarm: false,
+```
 
 #### Classic fields
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
+| `enabled` | `boolean` | `true` | If `false`, no classic pass (`PREWARM=1` can override); early-expiry drain stays on |
 | `max` | `number` | `400` | At most how many paths are prewarmed per pass |
 | `concurrency` | `number` | prod 4, dev 1 | Number of parallel workers |
 | `rps` | `number` | prod `0`, dev 4 | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. The default brake in dev keeps prewarming from holding page requests up. |
@@ -1158,7 +1172,7 @@ prewarm: {
 ```
 
 `hooks.prewarmPaths` and classic fields (`max`, `priority`, …) are **forbidden**
-with `onVisit`. Details: [06-caching.md](./06-caching.md).
+with `onVisit` or `prewarm: false`. Details: [06-caching.md](./06-caching.md).
 
 Each numeric field can be overridden by an environment variable of the same
 name; env takes precedence. Details: [06-caching.md](./06-caching.md).
@@ -1176,7 +1190,7 @@ its own default and warns — the page does not go down.
 | `layoutContext` | `({ pathname, metadata }) => object` | Layout locals; `lang`, `structuredData`, `extraHead` and `bodyClass` get special treatment | [04](./04-rendering.md) |
 | `notFound` | `() => object \| null` | 404 page definition; if `null`, the framework's error page | [03](./03-routing.md) |
 | `error` | `({ status, error }) => object \| string \| null` | Error pages other than 404 (and 404 when there is no `notFound`); a page definition or HTML directly | [03](./03-routing.md) |
-| `prewarmPaths` | `() => string[]` | Paths for classic prewarm; if omitted, the classic pass is never set up. **Forbidden** with `onVisit` | [06](./06-caching.md) |
+| `prewarmPaths` | `() => string[]` | Paths for classic prewarm; if omitted, the classic pass is never set up. **Forbidden** with `onVisit` and `prewarm: false` | [06](./06-caching.md) |
 
 ```js
 hooks: {
@@ -1270,7 +1284,7 @@ and no warning is printed.
 | `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache surface | — | API token. Until it is set, CDN purging and edge analytics stay off; it overrides `apiToken` in the config. The token is never returned in a response. [06](./06-caching.md) |
 | `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache surface | — | Zone identifier. No Cloudflare endpoint is called unless it is set alongside the token |
 | `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache surface | — | The root for purge URLs. Required when the panel is opened over an internal address |
-| `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |
+| `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on. Does not override `prewarm: false` (on-demand) |
 | `PREWARM_MAX` | `prewarm` | `400` | At most how many paths are prewarmed |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Number of parallel workers |
 | `PREWARM_RPS` | `prewarm` | `0` | At most how many prewarm requests per second; `0` is unlimited |

package/docs/en/09-dev-tools.md

@@ -213,6 +213,11 @@ What it shows:
   blocking time.
 - **Prewarm:** the progress of the warming round; it can be triggered manually
   from the panel, and individual paths can be retried.
+- **Cache (Server tab):** HTML and data entry counts; **Clear this page**
+  hard-drops every variant of the open path and reloads, **Clear all HTML** /
+  **Clear data cache** empty the in-process caches (with a confirm). Same
+  core APIs as the admin panel's `html:invalidate` / `html:clear` /
+  `data:clear`.
 - **Process:** pid, Node version, uptime, RSS and heap usage.
 - **Version:** the installed JSkelet version compared against the `latest` tag
   on npm. When a newer release exists, the **Server** tab grows an `update` chip
@@ -302,6 +307,9 @@ Under `brand.devBasePath` (default `/__jskelet/dev`):
 | `/report/clear` | POST | Resets page measurements and server API records |
 | `/prewarm` | POST | Triggers warming manually. If the body has `paths`, only those paths; 409 if warming is already running. |
 | `/clear` | POST | Resets the request and error logs |
+| `/cache/clear-html` | POST | Clears the entire HTML cache; returns `{ cleared }` |
+| `/cache/clear-data` | POST | Clears the data cache. Optional `prefix` in the body; returns `{ cleared }` |
+| `/cache/invalidate` | POST | Body: required `path` (must start with `/`) and optional `hard` (default `true`). Returns `{ count }` for affected entries |
 
 All of these endpoints are mounted by `mountDevtools()` only when
 `NODE_ENV=development`; thanks to the dynamic import, nothing is loaded into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.16",
+  "version": "0.7.0",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk SSR (optional EJS peer), vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/client/devtools/overlay.js

@@ -861,6 +861,93 @@ async function clearAll() {
   pollServer();
 }
 
+/** Son önbellek eyleminin kısa geri bildirimi; sonraki poll'da silinmez. */
+let cacheNotice = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let cacheNoticeTimer = null;
+
+/**
+ * @param {string} message
+ */
+function setCacheNotice(message) {
+  cacheNotice = message;
+  if (cacheNoticeTimer) clearTimeout(cacheNoticeTimer);
+  cacheNoticeTimer = setTimeout(() => {
+    cacheNotice = null;
+    cacheNoticeTimer = null;
+    lastBody = "";
+    render();
+  }, 4000);
+  lastBody = "";
+  render();
+}
+
+/**
+ * Bu sekmenin HTML önbelleğini düşürür ve sayfayı yeniler — aksi hâlde
+ * tarayıcıdaki DOM eski kalır, soğuk render görülmez.
+ */
+async function clearThisPageCache() {
+  const path = location.pathname || "/";
+  try {
+    await fetch(`${BASE}/cache/invalidate`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path, hard: true }),
+    });
+  } catch {
+    setCacheNotice("Could not reach the server to clear this page.");
+    return;
+  }
+  saveState();
+  location.reload();
+}
+
+async function clearHtmlCacheAll() {
+  if (
+    !confirm(
+      "Clear the entire HTML cache? Every page goes cold until the next render or prewarm.",
+    )
+  ) {
+    return;
+  }
+
+  try {
+    const response = await fetch(`${BASE}/cache/clear-html`, { method: "POST" });
+    const body = await response.json().catch(() => ({}));
+    setCacheNotice(
+      `HTML cache cleared (${typeof body.cleared === "number" ? body.cleared : "?"} entries).`,
+    );
+  } catch {
+    setCacheNotice("Could not clear the HTML cache.");
+  }
+  pollServer();
+}
+
+async function clearDataCacheAll() {
+  if (
+    !confirm(
+      "Clear every data-cache entry? Upstream traffic will spike on the next renders.",
+    )
+  ) {
+    return;
+  }
+
+  try {
+    const response = await fetch(`${BASE}/cache/clear-data`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const body = await response.json().catch(() => ({}));
+    setCacheNotice(
+      `Data cache cleared (${typeof body.cleared === "number" ? body.cleared : "?"} entries).`,
+    );
+  } catch {
+    setCacheNotice("Could not clear the data cache.");
+  }
+  pollServer();
+}
+
 /* ---------------------------------------------------------------- arayüz */
 
 const CSS = `
@@ -1162,6 +1249,7 @@ h4 .head-action { float: inline-end; text-transform: none; letter-spacing: 0; }
 .status.warn { background: rgba(251,191,36,.14); color: var(--mid); }
 .status.bad { background: rgba(251,113,133,.14); color: var(--bad); }
 .hint { color: var(--muted); font-size: 10.5px; }
+.hint.block { display: block; margin: 0 0 8px; line-height: 1.45; }
 .row .good { color: var(--good); } .row .mid { color: var(--mid); } .row .bad { color: var(--bad); }
 .row.clickable { cursor: pointer; grid-template-columns: auto auto 1fr auto auto; }
 .row.clickable.selected { border-color: rgba(255,255,255,.22); background: var(--surface-hover); }
@@ -1200,9 +1288,14 @@ h4 .head-action { float: inline-end; text-transform: none; letter-spacing: 0; }
 .btn.mini { display: inline-flex; align-items: center; gap: 6px; padding: 4px 9px; font-size: 11px; }
 .btn.mini svg { width: 12px; height: 12px; }
 .btn[disabled] { opacity: .5; cursor: default; }
-.toolbar { display: flex; justify-content: flex-end; margin-bottom: 10px; }
+.toolbar { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 6px; margin-bottom: 10px; }
+.toolbar.start { justify-content: flex-start; }
 .btn.danger { color: #ffc9d2; border-color: rgba(251,113,133,.28); background: rgba(251,113,133,.1); }
 .btn.danger:hover { color: #fff; border-color: rgba(251,113,133,.55); background: rgba(251,113,133,.22); }
+.notice {
+  margin: 0 0 10px; padding: 8px 10px; border-radius: 8px; font-size: 12px; line-height: 1.4;
+  color: #b9f2dc; background: rgba(52,211,153,.1); border: 1px solid rgba(52,211,153,.28);
+}
 `;
 
 let shadow = null;
@@ -2022,6 +2115,14 @@ function serverTab() {
       { label: "Avg. render", value: ms(average), tone: grade(average, [150, 500]) },
       { label: "Slowest", value: ms(slowest), tone: grade(slowest, [300, 1000]) },
       { label: "Restart", value: String(restarts), tone: offline ? "mid" : "" },
+      {
+        label: "HTML cache",
+        value: String(serverStats.cache?.html ?? 0),
+      },
+      {
+        label: "Data cache",
+        value: String(serverStats.cache?.data ?? 0),
+      },
       ...(serverStats.prewarm?.total
         ? [
             {
@@ -2033,6 +2134,7 @@ function serverTab() {
           ]
         : []),
     ])}
+    ${cacheSection()}
     ${upstreamSection()}
     <h4>Recent requests</h4>
     ${
@@ -2052,6 +2154,42 @@ function serverTab() {
   `;
 }
 
+/**
+ * HTML / veri önbelleğini panelden boşaltma. Admin panelindeki aynı işlemlerin
+ * kısa yolu; "bu sayfa" mevcut `location.pathname` için sert düşürme yapar.
+ *
+ * @returns {string}
+ */
+function cacheSection() {
+  const path = location.pathname || "/";
+  const html = serverStats?.cache?.html ?? 0;
+  const data = serverStats?.cache?.data ?? 0;
+
+  return `
+    <h4>Cache</h4>
+    ${
+      cacheNotice
+        ? `<div class="notice">${escapeHtml(cacheNotice)}</div>`
+        : ""
+    }
+    <p class="hint block">
+      In-process HTML (${html}) and data (${data}) entries.
+      Clearing this page drops every variant of <code>${escapeHtml(path)}</code> and reloads.
+    </p>
+    <div class="toolbar start">
+      <button class="btn mini" data-action="cache-page" title="Hard-drop HTML for ${escapeHtml(path)}">
+        ${TRASH_ICON} Clear this page
+      </button>
+      <button class="btn mini danger" data-action="cache-html" title="Clear every HTML cache entry">
+        ${TRASH_ICON} Clear all HTML
+      </button>
+      <button class="btn mini danger" data-action="cache-data" title="Clear every data-cache entry">
+        ${TRASH_ICON} Clear data cache
+      </button>
+    </div>
+  `;
+}
+
 /**
  * Upstream hız freninin durumu. Fren kapalıysa (varsayılan) hiçbir şey
  * basılmaz; açıkken 429 fırtınasında hızın nereye indiğini görmek, ayarı
@@ -2224,7 +2362,7 @@ const ABOUT = {
       <div class="step"><span class="n">1</span><span><b>Route</b><span><code>server/routes/</code> matches the URL and hands the request to the right controller.</span></span></div>
       <div class="step"><span class="n">2</span><span><b>Controller</b><span><code>server/controllers/</code> gathers the data it needs from the <code>lib/</code> services and prepares the model for the template.</span></span></div>
       <div class="step"><span class="n">3</span><span><b>Render</b><span><code>server/render.js</code> runs the EJS template and prints manifest entries and head hints into the layout.</span></span></div>
-      <div class="step"><span class="n">4</span><span><b>HTML cache</b><span><code>server/html-cache.js</code> stores the output; if the same URL is requested again the template never runs. The <code>cached</code> label on the Server tab shows this.</span></span></div>
+      <div class="step"><span class="n">4</span><span><b>HTML cache</b><span><code>server/html-cache.js</code> stores the output; if the same URL is requested again the template never runs. The Server tab shows entry counts and can clear this page, all HTML, or the data cache.</span></span></div>
       <div class="step"><span class="n">5</span><span><b>Response</b><span>Compression and cache headers are decided in <code>server/middleware/</code>; responses like event streams skip compression.</span></span></div>
     </div>
     <p><strong>Prewarming:</strong> <code>server/prewarm.js</code> visits the most travelled
@@ -2734,6 +2872,21 @@ function bind(root) {
     }
 
     if (target.dataset.action === "clear") clearAll();
+
+    if (target.dataset.action === "cache-page") {
+      void clearThisPageCache();
+      return;
+    }
+
+    if (target.dataset.action === "cache-html") {
+      void clearHtmlCacheAll();
+      return;
+    }
+
+    if (target.dataset.action === "cache-data") {
+      void clearDataCacheAll();
+      return;
+    }
   });
 }
 

package/src/config/defaults.js

@@ -51,12 +51,17 @@ export const DEFAULT_DEV_GATE_BYPASS = [
 ];
 
 /**
- * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
- * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
- * linkleri ısıtma.
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` ve `prewarm: false`
+ * (on-demand) ile birlikte kullanılamaz — ya açılış/`prewarmPaths` turu, ya
+ * ziyaret edilen sayfadaki linkleri ısıtma, ya yalnızca ziyaret yazımı.
+ *
+ * `mode` çözümleme sonucu: `"classic"` | `"onVisit"` | `"off"`.
+ * `prewarm: false` → `"off"` (erken TTL ısıtması dahil hiçbir arka plan yok).
  */
 export const DEFAULT_PREWARM = {
   enabled: true,
+  /** @type {"classic" | "onVisit" | "off"} */
+  mode: "classic",
   max: 400,
   intervalSeconds: 0,
   /** Paralel ısıtma isteği; dev'de sunucu tek süreç olduğu için düşürülür. */

package/src/config/index.js

@@ -940,18 +940,38 @@ function normalizeOnVisit(raw) {
 }
 
 /**
- * Klasik liste ısıtması ile `onVisit` karşılıklı dışlayıcıdır. İkisini birden
- * yazmak sessizce yanlış moda düşmesin diye yüklemede hata verir.
+ * Klasik liste ısıtması, `onVisit` ve `prewarm: false` (on-demand) karşılıklı
+ * dışlayıcıdır. Yanlış moda sessizce düşülmesin diye yüklemede hata verir.
  *
  * @param {unknown} raw
  * @returns {Record<string, unknown>}
  */
 function normalizePrewarm(raw) {
+  // On-demand: yalnızca ziyaret yazımı. Klasik / onVisit / early-expiry yok.
+  if (raw === false) {
+    return {
+      ...DEFAULT_PREWARM,
+      enabled: false,
+      mode: "off",
+      onVisit: { ...DEFAULT_PREWARM_ON_VISIT, enabled: false },
+    };
+  }
+
+  if (raw != null && (typeof raw !== "object" || Array.isArray(raw))) {
+    throw new Error(
+      "[config] cache().prewarm must be false, or an object " +
+        "(classic settings or { onVisit })",
+    );
+  }
+
   const source =
     raw && typeof raw === "object" && !Array.isArray(raw)
       ? /** @type {Record<string, unknown>} */ ({ ...raw })
       : {};
 
+  // `mode` çözümleme alanı; kullanıcı yazarsa yok sayılır.
+  delete source.mode;
+
   const onVisit = normalizeOnVisit(source.onVisit);
 
   if (onVisit.enabled) {
@@ -977,12 +997,15 @@ function normalizePrewarm(raw) {
     return {
       ...DEFAULT_PREWARM,
       enabled: true,
+      mode: "onVisit",
       onVisit,
     };
   }
 
   // Klasik mod: `onVisit: false` yazılmış olabilir; diğer alanlar varsayılanlarla
   // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
+  // `enabled: false` klasik turu keser ama early-expiry drain açık kalır —
+  // tamamen kapatmak için `prewarm: false` (`mode: "off"`) kullanılır.
   const classic = { ...source };
   delete classic.onVisit;
 
@@ -994,6 +1017,7 @@ function normalizePrewarm(raw) {
   return {
     ...DEFAULT_PREWARM,
     ...classic,
+    mode: "classic",
     onVisit,
   };
 }
@@ -1698,6 +1722,17 @@ export async function loadConfig(options = {}) {
     );
   }
 
+  if (
+    config.prewarm?.mode === "off" &&
+    typeof config.hooks?.prewarmPaths === "function"
+  ) {
+    throw new Error(
+      "[config] hooks.prewarmPaths() cannot be used with cache().prewarm: false. " +
+        "On-demand mode only caches pages as they are visited; classic mode uses " +
+        "prewarmPaths. Choose one.",
+    );
+  }
+
   // Dev'de build ve sunucu ayrı alt süreçler; üçü de aynı özeti basınca satır
   // banner'ın ve build bloğunun arasına üç kez giriyor. Özeti dış süreç basar.
   if (loaded && !process.env.JSKELET_CHILD) {

package/src/server/dev/devtools.js

@@ -15,7 +15,12 @@ import * as log from "../../log.mjs";
 import { FRAMEWORK_ROOT, getConfig } from "../../config/index.js";
 import { getRequestContext } from "../../http/request-context.js";
 import { prewarm, prewarmProgress } from "../prewarm.js";
-import { clearHtmlCache } from "../html-cache.js";
+import {
+  clearHtmlCache,
+  getHtmlCacheSize,
+  invalidateHtmlCache,
+} from "../html-cache.js";
+import { clearDataCache, getDataCacheSize } from "../data-cache.js";
 import {
   buildReport,
   clearPageReports,
@@ -325,6 +330,12 @@ function statsPayload() {
     version: versionStatus(),
     memory: { rss: usage.rss, heapUsed: usage.heapUsed },
     prewarm: { ...prewarmProgress },
+    // Overlay Server sekmesindeki önbellek sayaçları; her kalp atışında
+    // güncellenir ki temizleme sonrası yenilemeye gerek kalmasın.
+    cache: {
+      html: getHtmlCacheSize(),
+      data: getDataCacheSize(),
+    },
     requests: requests.slice(-25).reverse(),
     errors: errors.slice(-25).reverse(),
     // SSR dış çağrıları: overlay API sekmesi hangi sayfanın hangi
@@ -557,6 +568,41 @@ function router() {
     res.json({ ok: true });
   });
 
+  // Panelden HTML / veri önbelleğini elle boşaltma. Admin panelindeki
+  // `html:clear` / `html:invalidate` / `data:clear` ile aynı çekirdek API;
+  // yalnızca development'ta ve CSRF'siz — overlay zaten aynı origin'den gelir.
+  api.post("/cache/clear-html", (req, res) => {
+    const cleared = getHtmlCacheSize();
+    clearHtmlCache();
+    pushStats();
+    res.json({ ok: true, cleared });
+  });
+
+  api.post("/cache/clear-data", express.json({ limit: "8kb" }), (req, res) => {
+    const prefix =
+      typeof req.body?.prefix === "string" && req.body.prefix
+        ? req.body.prefix
+        : undefined;
+    const cleared = clearDataCache(prefix);
+    pushStats();
+    res.json({ ok: true, cleared });
+  });
+
+  api.post("/cache/invalidate", express.json({ limit: "8kb" }), (req, res) => {
+    const target = String(req.body?.path ?? "");
+    if (!target.startsWith("/")) {
+      res.status(400).json({ ok: false, reason: "path" });
+      return;
+    }
+
+    // Dev panelinde "bu sayfayı sil" soğuk render bekler; yumuşak bayatlatma
+    // eski HTML'i servis etmeye devam eder ve etkisi görünmez kalır.
+    const hard = req.body?.hard !== false;
+    const count = invalidateHtmlCache(target, { hard });
+    pushStats();
+    res.json({ ok: true, count, path: target, hard });
+  });
+
   return api;
 }
 

package/src/server/prewarm.js

@@ -928,6 +928,8 @@ async function drainVisitWarm() {
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
  * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
  * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
+ * `prewarm: false` (`mode: "off"`) on-demand: ziyaret yazımı kalır, hiçbir
+ * arka plan ısıtması kurulmaz; `PREWARM=1` bunu ezmez.
  *
  * @param {{ port: number }} options
  * @returns {void}
@@ -935,12 +937,14 @@ async function drainVisitWarm() {
 export function startPrewarm({ port }) {
   const config = getConfig();
   if (process.env.PREWARM === "0") return;
+  // On-demand: L1/L2 ziyaretle dolar; classic / onVisit / early-expiry yok.
+  if (config.prewarm?.mode === "off") return;
 
   const origins = resolvePrewarmOrigins(port);
   const origin = origins[0];
 
   // Klasik `prewarmPaths` olmasa da TTL öncesi soft-bayatlayan girdiler
-  // HTTP ile ısıtılsın. `PREWARM=0` yukarıda her şeyi keser.
+  // HTTP ile ısıtılsın. `PREWARM=0` / `mode: "off"` yukarıda her şeyi keser.
   startEarlyExpirySweep();
   startExpiryWarmDrain(origins);
 

package/types/config/defaults.d.ts

@@ -40,12 +40,17 @@ export declare const DEFAULT_STATIC: {
 /** Dev gate'in hiçbir koşulda kapatmadığı yollar. */
 export declare const DEFAULT_DEV_GATE_BYPASS: string[];
 /**
- * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
- * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
- * linkleri ısıtma.
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` ve `prewarm: false`
+ * (on-demand) ile birlikte kullanılamaz — ya açılış/`prewarmPaths` turu, ya
+ * ziyaret edilen sayfadaki linkleri ısıtma, ya yalnızca ziyaret yazımı.
+ *
+ * `mode` çözümleme sonucu: `"classic"` | `"onVisit"` | `"off"`.
+ * `prewarm: false` → `"off"` (erken TTL ısıtması dahil hiçbir arka plan yok).
  */
 export declare const DEFAULT_PREWARM: {
     enabled: boolean;
+    /** @type {"classic" | "onVisit" | "off"} */
+    mode: "classic" | "onVisit" | "off";
     max: number;
     intervalSeconds: number;
     /** Paralel ısıtma isteği; dev'de sunucu tek süreç olduğu için düşürülür. */

package/types/server/prewarm.d.ts

@@ -122,6 +122,8 @@ export declare function noteVisitWarm(html: string, context: {
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
  * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
  * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
+ * `prewarm: false` (`mode: "off"`) on-demand: ziyaret yazımı kalır, hiçbir
+ * arka plan ısıtması kurulmaz; `PREWARM=1` bunu ezmez.
  *
  * @param {{ port: number }} options
  * @returns {void}