@imgly/pdf-importer 0.1.0-rc.0

package/dist/node.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 {};