@imgly/pdf-importer 0.1.0-rc.2 → 0.2.0

package/dist/node.d.ts

@@ -1,22 +1,10 @@
 // Generated by dts-bundle-generator v9.5.1
 
 import CreativeEngine from '@cesdk/engine';
-import { Font, Typeface } from '@cesdk/engine';
+import { AssetAPI, Font, FontStyle, FontWeight, 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 {
+type WarningSeverity = "error" | "warning" | "info";
+interface WarningDefinition {
 	/** Default + sole severity. Call sites do not override. */
 	severity: WarningSeverity;
 	/**
@@ -25,7 +13,7 @@ export interface WarningDefinition {
 	 */
 	template: string;
 }
-export interface LogMessage<TCode extends string = string> {
+interface LogMessage<TCode extends string = string> {
 	/** Stable machine-readable identifier — never rename once shipped. */
 	code: TCode;
 	/** Inherited from the code definition. */
@@ -47,6 +35,50 @@ export declare class Logger<R extends Record<string, WarningDefinition>> {
 	emit<K extends keyof R & string>(code: K, params?: Record<string, unknown>): void;
 	getMessages(): LogMessage<keyof R & string>[];
 }
+type AssetQueryAPI = Pick<AssetAPI, "findAllSources" | "addLocalAssetSourceFromJSONURI" | "findAssets">;
+type AssetEngine = {
+	asset: AssetQueryAPI;
+};
+interface TypefaceParams {
+	family: string;
+	style?: Font["style"];
+	weight?: Font["weight"];
+}
+interface FontResolverOptions {
+	/**
+	 * When the requested weight is not available in the matched typeface,
+	 * pick the closest available weight using the CSS Font Matching algorithm.
+	 * Defaults to false — return null instead so the caller can decide what
+	 * to do (e.g. log a warning, use a different font).
+	 *
+	 * Only enable when the typeface name is known to be a good match. The
+	 * typeface query uses fuzzy matching, so applying weight fallback to a
+	 * poor name match can silently produce wildly wrong results.
+	 */
+	closestWeightMatch?: boolean;
+}
+interface FontResolverResult {
+	typeface: Typeface;
+	font: Font;
+	/**
+	 * Set to the originally requested family name when the typeface came from
+	 * the proprietary-fallbacks source (e.g. requested "Helvetica", got Roboto).
+	 * Undefined when the family matched the main Google Fonts catalog directly.
+	 * Always populated when applicable; consumers may ignore it.
+	 */
+	substitutedFrom?: string;
+}
+type TypefaceResolver = (params: TypefaceParams, engine: AssetEngine, options?: FontResolverOptions) => Promise<FontResolverResult | null>;
+/**
+ * Register the @imgly/gfonts asset sources (Google Fonts catalog + proprietary
+ * font fallbacks) with the CE.SDK engine.
+ *
+ * Adds two sources:
+ * - `ly.img.gfonts` — 1,394 Google Fonts typefaces (fuzzy-matched).
+ * - `ly.img.gfonts-fallbacks` — 16 proprietary-font alias entries
+ *   (e.g. Helvetica → Roboto), strict-matched.
+ */
+export declare function addGfontsAssetLibrary(engine: AssetEngine): Promise<void>;
 declare const WARNING_CODES: {
 	readonly DOC_PAGE_COUNT: {
 		readonly severity: "info";
@@ -64,6 +96,10 @@ declare const WARNING_CODES: {
 		readonly severity: "error";
 		readonly template: "An unknown block kind \"{kind}\" was encountered and was skipped.";
 	};
+	readonly PAGE_INDEX_OUT_OF_RANGE: {
+		readonly severity: "warning";
+		readonly template: "Requested page index {requested} is out of range; PDF has {available} page(s). No blocks were emitted.";
+	};
 	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.";
@@ -92,6 +128,22 @@ declare const WARNING_CODES: {
 		readonly severity: "error";
 		readonly template: "Text run references font \"{fontRef}\" which was not extracted. The text was skipped.";
 	};
+	readonly FONT_SUBSTITUTIONS: {
+		readonly severity: "warning";
+		readonly template: "Substituted {count} font famil{plural} during import: {pairs}.";
+	};
+	readonly FONT_SUBSET_FALLBACK: {
+		readonly severity: "warning";
+		readonly template: string;
+	};
+	readonly TEXT_OUTLINE_NO_FONT_FAMILY: {
+		readonly severity: "warning";
+		readonly template: "Text outline has no declared font family. The run was skipped.";
+	};
+	readonly TEXT_RUN_SKIPPED_NO_RESOLUTION: {
+		readonly severity: "warning";
+		readonly template: "No typeface or glyph outlines for \"{fontFamily}\"; run 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.";
@@ -110,7 +162,7 @@ declare const WARNING_CODES: {
 	};
 	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 template: "{prefix}image placement {idLabel} at ({bboxX}, {bboxY}) {bboxW}\u00D7{bboxH} pt could not be resolved by pdf.js (reason={reason}) and was dropped.";
 	};
 	readonly IMAGE_NO_PIXELS: {
 		readonly severity: "warning";
@@ -196,6 +248,10 @@ declare const WARNING_CODES: {
 		readonly severity: "warning";
 		readonly template: "Failed to register spot color \"{name}\": {error}";
 	};
+	readonly VECTOR_PATH_FILL_RULE_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "CE.SDK does not expose `{property}` on `vector_path` shapes (added in CE.SDK {sinceVersion}); the source PDF used non-zero winding fill, but imported paths render with the engine default (even-odd) winding. Self-overlapping or compound paths may render with holes inverted. Upgrade `@cesdk/engine` to {sinceVersion} or newer to preserve the source winding rule.";
+	};
 	readonly BLEND_MODE_UNSUPPORTED: {
 		readonly severity: "warning";
 		readonly template: "Blend mode \"{mode}\" is not supported. Using \"Normal\" as the default.";
@@ -236,15 +292,468 @@ declare const WARNING_CODES: {
 		readonly severity: "error";
 		readonly template: "{prefix}gradient shading was emitted without a pattern reference and was dropped.";
 	};
+	readonly TILING_PATTERN_AS_IMAGE: {
+		readonly severity: "info";
+		readonly template: "{prefix}tiling pattern \"{patternId}\" was imported as an image (single-image tiling pattern, e.g. Skia/Chrome PDF export of an embedded bitmap).";
+	};
+	readonly TILING_PATTERN_UNSUPPORTED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}tiling pattern \"{patternId}\" contains {imageCount} image XObject(s) and {otherOpCount} other paint op(s); only single-image tiling patterns are imported. The pattern fill was dropped.";
+	};
+	readonly TILING_PATTERN_UNRESOLVED: {
+		readonly severity: "error";
+		readonly template: "{prefix}tiling pattern \"{patternId}\" could not be resolved by pdf.js and was dropped.";
+	};
+	readonly TILING_PATTERN_IMAGE_DECODE_FAILED: {
+		readonly severity: "warning";
+		readonly template: "{prefix}tiling pattern \"{patternId}\" referenced image \"{imageObjId}\" but the image bytes could not be decoded. The pattern fill was dropped.";
+	};
+};
+interface Color {
+	space: "rgb" | "cmyk" | "gray";
+	/** in [0..1]. rgb:[r,g,b] cmyk:[c,m,y,k] gray:[g] */
+	values: number[];
+	/** in [0..1]; defaults to 1 */
+	alpha?: number;
+}
+type CesdkFontWeight = "thin" | "extraLight" | "light" | "normal" | "medium" | "semiBold" | "bold" | "extraBold" | "heavy";
+interface TextOutline {
+	kind: "text-outline";
+	/** pt, run bbox top-left */
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	/** SVG path data (all glyphs concatenated) */
+	d: string;
+	/** Original text (for diffing / accessibility) */
+	text: string;
+	/**
+	 * Family base parsed from the PDF PostScript name (subset prefix and
+	 * recognized weight/style/width suffix stripped — e.g.
+	 * `WTNEYF+Poppins-ExtraBold` → `Poppins`). Falls back to the full
+	 * subset-stripped name when no recognized suffix is present, so families
+	 * with internal hyphens like `SVN-BlogScript` survive intact. Suitable
+	 * as a font-resolver query.
+	 */
+	fontFamily: string;
+	/** pt */
+	fontSize: number;
+	/** Derived from fontObj.italic + name suffix. */
+	fontStyle?: "normal" | "italic";
+	/**
+	 * CE.SDK weight string. Together with `fontStyle` and `fontFamily` lets
+	 * the font-resolver substitute the correct typeface variant for an
+	 * editable text block, or — on resolver miss — be preserved as block
+	 * metadata.
+	 */
+	fontWeight?: CesdkFontWeight;
+	fill: Color | null;
+	/**
+	 * pt, pen x of the first glyph in device coords. Used by the
+	 * resolver-substitution path to place the editable text block at the
+	 * generator's setPositionX rather than the ink-bbox left edge (which is
+	 * shifted by the first glyph's LSB, typically ~1–2pt for caps).
+	 */
+	textOriginX?: number;
+	/**
+	 * Radians in CE.SDK screen (y-down) frame, 0 for horizontal. Optional;
+	 * absent on truly horizontal runs. Mirrors the `rotation` field on
+	 * TextRun so both emit paths can apply `setRotation` from the same
+	 * source. Sign convention: PDF's y-up Tm rotation atan2(b,a) negated to
+	 * match CE.SDK's y-down screen frame.
+	 */
+	rotation?: number;
+	/**
+	 * pt, ink-bbox width in the un-rotated text frame. Equals `width` for
+	 * horizontal runs; differs for ±90°/180° runs where `width`/`height`
+	 * describe the rotated AABB.
+	 */
+	unrotWidth?: number;
+	/**
+	 * pt, ink-bbox height in the un-rotated text frame. Pair with
+	 * `unrotWidth` to size the editable text block at its natural
+	 * pre-rotation dimensions; CE.SDK then auto-fits to its own typeface
+	 * metrics.
+	 */
+	unrotHeight?: number;
+	/**
+	 * [0..1], default 1. Like `VectorPath.opacity` and `ImageBox.opacity`,
+	 * lets the emitter apply `setOpacity` to text-outline blocks (the
+	 * walker uses this for runs that inherited a reduced fill alpha).
+	 */
+	opacity?: number;
+	/**
+	 * pt, baseline y in device (top-down) coords. Pen origin's y, used by
+	 * the resolver-substitution path to position the editable text block
+	 * at the baseline rather than the ink-bbox top.
+	 */
+	textOriginY?: number;
+}
+interface EmbeddedFont {
+	/**
+	 * Unique per subset. When a PDF embeds multiple subsets that share a PS
+	 * family name (common: one subset per chapter/page), this field is
+	 * suffixed with pdf.js's `loadedName` (e.g.
+	 * `PublicSans-Light#g_d0_f3`) so each subset keeps its own entry in
+	 * `Document.fonts`. Use `family` for display.
+	 */
+	postScriptName: string;
+	/**
+	 * Human typeface name from the font's opentype name table (falls back to
+	 * the PS family name).
+	 */
+	family: string;
+	/** 400 | 700 | 900 (pdf.js bold/black flags) */
+	weight?: number;
+	style?: "normal" | "italic";
+	/**
+	 * Width-axis label (OS/2 `usWidthClass` mapped to a normalized string,
+	 * or parsed from the PostScript suffix's width token: `cond`,
+	 * `extended`, `narrow`, …). Distinguishes condensed-width subsets
+	 * from normal-width subsets so the merger does not collapse them.
+	 * Absent when neither source carries width information.
+	 */
+	width?: string;
+	/** Raw TTF/OTF bytes */
+	data: Uint8Array;
+	/** 'font/otf' | 'font/ttf' */
+	mimeType: string;
+}
+interface ColorSpan {
+	from: number;
+	to: number;
+	fill: Color | null;
+}
+interface StyleSpan {
+	from: number;
+	to: number;
+	/** PostScript name from the originating run. */
+	fontRef: string;
+	/** CSS 100..900; matches `EmbeddedFont.weight`. */
+	fontWeight?: number;
+	/** Matches `EmbeddedFont.style`. */
+	fontStyle?: "normal" | "italic";
+}
+interface TextRun {
+	kind: "text-run";
+	/** pt, unrotated bbox top-left */
+	x: number;
+	/** pt */
+	y: number;
+	/** pt (with a small advance padding) */
+	width: number;
+	/** pt (ascender - descender, scaled by fontSize) */
+	height: number;
+	/** Rendered string (Unicode, not glyph codes) */
+	text: string;
+	/** postScriptName; resolves via Document.fonts */
+	fontRef: string;
+	/**
+	 * Logical font family (subset prefix + weight/style suffix stripped),
+	 * mirroring `EmbeddedFont.family`. Populated by `text-items.ts` from
+	 * the resolved EmbeddedFont so `postprocess-text.ts::canGroup` can
+	 * decide whether two distinct `fontRef`s (e.g. `Helvetica` +
+	 * `Helvetica-Bold`) belong to the same logical typeface and should
+	 * merge into one block with `styleSpans`. Absent on legacy inputs
+	 * (synthetic IR, older callers) — `canGroup` then falls back to the
+	 * stricter `fontRef === fontRef` test and keeps the runs split.
+	 */
+	family?: string;
+	/**
+	 * CSS 100..900, mirroring `EmbeddedFont.weight`. Used as the per-run
+	 * weight contribution when the merger bridges variants of the same
+	 * `family`. Absent on legacy inputs (merger then refuses to merge
+	 * across `fontRef` mismatches — see `family`).
+	 */
+	fontWeight?: number;
+	/** Mirrors `EmbeddedFont.style`. Pairs with `fontWeight`. */
+	fontStyle?: "normal" | "italic";
+	/**
+	 * Width-axis label, mirroring `EmbeddedFont.width`. Distinguishes
+	 * `Helvetica-Condensed` from `Helvetica-Regular` so the merger does
+	 * not collapse them — CE.SDK's per-range setters (`setTextFontWeight`,
+	 * `setTextFontStyle`) have no width parameter and would silently
+	 * render condensed glyphs at normal width.
+	 *
+	 * Values follow OS/2 `usWidthClass` semantics, normalized to a small
+	 * string set: `'ultraCondensed' | 'extraCondensed' | 'condensed' |
+	 * 'semiCondensed' | 'normal' | 'semiExpanded' | 'expanded' |
+	 * 'extraExpanded' | 'ultraExpanded'`. Absent on legacy inputs.
+	 */
+	fontWidth?: string;
+	/** pt */
+	fontSize: number;
+	/**
+	 * Radians, 0 for horizontal text. x/y place the block so rotation around
+	 * its center matches the PDF.
+	 */
+	rotation: number;
+	fill: Color | null;
+	/**
+	 * pt, pen origin x in PDF view-frame (top-left origin), pre-pivot-comp.
+	 * Populated by `text-items.ts`; used by `groupLineRuns` to test
+	 * pen-origin continuity between runs that pdf.js split mid-line for
+	 * kerning.
+	 */
+	baselineXPt?: number;
+	/** pt, pen origin y, same frame. */
+	baselineYPt?: number;
+	/**
+	 * pt, raw along-baseline advance from pdf.js (`item.width`). Distinct
+	 * from `width`, which carries a small rendering padding that is
+	 * intentionally invisible to merger logic.
+	 */
+	advanceWidthPt?: number;
+	/**
+	 * Per-character (UTF-16) color ranges within `text`. Set by `mergeRuns`
+	 * only when constituent runs differ in fill; absent for single-run
+	 * blocks and for merged groups with uniform fill (back-compat). Range
+	 * indices match `engine.block.setTextColor(id, color, from, to)`'s
+	 * contract.
+	 */
+	colorSpans?: ColorSpan[];
+	/**
+	 * Per-character (UTF-16) weight/style ranges within `text`. Set by
+	 * `mergeRuns` only when the merger bridged adjacent same-family runs
+	 * that use different weight/style variants (e.g. inline bold inside a
+	 * paragraph). Absent for single-run blocks and for merged groups with
+	 * uniform variant. Range indices match `engine.block.setTextFontWeight
+	 * (id, weight, from, to)` / `setTextFontStyle(id, style, from, to)`.
+	 */
+	styleSpans?: StyleSpan[];
+	/**
+	 * Lazy builder for the run's glyph outline as a vector path. Captures
+	 * the walker's pending run + glyph + font references; invoked by
+	 * `emit/cesdk.ts::emitGlyphsAsVectorPath` only when the font-strategy
+	 * cascade returns null and emission needs a fallback. Returns the SVG
+	 * `d` plus bbox geometry, or null when path extraction is unavailable
+	 * (Type 3 glyph charproc missing, opentype parse failure).
+	 *
+	 * Populated by `text-items.ts::extractTextRuns` from a per-BT/ET queue
+	 * stashed by the walker (`placeholder._lazyGlyphOutlines`). Holds
+	 * references — discarded when the IR is GC'd after emit. Builder is
+	 * called at most once per run (cascade-null is rare for asset-library
+	 * coverage).
+	 */
+	_buildGlyphOutline?: () => GlyphOutlineData | null;
+}
+interface GlyphOutlineData {
+	/** SVG path data in local bbox coordinates (top-left origin). */
+	d: string;
+	/** pt, bbox top-left in page coords. */
+	x: number;
+	/** pt */
+	y: number;
+	/** pt */
+	width: number;
+	/** pt */
+	height: number;
+}
+/**
+ * Per-run input to the cascade and emission layers. Built by
+ * `lib/make-request.ts` from the source IR block (either `TextRun` or
+ * `TextOutline`).
+ *
+ * Vector-outline data has two shapes depending on source kind:
+ *  - `TextOutline` sources carry `glyphPaths` eagerly (the walker built
+ *    the path because the font wasn't embeddable — Type 3 / restricted /
+ *    PUA).
+ *  - `TextRun` sources carry `buildGlyphOutline`, a lazy builder set up
+ *    by the walker + text-items pairing. Emission only invokes it when
+ *    the cascade returns null and a vector fallback is needed — most
+ *    documents have asset-library coverage and never call it.
+ */
+export interface FontRequest {
+	/** Display family (subset prefix stripped). */
+	family: string;
+	style: "normal" | "italic";
+	weight: Font["weight"];
+	/** Original text content; preserved for metadata + recovery. */
+	text: string;
+	/** Embedded subset bytes — present when the source was a TextRun. */
+	embeddedFont?: EmbeddedFont;
+	/** Concatenated glyph paths in local coords — present when the source was a TextOutline. */
+	glyphPaths?: string;
+	/** Lazy glyph-outline builder (TextRun sources). Built by walker;
+	 *  invoked at most once by emission when the cascade returns null. */
+	buildGlyphOutline?: () => GlyphOutlineData | null;
+	/** Original IR block — used by emission for geometry, fills, rotation, etc. */
+	source: TextRun | TextOutline;
+}
+export type CascadeResolution = {
+	kind: "typeface";
+	typeface: Typeface;
+	font?: Font;
+	/** Identifies which stage produced this resolution. */
+	provenance: string;
+	/** Forwarded from `FontResolverResult.substitutedFrom`. When set, the
+	 *  emission layer treats the resolution as substituted and recomputes
+	 *  layout. */
+	substitutedFrom?: string;
+} | {
+	kind: "subset";
+	embeddedFont: EmbeddedFont;
+	provenance: "embedded-subset";
 };
-export type PageBounds = "trim" | "media";
-export type PdfLogger = Logger<typeof WARNING_CODES>;
+/**
+ * Stage outcome. Distinguishing "pass with reason" from `null` lets debug
+ * logs explain *why* the cascade reached a given stage's neighbour. Cheap
+ * to carry now; expensive to retrofit.
+ */
+export type StageOutcome = CascadeResolution | {
+	kind: "pass";
+	reason: string;
+};
+interface CascadeLogger {
+	emit?: (code: string, params: Record<string, unknown>) => void;
+	log?: (message: string, level?: string) => void;
+}
+export interface FontStageContext {
+	engine: CreativeEngine;
+	resolver: TypefaceResolver | null;
+	/**
+	 * Per-import-call cache. Same `family|style|weight` resolves once per
+	 * `PDFParser.fromFile` invocation; reopening the PDF produces a fresh
+	 * cache. Created in the parser entry, discarded on completion.
+	 */
+	resolverCache: Map<string, FontResolverResult | null>;
+	logger: CascadeLogger | null;
+}
+export interface FontStage {
+	/** Stable identifier for logs and tests. */
+	readonly name: string;
+	resolve(req: FontRequest, ctx: FontStageContext): Promise<StageOutcome>;
+}
+export interface FontCascade {
+	readonly stages: readonly FontStage[];
+	resolve(req: FontRequest, ctx: FontStageContext): Promise<CascadeResolution | null>;
+}
+/**
+ * Result of a single emission call. The emission layer may produce zero,
+ * one, or more blocks; the `blocks` array is in z-order (back to front).
+ * `substituted` is true when the cascade's answer triggered a
+ * substitution that the dispatcher should account against the
+ * per-import substitution-count log.
+ */
+export interface EmissionResult {
+	/** CE.SDK block ids created. Empty array means the run was skipped. */
+	blocks: number[];
+	/** True when the resolution involved a font substitution. */
+	substituted: boolean;
+	/** Display name of the typeface the run resolved to, if any. */
+	resolvedFamily?: string;
+}
+/**
+ * Block-creation primitives that emission delegates to. The dispatcher
+ * fills these in so emission stays decoupled from `engine.block.*` and
+ * from the geometry helpers that already live in `emit/cesdk.ts`. Keeps
+ * the emission policy testable in isolation: each callback can be
+ * stubbed.
+ */
+export interface EmissionHelpers {
+	/**
+	 * Create an editable text block with the request's geometry and the
+	 * caller-supplied `applyFont` callback (called between layout and
+	 * properties — order matters for CE.SDK's `replaceText` wrap-marker).
+	 * `layoutIr` may be the original block or a typeface-aware substitute
+	 * (see `resolveLayoutForSubstitution` below).
+	 */
+	createEditableText(req: FontRequest, layoutIr: TextOutline | TextRun, applyFont: (engine: CreativeEngine, block: number) => void): number;
+	/**
+	 * Emit the request's `glyphPaths` as a `vector_path` graphic block at
+	 * the source bbox. Returns null when the request carries no
+	 * `glyphPaths` (TextRun source).
+	 */
+	emitGlyphsAsVectorPath(req: FontRequest): number | null;
+	/**
+	 * Compute the layout-aware IR for a substituted typeface. For TextRun
+	 * sources this is a no-op (returns `req.source`); for TextOutline
+	 * sources it derives the unrotated bbox CE.SDK needs using the
+	 * substitute's font metrics.
+	 */
+	resolveLayoutForSubstitution(req: FontRequest, resolution: CascadeResolution): Promise<TextOutline | TextRun>;
+}
+export interface EmissionContext {
+	engine: CreativeEngine;
+	logger: CascadeLogger | null;
+	/** Page index (1-based) for diagnostic context. */
+	pageIndex?: number;
+	helpers: EmissionHelpers;
+}
+export interface FontEmission {
+	readonly name: string;
+	emit(req: FontRequest, resolution: CascadeResolution | null, ctx: EmissionContext): Promise<EmissionResult>;
+}
+export interface FontStrategy {
+	readonly cascade: FontCascade;
+	readonly emission: FontEmission;
+}
+export declare const perfectMatchResolverStage: FontStage;
+export declare const embeddedSubsetStage: FontStage;
+export declare const anyMatchResolverStage: FontStage;
+export declare const defaultEmission: FontEmission;
+/**
+ * Build a cascade from an ordered list of stages. The cascade walks the
+ * list and returns the first non-pass outcome. When every stage passes,
+ * the cascade returns `null` (emission decides what to do).
+ */
+export declare function createFontCascade(stages: FontStage[]): FontCascade;
+interface FontStrategyDef {
+	cascade: FontCascade;
+	emission: FontEmission;
+}
+export declare function createFontStrategy(def: FontStrategyDef): FontStrategy;
+/**
+ * Default for `PDFParser.fromFile({ fontStrategy })`. Embedded subset
+ * bytes are used as an intermediate fallback to preserve the source's
+ * exact rendering when the family isn't in the asset library — vector
+ * outline extraction can produce incorrect bboxes or partial glyph
+ * coverage for some fonts, while the engine renders subset bytes
+ * faithfully.
+ *
+ *  - Run's family resolves perfectly in the asset library →
+ *    perfect-match typeface (HTTPS URI).
+ *  - Embedded subset present (TextRun source) → register the bytes and
+ *    emit as editable text with `setFont`. The resulting scene depends
+ *    on the bytes living in a `buffer://` URI; this is the offline-safe
+ *    path.
+ *  - Otherwise → any-match resolver (possibly substituted via the
+ *    fallbacks source; a per-import warning summarizes substitutions).
+ *  - Neither hits → cascade returns null → emission falls through to a
+ *    vector outline (TextOutline-source runs always have glyph paths;
+ *    TextRun-source runs use the Phase-2 lazy closure built by the
+ *    walker).
+ *
+ * For tools that explicitly want vectorization over subset bytes
+ * (e.g. brand-locked editors), use `assetLibraryStrategy`.
+ */
+export declare const editableFirstStrategy: FontStrategy;
+/**
+ * For print finalization, PDF-viewer-style integrations, and anywhere a
+ * silent Helvetica → Roboto substitution is unacceptable. Skips
+ * `anyMatchResolverStage`; non-embeddable runs without a perfect match
+ * fall through to vector outline.
+ */
+export declare const exactFidelityStrategy: FontStrategy;
+/**
+ * For brand-locked tools: every editable text must come from the asset
+ * library (or the resolver's alias fallbacks). Drops the subset stage so
+ * PDF-embedded subset bytes never leak through; runs whose family isn't
+ * in the library go straight to the any-match resolver.
+ */
+export declare const assetLibraryStrategy: FontStrategy;
+export declare const defaultStrategy: FontStrategy;
+type PageBounds = "trim" | "media";
+type PdfLogger = Logger<typeof WARNING_CODES>;
 export declare class PDFParser {
 	private engine;
 	private pdfBytes;
 	private fontResolver;
+	private fontStrategy;
 	private pageBounds;
 	private logger;
+	private ir?;
 	private constructor();
 	/**
 	 * Create a PDFParser instance from a PDF file.
@@ -252,17 +761,24 @@ export declare class PDFParser {
 	 * @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.
+	 * @param options.fontResolver - Custom font resolver. Invoked by the
+	 *   cascade's resolver-using stages (`perfectMatchResolverStage`,
+	 *   `anyMatchResolverStage`). Requires `addGfontsAssetLibrary` to be
+	 *   called on the engine before parse.
+	 * @param options.fontStrategy - Strategy controlling how text runs
+	 *   become blocks. Default: `editableFirstStrategy` — prefers a perfect
+	 *   asset-library match, falls back to the PDF-embedded subset, then to
+	 *   resolver substitution (any-match), and finally to vector outline
+	 *   when nothing else hits. Other shipped presets:
+	 *   `exactFidelityStrategy` (never substitute), `assetLibraryStrategy`
+	 *   (drop subset). Build custom strategies with `createFontStrategy({
+	 *   cascade, emission })`. See `packages/pdf-importer/CLAUDE.md` →
+	 *   "Font resolution" for the mental model and offline-safe recipe.
 	 * @returns A new PDFParser instance
 	 */
 	static fromFile(engine: CreativeEngine, file: Blob | File | ArrayBuffer, options?: {
 		fontResolver?: TypefaceResolver;
+		fontStrategy?: FontStrategy;
 		/**
 		 * Which PDF page box the emitted CE.SDK pages are sized to. Defaults
 		 * to `"trim"` (designed page + bleed margin, the end-user view).
@@ -285,16 +801,54 @@ export declare class PDFParser {
 	 * lines that share font/size and horizontal overlap merged into a single
 	 * multi-line block.
 	 *
+	 * Mirrors `engine.scene.loadFromString`: replaces the engine's current
+	 * scene with the imported PDF.
+	 *
 	 * @returns Parse result containing the scene ID and logger
 	 */
 	parse(): Promise<{
 		scene: number;
 		logger: PdfLogger;
 	}>;
+	/**
+	 * Parse the PDF and return the imported pages as detached CE.SDK blocks.
+	 *
+	 * Mirrors `engine.block.loadFromString`: returned blocks are NOT attached
+	 * to a scene. Caller appends and positions them however they want.
+	 *
+	 * Each PDF page yields one returned `page` block, sized to the PDF's
+	 * MediaBox in inches with the page's content as children. CE.SDK pages
+	 * are the right wrapper here — `setWidth`/`setHeight` scales children
+	 * proportionally (so callers can fit a PDF page into an arbitrary host
+	 * frame), and pages clip to their bounds (matching IDML's frame
+	 * semantics when content overflows).
+	 *
+	 * @param options
+	 * @param options.pageIndex 0-based page to load. Omit to load all pages
+	 *   (returns one block per page, in document order).
+	 * @returns Detached page block IDs (length 1 for single-page mode,
+	 *   `pdf.numPages` for all-pages mode), plus the logger so callers can
+	 *   forward parser warnings into their own diagnostic stream.
+	 */
+	loadAsBlocks(options?: {
+		pageIndex?: number;
+	}): Promise<{
+		blocks: number[];
+		logger: PdfLogger;
+	}>;
+	/**
+	 * Number of pages in the PDF document.
+	 *
+	 * Triggers a full IR extraction on first call (the same work `parse` /
+	 * `loadAsBlocks` does), then caches it. Subsequent calls — including
+	 * `parse` and `loadAsBlocks` themselves — reuse the cached IR.
+	 */
+	getPageCount(): Promise<number>;
 	/**
 	 * Get the logger for this parser instance.
 	 */
 	getLogger(): PdfLogger;
+	private ensureIR;
 }
 
 export {};