jskelet 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -27,15 +27,26 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- 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`
-  toggles runtime stdout lines. `JSKELET_LOG_BUCKET` (and `logs.s3.bucket`) may
-  be a plain bucket or a `bucket/prefix/…` path. `JSKELET_S3_API_URL` sets the
-  R2/MinIO endpoint (region defaults to `auto`). Missing credentials warn and
-  disable the S3 sink without taking the site down. Env: `JSKELET_LOG_BUCKET`,
-  `JSKELET_S3_ACCESS_KEY_ID`, `JSKELET_S3_SECRET_ACCESS_KEY`,
-  `JSKELET_S3_SESSION_TOKEN`, `JSKELET_S3_REGION`, `JSKELET_S3_API_URL`.
+  toggles runtime stdout lines. `JSKELET_LOG_BUCKET` / `JSKELET_S3_BUCKET`
+  (+ optional `JSKELET_S3_KEY_PREFIX`) may be a plain bucket or a
+  `bucket/prefix/…` path; with credentials present the sink turns on without
+  `enabled: true`. `JSKELET_S3_API_URL` sets the S3-compatible endpoint
+  (region defaults to `auto`). Env: `JSKELET_LOG_BUCKET`, `JSKELET_S3_*`.
 - Admin panel pages under `/_jskelet/admin`: Overview, Cache, Routes, Views,
   Logs and System. Configurable `allowIps` (exact or CIDR), `blockBots` (default
   on — crawler UAs get 404 before login), and `logSize`. Live Logs use an
@@ -114,6 +125,11 @@ 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
+
+- `examples/minimal` pages moved to `.jsk`; adds `features/demo` as a
+  co-located route + view sample.
+
 - 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,70 @@ 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 ve rastgele fonksiyon çağrısı yok — mantık controller veya JS bileşende
+kalır.
+
+### 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 +105,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).
 

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 |
 
@@ -768,8 +770,8 @@ mevcut davranışını korur. Açıldığında HTTP access log ile framework ola
 | `s3.enabled` | `boolean` | `false` | S3 batch PutObject sink'i |
 | `s3.bucket` | `string \| null` | `null` | Bucket ya da `bucket/prefix/…` yolu; `JSKELET_LOG_BUCKET` ezer |
 | `s3.prefix` | `string` | `"jskelet/logs/"` | Nesne anahtarı öneki (yolda verilmediyse) |
-| `s3.region` | `string \| null` | `null` | Bölge; verilmezse `JSKELET_S3_REGION`, endpoint varken `auto` |
-| `s3.endpoint` | `string \| null` | `null` | R2 / MinIO API adresi; `JSKELET_S3_API_URL` ezer |
+| `s3.region` | `string \| null` | `"auto"` | Bölge; verilmezse `JSKELET_S3_REGION`, yoksa `auto` |
+| `s3.endpoint` | `string \| null` | `null` | S3-uyumlu API adresi; `JSKELET_S3_API_URL` ezer |
 | `s3.flushIntervalMs` | `number` | `5000` | Batch flush aralığı |
 | `s3.maxBatch` | `number` | `100` | Bu kadar satırda erken flush |
 
@@ -975,12 +977,14 @@ basılmaz.
 | `JSKELET_SECRET` | `jskelet/cookies` | — | İmzalı cookie sırrı. `security.cookieSecret` verilmediğinde buradan okunur; ikisi de yoksa imzalı cookie API'si hata verir. [12](./12-panel-ve-oturum.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |
 | `JSKELET_ADMIN` | `createApp` | — | Ayarlıysa yönetim panelini açar; `0` config'te açık olan paneli kapatır. Env config'i ezer, çünkü panel genelde bir arıza sırasında tek seferlik açılır. [06](./06-cache.md) |
-| `JSKELET_LOG_BUCKET` | `logs.s3` | — | S3 bucket ya da `ayberkenis/jskelet/logs` gibi `bucket/prefix` yolu; `logs.s3.bucket`'ı ezer (`JSKELET_S3_BUCKET` yedek ad) |
-| `JSKELET_S3_ACCESS_KEY_ID` | `logs.s3` | — | S3 PutObject imzası. Yoksa ve `s3.enabled` ise sink kapanır |
-| `JSKELET_S3_SECRET_ACCESS_KEY` | `logs.s3` | — | S3 imza sırrı |
-| `JSKELET_S3_SESSION_TOKEN` | `logs.s3` | — | Geçici credential'lar için isteğe bağlı |
-| `JSKELET_S3_REGION` | `logs.s3` | — | `logs.s3.region` verilmezse; endpoint varken varsayılan `auto` |
-| `JSKELET_S3_API_URL` | `logs.s3` | — | R2 / MinIO endpoint; `logs.s3.endpoint`'i ezer |
+| `JSKELET_LOG_BUCKET` | `logs.s3` | — | Log hedefi: bucket ya da `bucket/prefix` yolu. Credential ile birlikte varsa sink otomatik açılır |
+| `JSKELET_S3_BUCKET` | `logs.s3` | — | `JSKELET_LOG_BUCKET` yoksa bucket; `JSKELET_S3_KEY_PREFIX` ile birleşir |
+| `JSKELET_S3_KEY_PREFIX` | `logs.s3` | — | `JSKELET_S3_BUCKET` ile kullanılır (`bucket/prefix`) |
+| `JSKELET_S3_ACCESS_KEY_ID` | `logs.s3` | — | PutObject imzası |
+| `JSKELET_S3_SECRET_ACCESS_KEY` | `logs.s3` | — | İmza sırrı (`JSKELET_S3_ACCESS_SECRET` yedek ad) |
+| `JSKELET_S3_SESSION_TOKEN` | `logs.s3` | — | Geçici credential için isteğe bağlı |
+| `JSKELET_S3_REGION` | `logs.s3` | `auto` | Verilmezse `auto` |
+| `JSKELET_S3_API_URL` | `logs.s3` | — | S3-uyumlu endpoint; `logs.s3.endpoint`'i ezer |
 | `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache yüzeyi | — | API token. Verilene kadar CDN purge'ü ve edge analitiği kapalıdır; config'teki `apiToken`'ı ezer. Token hiçbir cevapta dönmez. [06](./06-cache.md) |
 | `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache yüzeyi | — | Zone kimliği. Token'la birlikte verilmedikçe hiçbir Cloudflare ucu çağrılmaz |
 | `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache yüzeyi | — | Purge URL'lerinin kökü. Panel iç bir adresten açılıyorsa gerekir |

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,69 @@ 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 or arbitrary calls — keep logic in controllers or JS
+components.
+
+### 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 +105,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
 

package/docs/en/07-configuration.md

@@ -155,12 +155,14 @@ internally.
 
 | Key | Default | Contents |
 | --- | --- | --- |
-| `views` | `"views"` | EJS layout, pages, components |
-| `public` | `"public"` | Static files; the build output is written here too |
+| `views` | `"views"` | Layout, pages, components (classic root; `.jsk` / `.ejs`) |
+| `features` | `"features"` | Feature-first slices (`<name>/{server,views,client}`) |
+| `shared` | `"shared"` | Cross-feature server/views/client |
+| `public` | `"public"` | Static files; build output lands here too |
 | `client` | `"client"` | Island runtime sources and entries |
 | `routes` | `"routes"` | Route modules |
 | `styles` | `"styles/globals.css"` | Tailwind/PostCSS entry **file** |
-| `generated` | `".jskelet"` | `manifest.json`, `metafile.json`, `images.json` |
+| `generated` | `".jskelet"` | `manifest.json`, `templates/`, `metafile.json`, `images.json` |
 
 Even though `styles` is a file path it goes through the same resolution; keeping
 a separate field for it is not worth it.
@@ -784,8 +786,8 @@ events (`event` / `error`) are written as NDJSON lines to a file and/or S3.
 | `s3.enabled` | `boolean` | `false` | S3 batch PutObject sink |
 | `s3.bucket` | `string \| null` | `null` | Bucket or a `bucket/prefix/…` path; `JSKELET_LOG_BUCKET` overrides |
 | `s3.prefix` | `string` | `"jskelet/logs/"` | Object key prefix (when not given in the path) |
-| `s3.region` | `string \| null` | `null` | Region; falls back to `JSKELET_S3_REGION`, or `auto` when an endpoint is set |
-| `s3.endpoint` | `string \| null` | `null` | R2 / MinIO API URL; `JSKELET_S3_API_URL` overrides |
+| `s3.region` | `string \| null` | `"auto"` | Region; falls back to `JSKELET_S3_REGION`, otherwise `auto` |
+| `s3.endpoint` | `string \| null` | `null` | S3-compatible API URL; `JSKELET_S3_API_URL` overrides |
 | `s3.flushIntervalMs` | `number` | `5000` | Batch flush interval |
 | `s3.maxBatch` | `number` | `100` | Flush early after this many lines |
 
@@ -995,12 +997,14 @@ and no warning is printed.
 | `JSKELET_SECRET` | `jskelet/cookies` | — | The signed cookie secret. Read when `security.cookieSecret` is not set; if neither exists, the signed cookie API throws. [12](./12-dashboards-and-sessions.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
 | `JSKELET_ADMIN` | `createApp` | — | When set, turns the admin panel on; `0` turns off a panel enabled in the config. The env wins because the panel is usually opened once during an incident. [06](./06-caching.md) |
-| `JSKELET_LOG_BUCKET` | `logs.s3` | — | S3 bucket or a `bucket/prefix` path like `ayberkenis/jskelet/logs`; overrides `logs.s3.bucket` (`JSKELET_S3_BUCKET` is an alias) |
-| `JSKELET_S3_ACCESS_KEY_ID` | `logs.s3` | — | Signs S3 PutObject. Missing when `s3.enabled` disables the sink |
-| `JSKELET_S3_SECRET_ACCESS_KEY` | `logs.s3` | — | S3 signing secret |
+| `JSKELET_LOG_BUCKET` | `logs.s3` | — | Log target: bucket or `bucket/prefix` path. With credentials, the sink turns on automatically |
+| `JSKELET_S3_BUCKET` | `logs.s3` | — | Bucket when `JSKELET_LOG_BUCKET` is unset; joins with `JSKELET_S3_KEY_PREFIX` |
+| `JSKELET_S3_KEY_PREFIX` | `logs.s3` | — | Used with `JSKELET_S3_BUCKET` (`bucket/prefix`) |
+| `JSKELET_S3_ACCESS_KEY_ID` | `logs.s3` | — | Signs PutObject |
+| `JSKELET_S3_SECRET_ACCESS_KEY` | `logs.s3` | — | Signing secret (`JSKELET_S3_ACCESS_SECRET` is an alias) |
 | `JSKELET_S3_SESSION_TOKEN` | `logs.s3` | — | Optional, for temporary credentials |
-| `JSKELET_S3_REGION` | `logs.s3` | — | Used when `logs.s3.region` is unset; defaults to `auto` when an endpoint is set |
-| `JSKELET_S3_API_URL` | `logs.s3` | — | R2 / MinIO endpoint; overrides `logs.s3.endpoint` |
+| `JSKELET_S3_REGION` | `logs.s3` | `auto` | Defaults to `auto` when unset |
+| `JSKELET_S3_API_URL` | `logs.s3` | — | S3-compatible endpoint; overrides `logs.s3.endpoint` |
 | `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache surface | — | API token. Until it is set, CDN purging and edge analytics stay off; it overrides `apiToken` in the config. The token is never returned in a response. [06](./06-caching.md) |
 | `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache surface | — | Zone identifier. No Cloudflare endpoint is called unless it is set alongside the token |
 | `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache surface | — | The root for purge URLs. Required when the panel is opened over an internal address |

package/docs/en/08-build.md

@@ -12,6 +12,7 @@ build is in [09-dev-tools.md](./09-dev-tools.md).
 ## The pipeline and its order
 
 ```
+0. Templates      .jsk → .jskelet/templates/*.mjs (always; no-op if none)
 1. Fonts          if config.fonts is set
 2. Icon sprite    if config.icons !== false
 3. CSS            if the styles entry file exists
@@ -21,6 +22,10 @@ build is in [09-dev-tools.md](./09-dev-tools.md).
 7. Precompress    if not watch
 ```
 
+Template compilation finishes **before** asset scanning; there is no parse on
+the request path. Tailwind `@source` and the icon scan read source `.jsk` files
+(not the generated `.mjs`).
+
 The order is not arbitrary:
 
 - **CSS comes after the icon sprite.** The sprite is an asset and produces no

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jskelet",
-  "version": "0.3.4",
-  "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
+  "version": "0.4.0",
+  "description": "A framework that feels like no framework: Express 5 + build-time .jsk (or EJS) SSR, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",
   "author": "Ayberk Enis",

package/src/build/build.mjs

@@ -40,6 +40,12 @@ if (!child) {
 
 log.section("build");
 
+// Şablonlar asset taramasından önce derlenir; istek anında parse yok.
+await task("Templates", async () => {
+  const { buildTemplates } = await import("./tasks/templates.mjs");
+  await buildTemplates(config);
+});
+
 /** @type {Record<string, string>} */
 const manifest = {};
 

package/src/build/ensure-build.mjs

@@ -10,6 +10,10 @@ import { loadConfig } from "../config/index.js";
 
 const config = await loadConfig();
 
-if (!fs.existsSync(path.join(config.dirs.generated, "manifest.json"))) {
+const generated = config.dirs.generated;
+const needsAssets = !fs.existsSync(path.join(generated, "manifest.json"));
+const needsTemplates = !fs.existsSync(path.join(generated, "templates", "manifest.json"));
+
+if (needsAssets || needsTemplates) {
   await import("./build.mjs");
 }

package/src/build/tasks/icons.mjs

@@ -19,7 +19,7 @@ import { createRequire } from "node:module";
 import { pruneAssets, writeAsset } from "../paths.mjs";
 import * as log from "../../log.mjs";
 
-const SCAN_EXTENSIONS = new Set([".ejs", ".js", ".mjs"]);
+const SCAN_EXTENSIONS = new Set([".ejs", ".jsk", ".js", ".mjs"]);
 
 /** `icon({ … })` çağrısının tamamı; `name:` ifadesi ayrıca çözümlenir. */
 const ICON_CALL = /icon\(\s*\{([^}]*)\}/g;
@@ -189,7 +189,7 @@ export async function buildIconSprite(config) {
   }
 
   const scanDirs = (
-    config.icons?.scan ?? ["views", "client", "routes", "lib"]
+    config.icons?.scan ?? ["views", "client", "routes", "lib", "features", "shared"]
   ).map((dir) => path.resolve(config.root, dir));
 
   pruneAssets(["sprite."]);

package/src/build/tasks/templates.mjs

@@ -0,0 +1,20 @@
+/**
+ * `.jsk` şablonlarını `.jskelet/templates/` altına derler.
+ * Asset pipeline'dan önce çalışır; Tailwind/ikon taraması kaynak `.jsk`'yi okur.
+ */
+import { compileAll } from "../../compile/compile-all.js";
+import * as log from "../../log.mjs";
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {Promise<number>} Derlenen dosya sayısı.
+ */
+export async function buildTemplates(config) {
+  const result = await compileAll(config);
+  if (result.count === 0) {
+    log.line("no .jsk templates");
+  } else {
+    log.line(`${result.count} template${result.count === 1 ? "" : "s"} → .jskelet/templates`);
+  }
+  return result.count;
+}