jskelet 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -73,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

@@ -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/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/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.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/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/views/helpers/tags.js

@@ -324,28 +324,57 @@ export function toKebab(name) {
  * build yokken 404 link'i istememek için. `.jsk` ifade dilinde `asset()` /
  * `hasAsset()` çağrılamadığı için layout bu etiketi kullanır.
  *
- * @param {{ styles?: string[] }} [props]
+ * `blocking` varsayılan `true`: `<link rel="stylesheet">` boyamayı bekletir.
+ * Ölçümde bu, sheet geç gelince oluşan CLS'ten daha ucuz. `false` yalnızca
+ * açık boolean'dır (`:blocking="false"`); atlamak veya `true` aynı çıktıyı
+ * verir.
+ *
+ * @param {{ styles?: string[], blocking?: boolean }} [props]
  * @returns {string}
  */
 export function stylesheets(props = {}) {
   const styles = Array.isArray(props.styles) ? props.styles : [];
+  const blocking = props.blocking !== false;
   /** @type {string[]} */
   const parts = [];
 
-  if (hasAsset("app.css")) {
-    parts.push(
-      `<link rel="stylesheet" href="${esc(asset("app.css"))}" data-jskelet-css="app.css">`,
-    );
-  }
+  pushStylesheet(parts, "app.css", blocking);
 
   for (const sheet of styles) {
-    if (!sheet || !hasAsset(sheet)) continue;
+    if (!sheet) continue;
+    pushStylesheet(parts, sheet, blocking);
+  }
+
+  return parts.join("\n    ");
+}
+
+/**
+ * Tek bir manifest anahtarı için stylesheet linki.
+ *
+ * `blocking: false` iken `media="print"`: eşleşmeyen media tarayıcıda
+ * render-blocking sayılmaz, indirme boyamayı bekletmez. `onload` sheet
+ * inince `media`'yı `all` yapar. JS kapalıyken `onload` çalışmaz ve link
+ * print'te kalır; `<noscript>` içindeki normal link o yolu kapatır.
+ *
+ * @param {string[]} parts
+ * @param {string} name Manifest anahtarı (`app.css`, `home.css`, …)
+ * @param {boolean} blocking
+ */
+function pushStylesheet(parts, name, blocking) {
+  if (!hasAsset(name)) return;
+
+  const href = esc(asset(name));
+  const id = esc(name);
+  if (blocking) {
     parts.push(
-      `<link rel="stylesheet" href="${esc(asset(sheet))}" data-jskelet-css="${esc(sheet)}">`,
+      `<link rel="stylesheet" href="${href}" data-jskelet-css="${id}">`,
     );
+    return;
   }
 
-  return parts.join("\n    ");
+  parts.push(
+    `<link rel="stylesheet" href="${href}" media="print" onload="this.media='all'" data-jskelet-css="${id}">\n    <noscript><link rel="stylesheet" href="${href}" data-jskelet-css="${id}"></noscript>`,
+  );
 }
 
 /**

package/types/views/helpers/tags.d.ts

@@ -102,11 +102,17 @@ export declare function toKebab(name: string): string;
  * build yokken 404 link'i istememek için. `.jsk` ifade dilinde `asset()` /
  * `hasAsset()` çağrılamadığı için layout bu etiketi kullanır.
  *
- * @param {{ styles?: string[] }} [props]
+ * `blocking` varsayılan `true`: `<link rel="stylesheet">` boyamayı bekletir.
+ * Ölçümde bu, sheet geç gelince oluşan CLS'ten daha ucuz. `false` yalnızca
+ * açık boolean'dır (`:blocking="false"`); atlamak veya `true` aynı çıktıyı
+ * verir.
+ *
+ * @param {{ styles?: string[], blocking?: boolean }} [props]
  * @returns {string}
  */
 export declare function stylesheets(props?: {
     styles?: string[];
+    blocking?: boolean;
 }): string;
 /**
  * Layout gövde sonu script'leri: `main.js`, controller `entries`, isteğe