emf-converter 1.5.0 → 2.0.0

package/README.md

@@ -44,22 +44,20 @@ const pngDataUrl = await convertEmfToDataUrl(emfBuffer);
 const wmfPng = await convertWmfToDataUrl(wmfBuffer);
 
 // Optional: limit output dimensions (aspect ratio preserved)
-const scaled = await convertEmfToDataUrl(emfBuffer, 1024, 768);
+const scaled = await convertEmfToDataUrl(emfBuffer, { maxWidth: 1024, maxHeight: 768 });
 ```
 
 Both functions return `Promise<string | null>` — `null` if the buffer is invalid or no Canvas API is available.
 
 ## API
 
-### `convertEmfToDataUrl(buffer, maxWidth?, maxHeight?, options?)` · `convertWmfToDataUrl(buffer, maxWidth?, maxHeight?, options?)`
+### `convertEmfToDataUrl(buffer, options?)` · `convertWmfToDataUrl(buffer, options?)`
 
-| Parameter   | Type                                  | Description                                          |
-| ----------- | ------------------------------------- | ---------------------------------------------------- |
-| `buffer`    | `ArrayBuffer`                         | Raw EMF/WMF file bytes                               |
-| `maxWidth`  | `number` (optional)                   | Maximum output width in pixels                       |
-| `maxHeight` | `number` (optional)                   | Maximum output height in pixels                      |
-| `options`   | `EmfConvertOptions \| number` (opt.)  | Options object, or a numeric `dpiScale` (legacy)    |
-| **Returns** | `Promise<string \| null>`             | PNG data URL or `null` on failure                   |
+| Parameter   | Type                          | Description                                          |
+| ----------- | ----------------------------- | ---------------------------------------------------- |
+| `buffer`    | `ArrayBuffer`                 | Raw EMF/WMF file bytes                               |
+| `options`   | `EmfConvertOptions` (optional)| Output size, DPI scale, record limits, font mapping |
+| **Returns** | `Promise<string \| null>`     | PNG data URL or `null` on failure                   |
 
 #### `EmfConvertOptions`
 
@@ -73,7 +71,7 @@ Both functions return `Promise<string | null>` — `null` if the buffer is inval
 | `fontFamilyMap`      | `Record<string, string>`   | —              | Maps Windows face names (case-insensitive) to fonts available locally, e.g. `{ calibri: 'Carlito' }` |
 
 ```ts
-const png = await convertEmfToDataUrl(buffer, undefined, undefined, {
+const png = await convertEmfToDataUrl(buffer, {
 	dpiScale: 2,
 	fontFamilyMap: { calibri: 'Carlito', 'ms shell dlg': 'Tahoma' },
 });
@@ -83,13 +81,19 @@ const png = await convertEmfToDataUrl(buffer, undefined, undefined, {
 
 A three-phase pipeline: **parse → replay → export**. The header parser extracts the drawing bounds, a Canvas is created and clamped to 8192×8192 (configurable via `maxCanvasDimension`), then records are scanned sequentially and dispatched to GDI, EMF+, or WMF handlers that drive the Canvas 2D context. Embedded bitmaps (DIB and GDI+ pixel formats) and recursively embedded metafiles are resolved asynchronously after the synchronous replay completes.
 
-It supports 300+ EMF GDI record types, the EMF+ (GDI+) record set, and legacy WMF records, including state, transforms, objects, shapes, poly/path operations, text, bitmaps, and clipping.
+It supports 300+ EMF GDI record types, the EMF+ (GDI+) record set, and legacy WMF records, including state, transforms, objects, shapes, poly/path operations, text, bitmaps, gradients, raster operations, and clipping:
+
+- **Clip regions with full boolean combine modes** — the converter tracks the active clip as a list of path shapes, so `Intersect`, `Union`, `Xor`, `Exclude`, `Complement`, and `Replace` combine modes work for `EMR_INTERSECTCLIPRECT` / `EMR_EXCLUDECLIPRECT` / `EMR_EXTSELECTCLIPRGN` (all `RGN_*` modes), the EMF+ `SetClipRect` / `SetClipPath` / `SetClipRegion` records (all `CombineMode` values, including nested region-node trees), and clip translation via `EMR_OFFSETCLIPRGN` / EMF+ `OffsetClip`. Subtraction and symmetric difference are expressed through even-odd fill-rule clipping, which Canvas 2D cannot do with plain `clip()` stacking.
+- **Gradient brushes** — GDI+ linear gradients render as Canvas linear gradients with their full colour-stop list (preset blend colours and blend factors are expanded into stops, and the optional brush transform rotates the gradient axis). Path gradients render as radial gradients from the centre colour to the surrounding colour across the boundary radius.
+- **Raster operations (ROP2)** — every `SetROP2` mode is mapped: `R2_BLACK`, `R2_WHITE`, `R2_NOP`, `R2_COPYPEN`, `R2_NOTCOPYPEN`, and `R2_NOT` are emulated exactly (via colour inversion and `difference` compositing); the remaining bitwise AND/OR/XOR-family modes are approximated with the nearest arithmetic composite (`difference` / `darken` / `lighten`), combined with pen-colour inversion for the NOT variants.
+- **GDI world transforms** — the scale and translation set by `EMR_SETWORLDTRANSFORM` / `EMR_MODIFYWORLDTRANSFORM` are applied to all GDI drawing, which is required for GDI+-exported EMF files (they record coordinates at 16× sub-pixel precision with a compensating transform). EMF+ records support the full affine transform set.
 
 ## Limitations
 
-- **Region boolean ops are partial** — rectangle, path, and union-of-rectangles regions (multi-rect `RGNDATA`, EMF+ rect/path region trees) are clipped correctly, but `Xor` / `Exclude` / `Complement` region operations have no Canvas 2D equivalent and fall back to intersect-or-skip. `EMR_EXCLUDECLIPRECT` and `EMR_OFFSETCLIPRGN` are recognised but not applied (Canvas 2D cannot subtract from or translate an active clip).
-- **Gradient brushes are simplified** — GDI+ linear/path gradient brushes render with their primary colour only (no interpolated colour stops yet).
-- **Raster operations (ROP2) are partial** — `SetROP2` modes `R2_COPYPEN` (default) and `R2_NOP` are faithful; `R2_XORPEN`, `R2_MASKPEN`, `R2_MERGEPEN`, and `R2_NOT` are approximated via Canvas composite modes (`xor` / `multiply` / `lighten` / `difference`). The bitwise NOT/NAND/NOR-family modes have no Canvas equivalent and fall back to normal source-over drawing.
+- **Approximated edge cases in region ops** — all six combine modes are exact while the tracked clip is at most one composable shape (the overwhelmingly common case). When the clip is already an intersection of several shapes, or was set from a live path bracket (`EMR_SELECTCLIPPATH`), `Union` / `Xor` / `Complement` degrade to the nearest conservative approximation (a console log notes when this happens).
+- **Bitwise ROP2 modes are arithmetic approximations** — Canvas compositing cannot reproduce true bitwise AND/OR/XOR against the destination, so those modes use `darken` / `lighten` / `difference` stand-ins; only the modes listed above as exact are pixel-faithful.
+- **Gradient details** — gradient wrap/tile modes clamp instead of tiling, path gradients are radial approximations of the true boundary-shaped falloff, and texture (image) brushes fall back to solid black.
+- **GDI rotation/skew** — rotation and shear components of the *GDI* world transform are ignored (EMF+ transforms are unaffected); plain-GDI metafiles using rotated world transforms are rare.
 - **Safety limits** — output is clamped to 8192×8192 and replay stops after 200,000 records (EMF/WMF) or 500,000 (EMF+). All three are overridable via `maxCanvasDimension` / `maxRecords`.
 - **Font rendering** uses the host Canvas font engine, so glyph metrics may differ from Windows GDI. Weight, italic, underline, and strike-out are honoured; supply `fontFamilyMap` to remap Windows face names to fonts available in your environment.
 

package/dist/index.d.mts

@@ -58,14 +58,12 @@ interface EmfConvertOptions {
  * - The logical bounds are zero-sized or negative.
  * - No canvas API is available (e.g. headless test environment).
  *
- * @param buffer    - The raw EMF file bytes.
- * @param maxWidth  - Optional cap on the output canvas width (pixels).
- * @param maxHeight - Optional cap on the output canvas height (pixels).
- * @param optionsOrDpiScale - Either an {@link EmfConvertOptions} object, or
- *   a numeric DPI scale (for backward compatibility). Default DPI scale is 2.
+ * @param buffer  - The raw EMF file bytes.
+ * @param options - Optional {@link EmfConvertOptions} controlling output size,
+ *   DPI scale, record limits, and font mapping.
  * @returns A `data:image/png;base64,…` string, or `null` on failure.
  */
-declare function convertEmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, maxHeight?: number, optionsOrDpiScale?: EmfConvertOptions | number, recursionDepth?: number): Promise<string | null>;
+declare function convertEmfToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
 /**
  * Converts a WMF (Windows Metafile) binary buffer to a PNG data-URL string.
  *
@@ -80,14 +78,12 @@ declare function convertEmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, max
  * - The header cannot be parsed or reports invalid dimensions.
  * - No canvas API is available.
  *
- * @param buffer    - The raw WMF file bytes.
- * @param maxWidth  - Optional cap on the output canvas width (pixels).
- * @param maxHeight - Optional cap on the output canvas height (pixels).
- * @param optionsOrDpiScale - Either an {@link EmfConvertOptions} object, or
- *   a numeric DPI scale. Default DPI scale is 2.
+ * @param buffer  - The raw WMF file bytes.
+ * @param options - Optional {@link EmfConvertOptions} controlling output size,
+ *   DPI scale, record limits, and font mapping.
  * @returns A `data:image/png;base64,…` string, or `null` on failure.
  */
-declare function convertWmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, maxHeight?: number, optionsOrDpiScale?: EmfConvertOptions | number, recursionDepth?: number): Promise<string | null>;
+declare function convertWmfToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
 
 /**
  * Canvas creation, styling, string reading, stock objects, and export helpers.

package/dist/index.d.ts

@@ -58,14 +58,12 @@ interface EmfConvertOptions {
  * - The logical bounds are zero-sized or negative.
  * - No canvas API is available (e.g. headless test environment).
  *
- * @param buffer    - The raw EMF file bytes.
- * @param maxWidth  - Optional cap on the output canvas width (pixels).
- * @param maxHeight - Optional cap on the output canvas height (pixels).
- * @param optionsOrDpiScale - Either an {@link EmfConvertOptions} object, or
- *   a numeric DPI scale (for backward compatibility). Default DPI scale is 2.
+ * @param buffer  - The raw EMF file bytes.
+ * @param options - Optional {@link EmfConvertOptions} controlling output size,
+ *   DPI scale, record limits, and font mapping.
  * @returns A `data:image/png;base64,…` string, or `null` on failure.
  */
-declare function convertEmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, maxHeight?: number, optionsOrDpiScale?: EmfConvertOptions | number, recursionDepth?: number): Promise<string | null>;
+declare function convertEmfToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
 /**
  * Converts a WMF (Windows Metafile) binary buffer to a PNG data-URL string.
  *
@@ -80,14 +78,12 @@ declare function convertEmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, max
  * - The header cannot be parsed or reports invalid dimensions.
  * - No canvas API is available.
  *
- * @param buffer    - The raw WMF file bytes.
- * @param maxWidth  - Optional cap on the output canvas width (pixels).
- * @param maxHeight - Optional cap on the output canvas height (pixels).
- * @param optionsOrDpiScale - Either an {@link EmfConvertOptions} object, or
- *   a numeric DPI scale. Default DPI scale is 2.
+ * @param buffer  - The raw WMF file bytes.
+ * @param options - Optional {@link EmfConvertOptions} controlling output size,
+ *   DPI scale, record limits, and font mapping.
  * @returns A `data:image/png;base64,…` string, or `null` on failure.
  */
-declare function convertWmfToDataUrl(buffer: ArrayBuffer, maxWidth?: number, maxHeight?: number, optionsOrDpiScale?: EmfConvertOptions | number, recursionDepth?: number): Promise<string | null>;
+declare function convertWmfToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
 
 /**
  * Canvas creation, styling, string reading, stock objects, and export helpers.