sync

docs/next-image-provider.md

@@ -12,7 +12,9 @@ Next.js custom loader получает только:
 
 Поэтому public image URL должен принимать эти параметры напрямую и сам запускать read-through генерацию при miss.
 
-## Loader config
+## Remote source loader config
+
+Remote source mode нужен для сценария, где consumer project уже имеет изображение в `public` или внешний image URL и хочет получить `srcset` без предварительной регистрации asset.
 
 В Next.js приложении используется `loaderFile`:
 
@@ -32,14 +34,14 @@ module.exports = {
 ```js
 "use client"
 
-const imageBaseUrl = process.env.NEXT_PUBLIC_IMAGE_PLATFORM_URL
+import { createImagePlatformNextLoader } from "@image-platform/client"
 
-export default function imagePlatformLoader({ src, width, quality }) {
-  const normalizedSrc = src.startsWith("/") ? src.slice(1) : src
-  const q = quality || 80
-
-  return `${imageBaseUrl}/images/${normalizedSrc}?w=${width}&q=${q}&f=auto`
-}
+export default createImagePlatformNextLoader({
+  baseUrl: process.env.NEXT_PUBLIC_IMAGE_PLATFORM_URL,
+  preset: "card",
+  project: process.env.NEXT_PUBLIC_IMAGE_PLATFORM_PROJECT,
+  sourceBaseUrl: process.env.NEXT_PUBLIC_SITE_ORIGIN,
+})
 ```
 
 Пример использования:
@@ -48,12 +50,28 @@ export default function imagePlatformLoader({ src, width, quality }) {
 import Image from "next/image"
 
 export function ProductCard() {
-  return <Image src="asset_123/v4/card" width={640} height={420} alt="Product" />
+  return <Image src="/images/product.jpg" width={640} height={420} alt="Product" />
 }
 ```
 
+Если `src` относительный, `sourceBaseUrl` превращает его в абсолютный source URL, например `https://site.example.com/images/product.jpg`. Если `src` уже абсолютный, он передаётся как есть.
+
 ## Public URL
 
+Remote source URL:
+
+```text
+GET /p/{project}/remote/{preset}?src={sourceUrl}&w={width}&q={quality}&f=auto
+```
+
+Пример:
+
+```text
+https://img.example.com/p/acme/remote/card?src=https%3A%2F%2Fsite.example.com%2Fimages%2Fproduct.jpg&w=640&q=80&f=auto
+```
+
+Managed asset URL:
+
 ```text
 GET /images/{assetId}/v{version}/{preset}?w={width}&q={quality}&f=auto
 ```
@@ -66,10 +84,12 @@ Route реализован в Fastify Gateway. Для `card` ширина дол
 https://img.example.com/images/asset_123/v4/card?w=640&q=80&f=auto
 ```
 
-`src` не должен быть source URL. Это должен быть versioned platform identifier, например `asset_123/v4/card`. Source URL хранится в PostgreSQL и не раскрывается в public image URL.
+Для managed asset `src` не должен быть source URL. Это должен быть versioned platform identifier, например `asset_123/v4/card`. Source URL хранится в PostgreSQL и не раскрывается в public image URL.
 
 `v{version}` меняется при обновлении source image. Старые URL можно кэшировать как immutable без purge.
 
+Для remote source `src` является исходным URL. Этот режим не immutable по умолчанию: Gateway отдаёт `GATEWAY_REMOTE_CACHE_CONTROL`, потому что источник может быть mutable.
+
 ## Format auto
 
 `f=auto` выбирает output format по `Accept` header: