@mlightcad/cad-pdf-exporter 0.0.0-stage → 1.8.0-preview.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mlightcad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @mlightcad/cad-pdf-exporter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless (Node) export of DXF/DWG drawings to vector PDF.
+
+> **1.8.0:** New package. Same shared pipeline as browser `cpdf`, via
+> `@mlightcad/cad-pdf-core`, so server/CI export does not need Playwright or a
+> browser. See the [upgrade guide](../../docs/development/upgrade-guide.md).
+
+Uses `@mlightcad/data-model` + `@mlightcad/pdf-renderer` through
+`@mlightcad/cad-pdf-core`, the same pipeline as the browser `cpdf` command in
+`@mlightcad/cad-pdf-plugin`. **Does not** depend on
+`@mlightcad/cad-simple-viewer` or a browser.
+
+## Options
+
+| Option          | Values                  | Default   | Notes |
+| --------------- | ----------------------- | --------- | ----- |
+| `colorMode`     | `color` / `monochrome`  | `color`   | `monochrome`: white paper, all drawing content black |
+| `textMode`      | `text` / `vector`       | `text`    | `text` embeds fonts so text stays selectable |
+| `exportLayouts` | `true` / `false`        | `true`    | `true`: model space and every paper-space layout, one page each |
+| `title`         | string                  | file stem | PDF document title |
+| `fontsDir`      | path                    | —         | Local font library (takes precedence over `fontsUrl`) |
+| `fontsUrl`      | URL                     | jsDelivr  | Remote font library base URL |
+| `fontMapping`   | `{ [from]: to }`        | —         | Font name substitutions |
+| `dwgParser`     | `libredwg` / `dwg`      | `libredwg`| `dwg` needs the optional `@mlightcad/dwg-converter` |
+| `dwgLicenseKey` | string                  | —         | License for `dwgParser: 'dwg'` |
+
+Model space is always framed by drawable extents. A headless export has no
+live view, so the plugin's `Display` framing is not offered.
+
+In `monochrome` mode, linework and text are black and solid/gradient fills
+become grey by luminance. Wipeouts still mask in white and raster images keep
+their pixels. PNG and JPEG images are embedded; other raster formats (BMP,
+GIF) need a browser canvas to convert, so they are skipped in Node.
+
+## Example
+
+After `pnpm build`, from this package:
+
+```sh
+node examples/export-pdf.mjs drawing.dwg drawing.pdf
+node examples/export-pdf.mjs drawing.dwg drawing-bw.pdf --color-mode monochrome
+node examples/export-pdf.mjs drawing.dwg drawing.pdf --text-mode vector --no-layouts --fonts-dir D:/cad-data
+```
+
+## API
+
+```ts
+import {
+  convertDatabaseToPdf,
+  exportFileToPdf
+} from '@mlightcad/cad-pdf-exporter'
+
+// File → file
+await exportFileToPdf('drawing.dwg', 'drawing.pdf', {
+  colorMode: 'monochrome',
+  // Local font library: a face folder, that folder with fonts.json, or a
+  // cad-data checkout (faces resolved from its fonts/ directory).
+  fontsDir: 'D:/code/cad-data'
+})
+
+// Already-open database → bytes
+const bytes = await convertDatabaseToPdf(database, { title: 'drawing' })
+```
+
+## Fonts
+
+Text is drawn by the same MText engine as the viewer, running on the Node
+main thread. Fonts come from `fontsDir` or `fontsUrl` (by default the public
+cad-data library on jsDelivr; set `HTTPS_PROXY` when the network needs a
+proxy). With `textMode: 'text'`, TrueType/OpenType/WOFF faces are subset
+and embedded. SHX fonts have nothing to embed, so their text is drawn as
+vector glyphs.
+
+## Related packages
+
+- `@mlightcad/cad-pdf-core` — shared options and export pipeline
+- `@mlightcad/cad-pdf-plugin` — browser `cpdf` / `-cpdf` commands
+- `@mlightcad/cad-html-exporter` — the HTML counterpart of this package