jskelet 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -10,6 +10,10 @@ 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.

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/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/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.4",
+  "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/views/helpers/tags.js

@@ -320,9 +320,11 @@ export function toKebab(name) {
 }
 
 /**
- * Layout `<head>` stylesheet'leri. `hasAsset` false olanları basmaz —
- * build yokken 404 link'i istememek için. `.jsk` ifade dilinde `asset()` /
- * `hasAsset()` çağrılamadığı için layout bu etiketi kullanır.
+ * Layout `<head>` stylesheet'leri. Sayfa sheet'i varsa global CSS'i zaten
+ * taşıyan bu birleşik varlık basılır; yoksa `app.css` kullanılır. `hasAsset`
+ * false olanları basmaz — build yokken 404 link'i istememek için. `.jsk`
+ * ifade dilinde `asset()` / `hasAsset()` çağrılamadığı için layout bu etiketi
+ * kullanır.
  *
  * `blocking` varsayılan `true`: `<link rel="stylesheet">` boyamayı bekletir.
  * Ölçümde bu, sheet geç gelince oluşan CLS'ten daha ucuz. `false` yalnızca
@@ -337,11 +339,14 @@ export function stylesheets(props = {}) {
   const blocking = props.blocking !== false;
   /** @type {string[]} */
   const parts = [];
+  const available = [...new Set(styles.filter((sheet) => sheet && hasAsset(sheet)))];
 
-  pushStylesheet(parts, "app.css", blocking);
-
-  for (const sheet of styles) {
-    if (!sheet) continue;
+  // Sayfa çıktıları app.css'i içerir. İki linki birden basmak utility
+  // katmanını iki ağ yanıtında uygulayıp aradaki cascade durumunu boyatır.
+  if (available.length === 0) {
+    pushStylesheet(parts, "app.css", blocking);
+  }
+  for (const sheet of available) {
     pushStylesheet(parts, sheet, blocking);
   }
 

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

@@ -98,9 +98,11 @@ export declare function csrfField(): string;
  */
 export declare function toKebab(name: string): string;
 /**
- * Layout `<head>` stylesheet'leri. `hasAsset` false olanları basmaz —
- * build yokken 404 link'i istememek için. `.jsk` ifade dilinde `asset()` /
- * `hasAsset()` çağrılamadığı için layout bu etiketi kullanır.
+ * Layout `<head>` stylesheet'leri. Sayfa sheet'i varsa global CSS'i zaten
+ * taşıyan bu birleşik varlık basılır; yoksa `app.css` kullanılır. `hasAsset`
+ * false olanları basmaz — build yokken 404 link'i istememek için. `.jsk`
+ * ifade dilinde `asset()` / `hasAsset()` çağrılamadığı için layout bu etiketi
+ * kullanır.
  *
  * `blocking` varsayılan `true`: `<link rel="stylesheet">` boyamayı bekletir.
  * Ölçümde bu, sheet geç gelince oluşan CLS'ten daha ucuz. `false` yalnızca