jskelet 0.6.16 → 0.6.17

package/CHANGELOG.md

@@ -17,6 +17,12 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.16",
+  "version": "0.6.17",
   "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/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/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}