jskelet 0.7.3 → 0.7.5

package/CHANGELOG.md

@@ -10,6 +10,13 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
+- Page stylesheets are built as one asset containing global CSS followed by
+  page CSS. Routes that declare `styles` load the combined asset instead of
+  applying `app.css` and page utilities in separate cascade steps, preventing
+  the intermediate layout shifts that occur when those sheets arrive apart.
+- Redis HTML is stored as a small JSON meta key, a raw brotli `:body` key, and
+  optional `:enc:br` / `:enc:gzip` keys on a second connection. HTML command
+  timeouts use their own circuit breaker and no longer bypass the data cache.
 - `.jsk` codegen merges adjacent static HTML into fewer `+=` ops and drops
   template indentation (newline-only whitespace). A lone space between
   inline siblings is kept; `pre` / `textarea` / `script` / `style` / `code`
@@ -73,6 +80,9 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- `cache().redis.htmlCommandTimeoutMs` (default `2000`) limits only the HTML
+  Redis connection. `commandTimeoutMs` stays `200` for data, publish, and scan.
+  The admin Redis card shows both timeouts.
 - `stylesheets({ blocking: false })` and `<Stylesheets :blocking="false" />`
   emit each stylesheet with `media="print"` and an `onload` that switches it
   to `all`, plus a `<noscript>` fallback, so the links do not block rendering.

package/docs/03-routing.md

@@ -219,7 +219,7 @@ Controller `async (ctx) => sayfa` biçimindedir ve şu alanları döndürebilir:
 | `head` | `string` | `""` | `<head>`e olduğu gibi basılacak ham HTML (ör. LCP preload'ı). |
 | `bodyClass` | `string` | `hooks.layoutContext().bodyClass ?? ""` | `<body class="…">`. |
 | `entries` | `string[]` | `[]` | Bu sayfada ek olarak yüklenecek client entry adları: `["chart.js"]`. |
-| `styles` | `string[]` | `[]` | Bu sayfada ek olarak yüklenecek stylesheet adları: `["home.css"]` → `styles/pages/home.css`. |
+| `styles` | `string[]` | `[]` | Global CSS ile birleştirilip `app.css` yerine yüklenecek sayfa stylesheet adları: `["home.css"]` → `styles/pages/home.css`. |
 
 `revalidate` **`route()`'un ikinci argümanıdır**, controller'ın döndürdüğü
 nesnenin alanı değil.

package/docs/04-render-ve-sablonlar.md

@@ -182,12 +182,12 @@ Dikkat edilecek noktalar:
 - **`extraHead` en başta.** Kaynak ipuçlarını (`preconnect`, LCP `preload`)
   geciktirmek doğrudan LCP'ye yazılır.
 - **Global `app.css` varsayılan olarak render-blocking** ve gerekçesi
-  [02-mimari.md](./02-mimari.md)'de. Controller `styles: [...]` ile ek sayfa
-  sheet'leri de aynı şekilde basılır. `<Stylesheets :blocking="false" />`
-  (`stylesheets({ blocking: false })`) linkleri `media="print"` + `onload`
-  ile basar; JS kapalıyken `<noscript>` yedeği uygulanır. Boyama beklenmez,
-  sheet gelince düzen kayabilir. Build çalışmadıysa `hasAsset` false olur
-  ve etiket hiç basılmaz.
+  [02-mimari.md](./02-mimari.md)'de. Controller `styles: [...]` verirse sayfa
+  sheet'i global CSS'i de içeren birleşik varlıktır ve `app.css` yerine basılır.
+  `<Stylesheets :blocking="false" />` (`stylesheets({ blocking: false })`)
+  linki `media="print"` + `onload` ile basar; JS kapalıyken `<noscript>` yedeği
+  uygulanır. Boyama beklenmez, sheet gelince düzen kayabilir. Build çalışmadıysa
+  `hasAsset` false olur ve etiket hiç basılmaz.
 - **`hasAsset` kontrolleri** build eksikken sayfanın 404 veren dosyaları
   istememesini sağlar (`Stylesheets` / `BodyScripts` içinde).
 - **Devtools script'i** yalnızca `NODE_ENV=development` iken basılır; prod
@@ -437,7 +437,8 @@ icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
 
 ### `stylesheets(props)`
 
-Layout `<head>` içindeki global `app.css` ve controller `styles` dizisi.
+Layout `<head>` içindeki global `app.css` veya controller `styles` dizisindeki
+birleşik sayfa sheet'leri.
 Doğrudan çağırmak yerine yerleşik etiket kullanılır:
 
 ```jsk
@@ -451,7 +452,9 @@ stylesheets({ styles: ["home.css"], blocking: false });
 ```
 
 - `styles` manifest anahtarlarıdır (`"home.css"` → `styles/pages/home.css`).
-  `hasAsset` false olanlar basılmaz.
+  Geçerli en az bir sayfa sheet'i varsa `app.css` ayrıca basılmaz; her sayfa
+  çıktısı global CSS'i zaten içerir. Hiçbiri manifest'te yoksa `app.css`e
+  dönülür.
 - `blocking` varsayılan `true`: `<link rel="stylesheet" data-jskelet-css="…">`.
   Yalnızca boolean `false` beklemeyi kapatır. Çıktı `media="print"` ve
   `onload="this.media='all'"` olur; eşleşmeyen media boyamayı bekletmez.

package/docs/06-cache.md

@@ -831,9 +831,11 @@ npm install ioredis
 ```
 
 Kurulmadıysa ya da Redis'e bağlanılamıyorsa uyarı basılır ve site **bellek içi
-önbellekle çalışmaya devam eder**. Redis çalışırken düşerse aynı şey olur: bir
-devre kesici art arda beş hatadan sonra katmanı beş saniye baypas eder, böylece
-her istek ağ zaman aşımı beklemez.
+önbellekle çalışmaya devam eder**. Redis çalışırken düşerse aynı şey olur:
+veri ve HTML için ayrı devre kesiciler vardır. Art arda beş hata ilgili
+katmanı beş saniye baypas eder, böylece her istek ağ zaman aşımı beklemez.
+HTML zaman aşımı veri sayacına yazılmaz; yavaş bir sayfa küçük veri
+anahtarlarını kapatmaz.
 
 ### Ne kazanırsınız
 
@@ -852,6 +854,8 @@ her istek ağ zaman aşımı beklemez.
 
 ```
 _jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}:body
+_jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}:enc:{br|gzip}
 _jskelet:{namespace}:{buildId}:data:{anahtar}
 _jskelet:{namespace}:events
 ```
@@ -867,12 +871,25 @@ anahtarlar TTL ile ölür — elle temizlik ya da `FLUSHDB` gerekmez. Build
 bilinçli olarak `buildId` **taşımaz**: deploy sırasında eski ve yeni sürüm yan
 yana koşuyor ve bir purge ikisine de ulaşmalı.
 
-1 KB ve üstü HTML ve veri girdileri düz JSON olarak durmaz: `JSK\x01` önekli
-brotli gövde yazılır (kalite 5, metin modu — yanıt sıkıştırmasıyla aynı ayar).
-L1 yine çözülmüş nesne tutar; sıkıştırma yalnızca L1 miss'ten sonraki
-paylaşımda, yanıtı bekletmeden çalışır. Daha küçük kayıtlar düz JSON kalır,
-eski düz JSON kayıtlar da okunur. zstd kullanılmaz: `node:zlib` içindeki zstd
-22.15'ten itibaren var, motor ise `>=22`.
+HTML üç parçaya yazılır. Meta anahtarı küçük bir JSON'dur (`status`,
+`storedAt`, `expiresAt`, `staleUntil`, `produceMs`, `deps`) ve gövde içermez.
+`:body` HTML'in brotli baytıdır; base64 yoktur ve bu bayt bir JSON'un içine
+ikinci kez sıkıştırılmaz. `storeEncoded` açıksa yanıt için üretilmiş brotli
+veya gzip gövdesi `:enc:br` / `:enc:gzip` anahtarına olduğu gibi yazılır.
+Okuma meta ile gövdeyi tek pipeline'da ister; parçalardan biri yoksa kayıt yok
+sayılır ve sayfa render edilir.
+
+Veri girdileri 1 KB ve üstünde düz JSON olarak durmaz: `JSK\x01` önekli brotli
+gövde yazılır (kalite 5, metin modu — yanıt sıkıştırmasıyla aynı ayar). Daha
+küçük veri kayıtları düz JSON kalır. HTML bu sarmalayıcıyı kullanmaz. zstd
+kullanılmaz: `node:zlib` içindeki zstd 22.15'ten itibaren var, motor ise
+`>=22`.
+
+`commandTimeoutMs` (varsayılan 200) veri, yayın ve `SCAN` komutlarına
+uygulanır. HTML okuma ve yazma ayrı bir bağlantıdadır; `htmlCommandTimeoutMs`
+(varsayılan 2000) yalnız o bağlantının komutlarını sınırlar. ioredis zaman
+aşımı istemci genelinde olduğu için iki süre tek bağlantıda ayrılamaz.
+Uygulama bu alanı vermezse framework 2000 kullanır.
 
 Redis kapalıyken (ya da bağlanamadığında) aynı gövde `.jskelet/cache/<buildId>/`
 altına dosya olarak yazılır. Süreç yeniden açılınca L1 boştur ama diskteki
@@ -889,8 +906,8 @@ bir sonraki yazışta siler. `clearHtmlCache()` ve invalidation dosyayı da dü
   dışındaki durum kodları da paylaşılmaz.
 - **Sıkıştırılmış gövdeler varsayılan olarak paylaşılır.** `storeEncoded`
   (varsayılan `true`) soğuk replica'nın L2 HIT'te yeniden brotli ödemesini
-  önler; girdi başına boyutu iki-üç katına çıkarır. L2 boyutunu kısıtlamak
-  için `storeEncoded: false` verin.
+  önler. Gövde `:enc:{br|gzip}` anahtarına ham bayt olarak yazılır; meta
+  JSON'unun içine base64 girmez. Kapatmak için `storeEncoded: false` verin.
 - **Yumuşak invalidation Redis kopyasını siler.** Bayatlatmanın Redis karşılığı
   her anahtar için oku-değiştir-yaz turu demek ve bir webhook binlerce anahtarı
   birden düşürüyor. Silmenin bedeli, o yolu hiç görmemiş bir kopyanın bir kez
@@ -917,16 +934,18 @@ app.get("/api/healthcheck", (req, res) => {
 ```
 
 Bağlantı kurulmamışken de güvenle çağrılır. Dönen nesne
-`{ enabled, connected, keyPrefix, buildId, errors, bypassed }`; `bypassed` devre
-kesicinin açık olduğunu, `errors` toplam komut hatasını gösterir. Aynı özet dev
-panelinin raporunda da var ([09-dev-araclari.md](./09-dev-araclari.md)).
+`{ enabled, connected, keyPrefix, buildId, errors, bypassed, htmlErrors, htmlBypassed }`.
+`bypassed` veri katmanının, `htmlBypassed` HTML katmanının baypasta olduğunu
+gösterir. `errors` veri komutlarının, `htmlErrors` HTML komutlarının toplam
+hatasıdır. Aynı özet dev panelinin raporunda da var
+([09-dev-araclari.md](./09-dev-araclari.md)).
 
 İki teşhis yüzeyi daha var:
 
 | Çağrı | Ne der |
 | --- | --- |
 | `getRedisDetails()` | Bağlantının **nereye** kurulduğu: adres, TLS, veritabanı, `namespace`, hangi türlerin paylaşıldığı, purge yayınına abone olunup olunmadığı. Şifre asla dönmez — bağlantı URL'i sır taşıyor olabilir. |
-| `inspectRedis()` | Paylaşımlı kademede gerçekten ne durduğu: tür başına anahtar sayısı, `DBSIZE` ve `used_memory`. Bir `SCAN` turu olduğu için **istek yolunda çağrılmaz**; yönetim panelinde de ayrı bir düğmeye bağlı. |
+| `inspectRedis()` | Paylaşımlı kademede gerçekten ne durduğu: tür başına kayıt sayısı (HTML'de gövde ve kodlama parçaları tek sayfa sayılır), `DBSIZE` ve `used_memory`. Bir `SCAN` turu olduğu için **istek yolunda çağrılmaz**; yönetim panelinde de ayrı bir düğmeye bağlı. |
 
 Ayarların tam listesi: [07-yapilandirma.md](./07-yapilandirma.md).
 
@@ -1029,7 +1048,7 @@ değil.
 | Clear HTML cache | `clearHtmlCache()` |
 | Clear data cache (önek opsiyonel) | `clearDataCache(prefix)` |
 | Drop shared keys | Redis'teki `html` ya da `data` isim alanını tarar ve düşürür |
-| Count keys in Redis | `inspectRedis()` — tür başına anahtar sayısı, `DBSIZE` ve `used_memory` |
+| Count keys in Redis | `inspectRedis()` — tür başına kayıt (HTML parçaları tek sayfa sayılır), `DBSIZE` ve `used_memory` |
 | Prewarm | `prewarm()` — tur arkada koşar, ilerleme kartta görünür |
 | Cloudflare purge (her şey / bellekteki URL'ler / prefix / host / tag) | `purgeCloudflare()` |
 | Cloudflare ayarı ya da özelliği değiştirmek | Zone ayarları ve Tiered Cache / Cache Reserve |

package/docs/07-yapilandirma.md

@@ -960,15 +960,17 @@ kurulmadıysa ya da bağlanılamıyorsa uyarı basılır ve site bellek içi ön
 | `keyPrefix` | `string` | `"_jskelet"` | Anahtar düzeninin kökü |
 | `html` | `boolean` | `true` | HTML gövdeleri paylaşılsın mı |
 | `data` | `boolean` | `true` | `withDataCache` girdileri paylaşılsın mı |
-| `storeEncoded` | `boolean` | `true` | Brotli/gzip gövdeleri de paylaşılsın mı; girdi başına boyutu iki-üç katına çıkarır |
+| `storeEncoded` | `boolean` | `true` | Brotli/gzip gövdeleri ayrı `:enc:` anahtarına yazılsın mı |
 | `events` | `boolean` | `true` | pub/sub üzerinden invalidation yayını |
-| `commandTimeoutMs` | `number` | `200` | Tek bir komutun en fazla bekletebileceği süre |
-
-Anahtarlar `_jskelet:{namespace}:{buildId}:html:{yol}?{query}` biçiminde yaşar.
-`buildId` her build'de değişir, böylece deploy sonrası eski HTML kendiliğinden
-geçersiz olur. Kişiye özel (`storable: false`), `degraded` ve 200 dışındaki
-yanıtlar paylaşımlı kademeye hiç yazılmaz. Takaslar ve teşhis:
-[06-cache.md](./06-cache.md).
+| `commandTimeoutMs` | `number` | `200` | Veri, yayın ve `SCAN` için tek komutun tavanı |
+| `htmlCommandTimeoutMs` | `number` | `2000` | Yalnızca HTML bağlantısının komut tavanı. Verilmezse 2000 |
+
+Anahtarlar parçalıdır: `_jskelet:{namespace}:{buildId}:html:{yol}?{query}` küçük
+meta JSON'u, aynı anahtarın `:body` soneki HTML'in brotli baytını, `:enc:br`
+ve `:enc:gzip` ise yanıt kodlamasını tutar. `buildId` her build'de değişir,
+böylece deploy sonrası eski HTML kendiliğinden geçersiz olur. Kişiye özel
+(`storable: false`), `degraded` ve 200 dışındaki yanıtlar paylaşımlı kademeye
+hiç yazılmaz. Takaslar ve teşhis: [06-cache.md](./06-cache.md).
 
 ```js
 redis: {

package/docs/08-build.md

@@ -163,12 +163,18 @@ return {
 Dizin, `paths.styles` dosyasının yanındaki `pages/` klasörüdür (`styles` taşınırsa
 pages de yanında kalır). Dizin yoksa veya boşsa adım yalnızca global sheet üretir.
 
-Sayfa CSS'i sayfaya özel kurallar içindir. Tailwind utility'leri global sheet'te
-kalmalı — dosyada tam `@import "tailwindcss"` utility çıktısını tekrarlar.
-
-Layout `app.css`ten sonra `styles` dizisindeki her sheet için
-`<link data-jskelet-css="…">` basar; `hasAsset` false ise etiket yok.
-`blocking: false` aynı linklere `media="print"` ve `onload` ekler.
+Her sayfa çıktısı **global derlenmiş CSS + sayfa derlenmiş CSS** içeren tek bir
+dosyadır. Controller bir sayfa sheet'i bildirdiğinde layout `app.css`i ayrıca
+basmaz; yalnızca birleşik sheet'i yükler. Böylece inline kritik CSS, `app.css`
+ve page sheet içindeki aynı Tailwind utility katmanı üç ayrı anda uygulanmaz.
+Örneğin global `.px-0` ile sayfadaki `.lg:px-4` çatışsa bile tarayıcı yalnızca
+dosyanın son cascade sonucunu boyar ve ara düzen CLS üretmez.
+
+Sayfa CSS'i sayfaya özel kurallar içindir. Bir route için tek sayfa dosyası
+tercih edin; `styles` dizisinde birden fazla ad hâlâ desteklenir ama her biri
+global CSS'i taşıdığı için gereksiz tekrar indirir. Sayfa adı manifest'te yoksa
+layout güvenli biçimde `app.css`e döner. `blocking: false` birleşik linke
+`media="print"` ve `onload` ekler.
 
 ### `@source` direktifleri zorunludur
 

package/docs/en/03-routing.md

@@ -222,7 +222,7 @@ fields:
 | `head` | `string` | `""` | Raw HTML to be printed into `<head>` as-is (e.g. the LCP preload). |
 | `bodyClass` | `string` | `hooks.layoutContext().bodyClass ?? ""` | `<body class="…">`. |
 | `entries` | `string[]` | `[]` | The names of client entries to be loaded additionally on this page: `["chart.js"]`. |
-| `styles` | `string[]` | `[]` | Extra stylesheets for this page: `["home.css"]` → `styles/pages/home.css`. |
+| `styles` | `string[]` | `[]` | Page stylesheets combined with global CSS and loaded instead of `app.css`: `["home.css"]` → `styles/pages/home.css`. |
 
 `revalidate` is **the second argument of `route()`**, not a field of the object
 the controller returns.

package/docs/en/04-rendering.md

@@ -181,8 +181,9 @@ Points to watch:
 - **`extraHead` comes first.** Delaying resource hints (`preconnect`, LCP
   `preload`) writes straight into LCP.
 - **`<Stylesheets />` emits global `app.css` render-blocking by default**,
-  plus controller `styles: [...]`, with the reasoning in
-  [02-architecture.md](./02-architecture.md).
+  with the reasoning in [02-architecture.md](./02-architecture.md). When a
+  controller provides `styles: [...]`, a page sheet is a combined asset that
+  already contains global CSS and is emitted instead of `app.css`.
   `<Stylesheets :blocking="false" />` (`stylesheets({ blocking: false })`)
   emits the links with `media="print"` plus `onload`, and a `<noscript>`
   fallback when JS is off. Painting is not held, and the layout can shift
@@ -442,7 +443,8 @@ icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
 
 ### `stylesheets(props)`
 
-Global `app.css` and the controller `styles` list for the layout `<head>`.
+Global `app.css`, or the combined page sheets in the controller `styles` list,
+for the layout `<head>`.
 The built-in tag is the usual call site:
 
 ```jsk
@@ -456,7 +458,9 @@ stylesheets({ styles: ["home.css"], blocking: false });
 ```
 
 - `styles` are manifest keys (`"home.css"` → `styles/pages/home.css`). Names
-  for which `hasAsset` is false are omitted.
+  for which `hasAsset` is false are omitted. If at least one page sheet exists,
+  `app.css` is not emitted separately because every page output already
+  includes it. If none exists, the helper falls back to `app.css`.
 - `blocking` defaults to `true`:
   `<link rel="stylesheet" data-jskelet-css="…">`. Only the boolean `false`
   turns waiting off. The output is `media="print"` and

package/docs/en/06-caching.md

@@ -849,8 +849,10 @@ npm install ioredis
 
 If it is not installed, or Redis cannot be reached, a warning is printed and the
 site **keeps running on the in-process cache**. The same happens if Redis goes
-down while running: a circuit breaker bypasses the tier for five seconds after
-five consecutive failures, so requests do not each wait for a network timeout.
+down while running: data and HTML have separate circuit breakers. Five
+consecutive failures bypass that tier for five seconds, so requests do not each
+wait for a network timeout. An HTML timeout is not charged to the data counter,
+so a slow page does not shut the small data keys.
 
 ### What you get
 
@@ -870,6 +872,8 @@ five consecutive failures, so requests do not each wait for a network timeout.
 
 ```
 _jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}:body
+_jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}:enc:{br|gzip}
 _jskelet:{namespace}:{buildId}:data:{key}
 _jskelet:{namespace}:events
 ```
@@ -885,13 +889,25 @@ build has not been run the id is `dev`.
 deliberately does **not** carry `buildId`: during a deploy the old and the new
 version run side by side and a purge has to reach both.
 
-HTML and data entries of 1 KB or more are not stored as plain JSON. The shared
-tier receives a brotli body prefixed with `JSK\x01` (quality 5, text mode — the
-same settings as response compression). L1 still holds the decoded value;
-compression runs only when sharing after an L1 miss, and it does not delay the
-response. Smaller records stay plain JSON, and older plain JSON records are
-still read. zstd is not used: `node:zlib` gained it in 22.15, while the engine
-range is `>=22`.
+HTML is stored as three parts. The meta key is a small JSON document
+(`status`, `storedAt`, `expiresAt`, `staleUntil`, `produceMs`, `deps`) and does
+not contain the body. `:body` is the brotli bytes of the HTML: no base64, and
+those bytes are not compressed again inside JSON. When `storeEncoded` is on,
+the brotli or gzip body produced for the response is written as-is to
+`:enc:br` / `:enc:gzip`. A read pipelines meta and body; if either part is
+missing the record counts as absent and the page is rendered.
+
+Data entries of 1 KB or more are not stored as plain JSON. They are a brotli
+body prefixed with `JSK\x01` (quality 5, text mode — the same settings as
+response compression). Smaller data records stay plain JSON. HTML does not use
+that wrapper. zstd is not used: `node:zlib` gained it in 22.15, while the
+engine range is `>=22`.
+
+`commandTimeoutMs` (default 200) applies to data, publish, and `SCAN`. HTML
+reads and writes use a second connection; `htmlCommandTimeoutMs` (default
+2000) limits only that connection. ioredis applies `commandTimeout` to the
+whole client, so the two budgets cannot share one connection. When an
+application omits the field, the framework uses 2000.
 
 When Redis is off, or cannot connect, the same body is written under
 `.jskelet/cache/<buildId>/`. After a restart L1 is empty, but a fresh file
@@ -908,8 +924,9 @@ file too.
   tier: a leak would mean serving one user's HTML to the whole cluster.
   `degraded` renders and non-200 status codes are not shared either.
 - **Compressed bodies are shared by default.** `storeEncoded` (default `true`)
-  keeps a cold replica from paying brotli again on an L2 HIT; it doubles or
-  triples the size per entry. Set `storeEncoded: false` to keep L2 lean.
+  keeps a cold replica from paying brotli again on an L2 HIT. The body is
+  stored as raw bytes on an `:enc:{br|gzip}` key; it is not base64 inside the
+  meta JSON. Set `storeEncoded: false` to skip those keys.
 - **A soft invalidation deletes the Redis copy.** Staling in Redis would mean a
   read-modify-write round per key, and a webhook drops thousands of keys at
   once. The cost of deleting is one render on a replica that never saw that
@@ -936,9 +953,10 @@ app.get("/api/healthcheck", (req, res) => {
 ```
 
 Safe to call even with no connection. The returned object is
-`{ enabled, connected, keyPrefix, buildId, errors, bypassed }`; `bypassed` tells
-you the circuit breaker is open and `errors` is the total command failure count.
-The same summary is in the dev panel report
+`{ enabled, connected, keyPrefix, buildId, errors, bypassed, htmlErrors, htmlBypassed }`.
+`bypassed` means the data tier is in its bypass window and `htmlBypassed` means
+the HTML connection is. `errors` counts data-command failures and `htmlErrors`
+counts HTML-command failures. The same summary is in the dev panel report
 ([09-dev-tools.md](./09-dev-tools.md)).
 
 Two more diagnostic surfaces:
@@ -946,7 +964,7 @@ Two more diagnostic surfaces:
 | Call | What it tells you |
 | --- | --- |
 | `getRedisDetails()` | **Where** the connection points: address, TLS, database, `namespace`, which kinds are shared, whether the purge channel is subscribed. The password is never returned — a connection URL may carry one. |
-| `inspectRedis()` | What is actually in the shared tier: keys per kind, `DBSIZE` and `used_memory`. It runs a `SCAN`, so **never call it on the request path**; in the admin panel it sits behind its own button. |
+| `inspectRedis()` | What is actually in the shared tier: records per kind (HTML body and encoding fragments count as one page), `DBSIZE` and `used_memory`. It runs a `SCAN`, so **never call it on the request path**; in the admin panel it sits behind its own button. |
 
 The full list of settings: [07-configuration.md](./07-configuration.md).
 
@@ -1030,7 +1048,7 @@ export content.
 | Clear HTML cache | `clearHtmlCache()` |
 | Clear data cache (optional prefix) | `clearDataCache(prefix)` |
 | Drop shared keys | Scans and unlinks the `html` or `data` namespace in Redis |
-| Count keys in Redis | `inspectRedis()` — keys per kind, `DBSIZE` and `used_memory` |
+| Count keys in Redis | `inspectRedis()` — records per kind (HTML fragments count as one page), `DBSIZE` and `used_memory` |
 | Prewarm | `prewarm()` — the pass runs in the background, progress shows in the card |
 | Cloudflare purge (everything / URLs held here / prefix / host / tag) | `purgeCloudflare()` |
 | Change a Cloudflare setting or feature | Zone settings and Tiered Cache / Cache Reserve |

package/docs/en/07-configuration.md

@@ -979,12 +979,15 @@ the site keeps running on the in-process cache.
 | `keyPrefix` | `string` | `"_jskelet"` | Root of the key layout |
 | `html` | `boolean` | `true` | Whether HTML bodies are shared |
 | `data` | `boolean` | `true` | Whether `withDataCache` entries are shared |
-| `storeEncoded` | `boolean` | `true` | Whether brotli/gzip bodies are shared too; doubles or triples the size per entry |
+| `storeEncoded` | `boolean` | `true` | Whether brotli/gzip bodies are written to their own `:enc:` keys |
 | `events` | `boolean` | `true` | Invalidation broadcast over pub/sub |
-| `commandTimeoutMs` | `number` | `200` | At most how long a single command may block |
+| `commandTimeoutMs` | `number` | `200` | Per-command ceiling for data, publish, and `SCAN` |
+| `htmlCommandTimeoutMs` | `number` | `2000` | Per-command ceiling for the HTML connection only. `2000` when omitted |
 
-Keys live as `_jskelet:{namespace}:{buildId}:html:{path}?{query}`. `buildId`
-changes with every build, so old HTML becomes invalid on its own after a deploy.
+Keys are split: `_jskelet:{namespace}:{buildId}:html:{path}?{query}` is the
+small meta JSON, the `:body` suffix is the brotli bytes of the HTML, and
+`:enc:br` / `:enc:gzip` hold the response encoding. `buildId` changes with
+every build, so old HTML becomes invalid on its own after a deploy.
 Personalised (`storable: false`), `degraded` and non-200 responses are never
 written to the shared tier. Trade-offs and diagnosis:
 [06-caching.md](./06-caching.md).

package/docs/en/08-build.md

@@ -168,12 +168,19 @@ The directory is `pages/` next to the `paths.styles` file (if `styles` moves,
 pages stays beside it). If the directory is missing or empty, the step only
 produces the global sheet.
 
-Page CSS is for page-specific rules. Keep Tailwind utilities in the global
-sheet — a full `@import "tailwindcss"` in a page file duplicates utility output.
-
-After `app.css`, the layout emits a `<link data-jskelet-css="…">` for each name
-in `styles`; if `hasAsset` is false the tag is omitted. `blocking: false`
-adds `media="print"` and `onload` to those same links.
+Each page output is one file containing **compiled global CSS + compiled page
+CSS**. When a controller declares a page sheet, the layout does not emit
+`app.css` separately; it loads only the combined sheet. This prevents the same
+Tailwind utility layer in inline critical CSS, `app.css`, and the page sheet
+from taking effect at three different times. Even if global `.px-0` conflicts
+with page `.lg:px-4`, the browser paints only the file's final cascade result
+instead of an intermediate layout that causes CLS.
+
+Page CSS is for page-specific rules. Prefer one page file per route; multiple
+names in `styles` are still supported, but each carries the global CSS and
+therefore downloads redundant bytes. If no requested page name exists in the
+manifest, the layout safely falls back to `app.css`. `blocking: false` adds
+`media="print"` and `onload` to the combined link.
 
 ### `@source` directives are mandatory
 

package/package.json

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

package/src/build/tasks/css.mjs

@@ -1,9 +1,10 @@
 /**
  * Tailwind v4 → global `app.css` + isteğe bağlı sayfa stylesheet'leri.
  *
- * Global sheet her sayfada yüklenir (`paths.styles`). Sayfa sheet'leri
- * `styles/pages/*.css` altındadır ve yalnızca controller `styles: ["home.css"]`
- * bildiren sayfalarda basılır — island `entries` ile aynı sözleşme.
+ * Global sheet `paths.styles` girdisinden üretilir. Sayfa sheet'leri
+ * `styles/pages/*.css` altındadır; her çıktı global CSS + sayfa CSS'ini tek
+ * dosyada taşır ve yalnızca controller `styles: ["home.css"]` bildiren
+ * sayfalarda basılır — island `entries` ile aynı sözleşme.
  *
  * Ayrı bir "critical CSS" üretilmez. Ölçümde inline kritik CSS ilk ekranı tam
  * kapsamadığı için sheet gelince sayfa yeniden akıyordu (bir liste sayfasında
@@ -13,9 +14,11 @@
  * varsayılan olarak render-blocking; yalnızca ilgili sayfada ek maliyet.
  * Layout `stylesheets({ blocking: false })` ile bu beklemeyi kapatabilir.
  *
- * Tailwind utility'leri global sheet'te kalmalı. Sayfa CSS'inde tam
- * `@import "tailwindcss"` utility çıktısını tekrarlar; sayfaya özel kurallar
- * yeter.
+ * Birleşik çıktı önemli: inline kritik CSS, global utility'ler ve sayfa
+ * utility'leri ayrı ağ yanıtlarında sırayla uygulanırsa ara cascade düzeni
+ * boyanıp CLS üretebilir. Tarayıcı tek dosyayı ancak tamamı geldikten sonra
+ * uygular; sayfa dosyasındaki son kurallar yine global kuralları ezebilir ama
+ * kullanıcı ara durumu görmez.
  *
  * Tailwind'in sınıf taraması `globals.css` içindeki `@source` direktiflerine
  * bağlıdır. Otomatik tespit yalnızca stylesheet'in bulunduğu dizini tarar,
@@ -130,7 +133,8 @@ export async function buildCss(config, { watch = false } = {}) {
 
     for (const file of listPageStyles(pagesDir)) {
       const name = path.basename(file);
-      const css = applyCdnStaticUrls(await compile(file), config);
+      const pageCss = applyCdnStaticUrls(await compile(file), config);
+      const css = `${appCss}\n${pageCss}`;
       const url = writeAsset(name, css);
       urls[name] = url;
       bytes += Buffer.byteLength(css);

package/src/client/admin/i18n.js

@@ -90,7 +90,9 @@ export const MESSAGES = {
     "redis.broadcast.publish": "publish only",
     "redis.broadcast.local": "local only",
     "redis.timeout": "Command timeout",
+    "redis.htmlTimeout": "HTML command timeout",
     "redis.errors": "Command errors",
+    "redis.htmlErrors": "HTML command errors",
     "redis.tier": "Tier",
     "redis.tier.inProcess": "in-process only",
     "redis.replicas": "Replicas sharing this cache",
@@ -394,7 +396,9 @@ export const MESSAGES = {
     "redis.broadcast.publish": "yalnızca yayın",
     "redis.broadcast.local": "yalnızca yerel",
     "redis.timeout": "Komut zaman aşımı",
+    "redis.htmlTimeout": "HTML komut zaman aşımı",
     "redis.errors": "Komut hatası",
+    "redis.htmlErrors": "HTML komut hatası",
     "redis.tier": "Kademe",
     "redis.tier.inProcess": "yalnızca süreç içi",
     "redis.replicas": "Bu önbelleği paylaşan kopya",

package/src/client/admin/panel.js

@@ -556,8 +556,12 @@ function renderRedis(redis, state) {
         [t("redis.buildId"), redis.buildId || "dev"],
         [
           t("redis.sharesHtml"),
-          redis.html ? t("state.yes") : t("state.no"),
-          redis.html ? "on" : "off",
+          !redis.html
+            ? t("state.no")
+            : redis.htmlBypassed
+              ? t("state.bypassed")
+              : t("state.yes"),
+          redis.html && !redis.htmlBypassed ? "on" : "off",
         ],
         [
           t("redis.sharesData"),
@@ -579,7 +583,9 @@ function renderRedis(redis, state) {
           redis.events && redis.subscribed ? "on" : "off",
         ],
         [t("redis.timeout"), `${redis.commandTimeoutMs} ${t("unit.ms")}`],
+        [t("redis.htmlTimeout"), `${redis.htmlCommandTimeoutMs} ${t("unit.ms")}`],
         [t("redis.errors"), String(redis.errors), redis.errors ? "bad" : "on"],
+        [t("redis.htmlErrors"), String(redis.htmlErrors ?? 0), redis.htmlErrors ? "bad" : "on"],
       ]
     : [
         [t("redis.tier"), t("redis.tier.inProcess")],

package/src/config/defaults.js

@@ -297,11 +297,19 @@ export const DEFAULT_REDIS = {
   /** pub/sub üzerinden invalidation yayını. */
   events: true,
   /**
-   * Tek bir komutun en fazla bekletebileceği süre. Önbellek okuması isteği
+   * Veri, yayın ve SCAN için tek komut tavanı. Önbellek okuması isteği
    * bloklayan bir adım: Redis takıldığında render'a düşmek, ağı beklemekten
-   * iyidir.
+   * iyidir. HTML gövdesi bu süreye sığmaz; o bağlantının tavanı
+   * `htmlCommandTimeoutMs`.
    */
   commandTimeoutMs: 200,
+  /**
+   * Yalnızca HTML bağlantısı. ioredis `commandTimeout` istemci genelinde
+   * olduğu için gövde ayrı bağlantıda durur. Verilmezse 2000: uygulama
+   * config'i değiştirmek zorunda kalmasın. Parçalı yazma normalde bunun
+   * altında biter; tavan, gövde beklenmedik büyürse diye durur.
+   */
+  htmlCommandTimeoutMs: 2000,
 };
 
 /**

package/src/config/index.js

@@ -95,7 +95,8 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {boolean} data Veri önbelleği paylaşılsın mı.
  * @property {boolean} storeEncoded Sıkıştırılmış gövdeler de paylaşılsın mı.
  * @property {boolean} events pub/sub invalidation yayını.
- * @property {number} commandTimeoutMs
+ * @property {number} commandTimeoutMs Veri, yayın ve SCAN tavanı.
+ * @property {number} htmlCommandTimeoutMs Yalnızca HTML bağlantısının tavanı.
  */
 
 /**
@@ -340,6 +341,7 @@ function normalizePriority(raw) {
 function normalizeRedis(raw) {
   const source = /** @type {Record<string, any>} */ (raw ?? {});
   const timeout = Number(source.commandTimeoutMs);
+  const htmlTimeout = Number(source.htmlCommandTimeoutMs);
 
   return {
     enabled: source.enabled === true,
@@ -354,6 +356,10 @@ function normalizeRedis(raw) {
       Number.isFinite(timeout) && timeout > 0
         ? Math.floor(timeout)
         : DEFAULT_REDIS.commandTimeoutMs,
+    htmlCommandTimeoutMs:
+      Number.isFinite(htmlTimeout) && htmlTimeout > 0
+        ? Math.floor(htmlTimeout)
+        : DEFAULT_REDIS.htmlCommandTimeoutMs,
   };
 }