jskelet 0.7.1 → 0.7.2

package/src/server/image-optimizer.js

@@ -39,6 +39,17 @@ const imageCacheIndex = new Map();
 /** @type {number} */
 let imageCacheBytes = 0;
 
+/** Aynı url+w+q için eşzamanlı optimize birleşir. @type {Map<string, Promise<void>>} */
+const optimizeInflight = new Map();
+
+/**
+ * DNS güven kontrolü kısa TTL'li cache — her hop'ta tekrar lookup olmasın.
+ * @type {Map<string, { ok: boolean, until: number }>}
+ */
+const dnsSafeCache = new Map();
+const DNS_SAFE_TTL_MS = 60_000;
+const MAX_DNS_SAFE = 500;
+
 const MAX_REDIRECTS = 5;
 
 /**
@@ -172,16 +183,27 @@ export function isRemoteUrlShapeAllowed(url, allowHosts) {
  */
 export async function assertResolvedHostSafe(hostname) {
   if (isBlockedAddress(hostname)) return false;
+
+  const cached = dnsSafeCache.get(hostname);
+  if (cached && Date.now() < cached.until) return cached.ok;
+
+  /** @type {boolean} */
+  let ok = false;
   try {
     const results = await dns.lookup(hostname, { all: true, verbatim: true });
-    if (!results.length) return false;
-    for (const { address } of results) {
-      if (isBlockedAddress(address)) return false;
+    if (results.length) {
+      ok = results.every(({ address }) => !isBlockedAddress(address));
     }
-    return true;
   } catch {
-    return false;
+    ok = false;
+  }
+
+  if (dnsSafeCache.size >= MAX_DNS_SAFE) {
+    const oldest = dnsSafeCache.keys().next().value;
+    if (oldest !== undefined) dnsSafeCache.delete(oldest);
   }
+  dnsSafeCache.set(hostname, { ok, until: Date.now() + DNS_SAFE_TTL_MS });
+  return ok;
 }
 
 /**
@@ -355,32 +377,23 @@ async function handleOptimize(req, res, remote) {
       return;
     }
 
-    const upstream = await fetchUpstream(allowed.href, remote);
-    if (!upstream.ok) {
-      res.status(502).type("text").send("Upstream image fetch failed");
+    let pending = optimizeInflight.get(key);
+    if (!pending) {
+      pending = materializeOptimized(allowed.href, filePath, width, quality, remote).finally(
+        () => {
+          optimizeInflight.delete(key);
+        },
+      );
+      optimizeInflight.set(key, pending);
+    }
+    await pending;
+
+    if (imageCacheIndex.has(filePath) || fs.existsSync(filePath)) {
+      sendCached(res, filePath, remote.cacheMaxAge);
       return;
     }
 
-    const sharp = sharpModule.default;
-    const buffer = await sharp(upstream.buffer, { failOn: "none" })
-      .rotate()
-      .resize({
-        width,
-        withoutEnlargement: true,
-        fit: "inside",
-      })
-      .webp({ quality, effort: 4 })
-      .toBuffer();
-
-    // Atomik yaz: yarım dosya immutable cache'e düşmesin.
-    const tmp = `${filePath}.${process.pid}.tmp`;
-    await fs.promises.writeFile(tmp, buffer);
-    await fs.promises.rename(tmp, filePath);
-    // Yeni dosya için yer aç: en eski düşer. Az önce yazılan, tek başına
-    // tavanı aşıyorsa kalır; bir sonraki yazım onu düşürür. Silme, bu
-    // yanıtın `sendFile`'ından önce olmasın.
-    noteImageCacheFile(filePath, buffer.length);
-    sendCached(res, filePath, remote.cacheMaxAge);
+    res.status(502).type("text").send("Upstream image fetch failed");
   } catch (error) {
     console.warn("[images.remote] optimize failed:", error);
     // Bozuk kaynakta sayfa boş kalmasın: orijinale düş.
@@ -388,6 +401,37 @@ async function handleOptimize(req, res, remote) {
   }
 }
 
+/**
+ * @param {string} href
+ * @param {string} filePath
+ * @param {number} width
+ * @param {number} quality
+ * @param {import('../config/index.js').ImagesRemoteConfig} remote
+ * @returns {Promise<void>}
+ */
+async function materializeOptimized(href, filePath, width, quality, remote) {
+  if (imageCacheIndex.has(filePath) || fs.existsSync(filePath)) return;
+
+  const upstream = await fetchUpstream(href, remote);
+  if (!upstream.ok) return;
+
+  const sharp = /** @type {NonNullable<typeof sharpModule>} */ (sharpModule).default;
+  const buffer = await sharp(upstream.buffer, { failOn: "none" })
+    .rotate()
+    .resize({
+      width,
+      withoutEnlargement: true,
+      fit: "inside",
+    })
+    .webp({ quality, effort: 4 })
+    .toBuffer();
+
+  const tmp = `${filePath}.${process.pid}.tmp`;
+  await fs.promises.writeFile(tmp, buffer);
+  await fs.promises.rename(tmp, filePath);
+  noteImageCacheFile(filePath, buffer.length);
+}
+
 /**
  * Redirect'leri elle takip eder; her hop allowlist + DNS private kontrolünden geçer.
  *

package/src/server/redis.js

@@ -22,7 +22,7 @@ import crypto from "node:crypto";
 import { DEFAULT_REDIS } from "../config/defaults.js";
 import { tryImportFromApp } from "../build/resolve-peer.mjs";
 import { getBuildId } from "./assets.js";
-import { decodeCacheValue, encodeCacheValue } from "./cache-blob.js";
+import { decodeCacheValueAsync, encodeCacheValue } from "./cache-blob.js";
 
 /**
  * @typedef {import('../config/index.js').RedisConfig} RedisConfig
@@ -295,7 +295,7 @@ export async function redisGetJson(key) {
     const raw =
       typeof client.getBuffer === "function" ? await client.getBuffer(key) : await client.get(key);
     noteSuccess();
-    return raw == null ? null : decodeCacheValue(raw);
+    return raw == null ? null : await decodeCacheValueAsync(raw);
   } catch (error) {
     noteFailure("get", error);
     return null;

package/src/server/render.js

@@ -58,16 +58,22 @@ const isDev = process.env.NODE_ENV === "development";
  * taraması dosya sistemine dokunduğu için bir kez yapılır; config yüklenmeden
  * hesaplanamaz, bu yüzden ilk render'da kurulur.
  *
- * @type {{ helpers: Record<string, unknown>, options: Record<string, unknown>,
+ * Sayfa `.jsk` şablonları lazy yüklenir; layout + `components/*.jsk` eager.
+ *
+ * @typedef {{ helpers: Record<string, unknown>, options: Record<string, unknown>,
  *   viewsDir: string, viewRoots: string[], layout: string,
  *   compiled: Map<string, (data: object, helpers: object) => string>,
+ *   loading: Map<string, Promise<(data: object, helpers: object) => string | null>>,
+ *   manifest: Record<string, string>, templatesDir: string, bust: string,
  *   layoutRender: ((data: object, helpers: object) => string) | null
- * } | null}
+ * }} RenderEngine
  */
+
+/** @type {RenderEngine | null} */
 let engine = null;
 
 /**
- * @returns {Promise<NonNullable<typeof engine>>}
+ * @returns {Promise<RenderEngine>}
  */
 async function getEngine() {
   if (engine) return engine;
@@ -104,14 +110,11 @@ async function getEngine() {
     if (!(pascal in helpers)) helpers[pascal] = value;
   }
 
-  const { compiled, layoutRender: appLayoutRender } = await loadCompiledTemplates(
-    config,
-    helpers,
-  );
+  const loaded = await loadCompiledTemplates(config, helpers);
 
   // Yalnızca framework varsayılan layout'una düşüldüğünde hazır modülü kullan;
   // uygulamanın kendi layout.jsk'si derlenmemişse sessizce framework'e kayma.
-  let layoutRender = appLayoutRender;
+  let layoutRender = loaded.layoutRender;
   if (!layoutRender) {
     const fwLayout = path.join(FRAMEWORK_ROOT, "src", "templates", "layout.jsk");
     if (path.resolve(config.layout) === path.resolve(fwLayout)) {
@@ -125,7 +128,11 @@ async function getEngine() {
     viewRoots,
     layout: config.layout,
     helpers,
-    compiled,
+    compiled: loaded.compiled,
+    loading: new Map(),
+    manifest: loaded.manifest,
+    templatesDir: loaded.templatesDir,
+    bust: loaded.bust,
     layoutRender,
     options: {
       // `include('partials/header')` gibi çağrılar views kökünden çözülür.
@@ -141,11 +148,48 @@ async function getEngine() {
 }
 
 /**
- * Derlenmiş `.jsk` modüllerini yükler. İstek anında parse/compile yok.
+ * Manifest'ten tek bir derlenmiş view yükler. Include'lar modül grafiğinde
+ * statik import ile gelir.
+ *
+ * @param {RenderEngine} eng
+ * @param {string} viewId
+ * @returns {Promise<((data: object, helpers: object) => string) | null>}
+ */
+async function ensureCompiledView(eng, viewId) {
+  const hit = eng.compiled.get(viewId);
+  if (hit) return hit;
+
+  const rel = eng.manifest[viewId];
+  if (!rel) return null;
+
+  const pending = eng.loading.get(viewId);
+  if (pending) return pending;
+
+  const task = (async () => {
+    const file = path.join(eng.templatesDir, rel);
+    try {
+      const mod = await import(pathToFileURL(file).href + eng.bust);
+      if (typeof mod.render !== "function") return null;
+      eng.compiled.set(viewId, mod.render);
+      return mod.render;
+    } catch {
+      return null;
+    } finally {
+      eng.loading.delete(viewId);
+    }
+  })();
+
+  eng.loading.set(viewId, task);
+  return task;
+}
+
+/**
+ * Layout + `components/*.jsk` eager; sayfa şablonları ilk `renderView`'da.
  *
  * @param {import('../config/index.js').ResolvedConfig} config
  * @param {Record<string, unknown>} helpers
- * @returns {Promise<{ compiled: Map<string, Function>, layoutRender: Function | null }>}
+ * @returns {Promise<{ compiled: Map<string, Function>, layoutRender: Function | null,
+ *   manifest: Record<string, string>, templatesDir: string, bust: string }>}
  */
 async function loadCompiledTemplates(config, helpers) {
   /** @type {Map<string, (data: object, helpers: object) => string>} */
@@ -154,16 +198,26 @@ async function loadCompiledTemplates(config, helpers) {
   const manifestPath = path.join(templatesDir, "manifest.json");
 
   if (!fs.existsSync(manifestPath)) {
-    return { compiled, layoutRender: null };
+    return {
+      compiled,
+      layoutRender: null,
+      manifest: {},
+      templatesDir,
+      bust: "",
+    };
   }
 
   /** @type {Record<string, string>} */
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   const bust = isDev ? `?t=${Date.now()}` : "";
 
-  // Paralel import — sıralı await cold start'ı şişiriyordu.
+  const eagerIds = Object.keys(manifest).filter(
+    (id) => id === "layout" || id.startsWith("components/"),
+  );
+
   const entries = await Promise.all(
-    Object.entries(manifest).map(async ([viewId, rel]) => {
+    eagerIds.map(async (viewId) => {
+      const rel = manifest[viewId];
       const file = path.join(templatesDir, rel);
       try {
         const mod = await import(pathToFileURL(file).href + bust);
@@ -178,7 +232,6 @@ async function loadCompiledTemplates(config, helpers) {
     if (!mod || typeof mod.render !== "function") continue;
     compiled.set(viewId, mod.render);
 
-    // `components/*.jsk` → helpers.PascalName
     if (viewId.startsWith("components/")) {
       const base = viewId.slice("components/".length).split("/").pop() ?? "";
       const pascal = base
@@ -193,7 +246,24 @@ async function loadCompiledTemplates(config, helpers) {
   }
 
   const layoutRender = compiled.get("layout") ?? null;
-  return { compiled, layoutRender };
+  return { compiled, layoutRender, manifest, templatesDir, bust };
+}
+
+/**
+ * Listen öncesi: motor + asset manifest ısınır (sayfa prewarm değil).
+ *
+ * @returns {Promise<void>}
+ */
+export async function warmRenderEngine() {
+  await getEngine();
+  hasAsset("app.css");
+  hasAsset("main.js");
+  try {
+    const { getBuildId } = await import("./assets.js");
+    getBuildId();
+  } catch {
+    /* yoksa sessiz */
+  }
 }
 
 /**
@@ -232,8 +302,13 @@ export function resetRenderEngine() {
  * @returns {Promise<string>}
  */
 export async function renderView(view, data = {}) {
-  const { helpers, options, compiled, viewRoots, viewsDir } = await getEngine();
-  const renderFn = compiled.get(view);
+  const eng = await getEngine();
+  const { helpers, options, viewRoots, viewsDir } = eng;
+
+  let renderFn = eng.compiled.get(view) ?? null;
+  if (!renderFn && eng.manifest[view]) {
+    renderFn = await ensureCompiledView(eng, view);
+  }
   if (renderFn) {
     return renderFn({ ...data }, helpers);
   }
@@ -256,17 +331,31 @@ export async function renderPage(page) {
   const { helpers, options, layout, layoutRender } = await getEngine();
   const config = getConfig();
 
-  const metadata = {
+  // Gövde `page.metadata` ile başlar (hook beklemez). Head/layout birleşik
+  // metadata'yı alır — siteName/titleTemplate gibi hook alanları layout'ta.
+  const pageMeta = page.metadata ?? {};
+  const metadataPromise = (async () => ({
     ...(await hook("metadata", {}, page)),
-    ...(page.metadata ?? {}),
-  };
+    ...pageMeta,
+  }))();
 
-  // Layout bağlamı ve gövde paralel üretilir: navigasyon çoğu projede
-  // upstream'den geliyor ve gövde render'ıyla sırayla beklemek her sayfaya
-  // gereksiz gecikme ekliyor.
-  const [body, context] = await Promise.all([
-    renderView(page.view, { ...(page.data ?? {}), metadata }),
-    hook("layoutContext", {}, { pathname: page.pathname ?? "", metadata }),
+  const bodyPromise = renderView(page.view, {
+    ...(page.data ?? {}),
+    metadata: pageMeta,
+  });
+
+  // metadata → layoutContext zinciri gövdeyle paralel.
+  const layoutPromise = metadataPromise.then(async (metadata) => {
+    const context = await hook("layoutContext", {}, {
+      pathname: page.pathname ?? "",
+      metadata,
+    });
+    return { metadata, context };
+  });
+
+  const [body, { metadata, context }] = await Promise.all([
+    bodyPromise,
+    layoutPromise,
   ]);
 
   // Layout local'leri. `.jsk` `(data, helpers)` aldığı için helpers'ı data'ya
@@ -694,31 +783,28 @@ async function sendHtml(req, res, body, encoded, options = {}) {
   const encoding =
     req.method === "HEAD" ? null : negotiateEncoding(req.headers["accept-encoding"]);
 
-  if (!encoding || !encoded) {
+  if (!encoding) {
     if (options.etag === false) {
-      // Sıkıştırma middleware'i devreye girerse Content-Length'i kendisi
-      // kaldırır; girmezse doğru uzunlukla gider.
       res.setHeader("Content-Length", String(Buffer.byteLength(body)));
       res.end(req.method === "HEAD" ? undefined : body);
       return;
     }
-
     res.send(body);
     return;
   }
 
-  let buffer = encoded.get(encoding);
+  // Public cache haritası veya private/fragment: HTML'i burada sıkıştır —
+  // middleware'in ikinci kez buffer'lamasını ve private yolda q=5 maliyetini kes.
+  let buffer = encoded?.get(encoding);
   if (!buffer) {
     buffer = await encodeText(body, encoding);
-    // Ham HTML kalır; sıkıştırılmış kopya tek kodlamadır. Diğer istemci
-    // gelince eski buffer düşer, bayt bütçesi iki gövdeyi birden saymaz.
-    rememberHtmlEncoding(encoded, encoding, buffer);
+    if (encoded) rememberHtmlEncoding(encoded, encoding, buffer);
   }
 
   res.setHeader("Content-Encoding", encoding);
   res.setHeader("Vary", "Accept-Encoding");
   res.setHeader("Content-Length", String(buffer.length));
-  res.end(buffer);
+  res.end(req.method === "HEAD" ? undefined : buffer);
 }
 
 /**
@@ -770,12 +856,47 @@ async function produce(controller, ctx) {
   if (!first.transient.length) return { html: await renderNotFound(), status: 404 };
 
   // Buraya gelindiyse `notFound()` veri gelmediği için çağrılmış. **Var olan
-  // bir sayfayı** 404 olarak servis etmek en kötü sonuç: arama motoru geçici
-  // bir rate limit'i kalıcı bir kayıp sanar. Bu yüzden sayfa yeniden denenir —
-  // ısıtma günlükleri gösteriyor ki aynı yol saniyeler sonra 200 dönüyor.
-  const { attempts, delayMs } = transientRetry();
+  // bir sayfayı** 404 olarak servis etmek en kötü sonuç. Varsayılan: hemen
+  // 503 dön, retry'yi arka planda çalıştır (data cache ısınır). `background:
+  // false` eski senkron retry davranışını geri getirir.
+  const { attempts, delayMs, background } = transientRetry();
   let failures = first.transient;
 
+  if (background && attempts > 0) {
+    const retryDetail =
+      `returned notFound() while upstream is failing ` +
+      `(${summarizeFailures(failures)}), retrying in background (${attempts}×)`;
+    if (!suppressForPrewarm(retryDetail)) {
+      console.warn(`[render] ${ctx.pathname} ${retryDetail}`);
+    }
+
+    void (async () => {
+      for (let round = 1; round <= attempts; round += 1) {
+        await sleep(delayMs * round);
+        try {
+          const retried = await withUpstreamTracking(() =>
+            withRequestCache(() => attempt(controller, ctx)),
+          );
+          if ("page" in retried || !retried.transient.length) return;
+          failures = retried.transient;
+        } catch (error) {
+          console.warn(
+            `[render] ${ctx.pathname} background retry failed`,
+            error instanceof Error ? error.message : error,
+          );
+          return;
+        }
+      }
+    })();
+
+    return {
+      html: await renderStatusPage(503),
+      status: 503,
+      degraded: true,
+      retryAfter: RETRY_AFTER_SECONDS,
+    };
+  }
+
   for (let round = 1; round <= attempts; round += 1) {
     const retryDetail =
       `returned notFound() while upstream is failing ` +
@@ -784,29 +905,20 @@ async function produce(controller, ctx) {
       console.warn(`[render] ${ctx.pathname} ${retryDetail}`);
     }
 
-    // Beklemeden tekrar denemek rate limit'e girmiş bir API'de aynı 429'u
-    // getirir; kısa bekleme hem pencerenin dönmesine şans verir hem de
-    // fırtınayı büyütmez.
     await sleep(delayMs * round);
 
-    // Her deneme kendi upstream ve istek içi cache bağlamında çalışır: ilk
-    // turun hataları ikinci turun kararını kirletmesin ve memoize edilmiş
-    // boş cevaplar tekrar kullanılmasın.
     const retried = await withUpstreamTracking(() =>
       withRequestCache(() => attempt(controller, ctx)),
     );
 
     if ("page" in retried) return retried.page;
     if (!retried.transient.length) {
-      // Bu kez upstream sağlam cevap verdi ve "yok" dedi: gerçek 404.
       return { html: await renderNotFound(), status: 404 };
     }
 
     failures = retried.transient;
   }
 
-  // Denemeler tükendi. 404 yerine 503: önbelleğe girmez, `Retry-After` taşır
-  // ve bir sonraki istek gerçek içeriği üretebilir.
   const outageDetail =
     `could not be produced, upstream is still failing ` +
     `(${summarizeFailures(failures)}), serving an uncached 503 instead of a 404`;
@@ -830,11 +942,10 @@ async function produce(controller, ctx) {
 const RETRY_AFTER_SECONDS = 30;
 
 /**
- * Tekrar denemenin maliyeti upstream'e binen ikinci bir istek turu; bu yüzden
- * varsayılan tek deneme ve kısa bekleme. Rate limit fırtınasında toplam yük
- * iki katına çıkabilir, ama alternatifi var olan sayfaları 404'e düşürmek.
+ * Varsayılan: arka plan retry + hemen 503 (TTFB'yi sleep ile şişirmez).
+ * `background: false` → eski senkron döngü.
  *
- * @returns {{ attempts: number, delayMs: number }}
+ * @returns {{ attempts: number, delayMs: number, background: boolean }}
  */
 function transientRetry() {
   const raw = /** @type {any} */ (getConfig().transientRetry ?? {});
@@ -844,6 +955,7 @@ function transientRetry() {
   return {
     attempts: Number.isFinite(attempts) && attempts >= 0 ? Math.floor(attempts) : 1,
     delayMs: Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : 300,
+    background: raw.background !== false,
   };
 }
 

package/types/client/registry.d.ts

@@ -16,6 +16,8 @@
  * `data-island-idle` görünür olsa bile sayfa sakinleşene (load + boş zaman)
  * kadar bekletir. İlk ekranda görünen ama kritik olmayan ağır modüller
  * (ör. grafik kütüphanesi çeken mini grafik) LCP ile yarışmasın diye.
+ * Gizli (zero-box) host'larda da aynı yol kullanılır — `hydrate()` onları
+ * `mountWhenReady` ile bağlar, hemen `mountIsland` çağırmaz.
  *
  * `data-island-props` JSON ise parse edilip props olarak geçer.
  */

package/types/config/defaults.d.ts

@@ -175,6 +175,11 @@ export declare const DATA_CACHE_MAX_ENTRIES_CEILING = 20000;
 export declare const DEFAULT_TRANSIENT_RETRY: {
     attempts: number;
     delayMs: number;
+    /**
+     * `true` (varsayılan): ilk transient `notFound`ta hemen 503; retry arka
+     * planda data cache'i ısıtır. `false`: yanıt öncesi senkron retry (eski).
+     */
+    background: boolean;
 };
 /**
  * Upstream veri önbelleği.
@@ -236,9 +241,8 @@ export declare const DEFAULT_UPSTREAM_LIMIT: {
  * invalidation'ı bütün node'lara yaymak. Tek instance çalışan bir kurulumda
  * kazanç neredeyse yok; bu yüzden `enabled` varsayılan olarak kapalı.
  *
- * `storeEncoded` kapalı, çünkü sıkıştırılmış gövdeleri de paylaşmak girdi
- * başına boyutu iki-üç katına çıkarır ve brotli'yi yeniden üretmek Redis'ten
- * indirmekten çoğu zaman daha ucuz.
+ * `storeEncoded` açık: soğuk replica L2 HIT'te yeniden brotli ödemesin.
+ * Boyut artar; tek encoding (br) tutulduğu için maliyet sınırlıdır.
  */
 export declare const DEFAULT_REDIS: {
     enabled: boolean;
@@ -251,7 +255,7 @@ export declare const DEFAULT_REDIS: {
     html: boolean;
     /** Veri önbelleği paylaşılsın mı. */
     data: boolean;
-    /** Brotli/gzip gövdeleri de paylaşılsın mı. */
+    /** Brotli gövdeleri de paylaşılsın mı (yazma sonrası preencode). */
     storeEncoded: boolean;
     /** pub/sub üzerinden invalidation yayını. */
     events: boolean;

package/types/config/index.d.ts

@@ -147,6 +147,7 @@ export type ResolvedConfig = {
     transientRetry: {
         attempts: number;
         delayMs: number;
+        background?: boolean;
     };
     /**
      * Opsiyonel Redis ikinci kademesi.

package/types/index.d.ts

@@ -5,7 +5,7 @@
  * controller'lar bu yüzeyi kullanır. Alt yollardan (`jskelet/server`)
  * ithal etmek de mümkün; buradaki liste "kararlı" sayılan yüzeydir.
  */
-export { route, fragment, renderPage, renderView, renderNotFound, } from "./server/render.js";
+export { route, fragment, renderPage, renderView, renderNotFound, warmRenderEngine, resetRenderEngine, } from "./server/render.js";
 export { renderStatusPage, statusFromError } from "./server/status-page.js";
 export { createApp, startServer } from "./server/create-app.js";
 export { notFound, redirect, permanentRedirect, seeOther, isNotFoundError, isRedirectError, NotFoundError, RedirectError, } from "./http/control-flow.js";

package/types/server/cache-blob.d.ts

@@ -7,7 +7,15 @@
  */
 export declare function encodeCacheValue(value: unknown): string | Buffer | Promise<string | Buffer> | null;
 /**
+ * Senkron çözücü — küçük test / senkron yollar için. Hot path
+ * `decodeCacheValueAsync` kullanır (event loop'u brotli ile bloklamaz).
+ *
  * @param {Buffer | string} raw
  * @returns {unknown}
  */
 export declare function decodeCacheValue(raw: Buffer | string): unknown;
+/**
+ * @param {Buffer | string} raw
+ * @returns {Promise<unknown>}
+ */
+export declare function decodeCacheValueAsync(raw: Buffer | string): Promise<unknown>;

package/types/server/data-cache.d.ts

@@ -3,6 +3,7 @@ export type DataEntry = {
     expiresAt: number;
     staleUntil: number;
     bytes: number;
+    produceMs: number;
 };
 /**
  * Süreç ömrü boyunca biriken sayaçlar.

package/types/server/html-cache.d.ts

@@ -50,10 +50,8 @@ export type HtmlEntry = {
  */
 export declare function earlyRefreshLeadMs(produceMs: number, ttlMs: number): number;
 /**
- * Sıkıştırılmış gövde `install()`'dan sonra, ilk brotli/gzip yanıtında
- * girdinin `encoded` haritasına eklenir. Sayacı delta ile büyütmek, o sıra
- * LRU'dan düşmüş bir haritaya yazınca bir daha inmeyen bir artık bırakır;
- * store'dan yeniden okumak o artığı taşımaz.
+ * Bayt sayacını store'dan yeniden hesaplar. Testler elle `encoded` doldurunca
+ * çağırır; hot path `rememberHtmlEncoding` delta kullanır.
  *
  * @returns {void}
  */
@@ -202,7 +200,8 @@ export declare function isHtmlCacheFresh(pathname: string, req?: {
 export declare function isHtmlCacheKeyFresh(key: string): boolean;
 /**
  * Girdide en fazla bir sıkıştırılmış gövde durur. Yeni kodlama eskisinin
- * yerini alır; ham HTML kalır. Bayt sayacı `noteHtmlCacheGrowth` ile işlenir.
+ * yerini alır; ham HTML kalır. Bayt sayacı delta ile güncellenir — harita
+ * LRU'dan düşmüşse (store'da yok) sayaç oynatılmaz.
  *
  * @param {Map<string, Buffer>} encoded
  * @param {string} encoding

package/types/server/render.d.ts

@@ -1,3 +1,22 @@
+export type RenderEngine = {
+    helpers: Record<string, unknown>;
+    options: Record<string, unknown>;
+    viewsDir: string;
+    viewRoots: string[];
+    layout: string;
+    compiled: Map<string, (data: object, helpers: object) => string>;
+    loading: Map<string, Promise<(data: object, helpers: object) => string | null>>;
+    manifest: Record<string, string>;
+    templatesDir: string;
+    bust: string;
+    layoutRender: ((data: object, helpers: object) => string) | null;
+};
+/**
+ * Listen öncesi: motor + asset manifest ısınır (sayfa prewarm değil).
+ *
+ * @returns {Promise<void>}
+ */
+export declare function warmRenderEngine(): Promise<void>;
 /**
  * Uygulama geliştirirken bileşen dosyaları değişince kayıt yenilenmeli.
  * Dev sunucusu süreci yeniden başlattığı için normalde gerekmez; gömülü