jskelet 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -10,6 +10,16 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Dev overlay Errors tab now lists failed SSR and browser `fetch` calls with
+  page path, API URL, optional island name, and expandable response-body
+  details (JSON instead of `[object Object]`). Server `console.error` /
+  `console.warn` records also carry the current page when they fire during
+  render.
+- 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

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/09-dev-araclari.md

@@ -177,9 +177,13 @@ Tüm arayüz shadow DOM içinde durur, sayfanın CSS'i ile karışmaz.
 Gösterdikleri:
 
 - **Hatalar:** tarayıcı tarafındaki JS hataları, kaynak yükleme hataları
-  (`img`/`script`/`link`), ve sunucudaki `console.error` / `console.warn`
-  çıktıları. Sunucu tarafında `console` sarılır, böylece uyarılar terminalde
-  kaybolmaz.
+  (`img`/`script`/`link`), sunucudaki `console.error` / `console.warn`
+  çıktıları, ve SSR / tarayıcı `fetch` çağrılarının 4xx/5xx ya da ağ
+  başarısızlıkları. Her kayıt mümkün olduğunca **sayfa yolu**, **API URL** ve
+  (istemcide) **island adı** taşır; yanıt gövdesi **show details** ile açılır —
+  `[object Object]` yerine JSON. Sunucu tarafında `console` sarılır, böylece
+  uyarılar terminalde kaybolmaz; upstream hataları uygulamanın kendi logger'ı
+  stderr'e yazsa bile overlay'e düşer.
 - **SEO:** açık sayfanın istemci tarafı taraması — title ve meta description
   uzunluğu, `html lang`, viewport, canonical, robots/`noindex`, Open Graph ve
   Twitter etiketleri, H1/outline, görsel `alt`, boş linkler ve JSON-LD parse
@@ -244,9 +248,11 @@ http://localhost:3000/__jskelet/dev/report
   gezilmemiş ama ısıtılmış sayfalar da listelenir: SSR tarafı bilinir, istemci
   ölçümleri boş kalır.
 - **Sunucu API çağrıları:** SSR sırasında yapılan dış `fetch` çağrıları — URL,
-  host, metot, durum, süre, bayt. `globalThis.fetch` yalnızca development'ta
+  host, metot, durum, süre, bayt, hangi sayfa render edilirken yapıldığı ve
+  başarısız cevaplarda gövde özeti. `globalThis.fetch` yalnızca development'ta
   sarılır; üretim yolu dokunulmaz kalır. Kendi sunucumuza yapılan istekler
-  (ısıtma, sağlık kontrolü) API sayılmaz.
+  (ısıtma, sağlık kontrolü) API sayılmaz. Başarısız çağrılar overlay Errors
+  sekmesine de düşer.
 - **Build çıktısı:** manifest'teki her varlığın ham/gzip/brotli boyutu, ve
   esbuild metafile'ından chunk analizi — her çıktının boyutu, hangi kaynaklardan
   oluştuğu, hangi chunk'ları import ettiği. Kaynaklar okunur gruplara indirgenir

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/docs/en/09-dev-tools.md

@@ -181,9 +181,13 @@ the page's CSS.
 What it shows:
 
 - **Errors:** browser-side JS errors, resource loading errors
-  (`img`/`script`/`link`), and the server's `console.error` / `console.warn`
-  output. On the server side `console` is wrapped so warnings do not get lost in
-  the terminal.
+  (`img`/`script`/`link`), the server's `console.error` / `console.warn`
+  output, and failed SSR / browser `fetch` calls (4xx/5xx or network). Each
+  record carries a **page path**, **API URL**, and (on the client) an **island
+  name** when known; the response body opens under **show details** as JSON
+  instead of `[object Object]`. On the server side `console` is wrapped so
+  warnings do not get lost in the terminal; upstream failures still land in the
+  overlay even when the app's own logger writes them only to stderr.
 - **SEO:** a client-side scan of the current page — title and meta description
   length, `html lang`, viewport, canonical, robots/`noindex`, Open Graph and
   Twitter tags, H1/outline, image `alt`, empty links, and JSON-LD parse errors.
@@ -248,9 +252,10 @@ Its contents:
   status of the SSR output. Pages that were never visited but were warmed are
   listed too: the SSR side is known, the client measurements stay empty.
 - **Server API calls:** outbound `fetch` calls made during SSR — URL, host,
-  method, status, duration, bytes. `globalThis.fetch` is only wrapped in
-  development; the production path is left untouched. Requests to our own server
-  (warming, health check) do not count as API calls.
+  method, status, duration, bytes, which page was rendering, and a body summary
+  on failures. `globalThis.fetch` is only wrapped in development; the production
+  path is left untouched. Requests to our own server (warming, health check) do
+  not count as API calls. Failures also appear on the overlay Errors tab.
 - **Build output:** the raw/gzip/brotli size of every asset in the manifest, and
   chunk analysis from esbuild's metafile — the size of each output, which
   sources it is made of, which chunks it imports. Sources are reduced to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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",