emf-converter 3.4.0 → 3.5.0

package/dist/index.d.ts

@@ -136,15 +136,53 @@ interface EmfConvertOptions {
      */
     fontFamilyMap?: Record<string, string>;
     /**
-     * Antialias plain-GDI (EMF) vector shapes: Rectangle, Ellipse, RoundRect,
-     * Polygon, Polyline, arcs, and bracketed paths. Default `true`, Canvas's
-     * own smooth edges. `false` rasterises their fills and strokes the way
-     * Windows GDI does, without antialiasing and on GDI's own pixel grid, for
-     * output that matches what Windows paints pixel for pixel. It reads back
-     * and rewrites each shape's bounding box, so it is noticeably slower on
-     * shape-heavy files. EMF+ drawing and text are unaffected.
+     * Smooth shape edges instead of reproducing Windows' own rasterisation.
+     *
+     * PNG output defaults to `false`: plain-GDI vector shapes (Rectangle,
+     * Ellipse, RoundRect, Polygon, Polyline, arcs, bracketed paths, wide
+     * pens) are rasterised the way Windows GDI does, with its 28.4
+     * fixed-point geometry, fill rule, line algorithm and Bezier flattening,
+     * and EMF+ fills, strokes and clips follow the GDI+ `SmoothingMode` the
+     * file records (None, Default and HighSpeed aliased on GDI+'s pixel grid,
+     * AntiAlias and HighQuality with GDI+'s 8 x 4-sample antialiasing), so the
+     * PNG matches what Windows paints pixel for pixel.
+     *
+     * `true` draws every edge with Canvas's own antialiasing instead (still
+     * with GDI's geometry, pen widths, caps, joins and dash patterns), which
+     * looks smoother than Windows, especially for files recorded without
+     * GDI+ antialiasing.
+     *
+     * SVG output defaults to smooth vector edges (an SVG is meant to scale);
+     * `false` there embeds Windows' aliased shape pixels as image patches.
      */
     gdiAntialias?: boolean;
+    /**
+     * Font files to render GDI and WMF text with, exactly as Windows GDI
+     * does: TrueType `.ttf` / `.ttc` and raster `.fon` / `.fnt` bytes
+     * (`loadSystemFonts()` reads the installed ones in Node.js). The
+     * LOGFONT is realised against these files (face, weight, slant,
+     * `lfHeight`/`lfWidth`, charset fallback), each TrueType glyph is grid-fitted by the font's own TrueType
+     * instructions and scan-converted with TrueType dropout control
+     * (non-antialiased, 4x4 grayscale or ClearType per the LOGFONT's
+     * `lfQuality`), and glyphs are placed on GDI's integer device grid with
+     * GDI's own advance widths, cell metrics, underline and strike-out.
+     * Raster faces (MS Sans Serif, Helv, System, Terminal, ...) are drawn
+     * from their bitmaps at the size and whole-number stretch GDI picks.
+     * Supply the fonts the metafile names (for Windows-authored files, the
+     * matching files from `C:\Windows\Fonts`); a face that is missing is
+     * substituted the way GDI's font mapper would (by pitch and family),
+     * and without this option text is drawn with the canvas font engine.
+     * Ignored by SVG output, which keeps text as `<text>` but takes its
+     * per-glyph positions and metrics from these fonts.
+     */
+    fonts?: Array<ArrayBuffer | ArrayBufferView>;
+    /**
+     * Windows' system-wide font smoothing, which GDI applies to fonts that
+     * ask for `DEFAULT_QUALITY`, `DRAFT_QUALITY` or `PROOF_QUALITY` (most
+     * metafiles): `'cleartype'` (Windows' default), `'gray'` (standard
+     * antialiasing) or `'mono'` (smoothing off). Only used with `fonts`.
+     */
+    fontSmoothing?: 'cleartype' | 'gray' | 'mono';
 }
 /**
  * Options for the SVG outputs ({@link convertMetafileToSvg} and friends).
@@ -156,14 +194,34 @@ interface EmfConvertOptions {
 interface SvgConvertOptions extends EmfConvertOptions {
     /**
      * Evaluate raster operations that read the destination (exact ROP3 blits,
-     * exact bitwise ROP2) against a hidden raster mirror of the drawing, and
-     * embed the pixels they change as image patches. Needs a canvas backend
-     * (browser/worker canvas, or `@napi-rs/canvas` in Node.js); without one,
-     * or when set to `false`, those operations fall back to SVG blend modes
+     * bitwise ROP2, pattern-brush fills combined through ROP2, and
+     * `gdiAntialias: false` shapes) against a hidden raster mirror of the
+     * drawing, and embed the pixels they change as image patches. The mirror
+     * is the canvas backend when one exists (browser/worker canvas, or
+     * `@napi-rs/canvas` in Node.js) and the built-in pure-JavaScript
+     * rasteriser otherwise, so this needs no canvas. The built-in mirror
+     * cannot draw glyphs: where a raster operation reads pixels under text,
+     * every pixel whose result does not depend on the glyphs stays exact and
+     * the rest is handed to the SVG renderer as a blend-mode layer (exact for
+     * inversion and for masks whose channels are all 0 or 255). With `false`,
+     * no mirror is kept and those operations fall back to SVG blend modes
      * (`mix-blend-mode`), which are exact for the common mask ROPs on
      * black/white masks and approximate otherwise. Default `true`.
      */
     exactRasterOps?: boolean;
+    /**
+     * How EMF+ `DrawImage` bitmaps are scaled. `'renderer'` (the default)
+     * embeds the original image and lets the SVG renderer scale it with its
+     * own smoothing, which stays sharp at any display size. `'exact'` bakes
+     * each draw at device resolution with the GDI+-matching resampler (the
+     * PNG output's `InterpolationMode`/`PixelOffsetMode` model), so the SVG
+     * shows what GDI+ painted pixel for pixel at its nominal size. PNG and
+     * BMP images are decoded in pure JavaScript; JPEG, GIF and other formats
+     * need a canvas backend to decode and otherwise keep `'renderer'`
+     * scaling, as do draws GDI+ scales with a filter the resampler does not
+     * model (bicubic, high-quality).
+     */
+    imageResampling?: 'renderer' | 'exact';
     /**
      * Emit `width`/`height` attributes on the root `<svg>` (the `viewBox` is
      * always emitted). Set `false` for a fluid SVG that fills its container.
@@ -191,8 +249,13 @@ interface SvgConvertOptions extends EmfConvertOptions {
  * - The buffer matches neither a valid EMF header nor a valid WMF header.
  * - The logical bounds are zero-sized or negative.
  * - No canvas API is available (browser/worker canvas, or the optional
- *   `@napi-rs/canvas` package in plain Node.js). SVG output
- *   ({@link convertMetafileToSvg}) needs no canvas at all.
+ *   `@napi-rs/canvas` package in plain Node.js) AND the drawing contains
+ *   text or an image format only a canvas can decode (JPEG, GIF, ...).
+ *   Without a canvas the built-in pure-JavaScript rasteriser renders
+ *   everything else (vectors, clipping, gradients, bitmaps, PNG/BMP
+ *   images, every raster operation), but it has no font engine, so rather
+ *   than return an image silently missing its text it returns `null`. SVG
+ *   output ({@link convertMetafileToSvg}) needs no canvas at all.
  *
  * @param buffer  - The raw EMF or WMF file bytes.
  * @param options - Optional {@link EmfConvertOptions} controlling output size,
@@ -201,6 +264,7 @@ interface SvgConvertOptions extends EmfConvertOptions {
  * @returns A `data:image/png;base64,...` string, or `null` on failure.
  */
 declare function convertMetafileToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
+
 /**
  * Converts an EMF or WMF buffer (format auto-detected) into an SVG document
  * tree, the common source for every SVG output form: serialise it with
@@ -208,11 +272,12 @@ declare function convertMetafileToDataUrl(buffer: ArrayBuffer, options?: EmfConv
  * with {@link svgTreeToReact}, or generate component source with
  * {@link svgTreeToJsx}.
  *
- * Unlike PNG output this needs no canvas implementation: vectors, text,
- * gradients, clipping, and bitmaps are all recorded in pure JavaScript. A
- * canvas backend, when present, is used only to evaluate destination-
- * reading raster operations exactly (see {@link SvgConvertOptions.exactRasterOps})
- * and to measure text.
+ * This needs no canvas implementation: vectors, text, gradients, clipping,
+ * and bitmaps are all recorded in pure JavaScript, and destination-reading
+ * raster operations are evaluated exactly against a raster mirror of the
+ * drawing (see {@link SvgConvertOptions.exactRasterOps}), which is the
+ * canvas backend when one exists (it also measures text) and the built-in
+ * pure-JavaScript rasteriser otherwise.
  *
  * @returns The root `<svg>` node, or `null` for an invalid/empty metafile.
  */
@@ -239,4 +304,54 @@ declare function convertMetafileToSvgDataUrl(buffer: ArrayBuffer, options?: SvgC
  */
 declare const DEFAULT_DPI_SCALE = 1;
 
-export { type CreateElement, DEFAULT_DPI_SCALE, type EmfConvertOptions, type SvgConvertOptions, type SvgJsxOptions, type SvgNode, convertMetafileToDataUrl, convertMetafileToSvg, convertMetafileToSvgDataUrl, convertMetafileToSvgTree, svgTreeToDataUrl, svgTreeToJsx, svgTreeToReact, svgTreeToString };
+/**
+ * `loadSystemFonts()`: reads the operating system's installed font files
+ * (Node.js only) into buffers for the converter's `fonts` option.
+ *
+ * The Node.js modules are loaded with dynamic `import()` (and bundler
+ * ignore comments) only when the function is called, so the package stays
+ * browser-safe: nothing here is resolved or bundled for a browser build.
+ *
+ * @module load-system-fonts
+ */
+/** Options for {@link loadSystemFonts}. */
+interface LoadSystemFontsOptions {
+    /**
+     * Directories to scan instead of the platform defaults (Windows:
+     * `%WINDIR%\Fonts` and the per-user `%LOCALAPPDATA%\Microsoft\Windows\Fonts`;
+     * Linux: `/usr/share/fonts`, `/usr/local/share/fonts`, `~/.fonts`,
+     * `~/.local/share/fonts`; macOS: `/Library/Fonts`,
+     * `/System/Library/Fonts`, `~/Library/Fonts`). Missing directories are
+     * skipped.
+     */
+    dirs?: string[];
+    /**
+     * Keeps only the files this returns true for, given the full path and
+     * the lower-case file name (for example to load just the faces a
+     * metafile names: `(p, n) => /^(arial|times|cour)/.test(n)`).
+     */
+    filter?: (path: string, name: string) => boolean;
+    /** Subdirectory depth to descend (default 4; 0 scans only the directories themselves). */
+    maxDepth?: number;
+}
+/**
+ * Reads the installed TrueType (`.ttf`, `.ttc`) and raster (`.fon`,
+ * `.fnt`) font files, for `convertMetafileToDataUrl(data, { fonts })`
+ * and the SVG converters. Node.js only: in a browser (or any runtime
+ * without `process.versions.node`) it resolves to an empty array.
+ *
+ * Reading every installed font can take a few hundred megabytes on
+ * Windows; pass `filter` to load only what your metafiles use. Load once
+ * and reuse the array across conversions.
+ *
+ * @example
+ * ```ts
+ * import { convertMetafileToDataUrl, loadSystemFonts } from 'emf-converter';
+ *
+ * const fonts = await loadSystemFonts();
+ * const png = await convertMetafileToDataUrl(emfBytes, { fonts });
+ * ```
+ */
+declare function loadSystemFonts(options?: LoadSystemFontsOptions): Promise<Uint8Array[]>;
+
+export { type CreateElement, DEFAULT_DPI_SCALE, type EmfConvertOptions, type LoadSystemFontsOptions, type SvgConvertOptions, type SvgJsxOptions, type SvgNode, convertMetafileToDataUrl, convertMetafileToSvg, convertMetafileToSvgDataUrl, convertMetafileToSvgTree, loadSystemFonts, svgTreeToDataUrl, svgTreeToJsx, svgTreeToReact, svgTreeToString };