jskelet 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -10,6 +10,24 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Targeted HTML invalidation: `invalidateHtmlCache(target, { hard })` takes a
+  path, the config pattern syntax (`/news/:slug`), a regular expression or a list
+  of them, and returns how many entries were affected. By default it **stales**
+  the entries rather than deleting them, so a webhook that touches hundreds of
+  pages does not turn into hundreds of cold renders at the worst possible moment:
+  visitors keep getting the old HTML while the refresh runs in the background,
+  once per key. Matching is done against the path, so every query variant of a
+  page is covered by one call, and a render already in flight when the purge
+  arrives is not stored.
+- `clearDataCache()` now refreshes the HTML too. The `withDataCache` keys read
+  during a render are recorded, so dropping `news:abc` stales every page that
+  actually read it — the article, the home page listing it and the tag page —
+  without the application declaring any tags. Turn it off with
+  `cache().trackDependencies: false`; `getHtmlCacheEntries()` reports the
+  dependency count per page as `deps`.
+- Invalidated paths go to the front of the next prewarm pass, so an updated page
+  is refreshed without waiting for a visitor, while still respecting the `rps`
+  limit. The pass summary counts them separately.
 - An upstream data cache: `withDataCache(key, ttlSeconds, producer)` and the
   `dataCache(fn, { key, revalidate })` wrapper, with `clearDataCache(prefix?)`,
   `getDataCacheSize()` and `getDataCacheEntries()` alongside them. It keeps JSON
@@ -47,6 +65,17 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
+- The dev tools panel is now fed over a WebSocket (`<devBasePath>/ws`) instead of
+  polling `/stats` every two seconds. The server pushes statistics as they change
+  and sends live reload and CSS hot-swap events over the same connection, so an
+  open tab no longer keeps hitting the server while the panel is closed. No new
+  dependency is involved; if the socket cannot be opened, the panel falls back to
+  the previous SSE plus polling path.
+- Prewarming no longer holds up the rest of the dev server. In development it now
+  runs with a single worker and a default limit of 4 requests per second
+  (`prewarm.rps` / `PREWARM_RPS` still override it), so page requests and the dev
+  panel stay responsive while a warm-up round is going on. Production behaviour
+  is unchanged.
 - `notFound()` is no longer served as a 404 when a transient upstream failure
   (`429`, `5xx`, network error) happened during the same render. The page is
   retried first and, if upstream is still failing, responds with an uncached

package/docs/06-cache.md

@@ -306,8 +306,9 @@ Yönetim yüzeyi:
 | `getDataCacheEntries()` | Döküm: `{ key, stale, expiresIn }`. Değerin kendisi dönmez. |
 
 `clearDataCache("haber:")`, "bu içerik güncellendi" webhook'unun karşılığıdır:
-tek bir bölümün verisini düşürüp HTML'in bir sonraki tazelemesinde yeni içeriği
-almasını sağlar.
+tek bir bölümün verisini düşürür ve **o veriyi okumuş HTML sayfalarını da**
+bayatlatır, yani güncelleme TTL beklenmeden görünür. Ayrıntısı aşağıda,
+"Otomatik bağımlılık" bölümünde.
 
 ## Degraded render: `reportUpstreamFailure`
 
@@ -437,9 +438,70 @@ düşer.
 | Fonksiyon | Ne yapar |
 | --- | --- |
 | `withHtmlCache(key, ttlSeconds, producer)` | Önbelleği doğrudan kullanmak için. `ttlSeconds` 0 ise producer her zaman çalışır. |
+| `invalidateHtmlCache(target, options?)` | Eşleşen sayfaları bayatlatır (ya da `{ hard: true }` ile düşürür), etkilenen sayı döner. |
 | `clearHtmlCache()` | Store'u tamamen boşaltır. |
 | `getHtmlCacheSize()` | Girdi sayısı. |
-| `getHtmlCacheEntries()` | Döküm: `{ key, bytes, status, stale, expiresIn, encodings }`. HTML gövdesi dönmez, yalnızca boyutu. |
+| `getHtmlCacheEntries()` | Döküm: `{ key, bytes, status, stale, expiresIn, encodings, deps }`. HTML gövdesi dönmez, yalnızca boyutu. |
+
+### Hedefli invalidation
+
+TTL'i beklemekle tüm önbelleği boşaltmak arasındaki boşluğu `invalidateHtmlCache()`
+doldurur:
+
+```js
+import { invalidateHtmlCache } from "jskelet";
+
+invalidateHtmlCache("/haber/abc");            // o yol ve altı
+invalidateHtmlCache("/haber/:slug");          // desen sözdizimi
+invalidateHtmlCache([/-yorumlar$/, "/"]);     // RegExp ve liste
+```
+
+Varsayılan davranış **bayatlatmaktır**, silmek değil: girdi süresi geçmiş
+sayılır ve normal stale-while-revalidate yoluna düşer. Bir webhook beş yüz
+sayfayı birden düşürdüğünde sert silme, tam da içeriğin güncellendiği anda beş
+yüz soğuk render başlatır ve upstream'i döver. Bayatlatmada ziyaretçi eski
+HTML'i beklemeden alır, tazeleme arkada ve anahtar başına tek seferde koşar.
+Eski HTML'in gerçekten geçersiz olduğu durumlar için `{ hard: true }`.
+
+Anahtar `yol?query` olduğundan eşleştirme **yol kısmına** yapılır: bir yolun
+bütün query varyantları (`?utm_source=…` dahil) tek çağrıyla düşer. Düz
+string'te önek segment sınırında kesilir — `/haber` kuralı `/haberler`i
+etkilemez.
+
+Uçuşta olan bir render de hedeflenir: purge'den önce başlamış bir tur, sonucu
+artık eski veriyi taşıdığı için önbelleğe **yazılmaz** ve bir sonraki istek yeni
+bir tur başlatır.
+
+### Otomatik bağımlılık: `clearDataCache` HTML'i de tazeler
+
+Hangi sayfanın hangi içerikten etkilendiğini bildirmek gerekmez. Render
+sırasında okunan her `withDataCache` anahtarı kaydedilir; `clearDataCache()` bir
+anahtarı düşürdüğünde onu **fiilen okumuş** bütün HTML girdileri bayatlar.
+
+```js
+// "bu haber güncellendi" webhook'u
+clearDataCache(`haber:${slug}`);
+```
+
+Bu tek satır haber detayını, o haberi listeleyen ana sayfayı ve etiket
+sayfasını birlikte tazeler — çünkü üçü de o anahtarı okumuştu. Elle tag'lemede
+en sık yapılan hata (detayı işaretleyip listeyi unutmak) burada yapısal olarak
+mümkün değil: bildirim değil, gözlem var.
+
+Ayrıntılar:
+
+- Bağımlılık **her tazelemede yeniden** toplanır; sayfanın okuduğu anahtarlar
+  zamanla değişebilir.
+- Render sürerken gelen bir purge de yakalanır: o turun çıktısı "doğduğu anda
+  bayat" olacağı için önbelleğe yazılmaz.
+- Sayfa başına bağımlılık sayısı `getHtmlCacheEntries()` dökümünde `deps`
+  alanında görünür. Bir invalidation beklediğiniz sayfayı tazelemiyorsa önce
+  buraya bakın: sayfa o veriyi `withDataCache` üzerinden okumuyor olabilir.
+- `withDataCache` kullanmayan bir uygulamada kaydedilecek bir şey yoktur;
+  `cache().trackDependencies: false` ile izleme tamamen kapatılabilir.
+- Bayatlatılan yollar ısıtma kuyruğunun **başına** alınır. `prewarm` kuruluysa
+  sayfa, ziyaretçi gelmesini beklemeden tazelenir ve tur özeti bunu ayırt eder:
+  `[prewarm] warmed 12/12 pages, 3 invalidated (0.4s)`.
 
 Bir yönetim ucu yazmak için:
 
@@ -514,10 +576,13 @@ Kurallar:
 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
    doldurulur.
-2. `concurrency` işçi paralel olarak istek atar (prod'da 4, dev'de 2). Dev'de
-   daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU
-   için yarışmasın.
+2. `concurrency` işçi paralel olarak istek atar (prod'da 4, dev'de 1). Dev'de
+   tek işçi: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU için
+   yarışmasın.
 3. `rps` verilmişse tur bu hızın üstüne çıkmaz — paralellik ne olursa olsun.
+   Dev'de varsayılan olarak saniyede 4 istek uygulanır: render tek bir olay
+   döngüsünde çalıştığı için aralıksız bir tur, sayfa isteklerini ve dev
+   panelinin canlı kanalını arkasında bekletiyor.
 4. Başarısız yollar için, `retryDelayMs` bekledikten sonra **tek seri tekrar
    turu** yapılır (`concurrency: 1`). Bekleme bilinçli: rate limit pencereleri
    saniye mertebesinde, hemen tekrar denemek aynı 429'u almak demek.
@@ -607,8 +672,8 @@ tek seferlik deneyler config'i düzenlemeden yapılabilsin.
 | --- | --- | --- | --- |
 | Açık/kapalı | `PREWARM=0` kapatır, `PREWARM=1` config'i ezip açar | `enabled` | `true` |
 | Tur başına en fazla yol | `PREWARM_MAX` | `max` | `400` |
-| Paralellik | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
-| Saniyedeki istek | `PREWARM_RPS` | `rps` | `0` (sınırsız) |
+| Paralellik | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 1 |
+| Saniyedeki istek | `PREWARM_RPS` | `rps` | prod `0` (sınırsız), dev 4 |
 | Başlangıç gecikmesi (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
 | Tekrar turu gecikmesi (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Periyot (saniye) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (kapalı) |

package/docs/07-yapilandirma.md

@@ -560,9 +560,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -607,6 +607,16 @@ Açıkken `globalThis.fetch` sarılır ve render sırasındaki geçici upstream
 hataları (`429`, `5xx`, ağ) kendiliğinden bildirilir; `reportUpstreamFailure()`
 çağırmak gerekmez. `fetch`i kendisi saran bir uygulama bunu kapatabilir.
 
+### `cache().trackDependencies`
+
+**Tip:** `boolean` — **Varsayılan:** `true`
+
+Açıkken bir render'ın okuduğu `withDataCache` anahtarları kaydedilir ve
+`clearDataCache()` o veriyi okumuş HTML sayfalarını da bayatlatır — hedefli
+invalidation için uygulamanın hiçbir şey bildirmesi gerekmez
+([06-cache.md](./06-cache.md)). `withDataCache` kullanmayan bir uygulamada
+kaydedilecek bir şey yok; kapatmak bağlam kurma maliyetini de kaldırır.
+
 ### `cache().transientRetry`
 
 **Tip:** `{ attempts?: number, delayMs?: number } | false` —
@@ -623,8 +633,8 @@ Ayrıntı: [06-cache.md](./06-cache.md).
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
 | `max` | `number` | `400` | Bir turda en fazla kaç yol ısıtılır |
-| `concurrency` | `number` | prod 4, dev 2 | Paralel işçi sayısı |
-| `rps` | `number` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. |
+| `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. |
 | `delayMs` | `number` | prod 500, dev 3000 | Açılıştan sonra ilk turun gecikmesi |
 | `retryDelayMs` | `number` | `2000` | Tekrar turundan önce beklenen süre |
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
@@ -742,7 +752,7 @@ basılmaz.
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
-| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 2 | Paralel işçi sayısı |
+| `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 |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | İlk turun gecikmesi |
 | `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | Tekrar turundan önceki bekleme |

package/docs/09-dev-araclari.md

@@ -111,9 +111,9 @@ Restart satırı değişen dosyayı ya da sayısını gösterir:
 
 ## CSS hot-swap ve tam yenileme
 
-Dev sunucusu `.jskelet/manifest.json` dosyasını izler ve bir SSE kanalı
-(`<devBasePath>/events`) üzerinden tarayıcıya olay yayınlar. Manifest her build
-turunda yeniden yazıldığı için değişiklik tespiti manifest üzerinden yapılır.
+Dev sunucusu `.jskelet/manifest.json` dosyasını izler ve olayları canlı kanal
+(`<devBasePath>/ws`) üzerinden tarayıcıya yayınlar. Manifest her build turunda
+yeniden yazıldığı için değişiklik tespiti manifest üzerinden yapılır.
 
 | Değişen | Davranış |
 | --- | --- |
@@ -131,6 +131,29 @@ Sunucu yeniden başladığında overlay bunu **boot kimliğinden** anlar: her s
 kendine özgü bir `boot` değeri yayınlar, overlay değişikliği görüp "restarted"
 bilgisini gösterir ve kendi durumunu sıfırlamaz.
 
+## Canlı kanal
+
+Overlay'e giden her şey — istatistikler, live reload ve CSS hot-swap olayları —
+tek bir WebSocket üzerinden gelir (`<devBasePath>/ws`). Panel eskiden
+istatistikleri iki saniyede bir çekiyordu; açık her sekme, panel kapalıyken bile
+sunucuya sürekli istek atıyordu. Artık sunucu değişiklik oldukça iter: bir istek
+ya da hata kaydedildiğinde (120 ms birleştirilerek), ısıtma sürerken saniyede
+ve zamana bağlı alanlar (uptime, bellek, ısıtma sayacı) tazelensin diye iki
+saniyede bir. Kalp atışı bilinçli olarak ısıtmadan bağımsız: kanalın temposu bir
+arka plan işine göre değişirse panel de o işin ritmine bağlanmış olur. Bağlı
+panel yoksa hiçbir şey hesaplanmaz.
+
+El sıkışma HTTP `upgrade` olayında geçtiği ve o olay middleware zincirine hiç
+uğramadığı için kanal `listen` sonrası doğrudan sunucuya bağlanır
+(`attachDevSocket`). Sunucu tarafı `ws` gibi bir bağımlılık kullanmaz: yalnızca
+sunucu→istemci metin çerçevesi yazmak ve istemcinin ping/close çerçevelerini
+yanıtlamak gerekiyor.
+
+Soket hiç açılamazsa (araya giren bir proxy WebSocket'i geçirmiyor olabilir)
+overlay eski yola düşer: `/events` SSE akışı + `/stats` yoklaması. Soket kurulup
+sonra düşerse — yani sunucu yeniden başlıyorsa — yarım saniyede bir yeniden
+bağlanır ve gösterge bu sırada "bağlantı yok" der.
+
 ## Devtools overlay
 
 Sağ altta yüzen bir baloncuk; `Alt+D` ile açılır, `Esc` ya da karartma alanına
@@ -236,8 +259,9 @@ Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç gi
 | --- | --- | --- |
 | `/overlay.js` | GET | Overlay script'i |
 | `/logo.png` | GET | Overlay logosu |
-| `/events` | GET | SSE: live reload ve CSS hot-swap olayları |
-| `/stats` | GET | Anlık istatistikler (overlay 2 saniyede bir çeker) |
+| `/ws` | GET (upgrade) | Canlı kanal: istatistikler, live reload ve CSS hot-swap olayları |
+| `/events` | GET | SSE: yalnızca WebSocket kurulamazsa kullanılan yedek olay akışı |
+| `/stats` | GET | Anlık istatistikler; aynı yedek yolun veri ucu |
 | `/report` | GET | Rapor sayfası (HTML) |
 | `/report.js` | GET | Rapor sayfasının script'i |
 | `/report/data` | GET | Raporun tek veri kaynağı (JSON) |
@@ -294,7 +318,8 @@ yayına açılmamış bir ortam yönlendirme kurallarını bile dışarıya sız
 | Bozuk route modülü | Uyarı + atla | Fırlat |
 | Devtools ve rapor | Mount edilir | Hiç yüklenmez |
 | `globalThis.fetch` | Sarılır (ölçüm) | Dokunulmaz |
-| Prewarm paralelliği | 2 | 4 |
+| Prewarm paralelliği | 1 | 4 |
+| Prewarm hız freni | saniyede 4 istek | Sınırsız |
 | Prewarm gecikmesi | 3000 ms | 500 ms |
 | Eksik ikon uyarısı | Verilir | Verilmez |
 | Precompress | Watch'ta çalışmaz | Çalışır |

package/docs/11-tasima.md

@@ -52,7 +52,8 @@ alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()
 | `fetch(..., { next: { revalidate } })` | — | Önbellek sayfa düzeyinde |
 | `unstable_cache` | — | İstek üstü veri önbelleği yok; sayfa önbelleği var |
 | React `cache()` | `cache()` | Aynı davranış: istek içi memoizasyon |
-| `revalidatePath()` | `clearHtmlCache()` | Şu anda tek tek anahtar geçersizleme yok |
+| `revalidatePath()` | `invalidateHtmlCache("/haber/:slug")` | Yol, desen ya da RegExp; varsayılan olarak siler değil bayatlatır |
+| `revalidateTag()` | `clearDataCache("haber:")` | Tag bildirmeye gerek yok: bağımlılık render sırasında gözlenir ([06](./06-cache.md)) |
 | `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Express nesnesine doğrudan erişim |
 | `dynamic = "force-dynamic"` | `revalidate` vermemek | Önbellek kapalı demek |
 
@@ -94,8 +95,6 @@ Bunları taşıma planında baştan hesaba katın:
   önce belgeyi hazırlar, `viewTransition` geçişi yumuşatır
   ([07](./07-yapilandirma.md)).
 - **Server Actions.** Form gönderimleri normal `app.post(...)` handler'larıdır.
-- **Tek tek yol geçersizleme (`revalidatePath`).** Şimdilik tüm önbelleği
-  temizlemek (`clearHtmlCache()`) ya da TTL'in dolmasını beklemek var.
 - **Otomatik görsel optimizasyonu (istek anında).** Optimizasyon build zamanında
   yapılır ve yalnızca `public/` altındaki yerel görselleri kapsar; uzak görseller
   olduğu gibi basılır.

package/docs/en/06-caching.md

@@ -315,8 +315,9 @@ The management surface:
 | `getDataCacheEntries()` | A dump: `{ key, stale, expiresIn }`. The value itself is not returned. |
 
 `clearDataCache("news:")` is the counterpart of a "this content was updated"
-webhook: it drops one section's data so the next HTML refresh picks up the new
-content.
+webhook: it drops one section's data **and stales the HTML pages that read it**,
+so the update shows up without waiting for a TTL. See "Automatic dependencies"
+below.
 
 ## Degraded render: `reportUpstreamFailure`
 
@@ -447,9 +448,71 @@ through to the 503.
 | Function | What it does |
 | --- | --- |
 | `withHtmlCache(key, ttlSeconds, producer)` | For using the cache directly. If `ttlSeconds` is 0 the producer always runs. |
+| `invalidateHtmlCache(target, options?)` | Stales the matching pages (or drops them with `{ hard: true }`) and returns how many were affected. |
 | `clearHtmlCache()` | Empties the store completely. |
 | `getHtmlCacheSize()` | The number of entries. |
-| `getHtmlCacheEntries()` | A dump: `{ key, bytes, status, stale, expiresIn, encodings }`. The HTML body is not returned, only its size. |
+| `getHtmlCacheEntries()` | A dump: `{ key, bytes, status, stale, expiresIn, encodings, deps }`. The HTML body is not returned, only its size. |
+
+### Targeted invalidation
+
+`invalidateHtmlCache()` fills the gap between waiting for the TTL and flushing
+the whole cache:
+
+```js
+import { invalidateHtmlCache } from "jskelet";
+
+invalidateHtmlCache("/news/abc");             // that path and everything under it
+invalidateHtmlCache("/news/:slug");           // the pattern syntax
+invalidateHtmlCache([/-comments$/, "/"]);     // regexps and lists
+```
+
+The default is to **stale** the entry, not to delete it: it is treated as
+expired and falls through the normal stale-while-revalidate path. When a webhook
+takes down five hundred pages at once, a hard delete starts five hundred cold
+renders at exactly the moment the content changed, and hammers the upstream.
+Staling instead hands the visitor the old HTML without a wait, and the refresh
+runs in the background, once per key. Use `{ hard: true }` when the old HTML is
+genuinely invalid.
+
+Since the key is `path?query`, matching is done against the **path**: every
+query variant of a path (including `?utm_source=…`) is covered by one call. For
+a plain string the prefix stops at a segment boundary — a `/news` rule does not
+touch `/newsletter`.
+
+An in-flight render is targeted too: a pass that started before the purge is
+carrying data that is now out of date, so it is **not** stored and the next
+request starts a fresh pass.
+
+### Automatic dependencies: `clearDataCache` refreshes the HTML too
+
+You do not have to declare which page is affected by which content. Every
+`withDataCache` key read during a render is recorded, and when `clearDataCache()`
+drops a key, every HTML entry that **actually read it** is staled.
+
+```js
+// the "this article changed" webhook
+clearDataCache(`news:${slug}`);
+```
+
+That single line refreshes the article page, the home page that lists it and the
+tag page together — because all three read that key. The most common mistake in
+manual tagging (marking the detail page and forgetting the listing) is
+structurally impossible here: nothing is declared, everything is observed.
+
+Details:
+
+- Dependencies are collected **on every refresh**, since the keys a page reads
+  can change over time.
+- A purge that lands while a render is in flight is caught as well: that pass
+  would be stale the moment it was born, so it is not stored.
+- The dependency count per page shows up as `deps` in the `getHtmlCacheEntries()`
+  dump. If an invalidation is not refreshing the page you expected, look there
+  first: the page may not be reading that data through `withDataCache`.
+- An application that does not use `withDataCache` has nothing to record;
+  tracking can be turned off entirely with `cache().trackDependencies: false`.
+- Staled paths go to the **front** of the prewarm queue. If `prewarm` is set up
+  the page is refreshed without waiting for a visitor, and the pass summary says
+  so: `[prewarm] warmed 12/12 pages, 3 invalidated (0.4s)`.
 
 To write an admin endpoint:
 
@@ -528,11 +591,13 @@ Rules:
 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.
-2. `concurrency` workers send requests in parallel (4 in prod, 2 in dev). Less
-   parallelism in dev: so the scan does not compete for CPU with the render of
+2. `concurrency` workers send requests in parallel (4 in prod, 1 in dev). A
+   single worker in dev: so the scan does not compete for CPU with the render of
    the page you currently have open in the browser.
 3. If `rps` is given, the round never goes above that rate — no matter the
-   parallelism.
+   parallelism. In dev, 4 requests per second apply by default: rendering runs
+   on a single event loop, so an unpaced round leaves page requests and the dev
+   panel's live channel waiting behind it.
 4. **A single serial retry round** is performed for the failed paths after
    waiting `retryDelayMs` (`concurrency: 1`). The wait is deliberate: rate limit
    windows are on the order of seconds, so retrying immediately just earns the
@@ -623,8 +688,8 @@ comes first so that one-off experiments can be done without editing the config.
 | --- | --- | --- | --- |
 | On/off | `PREWARM=0` disables it, `PREWARM=1` overrides the config and enables it | `enabled` | `true` |
 | Maximum paths per round | `PREWARM_MAX` | `max` | `400` |
-| Parallelism | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
-| Requests per second | `PREWARM_RPS` | `rps` | `0` (unlimited) |
+| Parallelism | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 1 |
+| Requests per second | `PREWARM_RPS` | `rps` | prod `0` (unlimited), dev 4 |
 | Startup delay (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
 | Retry round delay (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Period (seconds) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (off) |

package/docs/en/07-configuration.md

@@ -572,9 +572,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -622,6 +622,17 @@ When on, `globalThis.fetch` is wrapped and transient upstream failures (`429`,
 `reportUpstreamFailure()` is not required. An application that wraps `fetch`
 itself can turn this off.
 
+### `cache().trackDependencies`
+
+**Type:** `boolean` — **Default:** `true`
+
+When on, the `withDataCache` keys a render reads are recorded, and
+`clearDataCache()` also stales the HTML pages that read that data — targeted
+invalidation without the application declaring anything
+([06-caching.md](./06-caching.md)). An application that does not use
+`withDataCache` has nothing to record; turning this off also removes the cost of
+setting up the context.
+
 ### `cache().transientRetry`
 
 **Type:** `{ attempts?: number, delayMs?: number } | false` —
@@ -638,8 +649,8 @@ a 404; if the retries are exhausted the response is an uncached 503. `false` or
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
 | `max` | `number` | `400` | At most how many paths are prewarmed per pass |
-| `concurrency` | `number` | prod 4, dev 2 | Number of parallel workers |
-| `rps` | `number` | `0` | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. |
+| `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. |
 | `delayMs` | `number` | prod 500, dev 3000 | Delay of the first pass after startup |
 | `retryDelayMs` | `number` | `2000` | How long to wait before the retry pass |
 | `intervalSeconds` | `number` | `0` | If greater than 0, the pass repeats periodically |
@@ -758,7 +769,7 @@ and no warning is printed.
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
 | `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |
 | `PREWARM_MAX` | `prewarm` | `400` | At most how many paths are prewarmed |
-| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 2 | Number of parallel workers |
+| `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 |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | Delay of the first pass |
 | `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | The wait before the retry pass |

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

@@ -116,7 +116,7 @@ If `JSKELET_VERBOSE=1` is set, all files are listed when more than one changed.
 ## CSS hot-swap and full reload
 
 The dev server watches `.jskelet/manifest.json` and broadcasts events to the
-browser over an SSE channel (`<devBasePath>/events`). Since the manifest is
+browser over the live channel (`<devBasePath>/ws`). Since the manifest is
 rewritten on every build round, change detection is done through the manifest.
 
 | What changed | Behavior |
@@ -134,6 +134,30 @@ When the server restarts, the overlay figures it out from the **boot id**: every
 process broadcasts a unique `boot` value, the overlay sees the change, shows the
 "restarted" note and does not reset its own state.
 
+## The live channel
+
+Everything the overlay shows — statistics, live reload and CSS hot-swap events —
+arrives over a single WebSocket (`<devBasePath>/ws`). The panel used to poll for
+statistics every two seconds, so every open tab kept hitting the server even
+while the panel was closed. Now the server pushes as things change: when a
+request or an error is recorded (coalesced over 120 ms), and every two seconds so
+the time-based fields (uptime, memory, the prewarm counter) stay fresh. The
+heartbeat is deliberately independent of prewarming: if the channel's tempo
+followed a background job, the panel would be tied to that job's rhythm. Nothing
+is computed when no panel is connected.
+
+The handshake happens on the HTTP `upgrade` event, and that event never reaches
+the middleware chain, so the channel is attached straight to the server after
+`listen` (`attachDevSocket`). The server side pulls in no dependency such as
+`ws`: all it needs is to write server-to-client text frames and to answer the
+client's ping/close frames.
+
+If the socket cannot be opened at all (a proxy in between may not pass WebSocket
+through), the overlay falls back to the old path: the `/events` SSE stream plus
+polling `/stats`. If the socket opens and later drops — that is, the server is
+restarting — it reconnects every half second and the indicator reads
+"server restarting…" in the meantime.
+
 ## Devtools overlay
 
 A floating bubble in the bottom right; opened with `Alt+D`, closed with `Esc` or
@@ -240,8 +264,9 @@ Under `brand.devBasePath` (default `/__jskelet/dev`):
 | --- | --- | --- |
 | `/overlay.js` | GET | The overlay script |
 | `/logo.png` | GET | The overlay logo |
-| `/events` | GET | SSE: live reload and CSS hot-swap events |
-| `/stats` | GET | Current statistics (the overlay polls every 2 seconds) |
+| `/ws` | GET (upgrade) | Live channel: statistics, live reload and CSS hot-swap events |
+| `/events` | GET | SSE: the fallback event stream, used only when WebSocket cannot be established |
+| `/stats` | GET | Current statistics; the data endpoint of that same fallback |
 | `/report` | GET | The report page (HTML) |
 | `/report.js` | GET | The report page's script |
 | `/report/data` | GET | The report's single data source (JSON) |
@@ -301,7 +326,8 @@ redirect rules.
 | Broken route module | Warn + skip | Throw |
 | Devtools and report | Mounted | Never loaded |
 | `globalThis.fetch` | Wrapped (measurement) | Untouched |
-| Prewarm concurrency | 2 | 4 |
+| Prewarm concurrency | 1 | 4 |
+| Prewarm rate limit | 4 requests/second | Unlimited |
 | Prewarm delay | 3000 ms | 500 ms |
 | Missing icon warning | Emitted | Not emitted |
 | Precompress | Does not run in watch | Runs |

package/docs/en/11-migration.md

@@ -53,7 +53,8 @@ will feel familiar. The *reasons* behind the differences are in
 | `fetch(..., { next: { revalidate } })` | — | The cache is at page level |
 | `unstable_cache` | — | No cross-request data cache; there is a page cache |
 | React `cache()` | `cache()` | Same behavior: in-request memoization |
-| `revalidatePath()` | `clearHtmlCache()` | There is currently no per-key invalidation |
+| `revalidatePath()` | `invalidateHtmlCache("/news/:slug")` | A path, a pattern or a regexp; stales rather than deletes by default |
+| `revalidateTag()` | `clearDataCache("news:")` | No tags to declare: the dependency is observed during the render ([06](./06-caching.md)) |
 | `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Direct access to the Express object |
 | `dynamic = "force-dynamic"` | Not passing `revalidate` | Which means the cache is off |
 
@@ -97,8 +98,6 @@ Account for these from the start in your migration plan:
   `viewTransition` smooths the transition
   ([07](./07-configuration.md)).
 - **Server Actions.** Form submissions are ordinary `app.post(...)` handlers.
-- **Per-path invalidation (`revalidatePath`).** For now there is clearing the
-  whole cache (`clearHtmlCache()`) or waiting for the TTL to expire.
 - **Automatic image optimization (at request time).** Optimization happens at
   build time and only covers local images under `public/`; remote images are
   emitted as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",