jskelet 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -10,6 +10,16 @@ one is listed under a **Breaking** heading.
 
 ### 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
+  are soft-staled by a sweeper and drained over HTTP even without classic
+  `prewarmPaths` (`PREWARM=0` disables both). In-flight refreshes no longer drop
+  the entry when `staleUntil` elapses.
 - Route-level stylesheets: put files in `styles/pages/*.css` and load them from
   the controller with `styles: ["home.css"]` (same contract as island
   `entries`). The layout emits them after global `app.css`; dev hot-swaps any

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

@@ -142,15 +142,29 @@ Girdi yapısı:
 ```
 expiresAt  = now + ttl
 staleUntil = now + ttl * 2      (STALE_FACTOR = 1)
+produceMs  = son başarılı üretimin süresi (ms)
 ```
 
 Okuma davranışı:
 
 | Durum | Yanıt | Arka plan |
 | --- | --- | --- |
-| `now < expiresAt` | Önbellekteki HTML, `HIT` | — |
+| `now < expiresAt - leadMs` | Önbellekteki HTML, `HIT` | — |
+| `expiresAt - leadMs ≤ now < expiresAt` | Önbellekteki HTML, `HIT` | **Erken tazeleme** başlar |
 | `expiresAt ≤ now < staleUntil` | Önbellekteki HTML **anında**, `STALE` | Tazeleme başlatılır |
-| `now ≥ staleUntil` | Girdi silinir, taze render, `MISS` | — |
+| `now ≥ staleUntil` | Girdi silinir, taze render, `MISS` (uçuştaki tazeleme varken silinmez) | — |
+
+`leadMs` sayfanın load süresini hesaba katar:
+
+```
+leadMs = min(max(produceMs * 2, 250ms), ttl / 2)
+```
+
+Böylece yavaş bir sayfa TTL dolduğu anda hâlâ soğuk render'a düşmez: taze
+HTML çoğu zaman `expiresAt` gelmeden yazılmış olur. Trafik yoksa bir sweeper
+aynı pencerede girdiyi soft-bayatlatır ve ısıtma kuyruğuna alır; `startPrewarm`
+( `PREWARM=0` değilse) kuyruğu HTTP ile boşaltır — klasik `prewarmPaths`
+olmasa da.
 
 Stale penceresinde tazelemenin hatası isteği etkilemez: eski HTML pencere
 boyunca geçerli kalır ve hata yalnızca loglanır

package/docs/07-yapilandirma.md

@@ -622,7 +622,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 
 Desen → saniye eşlemesi. Eşleşen kural, route'un kendi `revalidate` değerini
 **ezer**. Negatif ya da sonlu olmayan değerler yok sayılır; `0` "önbellekleme"
-anlamına gelir.
+anlamına gelir. TTL dolmadan önce framework, son render süresine göre erken
+arka plan tazelemesi başlatır (ayrı bir config alanı yok; ayrıntı
+[06-cache.md](./06-cache.md)).
 
 ```js
 html: {

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

@@ -150,15 +150,29 @@ The entry structure:
 ```
 expiresAt  = now + ttl
 staleUntil = now + ttl * 2      (STALE_FACTOR = 1)
+produceMs  = duration of the last successful produce (ms)
 ```
 
 Read behaviour:
 
 | State | Response | Background |
 | --- | --- | --- |
-| `now < expiresAt` | The cached HTML, `HIT` | — |
+| `now < expiresAt - leadMs` | The cached HTML, `HIT` | — |
+| `expiresAt - leadMs ≤ now < expiresAt` | The cached HTML, `HIT` | **Early refresh** starts |
 | `expiresAt ≤ now < staleUntil` | The cached HTML **immediately**, `STALE` | A refresh is started |
-| `now ≥ staleUntil` | The entry is deleted, fresh render, `MISS` | — |
+| `now ≥ staleUntil` | The entry is deleted, fresh render, `MISS` (not while a refresh is in flight) | — |
+
+`leadMs` accounts for the page’s load time:
+
+```
+leadMs = min(max(produceMs * 2, 250ms), ttl / 2)
+```
+
+So a slow page does not fall back to a cold render the moment TTL ends: fresh
+HTML is usually written before `expiresAt`. With no traffic, a sweeper
+soft-stales the entry in the same window and queues it for warming;
+`startPrewarm` (unless `PREWARM=0`) drains that queue over HTTP — even when
+classic `prewarmPaths` is absent.
 
 A failure of the refresh inside the stale window does not affect the request:
 the old HTML stays valid for the whole window and the error is only logged

package/docs/en/07-configuration.md

@@ -635,7 +635,9 @@ Details: [03-routing.md](./03-routing.md).
 
 A pattern → seconds mapping. A matching rule **overrides** the route's own
 `revalidate` value. Negative or non-finite values are ignored; `0` means "no
-caching".
+caching". Before TTL ends the framework starts an early background refresh
+based on the last render duration (no separate config field; see
+[06-caching.md](./06-caching.md)).
 
 The one exception is `route(fn, { private: true })`: on that route a matching
 pattern is ignored. The lock is deliberately one-way — a mistake in the other

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.0",
+  "version": "0.5.2",
   "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/index.js

@@ -38,6 +38,16 @@ export {
 export { reportUpstreamFailure } from "./server/upstream-tracking.js";
 export { asset, hasAsset, optimizedImage, getSpriteIds } from "./server/assets.js";
 export { remoteImageUrl, parseAllowedRemoteUrl } from "./server/image-optimizer.js";
+export {
+  ImageResponse,
+  OG_SIZE,
+  buildOgSvg,
+  escapeXml,
+  ogHandler,
+  ogImage,
+  sendOgImage,
+  wrapText,
+} from "./server/og-image.js";
 export { headHints } from "./server/head-hints.js";
 export { renderHeadMeta } from "./server/metadata.js";
 export {

package/src/server/html-cache.js

@@ -7,6 +7,11 @@
  * tazeleme turu` kadar geride olabilir. Fiyat gibi canlı alanlar istemcide
  * WebSocket'ten güncellendiği için bu gecikme ekranda görünmez.
  *
+ * TTL dolmadan önce de tazelenir (**erken tazeleme**): son başarılı üretimin
+ * süresi (`produceMs`) kadar önden arka plan refresh başlar, böylece yavaş
+ * bir sayfa TTL anında hâlâ soğuk render'a düşmez. Trafik yoksa sweeper
+ * girdiyi soft-bayatlatır ve ısıtma kuyruğuna alır.
+ *
  * TTL'in yanında ikinci bir tazelik kaynağı daha var: **hedefli
  * invalidation**. Bir içerik güncellendiğinde tüm önbelleği boşaltmak
  * (`clearHtmlCache()`) o an sıcak olan her sayfayı soğuk render'a çevirir;
@@ -50,9 +55,12 @@ import {
  * `encoded` haritası yanıt yolunda (`sendHtml`) doluyor, yani yazma anında
  * boş; `storeEncoded` açıkken harita büyüdüğünde girdi yeniden paylaşılır.
  *
+ * `produceMs`: son başarılı üretimin süresi. Erken tazeleme penceresi bundan
+ * türetilir; Redis'ten gelen kopyada yoksa varsayılan kullanılır.
+ *
  * @typedef {{ html: string, status: number, expiresAt: number,
  *   staleUntil: number, encoded: Map<string, Buffer>, deps: Set<string>,
- *   storedAt: number, sharedEncodings: number }} HtmlEntry
+ *   storedAt: number, sharedEncodings: number, produceMs: number }} HtmlEntry
  */
 
 /**
@@ -94,12 +102,27 @@ function trackDependencies() {
  */
 const STALE_FACTOR = 1;
 
+/**
+ * Redis'ten gelen veya süresi bilinmeyen girdiler için erken tazeleme lead'i.
+ * Ölçülmüş `produceMs` yokken aşırı iyimser (0) kalmamak için.
+ */
+const DEFAULT_PRODUCE_MS = 500;
+
+/** Erken tazelemenin alt sınırı — çok hızlı sayfalar da TTL'den önce ısınsın. */
+const EARLY_REFRESH_MIN_MS = 250;
+
+/** Trafiksiz girdileri erken pencerede soft-bayatlatma aralığı. */
+const EARLY_SWEEP_INTERVAL_MS = 1000;
+
 /** @type {Map<string, HtmlEntry>} */
 const store = new Map();
 
 /** @type {Map<string, Promise<{ html: string, status: number }>>} */
 const inflight = new Map();
 
+/** @type {ReturnType<typeof setInterval> | null} */
+let earlySweepTimer = null;
+
 /**
  * Uçuştaki her tazelemenin kimliği. Bir girdi tazelenirken invalidate
  * edilirse o tazelemenin sonucu **artık geçersizdir**: render, purge'den önce
@@ -148,6 +171,54 @@ const purgedDeps = new Map();
 
 const MAX_PURGED_DEPS = 1000;
 
+/**
+ * Erken tazeleme lead'i: son render süresinin 2 katı (en az 250 ms), TTL'in
+ * yarısından fazla olamaz — kısa TTL'lerde sürekli refresh döngüsü olmasın.
+ *
+ * @param {number} produceMs
+ * @param {number} ttlMs
+ * @returns {number}
+ */
+export function earlyRefreshLeadMs(produceMs, ttlMs) {
+  const measured =
+    Number.isFinite(produceMs) && produceMs > 0 ? produceMs : DEFAULT_PRODUCE_MS;
+  const lead = Math.max(measured * 2, EARLY_REFRESH_MIN_MS);
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return lead;
+  return Math.min(lead, ttlMs / 2);
+}
+
+/**
+ * @param {HtmlEntry} entry
+ * @returns {number}
+ */
+function entryTtlMs(entry) {
+  // Soft-bayatlatılmış girdide expiresAt 0; orijinal TTL storedAt farkından
+  // okunamaz. O durumda produceMs üzerinden güvenli bir üst sınır yeter.
+  if (entry.expiresAt > entry.storedAt) return entry.expiresAt - entry.storedAt;
+  return Math.max(entry.produceMs * 4, EARLY_REFRESH_MIN_MS * 2);
+}
+
+/**
+ * @param {HtmlEntry} entry
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+function isEarly(entry, now = Date.now()) {
+  if (now >= entry.expiresAt) return false;
+  const lead = earlyRefreshLeadMs(entry.produceMs, entryTtlMs(entry));
+  return now >= entry.expiresAt - lead;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function normalizeProduceMs(value) {
+  const n = Number(value);
+  if (Number.isFinite(n) && n >= 0) return Math.round(n);
+  return DEFAULT_PRODUCE_MS;
+}
+
 /**
  * Girdiyi ters indeksten söker. Bu adım atlanırsa indeks, düşen girdilerin
  * anahtarlarını tutmaya devam eder ve sessizce sızar.
@@ -183,7 +254,7 @@ function drop(key) {
 /**
  * @param {string} key
  * @returns {{ html: string, status: number, encoded: Map<string, Buffer>,
- *   stale: boolean } | null}
+ *   stale: boolean, early: boolean } | null}
  */
 function read(key) {
   const entry = store.get(key);
@@ -191,8 +262,12 @@ function read(key) {
 
   const now = Date.now();
   if (now >= entry.staleUntil) {
-    drop(key);
-    return null;
+    // Uçuştaki tazeleme bitene kadar girdiyi tut: yavaş upstream'de
+    // staleUntil dolup MISS'e düşmek erken tazelemenin amacını bozar.
+    if (!inflight.has(key)) {
+      drop(key);
+      return null;
+    }
   }
 
   // LRU: erişilen girdiyi sona taşı.
@@ -206,11 +281,13 @@ function read(key) {
     share(key, entry);
   }
 
+  const stale = now >= entry.expiresAt;
   return {
     html: entry.html,
     status: entry.status,
     encoded: entry.encoded,
-    stale: now >= entry.expiresAt,
+    stale,
+    early: !stale && isEarly(entry, now),
   };
 }
 
@@ -234,6 +311,7 @@ function share(key, entry) {
     storedAt: entry.storedAt,
     expiresAt: entry.expiresAt,
     staleUntil: entry.staleUntil,
+    produceMs: entry.produceMs,
     deps: [...entry.deps],
   };
 
@@ -298,6 +376,7 @@ async function readShared(key) {
     deps,
     storedAt,
     sharedEncodings: encoded.size,
+    produceMs: normalizeProduceMs(payload.produceMs),
   };
 }
 
@@ -306,8 +385,9 @@ async function readShared(key) {
  * @param {{ html: string, status: number }} value
  * @param {number} ttlSeconds
  * @param {Set<string> | null} deps Render sırasında okunan veri anahtarları.
+ * @param {number} [produceMs] Son üretimin süresi (ms).
  */
-function write(key, value, ttlSeconds, deps = null) {
+function write(key, value, ttlSeconds, deps = null, produceMs = DEFAULT_PRODUCE_MS) {
   const now = Date.now();
 
   /** @type {HtmlEntry} */
@@ -322,6 +402,7 @@ function write(key, value, ttlSeconds, deps = null) {
     deps: deps ?? new Set(),
     storedAt: now,
     sharedEncodings: 0,
+    produceMs: normalizeProduceMs(produceMs),
   };
 
   install(key, entry);
@@ -385,6 +466,9 @@ function refresh(key, ttlSeconds, producer) {
   const pending = inflight.get(key);
   if (pending) return pending;
 
+  // Tazeleme sürerken staleUntil dolmasın: drop → MISS yolu kapanır.
+  extendStaleWhileRefreshing(key);
+
   const token = {};
   tokens.set(key, token);
 
@@ -397,6 +481,17 @@ function refresh(key, ttlSeconds, producer) {
   return task;
 }
 
+/**
+ * @param {string} key
+ */
+function extendStaleWhileRefreshing(key) {
+  const entry = store.get(key);
+  if (!entry) return;
+  const lead = earlyRefreshLeadMs(entry.produceMs, entryTtlMs(entry));
+  const floor = Date.now() + lead;
+  if (entry.staleUntil < floor) entry.staleUntil = floor;
+}
+
 /**
  * @param {string} key
  * @param {number} ttlSeconds
@@ -436,7 +531,7 @@ async function produce(key, ttlSeconds, producer, token) {
   // öncesinde başlamış demektir; yazmak az önce düşürüleni geri koyardı.
   const valid = tokens.get(key) === token && !readsPurgedData(deps, startedAt);
   if (valid && value.status === 200 && !value.degraded && value.storable !== false) {
-    write(key, value, ttlSeconds, deps);
+    write(key, value, ttlSeconds, deps, Date.now() - startedAt);
   }
 
   return value;
@@ -447,7 +542,7 @@ async function produce(key, ttlSeconds, producer, token) {
  * @param {number} ttlSeconds 0 → cache yok
  * @param {() => Promise<{ html: string, status: number }>} producer
  * @returns {Promise<{ html: string, status: number, cached: boolean,
- *   stale?: boolean, encoded?: Map<string, Buffer> }>}
+ *   stale?: boolean, early?: boolean, encoded?: Map<string, Buffer> }>}
  */
 export async function withHtmlCache(key, ttlSeconds, producer) {
   if (!ttlSeconds) {
@@ -460,7 +555,8 @@ export async function withHtmlCache(key, ttlSeconds, producer) {
   if (hit) {
     // Süresi geçmiş girdi anında döner; tazeleme arkada yürür ve hatası
     // isteği etkilemez (eski HTML stale penceresi boyunca geçerli kalır).
-    if (hit.stale) {
+    // Erken pencerede de aynı: hâlâ HIT, ama TTL dolmadan taze HTML yazılsın.
+    if (hit.stale || hit.early) {
       invalidated.delete(key);
       void refresh(key, ttlSeconds, producer).catch((error) => {
         console.error(`[html-cache] background refresh failed: ${key}`, error);
@@ -829,3 +925,42 @@ export function isHtmlCacheFresh(pathname) {
   if (!entry) return false;
   return Date.now() < entry.expiresAt;
 }
+
+/**
+ * Erken tazeleme penceresine girmiş (veya TTL'i dolmuş) trafiksiz girdileri
+ * soft-bayatlatır ve ısıtma kuyruğuna alır. HTTP ısıtması producer'sız
+ * çalıştığı için soft-bayat şart: taze HIT yenileme tetiklemez.
+ *
+ * @returns {number} İşaretlenen girdi sayısı.
+ */
+export function sweepEarlyExpiry() {
+  const now = Date.now();
+  let marked = 0;
+
+  for (const [key, entry] of store) {
+    if (inflight.has(key)) continue;
+    // Zaten soft-bayat / kuyrukta — her saniye yeniden ekleme.
+    if (entry.expiresAt === 0) continue;
+    if (now < entry.expiresAt && !isEarly(entry, now)) continue;
+
+    entry.expiresAt = 0;
+    if (invalidated.size < MAX_INVALIDATED) invalidated.add(key);
+    marked += 1;
+  }
+
+  return marked;
+}
+
+/**
+ * Trafiksiz sayfaların TTL öncesi soft-bayatlatılması. `startPrewarm` açar;
+ * `PREWARM=0` iken hiç kurulmaz. `unref` — süreç kapanışını geciktirmez.
+ *
+ * @returns {void}
+ */
+export function startEarlyExpirySweep() {
+  if (earlySweepTimer) return;
+  earlySweepTimer = setInterval(() => {
+    sweepEarlyExpiry();
+  }, EARLY_SWEEP_INTERVAL_MS);
+  earlySweepTimer.unref();
+}

package/src/server/og-image.js

@@ -0,0 +1,356 @@
+/**
+ * Dinamik Open Graph görselleri — Next.js `ImageResponse` /
+ * `opengraph-image.tsx` karşılığı.
+ *
+ * JSX yok: ya hazır kart alanları (`title`, `description`, `siteName`) ya da
+ * ham `svg` verilir. sharp (opsiyonel peer) varsa PNG üretilir; yoksa SVG
+ * döner. Sosyal kazıyıcıların çoğu PNG beklediği için prod'da sharp önerilir.
+ *
+ * Domain bilgisi taşınmaz — metin, renk ve SVG uygulama tarafındandır.
+ */
+import { tryImportFromApp } from "../build/resolve-peer.mjs";
+import { getConfig } from "../config/index.js";
+import { isNotFoundError } from "../http/control-flow.js";
+
+/** @type {((input: Buffer, opts?: object) => import('sharp').Sharp) | null | undefined} */
+let sharpModule;
+
+/** Sosyal kartlar için yaygın boyut (Facebook / X / LinkedIn). */
+export const OG_SIZE = Object.freeze({ width: 1200, height: 630 });
+
+const DEFAULT_CACHE =
+  "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800";
+
+/**
+ * @typedef {object} OgCardOptions
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {string} [siteName]
+ * @property {string} [background] Düz SVG rengi (`#0f172a`)
+ * @property {string} [color] Ana metin rengi
+ * @property {string} [mutedColor] Açıklama / site adı
+ * @property {string} [accent] Sol şerit rengi
+ */
+
+/**
+ * @typedef {OgCardOptions & {
+ *   svg?: string,
+ *   width?: number,
+ *   height?: number,
+ *   format?: 'png' | 'svg',
+ *   cacheControl?: string,
+ * }} OgImageOptions
+ */
+
+/**
+ * @typedef {object} OgImageResult
+ * @property {Buffer} body
+ * @property {string} contentType
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * XML metin kaçışı — kullanıcı başlığı SVG'ye gömülür.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeXml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Kelime sınırında satır kır. Uzun kelime kesilir; taşan içerik son satırda `…`.
+ * @param {string} text
+ * @param {number} maxChars
+ * @param {number} maxLines
+ * @returns {string[]}
+ */
+export function wrapText(text, maxChars, maxLines) {
+  const words = String(text ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!words.length || maxLines < 1 || maxChars < 1) return [];
+
+  /** @type {string[]} */
+  const lines = [];
+  let current = "";
+  let overflow = false;
+
+  const pushCurrent = () => {
+    if (!current) return;
+    lines.push(current);
+    current = "";
+  };
+
+  for (const word of words) {
+    if (lines.length >= maxLines) {
+      overflow = true;
+      break;
+    }
+
+    const candidate = current ? `${current} ${word}` : word;
+    if (candidate.length <= maxChars) {
+      current = candidate;
+      continue;
+    }
+
+    pushCurrent();
+    if (lines.length >= maxLines) {
+      overflow = true;
+      break;
+    }
+
+    if (word.length <= maxChars) {
+      current = word;
+      continue;
+    }
+
+    let rest = word;
+    while (rest.length > maxChars) {
+      if (lines.length >= maxLines) {
+        overflow = true;
+        rest = "";
+        break;
+      }
+      lines.push(rest.slice(0, maxChars));
+      rest = rest.slice(maxChars);
+    }
+    current = rest;
+  }
+
+  if (current && lines.length < maxLines) {
+    lines.push(current);
+  } else if (current) {
+    overflow = true;
+  }
+
+  if (overflow && lines.length) {
+    const last = lines[lines.length - 1];
+    const base = last.endsWith("…") ? last.slice(0, -1) : last;
+    const trimmed = base.slice(0, Math.max(1, maxChars - 1));
+    lines[lines.length - 1] = `${trimmed}…`;
+  }
+
+  return lines;
+}
+
+/**
+ * Hazır kart SVG'si. Uygulama kendi SVG'sini vermek isterse `svg` kullanır.
+ * @param {OgCardOptions & { width?: number, height?: number }} options
+ * @returns {string}
+ */
+export function buildOgSvg(options = {}) {
+  const width = options.width ?? OG_SIZE.width;
+  const height = options.height ?? OG_SIZE.height;
+  const background = options.background ?? "#0f172a";
+  const color = options.color ?? "#f8fafc";
+  const muted = options.mutedColor ?? "#94a3b8";
+  const accent = options.accent ?? "#38bdf8";
+
+  const titleLines = wrapText(options.title ?? "", 28, 3);
+  const descLines = wrapText(options.description ?? "", 52, 2);
+  const siteName = options.siteName ? escapeXml(options.siteName) : "";
+
+  const titleTs = titleLines
+    .map((line, i) => {
+      const dy = i === 0 ? 0 : 72;
+      return `<tspan x="80" dy="${dy}">${escapeXml(line)}</tspan>`;
+    })
+    .join("");
+
+  const descTs = descLines
+    .map((line, i) => {
+      const dy = i === 0 ? 0 : 40;
+      return `<tspan x="80" dy="${dy}">${escapeXml(line)}</tspan>`;
+    })
+    .join("");
+
+  const titleY = 200;
+  const descY = titleY + Math.max(titleLines.length, 1) * 72 + 36;
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+    `<rect width="100%" height="100%" fill="${escapeXml(background)}"/>` +
+    `<rect x="0" y="0" width="14" height="${height}" fill="${escapeXml(accent)}"/>` +
+    (titleTs
+      ? `<text x="80" y="${titleY}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="64" font-weight="700" fill="${escapeXml(color)}">${titleTs}</text>`
+      : "") +
+    (descTs
+      ? `<text x="80" y="${descY}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="30" font-weight="400" fill="${escapeXml(muted)}">${descTs}</text>`
+      : "") +
+    (siteName
+      ? `<text x="80" y="${height - 64}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="24" font-weight="600" fill="${escapeXml(muted)}">${siteName}</text>`
+      : "") +
+    `</svg>`
+  );
+}
+
+/**
+ * @returns {Promise<((input: Buffer, opts?: object) => import('sharp').Sharp) | null>}
+ */
+async function loadSharp() {
+  if (sharpModule !== undefined) return sharpModule;
+
+  /** @type {any} */
+  let mod = null;
+  try {
+    mod = await tryImportFromApp(getConfig().root, "sharp");
+  } catch {
+    // Config yoksa (birim test) doğrudan çözümle.
+    try {
+      mod = await import("sharp");
+    } catch {
+      mod = null;
+    }
+  }
+
+  sharpModule = mod?.default ?? mod ?? null;
+  return sharpModule;
+}
+
+/**
+ * SVG veya kart alanlarından PNG/SVG gövde üretir.
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export async function ogImage(options = {}) {
+  const width = options.width ?? OG_SIZE.width;
+  const height = options.height ?? OG_SIZE.height;
+  const svg =
+    typeof options.svg === "string" && options.svg.trim()
+      ? options.svg
+      : buildOgSvg({ ...options, width, height });
+
+  const preferSvg = options.format === "svg";
+  const sharp = preferSvg ? null : await loadSharp();
+
+  if (!sharp) {
+    return {
+      body: Buffer.from(svg, "utf8"),
+      contentType: "image/svg+xml; charset=utf-8",
+      width,
+      height,
+    };
+  }
+
+  const body = await sharp(Buffer.from(svg, "utf8"))
+    .resize(width, height, { fit: "fill" })
+    .png()
+    .toBuffer();
+
+  return {
+    body,
+    contentType: "image/png",
+    width,
+    height,
+  };
+}
+
+/**
+ * Express yanıtına OG görseli basar.
+ * @param {import('express').Response} res
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export async function sendOgImage(res, options = {}) {
+  const result = await ogImage(options);
+  const cacheControl = options.cacheControl ?? DEFAULT_CACHE;
+
+  res.status(200);
+  res.setHeader("Content-Type", result.contentType);
+  res.setHeader("Cache-Control", cacheControl);
+  res.setHeader("Content-Length", String(result.body.length));
+  // Kazıyıcılar ve CDN'ler için boyut ipucu (meta ile de verilir).
+  res.setHeader("X-Og-Width", String(result.width));
+  res.setHeader("X-Og-Height", String(result.height));
+  res.end(result.body);
+  return result;
+}
+
+/**
+ * Next `opengraph-image` route handler'ına yakın Express sarmalayıcı.
+ *
+ * Factory `null` dönerse veya `notFound()` fırlatırsa 404.
+ *
+ * @param {(ctx: { params: Record<string, string>, query: import('express').Request['query'], req: import('express').Request }) =>
+ *   OgImageOptions | null | Promise<OgImageOptions | null>} factory
+ * @param {OgImageOptions} [defaults] Her istekte birleşen varsayılanlar
+ * @returns {import('express').RequestHandler}
+ */
+export function ogHandler(factory, defaults = {}) {
+  return async (req, res, next) => {
+    try {
+      const result = await factory({
+        params: req.params ?? {},
+        query: req.query,
+        req,
+      });
+      if (result == null) {
+        res.status(404).end();
+        return;
+      }
+      await sendOgImage(res, { ...defaults, ...result });
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        res.status(404).end();
+        return;
+      }
+      next(error);
+    }
+  };
+}
+
+/**
+ * Next.js `new ImageResponse(...)` DX'si. JSX yok — ilk argüman SVG string
+ * veya kart alanları nesnesi.
+ *
+ * @example
+ * ```js
+ * return new ImageResponse(
+ *   { title: post.title, description: post.excerpt, siteName: "Blog" },
+ *   { width: 1200, height: 630 },
+ * );
+ * // handler içinde: await image.send(res)
+ * ```
+ */
+export class ImageResponse {
+  /** @type {OgImageOptions} */
+  #options;
+
+  /**
+   * @param {string | OgCardOptions} element
+   * @param {Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & { width?: number, height?: number }} [init]
+   */
+  constructor(element, init = {}) {
+    if (typeof element === "string") {
+      this.#options = { ...init, svg: element };
+    } else {
+      this.#options = { ...element, ...init };
+    }
+  }
+
+  /** @returns {OgImageOptions} */
+  get options() {
+    return this.#options;
+  }
+
+  /** @returns {Promise<OgImageResult>} */
+  async buffer() {
+    return ogImage(this.#options);
+  }
+
+  /**
+   * @param {import('express').Response} res
+   * @returns {Promise<OgImageResult>}
+   */
+  async send(res) {
+    return sendOgImage(res, this.#options);
+  }
+}

package/src/server/prewarm.js

@@ -19,7 +19,7 @@
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
 import { getRequestContext } from "../http/request-context.js";
-import { isHtmlCacheFresh, takeInvalidatedPaths } from "./html-cache.js";
+import { isHtmlCacheFresh, takeInvalidatedPaths, startEarlyExpirySweep } from "./html-cache.js";
 import { getDataCacheStats } from "./data-cache.js";
 import { isTransientStatus } from "./upstream-tracking.js";
 import { upstreamCooldownMs } from "./upstream-limiter.js";
@@ -786,7 +786,8 @@ async function drainVisitWarm() {
 
 /**
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
- * `onVisit` modunda zamanlayıcı yok: yalnızca origin kaydı ve kuyruk.
+ * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
+ * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
  *
  * @param {{ port: number }} options
  * @returns {void}
@@ -797,6 +798,11 @@ export function startPrewarm({ port }) {
 
   const origin = `http://127.0.0.1:${port}`;
 
+  // Klasik `prewarmPaths` olmasa da TTL öncesi soft-bayatlayan girdiler
+  // HTTP ile ısıtılsın. `PREWARM=0` yukarıda her şeyi keser.
+  startEarlyExpirySweep();
+  startExpiryWarmDrain(origin);
+
   if (config.prewarm?.onVisit?.enabled) {
     const classicEnv = CLASSIC_PREWARM_ENV.filter((key) => process.env[key]);
     if (classicEnv.length) {
@@ -814,7 +820,8 @@ export function startPrewarm({ port }) {
   }
 
   if (process.env.PREWARM !== "1" && config.prewarm?.enabled === false) return;
-  // Isıtacak yol bildirmeyen bir projede zamanlayıcı kurmanın anlamı yok.
+  // Isıtacak yol bildirmeyen bir projede klasik tur zamanlayıcısı gerekmez;
+  // expiry drain yine de yukarıda kuruldu.
   if (typeof config.hooks?.prewarmPaths !== "function") return;
 
   const isDev = process.env.NODE_ENV === "development";
@@ -848,3 +855,50 @@ export function startPrewarm({ port }) {
   const interval = setting("PREWARM_INTERVAL_SECONDS", "intervalSeconds", 0);
   if (interval > 0) setInterval(() => void run(), interval * 1000).unref();
 }
+
+/** @type {string | null} */
+let expiryOrigin = null;
+
+/** @type {boolean} */
+let expiryDraining = false;
+
+/** @type {ReturnType<typeof setInterval> | null} */
+let expiryDrainTimer = null;
+
+/**
+ * Soft-bayat / invalidate kuyruğunu periyodik boşaltır. Klasik tur ve onVisit
+ * aynı kuyruğu da okur; bu drain `prewarmPaths` yokken de çalışır.
+ *
+ * @param {string} origin
+ * @returns {void}
+ */
+function startExpiryWarmDrain(origin) {
+  expiryOrigin = origin;
+  if (expiryDrainTimer) return;
+  expiryDrainTimer = setInterval(() => {
+    void drainExpiryWarm();
+  }, 1000);
+  expiryDrainTimer.unref();
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+async function drainExpiryWarm() {
+  if (expiryDraining || !expiryOrigin) return;
+
+  const paths = takeInvalidatedPaths();
+  if (!paths.length) return;
+
+  expiryDraining = true;
+  try {
+    const cold = paths.filter((path) => !isHtmlCacheFresh(path));
+    if (!cold.length) return;
+
+    await prewarm({ origin: expiryOrigin, paths: cold, quiet: true });
+  } catch (error) {
+    console.error("[prewarm] expiry warm failed", error);
+  } finally {
+    expiryDraining = false;
+  }
+}

package/src/server/router.js

@@ -14,8 +14,9 @@
  *
  * Modül sözleşmesi: default export ya da `register` adlı named export,
  * `(app, api) => void | Promise<void>` imzasıyla. `api` içinde `route`,
- * `fragment`, `renderView`, `renderPage` ve `notFound`/`redirect` hazır gelir,
- * böylece route dosyaları framework'ten tek tek import yapmak zorunda kalmaz.
+ * `fragment`, `renderView`, `renderPage`, `notFound`/`redirect` ve
+ * `ogHandler` hazır gelir, böylece route dosyaları framework'ten tek tek
+ * import yapmak zorunda kalmaz.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -29,6 +30,7 @@ import {
   redirect,
   seeOther,
 } from "../http/control-flow.js";
+import { ImageResponse, ogHandler, ogImage, sendOgImage } from "./og-image.js";
 
 const isDev = process.env.NODE_ENV === "development";
 
@@ -96,6 +98,10 @@ const api = {
   redirect,
   permanentRedirect,
   seeOther,
+  ogHandler,
+  ogImage,
+  sendOgImage,
+  ImageResponse,
 };
 
 /**