jskelet 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -27,6 +27,29 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- VS Code / Cursor extension skeleton under `extensions/vscode-jsk`: `.jsk`
+  language id, TextMate highlighting (`{{ }}` / `{#if}` / `{#each}` /
+  components), language config, and snippets. Install from that folder or
+  launch **JSK: Extension** from the repo root. Bound attrs on HTML tags
+  (`:src="… + '/path'"`) highlight nested single-quoted strings.
+- Compile-time known components are discovered from **named exports** in
+  `views/components/**/*.js` (plus `.jsk` component files), not from the file
+  basename — so `<SectionHead />` resolves when `sectionHead` lives in
+  `ui.js` without a stub re-export. Docs cover the `.jsk` template-vs-component
+  boundary and a `{ items, error }` loader / `LoadErrorState` pattern so
+  upstream failures are not mistaken for empty data.
+- Build-time `.jsk` templates: declarative HTML-like syntax compiled to ESM
+  render modules under `.jskelet/templates/` (no request-time parse, `eval`, or
+  `new Function`). Coexists with EJS; compiled `.jsk` wins when both exist.
+  Syntax: `{{ }}` / `{{{ }}}`, `{#if}` / `{#each}` / `{#include}`, PascalCase
+  components (`:prop` bindings), built-ins `Link` / `Image` / `Icon` /
+  `CsrfField` / `PreloadImage`.
+- Feature-first conventions: `paths.features` / `paths.shared`, multi-root
+  views and components, `features/<name>/index.js` route registration after
+  `routes/`. CLI: `jskelet generate feature|page|island`. `jskelet init`
+  scaffolds `.jsk` pages.
+- Template compile step in `jskelet build`; icon scan and Tailwind docs cover
+  `.jsk` / `features` / `shared`. Bench: `node scripts/bench-templates.mjs`.
 - Top-level `logs` config for persistent sinks: daily NDJSON files
   (`logs.file`) and batched S3 PutObject (`logs.s3`) with embedded SigV4 — no
   `@aws-sdk` dependency. `kinds` selects `http` / `event` / `error`; `console`
@@ -113,6 +136,17 @@ one is listed under a **Breaking** heading.
   variant of a path, which is the right default for a webhook but wrong when you
   want `/list?page=2` gone and `/list?page=3` left hot.
 
+### Changed
+
+- Duplicate component named exports (or the same PascalCase tag in two files)
+  now **fail** at build and at server startup instead of warning and letting
+  the second definition win. Overwriting `components/index.js` barrel exports
+  remains allowed.
+- `examples/minimal` pages moved to `.jsk`; adds `features/demo` as a
+  co-located route + view sample.
+- Marketing compare/FAQ copy no longer claims targeted invalidation is missing;
+  it points at `invalidateHtmlCache()` (and Redis pub/sub for multi-instance).
+
 - An adaptive per-host rate limit for upstream calls, `cache().upstream`. It sits
   in the `fetch` wrapper rather than in the prewarm pass, because what spends the
   quota is the API call, not the page: one render may make one call or twenty, so

package/bin/jskelet.mjs

@@ -1,11 +1,12 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * JSkelet CLI.
  *
  *   jskelet dev      build watch + sunucu, canlı yenileme, dev overlay
  *   jskelet build    tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
  *   jskelet start    prod sunucu (build eksikse önce üretir)
- *   jskelet init     bulunduğun dizine minimal iskelet kurar
+ *   jskelet init       bulunduğun dizine minimal iskelet kurar
+ *   jskelet generate   feature / page / island iskeleti
  *
  * Alt komutlar ayrı süreçlerde çalışır. Sebep: `dev` iki uzun ömürlü süreci
  * (build watch + sunucu) yönetiyor ve sunucunun ESM resolve hook'larına
@@ -90,14 +91,26 @@ switch (command) {
     break;
   }
 
+  case "generate": {
+    const { generate } = await import("../src/generate.mjs");
+    try {
+      await generate(process.cwd(), rest);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+      process.exit(1);
+    }
+    break;
+  }
+
   default: {
     const known = command ? `unknown command: ${command}\n\n` : "";
     process.stderr.write(
-      `${known}usage: jskelet <dev|build|start|init>\n\n` +
-        "  dev     build watch + server (live reload, dev overlay)\n" +
-        "  build   production build\n" +
-        "  start   production server\n" +
-        "  init    scaffold a minimal skeleton in the current directory\n",
+      `${known}usage: jskelet <dev|build|start|init|generate>\n\n` +
+        "  dev       build watch + server (live reload, dev overlay)\n" +
+        "  build     production build\n" +
+        "  start     production server\n" +
+        "  init      scaffold a minimal skeleton in the current directory\n" +
+        "  generate  scaffold feature | page | island\n",
     );
     process.exit(command ? 1 : 0);
   }

package/docs/02-mimari.md

@@ -25,6 +25,9 @@ JSkelet bu gözlemi mimarinin merkezine alır:
    olarak, kendi modülüyle, kendi zamanında bağlanır.
 3. **Sayfa üretimi önbelleklenir.** Aynı HTML'i her istekte yeniden üretmenin
    anlamı yok; TTL'li bir bellek önbelleği ISR'nin yerini tutar.
+4. **Şablonlar build-time derlenir (`.jsk`).** İstek anında parse yok; EJS
+   legacy olarak yan yana kalır. Feature'lar `features/<name>/{server,views,client}`
+   altında toplanabilir — URL kaydı yine açıktır.
 
 ## Bir isteğin yolu
 

package/docs/03-routing.md

@@ -63,9 +63,25 @@ export default {
 };
 ```
 
-**2. Liste yoksa `routes/` dizini alfabetik taranır.** Tarama özyinelemelidir
-(alt dizinler de dâhil), yalnızca `.js` ve `.mjs` dosyaları alınır ve adı `_`
-ile başlayan dosyalar atlanır (`_helpers.js` gibi paylaşılan modüller için).
+**2. Liste yoksa `routes/` dizini alfabetik taranır**, ardından her
+`features/<name>/index.js` (veya `.mjs`) alfabetik eklenir. Tarama
+özyinelemelidir (alt dizinler de dâhil), yalnızca `.js` ve `.mjs` dosyaları
+alınır ve adı `_` ile başlayan dosyalar atlanır (`_helpers.js` gibi paylaşılan
+modüller için).
+
+Feature-first düzen zorunlu değildir; bir feature örneği:
+
+```
+features/piyasalar/
+  index.js          # register(app, api) — URL'ler açıkça yazılır
+  server/
+  views/pages/…     # .jsk veya .ejs
+  views/components/
+  client/           # island'lar; client/entries'ten registerAll
+```
+
+`jskelet generate feature|page|island` iskelet üretir. Filesystem URL routing
+yoktur.
 
 Bu durumda dosya adlarına sayısal önek verin:
 

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

@@ -20,17 +20,96 @@ route(controller)
          │     renderView(page.view, { …data, metadata }),   → body
          │     hooks.layoutContext({ pathname, metadata }),  → context
          │   ])
-         └─ layout.ejs render  → tam HTML
+         └─ 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.
 
-## EJS motoru
+## `.jsk` — build-time derlenmiş şablonlar
 
-Motor ilk render'da bir kez kurulur; bileşen taraması dosya sistemine
-dokunduğu için her istekte yapılamaz ve config yüklenmeden hesaplanamaz.
+Yeni uygulamalarda varsayılan şablon biçimi `.jsk`'dir. Build sırasında
+(`.jskelet/templates/*.mjs`) normal ESM modüllerine çevrilir; **istek anında
+parse / `eval` / `new Function` yoktur**. Production yolu:
+
+```
+controller data → import edilmiş render(data, helpers) → HTML
+```
+
+### Sözdizimi özeti
+
+```html
+<section class="wrapper">
+  <h1>{{ title }}</h1>
+  <div>{{{ trustedHtml }}}</div>
+
+  {#if items.length}
+    <List :items="items" />
+  {#else}
+    <p>Boş</p>
+  {/if}
+
+  {#each items as item, i}
+    <li data-i="{{ i }}">{{ item }}</li>
+  {/each}
+
+  <Link href="/" text="Home" />
+  <div data-island="counter" data-island-props='{"start":0}'></div>
+</section>
+```
+
+| Özellik | Yazım |
+| --- | --- |
+| Kaçışlı metin | `{{ expr }}` |
+| Ham HTML | `{{{ expr }}}` |
+| Koşul | `{#if expr}` … `{#else}` … `{/if}` |
+| Döngü | `{#each list as item}` veya `as item, i` |
+| Include | `{#include "partials/header"}` (derlenmiş `.jsk`) |
+| Bileşen | PascalCase etiket; `:prop="expr"`, `prop="literal"`, boolean `disabled` |
+| Yerleşikler | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage` |
+
+İfade dili kasıtlı olarak dardır (erişim, karşılaştırma, ternary, `.length`).
+Atama, object literal ve rastgele fonksiyon çağrısı yok — mantık controller
+veya JS bileşende kalır.
+
+#### Şablon mu, bileşen mi?
+
+EJS’den geçerken sınırı erken çizmek işe yarar:
+
+| Burada kalsın (`.jsk`) | JS bileşene taşı |
+| --- | --- |
+| Metin, koşul, liste, prop bağlama | Fonksiyon çağrısı, nesne üretimi, biçimlendirme |
+| Yerleşik etiketler (`Link`, `Image`, …) | Birden fazla yardımcıdan HTML birleştirme |
+| Controller’dan gelen hazır veri | Upstream / hata ayırt eden UI (`LoadErrorState`) |
+
+Şablonda `format(x)` veya `{ a: 1 }` yazılamıyorsa bu bir eksik değil: o iş
+`views/components/*.js` veya controller’ındır. Karmaşık sayfalar bileşene
+kaçıyorsa ifade dilini genişletmek yerine bileşen sınırını net tutmak tercih
+edilir.
+
+### Editör desteği
+
+Repo içinde `extensions/vscode-jsk` VS Code / Cursor uzantısı vardır: sözdizimi
+renklendirme, dil yapılandırması ve snippet'ler. Yerel kurulum:
+
+```bash
+code --install-extension extensions/vscode-jsk
+```
+
+Ayrıntılar uzantı README'sinde.
+
+### EJS ile birlikte yaşam
+
+Aynı `view` id için derlenmiş `.jsk` varsa o kullanılır; yoksa `.ejs` dosyası
+EJS ile render edilir. Mevcut uygulamalar değişmeden çalışır. `jskelet init`
+yeni iskeleti `.jsk` ile kurar.
+
+## EJS motoru (legacy)
+
+EJS hâlâ desteklenir. Motor ilk render'da bir kez kurulur; bileşen taraması
+dosya sistemine dokunduğu için her istekte yapılamaz ve config yüklenmeden
+hesaplanamaz.
 
 Ayarlar:
 
@@ -52,8 +131,9 @@ normal akışta gerekmez.
 1. `jskelet.config.mjs` → `layout` verilmişse o kullanılır. Yol, **views
    dizininin üst dizinine** göre çözülür: `views` varsayılansa
    `layout: "views/ozel.ejs"` → `<root>/views/ozel.ejs`.
-2. Verilmemişse `views/layout.ejs` varsa o kullanılır.
-3. O da yoksa framework'ün kendi minimal layout'u kullanılır
+2. Verilmemişse `views/layout.jsk` (derlenmiş) varsa o kullanılır.
+3. Yoksa `views/layout.ejs` varsa o kullanılır.
+4. O da yoksa framework'ün kendi minimal layout'u kullanılır
    (`node_modules/jskelet/src/templates/layout.ejs`, ayrıca
    `jskelet/layout` belirteciyle de erişilebilir).
 
@@ -189,13 +269,18 @@ Kurallar:
 
 - Tarama özyinelemelidir; alt dizinler de kapsanır.
 - `default` export'lar yok sayılır — yalnızca named export'lar kaydedilir.
+- Compile-time bilinen bileşen listesi **dosya adından değil**, kaynak
+  metindeki named export'lardan okunur. `ui.js` içindeki `sectionHead` →
+  şablonda `<SectionHead />` (runtime zaten camelCase export'a PascalCase
+  alias ekler). Dosya adına göre stub re-export eklemeye gerek yoktur.
 - `loader.js` ve `index.js` bileşen dosyası sayılmaz.
 - `views/components/index.js` varsa **barrel** olarak, en düşük öncelikle en
   önce yüklenir. Tek amacı `lib/` yeniden ihraçlarını şablon local'i yapmak;
   bileşenlerin kendi dosyaları sonradan gelip sessizce üzerine yazar.
-- Aynı ad iki farklı bileşen dosyasında tanımlıysa uyarı basılır ve **ikincisi
-  kazanır**: `[components] 'card' is defined twice: a.js and b.js — the second
-  one wins.`
+- Aynı ad (veya aynı PascalCase etiket) iki farklı bileşen dosyasında
+  tanımlıysa **uyarı değil hata**: build ve sunucu açılışı
+  `Component 'card' is defined twice: …` ile durur. Barrel üzerine yazmak
+  bilinçli istisnadır.
 - `views/components` dizini yoksa bileşen kaydı boş kalır; bileşen kullanmayan
   bir proje de çalışır.
 

package/docs/06-cache.md

@@ -380,6 +380,68 @@ export async function apiGet(path) {
 }
 ```
 
+### Loader sözleşmesi: boş liste ≠ hata
+
+`catch → []` (veya `null`) ile yutulan bir upstream hatası, yanlış mapping ile
+aynı görünür: boş UI. Rate limit ve geçici hatalar logda doğru yönde
+işaretlense bile ziyaretçi “veri yok” sanır. Widget loader’ları sessiz
+`[]`’ye gömülmek yerine sonucu ayırsın:
+
+```js
+/**
+ * @returns {Promise<{ items: object[], error: Error | null }>}
+ */
+export async function loadTickerItems() {
+  try {
+    const items = await apiGet("/ticker");
+    if (!items) {
+      return { items: [], error: new Error("Upstream returned no data") };
+    }
+    return { items, error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+```
+
+Uygulama tarafında ortak bir `LoadErrorState` bileşeni (veya eşdeğeri) bu
+`error` alanını göstersin; her widget kendi boş hâline düşmesin:
+
+```js
+// views/components/load-error-state.js
+import { esc } from "jskelet/html";
+
+/**
+ * @param {{ message?: string, title?: string }} props
+ * @returns {string}
+ */
+export function LoadErrorState({ message, title = "Veri yüklenemedi" }) {
+  return `<div role="alert" data-load-error class="…">
+    <p>${esc(title)}</p>
+    ${message ? `<p>${esc(message)}</p>` : ""}
+  </div>`;
+}
+```
+
+```html
+{#if error}
+  <LoadErrorState :message="error.message" />
+{#else if items.length}
+  {#each items as item}
+    …
+  {/each}
+{#else}
+  <p>Kayıt yok</p>
+{/if}
+```
+
+Framework markaya özel UI taşımaz; `LoadErrorState` uygulama bileşenidir.
+Önemli olan sözleşme: `{ items, error }` (veya eşdeğeri) ve hata ile “gerçekten
+boş”un şablonda ayrı kolları.
+
 ### Geçici ve kalıcı hata ayrımı
 
 | Durum | Sayılır | Sonuç |

package/docs/07-yapilandirma.md

@@ -150,12 +150,14 @@ göre çözülür ve içeride mutlak yola çevrilir.
 
 | Anahtar | Varsayılan | İçeriği |
 | --- | --- | --- |
-| `views` | `"views"` | EJS layout, sayfalar, bileşenler |
+| `views` | `"views"` | Layout, sayfalar, bileşenler (klasik kök; `.jsk` / `.ejs`) |
+| `features` | `"features"` | Feature-first dilimler (`<name>/{server,views,client}`) |
+| `shared` | `"shared"` | Özellikler arası paylaşılan server/views/client |
 | `public` | `"public"` | Statik dosyalar; build çıktısı da buraya yazılır |
 | `client` | `"client"` | Island runtime kaynakları ve entry'ler |
 | `routes` | `"routes"` | Route modülleri |
 | `styles` | `"styles/globals.css"` | Tailwind/PostCSS giriş **dosyası** |
-| `generated` | `".jskelet"` | `manifest.json`, `metafile.json`, `images.json` |
+| `generated` | `".jskelet"` | `manifest.json`, `templates/`, `metafile.json`, `images.json` |
 
 `styles` bir dosya yolu olduğu hâlde aynı çözümlemeden geçer; ayrı bir alan
 tutmaya değmiyor.
@@ -200,8 +202,8 @@ Layout `.ejs` dosyasının yolu. Verilen değer **views dizininin üst dizinine*
 göre çözülür, yani varsayılan `views` ile `"views/ozel.ejs"` →
 `<root>/views/ozel.ejs`.
 
-Verilmezse sırayla: `views/layout.ejs` varsa o, yoksa framework'ün minimal
-layout'u. Ayrıntı: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md).
+Verilmezse sırayla: `views/layout.jsk`, `views/layout.ejs`, yoksa framework'ün
+minimal layout'u. Ayrıntı: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md).
 
 ## `routes`
 
@@ -467,7 +469,7 @@ Phosphor SVG sprite üretimi.
 
 | Değer | Sonuç |
 | --- | --- |
-| `{}` (varsayılan) | Sprite üretilir; taranan dizinler `["views", "client", "routes", "lib"]` |
+| `{}` (varsayılan) | Sprite üretilir; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
 | `{ scan: [...] }` | Taranan dizinler değiştirilir |
 | `false` | Sprite adımı tamamen atlanır |
 

package/docs/08-build.md

@@ -12,6 +12,7 @@ davranışı burada. Çıktının çalışma anında nasıl servis edildiği
 ## Hat ve sırası
 
 ```
+0. Templates      .jsk → .jskelet/templates/*.mjs (her zaman; dosya yoksa no-op)
 1. Fonts          config.fonts varsa
 2. Icon sprite    config.icons !== false ise
 3. CSS            styles giriş dosyası varsa
@@ -21,6 +22,10 @@ davranışı burada. Çıktının çalışma anında nasıl servis edildiği
 7. Precompress    watch değilse
 ```
 
+Şablon derlemesi asset taramasından **önce** biter; istek yolunda parse yoktur.
+Tailwind `@source` ve ikon taraması kaynak `.jsk` dosyalarını okur (üretilmiş
+`.mjs` değil).
+
 Sıra rastgele değil:
 
 - **CSS ikon sprite'ından sonra gelir.** Sprite bir varlıktır ve sınıf üretmez,

package/docs/en/02-architecture.md

@@ -25,6 +25,9 @@ JSkelet puts this observation at the centre of the architecture:
    independent "island", with its own module, at its own time.
 3. **Page production is cached.** There is no point in producing the same HTML
    again on every request; a memory cache with a TTL takes the place of ISR.
+4. **Templates are compiled at build time (`.jsk`).** No request-time parsing;
+   EJS remains as a legacy path. Features may co-locate under
+   `features/<name>/{server,views,client}` — route URLs stay explicit.
 
 ## The path of a request
 

package/docs/en/03-routing.md

@@ -65,10 +65,25 @@ export default {
 };
 ```
 
-**2. If there is no list, the `routes/` directory is scanned alphabetically.**
-The scan is recursive (subdirectories included), only `.js` and `.mjs` files are
-picked up, and files whose name begins with `_` are skipped (for shared modules
-like `_helpers.js`).
+**2. If there is no list, the `routes/` directory is scanned alphabetically**,
+then each `features/<name>/index.js` (or `.mjs`) is appended alphabetically.
+The scan under `routes/` is recursive (subdirectories included), only `.js` and
+`.mjs` files are picked up, and files whose name begins with `_` are skipped
+(for shared modules like `_helpers.js`).
+
+Feature-first layout is optional:
+
+```
+features/markets/
+  index.js          # register(app, api) — URLs are still explicit
+  server/
+  views/pages/…     # .jsk or .ejs
+  views/components/
+  client/           # islands; register from client/entries
+```
+
+`jskelet generate feature|page|island` scaffolds this. There is no filesystem
+URL routing.
 
 In that case, give the file names a numeric prefix:
 

package/docs/en/04-rendering.md

@@ -21,18 +21,95 @@ route(controller)
          │     renderView(page.view, { …data, metadata }),   → body
          │     hooks.layoutContext({ pathname, metadata }),  → context
          │   ])
-         └─ layout.ejs render  → full HTML
+         └─ 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 EJS engine
+## `.jsk` — build-time compiled templates
 
-The engine is set up once on the first render; the component scan touches the
-file system, so it cannot be done on every request and cannot be computed
-before the config is loaded.
+New apps default to `.jsk`. At build time they become normal ESM modules under
+`.jskelet/templates/*.mjs`. There is **no request-time parsing, `eval`, or
+`new Function`**. Production path:
+
+```
+controller data → imported render(data, helpers) → HTML
+```
+
+### Syntax summary
+
+```html
+<section class="wrapper">
+  <h1>{{ title }}</h1>
+  <div>{{{ trustedHtml }}}</div>
+
+  {#if items.length}
+    <List :items="items" />
+  {#else}
+    <p>Empty</p>
+  {/if}
+
+  {#each items as item, i}
+    <li data-i="{{ i }}">{{ item }}</li>
+  {/each}
+
+  <Link href="/" text="Home" />
+  <div data-island="counter" data-island-props='{"start":0}'></div>
+</section>
+```
+
+| Feature | Form |
+| --- | --- |
+| Escaped text | `{{ expr }}` |
+| Raw HTML | `{{{ expr }}}` |
+| Conditional | `{#if expr}` … `{#else}` … `{/if}` |
+| Loop | `{#each list as item}` or `as item, i` |
+| Include | `{#include "partials/header"}` (compiled `.jsk`) |
+| Component | PascalCase tag; `:prop="expr"`, `prop="literal"`, boolean `disabled` |
+| Built-ins | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage` |
+
+The expression language is intentionally small (access, compare, ternary,
+`.length`). No assignments, object literals, or arbitrary calls — keep logic in
+controllers or JS components.
+
+#### Template or component?
+
+When moving off EJS, draw the line early:
+
+| Stay in `.jsk` | Move to a JS component |
+| --- | --- |
+| Text, conditionals, lists, prop binding | Function calls, object construction, formatting |
+| Built-in tags (`Link`, `Image`, …) | Composing HTML from several helpers |
+| Ready-made data from the controller | Upstream / error-aware UI (`LoadErrorState`) |
+
+If the template cannot write `format(x)` or `{ a: 1 }`, that is intentional: the
+work belongs in `views/components/*.js` or the controller. Prefer a clear
+component boundary over widening the expression language when complex pages
+“escape” into JS.
+
+### Editor support
+
+`extensions/vscode-jsk` is a VS Code / Cursor extension in this repo: syntax
+highlighting, language configuration, and snippets. Local install:
+
+```bash
+code --install-extension extensions/vscode-jsk
+```
+
+See the extension README for details.
+
+### Coexistence with EJS
+
+If a compiled `.jsk` exists for a view id it wins; otherwise `.ejs` is rendered
+with EJS. Existing apps keep working unchanged. `jskelet init` scaffolds `.jsk`.
+
+## The EJS engine (legacy)
+
+EJS remains supported. The engine is set up once on the first render; the
+component scan touches the file system, so it cannot be done on every request
+and cannot be computed before the config is loaded.
 
 Settings:
 
@@ -54,14 +131,15 @@ normal flow because the dev server restarts the process.
 1. `jskelet.config.mjs` → if `layout` is given, it is used. The path is
    resolved relative to the **parent directory of the views directory**: if
    `views` is the default, `layout: "views/custom.ejs"` → `<root>/views/custom.ejs`.
-2. If it is not given and `views/layout.ejs` exists, that is used.
-3. If that does not exist either, the framework's own minimal layout is used
+2. If it is not given and `views/layout.jsk` exists (compiled), that is used.
+3. Else if `views/layout.ejs` exists, that is used.
+4. If that does not exist either, the framework's own minimal layout is used
    (`node_modules/jskelet/src/templates/layout.ejs`, also reachable through the
    `jskelet/layout` specifier).
 
-The third option exists so that a new project can work with a single route. The
+These fallbacks exist so that a new project can work with a single route. The
 most practical way to move to your own layout is to copy that file to
-`views/layout.ejs`.
+`views/layout.ejs` or author `views/layout.jsk`.
 
 ### The framework's default layout
 
@@ -192,14 +270,20 @@ Rules:
 
 - The scan is recursive; subdirectories are covered too.
 - `default` exports are ignored — only named exports are registered.
+- The compile-time known-component set is read from **named exports in the
+  source**, not from the file basename. `sectionHead` in `ui.js` →
+  `<SectionHead />` in the template (runtime already adds a PascalCase alias
+  for camelCase exports). You do not need a stub re-export named after the
+  file.
 - `loader.js` and `index.js` do not count as component files.
 - If `views/components/index.js` exists it is loaded first as a **barrel**,
   with the lowest priority. Its only purpose is to turn `lib/` re-exports into
   template locals; the components' own files come later and silently overwrite
   it.
-- If the same name is defined in two different component files a warning is
-  printed and **the second one wins**: `[components] 'card' is defined twice:
-  a.js and b.js — the second one wins.`
+- If the same name (or the same PascalCase tag) is defined in two different
+  component files, that is an **error, not a warning**: build and server
+  startup stop with `Component 'card' is defined twice: …`. Overwriting the
+  barrel is the deliberate exception.
 - If the `views/components` directory does not exist the component registry
   stays empty; a project that uses no components works fine too.