jskelet 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -10,6 +10,25 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- HTML cache key vary (`cache().vary`): `host: true` adds the public Host
+  (`x-forwarded-host` or `Host`, lowercase, no port) as `h=…|` before the path;
+  optional `headers` and `fn(req)` add further segments. Required on host-based
+  locale sites so one locale's HTML is not served on another. Classic prewarm
+  accepts `prewarm.origins` for multi-host warming when vary is on.
+
+### Changed
+
+- Marketing example visual language: darker ink canvas, solid cyan primary
+  CTAs, cyan-only glow/grid (indigo accents removed), and a measured trust
+  bar on the homepage (payload gzip, Node, license, zero web fonts) instead
+  of the marquee.
+
+### Added
+
+- Dynamic Open Graph images (Next.js `ImageResponse` / `opengraph-image`):
+  `ogImage`, `sendOgImage`, `ogHandler`, and `ImageResponse` turn card fields or
+  raw SVG into PNG when `sharp` is installed (SVG fallback otherwise). Wired in
+  `examples/blog` as `/og/blog/:slug.png` and `metadata.openGraph.image`.
 - Early HTML cache refresh before TTL expiry: the last successful produce time
   (`produceMs`) sets a lead window (`min(max(produceMs×2, 250ms), ttl/2)`). A
   still-fresh `HIT` in that window revalidates in the background; idle entries

package/docs/03-routing.md

@@ -35,6 +35,10 @@ gerekmez:
 | `redirect` | `jskelet` → `redirect` |
 | `permanentRedirect` | `jskelet` → `permanentRedirect` |
 | `seeOther` | `jskelet` → `seeOther` |
+| `ogHandler` | `jskelet` → `ogHandler` |
+| `ogImage` | `jskelet` → `ogImage` |
+| `sendOgImage` | `jskelet` → `sendOgImage` |
+| `ImageResponse` | `jskelet` → `ImageResponse` |
 
 İstersen doğrudan import da edebilirsin; `api` yalnızca kolaylık:
 

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

@@ -511,6 +511,64 @@ return {
 `renderHeadMeta(metadata)` fonksiyonu dışa açıktır; layout dışında (ör. bir
 fragment ya da e-posta) aynı etiketleri üretmek gerekirse kullanılabilir.
 
+## Dinamik OG görselleri
+
+Next.js `ImageResponse` / `opengraph-image.tsx` karşılığı. JSX yok: kart
+alanları (`title`, `description`, `siteName`, renkler) ya da ham `svg` verilir.
+`sharp` (opsiyonel peer) kuruluysa PNG, yoksa SVG döner. Sosyal kazıyıcıların
+çoğu PNG beklediği için prod'da `sharp` önerilir.
+
+HTML değil görsel döndüğü için `route()` kullanılmaz — `ogHandler` düz bir
+Express handler üretir. `notFound()` ve `null` dönüşü 404 olur.
+
+```js
+// routes/35-og.mjs
+export default function register(app, { ogHandler, notFound }) {
+  app.get(
+    "/og/blog/:slug.png",
+    ogHandler(async ({ params }) => {
+      const post = getPost(params.slug);
+      if (!post) notFound();
+      return {
+        title: post.title,
+        description: post.excerpt,
+        siteName: "Blog",
+      };
+    }),
+  );
+}
+```
+
+Sayfa metadata'sında mutlak URL ve boyut verin:
+
+```js
+openGraph: {
+  type: "article",
+  image: `${SITE_URL}/og/blog/${post.slug}.png`,
+  imageWidth: 1200,
+  imageHeight: 630,
+},
+```
+
+Ham SVG veya Next benzeri sınıf:
+
+```js
+import { ImageResponse, sendOgImage, OG_SIZE } from "jskelet";
+
+app.get("/og/custom.png", async (req, res) => {
+  const image = new ImageResponse(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">…</svg>`,
+    OG_SIZE,
+  );
+  await image.send(res);
+  // veya: await sendOgImage(res, { title: "…", format: "svg" });
+});
+```
+
+Varsayılan `Cache-Control`:
+`public, max-age=0, s-maxage=86400, stale-while-revalidate=604800`.
+`cacheControl` seçeneğiyle ezilir. Çalışan örnek: `examples/blog/routes/35-og.mjs`.
+
 ## Hook'lar
 
 Hook'lar `jskelet.config.mjs` → `hooks` altında tanımlanır. Hepsi opsiyonel,

package/docs/06-cache.md

@@ -43,8 +43,9 @@ sayfa da ilk ziyaretçide milisaniyeler içinde üretilir ve kota harcamaz.
 ## Public ve kişiye özel ayrımı
 
 Bu belgedeki her şey **herkese aynı gidebilen** HTML için geçerli. Cache
-anahtarında kimlik yok (yalnızca yol + query), yani önbellekteki bir sayfa onu
-ilk isteyen kişinin değil, o yolun cevabıdır.
+anahtarında kimlik yok (yalnızca yol + query + isteğe bağlı `vary`); yani
+önbellekteki bir sayfa onu ilk isteyen kişinin değil, o yolun (ve vary
+parçalarının) cevabıdır.
 
 Kullanıcıya bağlı bir sayfa bu yüzden ayrı bir yoldan geçer:
 
@@ -110,13 +111,14 @@ saklayabiliyordu.
 ## Cache anahtarı
 
 ```
-`${yol}?${izin verilen query parametreleri, sıralı}`
+`${varyPrefix}${yol}?${izin verilen query parametreleri, sıralı}`
 ```
 
-Query'siz bir istek için anahtar yalnızca yoldur. **Query parametresi taşıyan
-istek varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private,
-no-store` ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
-gibi sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
+`varyPrefix` varsayılan olarak boştur. Query'siz bir istek için anahtar
+`${varyPrefix}${yol}?` biçimindedir. **Query parametresi taşıyan istek
+varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private, no-store`
+ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…` gibi
+sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
 sayfaları kampanya varyantları için dışarı atıyor.
 
 Hangi parametrenin çıktıyı gerçekten değiştirdiğini uygulama bildirir —
@@ -135,6 +137,48 @@ Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (dikkat: gir
 sayısını sınırlayan tek şey `maxEntries` olur), `[]` ile eşlenirse query tamamen
 yok sayılır. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
+### Host / locale: `cache().vary`
+
+CDN zaten tam URL ile ayırır; asıl risk **origin L1** ve Redis HTML anahtarıdır.
+Host'tan locale üreten sitelerde (`tr.example.com` / `en.example.com`) vary
+olmadan ilk locale'in HTML'i diğer host'a servis edilir — Express 5'te istek
+nesnesine locale yazmak kırılgan bir kaçış yoludur.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, portsuz
+    host: true,
+    // veya özel:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Örnek anahtarlar: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Alan | Tip | Anlamı |
+| --- | --- | --- |
+| `host` | `boolean` | Public Host'u `h=…` olarak anahtara ekler |
+| `headers` | `string[]` | Verilen istek başlıklarını (`ad=değer`) ekler |
+| `fn` | `(req) => string \| null` | Dönüş değeri bir segment olarak eklenir (tam kontrol) |
+
+**Prewarm:** varsayılan ısıtma `http://127.0.0.1:<port>` üzerinden gider. 
+`vary.host` açıksa bu yalnızca loopback anahtarını ısıtır; locale sitelerinde
+çoklu origin gerekir:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+Port yazılmazsa dinleme portu eklenir. `onVisit` modunda ısıtma, vary açıkken
+ziyaretçinin `Host` başlığını kullanır.
+
 ## Stale-while-revalidate
 
 Girdi yapısı:
@@ -771,7 +815,7 @@ her istek ağ zaman aşımı beklemez.
 ### Anahtar düzeni
 
 ```
-_jskelet:{namespace}:{buildId}:html:{yol}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}
 _jskelet:{namespace}:{buildId}:data:{anahtar}
 _jskelet:{namespace}:events
 ```
@@ -1074,9 +1118,12 @@ da trafik geldikçe (`onVisit`) yapılır. Kazanç aynı — tıklanan / komşu
 soğuk render'ı beklemez — fakat veri dondurulmaz; her girdi route'un
 `revalidate` süresiyle yaşlanır ve stale-while-revalidate ile arkada tazelenir.
 
-Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>`), çünkü
-cache anahtarı, sıkıştırma ve middleware zinciri normal trafikle bire bir aynı
-olsun.
+Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>` ya da
+`cache().prewarm.origins`), çünkü cache anahtarı, sıkıştırma ve middleware
+zinciri normal trafikle bire bir aynı olsun. `vary.host` açıksa varsayılan
+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
@@ -1336,6 +1383,10 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   fazla `revalidate` + bir tazeleme turudur.
 - **Önbellek şişiyor.** Query parametreleri anahtara girdiği için kampanya
   parametreleri girdi çoğaltıyor olabilir.
+- **Yanlış dil / host HTML'i geliyor.** Host'tan locale üreten bir sitede
+  `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`
   modunda `listen` sonrası logda `onVisit mode` satırını ve public cache'li

package/docs/07-yapilandirma.md

@@ -614,9 +614,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, 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 }` —
 **Varsayılan:**
-`{ html: {}, query: {}, 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 } }`
+`{ html: {}, 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: [] } }`
 
 ### `cache().html`
 
@@ -671,6 +671,30 @@ Parametreler anahtara **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı gi
 paylaşır. `route(fn, { private: true })` bu bölümden etkilenmez; private route
 hiçbir koşulda cache'lenmez.
 
+### `cache().vary`
+
+HTML cache anahtarına query allowlist'ten **bağımsız** sabit parçalar ekler.
+Host'tan locale üreten sitelerde `host: true` **zorunlu**; aksi halde ilk
+locale'in HTML'i diğer host'a servis edilir. CDN zaten tam URL ile ayırır —
+bu ayar origin L1 ve Redis HTML anahtarı içindir.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` yoksa `Host`), lowercase, portsuz → `h=…` |
+| `headers` | `string[]` | `[]` | İstek başlıkları `ad=değer` olarak eklenir |
+| `fn` | `(req) => string \| null` | — | Dönüş bir segment olarak eklenir |
+
+Anahtar biçimi: `${vary}|${yol}?${query}` (vary yoksa önek yok). Ayrıntı:
+[06-cache.md](./06-cache.md).
+
 ### `cache().maxEntries`
 
 **Tip:** `number` — **Varsayılan:** `500`
@@ -900,6 +924,7 @@ sayfadaki linkler). Birlikte verilemez — config yüklenirken hata.
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
 | `rotate` | `boolean` | `true` | Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder |
 | `priority` | `(string \| RegExp)[]` | `[]` | Isıtma sırası; eşleşen yollar her turda başa alınır |
+| `origins` | `string[]` | `[]` | Klasik turda ısıtılacak origin'ler. Boşsa `http://127.0.0.1:<port>`. `vary.host` açıksa locale host'ları buraya yazın |
 
 `priority` iki biçim kabul eder: config'in her yerinde geçerli olan desen
 sözdizimi ve doğrudan `RegExp`. Önce yazılan önce ısınır.
@@ -909,6 +934,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // vary.host açıksa loopback tek başına yetmez:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // ana sayfa
     "/piyasalar/:path*",      // tüm piyasa bölümü

package/docs/11-tasima.md

@@ -40,6 +40,7 @@ alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()
 | `loading.js` / Suspense | — | Sunucu HTML'i tam; iskelet gerekmiyor |
 | Streaming SSR | — | Yanıt tek parça |
 | `generateMetadata()` | Controller `metadata` + `hooks.metadata()` | Aynı alan adları ([04](./04-render-ve-sablonlar.md)) |
+| `opengraph-image.tsx` / `ImageResponse` | `ogHandler` + `ImageResponse` / `sendOgImage` | SVG veya kart alanları → PNG (`sharp`); [04](./04-render-ve-sablonlar.md) |
 | `generateStaticParams()` | `hooks.prewarmPaths()` | Build zamanı değil, açılış zamanı ısıtma |
 | Route Handlers (`route.js`) | Düz Express handler'ı | `app.get/post(...)` |
 | Middleware (`middleware.ts`) | Express middleware + config `rewrites`/`headers`/`redirects` | `app.use(...)` |
@@ -68,6 +69,7 @@ başlığı elle okuyun.
 | `next/link` | `link({ href, text })` — `jskelet/tags` | `title` otomatik, dış bağlantıya `rel`/`target` otomatik |
 | `next/link` prefetch'i | `navigation: { prefetch, prerender }` | Speculation Rules; client runtime'ı yok ([07](./07-yapilandirma.md)) |
 | `next/image` | `image({ src, alt, priority })` — `jskelet/tags` | `srcset` build manifest'inden |
+| `next/og` `ImageResponse` | `ImageResponse` / `ogHandler` — `jskelet` | JSX yok; SVG veya `title`/`description` kartı |
 | `next/font/google` | `fonts: [{ family, weights }]` | Self-host woff2, commit edilir |
 | `@phosphor-icons/react` | `icon({ name, weight })` — `jskelet/tags` | Build zamanı SVG sprite |
 | `react-dom` preconnect/preload | `preconnect: [...]` + `headHints()` | ([04](./04-render-ve-sablonlar.md)) |

package/docs/README.md

@@ -57,8 +57,9 @@ npm --prefix examples/minimal run dev
 
 **`examples/blog/`** — dinamik route (`/blog/:slug`), etiket sayfaları,
 `redirects`/`rewrites`/`headers`/`cache` yapılandırmasının tamamı, fragment ile
-gelen sekme panelleri, form gönderimi, prewarm, `robots.txt`/`sitemap.xml`/`rss.xml`
-ve dört island (tema, sekme, arama, form).
+gelen sekme panelleri, form gönderimi, prewarm, `robots.txt`/`sitemap.xml`/`rss.xml`,
+dinamik OG görselleri (`/og/blog/:slug.png`) ve dört island (tema, sekme, arama,
+form).
 
 ```bash
 npm --prefix examples/blog install

package/docs/en/03-routing.md

@@ -36,6 +36,10 @@ don't have to import things one by one in every file:
 | `redirect` | `jskelet` → `redirect` |
 | `permanentRedirect` | `jskelet` → `permanentRedirect` |
 | `seeOther` | `jskelet` → `seeOther` |
+| `ogHandler` | `jskelet` → `ogHandler` |
+| `ogImage` | `jskelet` → `ogImage` |
+| `sendOgImage` | `jskelet` → `sendOgImage` |
+| `ImageResponse` | `jskelet` → `ImageResponse` |
 
 You can also import directly if you prefer; `api` is only a convenience:
 

package/docs/en/04-rendering.md

@@ -522,6 +522,64 @@ The `renderHeadMeta(metadata)` function is exported; it can be used when you
 need to produce the same tags outside the layout (for example in a fragment or
 an email).
 
+## Dynamic OG images
+
+Counterpart to Next.js `ImageResponse` / `opengraph-image.tsx`. There is no JSX:
+pass card fields (`title`, `description`, `siteName`, colours) or a raw `svg`.
+With the optional `sharp` peer installed the response is PNG; otherwise SVG.
+Most social scrapers expect PNG, so install `sharp` in production.
+
+Because the response is an image, not HTML, do not use `route()` — `ogHandler`
+returns a plain Express handler. `notFound()` and a `null` return yield 404.
+
+```js
+// routes/35-og.mjs
+export default function register(app, { ogHandler, notFound }) {
+  app.get(
+    "/og/blog/:slug.png",
+    ogHandler(async ({ params }) => {
+      const post = getPost(params.slug);
+      if (!post) notFound();
+      return {
+        title: post.title,
+        description: post.excerpt,
+        siteName: "Blog",
+      };
+    }),
+  );
+}
+```
+
+Point page metadata at the absolute URL and size:
+
+```js
+openGraph: {
+  type: "article",
+  image: `${SITE_URL}/og/blog/${post.slug}.png`,
+  imageWidth: 1200,
+  imageHeight: 630,
+},
+```
+
+Raw SVG or a Next-like class:
+
+```js
+import { ImageResponse, sendOgImage, OG_SIZE } from "jskelet";
+
+app.get("/og/custom.png", async (req, res) => {
+  const image = new ImageResponse(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">…</svg>`,
+    OG_SIZE,
+  );
+  await image.send(res);
+  // or: await sendOgImage(res, { title: "…", format: "svg" });
+});
+```
+
+Default `Cache-Control`:
+`public, max-age=0, s-maxage=86400, stale-while-revalidate=604800`.
+Override with `cacheControl`. Working example: `examples/blog/routes/35-og.mjs`.
+
 ## Hooks
 
 Hooks are defined in `jskelet.config.mjs` under `hooks`. They are all optional

package/docs/en/06-caching.md

@@ -46,9 +46,9 @@ milliseconds on the first visit, and spends no quota.
 ## Public versus per-visitor
 
 Everything in this document applies to HTML that **can go to everyone
-unchanged**. There is no identity in the cache key (only path + query), so a
-page in the cache is the answer for that path, not the answer for whoever asked
-for it first.
+unchanged**. There is no identity in the cache key (only path + query + optional
+`vary`), so a page in the cache is the answer for that path (and vary parts),
+not the answer for whoever asked for it first.
 
 A page that depends on the user therefore takes a separate path:
 
@@ -117,14 +117,15 @@ The cache also only kicks in for `GET` requests.
 ## The cache key
 
 ```
-`${path}?${the allowed query parameters, sorted}`
+`${varyPrefix}${path}?${the allowed query parameters, sorted}`
 ```
 
-For a request without a query the key is just the path. **A request that carries
-a query parameter is dynamic by default**: it never enters the cache and is sent
-with `private, no-store`. Caching every variant of a path mints an unbounded
-number of keys (`?utm_source=…` and friends), and in a 500-entry store LRU then
-evicts the real pages in favour of campaign variants.
+`varyPrefix` is empty by default. For a request without a query the key is
+`${varyPrefix}${path}?`. **A request that carries a query parameter is dynamic
+by default**: it never enters the cache and is sent with `private, no-store`.
+Caching every variant of a path mints an unbounded number of keys
+(`?utm_source=…` and friends), and in a 500-entry store LRU then evicts the
+real pages in favour of campaign variants.
 
 Which parameter actually changes the output is declared by the application, in
 `jskelet.config.mjs` → `cache().query`:
@@ -143,6 +144,49 @@ the key (careful: nothing but `maxEntries` then bounds the entry count), and one
 mapped to `[]` ignores the query entirely. Details:
 [07-configuration.md](./07-configuration.md).
 
+### Host / locale: `cache().vary`
+
+A CDN already separates by full URL; the real risk is the **origin L1** and the
+Redis HTML key. On sites that derive locale from the host
+(`tr.example.com` / `en.example.com`), without vary the first locale's HTML is
+served to the other host — mutating the request object for locale is a fragile
+workaround under Express 5.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, no port
+    host: true,
+    // or custom:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Example keys: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `host` | `boolean` | Adds the public Host as `h=…` |
+| `headers` | `string[]` | Adds the given request headers as `name=value` |
+| `fn` | `(req) => string \| null` | Appends the return value as a segment (full control) |
+
+**Prewarm:** the default warm-up goes through `http://127.0.0.1:<port>`. With
+`vary.host` that only warms the loopback key; locale sites need multiple
+origins:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+If no port is written, the listen port is added. In `onVisit` mode, when vary
+is on, warming uses the visitor's `Host` header.
+
 ## Stale-while-revalidate
 
 The entry structure:
@@ -788,7 +832,7 @@ five consecutive failures, so requests do not each wait for a network timeout.
 ### Key layout
 
 ```
-_jskelet:{namespace}:{buildId}:html:{path}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}
 _jskelet:{namespace}:{buildId}:data:{key}
 _jskelet:{namespace}:events
 ```
@@ -1075,8 +1119,11 @@ but the data is not frozen; every entry ages with the route's `revalidate` and
 is refreshed in the background with stale-while-revalidate.
 
 The warm-up is done with **real HTTP requests**
-(`http://127.0.0.1:<port>`), so that the cache key, the compression and the
-middleware chain are exactly the same as with normal traffic.
+(`http://127.0.0.1:<port>` or `cache().prewarm.origins`), so that the cache key,
+the compression and the middleware chain are exactly the same as with normal
+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
@@ -1339,6 +1386,10 @@ filled the cache.
   lag is at most `revalidate` + one refresh round.
 - **The cache is bloating.** Because query parameters go into the key, campaign
   parameters may be multiplying entries.
+- **Wrong language / host HTML.** On a site that derives locale from the host,
+  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
   defined, `PREWARM=0` is set, or `cache().prewarm.enabled === false`. In
   `onVisit` mode check the `onVisit mode` log line after `listen` and that a

package/docs/en/07-configuration.md

@@ -627,9 +627,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, 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 }` —
 **Default:**
-`{ html: {}, query: {}, 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 } }`
+`{ html: {}, 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: [] } }`
 
 ### `cache().html`
 
@@ -684,6 +684,31 @@ Parameters are written into the key **sorted**, so `?a=1&b=2` and `?b=2&a=1`
 share one entry. `route(fn, { private: true })` is unaffected by this section; a
 private route is never cached under any condition.
 
+### `cache().vary`
+
+Adds fixed segments to the HTML cache key **independently** of the query
+allowlist. On sites that derive locale from the host, `host: true` is
+**required**; otherwise the first locale's HTML is served to the other host. A
+CDN already separates by full URL — this setting is for the origin L1 and the
+Redis HTML key.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` else `Host`), lowercase, no port → `h=…` |
+| `headers` | `string[]` | `[]` | Request headers added as `name=value` |
+| `fn` | `(req) => string \| null` | — | Return value appended as a segment |
+
+Key shape: `${vary}|${path}?${query}` (no prefix when vary is empty). Details:
+[06-caching.md](./06-caching.md).
+
 ### `cache().maxEntries`
 
 **Type:** `number` — **Default:** `500`
@@ -920,6 +945,7 @@ page just visited). They cannot be combined — config load throws.
 | `intervalSeconds` | `number` | `0` | If greater than 0, the pass repeats periodically |
 | `rotate` | `boolean` | `true` | If the list is longer than `max`, periodic passes continue where they left off |
 | `priority` | `(string \| RegExp)[]` | `[]` | Warm-up order; matching paths are taken first on every pass |
+| `origins` | `string[]` | `[]` | Origins for the classic pass. Empty → `http://127.0.0.1:<port>`. With `vary.host`, list the locale hosts here |
 
 `priority` accepts two forms: the pattern syntax used everywhere in the config,
 and a plain `RegExp`. Whatever is written first is warmed first.
@@ -929,6 +955,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // with vary.host, loopback alone is not enough:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // the home page
     "/markets/:path*",        // the whole markets section

package/docs/en/11-migration.md

@@ -41,6 +41,7 @@ will feel familiar. The *reasons* behind the differences are in
 | `loading.js` / Suspense | — | The server HTML is complete; no skeleton needed |
 | Streaming SSR | — | The response is a single chunk |
 | `generateMetadata()` | Controller `metadata` + `hooks.metadata()` | Same field names ([04](./04-rendering.md)) |
+| `opengraph-image.tsx` / `ImageResponse` | `ogHandler` + `ImageResponse` / `sendOgImage` | SVG or card fields → PNG (`sharp`); [04](./04-rendering.md) |
 | `generateStaticParams()` | `hooks.prewarmPaths()` | Warming at startup time, not build time |
 | Route Handlers (`route.js`) | A plain Express handler | `app.get/post(...)` |
 | Middleware (`middleware.ts`) | Express middleware + config `rewrites`/`headers`/`redirects` | `app.use(...)` |
@@ -69,6 +70,7 @@ header manually.
 | `next/link` | `link({ href, text })` — `jskelet/tags` | `title` automatic, `rel`/`target` automatic for external links |
 | `next/link` prefetching | `navigation: { prefetch, prerender }` | Speculation Rules; no client runtime ([07](./07-configuration.md)) |
 | `next/image` | `image({ src, alt, priority })` — `jskelet/tags` | `srcset` from the build manifest |
+| `next/og` `ImageResponse` | `ImageResponse` / `ogHandler` — `jskelet` | No JSX; SVG or `title`/`description` card |
 | `next/font/google` | `fonts: [{ family, weights }]` | Self-hosted woff2, committed |
 | `@phosphor-icons/react` | `icon({ name, weight })` — `jskelet/tags` | Build-time SVG sprite |
 | `react-dom` preconnect/preload | `preconnect: [...]` + `headHints()` | ([04](./04-rendering.md)) |

package/docs/en/README.md

@@ -62,8 +62,8 @@ npm --prefix examples/minimal run dev
 **`examples/blog/`** — a dynamic route (`/blog/:slug`), tag pages, the whole of
 the `redirects`/`rewrites`/`headers`/`cache` configuration, tab panels arriving
 as fragments, form submission, prewarm,
-`robots.txt`/`sitemap.xml`/`rss.xml` and four islands (theme, tabs, search,
-form).
+`robots.txt`/`sitemap.xml`/`rss.xml`, dynamic OG images (`/og/blog/:slug.png`)
+and four islands (theme, tabs, search, form).
 
 ```bash
 npm --prefix examples/blog install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",

package/src/config/defaults.js

@@ -87,6 +87,13 @@ export const DEFAULT_PREWARM = {
    * @type {(string | RegExp)[]}
    */
   priority: [],
+  /**
+   * Klasik turda ısıtılacak origin listesi. Boşsa `http://127.0.0.1:<port>`.
+   * `cache().vary.host` açıkken locale host'ları buraya yazılmazsa yalnızca
+   * loopback anahtarı ısınır.
+   * @type {string[]}
+   */
+  origins: [],
 };
 
 /**
@@ -122,6 +129,7 @@ export const CLASSIC_PREWARM_KEYS = [
   "retryDelayMs",
   "rotate",
   "priority",
+  "origins",
 ];
 
 /**