emf-converter 3.3.0 → 3.5.0

package/dist/index.d.ts

@@ -1,20 +1,109 @@
 /**
- * Public API, a single auto-detecting entry point consumed by the rest of
- * the application.
+ * A tiny, framework-agnostic SVG document model plus its serialisers.
  *
- * The conversion pipeline for both formats follows the same high-level steps:
- * 1. Parse the file header to determine logical bounds and canvas dimensions
+ * The SVG backend (`svg-context.ts`) records a metafile's drawing into an
+ * {@link SvgNode} tree rather than straight into markup, so the same result
+ * can be handed to whichever consumer needs it:
+ *
+ * - {@link svgTreeToString}: standalone SVG markup (`<svg xmlns=...>...</svg>`)
+ * - {@link svgTreeToDataUrl}: a `data:image/svg+xml;base64,...` URL, usable
+ *   anywhere an image URL is (`<img src>`, CSS `background-image`, ...)
+ * - {@link svgTreeToReact}: live elements for React (or Preact, Solid's
+ *   `h`, Vue's `h`, ...), built through a caller-supplied `createElement`,
+ *   so this package never depends on a UI framework
+ * - {@link svgTreeToJsx}: JSX/TSX component source code, for build-time code
+ *   generation in the style of SVGR
+ *
+ * Attribute names are stored in their SVG (kebab-case) spelling; the React
+ * and JSX serialisers convert them to the camelCase property names React
+ * expects (`stroke-width` → `strokeWidth`, `clip-path` → `clipPath`, and a
+ * `style` string becomes a style object).
+ *
+ * @module svg-tree
+ */
+/** One SVG element. Text content (for `<text>`) lives in {@link SvgNode.text}. */
+interface SvgNode {
+    /** Element name, e.g. `path`, `g`, `linearGradient`. */
+    tag: string;
+    /** Attributes in SVG spelling (`stroke-width`, `clip-path`, `style`). */
+    attrs: Record<string, string | number>;
+    /** Child elements, in paint order. */
+    children?: SvgNode[];
+    /** Character data for text-bearing elements. Mutually exclusive with children. */
+    text?: string;
+}
+/** Serialises a tree to SVG markup. The root should be an `<svg>` element. */
+declare function svgTreeToString(node: SvgNode): string;
+/** Serialises a tree to a base64 `data:image/svg+xml` URL. */
+declare function svgTreeToDataUrl(node: SvgNode): string;
+/**
+ * A `createElement`-compatible factory: `React.createElement`, Preact's `h`,
+ * and most hyperscript-style factories fit this shape.
+ */
+type CreateElement<E> = (type: string, props: Record<string, unknown> | null, ...children: unknown[]) => E;
+/**
+ * Builds live framework elements from a tree via `createElement`.
+ *
+ * ```tsx
+ * import { createElement } from 'react';
+ * const tree = await convertMetafileToSvgTree(buffer);
+ * return tree ? svgTreeToReact(tree, createElement, { className: 'figure', width: '100%' }) : null;
+ * ```
+ *
+ * @param node          - The tree (normally the root `<svg>`).
+ * @param createElement - `React.createElement` or a compatible factory.
+ * @param rootProps     - Extra props merged onto the root element (override
+ *                        `width`/`height`, add `className`, `role`, ...).
+ */
+declare function svgTreeToReact<E>(node: SvgNode, createElement: CreateElement<E>, rootProps?: Record<string, unknown>): E;
+/** Options for {@link svgTreeToJsx}. */
+interface SvgJsxOptions {
+    /** Component name. Default `Metafile`. */
+    componentName?: string;
+    /** Emit TypeScript (`SVGProps<SVGSVGElement>` typing). Default `true`. */
+    typescript?: boolean;
+    /**
+     * Spread the component's props onto the root `<svg>` (after the recorded
+     * attributes, so callers can override `width`/`height`). Default `true`.
+     */
+    spreadProps?: boolean;
+}
+/**
+ * Generates JSX/TSX source for a React component rendering the tree, for
+ * build-time code generation (write it to a `.tsx` file and import it).
+ *
+ * ```ts
+ * const tree = await convertMetafileToSvgTree(buffer, { idPrefix: 'logo-' });
+ * writeFileSync('Logo.tsx', svgTreeToJsx(tree!, { componentName: 'Logo' }));
+ * ```
+ *
+ * The output uses the automatic JSX runtime (no `import React` needed); with
+ * `typescript: true` it imports only the `SVGProps` type from `react`.
+ */
+declare function svgTreeToJsx(node: SvgNode, options?: SvgJsxOptions): string;
+
+/**
+ * Public API: auto-detecting EMF/WMF conversion to PNG or SVG.
+ *
+ * The conversion pipeline for both formats and both outputs follows the same
+ * high-level steps:
+ * 1. Parse the file header to determine logical bounds and output dimensions
  *    (tried as EMF first, then WMF, to auto-detect the format).
- * 2. Create an in-memory canvas (OffscreenCanvas preferred, HTMLCanvasElement
- *    fallback, or the optional `@napi-rs/canvas` Node.js backend).
- * 3. Replay every metafile record onto the canvas context in order.
+ * 2. Create a drawing surface: an in-memory canvas (OffscreenCanvas
+ *    preferred, HTMLCanvasElement fallback, or the optional `@napi-rs/canvas`
+ *    Node.js backend) for PNG output, or an {@link SvgContext} recorder for
+ *    SVG output.
+ * 3. Replay every metafile record onto the surface in order.
  * 4. Resolve "deferred images", bitmap / embedded-metafile draws that require
  *    async image decoding (via {@link createImageBitmap} or, in Node.js, the
- *    `@napi-rs/canvas` `loadImage` helper).
- * 5. Export the canvas contents as a `data:image/png;base64,...` URL.
+ *    `@napi-rs/canvas` `loadImage` helper). SVG output embeds PNG/JPEG/GIF/
+ *    WebP bytes verbatim and nested metafiles as nested SVG, with no decode.
+ * 5. Export: a `data:image/png;base64,...` URL, or an SVG tree that can be
+ *    serialised to markup, a data URL, React elements, or JSX source.
  *
  * @module emf-converter
  */
+
 /**
  * Configuration options for EMF/WMF conversion.
  */
@@ -25,8 +114,8 @@ interface EmfConvertOptions {
     maxHeight?: number;
     /**
      * DPI scale factor for higher-resolution output.
-     * Default is 2 (HiDPI). Set to 1 for 1:1 pixel mapping.
-     * Values above 4 are clamped to 4 to prevent excessive memory usage.
+     * Default is 1 (1:1 pixel mapping). Values above 4 are clamped to 4 to
+     * prevent excessive memory usage.
      */
     dpiScale?: number;
     /**
@@ -46,6 +135,106 @@ interface EmfConvertOptions {
      * 'ms shell dlg': 'Tahoma' }`. Applied to GDI, WMF, and EMF+ text.
      */
     fontFamilyMap?: Record<string, string>;
+    /**
+     * 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).
+ * `maxWidth`/`maxHeight`/`dpiScale`/`maxCanvasDimension` set the SVG's
+ * coordinate space (its `viewBox` and default `width`/`height`) and the
+ * resolution of any embedded raster content; vector content stays sharp at
+ * any display size.
+ */
+interface SvgConvertOptions extends EmfConvertOptions {
+    /**
+     * Evaluate raster operations that read the destination (exact ROP3 blits,
+     * 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.
+     * Default `true`.
+     */
+    includeSize?: boolean;
+    /**
+     * Prefix for every generated element id (clip paths, gradients,
+     * patterns). Ids must be unique within an HTML document, so give each
+     * inlined SVG its own prefix. Defaults to a per-process counter
+     * (`emf1-`, `emf2-`, ...).
+     */
+    idPrefix?: string;
 }
 /**
  * Converts an EMF (Enhanced Metafile) or WMF (Windows Metafile) binary buffer
@@ -56,23 +245,17 @@ interface EmfConvertOptions {
  * starts with a valid `EMR_HEADER` record, so it doubles as a safe format
  * sniff. When that probe fails, the buffer is parsed as WMF instead.
  *
- * For EMF: parses the EMF header, iterates over all EMR records, and replays
- * them onto an in-memory canvas. Embedded EMF+ (GDI+) records found inside
- * EMR_COMMENT payloads are handled transparently.
- *
- * For WMF: parses the optional Aldus placeable header and the standard WMF
- * header, then replays all META_* records onto a canvas.
- *
- * The canvas is rendered at a configurable DPI scale (default 1x, 1:1 pixel
- * mapping) via {@link EmfConvertOptions.dpiScale}. On the first call in a
- * given process, the optional Node.js canvas backend (`@napi-rs/canvas`) is
- * loaded once and cached; see {@link ensureNodeCanvasModule}.
- *
  * Returns `null` when:
  * - 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).
+ *   `@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,
@@ -82,6 +265,38 @@ interface EmfConvertOptions {
  */
 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
+ * {@link svgTreeToString} / {@link svgTreeToDataUrl}, render it in React
+ * with {@link svgTreeToReact}, or generate component source with
+ * {@link svgTreeToJsx}.
+ *
+ * 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.
+ */
+declare function convertMetafileToSvgTree(buffer: ArrayBuffer, options?: SvgConvertOptions, recursionDepth?: number): Promise<SvgNode | null>;
+/**
+ * Converts an EMF or WMF buffer into standalone SVG markup
+ * (`<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>`).
+ *
+ * @returns The SVG markup, or `null` for an invalid/empty metafile.
+ */
+declare function convertMetafileToSvg(buffer: ArrayBuffer, options?: SvgConvertOptions): Promise<string | null>;
+/**
+ * Converts an EMF or WMF buffer into a base64 SVG data URL
+ * (`data:image/svg+xml;base64,...`), usable directly as an `<img src>`.
+ *
+ * @returns The data URL, or `null` for an invalid/empty metafile.
+ */
+declare function convertMetafileToSvgDataUrl(buffer: ArrayBuffer, options?: SvgConvertOptions): Promise<string | null>;
+
 /**
  * The default DPI scale factor used for EMF/WMF rendering.
  * Set to 1 for 1:1 pixel mapping (default).
@@ -89,4 +304,54 @@ declare function convertMetafileToDataUrl(buffer: ArrayBuffer, options?: EmfConv
  */
 declare const DEFAULT_DPI_SCALE = 1;
 
-export { DEFAULT_DPI_SCALE, type EmfConvertOptions, convertMetafileToDataUrl };
+/**
+ * `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 };