emf-converter 1.4.3 → 1.6.0

package/README.md

@@ -51,29 +51,53 @@ Both functions return `Promise<string | null>` — `null` if the buffer is inval
 
 ## API
 
-### `convertEmfToDataUrl(buffer, maxWidth?, maxHeight?)` · `convertWmfToDataUrl(buffer, maxWidth?, maxHeight?)`
-
-| 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   |
-| **Returns** | `Promise<string \| null>` | PNG data URL or `null` on failure |
+### `convertEmfToDataUrl(buffer, maxWidth?, maxHeight?, options?)` · `convertWmfToDataUrl(buffer, maxWidth?, maxHeight?, 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                   |
+
+#### `EmfConvertOptions`
+
+| Field                | Type                       | Default        | Description                                                                 |
+| -------------------- | -------------------------- | -------------- | --------------------------------------------------------------------------- |
+| `maxWidth`           | `number`                   | —              | Maximum output width in pixels (aspect ratio preserved)                     |
+| `maxHeight`          | `number`                   | —              | Maximum output height in pixels                                             |
+| `dpiScale`           | `number`                   | `1`            | Resolution multiplier for sharper output; clamped to `4`                    |
+| `maxCanvasDimension` | `number`                   | `8192`         | Hard cap on canvas width/height in pixels                                   |
+| `maxRecords`         | `number`                   | `200000`/`500000` | Cap on records processed per stream before replay stops (EMF+ uses the higher default unless overridden) |
+| `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, {
+	dpiScale: 2,
+	fontFamilyMap: { calibri: 'Carlito', 'ms shell dlg': 'Tahoma' },
+});
+```
 
 ## How it works
 
-A three-phase pipeline: **parse → replay → export**. The header parser extracts the drawing bounds, a Canvas is created and clamped to 4096×4096, 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.
+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, gradients, raster operations, 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, 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
 
-- **EMF+ region objects** are not parsed (no Canvas 2D equivalent for boolean region clipping).
-- **Gradient brushes are simplified** — GDI+ linear/path gradients use the primary colour only.
-- **No raster operations (ROP)** — `SetROP2` blend modes are not applied.
-- **Limited clipping** — single rect/path clipping is supported; combined regions are not.
-- **Safety limits** — output is clamped to 4096×4096; processing stops after 50,000 records (EMF/WMF) or 100,000 (EMF+).
-- **Font rendering** uses the browser's font engine, so glyph metrics may differ from Windows GDI.
+- **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.
 
 ## License
 

package/dist/index.d.mts

@@ -25,6 +25,23 @@ interface EmfConvertOptions {
      * Values above 4 are clamped to 4 to prevent excessive memory usage.
      */
     dpiScale?: number;
+    /**
+     * Hard cap on the output canvas width/height in pixels. Guards against
+     * pathological metafiles. Defaults to {@link MAX_CANVAS_DIMENSION} (8192).
+     */
+    maxCanvasDimension?: number;
+    /**
+     * Maximum number of records processed per stream before replay stops.
+     * Defaults to 200,000 for GDI/WMF and 500,000 for the finer-grained EMF+
+     * stream. Supplying a value overrides both with the same cap.
+     */
+    maxRecords?: number;
+    /**
+     * Optional map from a (case-insensitive) Windows face name to a CSS font
+     * family available in the rendering environment, e.g. `{ calibri: 'Carlito',
+     * 'ms shell dlg': 'Tahoma' }`. Applied to GDI, WMF, and EMF+ text.
+     */
+    fontFamilyMap?: Record<string, string>;
 }
 /**
  * Converts an EMF (Enhanced Metafile) binary buffer to a PNG data-URL string

package/dist/index.d.ts

@@ -25,6 +25,23 @@ interface EmfConvertOptions {
      * Values above 4 are clamped to 4 to prevent excessive memory usage.
      */
     dpiScale?: number;
+    /**
+     * Hard cap on the output canvas width/height in pixels. Guards against
+     * pathological metafiles. Defaults to {@link MAX_CANVAS_DIMENSION} (8192).
+     */
+    maxCanvasDimension?: number;
+    /**
+     * Maximum number of records processed per stream before replay stops.
+     * Defaults to 200,000 for GDI/WMF and 500,000 for the finer-grained EMF+
+     * stream. Supplying a value overrides both with the same cap.
+     */
+    maxRecords?: number;
+    /**
+     * Optional map from a (case-insensitive) Windows face name to a CSS font
+     * family available in the rendering environment, e.g. `{ calibri: 'Carlito',
+     * 'ms shell dlg': 'Tahoma' }`. Applied to GDI, WMF, and EMF+ text.
+     */
+    fontFamilyMap?: Record<string, string>;
 }
 /**
  * Converts an EMF (Enhanced Metafile) binary buffer to a PNG data-URL string