jskelet 0.6.15 → 0.6.17

package/CHANGELOG.md

@@ -17,6 +17,18 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- On-demand HTML cache via `cache().prewarm: false`: visited pages still
+  write to L1 and Redis/disk L2 with the usual `html` TTLs, but classic
+  prewarm, `onVisit` link warming, and early-expiry HTTP refresh stay off
+  (`PREWARM=1` does not override). Mutually exclusive with
+  `hooks.prewarmPaths`. Resolved `prewarm.mode` is `"off"` | `"classic"` |
+  `"onVisit"`.
+- When `build.assets.prefix` is set, the CSS build rewrites root-absolute
+  `url()` paths under `static.prefixes` (e.g. `/fonts/…`) to the CDN
+  prefix so they match the S3 key (`…/js/fonts/…`). Default upload
+  `include` is `["assets", "fonts"]`; prefix also forces `fonts` into
+  `include`. Font uploads run PutBucketCors with
+  `upload.corsOrigin` (default `"*"`, set `null` to skip).
 - `asset(name, { origin: "document" })` skips `build.assets.prefix` and
   returns the site-origin `/assets/…` path. `icon()` always resolves the
   sprite this way so SVG `<use href>` keeps working when other assets are

package/docs/06-cache.md

@@ -1173,10 +1173,34 @@ loopback yalnızca o host'un anahtarını ısıtır — locale sitelerinde
 `origins: ["http://localhost", "http://tr.localhost"]` gibi çoklu origin
 gerekir.
 
-İki mod **karşılıklı dışlayıcıdır**. `cache().prewarm.onVisit` açıksa klasik
-alanlar (`max`, `priority`, `rotate`, `intervalSeconds`, …) ve
-`hooks.prewarmPaths` birlikte verilemez — config yüklenirken hata fırlar.
-Tersi de geçerli: klasik liste ısıtması kullanıyorsanız `onVisit` yazmayın.
+Üç yüzey **karşılıklı dışlayıcıdır**: klasik (`hooks.prewarmPaths` + alanlar),
+`onVisit` ve on-demand (`prewarm: false`). Birini seçmek diğerini config
+yüklenirken reddeder.
+
+### Mod: on-demand — `prewarm: false`
+
+Arka plan ısıtması yok; yalnızca gerçek trafikle gelen sayfa önbelleğe yazılır.
+TTL `cache().html` (veya route `revalidate`) ile verilir. Redis açıksa L2'ye,
+değilse `.jskelet/cache/<buildId>/` disk L2'ye yazılır — ziyaret yazımı zaten
+böyle çalışır; bu mod klasik turu, `onVisit` link crawl'ını ve TTL öncesi
+early-expiry HTTP rewarm'ı kapatır. `PREWARM=1` bunu ezmez.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/": 60, "/haber/:slug": 300 },
+      redis: { enabled: true, url: process.env.REDIS_URL },
+      prewarm: false,
+    };
+  },
+};
+```
+
+`hooks.prewarmPaths` ile birlikte **yasaktır**. `prewarm: { enabled: false }`
+farklıdır: klasik turu keser ama early-expiry drain açık kalır; tamamen pasif
+mod için `prewarm: false` kullanın.
 
 ### Mod: `onVisit` — ziyaret edilen sayfanın linkleri
 
@@ -1442,12 +1466,13 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   `cache().vary.host: true` yoksa ilk locale'in HTML'i diğer host'a servis
   edilir. Prewarm yalnızca `127.0.0.1` ile ısınıyorsa `prewarm.origins` ile
   locale host'larını ekleyin.
-- **Isıtma hiç çalışmıyor.** Klasik modda `hooks.prewarmPaths` tanımlı değil,
-  `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
+- **Isıtma hiç çalışmıyor.** `prewarm: false` (on-demand) bilinçli olarak
+  hiçbir arka plan ısıtması kurmaz. Klasik modda `hooks.prewarmPaths` tanımlı
+  değil, `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
   modunda `listen` sonrası logda `onVisit mode` satırını ve public cache'li
   bir sayfa gezildiğini doğrulayın.
-- **Config `onVisit` + `max` / `prewarmPaths` ile düşüyor.** İki mod karşılıklı
-  dışlayıcı; yalnızca birini kullanın.
+- **Config `onVisit` / `prewarm: false` + `max` / `prewarmPaths` ile düşüyor.**
+  Üç yüzey karşılıklı dışlayıcı; yalnızca birini kullanın.
 - **Isıtma turu API'yi 429'a sokuyor.** `rps` verilmemiş. `concurrency`
   düşürmek yeterli değil; kotayı koruyan ayar toplam hız. Kalıcı çözüm veri
   önbelleği: ikinci turdan sonra ısıtma upstream'e gitmez.

package/docs/07-yapilandirma.md

@@ -635,7 +635,8 @@ değişmez** — asset'ler origin'den servis edilir.
 | `assets.upload.keyPrefix` | `string` | `""` | Nesne anahtarı öneki; bucket yolunda verilmişse o kazanır (`prefix` takma adı da kabul). |
 | `assets.upload.region` | `string` | `us-east-1` | Config; custom `endpoint` varken varsayılan `auto`. |
 | `assets.upload.endpoint` | `string \| null` | `null` | S3-uyumlu API (R2 / MinIO); config. |
-| `assets.upload.include` | `string[]` | `["assets"]` | `public/` altı dizinler (`assets`, isteğe `fonts`, …). |
+| `assets.upload.include` | `string[]` | `["assets", "fonts"]` | `public/` altı dizinler. `assets.prefix` doluysa `fonts` yoksa eklenir. |
+| `assets.upload.corsOrigin` | `string \| null` | `"*"` | Font upload'ta PutBucketCors `AllowedOrigin`; `null` kapatır (önceki CORS'un üzerine yazar). |
 | `assets.upload.cacheControl` | `string` | `public, max-age=31536000, immutable` | PutObject `Cache-Control`. |
 
 **Credential config'e yazılmaz.** Zincir: `AWS_ACCESS_KEY_ID` /
@@ -769,9 +770,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **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?: object }` —
+`() => { 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, max: 400, intervalSeconds: 0, origins: [] } }`
+`{ 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"`)
 
 ### `cache().html`
 
@@ -1083,14 +1084,28 @@ tam cevabı olmadığı — [06-cache.md](./06-cache.md) içinde.
 
 ### `cache().prewarm`
 
-İki mod: **klasik** (liste + açılış turu) veya **`onVisit`** (ziyaret edilen
-sayfadaki linkler). Birlikte verilemez — config yüklenirken hata.
+Üç yüzey: **`false`** (on-demand — yalnızca ziyaret yazımı), **klasik** (liste
++ açılış turu) veya **`onVisit`** (ziyaret edilen sayfadaki linkler). Birlikte
+verilemez — config yüklenirken hata. Çözümlenen `prewarm.mode`: `"off"` |
+`"classic"` | `"onVisit"`.
+
+#### On-demand — `prewarm: false`
+
+Arka plan ısıtması yok (klasik tur, `onVisit`, early-expiry HTTP rewarm).
+Ziyaret edilen sayfa `html` TTL'i ile L1 + Redis/disk L2'ye yazılır.
+`PREWARM=1` bunu ezmez. `hooks.prewarmPaths` ile **yasak**.
+`{ enabled: false }` klasik turu keser ama early-expiry açık kalır — tamamen
+pasif mod için `false` kullanın.
+
+```js
+prewarm: false,
+```
 
 #### Klasik alanlar
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
+| `enabled` | `boolean` | `true` | `false` ise klasik tur yapılmaz (`PREWARM=1` ile ezilebilir); early-expiry drain açık kalır |
 | `max` | `number` | `400` | Bir turda en fazla kaç yol ısıtılır |
 | `concurrency` | `number` | prod 4, dev 1 | Paralel işçi sayısı |
 | `rps` | `number` | prod `0`, dev 4 | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. Dev'deki varsayılan fren, ısıtmanın sayfa isteklerini bekletmemesi için. |
@@ -1134,8 +1149,8 @@ prewarm: {
 }
 ```
 
-`hooks.prewarmPaths` ve klasik alanlar (`max`, `priority`, …) `onVisit` ile
-**yasaktır**. Ayrıntı: [06-cache.md](./06-cache.md).
+`hooks.prewarmPaths` ve klasik alanlar (`max`, `priority`, …) `onVisit` veya
+`prewarm: false` ile **yasaktır**. Ayrıntı: [06-cache.md](./06-cache.md).
 
 Sayısal alanların her biri aynı adı taşıyan ortam değişkeniyle ezilebilir; env
 önceliklidir. Ayrıntı: [06-cache.md](./06-cache.md).
@@ -1153,7 +1168,7 @@ varsayılanına döner ve uyarır — sayfa düşmez.
 | `layoutContext` | `({ pathname, metadata }) => object` | Layout local'leri; `lang`, `structuredData`, `extraHead`, `bodyClass` özel yorumlanır | [04](./04-render-ve-sablonlar.md) |
 | `notFound` | `() => object \| null` | 404 sayfa tanımı; `null` ise framework'ün hata sayfası | [03](./03-routing.md) |
 | `error` | `({ status, error }) => object \| string \| null` | 404 dışındaki hata sayfaları (ve `notFound` yoksa 404); sayfa tanımı ya da doğrudan HTML | [03](./03-routing.md) |
-| `prewarmPaths` | `() => string[]` | Klasik ısıtmada ısıtılacak yollar; tanımlı değilse klasik tur kurulmaz. `onVisit` ile birlikte **yasak** | [06](./06-cache.md) |
+| `prewarmPaths` | `() => string[]` | Klasik ısıtmada ısıtılacak yollar; tanımlı değilse klasik tur kurulmaz. `onVisit` ve `prewarm: false` ile **yasak** | [06](./06-cache.md) |
 
 ```js
 hooks: {
@@ -1246,7 +1261,7 @@ basılmaz.
 | `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 |
-| `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
+| `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar. `prewarm: false` (on-demand) ezilmez |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Paralel işçi sayısı |
 | `PREWARM_RPS` | `prewarm` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız |

package/docs/08-build.md

@@ -91,12 +91,21 @@ dosya adlarını okunur tutuyor. Hash'li olmaları sayesinde bu dosyalara
 Varsayılan kapalıdır. Prefix / bucket / keyPrefix config'te; credential
 env → ECS task role → EC2 IMDS zincirinden. Açılınca:
 
-1. Production build `public/assets/` (ve `include` listesindeki diğer dizinler)
-   altındaki dosyaları S3'e PutObject ile kopyalar.
-2. Çalışma anında `asset()` / optimize görseller `build.assets.prefix` ile
-   absolute CDN URL basar. Entry CDN'deyse esbuild chunk'ları göreli yolla aynı
-   host'a gider. `icon()` sprite'ı ve `asset(name, { origin: "document" })`
-   site origin'inde kalır.
+1. Production build `public/assets/` ve `public/fonts/` (varsayılan `include`)
+   altındaki dosyaları S3'e PutObject ile kopyalar. `assets.prefix` doluysa
+   `include`'da `fonts` yoksa otomatik eklenir.
+2. CSS derlemesi `static.prefixes` kök-mutlak `url()` yollarını
+   (`/fonts/…`, `/assets/…`) `prefix` ile yeniden yazar — aksi hâlde CDN'deki
+   stylesheet `url("/fonts/x")` yolunu host köküne çözer ve `keyPrefix`
+   kaybolur. `@font-face` CDN CSS içinde kalabilir; font ile CSS aynı host'ta
+   olduğu için ek CORS gerekmez.
+3. Font yüklendiğinde ve `upload.corsOrigin` doluysa (varsayılan `"*"`)
+   PutBucketCors bir GET/HEAD kuralı yazar — bucket'taki önceki CORS'un
+   **üzerine** yazar; kapatmak için `corsOrigin: null`. HTML'den çapraz
+   origin font için bu (veya CloudFront response header) gerekir.
+4. Çalışma anında `asset()` / optimize görseller `build.assets.prefix` ile
+   absolute CDN URL basar. `icon()` sprite'ı ve
+   `asset(name, { origin: "document" })` site origin'inde kalır.
 
 Bucket adı noktalı olabilir (`static.ornek.com`); `https://…` şeması
 `prefix`'e yazılır. Config sözlüğü: [07-yapilandirma.md](./07-yapilandirma.md#build).
@@ -297,6 +306,10 @@ Kullanımı stylesheet'te elle yazılır:
 `.woff2` uzantısı ve `/fonts/` öneki varsayılan `static` kurallarında olduğu için
 bu dosyalara otomatik olarak `immutable` cache yazılır.
 
+`build.assets.prefix` açıksa build, CSS'teki `url("/fonts/…")` yollarını CDN
+prefix'iyle yeniden yazar ve fontları S3'e de basar — layout'ta ayrı
+`@font-face` tutmaya gerek kalmaz.
+
 ## İkon sprite
 
 **Yalnızca kaynakta kullanılan** ikonlar için bir `<symbol>` seti üretir. Tüm

package/docs/en/06-caching.md

@@ -1175,10 +1175,35 @@ traffic. With `vary.host`, the default loopback only warms that host's key —
 locale sites need multiple origins such as
 `origins: ["http://localhost", "http://tr.localhost"]`.
 
-The two modes are **mutually exclusive**. If `cache().prewarm.onVisit` is on,
-classic fields (`max`, `priority`, `rotate`, `intervalSeconds`, …) and
-`hooks.prewarmPaths` must not be set together — config load throws. The reverse
-holds too: if you use classic list warming, do not set `onVisit`.
+Three surfaces are **mutually exclusive**: classic (`hooks.prewarmPaths` +
+fields), `onVisit`, and on-demand (`prewarm: false`). Choosing one rejects the
+others at config load.
+
+### Mode: on-demand — `prewarm: false`
+
+No background warming; only pages hit by real traffic are written to the cache.
+TTL comes from `cache().html` (or the route `revalidate`). With Redis on, the
+entry goes to L2 Redis; otherwise to the `.jskelet/cache/<buildId>/` disk L2 —
+visit writes already work that way; this mode turns off the classic pass,
+`onVisit` link crawling, and early-expiry HTTP refresh before TTL. `PREWARM=1`
+does not override it.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/": 60, "/news/:slug": 300 },
+      redis: { enabled: true, url: process.env.REDIS_URL },
+      prewarm: false,
+    };
+  },
+};
+```
+
+**Forbidden** together with `hooks.prewarmPaths`. `prewarm: { enabled: false }`
+is different: it stops the classic pass but leaves the early-expiry drain on —
+use `prewarm: false` for fully passive mode.
 
 ### Mode: `onVisit` — links from the page just visited
 
@@ -1449,12 +1474,13 @@ filled the cache.
   without `cache().vary.host: true` the first locale's HTML is served to the
   other host. If prewarm only hits `127.0.0.1`, add the locale hosts via
   `prewarm.origins`.
-- **The warm-up never runs.** In classic mode `hooks.prewarmPaths` is not
+- **The warm-up never runs.** `prewarm: false` (on-demand) intentionally
+  installs no background warming. In classic mode `hooks.prewarmPaths` is not
   defined, `PREWARM=0` is set, or `cache().prewarm.enabled === false`. In
   `onVisit` mode check the `onVisit mode` log line after `listen` and that a
   public cacheable page was visited.
-- **Config fails with `onVisit` + `max` / `prewarmPaths`.** The two modes are
-  mutually exclusive; use only one.
+- **Config fails with `onVisit` / `prewarm: false` + `max` / `prewarmPaths`.**
+  The three surfaces are mutually exclusive; use only one.
 - **The warm-up round pushes the API into 429.** No `rps` was given. Lowering
   `concurrency` is not enough; the setting that protects the quota is the total
   rate. The lasting fix is the data cache: after the second round the warm-up

package/docs/en/07-configuration.md

@@ -648,7 +648,8 @@ changes** — assets stay on the origin.
 | `assets.upload.keyPrefix` | `string` | `""` | Object key prefix; a path on the bucket wins (`prefix` is accepted as an alias). |
 | `assets.upload.region` | `string` | `us-east-1` | Config; defaults to `auto` when `endpoint` is set. |
 | `assets.upload.endpoint` | `string \| null` | `null` | S3-compatible API (R2 / MinIO); config. |
-| `assets.upload.include` | `string[]` | `["assets"]` | Directories under `public/` (`assets`, optionally `fonts`, …). |
+| `assets.upload.include` | `string[]` | `["assets", "fonts"]` | Directories under `public/`. When `assets.prefix` is set, `fonts` is added if missing. |
+| `assets.upload.corsOrigin` | `string \| null` | `"*"` | PutBucketCors `AllowedOrigin` when fonts upload; `null` disables (replaces prior bucket CORS). |
 | `assets.upload.cacheControl` | `string` | `public, max-age=31536000, immutable` | PutObject `Cache-Control`. |
 
 **Credentials are not written in the config.** Chain: `AWS_ACCESS_KEY_ID` /
@@ -783,9 +784,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **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?: object }` —
+`() => { 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, max: 400, intervalSeconds: 0, origins: [] } }`
+`{ 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"`)
 
 ### `cache().html`
 
@@ -1105,14 +1106,28 @@ edges hold this page" has no exact answer — is in
 
 ### `cache().prewarm`
 
-Two modes: **classic** (list + startup pass) or **`onVisit`** (links from the
-page just visited). They cannot be combined — config load throws.
+Three surfaces: **`false`** (on-demand — visit writes only), **classic** (list
++ startup pass), or **`onVisit`** (links from the page just visited). They
+cannot be combined — config load throws. Resolved `prewarm.mode`: `"off"` |
+`"classic"` | `"onVisit"`.
+
+#### On-demand — `prewarm: false`
+
+No background warming (classic pass, `onVisit`, early-expiry HTTP refresh).
+Visited pages still write to L1 + Redis/disk L2 with the `html` TTLs.
+`PREWARM=1` does not override. **Forbidden** with `hooks.prewarmPaths`.
+`{ enabled: false }` stops the classic pass but leaves early-expiry on — use
+`false` for fully passive mode.
+
+```js
+prewarm: false,
+```
 
 #### Classic fields
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
+| `enabled` | `boolean` | `true` | If `false`, no classic pass (`PREWARM=1` can override); early-expiry drain stays on |
 | `max` | `number` | `400` | At most how many paths are prewarmed per pass |
 | `concurrency` | `number` | prod 4, dev 1 | Number of parallel workers |
 | `rps` | `number` | prod `0`, dev 4 | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. The default brake in dev keeps prewarming from holding page requests up. |
@@ -1157,7 +1172,7 @@ prewarm: {
 ```
 
 `hooks.prewarmPaths` and classic fields (`max`, `priority`, …) are **forbidden**
-with `onVisit`. Details: [06-caching.md](./06-caching.md).
+with `onVisit` or `prewarm: false`. Details: [06-caching.md](./06-caching.md).
 
 Each numeric field can be overridden by an environment variable of the same
 name; env takes precedence. Details: [06-caching.md](./06-caching.md).
@@ -1175,7 +1190,7 @@ its own default and warns — the page does not go down.
 | `layoutContext` | `({ pathname, metadata }) => object` | Layout locals; `lang`, `structuredData`, `extraHead` and `bodyClass` get special treatment | [04](./04-rendering.md) |
 | `notFound` | `() => object \| null` | 404 page definition; if `null`, the framework's error page | [03](./03-routing.md) |
 | `error` | `({ status, error }) => object \| string \| null` | Error pages other than 404 (and 404 when there is no `notFound`); a page definition or HTML directly | [03](./03-routing.md) |
-| `prewarmPaths` | `() => string[]` | Paths for classic prewarm; if omitted, the classic pass is never set up. **Forbidden** with `onVisit` | [06](./06-caching.md) |
+| `prewarmPaths` | `() => string[]` | Paths for classic prewarm; if omitted, the classic pass is never set up. **Forbidden** with `onVisit` and `prewarm: false` | [06](./06-caching.md) |
 
 ```js
 hooks: {
@@ -1269,7 +1284,7 @@ and no warning is printed.
 | `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 |
-| `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |
+| `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on. Does not override `prewarm: false` (on-demand) |
 | `PREWARM_MAX` | `prewarm` | `400` | At most how many paths are prewarmed |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Number of parallel workers |
 | `PREWARM_RPS` | `prewarm` | `0` | At most how many prewarm requests per second; `0` is unlimited |

package/docs/en/08-build.md

@@ -94,11 +94,20 @@ They are passed to templates automatically; in server code,
 Off by default. Prefix / bucket / keyPrefix come from config; credentials
 resolve from env → ECS task role → EC2 IMDS. When enabled:
 
-1. A production build PutObjects files under `public/assets/` (and any other
-   directories in `include`) to S3.
-2. At runtime `asset()` / optimised images emit absolute CDN URLs via
-   `build.assets.prefix`. When the entry script is on the CDN, esbuild chunks
-   resolve relatively on the same host. The `icon()` sprite and
+1. A production build PutObjects `public/assets/` and `public/fonts/`
+   (default `include`) to S3. When `assets.prefix` is set, `fonts` is added
+   to `include` if missing.
+2. The CSS step rewrites root-absolute `url()` paths under `static.prefixes`
+   (`/fonts/…`, `/assets/…`) with `prefix` — otherwise a stylesheet on the CDN
+   resolves `url("/fonts/x")` against the host root and drops `keyPrefix`.
+   `@font-face` can stay in the CDN CSS; font and CSS share a host, so no
+   extra CORS is needed for that path.
+3. When fonts are uploaded and `upload.corsOrigin` is set (default `"*"`),
+   PutBucketCors writes a GET/HEAD rule — it **replaces** the bucket's
+   previous CORS config; set `corsOrigin: null` to skip. Cross-origin fonts
+   from HTML still need this (or a CloudFront response-header policy).
+4. At runtime `asset()` / optimised images emit absolute CDN URLs via
+   `build.assets.prefix`. The `icon()` sprite and
    `asset(name, { origin: "document" })` stay on the document origin.
 
 Bucket names may include dots (`static.example.com`); put `https://…` in
@@ -305,6 +314,10 @@ Usage is written by hand in the stylesheet:
 Because the `.woff2` extension and the `/fonts/` prefix are in the default
 `static` rules, these files automatically get an `immutable` cache.
 
+When `build.assets.prefix` is set, the build rewrites `url("/fonts/…")` in CSS
+to the CDN prefix and uploads the font files too — you do not need a separate
+`@font-face` block in the layout.
+
 ## Icon sprite
 
 Produces a `<symbol>` set for **only the icons actually used in the source**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "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/rewrite-css-urls.mjs

@@ -0,0 +1,40 @@
+/**
+ * CDN prefix varken CSS `url(/fonts/…)` yollarını upload path'iyle hizalar.
+ *
+ * CDN'deki `app.css` kök-mutlak `/fonts/x.woff2` görünce tarayıcı bunu
+ * `https://cdn.example.com/fonts/x` diye çözer — `keyPrefix` (`/js` vb.)
+ * kaybolur ve 403 gelir. Prefix + aynı göreli yol (`…/js/fonts/x`) doğru
+ * nesneye gider; font ile CSS aynı host'ta olduğu için `@font-face` CORS
+ * istemez. HTML'den CDN font yüklemek ayrı: bucket/CloudFront CORS gerekir.
+ */
+import { applyAssetPrefix } from "../server/assets.js";
+
+/**
+ * @param {string} css
+ * @param {{ prefix: string, prefixes?: string[] }} options
+ * @returns {string}
+ */
+export function rewriteCssStaticUrls(css, { prefix, prefixes = [] }) {
+  if (!prefix || !css) return css;
+
+  const roots = [...prefixes]
+    .filter((entry) => typeof entry === "string" && entry.startsWith("/"))
+    .map((entry) => (entry.endsWith("/") ? entry : `${entry}/`))
+    .sort((a, b) => b.length - a.length);
+
+  if (!roots.length) return css;
+
+  return css.replace(
+    /url\(\s*(['"]?)(\/[^)"'\s]+)\1\s*\)/gi,
+    (match, quote, urlPath) => {
+      const pathOnly = urlPath.split(/[?#]/, 1)[0];
+      if (!roots.some((root) => pathOnly === root.slice(0, -1) || pathOnly.startsWith(root))) {
+        return match;
+      }
+
+      const rewritten = applyAssetPrefix(prefix, urlPath);
+      const q = quote || '"';
+      return `url(${q}${rewritten}${q})`;
+    },
+  );
+}

package/src/build/tasks/assets-upload.mjs

@@ -16,12 +16,22 @@ import {
   resolveS3Credentials,
   s3CredentialsMissingReason,
 } from "../../server/logs/s3-credentials.js";
-import { putObject } from "../../server/logs/s3-put.js";
+import { putBucketCors, putObject } from "../../server/logs/s3-put.js";
 import * as log from "../../log.mjs";
 import { paths } from "../paths.mjs";
 
 const CONCURRENCY = 8;
 
+/** Font MIME — CDN'den HTML çapraz origin yüklerken CORS gerekir. */
+const FONT_MIME = new Set([
+  "font/woff",
+  "font/woff2",
+  "font/ttf",
+  "font/otf",
+  "application/font-woff",
+  "application/font-woff2",
+]);
+
 /** @type {Record<string, string>} */
 const MIME = {
   ".js": "application/javascript; charset=utf-8",
@@ -116,6 +126,7 @@ export function assetsUploadSkipReason(config) {
 /**
  * @param {import('../../config/index.js').ResolvedConfig} config
  * @param {{ put?: typeof putObject,
+ *   putCors?: typeof putBucketCors,
  *   resolveCredentials?: typeof resolveS3Credentials }} [options]
  * @returns {Promise<void>}
  */
@@ -135,6 +146,7 @@ export async function uploadAssets(config, options = {}) {
   }
 
   const put = options.put ?? putObject;
+  const putCors = options.putCors ?? putBucketCors;
   // Normalize bazen atlanır (test / elle config); önek `/` ile bitsin.
   let keyPrefix = (upload.keyPrefix || "").replace(/^\/+/, "");
   if (keyPrefix && !keyPrefix.endsWith("/")) keyPrefix += "/";
@@ -162,6 +174,27 @@ export async function uploadAssets(config, options = {}) {
     return;
   }
 
+  const uploadsFonts = jobs.some((job) =>
+    FONT_MIME.has(contentTypeFor(job.file)),
+  );
+  if (uploadsFonts && upload.corsOrigin) {
+    try {
+      await putCors({
+        bucket: upload.bucket,
+        region: upload.region,
+        endpoint: upload.endpoint,
+        credentials,
+        allowedOrigin: upload.corsOrigin,
+      });
+      log.detail(`cors ${upload.corsOrigin}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[assets] PutBucketCors failed (${message}) — set CDN/bucket CORS manually for cross-origin fonts`,
+      );
+    }
+  }
+
   let uploaded = 0;
   let index = 0;
 

package/src/build/tasks/css.mjs

@@ -24,6 +24,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { paths, writeAsset, writeManifest } from "../paths.mjs";
+import { rewriteCssStaticUrls } from "../rewrite-css-urls.mjs";
 import { importFromApp, tryImportFromApp } from "../resolve-peer.mjs";
 import * as log from "../../log.mjs";
 
@@ -85,6 +86,23 @@ function listPageStyles(dir) {
     .map((name) => path.join(dir, name));
 }
 
+/**
+ * `build.assets.prefix` doluysa `static.prefixes` kök-mutlak `url()` yollarını
+ * CDN'e çevirir (`/fonts/…` → `https://cdn…/js/fonts/…`).
+ *
+ * @param {string} css
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {string}
+ */
+function applyCdnStaticUrls(css, config) {
+  const prefix = config.build?.assets?.prefix ?? "";
+  if (!prefix) return css;
+  return rewriteCssStaticUrls(css, {
+    prefix,
+    prefixes: config.static?.prefixes ?? ["/assets/", "/fonts/"],
+  });
+}
+
 /**
  * @param {import('../../config/index.js').ResolvedConfig} config
  * @param {{ watch?: boolean }} [options]
@@ -101,7 +119,7 @@ export async function buildCss(config, { watch = false } = {}) {
     const urls = {};
     let bytes = 0;
 
-    const appCss = await compile(input);
+    const appCss = applyCdnStaticUrls(await compile(input), config);
     const appUrl = writeAsset("app.css", appCss);
     urls["app.css"] = appUrl;
     bytes += Buffer.byteLength(appCss);
@@ -111,7 +129,7 @@ export async function buildCss(config, { watch = false } = {}) {
 
     for (const file of listPageStyles(pagesDir)) {
       const name = path.basename(file);
-      const css = await compile(file);
+      const css = applyCdnStaticUrls(await compile(file), config);
       const url = writeAsset(name, css);
       urls[name] = url;
       bytes += Buffer.byteLength(css);

package/src/config/defaults.js

@@ -51,12 +51,17 @@ export const DEFAULT_DEV_GATE_BYPASS = [
 ];
 
 /**
- * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
- * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
- * linkleri ısıtma.
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` ve `prewarm: false`
+ * (on-demand) ile birlikte kullanılamaz — ya açılış/`prewarmPaths` turu, ya
+ * ziyaret edilen sayfadaki linkleri ısıtma, ya yalnızca ziyaret yazımı.
+ *
+ * `mode` çözümleme sonucu: `"classic"` | `"onVisit"` | `"off"`.
+ * `prewarm: false` → `"off"` (erken TTL ısıtması dahil hiçbir arka plan yok).
  */
 export const DEFAULT_PREWARM = {
   enabled: true,
+  /** @type {"classic" | "onVisit" | "off"} */
+  mode: "classic",
   max: 400,
   intervalSeconds: 0,
   /** Paralel ısıtma isteği; dev'de sunucu tek süreç olduğu için düşürülür. */
@@ -508,9 +513,19 @@ export const DEFAULT_BUILD = {
       keyPrefix: "",
       region: "us-east-1",
       endpoint: null,
-      /** `public/` altı dizin adları. */
-      include: /** @type {string[]} */ (["assets"]),
+      /**
+       * `public/` altı dizin adları. `fonts` varsayılan: CDN CSS'teki
+       * `/fonts/…` rewrite'ı upload nesnesiyle hizalansın.
+       */
+      include: /** @type {string[]} */ (["assets", "fonts"]),
       cacheControl: "public, max-age=31536000, immutable",
+      /**
+       * Upload sırasında PutBucketCors ile yazılan `AllowedOrigin`.
+       * `null` / `false` → CORS adımı atlanır. Bucket'taki önceki CORS
+       * kuralının üzerine yazar — paylaşımlı kovada bilinçli açın.
+       * CDN CSS + aynı host font için genelde gerekmez.
+       */
+      corsOrigin: /** @type {string | null} */ ("*"),
     },
   },
 };

package/src/config/index.js

@@ -184,6 +184,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {string | null} endpoint
  * @property {string[]} include
  * @property {string} cacheControl
+ * @property {string | null} corsOrigin Font/CDN PutBucketCors `AllowedOrigin`; `null` kapatır.
  *
  * @typedef {object} BuildAssetsConfig
  * @property {string} prefix CDN origin (`build.assets.prefix`); sonunda `/` yok.
@@ -939,18 +940,38 @@ function normalizeOnVisit(raw) {
 }
 
 /**
- * Klasik liste ısıtması ile `onVisit` karşılıklı dışlayıcıdır. İkisini birden
- * yazmak sessizce yanlış moda düşmesin diye yüklemede hata verir.
+ * Klasik liste ısıtması, `onVisit` ve `prewarm: false` (on-demand) karşılıklı
+ * dışlayıcıdır. Yanlış moda sessizce düşülmesin diye yüklemede hata verir.
  *
  * @param {unknown} raw
  * @returns {Record<string, unknown>}
  */
 function normalizePrewarm(raw) {
+  // On-demand: yalnızca ziyaret yazımı. Klasik / onVisit / early-expiry yok.
+  if (raw === false) {
+    return {
+      ...DEFAULT_PREWARM,
+      enabled: false,
+      mode: "off",
+      onVisit: { ...DEFAULT_PREWARM_ON_VISIT, enabled: false },
+    };
+  }
+
+  if (raw != null && (typeof raw !== "object" || Array.isArray(raw))) {
+    throw new Error(
+      "[config] cache().prewarm must be false, or an object " +
+        "(classic settings or { onVisit })",
+    );
+  }
+
   const source =
     raw && typeof raw === "object" && !Array.isArray(raw)
       ? /** @type {Record<string, unknown>} */ ({ ...raw })
       : {};
 
+  // `mode` çözümleme alanı; kullanıcı yazarsa yok sayılır.
+  delete source.mode;
+
   const onVisit = normalizeOnVisit(source.onVisit);
 
   if (onVisit.enabled) {
@@ -976,12 +997,15 @@ function normalizePrewarm(raw) {
     return {
       ...DEFAULT_PREWARM,
       enabled: true,
+      mode: "onVisit",
       onVisit,
     };
   }
 
   // Klasik mod: `onVisit: false` yazılmış olabilir; diğer alanlar varsayılanlarla
   // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
+  // `enabled: false` klasik turu keser ama early-expiry drain açık kalır —
+  // tamamen kapatmak için `prewarm: false` (`mode: "off"`) kullanılır.
   const classic = { ...source };
   delete classic.onVisit;
 
@@ -993,6 +1017,7 @@ function normalizePrewarm(raw) {
   return {
     ...DEFAULT_PREWARM,
     ...classic,
+    mode: "classic",
     onVisit,
   };
 }
@@ -1264,11 +1289,25 @@ export function normalizeBuildAssets(raw) {
     }
   }
 
+  // CDN CSS `/fonts/…` → prefix'li URL yazar; fontlar upload'ta yoksa 403.
+  // Kullanıcı `include: ["assets"]` yazsa bile prefix varken `fonts` eklenir.
+  if (prefix && !include.includes("fonts")) {
+    include = [...include, "fonts"];
+  }
+
   const cacheControl =
     typeof uploadRaw.cacheControl === "string" && uploadRaw.cacheControl.trim()
       ? uploadRaw.cacheControl.trim()
       : DEFAULT_BUILD.assets.upload.cacheControl;
 
+  /** @type {string | null} */
+  let corsOrigin = DEFAULT_BUILD.assets.upload.corsOrigin;
+  if (uploadRaw.corsOrigin === null || uploadRaw.corsOrigin === false) {
+    corsOrigin = null;
+  } else if (typeof uploadRaw.corsOrigin === "string") {
+    corsOrigin = uploadRaw.corsOrigin.trim() || null;
+  }
+
   // Config'te bucket varsa `enabled` unutulmuş olsa bile aç. Açık `false` ezer.
   const enabled =
     uploadRaw.enabled === true ||
@@ -1284,6 +1323,7 @@ export function normalizeBuildAssets(raw) {
       endpoint,
       include,
       cacheControl,
+      corsOrigin,
     },
   };
 }
@@ -1682,6 +1722,17 @@ export async function loadConfig(options = {}) {
     );
   }
 
+  if (
+    config.prewarm?.mode === "off" &&
+    typeof config.hooks?.prewarmPaths === "function"
+  ) {
+    throw new Error(
+      "[config] hooks.prewarmPaths() cannot be used with cache().prewarm: false. " +
+        "On-demand mode only caches pages as they are visited; classic mode uses " +
+        "prewarmPaths. Choose one.",
+    );
+  }
+
   // Dev'de build ve sunucu ayrı alt süreçler; üçü de aynı özeti basınca satır
   // banner'ın ve build bloğunun arasına üç kez giriyor. Özeti dış süreç basar.
   if (loaded && !process.env.JSKELET_CHILD) {

package/src/server/logs/s3-put.js

@@ -14,6 +14,9 @@ import crypto from "node:crypto";
  * @typedef {{ bucket: string, key: string, body: string | Buffer,
  *   region: string, endpoint?: string | null, credentials: AwsCredentials,
  *   contentType?: string, cacheControl?: string | null, now?: Date }} PutObjectInput
+ *
+ * @typedef {{ bucket: string, region: string, endpoint?: string | null,
+ *   credentials: AwsCredentials, allowedOrigin: string, now?: Date }} PutBucketCorsInput
  */
 
 /**
@@ -131,6 +134,24 @@ export function useS3PathStyle(bucket, endpoint) {
   return bucket.includes(".");
 }
 
+/**
+ * @param {{ bucket: string, region: string, endpoint?: string | null }} input
+ * @returns {{ host: string, base: string, pathStyle: boolean }}
+ */
+function s3EndpointParts(input) {
+  const pathStyle = useS3PathStyle(input.bucket, input.endpoint);
+  if (input.endpoint) {
+    const base = String(input.endpoint).replace(/\/+$/, "");
+    return { host: new URL(input.endpoint).host, base, pathStyle: true };
+  }
+  if (pathStyle) {
+    const host = `s3.${input.region}.amazonaws.com`;
+    return { host, base: `https://${host}`, pathStyle: true };
+  }
+  const host = `${input.bucket}.s3.${input.region}.amazonaws.com`;
+  return { host, base: `https://${host}`, pathStyle: false };
+}
+
 /**
  * PutObject isteğini imzalar; ağ çağrısı yapmaz — test edilebilir olsun diye.
  *
@@ -145,22 +166,7 @@ export function buildSignedPutObject(input) {
   const payloadHash = sha256Hex(body);
 
   const keyPath = encodeS3Path(input.key.replace(/^\/+/, ""));
-  const pathStyle = useS3PathStyle(input.bucket, input.endpoint);
-
-  /** @type {string} */
-  let host;
-  /** @type {string} */
-  let base;
-  if (input.endpoint) {
-    base = String(input.endpoint).replace(/\/+$/, "");
-    host = new URL(input.endpoint).host;
-  } else if (pathStyle) {
-    host = `s3.${input.region}.amazonaws.com`;
-    base = `https://${host}`;
-  } else {
-    host = `${input.bucket}.s3.${input.region}.amazonaws.com`;
-    base = `https://${host}`;
-  }
+  const { host, base, pathStyle } = s3EndpointParts(input);
 
   const canonicalUri = pathStyle
     ? `/${encodeS3Path(input.bucket)}/${keyPath}`
@@ -219,6 +225,132 @@ export function buildSignedPutObject(input) {
   return { url, headers, body };
 }
 
+/**
+ * PutBucketCors gövdesi — tek kural, GET/HEAD.
+ *
+ * @param {string} allowedOrigin
+ * @returns {string}
+ */
+export function corsConfigurationXml(allowedOrigin) {
+  const origin = String(allowedOrigin)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>` +
+    `<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">` +
+    `<CORSRule>` +
+    `<AllowedOrigin>${origin}</AllowedOrigin>` +
+    `<AllowedMethod>GET</AllowedMethod>` +
+    `<AllowedMethod>HEAD</AllowedMethod>` +
+    `<AllowedHeader>*</AllowedHeader>` +
+    `<ExposeHeader>ETag</ExposeHeader>` +
+    `<ExposeHeader>Content-Type</ExposeHeader>` +
+    `<MaxAgeSeconds>86400</MaxAgeSeconds>` +
+    `</CORSRule>` +
+    `</CORSConfiguration>`
+  );
+}
+
+/**
+ * PutBucketCors isteğini imzalar (`PUT /?cors` veya path-style `/bucket?cors`).
+ *
+ * @param {PutBucketCorsInput} input
+ * @returns {{ url: string, headers: Record<string, string>, body: Buffer }}
+ */
+export function buildSignedPutBucketCors(input) {
+  const body = Buffer.from(corsConfigurationXml(input.allowedOrigin), "utf8");
+  const now = input.now ?? new Date();
+  const { amzDate, dateStamp } = formatAmzDates(now);
+  const payloadHash = sha256Hex(body);
+  const { host, base, pathStyle } = s3EndpointParts(input);
+
+  // AWS: cors alt kaynağının canonical query'si `cors=` (boş değer).
+  const canonicalQuerystring = "cors=";
+  const canonicalUri = pathStyle ? `/${encodeS3Path(input.bucket)}` : "/";
+
+  /** @type {Record<string, string>} */
+  const headers = {
+    host,
+    "content-type": "application/xml",
+    "content-length": String(body.length),
+    "x-amz-content-sha256": payloadHash,
+    "x-amz-date": amzDate,
+  };
+
+  if (input.credentials.sessionToken) {
+    headers["x-amz-security-token"] = input.credentials.sessionToken;
+  }
+
+  const { canonicalRequest, signedHeaders } = buildCanonicalRequest({
+    method: "PUT",
+    canonicalUri,
+    canonicalQuerystring,
+    headers,
+    payloadHash,
+  });
+
+  const stringToSign = buildStringToSign({
+    amzDate,
+    dateStamp,
+    region: input.region,
+    service: "s3",
+    canonicalRequest,
+  });
+
+  const signingKey = deriveSigningKey(
+    input.credentials.secretAccessKey,
+    dateStamp,
+    input.region,
+    "s3",
+  );
+  const signature = hmac("sha256", signingKey, stringToSign).toString("hex");
+  const credentialScope = `${dateStamp}/${input.region}/s3/aws4_request`;
+
+  headers.authorization =
+    `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${credentialScope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  const url = pathStyle
+    ? `${base}/${encodeS3Path(input.bucket)}?cors`
+    : `${base}/?cors`;
+
+  return { url, headers, body };
+}
+
+/**
+ * Bucket CORS yazar. Mevcut kuralların **üzerine** yazar; paylaşımlı
+ * kovada bilinçli kullanılmalı. İzin yoksa çağıran uyarır, upload sürer.
+ *
+ * @param {PutBucketCorsInput} input
+ * @returns {Promise<void>}
+ */
+export async function putBucketCors(input) {
+  const signed = buildSignedPutBucketCors(input);
+  /** @type {Response} */
+  let response;
+  try {
+    response = await fetch(signed.url, {
+      method: "PUT",
+      headers: signed.headers,
+      body: signed.body,
+    });
+  } catch (error) {
+    const detail =
+      error instanceof Error ? error.message : String(error);
+    throw new Error(`S3 PutBucketCors fetch failed (${signed.url}): ${detail}`);
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(
+      `S3 PutBucketCors ${response.status}: ${text.slice(0, 200) || response.statusText}`,
+    );
+  }
+}
+
 /**
  * @param {PutObjectInput} input
  * @returns {Promise<void>}

package/src/server/prewarm.js

@@ -928,6 +928,8 @@ async function drainVisitWarm() {
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
  * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
  * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
+ * `prewarm: false` (`mode: "off"`) on-demand: ziyaret yazımı kalır, hiçbir
+ * arka plan ısıtması kurulmaz; `PREWARM=1` bunu ezmez.
  *
  * @param {{ port: number }} options
  * @returns {void}
@@ -935,12 +937,14 @@ async function drainVisitWarm() {
 export function startPrewarm({ port }) {
   const config = getConfig();
   if (process.env.PREWARM === "0") return;
+  // On-demand: L1/L2 ziyaretle dolar; classic / onVisit / early-expiry yok.
+  if (config.prewarm?.mode === "off") return;
 
   const origins = resolvePrewarmOrigins(port);
   const origin = origins[0];
 
   // Klasik `prewarmPaths` olmasa da TTL öncesi soft-bayatlayan girdiler
-  // HTTP ile ısıtılsın. `PREWARM=0` yukarıda her şeyi keser.
+  // HTTP ile ısıtılsın. `PREWARM=0` / `mode: "off"` yukarıda her şeyi keser.
   startEarlyExpirySweep();
   startExpiryWarmDrain(origins);
 

package/types/config/defaults.d.ts

@@ -40,12 +40,17 @@ export declare const DEFAULT_STATIC: {
 /** Dev gate'in hiçbir koşulda kapatmadığı yollar. */
 export declare const DEFAULT_DEV_GATE_BYPASS: string[];
 /**
- * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
- * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
- * linkleri ısıtma.
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` ve `prewarm: false`
+ * (on-demand) ile birlikte kullanılamaz — ya açılış/`prewarmPaths` turu, ya
+ * ziyaret edilen sayfadaki linkleri ısıtma, ya yalnızca ziyaret yazımı.
+ *
+ * `mode` çözümleme sonucu: `"classic"` | `"onVisit"` | `"off"`.
+ * `prewarm: false` → `"off"` (erken TTL ısıtması dahil hiçbir arka plan yok).
  */
 export declare const DEFAULT_PREWARM: {
     enabled: boolean;
+    /** @type {"classic" | "onVisit" | "off"} */
+    mode: "classic" | "onVisit" | "off";
     max: number;
     intervalSeconds: number;
     /** Paralel ısıtma isteği; dev'de sunucu tek süreç olduğu için düşürülür. */
@@ -458,9 +463,19 @@ export declare const DEFAULT_BUILD: {
             keyPrefix: string;
             region: string;
             endpoint: null;
-            /** `public/` altı dizin adları. */
+            /**
+             * `public/` altı dizin adları. `fonts` varsayılan: CDN CSS'teki
+             * `/fonts/…` rewrite'ı upload nesnesiyle hizalansın.
+             */
             include: string[];
             cacheControl: string;
+            /**
+             * Upload sırasında PutBucketCors ile yazılan `AllowedOrigin`.
+             * `null` / `false` → CORS adımı atlanır. Bucket'taki önceki CORS
+             * kuralının üzerine yazar — paylaşımlı kovada bilinçli açın.
+             * CDN CSS + aynı host font için genelde gerekmez.
+             */
+            corsOrigin: string | null;
         };
     };
 };

package/types/config/index.d.ts

@@ -240,6 +240,10 @@ export type BuildAssetsUploadConfig = {
     endpoint: string | null;
     include: string[];
     cacheControl: string;
+    /**
+     * Font/CDN PutBucketCors `AllowedOrigin`; `null` kapatır.
+     */
+    corsOrigin: string | null;
 };
 export type BuildAssetsConfig = {
     /**

package/types/server/logs/s3-put.d.ts

@@ -14,6 +14,14 @@ export type PutObjectInput = {
     cacheControl?: string | null;
     now?: Date;
 };
+export type PutBucketCorsInput = {
+    bucket: string;
+    region: string;
+    endpoint?: string | null;
+    credentials: AwsCredentials;
+    allowedOrigin: string;
+    now?: Date;
+};
 /**
  * @param {string | Buffer} data
  * @returns {string}
@@ -91,6 +99,32 @@ export declare function buildSignedPutObject(input: PutObjectInput): {
     headers: Record<string, string>;
     body: Buffer;
 };
+/**
+ * PutBucketCors gövdesi — tek kural, GET/HEAD.
+ *
+ * @param {string} allowedOrigin
+ * @returns {string}
+ */
+export declare function corsConfigurationXml(allowedOrigin: string): string;
+/**
+ * PutBucketCors isteğini imzalar (`PUT /?cors` veya path-style `/bucket?cors`).
+ *
+ * @param {PutBucketCorsInput} input
+ * @returns {{ url: string, headers: Record<string, string>, body: Buffer }}
+ */
+export declare function buildSignedPutBucketCors(input: PutBucketCorsInput): {
+    url: string;
+    headers: Record<string, string>;
+    body: Buffer;
+};
+/**
+ * Bucket CORS yazar. Mevcut kuralların **üzerine** yazar; paylaşımlı
+ * kovada bilinçli kullanılmalı. İzin yoksa çağıran uyarır, upload sürer.
+ *
+ * @param {PutBucketCorsInput} input
+ * @returns {Promise<void>}
+ */
+export declare function putBucketCors(input: PutBucketCorsInput): Promise<void>;
 /**
  * @param {PutObjectInput} input
  * @returns {Promise<void>}

package/types/server/prewarm.d.ts

@@ -122,6 +122,8 @@ export declare function noteVisitWarm(html: string, context: {
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
  * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
  * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
+ * `prewarm: false` (`mode: "off"`) on-demand: ziyaret yazımı kalır, hiçbir
+ * arka plan ısıtması kurulmaz; `PREWARM=1` bunu ezmez.
  *
  * @param {{ port: number }} options
  * @returns {void}