jskelet 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -10,6 +10,9 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
+- 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 +76,13 @@ 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.
+  The default stays render-blocking.
 - Dev tools **Server** tab can clear the HTML cache for the open page, every
   HTML entry, or the data cache. Live stats include HTML/data entry counts;
   new endpoints under `devBasePath`: `POST /cache/clear-html`,

package/docs/02-mimari.md

@@ -155,9 +155,17 @@ kapsamadığı için sheet gelince sayfa yeniden akıyordu (bir liste sayfasınd
 ziyarette zaten `immutable` önbellekten geliyor.
 
 Sayfaya özel kurallar için `styles/pages/*.css` + controller `styles: [...]`
-eklenebilir ([08-build.md](./08-build.md)); bunlar da render-blocking basılır
-ama yalnızca ilgili sayfada. Tailwind utility'leri global sheet'te kalır —
-sayfa sheet'inde tam `@import "tailwindcss"` utility çıktısını tekrarlar.
+eklenebilir ([08-build.md](./08-build.md)); bunlar da varsayılan olarak
+render-blocking basılır ama yalnızca ilgili sayfada. Tailwind utility'leri
+global sheet'te kalır — sayfa sheet'inde tam `@import "tailwindcss"` utility
+çıktısını tekrarlar.
+
+Erken boyama isteyen bir layout bu varsayılandan çıkabilir:
+`stylesheets({ blocking: false })` veya şablonda
+`<Stylesheets :blocking="false" />`. Link `media="print"` ile iner, `onload`
+onu `all` yapar; JS kapalıyken `<noscript>` içindeki normal link uygulanır.
+Bu, yukarıdaki CLS takasının tersidir: ilk boyama erken gelir, sheet gelince
+düzen kayabilir.
 
 Aynı mantık ikonlarda da var: her ikon için ayrı istek yerine, build zamanında
 yalnızca kaynakta kullanılan sembollerden bir SVG sprite üretilir. Tüm Phosphor

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

@@ -113,7 +113,7 @@ script ve JSON-LD döngüleri için yerleşikler:
 
 | Etiket | Props | Çıktı |
 | --- | --- | --- |
-| `Stylesheets` | `styles` | `app.css` + sayfa sheet’leri (`data-jskelet-css`) |
+| `Stylesheets` | `styles`, `blocking` | `app.css` + sayfa sheet’leri (`data-jskelet-css`). `blocking` varsayılan `true` |
 | `BodyScripts` | `entries`, `devtools`, `devBasePath` | `main.js`, entry’ler, isteğe bağlı overlay |
 | `JsonLd` | `items` (`structuredData`) | `application/ld+json` script’leri |
 
@@ -181,9 +181,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` render-blocking** ve gerekçesi
+- **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. Build çalışmadıysa `hasAsset` false olur
+  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.
 - **`hasAsset` kontrolleri** build eksikken sayfanın 404 veren dosyaları
   istememesini sağlar (`Stylesheets` / `BodyScripts` içinde).
@@ -432,6 +435,32 @@ icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
   çalışma anında hesaplanan bir çağrı eksik sembole işaret ederse ekranda
   sessizce boşluk kalır ([08-build.md](./08-build.md)).
 
+### `stylesheets(props)`
+
+Layout `<head>` içindeki global `app.css` ve controller `styles` dizisi.
+Doğrudan çağırmak yerine yerleşik etiket kullanılır:
+
+```jsk
+<Stylesheets :styles="styles" />
+<Stylesheets :styles="styles" :blocking="false" />
+```
+
+```js
+stylesheets({ styles: ["home.css"] });
+stylesheets({ styles: ["home.css"], blocking: false });
+```
+
+- `styles` manifest anahtarlarıdır (`"home.css"` → `styles/pages/home.css`).
+  `hasAsset` false olanlar basılmaz.
+- `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.
+  `<noscript>` içindeki ikinci link, JS kapalıyken stillerin print'te
+  kalmamasını sağlar. Inline `onload` çalışmayan bir CSP'de (`script-src`
+  içinde `'unsafe-inline'` veya `script-src-attr` yok) sheet `print`'te kalır.
+- `data-jskelet-css` dev hot-swap'ın doğru linki seçmesi içindir; her iki
+  modda da yazılır.
+
 ### `preloadImage(props)`
 
 ```js

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

@@ -141,8 +141,10 @@ minifikasyon → `writeAsset("app.css", …)`.
   şekilde yavaşlatıyor.
 - **lightningcss opsiyoneldir:** yoksa Tailwind'in kendi çıktısı kullanılır,
   yalnızca birkaç kB daha büyük olur.
-- Global çıktı `app.css`'tir ve layout onu her sayfada render-blocking olarak
-  yükler. Ayrı bir "critical CSS" üretilmemesinin ölçüm gerekçesi
+- Global çıktı `app.css`'tir ve layout onu her sayfada varsayılan olarak
+  render-blocking yükler. `<Stylesheets :blocking="false" />` bu beklemeyi
+  kapatır ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)). Ayrı bir
+  "critical CSS" üretilmemesinin ölçüm gerekçesi
   [02-mimari.md](./02-mimari.md)'de.
 
 ### Sayfa stylesheet'leri (`styles/pages/`)
@@ -166,6 +168,7 @@ kalmalı — dosyada tam `@import "tailwindcss"` utility çıktısını tekrarla
 
 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.
 
 ### `@source` direktifleri zorunludur
 

package/docs/en/02-architecture.md

@@ -160,9 +160,16 @@ both faster and free of CLS; on the second visit it already comes from the
 
 Page-specific rules can use `styles/pages/*.css` plus controller
 `styles: [...]` ([08-build.md](./08-build.md)); those are also render-blocking
-but only on the pages that ask for them. Keep Tailwind utilities in the global
-sheet — a full `@import "tailwindcss"` in a page sheet duplicates utility
-output.
+by default, but only on the pages that ask for them. Keep Tailwind utilities
+in the global sheet — a full `@import "tailwindcss"` in a page sheet
+duplicates utility output.
+
+A layout that wants an earlier first paint can leave this default:
+`stylesheets({ blocking: false })`, or `<Stylesheets :blocking="false" />`
+in the template. The link downloads with `media="print"`, `onload` switches
+it to `all`, and a plain link inside `<noscript>` applies when JS is off.
+That is the reverse of the CLS tradeoff above: first paint arrives sooner,
+and the layout can shift when the sheet arrives.
 
 The same logic applies to icons: instead of a separate request per icon, an SVG
 sprite is produced at build time from only the symbols actually used in the

package/docs/en/04-rendering.md

@@ -180,10 +180,14 @@ Points to watch:
 
 - **`extraHead` comes first.** Delaying resource hints (`preconnect`, LCP
   `preload`) writes straight into LCP.
-- **`<Stylesheets />` emits global `app.css` (render-blocking)** plus controller
-  `styles: [...]`, with the reasoning in
-  [02-architecture.md](./02-architecture.md). If the build has not run,
-  `hasAsset` is false inside the tag and nothing is emitted.
+- **`<Stylesheets />` emits global `app.css` render-blocking by default**,
+  plus controller `styles: [...]`, with the reasoning in
+  [02-architecture.md](./02-architecture.md).
+  `<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
+  when the sheet arrives. If the build has not run, `hasAsset` is false
+  inside the tag and nothing is emitted.
 - **`<BodyScripts />` emits `main.js`, page `entries`, and the
   development-only overlay.** The overlay script exists only when
   `NODE_ENV=development`; it is absent from production output.
@@ -436,6 +440,34 @@ icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
   points at a missing symbol, the screen is silently left blank
   ([08-build.md](./08-build.md)).
 
+### `stylesheets(props)`
+
+Global `app.css` and the controller `styles` list for the layout `<head>`.
+The built-in tag is the usual call site:
+
+```jsk
+<Stylesheets :styles="styles" />
+<Stylesheets :styles="styles" :blocking="false" />
+```
+
+```js
+stylesheets({ styles: ["home.css"] });
+stylesheets({ styles: ["home.css"], blocking: false });
+```
+
+- `styles` are manifest keys (`"home.css"` → `styles/pages/home.css`). Names
+  for which `hasAsset` is false are omitted.
+- `blocking` defaults to `true`:
+  `<link rel="stylesheet" data-jskelet-css="…">`. Only the boolean `false`
+  turns waiting off. The output is `media="print"` and
+  `onload="this.media='all'"`; a non-matching media does not hold painting.
+  A second link inside `<noscript>` keeps styles from staying on `print`
+  when JS is off. Under a CSP that blocks inline handlers (no
+  `'unsafe-inline'` in `script-src`, and no `script-src-attr`) the sheet
+  stays on `print`.
+- `data-jskelet-css` is how dev hot-swap picks the right link; it is written
+  in both modes.
+
 ### `preloadImage(props)`
 
 ```js

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

@@ -145,9 +145,11 @@ The pipeline: PostCSS + `@tailwindcss/postcss` → minification with lightningcs
   noticeably.
 - **lightningcss is optional:** without it, Tailwind's own output is used, and it
   is only a few kB bigger.
-- The global output is `app.css` and the layout loads it render-blocking on every
-  page. The measurement-based reasoning for not producing a separate "critical
-  CSS" is in [02-architecture.md](./02-architecture.md).
+- The global output is `app.css` and the layout loads it render-blocking on
+  every page by default. `<Stylesheets :blocking="false" />` turns that wait
+  off ([04-rendering.md](./04-rendering.md)). The measurement-based reasoning
+  for not producing a separate "critical CSS" is in
+  [02-architecture.md](./02-architecture.md).
 
 ### Page stylesheets (`styles/pages/`)
 
@@ -170,7 +172,8 @@ 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.
+in `styles`; if `hasAsset` is false the tag is omitted. `blocking: false`
+adds `media="print"` and `onload` to those same links.
 
 ### `@source` directives are mandatory
 

package/package.json

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

@@ -10,7 +10,8 @@
  * CLS 0.307) ve aynı ~27 KB her HTML yanıtında tekrar ediyordu. Sıkıştırılmış
  * global sheet'i render-blocking bırakmak hem daha hızlı hem CLS'siz; ikinci
  * ziyarette zaten immutable önbellekten geliyor. Sayfa sheet'leri de
- * render-blocking; yalnızca ilgili sayfada ek maliyet.
+ * 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

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,
   };
 }