jskelet 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -10,6 +10,11 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Visit-driven HTML prewarm (`cache().prewarm.onVisit`): after each public
+  cacheable page response, same-origin links in the HTML are warmed in the
+  background (document order, `perPage` cap). Mutually exclusive with classic
+  prewarm (`max` / `priority` / `rotate` / `hooks.prewarmPaths`, etc.) — mixing
+  them fails at config load.
 - Runtime remote image optimizer: set `images.remote.allowHosts` to proxy
   allowlisted http(s) images through `/_jskelet/image?url=&w=&q=` as resized
   webp (disk cache under `.jskelet/image-cache/`). `image()` rewrites matching
@@ -28,6 +33,10 @@ one is listed under a **Breaking** heading.
 
 ### Fixed
 
+- Remote image optimizer cache hits no longer 404. Disk cache lives under
+  `.jskelet/image-cache/`; Express `sendFile` ignores dotfiles by default, so
+  the file was written but the response still failed. `sendCached` now passes
+  `dotfiles: "allow"`.
 - Cloudflare analytics in the cache panel no longer asks for an open-ended
   window. Queries used only `datetime_geq`, so Cloudflare closed the range at
   query time and a default 24h lookback became `1d` plus network delay — Free

package/docs/06-cache.md

@@ -1052,19 +1052,68 @@ yönlenen gerçek bir istekle o edge'in önbelleğine giriyor; sunucudan
 cache'lememe kararının en sık sebepleri, ve bu panelde `dynamic` olarak
 görünür.
 
-## Prewarm — açılışta ısıtma
+## Prewarm — açılışta veya ziyarette ısıtma
 
 Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz: önbellek
-süreç belleğinde yaşadığı için ısıtma da süreç ayağa kalkınca yapılır. Kazanç
-aynı — ilk ziyaretçi soğuk render'ı beklemez — fakat veri dondurulmaz; her girdi
-route'un `revalidate` süresiyle yaşlanır ve stale-while-revalidate ile arkada
-tazelenir.
+süreç belleğinde yaşadığı için ısıtma da süreç ayağa kalkınca (klasik mod) ya
+da trafik geldikçe (`onVisit`) yapılır. Kazanç aynı — tıklanan / komşu sayfa
+soğuk render'ı beklemez — fakat veri dondurulmaz; her girdi route'un
+`revalidate` süresiyle yaşlanır ve stale-while-revalidate ile arkada tazelenir.
 
 Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>`), çünkü
 cache anahtarı, sıkıştırma ve middleware zinciri normal trafikle bire bir aynı
 olsun.
 
-### `hooks.prewarmPaths()`
+İ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.
+
+### Mod: `onVisit` — ziyaret edilen sayfanın linkleri
+
+Bir kullanıcı herkese açık, önbelleklenebilir bir sayfayı (`public` HTML, 200)
+aldığında framework yanıt HTML'indeki aynı-origin `<a href>` yollarını (üstten
+alta, `perPage` kadar) kuyruğa alır ve arka planda ısıtır. Bir sonraki tıklama
+veya aynı sayfaya gelen başka ziyaretçi çoğu zaman `HIT` görür.
+
+```js
+// jskelet.config.mjs
+export default {
+  async cache() {
+    return {
+      html: { "/": 60, "/haber/:slug": 300 },
+      prewarm: {
+        onVisit: {
+          perPage: 20,      // sayfa başına en fazla link
+          concurrency: 2,   // opsiyonel
+          rps: 4,           // opsiyonel; 0 = sınırsız
+        },
+      },
+    };
+  },
+};
+```
+
+`onVisit: true` de yeterlidir (varsayılan `perPage: 20`).
+
+Kurallar:
+
+- Yalnızca `route()` ile giden **public + cache'lenebilir** 200 HTML tetikler;
+  `private`, degraded veya `no-store` yanıtlar link çıkarmaz.
+- Isıtma isteğinin kendi UA'sı (`brand.prewarmUserAgent`) tetiklemez — sonsuz
+  crawl olmaz.
+- Zaten taze olan yollar kuyruğa girmez.
+- `nofollow`, `target="_blank"`, `data-no-prefetch`, `prewarmSkip` ve
+  `navigation.exclude` Speculation Rules ile aynı muafiyetleri paylaşır.
+- Query string ısıtılmaz (varsayılan cache politikası query'yi dinamik sayar).
+- Açılışta otomatik tur yoktur; ilk ziyaretçi o sayfa için hâlâ MISS
+  ödeyebilir. Kritik yolları deploy öncesi sıcak tutmak istiyorsanız klasik
+  modu veya readiness + seed tercih edin.
+- `PREWARM=0` onVisit'i de kapatır. `PREWARM_MAX` / `PREWARM_INTERVAL_SECONDS`
+  / `PREWARM_DELAY_MS` / `PREWARM_RETRY_DELAY_MS` onVisit ile birlikte
+  kullanılamaz (hata).
+
+### Mod: klasik — `hooks.prewarmPaths()`
 
 Hangi yolların ısıtılacağını uygulama bildirir; genelde sitemap üreten
 fonksiyonun aynısıdır.
@@ -1089,9 +1138,10 @@ Kurallar:
   `/api/`, `/_fragment/`, `/__jskelet/`. Oturuma bağlı sayfalar ısıtılmamalı.
 - Tekilleştirme **sırayı korur**: `priority` verilmediğinde uygulamanın verdiği
   sıra anlamlıdır — en önemli sayfaları başa koyun.
-- Bu hook tanımlı değilse ısıtma hiç kurulmaz; zamanlayıcı bile açılmaz.
+- Bu hook tanımlı değilse klasik ısıtma hiç kurulmaz; zamanlayıcı bile açılmaz.
+  (`onVisit` modunda hook **yasaktır**, yukarıya bakın.)
 
-### Tur mantığı
+### Tur mantığı (klasik)
 
 1. Liste toplanır. `max`'tan (varsayılan 400) uzunsa bir dilim seçilir:
    `priority` eşleşenler **her turda** başa alınır, kalan yerler kuyruktan
@@ -1272,8 +1322,12 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   fazla `revalidate` + bir tazeleme turudur.
 - **Önbellek şişiyor.** Query parametreleri anahtara girdiği için kampanya
   parametreleri girdi çoğaltıyor olabilir.
-- **Isıtma hiç çalışmıyor.** `hooks.prewarmPaths` tanımlı değil, `PREWARM=0`
-  ayarlı ya da `cache().prewarm.enabled === false`.
+- **Isıtma hiç çalışmıyor.** 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.
 - **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

@@ -882,6 +882,11 @@ 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.
+
+#### Klasik alanlar
+
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
@@ -910,6 +915,24 @@ prewarm: {
 }
 ```
 
+#### `onVisit`
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `onVisit` | `true \| false \| object` | kapalı | Ziyaret tabanlı ısıtma |
+| `onVisit.perPage` | `number` | `20` | Sayfa başına üstten alta en fazla link |
+| `onVisit.concurrency` | `number` | klasik ile aynı | Paralel işçi |
+| `onVisit.rps` | `number` | klasik ile aynı | Saniyedeki tavan; `0` sınırsız |
+
+```js
+prewarm: {
+  onVisit: { perPage: 20, rps: 4 },
+}
+```
+
+`hooks.prewarmPaths` ve klasik alanlar (`max`, `priority`, …) `onVisit` 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).
 
@@ -926,7 +949,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[]` | Isıtılacak yollar; tanımlı değilse ısıtma hiç kurulmaz | [06](./06-cache.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) |
 
 ```js
 hooks: {

package/docs/en/06-caching.md

@@ -1051,20 +1051,69 @@ before anything else: `Cache-Control: private`, `Set-Cookie` and query string
 settings are the most common reasons an edge decides not to cache, and they
 show up as `dynamic` in this panel.
 
-## Prewarm — warming up at startup
+## Prewarm — warming at startup or on visit
 
 The equivalent of Next's build-time prerender, except the output is not written
-to disk: since the cache lives in process memory, the warm-up also happens when
-the process comes up. The gain is the same — the first visitor does not wait
-for a cold render — but the data is not frozen; every entry ages with the
-route's `revalidate` and is refreshed in the background with
-stale-while-revalidate.
+to disk: since the cache lives in process memory, the warm-up happens when the
+process comes up (classic mode) or as traffic arrives (`onVisit`). The gain is
+the same — the clicked / neighbouring page does not wait for a cold render —
+but the data is not frozen; every entry ages with the route's `revalidate` and
+is refreshed in the background with stale-while-revalidate.
 
 The warm-up is done with **real HTTP requests**
 (`http://127.0.0.1:<port>`), so that the cache key, the compression and the
 middleware chain are exactly the same as with normal traffic.
 
-### `hooks.prewarmPaths()`
+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`.
+
+### Mode: `onVisit` — links from the page just visited
+
+When a user receives a public, cacheable page (`public` HTML, 200), the
+framework takes same-origin `<a href>` paths from the response HTML (top to
+bottom, up to `perPage`) and warms them in the background. The next click, or
+another visitor to the same neighbourhood, usually sees a `HIT`.
+
+```js
+// jskelet.config.mjs
+export default {
+  async cache() {
+    return {
+      html: { "/": 60, "/news/:slug": 300 },
+      prewarm: {
+        onVisit: {
+          perPage: 20,      // at most this many links per page
+          concurrency: 2,   // optional
+          rps: 4,           // optional; 0 = unlimited
+        },
+      },
+    };
+  },
+};
+```
+
+`onVisit: true` is enough (default `perPage: 20`).
+
+Rules:
+
+- Only **public + cacheable** 200 HTML from `route()` triggers it; `private`,
+  degraded or `no-store` responses do not extract links.
+- The warmer's own UA (`brand.prewarmUserAgent`) does not trigger — no crawl
+  loop.
+- Paths that are already fresh are not enqueued.
+- `nofollow`, `target="_blank"`, `data-no-prefetch`, `prewarmSkip` and
+  `navigation.exclude` share the same exemptions as Speculation Rules.
+- Query strings are not warmed (default cache policy treats query as dynamic).
+- There is no automatic startup pass; the first visitor to a page may still pay
+  a MISS. If you need critical paths hot before traffic, prefer classic mode or
+  readiness + a seed.
+- `PREWARM=0` turns onVisit off too. `PREWARM_MAX` / `PREWARM_INTERVAL_SECONDS`
+  / `PREWARM_DELAY_MS` / `PREWARM_RETRY_DELAY_MS` cannot be used with onVisit
+  (error).
+
+### Mode: classic — `hooks.prewarmPaths()`
 
 The application declares which paths get warmed; usually it is the very same
 function that produces the sitemap.
@@ -1090,11 +1139,10 @@ Rules:
   not be warmed.
 - Deduplication **preserves order**: when no `priority` is given, the order the
   application provides is meaningful — put the most important pages first.
-- If this hook is not defined the warm-up is never set up; not even the timer
-  is started.
-
-### Round logic
+- If this hook is not defined the classic warm-up is never set up; not even the
+  timer is started. (In `onVisit` mode the hook is **forbidden** — see above.)
 
+### Round logic (classic)
 1. The list is collected. If it is longer than `max` (400 by default) a slice is
    selected: the paths matching `priority` are taken first **on every round**,
    and the remaining slots are filled from the queue.
@@ -1277,8 +1325,12 @@ filled the cache.
   lag is at most `revalidate` + one refresh round.
 - **The cache is bloating.** Because query parameters go into the key, campaign
   parameters may be multiplying entries.
-- **The warm-up never runs.** `hooks.prewarmPaths` is not defined, `PREWARM=0`
-  is set, or `cache().prewarm.enabled === false`.
+- **The warm-up never runs.** 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.
 - **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

@@ -902,6 +902,11 @@ 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.
+
+#### Classic fields
+
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
@@ -930,6 +935,24 @@ prewarm: {
 }
 ```
 
+#### `onVisit`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `onVisit` | `true \| false \| object` | off | Visit-driven warming |
+| `onVisit.perPage` | `number` | `20` | At most how many links per page (top to bottom) |
+| `onVisit.concurrency` | `number` | same as classic | Parallel workers |
+| `onVisit.rps` | `number` | same as classic | Requests per second cap; `0` unlimited |
+
+```js
+prewarm: {
+  onVisit: { perPage: 20, rps: 4 },
+}
+```
+
+`hooks.prewarmPaths` and classic fields (`max`, `priority`, …) are **forbidden**
+with `onVisit`. 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).
 
@@ -946,7 +969,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 to prewarm; if it is not defined, prewarming is never set up | [06](./06-caching.md) |
+| `prewarmPaths` | `() => string[]` | Paths for classic prewarm; if omitted, the classic pass is never set up. **Forbidden** with `onVisit` | [06](./06-caching.md) |
 
 ```js
 hooks: {

package/package.json

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

package/src/config/defaults.js

@@ -50,7 +50,11 @@ export const DEFAULT_DEV_GATE_BYPASS = [
   "/favicon.ico",
 ];
 
-/** Prewarm ayarlarının kod içi varsayılanları. */
+/**
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
+ * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
+ * linkleri ısıtma.
+ */
 export const DEFAULT_PREWARM = {
   enabled: true,
   max: 400,
@@ -85,6 +89,41 @@ export const DEFAULT_PREWARM = {
   priority: [],
 };
 
+/**
+ * Ziyaret tabanlı ısıtma. Bir sayfa servis edilince HTML'deki aynı-origin
+ * linkler kuyruğa alınır; bir sonraki tıklama (veya başka ziyaretçi) çoğu
+ * zaman HIT görür. Klasik `prewarm` alanlarıyla karşılıklı dışlayıcıdır.
+ */
+export const DEFAULT_PREWARM_ON_VISIT = {
+  enabled: false,
+  /** Sayfa başına üstten alta en fazla kaç link kuyruğa alınır. */
+  perPage: 20,
+  /**
+   * Paralel işçi; `null` → klasik prewarm ile aynı varsayılan
+   * (prod 4 / dev 1) `startPrewarm` içinde çözülür.
+   * @type {number | null}
+   */
+  concurrency: null,
+  /**
+   * Saniyedeki istek tavanı; `null` → klasik ile aynı (prod 0 / dev 4).
+   * @type {number | null}
+   */
+  rps: null,
+};
+
+/** `onVisit` açıkken `cache().prewarm` kökünde yasak olan klasik alanlar. */
+export const CLASSIC_PREWARM_KEYS = [
+  "enabled",
+  "max",
+  "intervalSeconds",
+  "concurrency",
+  "delayMs",
+  "rps",
+  "retryDelayMs",
+  "rotate",
+  "priority",
+];
+
 /**
  * HTML önbelleğinin girdi sınırı. 500 girdi ortalama bir sayfa boyutunda
  * yaklaşık 100-200 MB tutar; uzun kuyruklu siteler bunu yükseltmek yerine

package/src/config/index.js

@@ -42,7 +42,9 @@ import {
   DEFAULT_NAVIGATION,
   DEFAULT_NAVIGATION_EXCLUDE,
   DEFAULT_PREWARM,
+  DEFAULT_PREWARM_ON_VISIT,
   DEFAULT_PREWARM_SKIP,
+  CLASSIC_PREWARM_KEYS,
   DEFAULT_REDIS,
   DEFAULT_SECURITY,
   DEFAULT_STATIC,
@@ -655,7 +657,7 @@ function normalizeCache(raw) {
     html.push({ pattern, seconds: value });
   }
 
-  const prewarm = { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) };
+  const prewarm = normalizePrewarm(raw?.prewarm);
   const queryRules = normalizeQueryRules(raw?.query);
   const maxEntries = Number(raw?.maxEntries);
 
@@ -688,6 +690,98 @@ function normalizeCache(raw) {
   };
 }
 
+/**
+ * @param {unknown} raw
+ * @returns {{ enabled: boolean } & typeof DEFAULT_PREWARM_ON_VISIT}
+ */
+function normalizeOnVisit(raw) {
+  if (raw === true) {
+    return { ...DEFAULT_PREWARM_ON_VISIT, enabled: true };
+  }
+
+  if (raw == null || raw === false) {
+    return { ...DEFAULT_PREWARM_ON_VISIT, enabled: false };
+  }
+
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      "[config] cache().prewarm.onVisit must be true, false, or an object",
+    );
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const perPage = Number(source.perPage);
+  const concurrency = Number(source.concurrency);
+  const rps = Number(source.rps);
+
+  return {
+    ...DEFAULT_PREWARM_ON_VISIT,
+    enabled: source.enabled !== false,
+    perPage:
+      Number.isFinite(perPage) && perPage > 0
+        ? Math.floor(perPage)
+        : DEFAULT_PREWARM_ON_VISIT.perPage,
+    concurrency:
+      Number.isFinite(concurrency) && concurrency > 0
+        ? Math.floor(concurrency)
+        : null,
+    rps: Number.isFinite(rps) && rps >= 0 ? rps : null,
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {unknown} raw
+ * @returns {Record<string, unknown>}
+ */
+function normalizePrewarm(raw) {
+  const source =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? /** @type {Record<string, unknown>} */ ({ ...raw })
+      : {};
+
+  const onVisit = normalizeOnVisit(source.onVisit);
+
+  if (onVisit.enabled) {
+    const conflicts = Object.keys(source).filter(
+      (key) => key !== "onVisit" && CLASSIC_PREWARM_KEYS.includes(key),
+    );
+    if (conflicts.length) {
+      throw new Error(
+        "[config] cache().prewarm.onVisit cannot be combined with classic " +
+          `prewarm settings (${conflicts.join(", ")}). Use either onVisit or ` +
+          "classic settings (max, priority, rotate, …), not both.",
+      );
+    }
+
+    const unknown = Object.keys(source).filter((key) => key !== "onVisit");
+    if (unknown.length) {
+      throw new Error(
+        "[config] cache().prewarm.onVisit cannot be combined with " +
+          `${unknown.join(", ")}. On-visit mode only accepts the onVisit object.`,
+      );
+    }
+
+    return {
+      ...DEFAULT_PREWARM,
+      enabled: true,
+      onVisit,
+    };
+  }
+
+  // Klasik mod: `onVisit: false` yazılmış olabilir; diğer alanlar varsayılanlarla
+  // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
+  const classic = { ...source };
+  delete classic.onVisit;
+  return {
+    ...DEFAULT_PREWARM,
+    ...classic,
+    onVisit,
+  };
+}
+
 /** Speculation Rules'un tanıdığı eagerness değerleri. */
 const EAGERNESS = new Set(["conservative", "moderate", "eager"]);
 
@@ -1043,6 +1137,17 @@ export async function loadConfig(options = {}) {
     clientEnv: source.clientEnv ?? [],
   };
 
+  if (
+    config.prewarm?.onVisit?.enabled &&
+    typeof config.hooks?.prewarmPaths === "function"
+  ) {
+    throw new Error(
+      "[config] hooks.prewarmPaths() cannot be used with cache().prewarm.onVisit. " +
+        "On-visit mode warms links from each response; 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/index.js

@@ -77,7 +77,7 @@ export {
 } from "./server/cloudflare.js";
 // Upstream hız freninin host başına durumu: healthcheck ve teşhis uçları için.
 export { getUpstreamLimiterStatus } from "./server/upstream-limiter.js";
-export { prewarm, prewarmProgress } from "./server/prewarm.js";
+export { prewarm, prewarmProgress, extractSameOriginLinks, isOnVisitPrewarm } from "./server/prewarm.js";
 export { createProxy } from "./server/middleware/upstream-proxy.js";
 export { getConfig, loadConfig } from "./config/index.js";
 export { attrs, cn, cx, esc, jsonScript } from "./views/helpers/html.js";

package/src/server/html-cache.js

@@ -815,3 +815,17 @@ export function getHtmlCacheEntries() {
     deps: entry.deps.size,
   }));
 }
+
+/**
+ * Yol (query'siz) için taze bir HTML girdisi var mı? Ziyaret ısıtması yalnızca
+ * soğuk / bayat hedefleri kuyruğa alır; HIT'leri yeniden çekmez.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isHtmlCacheFresh(pathname) {
+  if (typeof pathname !== "string" || !pathname.startsWith("/")) return false;
+  const entry = store.get(pathname);
+  if (!entry) return false;
+  return Date.now() < entry.expiresAt;
+}

package/src/server/image-optimizer.js

@@ -309,7 +309,8 @@ function sendCached(res, filePath, maxAge) {
     `public, max-age=${maxAge}, stale-while-revalidate=${Math.min(maxAge, 86400)}`,
   );
   res.setHeader("Vary", "Accept");
-  res.sendFile(path.resolve(filePath));
+  // Cache dir is under .jskelet/; Express send ignores dotfiles by default.
+  res.sendFile(path.resolve(filePath), { dotfiles: "allow" });
 }
 
 /**

package/src/server/prewarm.js

@@ -1,31 +1,43 @@
 /**
- * Sunucu açılışında sayfaları önden render edip HTML cache'ini doldurur.
+ * Sunucu açılışında veya ziyaret sırasında sayfaları önden render edip HTML
+ * cache'ini doldurur.
+ *
+ * İki karşılıklı dışlayan mod:
+ *
+ * 1. **Klasik** — `hooks.prewarmPaths()` listesi, açılış/`intervalSeconds`
+ *    turları, `priority` / `rotate` / `max`.
+ * 2. **onVisit** — herkese açık bir sayfa servis edilince HTML'deki
+ *    aynı-origin linkler kuyruğa alınır; tıklanabilir komşular ısınır.
  *
  * Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz:
  * HTML cache süreç belleğinde yaşadığı için ısıtma da süreç ayağa kalkınca
- * yapılır. Kazanç aynı — ilk ziyaretçi soğuk render'ı beklemez — fakat veri
- * dondurulmaz: her girdi route'un `revalidate` süresiyle yaşlanır ve
- * stale-while-revalidate ile arkada tazelenir.
+ * (veya trafik geldikçe) yapılır.
  *
  * Isıtma gerçek HTTP istekleriyle yapılır: cache anahtarı, sıkıştırma ve
- * middleware zinciri normal trafikle bire bir aynı olsun. Hangi yolların
- * ısıtılacağını uygulama `hooks.prewarmPaths()` ile bildirir; genelde
- * sitemap üreten fonksiyonun aynısıdır.
- *
- * On binlerce yolluk bir sitede tur bir "damla damla" tarayıcıya dönüşür:
- * `priority` desenleri her turda başa alınır, geri kalan kuyruk turlar
- * arasında kaldığı yerden devam eder (`rotate`) ve `rps` toplam hızı upstream
- * kotasının altında tutar. Amaç, kimse gelmese bile hiçbir sayfanın soğuk
- * kalmaması — ama bunu API'yi düşürmeden yapmak.
+ * middleware zinciri normal trafikle bire bir aynı olsun.
  */
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
 import { getRequestContext } from "../http/request-context.js";
-import { takeInvalidatedPaths } from "./html-cache.js";
+import { isHtmlCacheFresh, takeInvalidatedPaths } from "./html-cache.js";
 import { getDataCacheStats } from "./data-cache.js";
 import { isTransientStatus } from "./upstream-tracking.js";
 import { upstreamCooldownMs } from "./upstream-limiter.js";
 
+/** Klasik turu yöneten env'ler; `onVisit` ile birlikte yasak. */
+const CLASSIC_PREWARM_ENV = [
+  "PREWARM_MAX",
+  "PREWARM_INTERVAL_SECONDS",
+  "PREWARM_DELAY_MS",
+  "PREWARM_RETRY_DELAY_MS",
+];
+
+/**
+ * onVisit turu sürerken concurrency/rps. Klasik moda dokunmaz (`null`).
+ * @type {{ concurrency: number | null, rps: number | null }}
+ */
+const visitWarmSettings = { concurrency: null, rps: null };
+
 /**
  * Isıtmanın canlı durumu. Dev araçları bunu okuyup ilerlemeyi gösterir;
  * üretimde kimse okumazsa da maliyeti bir nesnedir.
@@ -127,6 +139,15 @@ function num(value, fallback) {
  * @returns {number}
  */
 function setting(envKey, configKey, fallback) {
+  if (
+    visitWarmSettings.concurrency != null &&
+    configKey === "concurrency"
+  ) {
+    return visitWarmSettings.concurrency;
+  }
+  if (visitWarmSettings.rps != null && configKey === "rps") {
+    return visitWarmSettings.rps;
+  }
   return num(process.env[envKey], num(getConfig().prewarm?.[configKey], fallback));
 }
 
@@ -421,13 +442,18 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
 
   // Dev'de tek işçi: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU
   // için yarışmasın.
-  const concurrency = setting("PREWARM_CONCURRENCY", "concurrency", isDev ? 1 : 4);
+  const concurrency = setting(
+    "PREWARM_CONCURRENCY",
+    "concurrency",
+    isDev ? 1 : 4,
+  );
 
   // Render tek bir olay döngüsünde çalışıyor: aralıksız bir tur, geliştirme
   // sırasında sayfa isteklerini ve dev panelinin kanalını arkasında bekletiyor.
   // Dev'de varsayılan bir hız freni bu yüzden var; üretimde ısıtma bir kez
   // olup bittiği için fren yalnızca istenirse (`prewarm.rps`) devreye girer.
-  const rps = num(process.env.PREWARM_RPS, num(getConfig().prewarm?.rps, isDev ? 4 : 0));
+  // onVisit turlarında `visitWarmSettings.rps` `setting()` üzerinden iner.
+  const rps = setting("PREWARM_RPS", "rps", isDev ? 4 : 0);
   const pace = createPacer(rps);
 
   const all = only?.length ? only : await collectPaths();
@@ -554,8 +580,213 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
 }
 
 /**
- * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır; isteğe
- * bağlı olarak periyodik tekrarlar. Hiçbir hata süreci düşürmez.
+ * Speculation Rules `href_matches` benzeri dışlama: tam yol veya `/*` öneki.
+ *
+ * @param {string} pathname
+ * @param {string[]} patterns
+ * @returns {boolean}
+ */
+function matchesHrefExclude(pathname, patterns) {
+  for (const pattern of patterns) {
+    if (typeof pattern !== "string" || !pattern) continue;
+    if (pattern.endsWith("/*")) {
+      const base = pattern.slice(0, -2);
+      if (pathname === base || pathname.startsWith(`${base}/`)) return true;
+      continue;
+    }
+    if (pathname === pattern) return true;
+  }
+  return false;
+}
+
+/**
+ * HTML içindeki aynı-origin `<a href>` yollarını DOM sırasıyla (üstten alta)
+ * toplar. Speculation Rules ile aynı muafiyetler: `nofollow`, `_blank`,
+ * `data-no-prefetch`, `prewarmSkip`, `navigation.exclude`.
+ *
+ * @param {string} html
+ * @param {{ limit?: number, basePath?: string }} [options]
+ * @returns {string[]}
+ */
+export function extractSameOriginLinks(html, options = {}) {
+  if (typeof html !== "string" || !html) return [];
+
+  const limit = Math.max(1, Math.floor(Number(options.limit) || 20));
+  const { prewarmSkip, navigation } = getConfig();
+  const exclude = navigation?.exclude ?? [];
+
+  /** @type {string[]} */
+  const links = [];
+  const seen = new Set();
+  const tagRe = /<a\b([^>]*)>/gi;
+  let match;
+
+  while ((match = tagRe.exec(html)) !== null && links.length < limit) {
+    const attrs = match[1];
+    if (/\btarget\s*=\s*(?:"_blank"|'_blank'|_blank)(?=[\s>]|$)/i.test(attrs)) {
+      continue;
+    }
+    if (/\bdata-no-prefetch\b/i.test(attrs)) continue;
+
+    const relMatch = attrs.match(
+      /\brel\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i,
+    );
+    const rel = relMatch?.[1] ?? relMatch?.[2] ?? relMatch?.[3] ?? "";
+    if (/\bnofollow\b/i.test(rel)) continue;
+
+    const hrefMatch = attrs.match(
+      /\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i,
+    );
+    const href = hrefMatch?.[1] ?? hrefMatch?.[2] ?? hrefMatch?.[3];
+    if (!href) continue;
+
+    const path = normalizeWarmPath(href, options.basePath);
+    if (!path) continue;
+    if (prewarmSkip.some((prefix) => path.startsWith(prefix))) continue;
+    if (matchesHrefExclude(path, exclude)) continue;
+    if (seen.has(path)) continue;
+
+    seen.add(path);
+    links.push(path);
+  }
+
+  return links;
+}
+
+/**
+ * @param {string} href
+ * @param {string} [basePath] Ziyaret edilen sayfa; göreli href çözümü için.
+ * @returns {string | null}
+ */
+function normalizeWarmPath(href, basePath = "/") {
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  if (/^(mailto|tel|javascript|data):/i.test(trimmed)) return null;
+
+  try {
+    const basePathname = basePath.startsWith("/") ? basePath : `/${basePath}`;
+    const url = new URL(trimmed, `https://warm.invalid${basePathname}`);
+    // Dış origin veya `https://…` mutlak linkler elenir; yalnızca site-içi
+    // path / göreli href ısınır.
+    if (url.origin !== "https://warm.invalid") return null;
+    return url.pathname || "/";
+  } catch {
+    return null;
+  }
+}
+
+/** @type {string | null} */
+let visitOrigin = null;
+/** @type {string[]} */
+const visitPending = [];
+/** @type {Set<string>} */
+const visitQueued = new Set();
+let visitDraining = false;
+
+/**
+ * Ziyaret ısıtması açık mı? `PREWARM=0` her iki modu da keser.
+ *
+ * @returns {boolean}
+ */
+export function isOnVisitPrewarm() {
+  if (process.env.PREWARM === "0") return false;
+  try {
+    return getConfig().prewarm?.onVisit?.enabled === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Yanıt gövdesindeki linkleri soğuksa kuyruğa alır. İstek yolunu bloklamamak
+ * için `route()` bunu `queueMicrotask` ile çağırır.
+ *
+ * @param {string} html
+ * @param {{ path: string, req?: { get?: (name: string) => string | undefined,
+ *   headers?: Record<string, unknown> } }} context
+ * @returns {void}
+ */
+export function noteVisitWarm(html, context) {
+  if (!isOnVisitPrewarm() || !visitOrigin) return;
+  if (!context?.path || typeof html !== "string") return;
+
+  const ua =
+    context.req?.get?.("user-agent") ??
+    /** @type {string | undefined} */ (context.req?.headers?.["user-agent"]);
+  if (ua && ua === getConfig().brand.prewarmUserAgent) return;
+
+  const perPage = Number(getConfig().prewarm?.onVisit?.perPage) || 20;
+  const links = extractSameOriginLinks(html, {
+    limit: perPage,
+    basePath: context.path,
+  });
+
+  for (const path of links) {
+    if (path === context.path) continue;
+    if (isHtmlCacheFresh(path)) continue;
+    if (visitQueued.has(path)) continue;
+    visitQueued.add(path);
+    visitPending.push(path);
+  }
+
+  enqueueInvalidatedForVisit();
+  if (visitPending.length) void drainVisitWarm();
+}
+
+/**
+ * Invalidate edilmiş yolları da kuyruğa alır (klasik turdaki
+ * `takeInvalidatedPaths` karşılığı).
+ *
+ * @returns {void}
+ */
+function enqueueInvalidatedForVisit() {
+  for (const path of takeInvalidatedPaths()) {
+    if (visitQueued.has(path)) continue;
+    visitQueued.add(path);
+    visitPending.push(path);
+  }
+}
+
+async function drainVisitWarm() {
+  if (visitDraining || !visitOrigin) return;
+  visitDraining = true;
+
+  const onVisit = getConfig().prewarm?.onVisit ?? {};
+
+  try {
+    while (visitPending.length) {
+      enqueueInvalidatedForVisit();
+
+      const batch = visitPending.splice(0, 32);
+      for (const path of batch) visitQueued.delete(path);
+
+      const cold = batch.filter((path) => !isHtmlCacheFresh(path));
+      if (!cold.length) continue;
+
+      // Klasik `prewarm()` turunu yeniden kullan: retry, progress, UA aynı.
+      // onVisit.concurrency / rps verilmişse `visitWarmSettings` ile iner;
+      // yoksa `prewarm()` kendi (env → config → isDev) zincirine düşer.
+      visitWarmSettings.concurrency = onVisit.concurrency;
+      visitWarmSettings.rps = onVisit.rps;
+
+      try {
+        await prewarm({ origin: visitOrigin, paths: cold, quiet: true });
+      } catch (error) {
+        console.error("[prewarm] onVisit warm failed", error);
+      } finally {
+        visitWarmSettings.concurrency = null;
+        visitWarmSettings.rps = null;
+      }
+    }
+  } finally {
+    visitDraining = false;
+    if (visitPending.length) void drainVisitWarm();
+  }
+}
+
+/**
+ * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
+ * `onVisit` modunda zamanlayıcı yok: yalnızca origin kaydı ve kuyruk.
  *
  * @param {{ port: number }} options
  * @returns {void}
@@ -563,12 +794,30 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
 export function startPrewarm({ port }) {
   const config = getConfig();
   if (process.env.PREWARM === "0") return;
+
+  const origin = `http://127.0.0.1:${port}`;
+
+  if (config.prewarm?.onVisit?.enabled) {
+    const classicEnv = CLASSIC_PREWARM_ENV.filter((key) => process.env[key]);
+    if (classicEnv.length) {
+      throw new Error(
+        "[prewarm] onVisit mode cannot be used with " +
+          `${classicEnv.join(", ")}. Those env vars belong to classic prewarm.`,
+      );
+    }
+
+    visitOrigin = origin;
+    console.log(
+      `[prewarm] onVisit mode — warming links from each public page response`,
+    );
+    return;
+  }
+
   if (process.env.PREWARM !== "1" && config.prewarm?.enabled === false) return;
   // Isıtacak yol bildirmeyen bir projede zamanlayıcı kurmanın anlamı yok.
   if (typeof config.hooks?.prewarmPaths !== "function") return;
 
   const isDev = process.env.NODE_ENV === "development";
-  const origin = `http://127.0.0.1:${port}`;
 
   // Hız frenli bir tur `intervalSeconds`'tan uzun sürebilir; üst üste binen
   // turlar `prewarmProgress`'i bozar ve upstream'e iki kat yük bindirir.

package/src/server/render.js

@@ -41,7 +41,7 @@ import * as html from "../views/helpers/html.js";
 import * as tags from "../views/helpers/tags.js";
 import { loadComponents } from "../views/components/loader.js";
 import { renderStatusPage } from "./status-page.js";
-import { suppressForPrewarm } from "./prewarm.js";
+import { suppressForPrewarm, noteVisitWarm } from "./prewarm.js";
 import {
   ensureTemplatesCompiled,
   getComponentDirs,
@@ -395,6 +395,17 @@ export function route(controller, options = {}) {
       // ETag kişiye özel HTML için kullanıcıya özgü bir doğrulayıcıdır ve
       // `no-store` ile birlikte hiçbir işe yaramaz; üretilmesi engellenir.
       await sendHtml(req, res, result.html, result.encoded, { etag: publicCache });
+
+      // onVisit: yanıt gittikten sonra linkleri kuyruğa al — TTFB'yi şişirmez.
+      // Yalnızca herkese açık, önbelleklenebilir 200 HTML; private / degraded
+      // sayfadaki linkler kişiye özel veya eksik olabilir.
+      if (publicCache && result.status === 200 && result.html) {
+        const pagePath = req.path;
+        const pageHtml = result.html;
+        queueMicrotask(() => {
+          noteVisitWarm(pageHtml, { path: pagePath, req });
+        });
+      }
     } catch (error) {
       if (isRedirectError(error)) {
         // Oturuma bağlı bir yönlendirme de kişiye özeldir: "giriş yapmalısın"