@imgly/pdf-importer 0.1.0-rc.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# @imgly/pdf-importer
+
+## 0.1.0
+
+First public release of `@imgly/pdf-importer` — convert PDF files into
+CE.SDK scenes using `@imgly/pdfjs-dist` (an IMG.LY fork of Mozilla
+pdf.js, https://github.com/imgly/pdf.js).
+
+### Pipeline
+
+- Extract → post-process → emit pipeline: walks pdf.js operator streams (`extract/walker.mjs`), emits drawable blocks (images, vector paths, text outlines) in paint order, uses `page.getTextContent()` for editable text runs, merges adjacent same-font/size runs with horizontal overlap into multi-line paragraph blocks, and writes the IR as CE.SDK blocks.
+- Text is always imported as full-paragraph blocks (no per-character or per-word splitting mode).
+- PDF points are converted to inches (1pt = 1/72 inch) for CE.SDK design units.
+- Spot color detection (CutContour, Thru-cut, etc.) for cut/fold mark handling.
+- `addGfontsAssetLibrary` helper to register the shared `@imgly/gfonts` asset source.
+
+### Font handling
+
+- Font-strategy cascade with lazy vector fallback. Shipped presets: `editableFirstStrategy` (default), `exactFidelityStrategy`, `assetLibraryStrategy`. `createFontStrategy` / `createFontCascade` for custom cascades.
+
+### Image handling
+
+- Image-modulated luminosity SMask support (per-pixel alpha compositing of soft masks).
+- PDF fill rule (`f`/`F` vs `f*`/`B*`) is forwarded to the `vector_path` shape.
+- Skia 9-patch tiling-pattern decomposition is accepted as-is.
+
+### Robustness
+
+- 180°-rotated text runs are no longer dropped during text pickup.
+- Tiling-pattern bitmaps and pdf.js `objs` cleanup race conditions are handled.

package/README.md

@@ -110,6 +110,25 @@ const sceneString = await engine.scene.saveToString();
 
 When using `addGfontsAssetLibrary()` (the default font resolver), the resulting scene string will contain Google CDN URLs for fonts. If you need fonts hosted on your own infrastructure, configure a custom font resolver instead of using the default Google Fonts integration.
 
+## Font Strategies
+
+The importer ships with three font-handling presets that trade editability against visual fidelity. Pick one via `PDFParser.fromFile(engine, blob, { fontStrategy })`, or compose your own with `createFontStrategy` / `createFontCascade`.
+
+| Preset | Behavior | When to use |
+|---|---|---|
+| `editableFirstStrategy` *(default)* | perfect-match → PDF-embedded subset bytes → any-match substitution | General-purpose import. Prefers asset-library typefaces for editability, falls back to the PDF's embedded subset for fidelity, substitutes when neither is available. |
+| `exactFidelityStrategy` | perfect-match → PDF-embedded subset bytes | Print finalization. Never substitutes; falls through to vector outline when no matching typeface or embedded font is available. |
+| `assetLibraryStrategy` | perfect-match → any-match substitution | Brand-locked tools. Skips the embedded-subset stage so only asset-library typefaces are used; non-matching fonts go through substitution or vector outline. |
+
+```js
+import { PDFParser, exactFidelityStrategy } from "@imgly/pdf-importer";
+
+const parser = await PDFParser.fromFile(engine, blob, {
+  fontStrategy: exactFidelityStrategy,
+});
+await parser.parse();
+```
+
 ## NodeJS Quick-Start Example
 
 > **Prerequisite — emoji handling.** Two CE.SDK settings need attention when
@@ -198,7 +217,7 @@ The PDF importer has some limitations and unsupported features that you should b
 
 2. **Font Support**
 
-   - If a font name is not available as a typeface asset source, it will be replaced with fallback fonts.
+   - Fonts not available as a typeface asset source fall back through the configured `fontStrategy` (see [Font Strategies](#font-strategies) above): embedded subset bytes when present, then resolver substitution, then a vector-outline rendering. The default strategy substitutes; configure `exactFidelityStrategy` to disable substitution.
 
 3. **Complex Vector Paths**
 
@@ -214,11 +233,11 @@ The PDF importer has some limitations and unsupported features that you should b
 
 6. **Image SMask Compositing**
 
-   - When a PDF image has an SMask (soft mask / per-pixel alpha), the alpha channel is composited into the image data and output as an RGBA PNG. This means JPEG images with an SMask lose the JPEG pass-through optimization and are decoded then re-encoded as PNG, which increases file size.
+   - Per-pixel soft masks (image-modulated luminosity SMasks) are supported and composited into the image as an RGBA PNG. As a consequence, JPEG images carrying an SMask lose the JPEG pass-through optimization — they are decoded and re-encoded as PNG, which increases file size.
 
-## Contributing
+## Changelog
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, adding test samples, and the regression workflow.
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
 ## License