emf-converter 4.18.2 → 4.20.0

package/README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/ChristopherVR/emf-converter/actions/workflows/ci.yml/badge.svg)](https://github.com/ChristopherVR/emf-converter/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/emf-converter.svg)](LICENSE)
 
-A zero-dependency TypeScript library that converts **EMF** (Enhanced Metafile, including embedded **EMF+** / GDI+ records) and **WMF** (Windows Metafile) files into **PNG** or **SVG** (markup, a base64 data URL, React elements, or a generated JSX/TSX component).
+A zero-dependency TypeScript library that converts **EMF** (Enhanced Metafile, including embedded **EMF+** / GDI+ records) and **WMF** (Windows Metafile) files into **PNG**, **JPEG** or **SVG** (markup, a base64 data URL, React elements, or a generated JSX/TSX component).
 
 Windows metafiles are recorded GDI and GDI+ drawing calls, commonly embedded in Office documents and on the Windows clipboard. This library replays those calls the way Windows does: the PNG output is checked pixel for pixel against images painted by Windows itself (hundreds of ground-truth fixtures under `src/__fixtures__/gdi`, generated by `scripts/gdi-fixtures`), and the SVG output keeps vectors, text and gradients resolution-independent.
 
@@ -20,7 +20,7 @@ Windows metafiles are recorded GDI and GDI+ drawing calls, commonly embedded in
 
 ## Documentation and demo
 
-The documentation site at **https://christophervr.github.io/emf-converter/** includes a live demo: drop an `.emf` or `.wmf` file to see the PNG or SVG output, download it, or copy it as a TSX component.
+The documentation site at **https://christophervr.github.io/emf-converter/** includes a live demo: drop an `.emf` or `.wmf` file to see the PNG, JPEG or SVG output, download it, or copy it as a TSX component.
 
 The site is built with VitePress from the `docs/` directory. Run it locally with `bun run docs:dev`.
 
@@ -32,14 +32,14 @@ npm install emf-converter
 
 No required dependencies:
 
-- **Browser / Web Worker**: `OffscreenCanvas` or `HTMLCanvasElement` is used automatically. Bundlers select the dedicated browser entry through conditional exports; it contains no native canvas or Node filesystem imports. Installing `@napi-rs/canvas` is only needed for the optional Node backend.
-- **Node.js**: SVG output, and PNG output for drawings without text, work out of the box through the built-in rasteriser. For PNG output of drawings with text, either pass `fonts` (see [Exact text](#exact-text)) or install the optional [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas) (prebuilt, no `node-gyp`):
+- **Browser / Web Worker**: `OffscreenCanvas` or `HTMLCanvasElement` is used automatically for PNG and JPEG. Bundlers select the dedicated browser entry through conditional exports; it contains no native canvas or Node filesystem imports. Installing `@napi-rs/canvas` is only needed for the optional Node backend.
+- **Node.js**: SVG output, and PNG/JPEG output for drawings without text, work out of the box through the built-in rasteriser. For PNG/JPEG output of drawings with text, either pass `fonts` (see [Exact text](#exact-text)) or install the optional [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas) (prebuilt, no `node-gyp`):
 
   ```bash
   npm install @napi-rs/canvas
   ```
 
-  Without either, PNG conversion of a drawing that contains text returns `null` rather than an image missing its text.
+  Without either, PNG/JPEG conversion of a drawing that contains text returns `null` rather than an image missing its text.
 
 ## Quick start
 
@@ -60,6 +60,21 @@ const smooth = await convertMetafileToDataUrl(buffer, { gdiAntialias: true });
 
 Returns `Promise<string | null>`; `null` when the buffer is not a valid metafile (or, in plain Node.js, when it has text and neither `fonts` nor `@napi-rs/canvas` is available).
 
+### JPEG output
+
+```typescript
+import { convertMetafileToJpegDataUrl } from 'emf-converter';
+
+const jpeg = await convertMetafileToJpegDataUrl(buffer);
+// => "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
+
+// Quality 0-1 (default 0.92), the colour under transparent areas (default white),
+// plus every PNG option (maxWidth, dpiScale, fonts, ...).
+const preview = await convertMetafileToJpegDataUrl(buffer, { quality: 0.7, background: '#f4f4f4', maxWidth: 800 });
+```
+
+The same rendering as the PNG, encoded by the bundled baseline JPEG encoder, so the output is identical in browsers and Node.js. JPEG has no transparency: the metafile's transparent background is filled with `background`. Colour is kept at full resolution (4:4:4) so coloured lines and text stay crisp; `chromaSubsampling: true` halves it (4:2:0) for a smaller file.
+
 ### SVG output
 
 ```typescript
@@ -144,14 +159,19 @@ Without `fonts`, text is drawn by the host's canvas font engine (supply `fontFam
 
 #### `EmfConvertOptions`
 
-`wmfAnsiCodePage` sets the known ANSI code page of a WMF playback device
-(for example, `936` from Windows `GetACP()`). It applies to ANSI/DEFAULT text
-and ANSI font face names. Its default is `1252`; explicit text charsets and
-EMF text are unchanged. See the [API reference](docs/api.md) for supported values.
+`ansiCodePage` and `oemCodePage` set the known code pages of the playback
+device (for example, `936` from Windows `GetACP()` and `866` from `GetOEMCP()`).
+Windows decodes ANSI text records (EMF and WMF) in ANSI/DEFAULT fonts with the
+ANSI code page, WMF font face names too, and text in OEM fonts with the OEM code
+page. The defaults are `1252` and `437`; explicit text charsets are unchanged.
+`wmfAnsiCodePage` overrides `ansiCodePage` for WMF input only. See the
+[API reference](docs/api.md) for supported values.
 
 | Field                | Type                                  | Default           | Description |
 | -------------------- | ------------------------------------- | ----------------- | ----------- |
 | `maxWidth`           | `number`                              | None              | Maximum output width in pixels (aspect ratio preserved) |
+| `ansiCodePage`       | `number`                              | `1252`            | Playback-device ANSI code page (`GetACP()`) for ANSI/DEFAULT text |
+| `oemCodePage`        | `number`                              | `437`             | Playback-device OEM code page (`GetOEMCP()`) for OEM text |
 | `maxHeight`          | `number`                              | None              | Maximum output height in pixels |
 | `dpiScale`           | `number`                              | `1`               | Resolution multiplier; clamped to `4` |
 | `maxCanvasDimension` | `number`                              | `8192`            | Hard cap on output width/height in pixels |
@@ -161,6 +181,18 @@ EMF text are unchanged. See the [API reference](docs/api.md) for supported value
 | `fontSmoothing`      | `'cleartype' \| 'gray' \| 'mono'`     | `'cleartype'`     | What `DEFAULT_QUALITY` / `DRAFT_QUALITY` / `PROOF_QUALITY` fonts render as (Windows' system setting) |
 | `fontFamilyMap`      | `Record<string, string>`              | None              | Without `fonts`: maps Windows face names (case-insensitive) to locally available fonts, e.g. `{ calibri: 'Carlito' }` |
 
+### `convertMetafileToJpegDataUrl(buffer, options?)`
+
+Returns `Promise<string | null>`, a `data:image/jpeg;base64,...` URL (`null` in the same cases as the PNG function).
+
+#### `JpegConvertOptions` (extends `EmfConvertOptions`)
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `quality` | `number` | `0.92` | JPEG quality from `0` to `1`, as for `canvas.toDataURL('image/jpeg', quality)` |
+| `background` | `string` | `'#ffffff'` | Colour under transparent pixels, `#rgb` or `#rrggbb` (other values fall back to white) |
+| `chromaSubsampling` | `boolean` | `false` | `true` stores colour at half resolution (4:2:0) for a smaller file |
+
 ### SVG functions
 
 | Function | Returns |
@@ -188,7 +220,7 @@ Node.js only (returns `[]` elsewhere; the package stays browser-safe). Reads the
 
 ## How it works
 
-A three-phase pipeline: **parse → replay → export**. Records are replayed by the GDI, EMF+ or WMF handlers onto a Canvas (or the built-in pure-JavaScript rasteriser) for PNG, or onto a recording context for SVG. GDI and GDI+ shapes, raster operations, brushes, clipping, text and WMF playback are all fitted to output painted by Windows itself.
+A three-phase pipeline: **parse → replay → export**. Records are replayed by the GDI, EMF+ or WMF handlers onto a Canvas (or the built-in pure-JavaScript rasteriser) for PNG and JPEG, or onto a recording context for SVG. GDI and GDI+ shapes, raster operations, brushes, clipping, text and WMF playback are all fitted to output painted by Windows itself.
 
 See [How it works](docs/how-it-works.md) for the pipeline, the Windows-parity details and the full list of supported records.