jskelet 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -8,6 +8,15 @@ one is listed under a **Breaking** heading.
 
 ## [Unreleased]
 
+### Added
+
+- Runtime remote image optimizer: set `images.remote.allowHosts` to proxy
+  allowlisted http(s) images through `/_jskelet/image?url=&w=&q=` as resized
+  webp (disk cache under `.jskelet/image-cache/`). `image()` rewrites matching
+  remote `src` values automatically; `remoteImageUrl()` builds URLs by hand.
+  Requires `sharp` at runtime; without it the endpoint 302-redirects to the
+  source.
+
 ### Breaking
 
 - The cache admin panel moved to a top-level `admin()` config section at
@@ -19,6 +28,10 @@ one is listed under a **Breaking** heading.
 
 ### Fixed
 
+- Remote image optimizer cache hits no longer 404. Disk cache lives under
+  `.jskelet/image-cache/`; Express `sendFile` ignores dotfiles by default, so
+  the file was written but the response still failed. `sendCached` now passes
+  `dotfiles: "allow"`.
 - Cloudflare analytics in the cache panel no longer asks for an open-ended
   window. Queries used only `datetime_geq`, so Cloudflare closed the range at
   query time and a default 24h lookback became `1d` plus network delay — Free

package/docs/02-mimari.md

@@ -42,6 +42,8 @@ JSkelet bu gözlemi mimarinin merkezine alır:
  ├─ staticPrecompressed            build'de üretilmiş .br/.gz kopyalar (kalite 11)
  ├─ express.static                 public/ altındaki dosyalar
  ├─ (dev) devtools                 yalnızca NODE_ENV=development
+ ├─ admin (açıksa)                 /_jskelet/admin
+ ├─ image optimizer (remote)       /_jskelet/image — allowHosts doluysa
  ├─ body parser'lar                urlencoded 64kb + json 256kb
  ├─ rewrites(afterFiles)           statik denendikten sonra
  ├─ route'lar

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

@@ -383,12 +383,16 @@ Davranış:
 
 - `public/` altındaki yerel raster görseller için build'de üretilen webp
   varyantları (`.jskelet/images.json`) otomatik olarak `srcset` + intrinsic
-  `width`/`height` olarak eklenir. Manifest'te olmayan ya da uzak görseller
-  olduğu gibi basılır.
-- `srcset` elle verilmişse ya da `unoptimized: true` ise manifest'e hiç
-  bakılmaz.
+  `width`/`height` olarak eklenir. Manifest'te olmayan yerel yollar olduğu
+  gibi basılır.
+- `images.remote.allowHosts` açıksa uzak `http(s)` URL'leri
+  `/_jskelet/image?url=&w=` proxy'sine çevrilir (webp). `width` varsa 1x/2x
+  + config `widths` ile `srcset` üretilir.
+- `srcset` elle verilmişse ya da `unoptimized: true` ise ne manifest ne de
+  remote proxy kullanılır.
 - Yalnızca **tek** varyant üretilmişse (kaynak zaten küçükse) `srcset`/`sizes`
-  yazılmaz; gürültüden ibaret olurdu.
+  yazılmaz; gürültüden ibaret olurdu. Remote'da tek genişlikte bile `src`
+  yine optimize URL'dir.
 - `sizes` verilmezse makul bir varsayılan üretilir: görsel kendi intrinsic
   genişliğinden büyütülmez, dar ekranlarda viewport'u kaplar
   (`(max-width: Npx) 100vw, Npx`).

package/docs/07-yapilandirma.md

@@ -482,24 +482,51 @@ icons: { scan: ["views", "client", "routes", "lib", "content"] }
 
 ## `images`
 
-**Tip:** `{ widths?: number[], quality?: number, skip?: string[] } | false` —
-**Varsayılan:** `{}`
+**Tip:**
+`{ widths?: number[], quality?: number, skip?: string[], remote?: { allowHosts: string[], path?: string, maxWidth?: number, cacheMaxAge?: number, fetchTimeoutMs?: number, maxBytes?: number } | false } | false`
+— **Varsayılan:** `{ widths, quality, skip, remote: false }` (remote kapalı)
+
+`public/` altındaki png/jpg görsellerin webp varyantlarını **build**'de üretir.
+`remote.allowHosts` verilirse çalışma anında uzak görselleri de proxy eder
+(`/_jskelet/image?url=&w=&q=` → webp).
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `widths` | `number[]` | `[400, 640, 960, 1280, 1920]` | Build ve remote `srcset` adayları. Kaynaktan büyük olanlar build'de elenir; kaynağın kendi genişliği (en fazla 1920) her zaman eklenir. |
+| `quality` | `number` | `78` | webp kalitesi. Build'de imzaya girer; remote uçta `q` varsayılanı. |
+| `skip` | `string[]` | `[]` | Build'de taranmayacak **dizin adları**. `assets` ve `fonts` her zaman atlanır. |
+| `remote` | `object \| false` | kapalı | Runtime optimizer. `allowHosts` **zorunlu**; boşsa uç mount edilmez. |
 
-`public/` altındaki png/jpg görsellerin webp varyantlarını üretir.
+### `images.remote`
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `widths` | `number[]` | `[400, 640, 960, 1280, 1920]` | Üretilecek genişlikler. Kaynaktan büyük olanlar elenir; kaynağın kendi genişliği (en fazla 1920) her zaman eklenir. |
-| `quality` | `number` | `78` | webp kalitesi. Değişince kodlayıcı imzası değişir ve tüm görseller yeniden kodlanır. |
-| `skip` | `string[]` | `[]` | Taranmayacak **dizin adları**. `assets` ve `fonts` her zaman atlanır. |
+| `allowHosts` | `string[]` | `[]` | Çekilebilecek host'lar. `*.cdn.example.com` sonek jokerini destekler. |
+| `path` | `string` | `/_jskelet/image` | Optimizer GET yolu. |
+| `maxWidth` | `number` | `1920` | `w` üst sınırı. |
+| `cacheMaxAge` | `number` | `2592000` (30 gün) | Yanıt `Cache-Control` max-age (saniye). Disk önbelleği `.jskelet/image-cache/`. |
+| `fetchTimeoutMs` | `number` | `10000` | Upstream fetch zaman aşımı. |
+| `maxBytes` | `number` | `10485760` (10 MiB) | Upstream gövde üst sınırı. |
 
-`false` verilirse görsel adımı hiç çalışmaz. Adım `sharp` gerektirir ve watch
-turunda hiç çalışmaz. Ayrıntı: [08-build.md](./08-build.md).
+`false` verilirse görsel adımı hiç çalışmaz. Build adımı `sharp` gerektirir ve
+watch turunda hiç çalışmaz. Remote açıksa `sharp` **runtime**'da da gerekir;
+yoksa optimizer kaynak URL'ye 302 yönlendirir. Ayrıntı: [08-build.md](./08-build.md).
 
 ```js
-images: { widths: [400, 800, 1200], quality: 82, skip: ["indirmeler"] }
+images: {
+  widths: [400, 800, 1200],
+  quality: 82,
+  skip: ["indirmeler"],
+  remote: {
+    allowHosts: ["static.ornek.com", "*.cdn.ornek.com"],
+  },
+}
 ```
 
+`image({ src: "https://static.ornek.com/a.jpg", width: 96, alt: "…" })` bu
+ayarla `src` / `srcset`'i `/_jskelet/image?url=…&w=96` biçimine çevirir.
+Elle URL kurmak için `remoteImageUrl(src, { width })` (`jskelet`).
+
 ## `clientEnv`
 
 **Tip:** `string[]` — **Varsayılan:** `[]`

package/docs/08-build.md

@@ -290,6 +290,13 @@ değiştirmez ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
 Bu adım `sharp` gerektirir. Kurulu değilse adım sessizce atlanır ve `image()`
 orijinal dosyaya döner. Watch turunda hiç çalışmaz.
 
+## Runtime uzak görsel proxy
+
+`images.remote.allowHosts` verilirse `createApp` `/_jskelet/image` ucunu
+mount eder. CMS / CDN kapakları build'e girmediği için `image()` bu host'lardaki
+URL'leri `?url=&w=` biçiminde yeniden yazar; uç sharp ile webp üretir ve
+`.jskelet/image-cache/` altına yazar. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
+
 ## Precompress
 
 Build çıktısı varlıkların brotli (kalite 11) ve gzip (seviye 9) kopyalarını

package/docs/10-dagitim.md

@@ -97,6 +97,7 @@ ENV HOST=0.0.0.0
 
 COPY package.json package-lock.json ./
 # sharp ve tailwind yalnızca build zamanı gerekli; çalışma imajına girmesin.
+# images.remote kullanıyorsanız sharp'ı production dependencies'e alın.
 RUN npm ci --omit=dev && npm cache clean --force
 
 COPY --from=build /app/jskelet.config.mjs ./jskelet.config.mjs
@@ -126,9 +127,11 @@ Notlar:
   anında yapılıyor. `lib/` yalnızca projenizde varsa kopyalayın.
 - **`.jskelet/` gerekir:** `manifest.json` olmadan `asset()` hash'li URL'leri
   bulamaz ve `jskelet start` build'i baştan çalıştırmaya kalkar.
-- **`sharp` çalışma imajında gerekmez:** yalnızca build zamanı görsel
+- **`sharp` çalışma imajında genelde gerekmez:** yalnızca build zamanı görsel
   optimizasyonu için. `--omit=dev` ile dışarıda kalır (devDependency olarak
-  kurulmuşsa).
+  kurulmuşsa). **`images.remote` açıksa** sharp runtime bağımlılığıdır —
+  production `dependencies`'e alın ya da runtime imajında ayrıca kurun; yoksa
+  optimizer kaynak URL'ye 302 yönlendirir.
 - `jskelet start`ı `npx` olmadan çağırmak isterseniz
   `CMD ["node", "node_modules/jskelet/bin/jskelet.mjs", "start"]` de çalışır.
 

package/docs/11-tasima.md

@@ -96,9 +96,10 @@ Bunları taşıma planında baştan hesaba katın:
   önce belgeyi hazırlar, `viewTransition` geçişi yumuşatır
   ([07](./07-yapilandirma.md)).
 - **Server Actions.** Form gönderimleri normal `app.post(...)` handler'larıdır.
-- **Otomatik görsel optimizasyonu (istek anında).** Optimizasyon build zamanında
-  yapılır ve yalnızca `public/` altındaki yerel görselleri kapsar; uzak görseller
-  olduğu gibi basılır.
+- **Otomatik görsel optimizasyonu (istek anında).** Yerel `public/` görselleri
+  hâlâ build zamanında optimize edilir. Uzak `http(s)` görseller
+  `images.remote.allowHosts` verilirse çalışma anında proxy edilir
+  (`/_jskelet/image` → webp); config yoksa olduğu gibi basılır.
 
 ## Yan yana örnek
 

package/docs/en/02-architecture.md

@@ -42,6 +42,8 @@ Request
  ├─ staticPrecompressed            .br/.gz copies produced at build (quality 11)
  ├─ express.static                 files under public/
  ├─ (dev) devtools                 only when NODE_ENV=development
+ ├─ admin (if enabled)             /_jskelet/admin
+ ├─ image optimizer (remote)       /_jskelet/image — when allowHosts is set
  ├─ body parsers                   urlencoded 64kb + json 256kb
  ├─ rewrites(afterFiles)           after static has been tried
  ├─ routes

package/docs/en/04-rendering.md

@@ -389,12 +389,16 @@ Behaviour:
 
 - For local raster images under `public/`, the webp variants generated at build
   time (`.jskelet/images.json`) are added automatically as `srcset` plus
-  intrinsic `width`/`height`. Images that are not in the manifest, or remote
-  ones, are emitted as-is.
-- If `srcset` is given by hand, or `unoptimized: true` is set, the manifest is
-  not consulted at all.
+  intrinsic `width`/`height`. Local paths missing from the manifest are emitted
+  as-is.
+- When `images.remote.allowHosts` is set, remote `http(s)` URLs are rewritten to
+  the `/_jskelet/image?url=&w=` proxy (webp). If `width` is set, `srcset`
+  includes 1x/2x plus config `widths`.
+- If `srcset` is given by hand, or `unoptimized: true` is set, neither the
+  manifest nor the remote proxy is used.
 - If only **one** variant was produced (because the source is already small),
-  `srcset`/`sizes` are not written; they would be pure noise.
+  `srcset`/`sizes` are not written; they would be pure noise. For remote images,
+  a single width still rewrites `src` to the optimized URL.
 - If `sizes` is not given a reasonable default is produced: the image is not
   scaled beyond its own intrinsic width, and it fills the viewport on narrow
   screens (`(max-width: Npx) 100vw, Npx`).

package/docs/en/07-configuration.md

@@ -494,24 +494,52 @@ icons: { scan: ["views", "client", "routes", "lib", "content"] }
 
 ## `images`
 
-**Type:** `{ widths?: number[], quality?: number, skip?: string[] } | false` —
-**Default:** `{}`
+**Type:**
+`{ widths?: number[], quality?: number, skip?: string[], remote?: { allowHosts: string[], path?: string, maxWidth?: number, cacheMaxAge?: number, fetchTimeoutMs?: number, maxBytes?: number } | false } | false`
+— **Default:** `{ widths, quality, skip, remote: false }` (remote off)
 
-Generates webp variants of the png/jpg images under `public/`.
+Generates webp variants of png/jpg files under `public/` at **build** time.
+When `remote.allowHosts` is set, also proxies remote images at runtime
+(`/_jskelet/image?url=&w=&q=` → webp).
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `widths` | `number[]` | `[400, 640, 960, 1280, 1920]` | Widths to generate. Ones larger than the source are dropped; the source's own width (at most 1920) is always added. |
-| `quality` | `number` | `78` | webp quality. When it changes, the encoder signature changes and every image is re-encoded. |
-| `skip` | `string[]` | `[]` | **Directory names** not to scan. `assets` and `fonts` are always skipped. |
+| `widths` | `number[]` | `[400, 640, 960, 1280, 1920]` | Candidates for build and remote `srcset`. Ones larger than the source are dropped at build; the source's own width (at most 1920) is always added. |
+| `quality` | `number` | `78` | webp quality. Part of the build encoder signature; default `q` on the remote endpoint. |
+| `skip` | `string[]` | `[]` | **Directory names** not to scan at build. `assets` and `fonts` are always skipped. |
+| `remote` | `object \| false` | off | Runtime optimizer. `allowHosts` is **required**; empty disables the route. |
+
+### `images.remote`
 
-If `false` is given, the image step never runs. The step requires `sharp` and
-never runs on a watch pass. Details: [08-build.md](./08-build.md).
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `allowHosts` | `string[]` | `[]` | Hosts that may be fetched. Supports a `*.cdn.example.com` suffix wildcard. |
+| `path` | `string` | `/_jskelet/image` | Optimizer GET path. |
+| `maxWidth` | `number` | `1920` | Cap for `w`. |
+| `cacheMaxAge` | `number` | `2592000` (30 days) | Response `Cache-Control` max-age (seconds). Disk cache under `.jskelet/image-cache/`. |
+| `fetchTimeoutMs` | `number` | `10000` | Upstream fetch timeout. |
+| `maxBytes` | `number` | `10485760` (10 MiB) | Upstream body size limit. |
+
+If `false` is given, neither surface runs. The build step requires `sharp` and
+never runs on a watch pass. With remote enabled, `sharp` is also needed at
+**runtime**; without it the optimizer 302-redirects to the source URL. Details:
+[08-build.md](./08-build.md).
 
 ```js
-images: { widths: [400, 800, 1200], quality: 82, skip: ["downloads"] }
+images: {
+  widths: [400, 800, 1200],
+  quality: 82,
+  skip: ["downloads"],
+  remote: {
+    allowHosts: ["static.example.com", "*.cdn.example.com"],
+  },
+}
 ```
 
+`image({ src: "https://static.example.com/a.jpg", width: 96, alt: "…" })`
+rewrites `src` / `srcset` to `/_jskelet/image?url=…&w=96`. To build URLs by
+hand, use `remoteImageUrl(src, { width })` from `jskelet`.
+
 ## `clientEnv`
 
 **Type:** `string[]` — **Default:** `[]`

package/docs/en/08-build.md

@@ -305,6 +305,13 @@ to the `.jskelet/images.json` manifest. `image()` looks at that manifest and add
 This step requires `sharp`. If it is not installed the step is silently skipped
 and `image()` falls back to the original file. It never runs on a watch pass.
 
+## Runtime remote image proxy
+
+When `images.remote.allowHosts` is set, `createApp` mounts `/_jskelet/image`.
+CMS / CDN covers never enter the build, so `image()` rewrites those host URLs to
+`?url=&w=`; the endpoint encodes webp with sharp and stores files under
+`.jskelet/image-cache/`. Details: [07-configuration.md](./07-configuration.md).
+
 ## Precompress
 
 Produces brotli (quality 11) and gzip (level 9) copies of the built assets:

package/docs/en/10-deployment.md

@@ -98,6 +98,7 @@ ENV HOST=0.0.0.0
 
 COPY package.json package-lock.json ./
 # sharp and tailwind are only needed at build time; keep them out of the runtime image.
+# If you use images.remote, move sharp to production dependencies.
 RUN npm ci --omit=dev && npm cache clean --force
 
 COPY --from=build /app/jskelet.config.mjs ./jskelet.config.mjs
@@ -127,9 +128,11 @@ Notes:
   rendering happens at runtime. Copy `lib/` only if your project has one.
 - **`.jskelet/` is needed:** without `manifest.json`, `asset()` cannot find the
   hashed URLs and `jskelet start` will try to run the build from scratch.
-- **`sharp` is not needed in the runtime image:** it is only for build-time image
-  optimization. `--omit=dev` leaves it out (if it was installed as a
-  devDependency).
+- **`sharp` is usually not needed in the runtime image:** it is only for
+  build-time image optimization. `--omit=dev` leaves it out (if it was installed
+  as a devDependency). **If `images.remote` is enabled**, sharp is a runtime
+  dependency — move it to production `dependencies` or install it in the
+  runtime image; otherwise the optimizer 302-redirects to the source URL.
 - If you would rather call `jskelet start` without `npx`,
   `CMD ["node", "node_modules/jskelet/bin/jskelet.mjs", "start"]` works too.
 

package/docs/en/11-migration.md

@@ -99,9 +99,10 @@ Account for these from the start in your migration plan:
   `viewTransition` smooths the transition
   ([07](./07-configuration.md)).
 - **Server Actions.** Form submissions are ordinary `app.post(...)` handlers.
-- **Automatic image optimization (at request time).** Optimization happens at
-  build time and only covers local images under `public/`; remote images are
-  emitted as-is.
+- **Automatic image optimization (at request time).** Local `public/` images
+  are still optimized at build time. Remote `http(s)` images can be proxied at
+  runtime when `images.remote.allowHosts` is set (`/_jskelet/image` → webp);
+  without that config they are emitted as-is.
 
 ## A side-by-side example
 

package/package.json

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

@@ -367,6 +367,32 @@ export const DEFAULT_SECURITY = {
   },
 };
 
+/**
+ * Build-zamanı görsel adımı + opsiyonel runtime uzak görsel proxy.
+ *
+ * `remote` kapalıyken `image()` uzak URL'leri olduğu gibi basar (eski davranış).
+ * Açılınca yalnızca `allowHosts` listesindeki host'lar proxy edilir — boş liste
+ * açık proxy / SSRF kapısı olurdu, bu yüzden allowHosts olmadan remote hiç
+ * mount edilmez.
+ */
+export const DEFAULT_IMAGES = {
+  widths: [400, 640, 960, 1280, 1920],
+  quality: 78,
+  skip: /** @type {string[]} */ ([]),
+  remote: {
+    /** @type {string[]} */
+    allowHosts: [],
+    path: "/_jskelet/image",
+    /** İzin verilen en büyük `w` (retina üstü israf). */
+    maxWidth: 1920,
+    /** Disk önbelleği Cache-Control max-age (saniye). */
+    cacheMaxAge: 60 * 60 * 24 * 30,
+    fetchTimeoutMs: 10_000,
+    /** Upstream gövde üst sınırı; aşılırsa 502. */
+    maxBytes: 10 * 1024 * 1024,
+  },
+};
+
 /**
  * Markalama. Header adı ve dev overlay yolu tek yerden değişsin diye
  * config'ten okunur — fork eden proje kendi adını verebilir.

package/src/config/index.js

@@ -37,6 +37,7 @@ import {
   DEFAULT_DEV_GATE_BYPASS,
   DEFAULT_DIRS,
   DEFAULT_HTML_CACHE_MAX_ENTRIES,
+  DEFAULT_IMAGES,
   DEFAULT_LOGS,
   DEFAULT_NAVIGATION,
   DEFAULT_NAVIGATION_EXCLUDE,
@@ -130,10 +131,29 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {string[]} watch Dev sunucusunun izlediği ek dizinler.
  * @property {{ family: string, slug?: string, weights: number[] }[]} fonts
  * @property {{ scan?: string[] } | false} icons
- * @property {{ widths?: number[], quality?: number, skip?: string[] } | false} images
+ * @property {ImagesConfig | false} images
  * @property {string[]} clientEnv Client bundle'a gömülecek env anahtarları.
  */
 
+/**
+ * @typedef {object} ImagesRemoteConfig
+ * @property {boolean} enabled
+ * @property {string[]} allowHosts
+ * @property {string} path
+ * @property {number} maxWidth
+ * @property {number} cacheMaxAge
+ * @property {number} fetchTimeoutMs
+ * @property {number} maxBytes
+ */
+
+/**
+ * @typedef {object} ImagesConfig
+ * @property {number[]} widths
+ * @property {number} quality
+ * @property {string[]} skip
+ * @property {ImagesRemoteConfig | false} remote
+ */
+
 /** @type {ResolvedConfig | null} */
 let config = null;
 
@@ -772,6 +792,83 @@ function normalizeSecurity(raw) {
   };
 }
 
+/**
+ * Build + runtime görsel ayarları. `false` → her iki yüzey de kapalı.
+ * `remote.allowHosts` boşsa remote kapalı kalır (açık proxy olmasın).
+ *
+ * @param {unknown} raw
+ * @returns {ImagesConfig | false}
+ */
+function normalizeImages(raw) {
+  if (raw === false) return false;
+
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const widths = asArray(source.widths ?? DEFAULT_IMAGES.widths, "images.widths")
+    .map((entry) => Number(entry))
+    .filter((entry) => Number.isFinite(entry) && entry > 0)
+    .map((entry) => Math.round(entry));
+
+  const quality = Number(source.quality ?? DEFAULT_IMAGES.quality);
+  const skip = asArray(source.skip ?? DEFAULT_IMAGES.skip, "images.skip")
+    .filter((entry) => typeof entry === "string")
+    .map(String);
+
+  /** @type {ImagesRemoteConfig | false} */
+  let remote = false;
+  if (source.remote !== false && source.remote != null) {
+    const rem = /** @type {Record<string, any>} */ (
+      source.remote === true ? {} : source.remote
+    );
+    const allowHosts = asArray(
+      rem.allowHosts ?? DEFAULT_IMAGES.remote.allowHosts,
+      "images.remote.allowHosts",
+    )
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map((entry) => String(entry).trim().toLowerCase());
+
+    if (allowHosts.length === 0) {
+      if (source.remote === true || rem.allowHosts != null) {
+        console.warn(
+          "[config] images.remote needs a non-empty allowHosts list; remote optimizer disabled",
+        );
+      }
+    } else {
+      remote = {
+        enabled: true,
+        allowHosts,
+        path: String(rem.path ?? DEFAULT_IMAGES.remote.path),
+        maxWidth: Math.max(
+          1,
+          Number(rem.maxWidth ?? DEFAULT_IMAGES.remote.maxWidth) ||
+            DEFAULT_IMAGES.remote.maxWidth,
+        ),
+        cacheMaxAge: Math.max(
+          0,
+          Number(rem.cacheMaxAge ?? DEFAULT_IMAGES.remote.cacheMaxAge) ||
+            DEFAULT_IMAGES.remote.cacheMaxAge,
+        ),
+        fetchTimeoutMs: Math.max(
+          1000,
+          Number(rem.fetchTimeoutMs ?? DEFAULT_IMAGES.remote.fetchTimeoutMs) ||
+            DEFAULT_IMAGES.remote.fetchTimeoutMs,
+        ),
+        maxBytes: Math.max(
+          1024,
+          Number(rem.maxBytes ?? DEFAULT_IMAGES.remote.maxBytes) ||
+            DEFAULT_IMAGES.remote.maxBytes,
+        ),
+      };
+    }
+  }
+
+  return {
+    widths: widths.length ? widths : [...DEFAULT_IMAGES.widths],
+    quality: Number.isFinite(quality) && quality > 0 ? quality : DEFAULT_IMAGES.quality,
+    skip,
+    remote,
+  };
+}
+
 /**
  * Dizin adlarını mutlak yola çevirir. `styles` bir dosya yolu olduğu için
  * de aynı çözümlemeden geçer; ayrı bir alan tutmaya değmez.
@@ -942,7 +1039,7 @@ export async function loadConfig(options = {}) {
     // olsun diye aynı yerden geçer.
     fonts: source.fonts ?? [],
     icons: source.icons ?? {},
-    images: source.images ?? {},
+    images: normalizeImages(source.images),
     clientEnv: source.clientEnv ?? [],
   };
 

package/src/index.js

@@ -37,6 +37,7 @@ export {
 } from "./http/cookies.js";
 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 { headHints } from "./server/head-hints.js";
 export { renderHeadMeta } from "./server/metadata.js";
 export {

package/src/server/create-app.js

@@ -17,6 +17,8 @@
  *      static'e düşer ve middleware anında sıkıştırır (kalite 5).
  *   4b. admin paneli (açıksa) — statikten sonra, route'lardan önce: kendi
  *      gövde ayrıştırıcısını taşır ve uygulama yolunu gölgeleyemez.
+ *   4c. image optimizer (images.remote) — uzak görselleri webp'ye çevirir;
+ *      body parser'dan önce, admin ile aynı katmanda.
  *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
  *      maliyeti ödenmesin.
  *   6. csrf — body parser'lardan sonra olmalı: token form alanından okunuyor.
@@ -137,6 +139,13 @@ export async function createApp(options = {}) {
     mountAdmin(app);
   }
 
+  // Uzak görsel proxy: allowHosts doluysa mount. Statikten sonra, body
+  // parser'dan önce — görsel GET'lerinde gövde ayrıştırma maliyeti ödenmesin.
+  if (config.images && config.images !== false && config.images.remote) {
+    const { mountImageOptimizer } = await import("./image-optimizer.js");
+    await mountImageOptimizer(app);
+  }
+
   app.use(express.urlencoded({ extended: false, limit: "64kb" }));
   app.use(express.json({ limit: "256kb" }));
 

package/src/server/image-optimizer.js

@@ -0,0 +1,339 @@
+/**
+ * Runtime uzak görsel proxy: allowlist'teki host'lardan çeker, sharp ile
+ * webp'ye çevirir, diske yazar ve uzun Cache-Control ile servis eder.
+ *
+ * Next.js `/_next/image` karşılığı. Build zamanı `images.mjs` yalnızca
+ * `public/` altındaki yerel dosyaları kapsar; CMS / CDN kapakları için bu uç
+ * gerekir. Kapalıyken (allowHosts yok) router hiç mount edilmez.
+ *
+ * sharp yoksa 302 ile orijinale yönlendirilir — sayfa bozulmaz, tasarruf
+ * olmaz. Deployment notu: remote açıksa sharp runtime bağımlılığıdır.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { tryImportFromApp } from "../build/resolve-peer.mjs";
+import { getConfig } from "../config/index.js";
+
+/** @type {typeof import('sharp') | null | undefined} */
+let sharpModule;
+
+/** @type {string | null} */
+let cacheDir = null;
+
+/**
+ * @returns {import('../config/index.js').ImagesRemoteConfig | null}
+ */
+export function getRemoteImages() {
+  const images = getConfig().images;
+  if (!images || images === false || !images.remote || !images.remote.enabled) {
+    return null;
+  }
+  return images.remote;
+}
+
+/**
+ * Mutlak http(s) URL mi ve allowHosts'ta mı.
+ * @param {string} src
+ * @returns {URL | null}
+ */
+export function parseAllowedRemoteUrl(src) {
+  const remote = getRemoteImages();
+  if (!remote || typeof src !== "string") return null;
+
+  let url;
+  try {
+    url = new URL(src);
+  } catch {
+    return null;
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (!isHostAllowed(url.hostname, remote.allowHosts)) return null;
+  if (isBlockedAddress(url.hostname)) return null;
+
+  return url;
+}
+
+/**
+ * @param {string} hostname
+ * @param {string[]} allowHosts
+ * @returns {boolean}
+ */
+export function isHostAllowed(hostname, allowHosts) {
+  const host = hostname.toLowerCase();
+  return allowHosts.some((entry) => {
+    const pattern = entry.toLowerCase();
+    if (pattern.startsWith("*.")) {
+      const suffix = pattern.slice(1); // ".example.com"
+      return host.endsWith(suffix) || host === pattern.slice(2);
+    }
+    return host === pattern;
+  });
+}
+
+/**
+ * Literal private / link-local / loopback host'ları reddet (SSRF).
+ * Allowlist asıl koruma; bu ek bir savunma katmanı.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isBlockedAddress(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "0.0.0.0" || host.endsWith(".localhost")) {
+    return true;
+  }
+  if (host === "::1" || host === "0:0:0:0:0:0:0:1") return true;
+
+  // IPv4
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (ipv4) {
+    const parts = ipv4.slice(1).map(Number);
+    if (parts.some((n) => n > 255)) return true;
+    const [a, b] = parts;
+    if (a === 10 || a === 127 || a === 0) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+    return false;
+  }
+
+  // Ham IPv6 private / ULA — basit önek kontrolü
+  if (host.includes(":")) {
+    if (host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80")) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Optimizer URL'si üret. `image()` ve elle URL kuran uygulamalar için.
+ * @param {string} src Uzak görsel URL'si
+ * @param {{ width: number, quality?: number }} options
+ * @returns {string | null} Allowlist dışıysa null
+ */
+export function remoteImageUrl(src, options) {
+  const remote = getRemoteImages();
+  const allowed = parseAllowedRemoteUrl(src);
+  if (!remote || !allowed) return null;
+
+  const images = getConfig().images;
+  const quality =
+    options.quality ??
+    (images && images !== false ? images.quality : 78) ??
+    78;
+  const width = clampWidth(options.width, remote.maxWidth);
+
+  const params = new URLSearchParams({
+    url: allowed.href,
+    w: String(width),
+    q: String(quality),
+  });
+  return `${remote.path}?${params}`;
+}
+
+/**
+ * @param {number} width
+ * @param {number} maxWidth
+ * @returns {number}
+ */
+export function clampWidth(width, maxWidth) {
+  const n = Math.round(Number(width));
+  if (!Number.isFinite(n) || n < 1) return Math.min(640, maxWidth);
+  return Math.min(n, maxWidth);
+}
+
+/**
+ * Görüntülenen genişliğe göre srcset adayları (1x + 2x + config widths).
+ * @param {number} displayWidth
+ * @param {number[]} widths
+ * @param {number} maxWidth
+ * @returns {number[]}
+ */
+export function srcsetWidths(displayWidth, widths, maxWidth) {
+  const base = Math.max(1, Math.round(displayWidth));
+  const candidates = new Set([
+    base,
+    Math.min(base * 2, maxWidth),
+    ...widths.filter((w) => w >= base && w <= maxWidth),
+  ]);
+  return [...candidates].sort((a, b) => a - b);
+}
+
+/**
+ * @param {import('express').Express} app
+ * @returns {Promise<void>}
+ */
+export async function mountImageOptimizer(app) {
+  const remote = getRemoteImages();
+  if (!remote) return;
+
+  const config = getConfig();
+  cacheDir = path.join(config.dirs.generated, "image-cache");
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  sharpModule = await tryImportFromApp(config.root, "sharp");
+  if (!sharpModule) {
+    console.warn(
+      "[images.remote] sharp not installed; optimizer will redirect to the source URL",
+    );
+  }
+
+  app.get(remote.path, (req, res) => {
+    void handleOptimize(req, res, remote);
+  });
+}
+
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('../config/index.js').ImagesRemoteConfig} remote
+ */
+async function handleOptimize(req, res, remote) {
+  const rawUrl = typeof req.query.url === "string" ? req.query.url : "";
+  const allowed = parseAllowedRemoteUrl(rawUrl);
+  if (!allowed) {
+    res.status(400).type("text").send("Invalid or disallowed image url");
+    return;
+  }
+
+  const images = getConfig().images;
+  const defaultQ = images && images !== false ? images.quality : 78;
+  const quality = clampQuality(
+    typeof req.query.q === "string" ? req.query.q : defaultQ,
+    defaultQ,
+  );
+  const width = clampWidth(
+    typeof req.query.w === "string" ? req.query.w : 640,
+    remote.maxWidth,
+  );
+
+  if (!sharpModule) {
+    res.redirect(302, allowed.href);
+    return;
+  }
+
+  const key = cacheKey(allowed.href, width, quality);
+  const filePath = path.join(/** @type {string} */ (cacheDir), `${key}.webp`);
+
+  try {
+    if (fs.existsSync(filePath)) {
+      sendCached(res, filePath, remote.cacheMaxAge);
+      return;
+    }
+
+    const upstream = await fetchUpstream(allowed.href, remote);
+    if (!upstream.ok) {
+      res.status(502).type("text").send("Upstream image fetch failed");
+      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);
+
+    sendCached(res, filePath, remote.cacheMaxAge);
+  } catch (error) {
+    console.warn("[images.remote] optimize failed:", error);
+    // Bozuk kaynakta sayfa boş kalmasın: orijinale düş.
+    if (!res.headersSent) res.redirect(302, allowed.href);
+  }
+}
+
+/**
+ * @param {string} href
+ * @param {import('../config/index.js').ImagesRemoteConfig} remote
+ * @returns {Promise<{ ok: true, buffer: Buffer } | { ok: false }>}
+ */
+async function fetchUpstream(href, remote) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), remote.fetchTimeoutMs);
+
+  try {
+    const response = await fetch(href, {
+      signal: controller.signal,
+      redirect: "follow",
+      headers: {
+        // Bazı CDN'ler bot UA reddeder; tarayıcıya yakın tut.
+        Accept: "image/avif,image/webp,image/*,*/*;q=0.8",
+        "User-Agent": "jskelet-image-optimizer/1",
+      },
+    });
+
+    if (!response.ok) return { ok: false };
+
+    const type = response.headers.get("content-type") ?? "";
+    if (type && !type.startsWith("image/") && !type.includes("octet-stream")) {
+      return { ok: false };
+    }
+
+    const length = Number(response.headers.get("content-length") ?? 0);
+    if (length > remote.maxBytes) return { ok: false };
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.byteLength > remote.maxBytes) return { ok: false };
+
+    return { ok: true, buffer };
+  } catch {
+    return { ok: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * @param {import('express').Response} res
+ * @param {string} filePath
+ * @param {number} maxAge
+ */
+function sendCached(res, filePath, maxAge) {
+  res.setHeader("Content-Type", "image/webp");
+  res.setHeader(
+    "Cache-Control",
+    `public, max-age=${maxAge}, stale-while-revalidate=${Math.min(maxAge, 86400)}`,
+  );
+  res.setHeader("Vary", "Accept");
+  // Cache dir is under .jskelet/; Express send ignores dotfiles by default.
+  res.sendFile(path.resolve(filePath), { dotfiles: "allow" });
+}
+
+/**
+ * @param {string} href
+ * @param {number} width
+ * @param {number} quality
+ * @returns {string}
+ */
+function cacheKey(href, width, quality) {
+  return crypto
+    .createHash("sha256")
+    .update(`webp-q${quality}-e4:${width}:${href}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function clampQuality(value, fallback) {
+  const n = Math.round(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(100, Math.max(1, n));
+}

package/src/views/helpers/tags.js

@@ -4,6 +4,11 @@
  */
 import { attrs, esc, cn } from "./html.js";
 import { asset, getSpriteIds, optimizedImage } from "../../server/assets.js";
+import {
+  parseAllowedRemoteUrl,
+  remoteImageUrl,
+  srcsetWidths,
+} from "../../server/image-optimizer.js";
 import { getRequestContext, markTainted } from "../../http/request-context.js";
 import { getSignedCookie, randomToken, setSignedCookie } from "../../http/cookies.js";
 import { getConfig } from "../../config/index.js";
@@ -53,7 +58,11 @@ export function link(props) {
  * `next/image` karşılığı. `public/` altındaki yerel görseller için build'de
  * üretilen webp varyantları (`build/tasks/images.mjs`) otomatik olarak
  * `srcset` + intrinsic `width`/`height` olarak eklenir; manifest'te olmayan
- * ya da uzak görseller olduğu gibi basılır.
+ * yerel yollar olduğu gibi basılır.
+ *
+ * `images.remote.allowHosts` açıksa uzak http(s) URL'leri `/_jskelet/image`
+ * proxy'sine çevrilir (webp + `w`). `unoptimized` veya elle `srcset` bunu
+ * atlar.
  *
  * `priority` LCP görselleri için `fetchpriority=high` + eager yükleme yapar.
  * @param {{ src: string, alt: string, width?: number, height?: number,
@@ -79,20 +88,27 @@ export function image(props) {
   } = props;
 
   const optimized = unoptimized || srcset ? undefined : optimizedImage(src);
+  const remote = unoptimized || srcset ? null : remoteResponsive(src, width);
   const largest = optimized?.variants.at(-1);
   // Tek varyant üretilmişse (kaynak zaten küçükse) srcset/sizes gürültüden ibaret.
-  const responsive = optimized && optimized.variants.length > 1;
+  const responsive =
+    (optimized && optimized.variants.length > 1) ||
+    (remote && remote.srcset);
 
   const attributes = attrs({
-    src: largest?.url ?? src,
+    src: largest?.url ?? remote?.src ?? src,
     alt: alt ?? "",
     width: fill ? undefined : (width ?? optimized?.width),
     height: fill ? undefined : (height ?? optimized?.height),
     class: fill
       ? cn("absolute inset-0 h-full w-full object-cover", className)
       : className,
-    sizes: responsive ? (sizes ?? defaultSizes(optimized)) : sizes,
-    srcset: responsive ? toSrcSet(optimized) : srcset,
+    sizes: responsive
+      ? (sizes ?? (optimized ? defaultSizes(optimized) : remote?.sizes))
+      : sizes,
+    srcset: responsive
+      ? (optimized ? toSrcSet(optimized) : remote?.srcset)
+      : srcset,
     loading: loading ?? (priority ? "eager" : "lazy"),
     decoding: priority ? "sync" : "async",
     fetchpriority: priority ? "high" : undefined,
@@ -102,6 +118,37 @@ export function image(props) {
   return `<img${attributes}>`;
 }
 
+/**
+ * Uzak URL → optimizer `src` / `srcset`. Allowlist dışıysa null.
+ * @param {string} src
+ * @param {number | undefined} width
+ * @returns {{ src: string, srcset?: string, sizes?: string } | null}
+ */
+function remoteResponsive(src, width) {
+  if (!parseAllowedRemoteUrl(src)) return null;
+
+  const images = getConfig().images;
+  if (!images || images === false || !images.remote) return null;
+
+  const display = width && width > 0 ? width : 640;
+  const widths = srcsetWidths(display, images.widths, images.remote.maxWidth);
+  const urls = widths
+    .map((w) => {
+      const href = remoteImageUrl(src, { width: w });
+      return href ? `${href} ${w}w` : null;
+    })
+    .filter(Boolean);
+
+  const primary = remoteImageUrl(src, { width: display });
+  if (!primary) return null;
+
+  return {
+    src: primary,
+    srcset: urls.length > 1 ? urls.join(", ") : undefined,
+    sizes: `(max-width: ${display}px) 100vw, ${display}px`,
+  };
+}
+
 /**
  * @param {import("../../server/assets.js").OptimizedImage} optimized
  * @returns {string}