jskelet 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -26,9 +26,46 @@ one is listed under a **Breaking** heading.
   variant URLs once at load time.
 - `scripts/measure-ssr.mjs` microbench for fixture `renderView` /
   `renderPage` and live cache MISS/HIT timings against a running app.
+- HTML cache awaits brotli on write so the MISS response can reuse it;
+  `rememberHtmlEncoding` updates the byte budget by delta instead of
+  rescanning the store. Short negative cache skips empty L2 (Redis/disk)
+  lookups after a miss.
+- Data cache early-refreshes near TTL (same lead formula as HTML) and skips
+  repeated empty L2 reads the same way; `produceMs` is stored on entries.
+- Image optimizer coalesces concurrent work for the same `url+w+q` and caches
+  DNS safety checks for 60s.
+- Disk/Redis L2 decode uses async brotli (no sync decompress on the event
+  loop). `cache()` skips `JSON.stringify` for a single primitive argument.
+- `preconnectHints()` adds `build.assets.prefix` origin automatically. Build
+  runs Fonts and Icon sprite in parallel; precompress writes `.br`/`.gz` in
+  parallel per file.
+- Cold SSR without prewarm: `warmRenderEngine()` runs before listen; page
+  `.jsk` templates load lazily (layout + `components/*` stay eager); production
+  `ensureTemplatesCompiled` returns on manifest without walking sources.
+- L2 read races a 50ms budget then produces locally; Redis `storeEncoded`
+  defaults to on.
+- `renderPage` runs the body with `page.metadata` in parallel with the
+  `metadata` hook + `layoutContext` chain.
+- `sendHtml` always negotiates brotli/gzip for HTML (including
+  `fragment` / `private`), instead of relying on compression middleware.
+- Transient upstream `notFound()` defaults to an immediate 503 with
+  background retry (`cache().transientRetry.background`; set `false` for the
+  old sync loop). `warmRenderEngine` / `resetRenderEngine` are exported.
+
+### Breaking
+
+- Redis `storeEncoded` defaults to `true` (was `false`). Opt out with
+  `cache().redis.storeEncoded: false` if L2 size must stay minimal.
+- Transient retry no longer delays the visitor by default
+  (`background: true`). Set `cache().transientRetry.background: false` to
+  wait for sync retries before responding.
 
 ### Fixed
 
+- `hydrate()` mounts zero-box hosts (`hidden` / no layout box) through
+  `mountWhenReady()` instead of calling `mountIsland()` immediately, so
+  `data-island-idle` on a hidden host still waits for `load` plus idle time.
+  `data-island-eager` is unchanged (mounts right away).
 - S3 PutObject uses path-style URLs for bucket names that contain dots
   (e.g. `static.investvio.dev`). Virtual-hosted
   `bucket.s3.region.amazonaws.com` fails TLS because the cert only covers
@@ -36,6 +73,10 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- `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

@@ -15,17 +15,18 @@ route(controller)
  └─ produce()
      ├─ controller(ctx)  → sayfa tanımı
      └─ renderPage(page)
-         ├─ hooks.metadata(page) + page.metadata      → metadata
          ├─ Promise.all([
-         │     renderView(page.view, { …data, metadata }),   → body
-         │     hooks.layoutContext({ pathname, metadata }),  → context
+         │     renderView(page.view, { …data, page.metadata }),  → body
+         │     hooks.metadata(page) + page.metadata              → metadata
+         │       └─ hooks.layoutContext({ pathname, metadata })  → context
          │   ])
          └─ layout (.jsk derlenmiş veya .ejs)  → tam HTML
 ```
 
-Layout bağlamı ve gövde **paralel** üretilir. Sebebi ölçümden geliyor:
-navigasyon çoğu projede upstream'den geliyor ve gövde render'ıyla sırayla
-beklemek her sayfaya gereksiz gecikme ekliyor.
+Gövde, `hooks.metadata` + `layoutContext` zinciriyle **paralel** üretilir.
+Şablon locals'ında `metadata` önce controller'ın `page.metadata`'sıdır; layout
+birleşik (hook + sayfa) metadata'yı alır. Navigasyon çoğu projede upstream'den
+gelir — gövdeyi metadata zincirinin bitmesini bekletmek her MISS'e gecikme ekler.
 
 ## `.jsk` — build-time derlenmiş şablonlar
 
@@ -112,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 |
 
@@ -180,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).
@@ -431,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/05-islands.md

@@ -108,10 +108,14 @@ ve doğrudan boş zamana kaydırılır.
 `hidden` bir drawer ya da dialog'un düzen kutusu yoktur ve
 `IntersectionObserver` onu **asla** bildirmez. Bu yüzden `hydrate()` ölçümleri
 tek seferde okur (`getClientRects().length > 0`) ve kutusu olmayan elementleri
-gözlemciye vermek yerine doğrudan bağlar. Ölçümlerin tek seferde okunması da
-bilinçli: araya yazma girmediği için tek reflow olur.
-
-Pratik sonucu: bir modal'ı `hidden` başlatabilirsiniz, island'ı yine bağlanır.
+gözlemciye vermek yerine `mountWhenReady()` ile bağlar — yani
+`data-island-idle` gizli host'ta da geçerlidir (`load` + boş zaman); idle
+olmayanlar boş zamana kaydırılır. Ölçümlerin tek seferde okunması bilinçli:
+araya yazma girmediği için tek reflow olur. `data-island-eager` hâlâ hemen
+bağlanır.
+
+Pratik sonucu: bir modal'ı `hidden` başlatabilirsiniz, island'ı yine bağlanır;
+ağır bir gizli host için `data-island-idle` LCP ile yarışmayı keser.
 
 ## `client/` dizini
 

package/docs/06-cache.md

@@ -560,39 +560,40 @@ 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ı
-varsa `notFound()` 404 olarak servis edilmez. Sırayla:
+varsa `notFound()` 404 olarak servis edilmez. Varsayılan (`background: true`):
 
-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.
+1. Ziyaretçiye hemen önbelleğe girmeyen bir `503` + `Retry-After` gider.
+2. Aynı yol arka planda 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. Başarılı olursa
+   sonraki istek L1/L2 HIT alır.
+3. `background: false` eski senkron döngüyü açar: önce bekle + dene, başarısızsa
+   503; başarılıysa ziyaretçi gerçek içeriği görür.
 
 | Render sırasında | `notFound()` sonucu |
 | --- | --- |
-| Geçici hata var (`429`, `5xx`, ağ hatası) | Tekrar dene → başarılıysa sayfa; hâlâ olmuyorsa `503`, `Retry-After: 30`, `no-store` |
+| Geçici hata + `background: true` (varsayılan) | Hemen `503`, `Retry-After: 30`, `no-store`; retry arka planda |
+| Geçici hata + `background: false` | Tekrar dene → başarılıysa sayfa; değilse `503` |
 | 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ı:
 
 ```
-[render] /haber/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /haber/x returned notFound() while upstream is failing (429 /api/...), retrying in background (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.
+gelir (senkron retry veya sonraki istek), 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 },
+  transientRetry: { attempts: 2, delayMs: 500, background: true },
 }
 ```
 
@@ -886,9 +887,10 @@ bir sonraki yazışta siler. `clearHtmlCache()` ve invalidation dosyayı da dü
   bile geçerli olan bu kural paylaşımlı kademede daha da kritik: sızması, bir
   kullanıcının HTML'ini tüm kümeye servis etmek olur. `degraded` render ve 200
   dışındaki durum kodları da paylaşılmaz.
-- **Sıkıştırılmış gövdeler varsayılan olarak yerel kalır.** `storeEncoded: true`
-  ile açılabilir, ama girdi başına boyutu iki-üç katına çıkarır; brotli'yi
-  yeniden üretmek çoğu zaman Redis'ten indirmekten ucuzdur.
+- **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.
 - **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

package/docs/07-yapilandirma.md

@@ -772,7 +772,7 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 **Tip:**
 `() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: false | object }` —
 **Varsayılan:**
-`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (veya `prewarm: false` → `mode: "off"`)
+`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300, background: true }, upstream: { rate: 0 }, redis: { enabled: false, storeEncoded: true }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (veya `prewarm: false` → `mode: "off"`)
 
 ### `cache().html`
 
@@ -902,13 +902,14 @@ kaydedilecek bir şey yok; kapatmak bağlam kurma maliyetini de kaldırır.
 
 ### `cache().transientRetry`
 
-**Tip:** `{ attempts?: number, delayMs?: number } | false` —
-**Varsayılan:** `{ attempts: 1, delayMs: 300 }`
+**Tip:** `{ attempts?: number, delayMs?: number, background?: boolean } | false` —
+**Varsayılan:** `{ attempts: 1, delayMs: 300, background: true }`
 
 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).
+denenir. Amaç var olan bir sayfanın 404'e dönüşmemesi. `background: true`
+(varsayılan) ziyaretçiye hemen 503 verir ve retry'yi arka planda koşturur;
+`false` eski senkron döngüyü açar (önce bekle + dene, sonra yanıt). `false` ya
+da `attempts: 0` tekrarı kapatır. Ayrıntı: [06-cache.md](./06-cache.md).
 
 ### `cache().upstream`
 
@@ -959,7 +960,7 @@ 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` | `false` | 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 de paylaşılsın mı; girdi başına boyutu iki-üç katına çıkarır |
 | `events` | `boolean` | `true` | pub/sub üzerinden invalidation yayını |
 | `commandTimeoutMs` | `number` | `200` | Tek bir komutun en fazla bekletebileceği süre |
 

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

@@ -16,17 +16,19 @@ route(controller)
  └─ produce()
      ├─ controller(ctx)  → page definition
      └─ renderPage(page)
-         ├─ hooks.metadata(page) + page.metadata      → metadata
          ├─ Promise.all([
-         │     renderView(page.view, { …data, metadata }),   → body
-         │     hooks.layoutContext({ pathname, metadata }),  → context
+         │     renderView(page.view, { …data, page.metadata }),  → body
+         │     hooks.metadata(page) + page.metadata              → metadata
+         │       └─ hooks.layoutContext({ pathname, metadata })  → context
          │   ])
          └─ layout (.jsk compiled or .ejs)  → full HTML
 ```
 
-The layout context and the body are produced **in parallel**. The reason comes
-from measurement: in most projects navigation comes from upstream, and waiting
-for it in sequence with the body render adds needless latency to every page.
+The body runs **in parallel** with the `hooks.metadata` + `layoutContext`
+chain. Template locals see the controller's `page.metadata` first; the layout
+receives the merged (hook + page) metadata. Navigation often comes from
+upstream — waiting for the metadata chain before starting the body adds latency
+to every MISS.
 
 ## `.jsk` — build-time compiled templates
 
@@ -178,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.
@@ -434,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/05-islands.md

@@ -111,12 +111,16 @@ skipped and it is deferred straight to idle time.
 
 A `hidden` drawer or dialog has no layout box, and `IntersectionObserver`
 **never** reports it. That is why `hydrate()` reads its measurements in one go
-(`getClientRects().length > 0`) and mounts elements without a box directly
-instead of handing them to the observer. Reading the measurements in one go is
-deliberate too: since no write comes in between there is only a single reflow.
+(`getClientRects().length > 0`) and mounts zero-box elements via
+`mountWhenReady()` instead of handing them to the observer — so
+`data-island-idle` still applies on a hidden host (`load` plus idle time);
+non-idle hosts are deferred to idle time. Reading the measurements in one go
+is deliberate: since no write comes in between there is only a single reflow.
+`data-island-eager` still mounts immediately.
 
 The practical consequence: you can start a modal as `hidden` and its island
-will still mount.
+will still mount; use `data-island-idle` on a heavy hidden host so it does not
+compete with LCP.
 
 ## The `client/` directory
 

package/docs/en/06-caching.md

@@ -570,39 +570,41 @@ 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
-happened during the render, `notFound()` is not served as a 404. In order:
+happened during the render, `notFound()` is not served as a 404. Default
+(`background: true`):
 
-1. The page is **retried** after a short delay (once by default, after 300 ms).
+1. The visitor gets an immediate uncached `503` + `Retry-After`.
+2. The same path is retried in the background (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.
+   the first round's failure nor its memoized empty answers affect it. On
+   success the next request is an L1/L2 HIT.
+3. `background: false` restores the old sync loop: wait + retry first; on
+   success the visitor sees real content, otherwise a 503.
 
 | During the render | Result of `notFound()` |
 | --- | --- |
-| A transient failure exists (`429`, `5xx`, network error) | Retry → the page if it succeeds; otherwise `503`, `Retry-After: 30`, `no-store` |
+| Transient failure + `background: true` (default) | Immediate `503`, `Retry-After: 30`, `no-store`; retry in background |
+| Transient failure + `background: false` | Retry → the page if it succeeds; otherwise `503` |
 | 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:
 
 ```
-[render] /news/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /news/x returned notFound() while upstream is failing (429 /api/...), retrying in background (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".
+So **an existing page never turns into a 404**: either the real content arrives
+(sync retry or the next request), 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 },
+  transientRetry: { attempts: 2, delayMs: 500, background: true },
 }
 ```
 
@@ -905,9 +907,9 @@ file too.
   rule already holds in a single process, but it matters far more in a shared
   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 stay local by default.** `storeEncoded: true` turns this
-  on, but it doubles or triples the size per entry; recomputing brotli is
-  usually cheaper than downloading it from Redis.
+- **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.
 - **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

package/docs/en/07-configuration.md

@@ -786,7 +786,7 @@ Details: [03-routing.md](./03-routing.md).
 **Type:**
 `() => { html?: Record<string, number>, staleWhileRevalidate?: number, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: false | object }` —
 **Default:**
-`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (or `prewarm: false` → `mode: "off"`)
+`{ html: {}, staleWhileRevalidate: 60, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300, background: true }, upstream: { rate: 0 }, redis: { enabled: false, storeEncoded: true }, prewarm: { enabled: true, mode: "classic", max: 400, intervalSeconds: 0, origins: [] } }` (or `prewarm: false` → `mode: "off"`)
 
 ### `cache().html`
 
@@ -920,13 +920,15 @@ setting up the context.
 
 ### `cache().transientRetry`
 
-**Type:** `{ attempts?: number, delayMs?: number } | false` —
-**Default:** `{ attempts: 1, delayMs: 300 }`
+**Type:** `{ attempts?: number, delayMs?: number, background?: boolean } | false` —
+**Default:** `{ attempts: 1, delayMs: 300, background: true }`
 
 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).
+a 404. `background: true` (default) returns 503 immediately and runs the retry
+in the background; `false` restores the old sync loop (wait + retry, then
+respond). `false` or `attempts: 0` disables the retry. Details:
+[06-caching.md](./06-caching.md).
 
 ### `cache().upstream`
 
@@ -977,7 +979,7 @@ 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` | `false` | Whether brotli/gzip bodies are shared too; doubles or triples the size per entry |
+| `storeEncoded` | `boolean` | `true` | Whether brotli/gzip bodies are shared too; doubles or triples the size per entry |
 | `events` | `boolean` | `true` | Invalidation broadcast over pub/sub |
 | `commandTimeoutMs` | `number` | `200` | At most how long a single command may block |
 

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.1",
+  "version": "0.7.3",
   "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/build.mjs

@@ -68,14 +68,29 @@ async function task(label, run) {
   }
 }
 
-if (config.fonts?.length) {
-  const { copyFonts } = await import("./tasks/fonts.mjs");
-  Object.assign(manifest, await task("Fonts", () => copyFonts(config)));
-}
-
-if (config.icons !== false) {
-  const { buildIconSprite } = await import("./tasks/icons.mjs");
-  Object.assign(manifest, await task("Icon sprite", () => buildIconSprite(config)));
+// Fonts ve icon sprite birbirine bağlı değil — paralel.
+{
+  /** @type {Promise<Record<string, string> | void>[]} */
+  const parallel = [];
+  if (config.fonts?.length) {
+    parallel.push(
+      (async () => {
+        const { copyFonts } = await import("./tasks/fonts.mjs");
+        return task("Fonts", () => copyFonts(config));
+      })(),
+    );
+  }
+  if (config.icons !== false) {
+    parallel.push(
+      (async () => {
+        const { buildIconSprite } = await import("./tasks/icons.mjs");
+        return task("Icon sprite", () => buildIconSprite(config));
+      })(),
+    );
+  }
+  for (const part of await Promise.all(parallel)) {
+    if (part) Object.assign(manifest, part);
+  }
 }
 
 if (fs.existsSync(config.dirs.styles)) {