jskelet 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -31,23 +31,48 @@ one is listed under a **Breaking** heading.
   retry pass, since rate limit windows are measured in seconds.
 - `cache().maxEntries` configures the HTML cache limit, which used to be a fixed
   500.
+- Transient upstream failures are now detected without any application code:
+  `globalThis.fetch` is wrapped during startup and `429`, `5xx` and network
+  errors raised inside a render are reported on their own, so rate limits stop
+  turning existing pages into 404s even when the data layer never calls
+  `reportUpstreamFailure()`. Requests outside a render and requests to the
+  server itself are ignored, deterministic answers such as `404` are not
+  reported, and the wrapper can be turned off with `cache().trackUpstream:
+  false`.
+- `cache().transientRetry` (`{ attempts: 1, delayMs: 300 }` by default) retries a
+  page that called `notFound()` while upstream was failing. Each attempt runs in
+  a fresh upstream and per-request cache scope, so a page whose data arrives on
+  the second try is served and cached as usual instead of degrading to an error.
 - The dev report now includes the data cache entry count under `cache.data`.
 
 ### 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.
 - `notFound()` is no longer served as a 404 when a transient upstream failure
-  (`429`, `5xx`, network error) was reported during the same render. Those pages
-  now respond with an uncached `503` and `Retry-After`, so a temporary rate limit
-  is not frozen into "this page does not exist" for the whole TTL.
+  (`429`, `5xx`, network error) happened during the same render. The page is
+  retried first and, if upstream is still failing, responds with an uncached
+  `503` and `Retry-After`. A temporary rate limit is no longer frozen into "this
+  page does not exist" for the whole TTL. A retry that gets a clean answer saying
+  the page is gone still returns a normal 404.
 - Responses produced with missing data are no longer offered to shared caches:
   a `degraded` render is sent with `private, no-store` instead of
   `public, s-maxage=…`. The `X-JSkelet-Cache` diagnostic header is still written.
 - The prewarm summary distinguishes paths left for the next pass
   (`700 deferred to the next pass`) from paths dropped entirely
   (`700 over the limit`).
-- The changelog page of the marketing example is generated from the installed
-  package's `CHANGELOG.md` instead of a hand-written list, and shows the version
-  published on npm next to the installed one.
+- The changelog page of the marketing example is generated from the project's
+  `CHANGELOG.md` instead of a hand-written list, and shows the version published
+  on npm next to the installed one.
+- The marketing example reads its markdown (documentation and changelog) from
+  the repository over GitHub's raw endpoint, falling back to the installed
+  package when the network is unavailable, so a deployment that ships without
+  `node_modules` can still serve the docs. In development the local file wins
+  and nothing is cached. The branch is overridable with `DOCS_REF`.
 
 ## [0.1.2] - 2026-08-30
 

package/docs/06-cache.md

@@ -5,8 +5,8 @@ Bu belge JSkelet'in ISR ikamesini bütün ayrıntılarıyla anlatır: HTML TTL
 cache anahtarının nasıl kurulduğu, `X-JSkelet-Cache` başlığının değerleri,
 sıkıştırılmış gövdenin neden önbellekte durduğu, istek içi memoizasyon
 (`withRequestCache` / `cache()`), veri önbelleği (`withDataCache`), upstream
-hatalarının önbelleği nasıl etkilediği (`reportUpstreamFailure`) ve sunucu
-açılışındaki ısıtma turu.
+hatalarının önbelleği nasıl etkilediği (otomatik izleme ve
+`reportUpstreamFailure`) ve sunucu açılışındaki ısıtma turu.
 Kararların arkasındaki ölçüm gerekçeleri [02-mimari.md](./02-mimari.md)'de,
 config alanlarının tam referansı [07-yapilandirma.md](./07-yapilandirma.md)'de.
 
@@ -315,9 +315,34 @@ Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir.
 HTML'i tüm TTL boyunca servis etmek yerine önbelleğe **hiç yazmamak** doğru
 davranış: sonraki istek yeniden dener.
 
+Bu bilgi iki yoldan gelir.
+
+### Otomatik izleme (varsayılan)
+
+`createApp()` açılışta `globalThis.fetch`i sarar ve render sırasında yapılan
+çağrılardaki **geçici** hataları (`429`, `5xx`, ağ hatası) kendiliğinden
+bildirir. Uygulama tarafında hiçbir satır gerekmez; `fetch` ile konuşan bir API
+istemcisi varsa rate limit koruması hazırdır.
+
+Ayrıntılar:
+
+- Yalnızca bir render bağlamı içindeki çağrılar sayılır. Script'ten, cron'dan
+  ya da istek dışı bir yerden yapılan `fetch` dokunulmaz kalır.
+- Kendi sunucumuza yapılan istekler (`localhost`, `127.0.0.1`) atlanır: ısıtma
+  turu ve sağlık kontrolü upstream değildir.
+- `404`/`403` gibi deterministik cevaplar **otomatik olarak bildirilmez**. Çoğu
+  API'de `404` "böyle bir kayıt yok" demektir; onu eksik veri saymak her yok
+  sayfasında yanlış uyarı üretirdi.
+- Kapatmak için `cache().trackUpstream: false`. `fetch`i kendisi saran bir
+  uygulama (ölçüm, retry, circuit breaker) bunu tercih edebilir.
+
+### Elle bildirim
+
+`fetch` kullanmayan bir istemci (veritabanı sürücüsü, gRPC, satıcı SDK'sı) ya da
+kalıcı hataları da işaretlemek isteyen bir katman için sözleşme aynı kaldı.
 Bağımlılık yönü bilinçli olarak tersine çevrilmiştir: framework veri katmanını
 tanımaz, veri katmanı framework'e haber verir. Hiç çağıran olmazsa maliyet boş
-bir dizidir.
+bir dizidir. Aynı hata her iki yoldan bildirilirse tekilleştirilir.
 
 ```js
 // lib/api/client.js
@@ -366,18 +391,44 @@ geçici bir kota sorunu TTL boyunca "bu sayfa yok" cevabına dönüşür. Arama
 için bu kalıcı bir kayıp.
 
 Framework bu durumu ayırır: render sırasında **geçici** bir upstream hatası
-bildirilmişse `notFound()` 404 olarak servis edilmez.
+varsa `notFound()` 404 olarak servis edilmez. Sırayla:
+
+1. Sayfa kısa bir beklemeden sonra **yeniden denenir** (varsayılan bir kez,
+   300 ms sonra). Deneme kendi upstream ve istek içi cache bağlamında koşar;
+   ilk turun hatası da memoize edilmiş boş cevabı da ikinci turu etkilemez.
+2. İkinci tur sayfayı üretebilirse ziyaretçi **gerçek içeriği** görür ve çıktı
+   normal şekilde önbelleğe girer. Isıtma günlükleri bunun sık olduğunu
+   gösteriyor: aynı yol saniyeler sonra 200 dönüyor.
+3. Denemeler tükendiyse yanıt `503` olur — önbelleğe girmez, `Retry-After`
+   taşır, sonraki istek yine gerçek içeriği üretebilir.
 
 | Render sırasında | `notFound()` sonucu |
 | --- | --- |
-| Geçici hata var (`429`, `5xx`, ağ hatası) | `503`, `Retry-After: 30`, `no-store` — önbelleğe **girmez**, sonraki istek gerçek içeriği üretir |
-| Kalıcı hata var (`404`, `403`…) ya da hata yok | Normal `404` |
+| Geçici hata var (`429`, `5xx`, ağ hatası) | Tekrar dene → başarılıysa sayfa; hâlâ olmuyorsa `503`, `Retry-After: 30`, `no-store` |
+| Tekrar denemede upstream sağlam cevap verip "yok" dedi | Normal `404` |
+| Kalıcı hata var (`404`, `403`…) ya da hata yok | Normal `404`, tekrar denenmez |
+
+Log satırları:
 
-Log satırı:
-`[render] /haber/x returned notFound() while upstream is failing (429 /api/...), serving an uncached 503 instead`
+```
+[render] /haber/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /haber/x could not be produced, upstream is still failing (429 /api/...), serving an uncached 503 instead of a 404
+```
+
+Yani **var olan bir sayfa hiçbir koşulda 404'e dönüşmez**: ya gerçek içerik
+gelir, ya önbelleğe girmeyen bir 503. Hiçbir şey "yok" olarak dondurulmaz.
+
+Tekrar denemenin maliyeti upstream'e binen ikinci bir istek turudur; bu yüzden
+varsayılan tek deneme. Ayar `cache().transientRetry`:
+
+```js
+cache: {
+  transientRetry: { attempts: 2, delayMs: 500 },
+}
+```
 
-Yani upstream'in kotası dolduğunda sayfa dinamik olarak, önbelleğe yazılmadan
-üretilir; hiçbir şey "yok" olarak dondurulmaz.
+`transientRetry: false` (ya da `attempts: 0`) tekrarı kapatır ve doğrudan 503'e
+düşer.
 
 ## Önbelleği yönetmek
 
@@ -612,8 +663,10 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
 - **Isıtma listesi `max`'tan uzun ve sonu hiç ısınmıyor.** `rotate: false`
   olabilir; logdaki `over the limit` ifadesi bunu gösterir.
 - **Bir bölümün tamamı 404 dönüyor.** Upstream düşmüş olabilir. Artık bu durumda
-  404 değil önbelleğe girmeyen 503 dönüyor; logda `returned notFound() while
-  upstream is failing` satırını arayın.
+  sayfa bir kez daha denenir, olmazsa 404 değil önbelleğe girmeyen 503 döner;
+  logda `returned notFound() while upstream is failing` satırını arayın. Hâlâ
+  404 görüyorsanız hata `fetch` dışı bir istemciden geliyor olabilir
+  (`reportUpstreamFailure()` gerekir) ya da `cache().trackUpstream` kapatılmış.
 
 ## Sırada ne var
 

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, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -599,6 +599,24 @@ Upstream veri önbelleği (`withDataCache`). Ayrıntı: [06-cache.md](./06-cache
 | `maxEntries` | `number` | `10000` | LRU girdi sınırı. JSON, HTML'e göre onlarca kat küçük olduğu için sınır yüksek. |
 | `staleFactor` | `number` | `10` | TTL dolduktan sonra girdinin kaç TTL boyunca daha kullanılabileceği. `0` → bayat servis yok. |
 
+### `cache().trackUpstream`
+
+**Tip:** `boolean` — **Varsayılan:** `true`
+
+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().transientRetry`
+
+**Tip:** `{ attempts?: number, delayMs?: number } | false` —
+**Varsayılan:** `{ attempts: 1, delayMs: 300 }`
+
+Geçici bir upstream hatası yüzünden `notFound()` çağrılan sayfa kaç kez daha
+denenir. Amaç var olan bir sayfanın 404'e dönüşmemesi; denemeler tükenirse yanıt
+önbelleğe girmeyen bir 503 olur. `false` ya da `attempts: 0` tekrarı kapatır.
+Ayrıntı: [06-cache.md](./06-cache.md).
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |

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,27 @@ 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
+bir, geri kalan zamanda yalnızca uptime/bellek tazelensin diye dört saniyede bir.
+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 +257,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) |

package/docs/en/06-caching.md

@@ -5,7 +5,7 @@ cache and its stale-while-revalidate behaviour, where `revalidate` comes from,
 how the cache key is built, the values of the `X-JSkelet-Cache` header, why the
 compressed body is kept in the cache, per-request memoization
 (`withRequestCache` / `cache()`), the data cache (`withDataCache`), how upstream
-failures affect the cache (`reportUpstreamFailure`) and the prewarm round at
+failures affect the cache (automatic tracking and `reportUpstreamFailure`) and the prewarm round at
 server startup. The
 measurement rationale behind the decisions is in
 [02-architecture.md](./02-architecture.md), and the full reference of config
@@ -324,9 +324,35 @@ If upstream went down during the render, the output contains missing data.
 Rather than serving such HTML for the whole TTL, the right behaviour is to
 **never write it** to the cache: the next request tries again.
 
-The dependency direction is deliberately inverted: the framework does not know
-about the data layer, the data layer notifies the framework. If nobody ever
-calls it, the cost is an empty array.
+This information arrives through two paths.
+
+### Automatic tracking (the default)
+
+At startup `createApp()` wraps `globalThis.fetch` and reports **transient**
+failures (`429`, `5xx`, network errors) from calls made during a render on its
+own. No application code is needed; if your API client talks over `fetch`, the
+rate limit protection is already in place.
+
+The details:
+
+- Only calls inside a render scope count. A `fetch` from a script, a cron job or
+  anywhere outside a request is left untouched.
+- Requests to our own server (`localhost`, `127.0.0.1`) are skipped: the warm-up
+  round and the health check are not upstream.
+- Deterministic answers such as `404`/`403` are **not** reported automatically.
+  In most APIs a `404` means "no such record"; treating it as missing data would
+  produce a false warning on every not-found page.
+- To turn it off: `cache().trackUpstream: false`. An application that wraps
+  `fetch` itself (metrics, retries, a circuit breaker) may prefer that.
+
+### Manual reporting
+
+For a client that does not use `fetch` (a database driver, gRPC, a vendor SDK),
+or for a layer that wants to flag permanent failures too, the contract is
+unchanged. The dependency direction is deliberately inverted: the framework does
+not know about the data layer, the data layer notifies the framework. If nobody
+ever calls it, the cost is an empty array. If the same failure arrives through
+both paths it is de-duplicated.
 
 ```js
 // lib/api/client.js
@@ -374,19 +400,45 @@ site into 404s when upstream is rate limited — and because those 404s enter th
 cache, a temporary quota problem becomes a "this page does not exist" answer for
 the whole TTL. For a search engine that is a permanent loss.
 
-The framework separates the two cases: if a **transient** upstream failure was
-reported during the render, `notFound()` is not served as a 404.
+The framework separates the two cases: if a **transient** upstream failure
+happened during the render, `notFound()` is not served as a 404. In order:
+
+1. The page is **retried** after a short delay (once by default, after 300 ms).
+   The retry runs in its own upstream and per-request cache scope, so neither
+   the first round's failure nor its memoized empty answers affect it.
+2. If the second round can produce the page, the visitor sees the **real
+   content** and the output is cached normally. Warm-up logs show this is
+   common: the same path returns 200 seconds later.
+3. If the retries are exhausted the response is a `503` — not cached, carrying
+   `Retry-After`, and the next request can still produce the real content.
 
 | During the render | Result of `notFound()` |
 | --- | --- |
-| A transient failure exists (`429`, `5xx`, network error) | `503`, `Retry-After: 30`, `no-store` — **not** written to the cache, the next request produces the real content |
-| A permanent failure (`404`, `403`…) or no failure | A normal `404` |
+| A transient failure exists (`429`, `5xx`, network error) | Retry → the page if it succeeds; otherwise `503`, `Retry-After: 30`, `no-store` |
+| The retry got a clean answer saying "not there" | A normal `404` |
+| A permanent failure (`404`, `403`…) or no failure | A normal `404`, no retry |
+
+The log lines:
 
-The log line:
-`[render] /news/x returned notFound() while upstream is failing (429 /api/...), serving an uncached 503 instead`
+```
+[render] /news/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /news/x could not be produced, upstream is still failing (429 /api/...), serving an uncached 503 instead of a 404
+```
+
+So **an existing page never turns into a 404**: either the real content arrives,
+or an uncached 503 does. Nothing is frozen as "missing".
+
+The cost of a retry is a second round of requests on upstream, which is why the
+default is a single attempt. The setting is `cache().transientRetry`:
+
+```js
+cache: {
+  transientRetry: { attempts: 2, delayMs: 500 },
+}
+```
 
-So when upstream runs out of quota the page is produced dynamically, without
-being written to the cache; nothing is frozen as "missing".
+`transientRetry: false` (or `attempts: 0`) disables the retry and falls straight
+through to the 503.
 
 ## Managing the cache
 
@@ -628,9 +680,12 @@ filled the cache.
   does not reach upstream.
 - **The warm-up list is longer than `max` and its tail never warms.** `rotate`
   may be `false`; the `over the limit` phrase in the log shows this.
-- **A whole section returns 404.** Upstream may be down. In that case a 503 that
-  does not enter the cache is now returned instead of a 404; look for the
-  `returned notFound() while upstream is failing` line in the log.
+- **A whole section returns 404.** Upstream may be down. The page is now retried
+  once and, failing that, a 503 that does not enter the cache is returned
+  instead of a 404; look for the `returned notFound() while upstream is failing`
+  line in the log. If you still see 404s, the failure may come from a non-`fetch`
+  client (which needs `reportUpstreamFailure()`) or `cache().trackUpstream` is
+  off.
 
 ## What's next
 

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, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -613,6 +613,25 @@ The upstream data cache (`withDataCache`). Details:
 | `maxEntries` | `number` | `10000` | The LRU entry limit. The limit is high because JSON is tens of times smaller than HTML. |
 | `staleFactor` | `number` | `10` | For how many TTLs an entry stays usable after the TTL expired. `0` → no stale serving. |
 
+### `cache().trackUpstream`
+
+**Type:** `boolean` — **Default:** `true`
+
+When on, `globalThis.fetch` is wrapped and transient upstream failures (`429`,
+`5xx`, network) during a render are reported automatically; calling
+`reportUpstreamFailure()` is not required. An application that wraps `fetch`
+itself can turn this off.
+
+### `cache().transientRetry`
+
+**Type:** `{ attempts?: number, delayMs?: number } | false` —
+**Default:** `{ attempts: 1, delayMs: 300 }`
+
+How many extra times a page is tried when `notFound()` was called because of a
+transient upstream failure. The point is that an existing page never turns into
+a 404; if the retries are exhausted the response is an uncached 503. `false` or
+`attempts: 0` disables the retry. Details: [06-caching.md](./06-caching.md).
+
 ### `cache().prewarm`
 
 | Field | Type | Default | Meaning |

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,28 @@ 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), once per second while
+prewarming runs, and every four seconds otherwise so uptime and memory stay
+fresh. 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 +262,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) |

package/package.json

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