@namahapdf/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1360 @@
+/**
+ * Avni Engine Core Types
+ * Defines the standard interfaces for document processing
+ */
+type DocumentType = 'pdf' | 'docx' | 'image' | 'text' | 'csv';
+interface AvniDocument {
+    id: string;
+    name: string;
+    blob: Blob;
+    type: DocumentType;
+    size: number;
+    metadata: Record<string, unknown>;
+    history: ProcessingStep[];
+}
+interface ProcessingStep {
+    taskId: string;
+    processorName: string;
+    timestamp: number;
+    params: Record<string, unknown>;
+}
+interface ProcessorResult {
+    success: boolean;
+    document: AvniDocument;
+    error?: string;
+    metrics?: {
+        duration: number;
+        originalSize: number;
+        newSize: number;
+    };
+}
+interface IAvniProcessor {
+    name: string;
+    supportedTypes: DocumentType[];
+    process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
+}
+interface PipelineConfig {
+    tasks: {
+        processorName: string;
+        params: Record<string, unknown>;
+    }[];
+}
+
+declare class AvniOrchestrator {
+    private processors;
+    /**
+     * Register a new tool (processor) to the engine
+     */
+    registerProcessor(processor: IAvniProcessor): void;
+    /**
+     * Run a sequence of tasks on a document
+     */
+    runPipeline(initialDoc: AvniDocument, config: PipelineConfig): Promise<ProcessorResult[]>;
+    getAvailableProcessors(): string[];
+}
+declare const avniEngine: AvniOrchestrator;
+
+type PDFNull = {
+    type: 'null';
+};
+type PDFBoolean = {
+    type: 'boolean';
+    value: boolean;
+};
+type PDFInteger = {
+    type: 'integer';
+    value: number;
+};
+type PDFReal = {
+    type: 'real';
+    value: number;
+};
+type PDFString = {
+    type: 'string';
+    value: Uint8Array;
+    encoding: 'literal' | 'hex';
+};
+/**
+ * All possible PDF object types
+ */
+type PDFObject = PDFNull | PDFBoolean | PDFInteger | PDFReal | PDFString | PDFName | PDFArray | PDFDict | PDFStream | PDFRef;
+/**
+ * PDF Name object - always starts with /
+ * Examples: /Type, /Font, /Contents
+ */
+type PDFName = {
+    type: 'name';
+    value: string;
+};
+/**
+ * PDF Array - [ item1 item2 ... ]
+ */
+type PDFArray = {
+    type: 'array';
+    items: PDFObject[];
+};
+/**
+ * PDF Dictionary - << key1 value1 key2 value2 ... >>
+ */
+type PDFDict = {
+    type: 'dict';
+    entries: Map<string, PDFObject>;
+};
+/**
+ * PDF Stream - binary data with associated dictionary
+ * << dict >>
+ * stream
+ * ... binary data ...
+ * endstream
+ */
+type PDFStream = {
+    type: 'stream';
+    dict: PDFDict;
+    rawBytes: Uint8Array;
+    decode: () => Promise<Uint8Array>;
+    data?: Uint8Array;
+} | {
+    type: 'stream';
+    dict: PDFDict;
+    data: Uint8Array;
+    rawBytes?: Uint8Array;
+    decode?: () => Promise<Uint8Array>;
+};
+/**
+ * PDF Indirect Reference - R indirect object reference
+ * Example: 5 0 R refers to object 5, generation 0
+ */
+type PDFRef = {
+    type: 'ref';
+    objNum: number;
+    genNum: number;
+};
+/**
+ * Cross-reference table entry
+ * Points to where an object starts in the file
+ */
+type XRefEntry = {
+    type: 'uncompressed';
+    offset: number;
+    genNum: number;
+    inUse: boolean;
+} | {
+    type: 'compressed';
+    streamNum: number;
+    indexNum: number;
+    genNum: number;
+    inUse: boolean;
+};
+/**
+ * Parsed PDF document - the object tree
+ */
+type PDFDocument = {
+    rawBytes: Uint8Array;
+    xrefTables: Map<number, Map<number, XRefEntry>>;
+    objectCache: Map<string, PDFObject>;
+    rootRef: PDFRef;
+    trailer: PDFDict;
+    version: string;
+};
+
+/**
+ * PDF Parser - Main Entry Point
+ *
+ * Orchestrates the parsing pipeline:
+ * 1. Find xref offset
+ * 2. Parse cross-reference table(s)
+ * 3. Create lazy-loaded object tree
+ * 4. Return PDFDocument
+ *
+ * Supports both compressed (xref stream) and uncompressed (traditional xref) formats.
+ */
+
+/**
+ * Main PDF Parser
+ */
+declare class PDFParser {
+    private bytes;
+    private document;
+    private objectStreamCache;
+    private encryptRef;
+    private decryptionHandler;
+    constructor(pdfBytes: Uint8Array);
+    /**
+     * Main parse entry point
+     */
+    parse(): PDFDocument;
+    /**
+     * Extract PDF version from header
+     * Format: %PDF-X.Y
+     */
+    private extractVersion;
+    /**
+     * Parse all xref tables (including previous versions for incremental updates)
+     */
+    private parseXRefTables;
+    /**
+     * Extract root reference from trailer
+     */
+    private extractRootRef;
+    /**
+     * Load an object by reference (lazy loading)
+     * This is called by users of the parser to load specific objects
+     */
+    loadObject(ref: PDFRef): PDFObject;
+    private loadObjectStream;
+    private repairStreamBytesFromLengthRef;
+    private findStreamDataStart;
+    private decryptObject;
+    private decryptObjectRecursive;
+}
+
+declare function loadPageContentStream(contentsEntry: PDFObject | undefined, loadObject: (ref: PDFRef) => PDFObject | Promise<PDFObject>): Promise<{
+    combinedBytes: Uint8Array;
+    streamCount: number;
+    streamByteLengths: number[];
+}>;
+
+type Matrix = [number, number, number, number, number, number];
+type DrawCommand = {
+    op: 'save_state';
+} | {
+    op: 'restore_state';
+} | {
+    op: 'set_ctm';
+    matrix: Matrix;
+} | {
+    op: 'begin_text';
+} | {
+    op: 'end_text';
+} | {
+    op: 'set_font';
+    name: string;
+    size: number;
+} | {
+    op: 'move_text';
+    tx: number;
+    ty: number;
+} | {
+    op: 'move_text_set_leading';
+    tx: number;
+    ty: number;
+} | {
+    op: 'set_text_matrix';
+    matrix: Matrix;
+} | {
+    op: 'next_line';
+} | {
+    op: 'show_string';
+    data: Uint8Array;
+} | {
+    op: 'show_strings';
+    items: Array<Uint8Array | number>;
+} | {
+    op: 'next_line_show_string';
+    data: Uint8Array;
+} | {
+    op: 'set_spacing_next_line_show_string';
+    wordSpacing: number;
+    charSpacing: number;
+    data: Uint8Array;
+} | {
+    op: 'set_char_spacing';
+    spacing: number;
+} | {
+    op: 'set_word_spacing';
+    spacing: number;
+} | {
+    op: 'set_horiz_scale';
+    scale: number;
+} | {
+    op: 'set_leading';
+    leading: number;
+} | {
+    op: 'set_text_render';
+    mode: number;
+} | {
+    op: 'set_text_rise';
+    rise: number;
+} | {
+    op: 'move_to';
+    x: number;
+    y: number;
+} | {
+    op: 'line_to';
+    x: number;
+    y: number;
+} | {
+    op: 'curve_to';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x3: number;
+    y3: number;
+} | {
+    op: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | {
+    op: 'close_path';
+} | {
+    op: 'stroke';
+} | {
+    op: 'fill';
+} | {
+    op: 'fill_even_odd';
+} | {
+    op: 'fill_stroke';
+} | {
+    op: 'clip';
+} | {
+    op: 'clip_even_odd';
+} | {
+    op: 'end_path';
+} | {
+    op: 'set_line_width';
+    width: number;
+} | {
+    op: 'set_line_cap';
+    cap: number;
+} | {
+    op: 'set_line_join';
+    join: number;
+} | {
+    op: 'set_miter_limit';
+    limit: number;
+} | {
+    op: 'set_dash';
+    array: number[];
+    phase: number;
+} | {
+    op: 'set_rendering_intent';
+    intent: string;
+} | {
+    op: 'fill_stroke_even_odd';
+} | {
+    op: 'close_stroke';
+} | {
+    op: 'curve_to_v';
+    x2: number;
+    y2: number;
+    x3: number;
+    y3: number;
+} | {
+    op: 'set_fill_color_rgb';
+    r: number;
+    g: number;
+    b: number;
+} | {
+    op: 'set_stroke_color_rgb';
+    r: number;
+    g: number;
+    b: number;
+} | {
+    op: 'set_fill_gray';
+    gray: number;
+} | {
+    op: 'set_stroke_gray';
+    gray: number;
+} | {
+    op: 'set_fill_cmyk';
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+} | {
+    op: 'set_stroke_cmyk';
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+} | {
+    op: 'set_fill_color_space';
+    name: string;
+} | {
+    op: 'set_stroke_color_space';
+    name: string;
+} | {
+    op: 'set_fill_color';
+    values: number[];
+    patternName?: string;
+} | {
+    op: 'set_stroke_color';
+    values: number[];
+    patternName?: string;
+} | {
+    op: 'set_graphics_state';
+    name: string;
+} | {
+    op: 'xobject';
+    name: string;
+} | {
+    op: 'begin_marked_content';
+    tag: string;
+    properties?: PDFDict;
+} | {
+    op: 'end_marked_content';
+} | {
+    op: 'type3_glyph_width';
+    wx: number;
+    wy: number;
+} | {
+    op: 'shade';
+    name: string;
+} | {
+    op: 'close_fill_stroke';
+} | {
+    op: 'close_fill_stroke_even_odd';
+} | {
+    op: 'inline_image';
+    params: PDFDict;
+    data: Uint8Array;
+} | {
+    op: 'unknown';
+    keyword: string;
+    operands: PDFObject[];
+};
+
+declare function parseContentStream(bytes: Uint8Array): DrawCommand[];
+
+type Color = {
+    space: 'rgb';
+    r: number;
+    g: number;
+    b: number;
+} | {
+    space: 'gray';
+    gray: number;
+} | {
+    space: 'cmyk';
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+};
+
+type RenderGlyphBox = {
+    canvasX: number;
+    canvasY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    canvasBaselineY: number;
+    char: string;
+    charCode: number;
+    runIndex: number;
+};
+type RenderTextRun = {
+    index: number;
+    text: string;
+    fontName: string;
+    fontSize: number;
+    canvasX: number;
+    canvasY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    canvasBaselineX: number;
+    canvasBaselineY: number;
+    fillColor: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    streamOperatorIndex: number;
+    /** True when captured inside a Form XObject — streamOperatorIndex is then
+     * relative to the form's command list, not the page content stream. */
+    fromXObject: boolean;
+    glyphs: RenderGlyphBox[];
+    /** The exact CSS font-family the canvas drew this run with (registered
+     * embedded family + substitute fallback, or just the substitute family).
+     * Lets the inline editor render identical text — no size/width jump. */
+    fontFamily?: string;
+};
+/** A drawn image (XObject or inline), captured for editor selection. */
+type RenderImageBox = {
+    canvasX: number;
+    canvasY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    /** PDF user-space CTM at draw time (image occupies the unit square). */
+    ctm: Matrix;
+    kind: 'xobject' | 'inline';
+    xobjectName: string | null;
+    streamOperatorIndex: number;
+    fromXObject: boolean;
+};
+/** A clustered vector-graphics object, captured for editor selection. */
+type RenderGraphicBox = {
+    canvasX: number;
+    canvasY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    operatorStart: number;
+    operatorEnd: number;
+    paintOperatorIndices: number[];
+    /** PDF user-space CTM when the cluster's first path began. */
+    ctmAtStart: Matrix;
+    fromXObject: boolean;
+};
+declare class PageRenderer {
+    private readonly canvas;
+    private readonly pageWidth;
+    private readonly pageHeight;
+    private readonly scale;
+    private stateStack;
+    private state;
+    private ctx;
+    private readonly disableClip;
+    private readonly debug;
+    private readonly debugAtomic;
+    private readonly maxAtomicLogs;
+    private atomicLogCount;
+    private commandIndex;
+    private xobjectDepth;
+    private pageResources;
+    private objectLoader;
+    private fontCache;
+    /** fontName -> registered FontFace family, populated by preloadEmbeddedFonts
+     * before each async render pass. Read by loadFontInfo. */
+    private embeddedFamilies;
+    /** Memoized canvas glyph widths keyed by `${ctx.font}|${char}`, cleared per
+     * render pass. Avoids a measureText (GPU readback) per glyph for fonts that
+     * lack PDF width metrics. */
+    private glyphWidthCache;
+    /** Cached resolvers for Separation/DeviceN color spaces (keyed by resource name). */
+    private separationColorCache;
+    /** Currently-active Separation/DeviceN resolver for fill/stroke, mirrored with stateStack. */
+    private fillColorResolver;
+    private strokeColorResolver;
+    private resolverStack;
+    private capturedTextRuns;
+    private fontDiagnosticsLogged;
+    private rawByteDiagnosticsLogged;
+    private currentPathX;
+    private currentPathY;
+    private pathStartX;
+    private pathStartY;
+    private readonly initialTransform;
+    private readonly forcedColor;
+    private readonly patternDepth;
+    /** Resolved patterns per (name, paint color); scoped to the active
+     * resource dict — swapped around Form XObjects, cleared per render pass. */
+    private patternCache;
+    /** Decoded mesh-shading triangles per shading dict, one render pass. */
+    private meshCache;
+    /** The real page canvas context; this.ctx may point at a layer. */
+    private baseCtx;
+    /** Offscreen compositing layers: transparency groups + ExtGState SMasks. */
+    private layerStack;
+    private layerPool;
+    private static readonly MAX_LAYER_DEPTH;
+    /** Object-capture state for the editor (images + vector clusters). */
+    private capturedImages;
+    private paintRecords;
+    private breakerIndices;
+    private pendingPath;
+    /** >0 while rendering content that is not page content (Type3 glyph
+     * charprocs, soft-mask forms) — capture hooks become no-ops. */
+    private captureSuppressed;
+    constructor(canvas: HTMLCanvasElement, pageWidth: number, pageHeight: number, scale: number, options?: {
+        disableClip?: boolean;
+        debug?: boolean;
+        debugAtomic?: boolean;
+        maxAtomicLogs?: number;
+        /** Skip the opaque white page fill (pattern cells, mask layers). */
+        transparentBackground?: boolean;
+        /** Replace the standard viewport transform (content space → device
+         * pixels); used to render pattern cells in pattern space. */
+        initialTransform?: Matrix;
+        /** PaintType 2 (uncolored) tiling patterns: ignore all color
+         * operators and paint everything with this color. */
+        forcedColor?: Color;
+        /** Nested pattern-cell recursion depth (cap guards cycles). */
+        patternDepth?: number;
+    });
+    render(commands: DrawCommand[]): void;
+    renderAsync(commands: DrawCommand[]): Promise<void>;
+    /**
+     * Paint a page's pre-existing annotations (highlights, strikethrough, ink,
+     * shapes, stamps, FreeText, …) by rendering each annotation's normal
+     * appearance stream (/AP /N) as a Form XObject, mapping the appearance BBox
+     * onto the annotation /Rect per PDF 32000-1 §12.5.5. Call after renderAsync().
+     *
+     * Widget (form-field) annotations are skipped — those are handled by the
+     * AcroForm path; Popup/Link and Hidden/NoView annotations are skipped too.
+     */
+    renderAnnotations(pageDict: PDFDict | undefined): Promise<void>;
+    private renderOneAnnotation;
+    /** Resolve an annotation's normal appearance (/AP /N), following the /AS
+     *  appearance-state sub-dictionary when present (e.g. checkbox On/Off). */
+    private resolveAppearanceStream;
+    private runCommandsAsync;
+    getCapturedTextRuns(): RenderTextRun[];
+    getCapturedImages(): RenderImageBox[];
+    getCapturedGraphics(): RenderGraphicBox[];
+    /** Track path geometry in device pixels for graphics capture. */
+    private extendPendingPath;
+    private recordPaintForCapture;
+    /** Text and images split vector clusters in the paint stream. */
+    private recordBreaker;
+    private captureImageBox;
+    setFontContext(pageResources: PDFDict | undefined, objectLoader?: (ref: PDFRef) => PDFObject): void;
+    private execute;
+    private moveToNextTextLine;
+    private renderText;
+    private renderType3Text;
+    private commandPayload;
+    private decodeText;
+    /** Canvas glyph width, memoized per (current font, text) for the render pass. */
+    private measureGlyphWidthCached;
+    /**
+     * Resolve the page's Font dictionary and register each embedded font program
+     * (TrueType/OpenType with a Unicode cmap) as a browser FontFace, recording
+     * fontName -> family in embeddedFamilies. Best-effort: any failure leaves the
+     * font absent from the map, so loadFontInfo simply falls back to substitution.
+     */
+    private preloadEmbeddedFonts;
+    private getCurrentFontInfo;
+    private loadFontInfo;
+    private logFontDiagnostic;
+    private resolveObject;
+    private resolveColorSpaceName;
+    /**
+     * Build and cache a color resolver for Separation / DeviceN color spaces.
+     * Returns null for device color spaces (handled by colorFromComponents).
+     */
+    private buildComplexColorResolver;
+    private renderXObject;
+    private resolveImageColorSpace;
+    /** Resolve the parameter dict for a filter, handling the array form of
+     *  /DecodeParms (pick the entry that is actually a dict). */
+    private resolveDecodeParms;
+    /**
+     * Decode a JBIG2-filtered image stream to packed 1-bpp filter bytes using
+     * pdf.js's `Jbig2Image`. Mirrors pdf.js's Jbig2Stream: optional
+     * /JBIG2Globals shared segments are prepended, and the result is bit-inverted
+     * (JBIG2 uses 1=black, but PDF's DeviceGray 1-bpc / ImageMask sample
+     * convention is 0=black). Returns null on failure so the caller can skip
+     * drawing rather than paint garbage.
+     */
+    private decodeJbig2;
+    /**
+     * Decode a CCITTFax (Group 3/4 fax) image stream to packed 1-bpp filter bytes
+     * via pdf.js's `CCITTFaxDecoder`. Polarity (BlackIs1) and the other
+     * parameters come from /DecodeParms; the decoder yields one packed byte per
+     * `readNextChar()`. Returns null on failure.
+     */
+    private decodeCcitt;
+    /** Composite an RGBA ImageData through a scratch canvas onto the page (the
+     *  shared tail of every sampled-image path). */
+    private drawRgbaImageData;
+    private renderImageXObject;
+    /**
+     * Decode a CMYK/YCCK JPEG with pdf.js's JpegImage (the browser's
+     * createImageBitmap mis-handles Adobe CMYK markers) and composite it,
+     * applying any /SMask. forceRGBA gives a ready-to-paint RGBA buffer.
+     */
+    private renderJpegViaPdfjs;
+    /**
+     * Decode a JPEG 2000 image with pdf.js's JpxImage and composite it. The
+     * decoded tile holds interleaved component samples; assemble RGBA (CMYK→RGB
+     * for 4-component data). Used because createImageBitmap('image/jp2') only
+     * works on Safari.
+     */
+    private renderJpxViaPdfjs;
+    /**
+     * Inline images (BI…ID…EI) reuse the XObject image pipeline: the
+     * abbreviated keys/values are expanded to their full equivalents and the
+     * payload is wrapped in a synthetic stream object.
+     */
+    private renderInlineImage;
+    /** Resolve a named entry from a page Resources sub-dictionary. */
+    private lookupResource;
+    /**
+     * Extract a soft mask's grayscale alpha at the base image's resolution. The
+     * mask's own /Filter must be honoured: a DCT/JPX-compressed SMask has to be
+     * image-decoded — `decodeStreamSync` returns the raw JPEG bytes for those
+     * filters, and dumping those into the alpha channel blacks the image out.
+     * Flate/raw masks keep the sync path.
+     */
+    private decodeSMaskAlpha;
+    private renderImageWithSMask;
+    private renderStencilMask;
+    private drawImageBitmapLike;
+    private decodeTextWithFont;
+    private logDebug;
+    private captureAtomicState;
+    private samplePixels;
+    private logAtomic;
+    private applyExtGState;
+    /** Content space → device pixels, before the CTM: the y-flipped, scaled
+     * page viewport — or the caller-supplied transform for pattern cells. */
+    private deviceBase;
+    private applyCurrentTransform;
+    /**
+     * Sync-render fallback (legacy): shading patterns approximate to a
+     * gradient with the pattern matrix baked into the coordinates. The async
+     * path resolves patterns properly via resolvePattern/paintFill instead.
+     */
+    private resolvePatternFillStyle;
+    /** Resolve a pattern resource (async path: tiling cells fully rendered). */
+    private resolvePattern;
+    /** scn/SCN with a pattern name on the async path. */
+    private applyPatternColor;
+    /** Render one tiling-pattern cell with a child renderer in pattern space. */
+    private renderTilingCell;
+    /** Fill the current path: plain color, or pattern painted in pattern space. */
+    private paintFill;
+    /**
+     * Stroke the current path. Pattern strokes approximate by tiling in the
+     * current user space (canvas cannot clip to a stroke region).
+     */
+    private paintStroke;
+    /**
+     * Clip to the current path, switch the context into pattern space
+     * (deviceBase · patternMatrix), and flood the visible region. Canvas path
+     * coordinates were captured at construction time, so re-transforming here
+     * only affects the paint — the standard pattern-space painting technique.
+     */
+    private paintPatternThroughPath;
+    /** Fill the active clip with the shading's /Background color, if any. */
+    private paintShadingBackground;
+    /**
+     * Paint a shading of any supported type, mapping shading space → device
+     * via `userToDevice`. Assumes the caller has set clip + alpha; manages its
+     * own transform. Types 2/3 → canvas gradient; 1 → sampled f(x,y) tile;
+     * 4–7 → Gouraud-rasterized triangle mesh.
+     */
+    private paintShadingWithBase;
+    /** ShadingType 1: sample f(x, y) over Domain into a tile, draw under the matrix. */
+    private paintFunctionShading;
+    /** ShadingTypes 4–7: decode the vertex stream and blit a Gouraud raster. */
+    private paintMeshShading;
+    /** fillRect covering the whole canvas, expressed in the current user space. */
+    private floodCanvasExtent;
+    /**
+     * Gradient for axial/radial shadings, honoring Domain and Extend, sampled
+     * at 64 stops. Coordinates are in shading space unless `coordMatrix` bakes
+     * a transform in (sync legacy path).
+     */
+    private createCanvasGradient;
+    private acquireLayerCanvas;
+    private releaseLayerCanvas;
+    /**
+     * Redirect drawing into a fresh full-size offscreen layer. The current
+     * transform and line/paint styles carry over; clip does NOT (it applies
+     * when the layer composites back onto the saved context). Returns false
+     * (and draws inline as before) past the depth cap.
+     */
+    private pushLayer;
+    /** Apply the layer's mask (if any) and composite it onto the saved context. */
+    private popLayer;
+    /**
+     * ExtGState /SMask handling (async path). A dict pushes a masked layer
+     * scoped to the enclosing q/Q; /None pops mask layers opened at this
+     * state depth.
+     */
+    private applySoftMaskFromExtGState;
+    /** Render an SMask's /G form into an alpha-mask canvas at the current CTM. */
+    private renderSMaskCanvas;
+    /**
+     * Render a Form XObject stream inline against the current context — the
+     * shared body used by soft-mask generation. Resource/state handling
+     * mirrors the renderXObject form branch.
+     */
+    private renderFormStreamInline;
+    private renderShadeOperator;
+}
+
+/**
+ * Styled-text model shared by the rich inline editor (UI) and the PDF writer
+ * (`PDFEditSession`). A styled run is an ordered list of {@link StyledSpan}s;
+ * each span carries its own weight/style/decoration/size/color so a single line
+ * can mix, e.g., a bold word inside plain text.
+ *
+ * This module is pure and dependency-free (only the `PDFColor` type) so it can be
+ * unit-tested and imported from both the browser editor and the server edit
+ * pipeline. Font *family* resolution stays in `PDFEditSession.mapPdfFontName` —
+ * here we only canonicalize a name string that mapper already understands, so
+ * the two never drift.
+ */
+
+type TextStyle = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Font size in PDF points. Falls back to the run/op size when omitted. */
+    sizePt?: number;
+    color?: PDFColor;
+};
+/** A contiguous slice of text drawn in one uniform style. */
+type StyledSpan = {
+    text: string;
+    style: TextStyle;
+};
+
+/**
+ * Unified annotation model for the editor's annotation layer.
+ *
+ * Everything is stored in **PDF points, bottom-left origin** (not container
+ * pixels) so annotations survive zoom changes and map directly onto PDF
+ * `/Annot` rects on export. The UI renders them by projecting through
+ * `pdfToContainer`; the engine writes them as real annotation objects via
+ * `annotationWriter`.
+ */
+type PdfPoint = {
+    x: number;
+    y: number;
+};
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * One line's worth of selected text, PDF space. Kept axis-aligned (PDF
+ * `/QuadPoints` allow rotation, but the editor only produces upright text
+ * selections). `baselineY` lets underline/strikeout sit on the right line.
+ */
+type Quad = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    baselineY: number;
+};
+type AnnotStyle = {
+    /** Stroke / markup color. */
+    color: PDFColor;
+    /** Constant opacity 0..1 → PDF `/CA`. */
+    opacity: number;
+    /** Stroke width in points (shapes / ink). */
+    strokeWidth?: number;
+    /** Interior fill for closed shapes; `null`/absent = no fill. */
+    fill?: PDFColor | null;
+};
+type TextMarkupKind = 'highlight' | 'underline' | 'strikeout' | 'squiggly';
+type ShapeKind = 'rect' | 'ellipse' | 'line' | 'arrow' | 'polygon' | 'polyline';
+type AnnotBase = {
+    id: string;
+    pageIndex: number;
+    style: AnnotStyle;
+    author?: string;
+    /** ms epoch; surfaces as `/CreationDate` + `/M`. */
+    createdAt: number;
+};
+/** Highlight / underline / strikeout / squiggly over selected text. */
+type TextMarkupAnnotation = AnnotBase & {
+    kind: TextMarkupKind;
+    /** Per-line rects covering the selected glyphs. */
+    quads: Quad[];
+    /** The covered text (annotation `/Contents`). */
+    text: string;
+};
+/**
+ * Vector shape. `points` semantics by kind:
+ * - `rect` / `ellipse`: two opposite corners.
+ * - `line` / `arrow`: two endpoints.
+ * - `polygon` / `polyline`: ordered vertices (>= 2).
+ */
+type ShapeAnnotation = AnnotBase & {
+    kind: ShapeKind;
+    points: PdfPoint[];
+};
+/** Freehand brush / pencil: one or more captured strokes. */
+type InkAnnotation = AnnotBase & {
+    kind: 'ink';
+    strokes: PdfPoint[][];
+};
+/** Sticky note (`/Text`) or text box / callout (`/FreeText`). */
+type NoteAnnotation = AnnotBase & {
+    kind: 'note' | 'freetext';
+    rect: Rect;
+    text: string;
+};
+type Annotation = TextMarkupAnnotation | ShapeAnnotation | InkAnnotation | NoteAnnotation;
+
+type PDFColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+type PDFFontSpec = {
+    cssFamily?: string;
+    pdfName?: string;
+    sizePt: number;
+    weight?: string;
+    color?: PDFColor;
+    lineHeight?: number;
+    charSpacing?: number;
+};
+type PdfMatrix = [number, number, number, number, number, number];
+
+type InsertTextOperation = {
+    type: 'insert-text';
+    pageIndex: number;
+    text: string;
+    x: number;
+    y: number;
+    size?: number;
+    color?: PDFColor;
+    /** When present, the text is drawn as styled spans (bold/italic/underline/
+     * strikethrough/size/color per span) instead of the flat `text`+`size`+
+     * `color`. `text` should still hold the plain concatenation for logging. */
+    spans?: StyledSpan[];
+    /** Base font name whose family the spans inherit (e.g. the original run's
+     * font). Bold/italic come from each span's style. */
+    fontName?: string;
+};
+type RedactAreaOperation = {
+    type: 'redact-area';
+    pageIndex: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color?: PDFColor;
+    padding?: number;
+    /** When set, the show-text operators under the rect are removed from the
+     * content stream (true redaction) so the covered text can't be extracted. */
+    removeOperators?: {
+        streamOperatorIndices: number[];
+    };
+};
+/**
+ * Bounds (in PDF space) that the erase/whiteout rectangle of a replace-text
+ * operation must not cross, derived from neighboring text runs so the cover
+ * box never swallows adjacent lines or words.
+ */
+type EraseClamp = {
+    /** Erase rect bottom edge must stay >= this. */
+    minY?: number;
+    /** Erase rect top edge must stay <= this. */
+    maxY?: number;
+    /** Erase rect right edge must stay <= this. */
+    maxRight?: number;
+};
+type ReplaceTextOperation = {
+    type: 'replace-text';
+    pageIndex: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    baselineY?: number;
+    newText: string;
+    size?: number;
+    font?: PDFFontSpec;
+    color?: PDFColor;
+    backgroundColor?: PDFColor;
+    erasePadding?: number;
+    eraseClamp?: EraseClamp;
+    /** When set, the original show-text operators are removed from the content
+     * stream (Adobe-style) instead of being covered with a rectangle; the
+     * cover box remains the fallback if the rewrite fails. */
+    removeOperators?: {
+        streamOperatorIndices: number[];
+    };
+    /** When present, the replacement is drawn as styled spans (per-span bold/
+     * italic/underline/strikethrough/size/color) using `font.pdfName` as the
+     * base family. Supersedes `newText` for drawing; keep `newText` as the plain
+     * concatenation for width/erase sizing and history. */
+    spans?: StyledSpan[];
+};
+/**
+ * Remove visual objects (images / vector clusters) by blanking their operator
+ * spans in the content stream. Fails safe: when a span cannot be removed
+ * without side effects, the whole operation no-ops.
+ */
+type DeleteObjectOperation = {
+    type: 'delete-object';
+    pageIndex: number;
+    spans: Array<{
+        start: number;
+        end: number;
+    }>;
+};
+/**
+ * Move/resize a visual object by wrapping its operator span in `q T' cm … Q`,
+ * where T' = baseCtm⁻¹ · matrix · baseCtm maps the page-space transform into
+ * the span's local user space.
+ */
+type TransformObjectOperation = {
+    type: 'transform-object';
+    pageIndex: number;
+    span: {
+        start: number;
+        end: number;
+    };
+    /** Desired page-space transform T (PDF points, bottom-left origin). */
+    matrix: PdfMatrix;
+    /** PDF user-space CTM at the span start, captured at render time. */
+    baseCtm: PdfMatrix;
+};
+/** Place a new raster image (uploaded by the user) onto a page. */
+type InsertImageOperation = {
+    type: 'insert-image';
+    pageIndex: number;
+    /** PDF points, bottom-left corner of the placement. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    bytes: Uint8Array;
+    format: 'png' | 'jpeg';
+};
+type RotatePageOperation = {
+    type: 'rotate-page';
+    pageIndex: number;
+    degrees: 90 | 180 | 270;
+};
+type DeletePageOperation = {
+    type: 'delete-page';
+    pageIndex: number;
+};
+type FormFieldType$1 = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature';
+/**
+ * Field-authoring properties shared by create / update operations. Geometry,
+ * options and flags fully describe a field so an update can be expressed as a
+ * delete + recreate from the same spec.
+ */
+type FormFieldSpec = {
+    pageIndex: number;
+    fieldType: FormFieldType$1;
+    /** Fully-qualified AcroForm field name (/T). */
+    name: string;
+    /** PDF points, bottom-left origin. For radios, the bounding rect of option 0. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    value?: string;
+    /** Dropdown / radio option export values. Radios use one rect per option. */
+    options?: string[];
+    /** Per-option rects for radio groups (same length/order as `options`). */
+    optionRects?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    fontSize?: number;
+    required?: boolean;
+    readOnly?: boolean;
+    /** Text fields: allow multiple lines. */
+    multiline?: boolean;
+    /** Text-field text alignment (quadding). */
+    align?: 'left' | 'center' | 'right';
+    /** Text fields: maximum character count (0 / undefined = unlimited). */
+    maxLength?: number;
+    /** Dropdown: combo box that also accepts free-typed text. */
+    editable?: boolean;
+};
+/** Author a new interactive form field on a page. */
+type CreateFormFieldOperation = FormFieldSpec & {
+    type: 'create-form-field';
+};
+/**
+ * Replace an existing field (authored or parsed) with a new spec. Implemented as
+ * remove(oldName) + create(spec); covers geometry, options, name and flag edits.
+ */
+type UpdateFormFieldOperation = FormFieldSpec & {
+    type: 'update-form-field';
+    /** Name of the field to replace (may differ from the new `name`). */
+    oldName: string;
+};
+/** Set the value of one or more existing fields (fill). */
+type SetFormValuesOperation = {
+    type: 'set-form-values';
+    values: Array<{
+        name: string;
+        fieldType: FormFieldType$1;
+        value: string;
+    }>;
+    /** UI-only hint: page to re-render after committing (PDFEditSession ignores it). */
+    pageIndex?: number;
+};
+type DeleteFormFieldOperation = {
+    type: 'delete-form-field';
+    name: string;
+};
+/** Bake all field values into page content and remove the interactive form. */
+type FlattenFormOperation = {
+    type: 'flatten-form';
+};
+/**
+ * Write one annotation as a real PDF `/Annot` object (with an appearance
+ * stream + `/CA` opacity) onto its page. Non-destructive: the underlying page
+ * content and selectable text are untouched. See annotationWriter.ts.
+ */
+type AddAnnotationOperation = {
+    type: 'add-annotation';
+    annotation: Annotation;
+};
+type PDFEditOperation = InsertTextOperation | RedactAreaOperation | ReplaceTextOperation | DeleteObjectOperation | TransformObjectOperation | InsertImageOperation | RotatePageOperation | DeletePageOperation | CreateFormFieldOperation | UpdateFormFieldOperation | SetFormValuesOperation | DeleteFormFieldOperation | FlattenFormOperation | AddAnnotationOperation;
+
+declare class PDFEditSession {
+    private readonly pdfDoc;
+    private readonly pdfBytes;
+    private readonly standardFontCache;
+    private readonly embeddedFontCache;
+    private embeddedFonts;
+    private fontkitRegistered;
+    /** Bytes matching the document's last loaded/saved state — the same bytes
+     * the UI parsed when it captured stream operator indices. */
+    private currentBytes;
+    /** Per-page combined content bytes after rewrites within this save cycle,
+     * so consecutive rewrites on one page compose instead of resetting. */
+    private readonly rewrittenPages;
+    /** Pages whose command indices were invalidated by a length-changing
+     * rewrite (transform-object) this save cycle — further index-based
+     * rewrites on them must refuse rather than corrupt. */
+    private readonly indexInvalidPages;
+    private constructor();
+    static fromAvniDocument(doc: AvniDocument): Promise<PDFEditSession>;
+    /** Open a session straight from PDF bytes (server-side edit pipeline) —
+     * mirrors fromAvniDocument without needing an AvniDocument wrapper. */
+    static fromBytes(bytes: Uint8Array): Promise<PDFEditSession>;
+    getPageCount(): number;
+    applyOperations(operations: PDFEditOperation[]): Promise<void>;
+    /** Create / fill / delete / flatten interactive form fields via pdf-lib. */
+    private applyFormOperations;
+    private createFormField;
+    private setFieldValue;
+    toBlob(): Promise<Blob>;
+    /**
+     * Adobe-style text removal: blank the original show-text operators inside
+     * the page's content stream(s) so no cover rectangle is needed. Returns
+     * false when the rewrite cannot be applied safely (caller falls back to
+     * the cover-box erase).
+     */
+    private tryRemoveTextOperators;
+    /**
+     * Blank arbitrary operator spans (delete-object). Same stream-update
+     * mechanics as tryRemoveTextOperators; false on any anomaly.
+     */
+    private tryNeutralizeSpans;
+    /**
+     * Move/resize: wrap the object's span in `q M cm … Q` where
+     * M = C⁻¹·T·C maps the page-space transform into the span's local space.
+     * Length-changing — marks the page so later index-based rewrites refuse.
+     */
+    private tryWrapSpanWithTransform;
+    private deletePage;
+    /** Cache per image content so repeated placements reuse one XObject. */
+    private readonly embeddedImageCache;
+    private getEmbeddedImage;
+    private getStandardFont;
+    /**
+     * Draw a list of styled spans left-to-right starting at (`startX`,
+     * `baselineY`). Each span resolves its own standard font (family inherited
+     * from `baseFontName`, weight/style from the span) via the same
+     * fit/transliterate path as a flat edit, then advances x by the drawn width.
+     * Underline / strikethrough are thin rectangles spanning the drawn width.
+     */
+    private drawStyledSpans;
+    private getRenderableFont;
+    private supportedCodePoints;
+    private unsupportedCount;
+    /**
+     * Best-effort projection of text onto what `font` can encode: known
+     * lookalikes are transliterated, anything still unencodable is dropped
+     * with a warning — an edit must degrade, never fail the pipeline
+     * (e.g. WinAnsi cannot encode "⋄" from extracted symbol text).
+     */
+    private fitTextToFont;
+    private fontSupportsText;
+    private getEmbeddedFont;
+    private getEmbeddedFontPrograms;
+    private ensureFontkitRegistered;
+}
+
+/**
+ * Extract `/Link` annotations from a page so the View tool can overlay clickable
+ * regions. External links carry a `uri`; internal go-to links resolve to a
+ * `destPageIndex`. Geometry is PDF points, bottom-left origin (the same space the
+ * overlay positions with `pdfToContainer`).
+ */
+type LinkAnnotation = {
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** External link target (from /A /URI). */
+    uri?: string;
+    /** Resolved 0-based page index for internal go-to links (/Dest or /A /GoTo). */
+    destPageIndex?: number;
+};
+/**
+ * Read a page's `/Annots` for `/Subtype /Link` entries. `pageRefIndex` maps a
+ * page object ref key (`objNum:gen`) to its index so internal links resolve.
+ */
+declare function parseLinkAnnotations(pageDict: PDFDict | undefined, pageRefIndex: Map<string, number>, loadObject: (ref: PDFRef) => PDFObject | undefined): LinkAnnotation[];
+
+/**
+ * Unified, viewer-agnostic representation of an interactive form field. Both
+ * fields parsed from an existing AcroForm and fields authored in the editor are
+ * expressed with this model; the overlay UI renders it and pdf-lib persists it.
+ */
+type FormFieldType = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature';
+/** PDF-space rectangle (points, bottom-left origin). */
+type FormFieldRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type FormField = {
+    /** Stable key — existing fields use the fully-qualified name; new fields a generated id. */
+    id: string;
+    /** AcroForm field name (/T, qualified through the parent chain with '.'). */
+    name: string;
+    type: FormFieldType;
+    pageIndex: number;
+    rect: FormFieldRect;
+    /** Text value; 'On'/export value for check & radio; selected option for dropdown. */
+    value?: string;
+    /** Selectable export values for dropdown / radio. */
+    options?: string[];
+    /** The "on" export name for a checkbox/radio widget (from /AP /N, the non-Off key). */
+    onState?: string;
+    /** Font size from /DA; 0 (or undefined) means auto-size. */
+    fontSize?: number;
+    multiline?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    /** Text-field text alignment (quadding). */
+    align?: 'left' | 'center' | 'right';
+    /** Text fields: maximum character count (0 / undefined = unlimited). */
+    maxLength?: number;
+    /** Dropdown: combo box that also accepts free-typed text. */
+    editable?: boolean;
+    /** Per-option rects for radio groups (same order as `options`). */
+    optionRects?: FormFieldRect[];
+    /** True when authored in this editing session (not parsed from the source PDF). */
+    isNew?: boolean;
+};
+
+/**
+ * Walk the AcroForm field tree (resolving /Kids) and flatten terminal fields and
+ * their widgets into `FormField`s. Radio groups yield one entry per option widget
+ * (sharing `name`); other fields yield one entry per widget.
+ */
+declare function parseFormFields(catalog: PDFDict | undefined, pageDictsByIndex: Map<number, PDFDict>, loadObject: (ref: PDFRef) => PDFObject | undefined): FormField[];
+
+declare class PDFEditProcessor implements IAvniProcessor {
+    name: string;
+    supportedTypes: "pdf"[];
+    process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
+}
+
+declare class PDFCompressor implements IAvniProcessor {
+    name: string;
+    supportedTypes: "pdf"[];
+    process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
+    private compressImageInBrowser;
+}
+
+/** Shared license/activation contracts used by both the engine gate and the server. */
+/** Capabilities a license can unlock. `view`/`annotate` are the always-available base. */
+type LicenseFeature = 'view' | 'annotate' | 'edit-text' | 'sign' | 'redact' | 'forms' | 'export-clean';
+type LicenseEdition = 'trial' | 'pro' | 'enterprise';
+type LicenseStatus = 'UNLICENSED' | 'INVALID' | 'LICENSED' | 'GRACE' | 'DEGRADED';
+interface LicenseState {
+    status: LicenseStatus;
+    edition: LicenseEdition | null;
+    features: LicenseFeature[];
+    /** True when render/export should be watermarked. */
+    watermark: boolean;
+    /** Human-readable reason (for diagnostics; never user-facing copy). */
+    reason: string;
+}
+
+/**
+ * Soft-fail watermark used when the license gate is not satisfied (unlicensed,
+ * invalid, degraded, or trial). Two surfaces:
+ *   - `drawWatermarkOnCanvas` — diagonal repeated text over the on-screen preview.
+ *   - `stampWatermarkOnPdf`   — bakes the same notice onto every page of an export,
+ *     so a downloaded file is visibly unlicensed (the commercial deterrent).
+ *
+ * pdf-lib is already a project dependency; it's imported lazily so the watermark
+ * code only loads when actually needed.
+ */
+declare const WATERMARK_TEXT = "NamahaPDF \u00B7 Unlicensed SDK";
+/** Tile a faint diagonal watermark across a 2D canvas context. */
+declare function drawWatermarkOnCanvas(ctx: CanvasRenderingContext2D, width: number, height: number, text?: string): void;
+/**
+ * Stamp the watermark onto every page of a PDF and return the new bytes.
+ * Best-effort: if pdf-lib fails to load/parse, the original bytes are returned
+ * (we never want the watermark step to block a download outright).
+ */
+declare function stampWatermarkOnPdf(bytes: Uint8Array, text?: string): Promise<Uint8Array>;
+
+/**
+ * Client-side license gate for the NamahaPDF engine.
+ *
+ * Flow (see configureLicense):
+ *   1. Verify the license key OFFLINE (signature, expiry, domain) — instant, no network.
+ *   2. If a cached activation token is still valid → LICENSED immediately.
+ *   3. Kick a NON-BLOCKING background activation that exchanges the key for a fresh,
+ *      short-TTL activation token (which is also what the server can revoke).
+ *
+ * Offline grace is weighted heavily on purpose: transient network/server failures
+ * never punish a paying customer. We tolerate up to MAX_FAILURES (5) attempts AND a
+ * BOOTSTRAP_GRACE window before degrading — the SDK degrades immediately ONLY on an
+ * explicit signed `revoked`/`invalid` from the server.
+ *
+ * Everything is injectable (storage / fetch / clock / public key) so it is unit-testable
+ * without a browser or a server.
+ */
+
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+interface LicenseConfig {
+    /** The signed license key the developer received. */
+    licenseKey?: string;
+    /** Activation endpoint. Defaults to a same-origin `/api/license/activate`. */
+    activationUrl?: string;
+    /** Stable per-install id; auto-generated + persisted when omitted. */
+    deviceId?: string;
+    /** First-party bypass — our own app passes this so it never watermarks itself. */
+    owner?: boolean;
+    /** Override the embedded public key (tests only). */
+    publicKeyHex?: string;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Injected storage (tests / Node). */
+    storage?: StorageLike;
+    /** Injected fetch (tests / Node). */
+    fetchImpl?: typeof fetch;
+    /** Host to domain-check against; defaults to location.hostname in the browser. */
+    host?: string;
+    /** Background retry backoff in ms (tests can shorten). */
+    retryDelays?: number[];
+}
+type Listener = (s: LicenseState) => void;
+/**
+ * Configure (or reconfigure) the license gate. Verifies the key synchronously and
+ * starts a background activation. Returns the immediate state; subscribe with
+ * `onLicenseChange` for updates as activation completes.
+ */
+declare function configureLicense(config?: LicenseConfig): LicenseState;
+/** Current license state (synchronous, cheap). */
+declare function getLicenseState(): LicenseState;
+declare function isFeatureEnabled(feature: LicenseFeature): boolean;
+/** Throws if a feature is not licensed — use to guard gated engine operations. */
+declare function assertFeature(feature: LicenseFeature): void;
+declare function shouldWatermark(): boolean;
+/** Subscribe to state changes (activation success/failure). Returns an unsubscribe. */
+declare function onLicenseChange(cb: Listener): () => void;
+
+export { type AvniDocument, AvniOrchestrator, type DocumentType, type DrawCommand, type IAvniProcessor, type LicenseConfig, type LicenseEdition, type LicenseFeature, type LicenseState, type LicenseStatus, type LinkAnnotation, type Matrix, PDFCompressor, type PDFEditOperation, PDFEditProcessor, PDFEditSession, PDFParser, PageRenderer, type PipelineConfig, type ProcessingStep, type ProcessorResult, type RenderGlyphBox, type RenderGraphicBox, type RenderImageBox, type RenderTextRun, WATERMARK_TEXT, assertFeature, avniEngine, configureLicense, drawWatermarkOnCanvas, getLicenseState, isFeatureEnabled, loadPageContentStream, onLicenseChange, parseContentStream, parseFormFields, parseLinkAnnotations, shouldWatermark, stampWatermarkOnPdf };