@imgly/pdf-importer 0.1.0-rc.0

package/README.md

@@ -0,0 +1,225 @@
+# PDF Importer for the CE.SDK
+
+## Overview
+
+The PDF Importer for the CE.SDK allows you to seamlessly integrate PDF files into the editor while retaining essential design attributes.
+
+Here's an overview of the main features:
+
+- _File Format Translation_: The importer converts **PDF files** into the CE.SDK scene file format using [`pdfjs-dist`](https://github.com/mozilla/pdf.js) (Mozilla's pdf.js), in its legacy/CJS-safe build.
+- _Bulk Importing_: The codebase is adaptable for bulk importing, streamlining large-scale projects.
+- _Color Translation_: RGB, CMYK, and Separation spot colors from PDFs are translated into CE.SDK's native `RGBAColor`, `CMYKColor`, and `SpotColor` variants. CMYK values are preserved end-to-end instead of collapsed to sRGB; Separation inks are registered on the document's spot-color registry (via `engine.editor.setSpotColorCMYK`) with their declared alternate CMYK values. DeviceN inks degrade to their alternate-space solid for now.
+
+The following PDF design elements will be preserved by the import:
+
+- _Positioning and Rotation_: Elements' positioning and rotation are accurately transferred.
+- _Image Elements_: Embedded images (JPEG, PNG) are extracted and placed as graphic blocks. Note that only images with formats that are [supported by CE.SDK](https://img.ly/docs/cesdk/js/file-format-support-3c4b2a/#importing-media) will be rendered.
+- _Text Elements_: Font family continuity is maintained, with options to supply font URIs or use Google fonts. Bold, italic, and weight styles are supported.
+- _Vector Paths_: SVG path data from the PDF is imported as vector path blocks.
+- _Colors and Gradients_: Solid colors, linear gradients, and radial gradients are faithfully reproduced.
+- _Spot Color Detection_: Cut/fold marks using spot colors (CutContour, Thru-cut, etc.) are detected and can be handled separately. Brand spot inks (Separation / DeviceN entries in the page's `/ColorSpace` resource dictionary) are preserved as `SpotColor` fills and registered on the CE.SDK document-level spot registry.
+
+## How It Works
+
+The importer runs a three-stage pipeline on each PDF page:
+
+1. **Extract** — a `pdfjs-dist` operator walker emits drawable blocks (images, vector paths, text outlines) in paint order. `page.getTextContent()` produces one editable text run per line.
+2. **Post-process** — adjacent text runs with the same font/size and horizontal overlap are merged into multi-line paragraph blocks.
+3. **Emit** — the intermediate representation is written as CE.SDK blocks: text, image, vector, outline.
+
+PDF points are converted to inches (1pt = 1/72 inch) for CE.SDK design units. Embedded images become `buffer://` URIs; engine-provided fonts use `bundle://` URIs.
+
+## Installation
+
+You can install `@imgly/pdf-importer` via npm or yarn. Use the following commands to install the package:
+
+```shell
+npm install @imgly/pdf-importer
+yarn add @imgly/pdf-importer
+```
+
+## Browser Quick-Start Example
+
+```js
+import CreativeEngine from "@cesdk/engine";
+import { PDFParser, addGfontsAssetLibrary } from "@imgly/pdf-importer";
+
+const blob = await fetch("https://example.com/document.pdf").then((res) =>
+  res.blob()
+);
+const engine = await CreativeEngine.init({
+  license: "YOUR_LICENSE",
+});
+// We use google fonts to replace well known fonts in the default font resolver.
+await addGfontsAssetLibrary(engine);
+const parser = await PDFParser.fromFile(engine, blob);
+
+await parser.parse();
+
+const image = await engine.block.export(
+  engine.block.findByType("//ly.img.ubq/page")[0],
+  "image/png"
+);
+const sceneExportUrl = window.URL.createObjectURL(image);
+console.log("The imported PDF file looks like:", sceneExportUrl);
+// You can now e.g export the scene as archive with engine.scene.saveToArchive()
+```
+
+## Saving Scenes with Stable URLs
+
+By default, the PDF importer creates internal `buffer://` URLs for embedded images. These are transient resources that work well when saving to an archive (`engine.scene.saveToArchive()`), which bundles all assets together.
+
+However, if you want to save scenes as JSON strings (`engine.scene.saveToString()`) with stable, permanent URLs (e.g., for storing in a database or referencing CDN-hosted assets), you need to relocate the transient resources first.
+
+### Why Relocate?
+
+- **Scene Archives** (`saveToArchive`): Include all assets in a single ZIP file. Transient `buffer://` URLs work fine.
+- **Scene Strings** (`saveToString`): Only contain references to assets. Transient URLs won't work when reloading the scene later. You need permanent URLs (e.g., `https://`).
+
+### How to Relocate Transient Resources
+
+After parsing the PDF file, use CE.SDK's native APIs to find and relocate all transient resources:
+
+```js
+// 1. Parse the PDF file
+const parser = await PDFParser.fromFile(engine, blob);
+await parser.parse();
+
+// 2. Find all transient resources (embedded images from the PDF)
+const transientResources = engine.editor.findAllTransientResources();
+
+// 3. Upload each resource and relocate to permanent URL
+for (const resource of transientResources) {
+  const { URL: bufferUri, size } = resource;
+
+  // Extract binary data from the buffer
+  const data = engine.editor.getBufferData(bufferUri, 0, size);
+
+  // Upload to your backend/CDN (implement your own upload logic)
+  const permanentUrl = await uploadToBackend(data);
+
+  // Relocate the resource to the permanent URL
+  engine.editor.relocateResource(bufferUri, permanentUrl);
+}
+
+// 4. Now save to string - all URLs will be permanent
+const sceneString = await engine.scene.saveToString();
+```
+
+### Note on Font URLs
+
+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.
+
+## NodeJS Quick-Start Example
+
+> **Prerequisite — emoji handling.** Two CE.SDK settings need attention when
+> running the importer headlessly under `@cesdk/node`:
+>
+> - **`ubq://forceSystemEmojis = false`** — by default the engine routes any
+>   codepoint that ICU classifies as `RGI_Emoji` (e.g. `♥`, `★`, the dingbats
+>   block) through the emoji font *even when the active typeface has a glyph
+>   for it*. Customer PDFs frequently embed real text fonts (ZapfDingbats,
+>   Webdings, …) that map these codepoints to actual glyphs; forcing the
+>   substitution discards the producer's intended glyph and pulls in a
+>   generic color emoji. Setting the flag to `false` makes the engine respect
+>   the embedded/substituted font when it covers the codepoint.
+> - **`ubq://defaultEmojiFontFileUri = <CDN URL>`** — `@cesdk/node` ships
+>   only `assets/core/`, not `assets/emoji/NotoColorEmoji.ttf`. Even with
+>   `forceSystemEmojis=false`, true color emoji (🧐, 🎉, …) that no embedded
+>   text font covers still need a working emoji font URI, or
+>   `engine.block.export(page, "image/png")` aborts with `FILE_FETCH_FAILED`
+>   for the engine's synthesised local-file URL. Point the engine at the
+>   IMG.LY-hosted preset, or self-host the file and supply your own URI /
+>   `bundle://` path.
+>
+> ```js
+> engine.editor.setSettingBool("ubq://forceSystemEmojis", false);
+> engine.editor.setSettingString(
+>   "ubq://defaultEmojiFontFileUri",
+>   "https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf",
+> );
+> ```
+>
+> See the [CE.SDK Emojis guide](https://img.ly/docs/cesdk/node/text/emojis-510651/)
+> for the full set of options. Browser consumers initialised with the
+> default IMG.LY-CDN `baseURL` already get the emoji font for free, and most
+> integrations also want `forceSystemEmojis=false` for the same
+> embedded-font-respect reason.
+
+```js
+// index.mjs
+import CreativeEngine from "@cesdk/node";
+import { promises as fs } from "fs";
+import { PDFParser, addGfontsAssetLibrary } from "@imgly/pdf-importer";
+
+async function main() {
+  const engine = await CreativeEngine.init({
+    license: "YOUR_LICENSE",
+  });
+
+  // Respect embedded fonts for emoji-class codepoints (♥, ★, …) and
+  // give true color emoji a working font URI — see the prerequisite
+  // note above.
+  engine.editor.setSettingBool("ubq://forceSystemEmojis", false);
+  engine.editor.setSettingString(
+    "ubq://defaultEmojiFontFileUri",
+    "https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf",
+  );
+
+  await addGfontsAssetLibrary(engine);
+
+  const pdfBuffer = await fs.readFile("./document.pdf");
+  const parser = await PDFParser.fromFile(engine, pdfBuffer.buffer);
+  await parser.parse();
+
+  const image = await engine.block.export(
+    engine.block.findByType("//ly.img.ubq/page")[0],
+    "image/png"
+  );
+  const imageBuffer = await image.arrayBuffer();
+  await fs.writeFile("./example.png", Buffer.from(imageBuffer));
+
+  engine.dispose();
+}
+main();
+```
+
+## Issues
+
+If you encounter any issues or have questions, please don't hesitate to contact us at support@img.ly.
+
+## Limitations and Unsupported Features
+
+The PDF importer has some limitations and unsupported features that you should be aware of:
+
+1. **Linked Images**
+
+   - Only embedded images are supported. External image references are not resolved.
+
+2. **Font Support**
+
+   - If a font name is not available as a typeface asset source, it will be replaced with fallback fonts.
+
+3. **Complex Vector Paths**
+
+   - Some complex clipping paths or compound shapes may experience minor distortion.
+
+4. **Annotations and Forms**
+
+   - PDF annotations, form fields, and interactive elements are not imported.
+
+5. **Transparency Groups**
+
+   - Advanced transparency group blending modes may not be fully reproduced.
+
+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.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, adding test samples, and the regression workflow.
+
+## License
+
+The software is free for use under the AGPL License.

package/dist/browser.d.ts

@@ -0,0 +1,300 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import CreativeEngine from '@cesdk/engine';
+import { Font, Typeface } from '@cesdk/engine';
+
+export interface TypefaceParams {
+	family: string;
+	style: Font["style"];
+	weight: Font["weight"];
+}
+export type TypefaceResolver = (fontParameters: TypefaceParams, engine: CreativeEngine) => Promise<FontResolverResult | null>;
+export declare function addGfontsAssetLibrary(engine: CreativeEngine): Promise<void>;
+export interface FontResolverResult {
+	typeface: Typeface;
+	font: Font;
+	substitutedFrom?: string;
+}
+export type WarningSeverity = "error" | "warning" | "info";
+export interface WarningDefinition {
+	/** Default + sole severity. Call sites do not override. */
+	severity: WarningSeverity;
+	/**
+	 * Template with `{name}` placeholders. Renderer throws if a placeholder
+	 * has no matching key in `params` — guards against silent typos.
+	 */
+	template: string;
+}
+export interface LogMessage<TCode extends string = string> {
+	/** Stable machine-readable identifier — never rename once shipped. */
+	code: TCode;
+	/** Inherited from the code definition. */
+	type: WarningSeverity;
+	/** Human-readable rendered string. */
+	message: string;
+	/** Raw structured fields — superset of all `{name}` placeholders. */
+	params: Record<string, unknown>;
+}
+/**
+ * Generic structured logger. Severity is registry-driven (PostgreSQL
+ * SQLSTATE pattern) — call sites cannot override. To change severity,
+ * edit the registry.
+ */
+export declare class Logger<R extends Record<string, WarningDefinition>> {
+	private readonly registry;
+	private messages;
+	constructor(registry: R);
+	emit<K extends keyof R & string>(code: K, params?: Record<string, unknown>): void;
+	getMessages(): LogMessage<keyof R & string>[];
+}
+declare const WARNING_CODES: {
+	readonly DOC_PAGE_COUNT: {
+		readonly severity: "info";
+		readonly template: "PDF has {count} page(s)";
+	};
+	readonly DOC_PAGE_BLOCK_COUNT: {
+		readonly severity: "info";
+		readonly template: "Page {page}: {imageCount} image, {vectorCount} vector, {textCount} text, {outlineCount} outline";
+	};
+	readonly DOC_PAGE_ROTATION_DROPPED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}PDF declares /Rotate {pageRotation}; the importer does not apply page rotation, so the imported page is in its un-rotated (native) orientation. Viewer-rendered output may differ from the source's display orientation.";
+	};
+	readonly BLOCK_KIND_UNKNOWN: {
+		readonly severity: "error";
+		readonly template: "An unknown block kind \"{kind}\" was encountered and was skipped.";
+	};
+	readonly FONT_OPENTYPE_PARSE_FAILED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}font \"{fontName}\" could not be parsed as OpenType{reason}. Glyph outlines will fall back to pdf.js raster paths \u2014 some shapes may render without stroke/anti-aliasing detail.";
+	};
+	readonly FONT_CMAP_AUGMENTED: {
+		readonly severity: "info";
+		readonly template: "Font \"{fontName}\" character map was augmented (cmap patches={cmapPatches}, injected glyphs={injectedGlyphs}).";
+	};
+	readonly FONT_CMAP_AUGMENT_FAILED: {
+		readonly severity: "warning";
+		readonly template: "Font \"{fontName}\" character map could not be augmented. Using the original font data \u2014 some glyphs may render incorrectly.";
+	};
+	readonly FONT_RESOLVER_MISS: {
+		readonly severity: "warning";
+		readonly template: "Font \"{fontFamily}\" could not be resolved. The text was rendered as a vector outline.";
+	};
+	readonly FONT_NOT_FOUND_IN_ASSETS: {
+		readonly severity: "warning";
+		readonly template: "Font \"{fontFamily}\" was not found in the asset library. The text was rendered as a vector outline.";
+	};
+	readonly FONT_SUBSTITUTED: {
+		readonly severity: "info";
+		readonly template: "Font \"{fontFamily}\" was substituted with \"{substitutedName}\" from the asset library.";
+	};
+	readonly FONT_REF_NOT_EXTRACTED: {
+		readonly severity: "error";
+		readonly template: "Text run references font \"{fontRef}\" which was not extracted. The text was skipped.";
+	};
+	readonly TEXT_RENDER_MODE_SKIPPED: {
+		readonly severity: "warning";
+		readonly template: "Text item{pageTag}: skipped \"{text}\" \u2014 PDF text rendering mode {modeLabel}. This text paints no ink; for mode 7 it acts as a clipping mask for following images, an effect the importer does not currently reproduce.";
+	};
+	readonly TEXT_OVERFLOW_AFTER_AUTOSIZE: {
+		readonly severity: "warning";
+		readonly template: "Text \"{text}\" did not fit after auto-sizing; it still overflows by {overflowLines} line(s). The text was kept; some content may be clipped.";
+	};
+	readonly TEXT_CLIP_MODE_7_DROPPED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}{label} at ({bbox}) {bboxSize} pt: dropped because the surrounding region was clipped by text in PDF render mode 7 (text-as-clipping-mask). The masked artwork cannot be reproduced as text-clipped content.";
+	};
+	readonly IMAGE_ENCODER_MISS: {
+		readonly severity: "warning";
+		readonly template: "{prefix}an image{idLabel} ({width}\u00D7{height} raw pixels{kind}) could not be encoded ({reason}). The image was dropped from the imported design.";
+	};
+	readonly IMAGE_PDFJS_UNRESOLVED: {
+		readonly severity: "error";
+		readonly template: "{prefix}image placement {idLabel} at ({bboxX}, {bboxY}) {bboxW}\u00D7{bboxH} pt could not be resolved by pdf.js and was dropped.";
+	};
+	readonly IMAGE_NO_PIXELS: {
+		readonly severity: "warning";
+		readonly template: "An image element has no pixel data and was skipped.";
+	};
+	readonly IMAGE_FLIP_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "Image flip could not be applied (engine version too old). The image will display without flip.";
+	};
+	readonly IMAGE_SKEW_DROPPED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}an image{idLabel} at ({bboxX}, {bboxY}) {bboxW}\u00D7{bboxH} pt has a skewed transform ctm={ctm}{residualStr} that cannot be represented. Placed axis-aligned \u2014 image content will appear un-skewed.";
+	};
+	readonly IMAGE_CLIPPED_NO_BYTES: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a clipped image at {bbox} had no decoded bytes; the placement was dropped before combining clip shapes.";
+	};
+	readonly IMAGE_CLIP_UNUSABLE: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a clipped image at {bbox} with {clipCount} clip path(s) has no usable clip \u2014 {degenerateCount} degenerate, {disjointCount} disjoint from the image. The image was dropped.";
+	};
+	readonly IMAGE_CLIP_EMPTY_INTERSECTION: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a clipped image at {bbox} with {clipCount} clip path(s) had an empty intersection. The image was dropped.";
+	};
+	readonly IMAGE_CLIP_COMBINE_FAILED: {
+		readonly severity: "error";
+		readonly template: "{prefix}a clipped image at {bbox} with {clipCount} clip path(s) could not be combined. The image was dropped from the imported design.";
+	};
+	readonly IMAGE_MASK_NO_FILL_COLOR: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a stencil ImageMask paint (objId={objId}) had no current fill colour to composite with. The mask was dropped from the imported design.";
+	};
+	readonly IMAGE_MASK_COMPOSITE_FAIL: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a stencil ImageMask (objId={objId}) at ({bboxX}, {bboxY}) {bboxW}\u00D7{bboxH} pt could not be composited with the current fill colour (space={colourSpace}). The mask was dropped from the imported design.";
+	};
+	readonly IMAGE_MASK_GROUP_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a paintImageMaskXObjectGroup batch of {count} stencil paints is not supported by the importer. The masks were dropped.";
+	};
+	readonly IMAGE_MASK_REPEAT_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a paintImageMaskXObjectRepeat tiling {count} stencil paints is not supported by the importer. The masks were dropped.";
+	};
+	readonly CLIP_DEGENERATE_FALLBACK: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a clipped vector path at {bbox} with {clipCount} clip path(s) has no usable clip \u2014 {degenerateCount} degenerate (zero width or height). Falling back to the unclipped path.";
+	};
+	readonly CLIP_COMBINE_STROKE_ONLY: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a clipped vector path at {bbox} with {clipCount} clip path(s) has no fill color (stroke-only) which cannot survive combine. Falling back to the unclipped path.";
+	};
+	readonly CLIP_COMBINE_FAILED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}a vector path at {bbox} with {clipCount} clip path(s) could not be combined. Rendered without its clip \u2014 some content may extend beyond the intended mask.";
+	};
+	readonly CLIP_COMBINE_TOO_FEW_INPUTS: {
+		readonly severity: "warning";
+		readonly template: "{prefix}clip combine was called with {inputCount} input block(s) (need at least 2). The owner block was emitted without its clips.";
+	};
+	readonly CLIP_COMBINE_NOT_COMBINABLE: {
+		readonly severity: "warning";
+		readonly template: "{prefix}clip combine rejected {inputCount} input block(s) as not combinable (nested or incompatible shapes). The owner block was emitted without its clips.";
+	};
+	readonly CLIP_COMBINE_THREW: {
+		readonly severity: "warning";
+		readonly template: "{prefix}clip combine of {inputCount} input block(s) failed ({reason}). The owner block was emitted without its clips.";
+	};
+	readonly COLOR_TYPE_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}{subject}color of type \"{colorType}\" is not supported. Rendered as black.";
+	};
+	readonly COLOR_SPACE_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}{elementLabel}color space \"{space}\" ({color}) at {bbox} is not supported. Rendered as black.";
+	};
+	readonly SPOT_COLOR_NO_ALTERNATE: {
+		readonly severity: "warning";
+		readonly template: "Spot color \"{name}\" has no resolvable alternate; leaving at engine default.";
+	};
+	readonly SPOT_COLOR_REGISTER_FAILED: {
+		readonly severity: "warning";
+		readonly template: "Failed to register spot color \"{name}\": {error}";
+	};
+	readonly BLEND_MODE_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "Blend mode \"{mode}\" is not supported. Using \"Normal\" as the default.";
+	};
+	readonly SHADING_UNRESOLVED: {
+		readonly severity: "error";
+		readonly template: "{prefix}gradient shading could not be resolved by pdf.js and was removed. The painted region will be missing in the imported scene.";
+	};
+	readonly SHADING_MESH_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}gradient shading uses an unsupported mesh variant (PDF ShadingType 4\u20137). The region was dropped because mesh gradients can't be represented as a CE.SDK gradient fill.";
+	};
+	readonly SHADING_UNKNOWN_IR_TAG: {
+		readonly severity: "error";
+		readonly template: "{prefix}gradient shading reported unknown IR tag \"{tag}\" and was dropped.";
+	};
+	readonly SHADING_INSUFFICIENT_STOPS: {
+		readonly severity: "warning";
+		readonly template: "{prefix}gradient shading produced fewer than two color stops and was dropped.";
+	};
+	readonly SHADING_NO_CLIP_FALLBACK_BBOX: {
+		readonly severity: "info";
+		readonly template: "{prefix}gradient shading was painted without an active clip path. Falling back to the shading /BBox; if this scene shows gradient bands outside the intended shape, file a bug.";
+	};
+	readonly SHADING_CLIP_DEGENERATE: {
+		readonly severity: "warning";
+		readonly template: "{prefix}gradient shading clip path was degenerate and the region was dropped.";
+	};
+	readonly SHADING_RADIAL_FOCAL_DROPPED: {
+		readonly severity: "info";
+		readonly template: "{prefix}radial gradient declared a non-zero inner radius (PDF Shading Type 3 focal point). It was approximated as a centered radial; the focal offset was dropped.";
+	};
+	readonly SHADING_UNKNOWN_RADIAL_SUBTYPE: {
+		readonly severity: "error";
+		readonly template: "{prefix}gradient shading reported unknown RadialAxial subtype \"{kind}\" and was dropped.";
+	};
+	readonly SHADING_NO_PATTERN_REF: {
+		readonly severity: "error";
+		readonly template: "{prefix}gradient shading was emitted without a pattern reference and was dropped.";
+	};
+};
+export type PageBounds = "trim" | "media";
+export type PdfLogger = Logger<typeof WARNING_CODES>;
+export declare class PDFParser {
+	private engine;
+	private pdfBytes;
+	private fontResolver;
+	private pageBounds;
+	private logger;
+	private constructor();
+	/**
+	 * Create a PDFParser instance from a PDF file.
+	 *
+	 * @param engine - CE.SDK engine instance
+	 * @param file - PDF file as Blob, File, or ArrayBuffer
+	 * @param options - Optional configuration
+	 * @param options.fontResolver - Custom font resolver. Invoked per-font
+	 *   for any text run whose font bytes are not embeddable (Type3 fonts,
+	 *   restricted-embedding fonts). On hit the importer emits an editable
+	 *   text block with the resolved typeface; on miss it falls back to a
+	 *   vector-path outline with preserved text metadata
+	 *   (`ly.img.pdf-importer.text.*`). Requires `addGfontsAssetLibrary`
+	 *   to be called on the engine before parse.
+	 * @returns A new PDFParser instance
+	 */
+	static fromFile(engine: CreativeEngine, file: Blob | File | ArrayBuffer, options?: {
+		fontResolver?: TypefaceResolver;
+		/**
+		 * Which PDF page box the emitted CE.SDK pages are sized to. Defaults
+		 * to `"trim"` (designed page + bleed margin, the end-user view).
+		 * `"media"` keeps pages at MediaBox (aka `page.view`) dimensions
+		 * with children unshifted — used by the regression pixel-diff harness
+		 * so CE.SDK exports match `pdftoppm`'s full-MediaBox reference images.
+		 */
+		pageBounds?: PageBounds;
+	}): Promise<PDFParser>;
+	/**
+	 * @deprecated Use options object instead: `fromFile(engine, file, { fontResolver })`
+	 */
+	static fromFile(engine: CreativeEngine, file: Blob | File | ArrayBuffer, fontResolver?: TypefaceResolver): Promise<PDFParser>;
+	/**
+	 * Parse the PDF file and emit a CE.SDK scene with all pages.
+	 *
+	 * Pipeline: pdf.js → IR (`extractDocument`) → line-run grouping →
+	 * CE.SDK scene (`emitInto`). Text extraction always produces full text
+	 * blocks: one block per line from pdf.js `getTextContent`, with adjacent
+	 * lines that share font/size and horizontal overlap merged into a single
+	 * multi-line block.
+	 *
+	 * @returns Parse result containing the scene ID and logger
+	 */
+	parse(): Promise<{
+		scene: number;
+		logger: PdfLogger;
+	}>;
+	/**
+	 * Get the logger for this parser instance.
+	 */
+	getLogger(): PdfLogger;
+}
+
+export {};