feat: allow functions in overrideMap for programmatic color conversion

docs/api-javascript.md

@@ -6,6 +6,10 @@
 ### Functions
 
 - [`build`](#build)
+- [`builtinCmykConversion`](#builtincmykconversion)
+- [`builtinCmykReplacement`](#builtincmykreplacement)
+- [`builtinGrayConversion`](#builtingrayconversion)
+- [`builtinGrayReplacement`](#builtingrayreplacement)
 - [`create`](#create)
 - [`createVitePlugin`](#createviteplugin)
 - [`defineConfig`](#defineconfig)
@@ -14,12 +18,16 @@
 
 ### Interfaces
 
+- [`ColorConversionOptions`](#colorconversionoptions)
+- [`ImageContext`](#imagecontext)
 - [`StringifyMarkdownOptions`](#stringifymarkdownoptions)
 - [`TemplateVariable`](#templatevariable)
 
 ### Type Aliases
 
+- [`CmykConvertFunction`](#cmykconvertfunction)
 - [`Metadata`](#metadata)
+- [`ReplaceFunction`](#replacefunction)
 - [`StructuredDocument`](#structureddocument)
 - [`StructuredDocumentSection`](#structureddocumentsection)
 - [`VivliostyleConfigSchema`](#vivliostyleconfigschema)
@@ -64,7 +72,7 @@ build({
 
 ###### cmyk?
 
-`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; \} = `CmykSchema`
+`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: (\[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\] \| (`rgb`) => \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \} \| `Promise`\<\{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\>)[]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; `warnUnreplacedImages?`: `boolean`; \} = `CmykSchema`
 
 ###### config?
 
@@ -272,6 +280,85 @@ build({
 
 ***
 
+### builtinCmykConversion()
+
+> **builtinCmykConversion**(`options`): [`CmykConvertFunction`](#cmykconvertfunction)
+
+Returns a CmykConvertFunction that converts RGB colors to CMYK.
+Internally creates a 1x1 RGB pixmap and delegates to builtinCmykReplacement
+for the actual conversion, reusing ICC profile support.
+
+#### Parameters
+
+##### options
+
+[`ColorConversionOptions`](#colorconversionoptions) = `{}`
+
+#### Returns
+
+[`CmykConvertFunction`](#cmykconvertfunction)
+
+***
+
+### builtinCmykReplacement()
+
+> **builtinCmykReplacement**(`options`): [`ReplaceFunction`](#replacefunction)
+
+Returns a ReplaceFunction that converts RGB images to CMYK.
+When called without arguments, uses mupdf's DeviceCMYK color space.
+An output ICC profile can be provided for profile-based conversion.
+
+#### Parameters
+
+##### options
+
+[`ColorConversionOptions`](#colorconversionoptions) = `{}`
+
+#### Returns
+
+[`ReplaceFunction`](#replacefunction)
+
+***
+
+### builtinGrayConversion()
+
+> **builtinGrayConversion**(`options`): [`CmykConvertFunction`](#cmykconvertfunction)
+
+Returns a CmykConvertFunction that converts RGB colors to grayscale (K only).
+Internally delegates to builtinGrayReplacement and maps the Gray value to K.
+
+#### Parameters
+
+##### options
+
+[`ColorConversionOptions`](#colorconversionoptions) = `{}`
+
+#### Returns
+
+[`CmykConvertFunction`](#cmykconvertfunction)
+
+***
+
+### builtinGrayReplacement()
+
+> **builtinGrayReplacement**(`options`): [`ReplaceFunction`](#replacefunction)
+
+Returns a ReplaceFunction that converts RGB images to grayscale.
+When called without arguments, uses mupdf's DeviceGray color space.
+An output ICC profile can be provided for profile-based conversion.
+
+#### Parameters
+
+##### options
+
+[`ColorConversionOptions`](#colorconversionoptions) = `{}`
+
+#### Returns
+
+[`ReplaceFunction`](#replacefunction)
+
+***
+
 ### create()
 
 > **create**(`options`): `Promise`\<`void`\>
@@ -296,7 +383,7 @@ Scaffold a new Vivliostyle project.
 
 ###### cmyk?
 
-`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; \} = `CmykSchema`
+`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: (\[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\] \| (`rgb`) => \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \} \| `Promise`\<\{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\>)[]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; `warnUnreplacedImages?`: `boolean`; \} = `CmykSchema`
 
 ###### config?
 
@@ -526,7 +613,7 @@ Scaffold a new Vivliostyle project.
 
 ###### cmyk?
 
-`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; \} = `CmykSchema`
+`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: (\[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\] \| (`rgb`) => \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \} \| `Promise`\<\{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\>)[]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; `warnUnreplacedImages?`: `boolean`; \} = `CmykSchema`
 
 ###### config?
 
@@ -776,7 +863,7 @@ Open a browser for previewing the publication.
 
 ###### cmyk?
 
-`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; \} = `CmykSchema`
+`boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: (\[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\] \| (`rgb`) => \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \} \| `Promise`\<\{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\>)[]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; `warnUnreplacedImages?`: `boolean`; \} = `CmykSchema`
 
 ###### config?
 
@@ -1010,6 +1097,30 @@ Unified processor.
 
 ## Interfaces
 
+### ColorConversionOptions
+
+#### Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="outputprofile"></a> `outputProfile?` | `Uint8Array`\<`ArrayBufferLike`\> |
+
+***
+
+### ImageContext
+
+#### Methods
+
+##### asPNG()
+
+> **asPNG**(): `Uint8Array`
+
+###### Returns
+
+`Uint8Array`
+
+***
+
 ### StringifyMarkdownOptions
 
 Option for convert Markdown to a stringify (HTML).
@@ -1047,7 +1158,7 @@ Option for convert Markdown to a stringify (HTML).
 | `browser.tag?` | `string` |
 | `browser.type` | `"chrome"` \| `"chromium"` \| `"firefox"` |
 | <a id="cliversion"></a> `cliVersion` | `string` |
-| <a id="cmyk"></a> `cmyk?` | `boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; \} |
+| <a id="cmyk"></a> `cmyk?` | `boolean` \| \{ `mapOutput?`: `string`; `overrideMap?`: (\[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\] \| (`rgb`) => \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \} \| `Promise`\<\{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\>)[]; `reserveMap?`: \[`string` \| \{ `b`: `number`; `g`: `number`; `r`: `number`; \}, \{ `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; \}\][]; `warnUnmapped?`: `boolean`; `warnUnreplacedImages?`: `boolean`; \} |
 | <a id="config"></a> `config?` | `string` |
 | <a id="configdata"></a> `configData?` | [`VivliostyleConfigSchema`](#vivliostyleconfigschema) \| `null` |
 | <a id="coreversion"></a> `coreVersion` | `string` |
@@ -1105,6 +1216,22 @@ Option for convert Markdown to a stringify (HTML).
 
 ## Type Aliases
 
+### CmykConvertFunction()
+
+> **CmykConvertFunction** = (`rgb`) => `CMYKValue` \| `Promise`\<`CMYKValue`\>
+
+#### Parameters
+
+##### rgb
+
+`RGBValue`
+
+#### Returns
+
+`CMYKValue` \| `Promise`\<`CMYKValue`\>
+
+***
+
 ### Metadata
 
 > **Metadata** = `object`
@@ -1212,6 +1339,22 @@ VFM settings.
 
 ***
 
+### ReplaceFunction()
+
+> **ReplaceFunction** = (`image`) => `Uint8Array` \| `Promise`\<`Uint8Array`\>
+
+#### Parameters
+
+##### image
+
+[`ImageContext`](#imagecontext)
+
+#### Returns
+
+`Uint8Array` \| `Promise`\<`Uint8Array`\>
+
+***
+
 ### StructuredDocument
 
 > **StructuredDocument** = `object`

docs/config.md

@@ -429,10 +429,10 @@ pdfPostprocess takes precedence.
     Convert device-cmyk() colors to CMYK in the output PDF.
     Can be a boolean or a config object with overrideMap and warnUnmapped options.
 
-  - `replaceImage`: ([ReplaceImageEntry](#replaceimageentry))[]  
+  - `replaceImage`: ([ReplaceImageEntry](#replaceimageentry) | ((image: { asPNG(): Uint8Array }) => Uint8Array | Promise<Uint8Array>))[]  
     Replace images in the output PDF.
-    Each entry specifies a source image path and its replacement image path.
-    Useful for replacing RGB images with CMYK versions.
+    Each entry can be an object with source/replacement paths, an object with a source path
+    and a replacement function, or a bare function that processes all RGB images.
 
 #### Type definition
 
@@ -443,7 +443,14 @@ type PdfPostprocessConfig = {
     | "press-ready-local";
   preflightOption?: string[];
   cmyk?: boolean | CmykConfig;
-  replaceImage?: ReplaceImageEntry[];
+  replaceImage?: (
+    | ReplaceImageEntry
+    | ((image: {
+        asPNG(): Uint8Array;
+      }) =>
+        | Uint8Array
+        | Promise<Uint8Array>)
+  )[];
 };
 ```
 
@@ -453,10 +460,10 @@ type PdfPostprocessConfig = {
 
 - `CmykConfig`
 
-  - `overrideMap`: ("{tuple(Array)}")[]  
+  - `overrideMap`: ("{tuple(Array)}" | ((rgb: { r: number; g: number; b: number }) => { c: number; m: number; y: number; k: number } | Promise<{ c: number; m: number; y: number; k: number }>))[]  
     Custom RGB to CMYK color mapping.
-    Each entry is a tuple of [rgb, {c, m, y, k}].
-    RGB can be an object {r, g, b} with integers (0-10000) or a hex color string (e.g. "#ff0000").
+    Each entry is either a tuple of [rgb, {c, m, y, k}] or a function
+    that converts unmapped RGB colors to CMYK (used as fallback).
 
   - `reserveMap`: ("{tuple(Array)}")[]  
     Pre-register RGB to CMYK color mappings for use in SVG or other non-CSS contexts.
@@ -466,16 +473,39 @@ type PdfPostprocessConfig = {
   - `warnUnmapped`: boolean  
     Warn when RGB colors not mapped to CMYK are encountered. (default: true)
 
+  - `warnUnreplacedImages`: boolean  
+    Warn when non-CMYK-compatible images remain in the PDF after image replacement. (default: true)
+
   - `mapOutput`: string  
     Output the CMYK color map to a JSON file at the specified path.
 
 #### Type definition
 
 ```ts
 type CmykConfig = {
-  overrideMap?: "{tuple(Array)}"[];
+  overrideMap?: (
+    | "{tuple(Array)}"
+    | ((rgb: {
+        r: number;
+        g: number;
+        b: number;
+      }) =>
+        | {
+            c: number;
+            m: number;
+            y: number;
+            k: number;
+          }
+        | Promise<{
+            c: number;
+            m: number;
+            y: number;
+            k: number;
+          }>)
+  )[];
   reserveMap?: "{tuple(Array)}"[];
   warnUnmapped?: boolean;
+  warnUnreplacedImages?: boolean;
   mapOutput?: string;
 };
 ```
@@ -489,15 +519,21 @@ type CmykConfig = {
   - `source`: string | RegExp  
     Path to the source image file, or a RegExp pattern to match multiple files.
 
-  - `replacement`: string  
-    Path to the replacement image file. When source is a RegExp, supports $1, $2, etc. for captured groups.
+  - `replacement`: string | ((image: { asPNG(): Uint8Array }) => Uint8Array | Promise<Uint8Array>)  
+    Path to the replacement image file, a function that processes the image, or when source is a RegExp with a string replacement, supports $1, $2, etc.
 
 #### Type definition
 
 ```ts
 type ReplaceImageEntry = {
   source: string | RegExp;
-  replacement: string;
+  replacement:
+    | string
+    | ((image: {
+        asPNG(): Uint8Array;
+      }) =>
+        | Uint8Array
+        | Promise<Uint8Array>);
 };
 ```