@hufe921/jsofd 1.0.0

package/dist/pdf.d.ts

@@ -0,0 +1,1122 @@
+/**
+ * jsOFD public type definitions.
+ */
+/** RGB color (0-255) */
+type RGB = [number, number, number];
+/** Paper format: a name ('a4', 'letter', ...) or [width, height] in the active unit */
+type PageFormat = string | [number, number] | number[];
+/** Page orientation */
+type Orientation = 'p' | 'portrait' | 'l' | 'landscape';
+/** Measurement unit */
+type Unit = 'pt' | 'mm' | 'cm' | 'in' | 'inch' | 'px' | 'pc' | 'em' | 'ex';
+/** Constructor options */
+interface jsOFDOptions {
+    /** Page orientation, default 'p' (portrait) */
+    orientation?: Orientation;
+    /** Measurement unit, default 'mm' */
+    unit?: Unit;
+    /** Paper format, default 'a4'; may be a [width, height] array */
+    format?: PageFormat;
+    /** Number serialization precision (decimals), default 4 */
+    floatPrecision?: number;
+}
+interface EmbeddedFontFile {
+    /** Raw TTF/OTF bytes written into `Doc_0/Res/`. */
+    data: Uint8Array;
+    /** File extension: `ttf` or `otf`. */
+    ext: string;
+}
+/** Font style */
+type FontStyle = 'normal' | 'bold' | 'italic' | 'bolditalic';
+/** Text alignment */
+type TextAlign = 'left' | 'center' | 'right' | 'justify';
+/** Text baseline */
+type TextBaseline = 'alphabetic' | 'top' | 'middle' | 'bottom' | 'hanging';
+/** Text rendering mode */
+type TextRenderingMode = 'fill' | 'stroke' | 'fillThenStroke' | 'invisible';
+/** doc.text() options */
+interface TextOptions {
+    /** Horizontal alignment, default 'left'; 'justify' requires maxWidth */
+    align?: TextAlign;
+    /** Rotation in degrees, clockwise around the x,y anchor */
+    angle?: number;
+    /** Baseline position, default 'alphabetic' (x,y marks the baseline) */
+    baseline?: TextBaseline;
+    /** Extra spacing between glyphs (active unit) */
+    charSpace?: number;
+    /** Line height factor, default 1.15 */
+    lineHeightFactor?: number;
+    /** Maximum line width before wrapping (active unit) */
+    maxWidth?: number;
+    /** Rendering mode (string or PDF Tr number 0-7) */
+    renderingMode?: TextRenderingMode | number | boolean;
+    /** Opacity 0-1 */
+    opacity?: number;
+    /** Font size override in points (jsPDF semantics) */
+    fontSize?: number;
+    /** Horizontal scale; 1 is unscaled (jsPDF horizontalScale) */
+    horizontalScale?: number;
+    /** Render right-to-left (jsPDF R2L) */
+    R2L?: boolean;
+}
+/** Link options */
+interface LinkOptions {
+    /** External URL */
+    url?: string;
+    /** In-document target page number (1-based) */
+    pageNumber?: number;
+    /** Jump magnification */
+    magFactor?: 'fit' | 'fitH' | 'fitV' | number | string;
+}
+/** Document properties */
+interface DocProperties {
+    title?: string;
+    subject?: string;
+    author?: string;
+    keywords?: string;
+    creator?: string;
+    creatorVersion?: string;
+}
+/** addFont options */
+interface AddFontOptions {
+    /** Display family name (defaults to fontName) */
+    familyName?: string;
+    /** Whether the font is serif */
+    serif?: boolean;
+    /** Whether the font is monospaced */
+    fixed?: boolean;
+    /** Whether the font covers CJK (full-width approximation) */
+    cjk?: boolean;
+    /** Ascent (1/1000 em, default 800) */
+    ascent?: number;
+    /** Descent (1/1000 em, negative, default -200) */
+    descent?: number;
+    /** Custom width table (ASCII 32..126, 1/1000 em) */
+    widths?: Partial<Record<FontStyle, number[]>>;
+    /** Alias for setFont lookups */
+    alias?: string;
+    /** Embedded font file extension override (`ttf` default, `otf` for CFF). */
+    fontExt?: string;
+}
+/** Bookmark options */
+interface OutlineOptions {
+    /** Target page number (1-based, default 1) */
+    pageNumber?: number;
+    /** Jump position */
+    left?: number;
+    top?: number;
+    zoom?: number;
+}
+/** Bookmark node returned by doc.outline.add; pass back as parent to nest */
+interface OutlineNode {
+    title: string;
+    parent: OutlineNode | null;
+    children: OutlineNode[];
+    options: OutlineOptions;
+}
+/** Attachment options */
+interface AttachmentOptions {
+    /** Attachment format description */
+    format?: string;
+    /** Description */
+    description?: string;
+}
+/** Accepted addImage inputs */
+type ImageInput = string | Uint8Array | ArrayBuffer | HTMLImageElement | HTMLCanvasElement;
+/** Image properties returned by getImageProperties */
+interface ImageProperties {
+    fileType: string;
+    width: number | null;
+    height: number | null;
+    bytes: number;
+    data: Uint8Array;
+}
+/** Graphics state */
+interface GState {
+    /** Opacity 0-1 */
+    opacity?: number;
+}
+/** Reader interface preferences (jsPDF viewerPreferences) */
+interface ViewerPreferences {
+    HideToolbar?: boolean;
+    HideMenubar?: boolean;
+    HideWindowUI?: boolean;
+    FitWindow?: boolean;
+}
+/** output() return type ('dataurlnewwindow' returns null after opening a window) */
+type OutputResult = ArrayBuffer | Uint8Array | string | Blob | null;
+/** Active font info (getFont) */
+interface FontInfo {
+    fontName: string;
+    fontStyle: FontStyle;
+    key: string;
+}
+
+/**
+ * Internal page object model (points; converted to mm at serialisation time).
+ */
+
+interface PageData {
+    /** Page width in points */
+    width: number;
+    /** Page height in points */
+    height: number;
+    objects: PageObject[];
+}
+type PageObject = TextRun | PathRun | ImageRun | LinkRun;
+interface TextRun {
+    t: 'text';
+    /** Baseline start X in points */
+    x: number;
+    /** Baseline start Y in points */
+    y: number;
+    text: string;
+    /** Font size in points */
+    size: number;
+    fontKey: string;
+    style: FontStyle;
+    color: RGB;
+    charSpace: number;
+    /** Rotation in degrees */
+    angle: number;
+    ascent: number;
+    descent: number;
+    renderingMode: string;
+    opacity: number | null;
+    /** Justification target width in points; null disables stretching */
+    justifyWidth: number | null;
+    /** Horizontal scale (jsPDF horizontalScale; 1 is unscaled) */
+    hScale: number;
+    /** Per-glyph advances in points (PDF import); falls back to font metrics */
+    glyphWs?: number[];
+}
+type PathOp = {
+    op: 'M';
+    x: number;
+    y: number;
+} | {
+    op: 'L';
+    x: number;
+    y: number;
+} | {
+    op: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    op: 'Z';
+};
+interface DashState {
+    pattern: number[];
+    phase: number;
+}
+interface PathRun {
+    t: 'path';
+    ops: PathOp[];
+    fill: boolean;
+    stroke: boolean;
+    fillColor: RGB;
+    strokeColor: RGB;
+    /** Stroke width in points */
+    lineWidth: number;
+    dash: DashState | null;
+    cap: number;
+    join: number;
+    /** Miter limit in points (emitted when > 1) */
+    miterLimit: number;
+    opacity: number | null;
+}
+interface AttachmentData {
+    name: string;
+    data: Uint8Array;
+    format: string;
+    description: string;
+    creationDate: Date;
+}
+/** Registered image resources (deduplicated). */
+interface ImageResource {
+    alias: string;
+    data: Uint8Array;
+    /** OFD MultiMedia Format value (PNG/JPEG/GIF/BMP/TIFF) */
+    format: string;
+    /** File extension (lowercase) */
+    ext: string;
+    width: number | null;
+    height: number | null;
+    /** Resource ID assigned at serialisation time */
+    resId: number;
+}
+interface ImageRun {
+    t: 'image';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Image resource reference */
+    imageRef: ImageResource;
+    angle: number;
+    opacity: number | null;
+}
+interface LinkRun {
+    t: 'link';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    url: string | null;
+    pageNumber: number | null;
+    magFactor: string | number | null;
+}
+
+/**
+ * Font registry and text metrics.
+ *
+ * Width tables come from the public Adobe Core 14 AFM metrics (Helvetica/Times/Courier, ASCII 32..126);
+ * Chinese fonts (Song/Hei/Kai/FangSong) are approximated as full-width 1000, half-width 500.
+ * No font files are embedded; FontName references the reader's local fonts.
+ */
+
+interface FontWidths {
+    normal?: number[];
+    bold?: number[];
+    italic?: number[];
+    bolditalic?: number[];
+}
+interface FontDef {
+    /** PostScript/reference name (written to FontName) */
+    familyName: string;
+    /** Display name (written to FamilyName) */
+    displayName: string;
+    serif: boolean;
+    fixed: boolean;
+    /** Whether the font covers CJK (full-width CJK, half-width ASCII when true) */
+    cjk: boolean;
+    /** Ascent (1/1000 em) */
+    ascent: number;
+    /** Descent (1/1000 em, negative) */
+    descent: number;
+    widths: FontWidths | null;
+    /** Per-code-point widths in 1/1000 em (embedded fonts, exact metrics). */
+    unicodeWidths?: Map<number, number>;
+    /** Embedded font file; when present readers never fall back to local fonts. */
+    fontFile?: EmbeddedFontFile;
+}
+
+/** Interactive annotations: link areas and file attachments. */
+
+declare const AnnotationApi: {
+    /**
+     * Add a clickable rectangular area.
+     *
+     * Pass `url` for an external target or `pageNumber` (1-based) for an
+     * in-document jump. The area itself is invisible.
+     */
+    link(this: jsOFD, x: number, y: number, w: number, h: number, options?: LinkOptions): jsOFD;
+    /**
+     * Embed a file as an OFD attachment.
+     *
+     * @param data UTF-8 text, a base64 data URL, or binary bytes
+     */
+    addFileAsAttachment(this: jsOFD, filename: string, data: string | Uint8Array | ArrayBuffer, options?: AttachmentOptions): jsOFD;
+};
+type AnnotationApi = typeof AnnotationApi;
+declare module '../jsofd' {
+    interface jsOFD extends AnnotationApi {
+    }
+}
+
+/**
+ * Visual annotations: highlight, underline, strikeout, squiggly, freehand
+ * ink, free text and stamp-like boxes.
+ *
+ * They are emitted as ordinary page objects (translucent fills, strokes,
+ * text), so every OFD reader renders them without needing the optional
+ * annotation sidecar of the standard.
+ */
+
+type AnnotationType = 'highlight' | 'underline' | 'strikeout' | 'squiggly' | 'ink' | 'freetext' | 'box';
+interface AnnotationOptions {
+    /** Annotation color (default per type) */
+    color?: RGB;
+    /** Opacity 0-1 (default 0.35 for highlight, 1 otherwise) */
+    opacity?: number;
+    /** Line thickness (active unit, default 0.6) */
+    lineWidth?: number;
+    /** Font size in pt for freetext (default 11) */
+    fontSize?: number;
+    /** Font key for freetext (default: current font) */
+    fontKey?: string;
+    /** Text for freetext */
+    text?: string;
+    /** Fill color for box (default: transparent — stroke only) */
+    fill?: RGB;
+    /** Freehand point list for `ink` (active units) */
+    points?: [number, number][];
+}
+declare const AnnotationVisualApi: {
+    /**
+     * Draw a visual annotation over the rectangle `(x, y, w, h)` and return the
+     * doc for chaining.
+     *
+     * - `highlight`  translucent marker behind/over text (default yellow)
+     * - `underline`  straight line at the bottom edge
+     * - `strikeout`  line through the vertical middle
+     * - `squiggly`   hand-drawn style zigzag along the bottom edge
+     * - `box`        rectangle outline (optionally filled via `options.fill`)
+     * - `ink`        `options.points` as a freehand polyline (`[[x,y],…]`)
+     * - `freetext`   `options.text` wrapped inside the rectangle
+     */
+    addAnnotation(this: jsOFD, type: AnnotationType, x: number, y: number, w: number, h: number, options?: AnnotationOptions): jsOFD;
+};
+type AnnotationVisualApi = typeof AnnotationVisualApi;
+declare module '../jsofd' {
+    interface jsOFD extends AnnotationVisualApi {
+    }
+}
+
+/**
+ * Page-flow helpers: automatic multi-page text flow (`autoPaging`) and
+ * header/footer hooks applied to every page (`headerFooter`).
+ */
+
+/** Info passed to page hooks. */
+interface PageInfo {
+    /** One-based page number */
+    pageNumber: number;
+    /** Total page count at the time of the call */
+    pageCount: number;
+}
+type PageHook = (doc: jsOFD, info: PageInfo) => void;
+interface HeaderFooterOptions {
+    /** Drawn on every page in `startPage..end` */
+    header?: PageHook;
+    /** Drawn on every page in `startPage..end` */
+    footer?: PageHook;
+    /** First one-based page to draw on (default 1) */
+    startPage?: number;
+    /** Last one-based page to draw on (default: last page) */
+    endPage?: number;
+}
+interface AutoPagingOptions {
+    /** Left edge of the text block (active unit) */
+    x?: number;
+    /** First baseline (active unit); defaults to `topMargin` + first line */
+    y?: number;
+    /** Wrap width (active unit); defaults to page width − `x` − `rightMargin` */
+    maxWidth?: number;
+    /** Page top margin used when a new page starts (active unit, default 20) */
+    topMargin?: number;
+    /** Page bottom margin; flow breaks before crossing it (default 20) */
+    bottomMargin?: number;
+    /** Right margin when `maxWidth` is omitted (default 20) */
+    rightMargin?: number;
+    /** Line height factor (default: current global) */
+    lineHeightFactor?: number;
+    /** Alignment of every line (default 'left') */
+    align?: 'left' | 'center' | 'right' | 'justify';
+    /** Called after each automatic `addPage()` */
+    onNewPage?: PageHook;
+}
+declare const FlowApi: {
+    /**
+     * Flow long text across as many pages as needed.
+     *
+     * Lines wrap at `maxWidth` (same CJK/Latin rules as `text()`); when the
+     * next line would cross the bottom margin a new page is appended and
+     * `onNewPage` fires (for headers, page numbers, …).
+     *
+     * @returns the Y coordinate (active unit) after the last line — chain more
+     * content from there
+     */
+    autoPaging(this: jsOFD, text: string, options?: AutoPagingOptions): number;
+    /**
+     * Draw headers and footers on a page range.
+     *
+     * Hooks receive the document (positioned on the target page — use
+     * `text`/`line`/… normally) and `{ pageNumber, pageCount }`. Common use:
+     *
+     * ```ts
+     * doc.headerFooter({
+     *   header: (d, { pageNumber }) => d.text('季度报告', 20, 12),
+     *   footer: (d, { pageNumber, pageCount }) =>
+     *     d.text(`第 ${pageNumber} 页 / 共 ${pageCount} 页`, 105, 285, { align: 'center' }),
+     * });
+     * ```
+     */
+    headerFooter(this: jsOFD, options: HeaderFooterOptions): jsOFD;
+};
+type FlowApi = typeof FlowApi;
+declare module '../jsofd' {
+    interface jsOFD extends FlowApi {
+    }
+}
+
+/**
+ * `doc.html()` — render simple HTML into the document.
+ *
+ * A dependency-free tag-stream parser (works in Node and browsers) walks the
+ * markup and lays out block elements — headings, paragraphs, lists, breaks —
+ * flowing across pages at the bottom margin. Inline styling covers bold and
+ * italic (`b`, `strong`, `i`, `em`), entities are decoded.
+ *
+ * This is deliberately not a CSS engine: layout attributes come from the tag
+ * semantics, not stylesheets.
+ */
+
+interface HtmlOptions {
+    /** Left edge of the text block (active unit, default 20) */
+    x?: number;
+    /** Top of the content (active unit, default 20) */
+    y?: number;
+    /** Wrap width (default: page width − x − `rightMargin`) */
+    width?: number;
+    /** Bottom margin of the flow area (default 20) */
+    bottomMargin?: number;
+    /** Top margin used on continuation pages (default 20) */
+    topMargin?: number;
+    /** Base font size in pt (default 11) */
+    fontSize?: number;
+    /** Heading scale factor per level: h1 = base × 2, h2 = × 1.5, … */
+    headingScale?: number;
+    /** Line height factor (default 1.5) */
+    lineHeightFactor?: number;
+    /** Called after each automatic page break */
+    onNewPage?: (doc: jsOFD, info: {
+        pageNumber: number;
+        pageCount: number;
+    }) => void;
+}
+declare const HtmlApi: {
+    /**
+     * Render an HTML fragment and return the final Y (active unit).
+     *
+     * Supported: `h1–h6`, `p`, `div`, `br`, `ul/ol` + `li`, `b/strong`,
+     * `i/em`, entities. Inline `span` text is preserved. Attributes and CSS
+     * are ignored by design.
+     */
+    html(this: jsOFD, html: string, options?: HtmlOptions): number;
+};
+type HtmlApi = typeof HtmlApi;
+declare module '../jsofd' {
+    interface jsOFD extends HtmlApi {
+    }
+}
+
+/** Image embedding and inspection. */
+
+declare const ImageApi: {
+    /**
+     * Embed an image and place it on the current page.
+     *
+     * Binary data (PNG/JPEG/GIF/BMP/TIFF) is embedded byte-for-byte; data URLs,
+     * bare base64 strings (with `format`), `HTMLImageElement` and
+     * `HTMLCanvasElement` inputs are also accepted.
+     *
+     * When `w`/`h` are omitted the natural size at 72 dpi is used. Identical
+     * data is stored once and referenced multiple times.
+     */
+    addImage(this: jsOFD, a: unknown, b: unknown, c?: unknown, d?: unknown, e?: unknown, f?: unknown, g?: unknown, h?: unknown, i?: unknown): jsOFD;
+    /**
+     * Inspect an image without embedding it.
+     *
+     * @returns format, pixel dimensions, byte count and the raw data
+     */
+    getImageProperties(this: jsOFD, imageData: ImageInput): ImageProperties;
+};
+/** Structural type of the mixin (merged into jsOFD via declaration merging). */
+type ImageApi = typeof ImageApi;
+declare module '../jsofd' {
+    interface jsOFD extends ImageApi {
+    }
+}
+
+/** Vector shape primitives: lines, polylines, curves and closed shapes. */
+
+declare const ShapeApi: {
+    /**
+     * @internal Push a path onto the current page using the active graphics
+     * state. All public shape helpers funnel through this single entry point.
+     */
+    _pushPath(this: jsOFD, ops: PathOp[], style?: string): jsOFD;
+    /** Draw a straight line from `(x1, y1)` to `(x2, y2)`. */
+    line(this: jsOFD, x1: number, y1: number, x2: number, y2: number, style?: string): jsOFD;
+    /**
+     * Draw a polyline or curve through relative segments (jsPDF `lines`).
+     *
+     * The path starts with `M` at the anchor `(x, y)`. Each segment is a
+     * cumulative delta relative to the current point:
+     * `[dx, dy]` draws a straight line, `[x1, y1, x2, y2, x3, y3]` a cubic
+     * Bézier through three delta points.
+     *
+     * Supports the legacy signature `lines(x, y, lines, scale, style, closed)`.
+     */
+    lines(this: jsOFD, linesOrX: number[][] | number, xOrY: number | number[][], yOrLines?: number | number[][], scale1OrStyle?: number | number[] | string, scale2?: number | string, styleOrClosed?: string | boolean, _closedArg?: boolean): jsOFD;
+    /** Draw a triangle through three vertices. */
+    triangle(this: jsOFD, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, style?: string): jsOFD;
+    /** Draw a rectangle; `(x, y)` is the top-left corner. */
+    rect(this: jsOFD, x: number, y: number, w: number, h: number, style?: string): jsOFD;
+    /**
+     * Draw a rounded rectangle; `(x, y)` is the top-left corner.
+     *
+     * `ry` defaults to `rx`. Corners are quarter circles approximated with
+     * cubic Béziers (κ = 0.5523).
+     */
+    roundedRect(this: jsOFD, x: number, y: number, w: number, h: number, rx: number, ry?: number, style?: string): jsOFD;
+    /** Draw an ellipse centered at `(x, y)`. */
+    ellipse(this: jsOFD, x: number, y: number, rx: number, ry: number, style?: string): jsOFD;
+    /** Draw a circle centered at `(x, y)` with radius `r`. */
+    circle(this: jsOFD, x: number, y: number, r: number, style?: string): jsOFD;
+};
+type ShapeApi = typeof ShapeApi;
+declare module '../jsofd' {
+    interface jsOFD extends ShapeApi {
+    }
+}
+
+/** Document state accessors: fonts, colors and graphics state. */
+
+declare const StateApi: {
+    /** Resolve a font key to its definition (custom → builtin → Helvetica). */
+    getFontDef(this: jsOFD, key: string): FontDef;
+    /**
+     * Register a custom font.
+     *
+     * Fonts are referenced by `FontName` and resolved by the reader's local
+     * font table — no font file is embedded.
+     *
+     * @param postScriptName unique registry key
+     * @param fontName       family name written to the OFD font declaration
+     * @param fontStyle      `normal` / `bold` / `italic` / `bolditalic`
+     * @param opts           metrics (ascent/descent/widths) and aliases
+     */
+    addFont(this: jsOFD, postScriptName: string, fontName: string, fontStyle: string, opts?: AddFontOptions): string;
+    /**
+     * Register a font with an embedded file (recommended for CJK documents).
+     *
+     * Parses the font for exact metrics (units per em, ascent/descent, per-glyph
+     * advance widths via cmap/hmtx) and writes the bytes into the OFD package as
+     * `FontFile`. Embedded fonts render identically in every reader — unembedded
+     * fonts depend on the reader's local font table and may show garbage glyphs.
+     *
+     * Registering a key that matches a built-in (`'simsun'`, `'simhei'`, ...)
+     * overrides it, so existing code keeps working while gaining embedding.
+     *
+     * @param postScriptName registry key, e.g. `'simsun'` or `'MyFont'`
+     * @param fontName       family name written to the OFD font declaration
+     * @param ttfData        TTF/OTF (or TTC) file bytes
+     */
+    addFontTtf(this: jsOFD, postScriptName: string, fontName: string, ttfData: Uint8Array, opts?: AddFontOptions): string;
+    /**
+     * Select the active font.
+     *
+     * Accepts PostScript names (`Helvetica-Bold`), family names (`helvetica`,
+     * `times`), common Chinese names (`宋体`, `黑体`, `楷体`, `仿宋`) and any
+     * previously registered custom key or alias.
+     */
+    setFont(this: jsOFD, fontName: string, fontStyle?: string): jsOFD;
+    /** Set the font size in points (independent of the document unit, like jsPDF). */
+    setFontSize(this: jsOFD, size: number): jsOFD;
+    /** Active font size in points (default 16, like jsPDF). */
+    getFontSize(this: jsOFD): number;
+    /** Set extra spacing between glyphs, in the active unit. */
+    setCharSpace(this: jsOFD, space: number): jsOFD;
+    /** Active character spacing in the active unit. */
+    getCharSpace(this: jsOFD): number;
+    /** Set the line height factor (default 1.15, like jsPDF). */
+    setLineHeightFactor(this: jsOFD, f: number): jsOFD;
+    /** Registered font keys, built-in first. */
+    getFontList(this: jsOFD): string[];
+    /** Information about the active font (jsPDF `getFont()`). */
+    getFont(this: jsOFD): FontInfo;
+    /** Set the text fill color (`r` may also be a color name or hex string). */
+    setTextColor(this: jsOFD, r: number | string, g?: number, b?: number): jsOFD;
+    /** Active text color as `#rrggbb` (jsPDF getter semantics). */
+    getTextColor(this: jsOFD): string;
+    /** Set the stroke color used by shape outlines. */
+    setDrawColor(this: jsOFD, r: number | string, g?: number, b?: number): jsOFD;
+    /** Active stroke color as `#rrggbb`. */
+    getDrawColor(this: jsOFD): string;
+    /** Set the fill color used by filled shapes. */
+    setFillColor(this: jsOFD, r: number | string, g?: number, b?: number): jsOFD;
+    /** Active fill color as `#rrggbb`. */
+    getFillColor(this: jsOFD): string;
+    /** Set the stroke width in the active unit. */
+    setLineWidth(this: jsOFD, width: number): jsOFD;
+    /** Active stroke width in the active unit. */
+    getLineWidth(this: jsOFD): number;
+    /** Set the dash pattern (active unit); an empty array clears dashing. */
+    setLineDashPattern(this: jsOFD, dashArray: number[], dashPhase?: number): jsOFD;
+    /** Active dash pattern in the active unit. */
+    getLineDashPattern(this: jsOFD): number[];
+    /** Set the line cap: 0 butt, 1 round, 2 square (names accepted). */
+    setLineCap(this: jsOFD, style: number | "butt" | "round" | "square"): jsOFD;
+    /** Active line cap (0-2). */
+    getLineCap(this: jsOFD): number;
+    /** Set the line join: 0 miter, 1 round, 2 bevel (names accepted). */
+    setLineJoin(this: jsOFD, style: number | "miter" | "round" | "bevel"): jsOFD;
+    /** Active line join (0-2). */
+    getLineJoin(this: jsOFD): number;
+    /** Set the miter limit (active unit); values ≤ 1 omit the attribute. */
+    setLineMiterLimit(this: jsOFD, limit: number): jsOFD;
+    /** Active miter limit in the active unit. */
+    getLineMiterLimit(this: jsOFD): number;
+    /** Line height in points: font size × line height factor. */
+    getLineHeight(this: jsOFD): number;
+    /** Enable or disable right-to-left rendering. */
+    setR2L(this: jsOFD, value: boolean): jsOFD;
+    /** Whether right-to-left rendering is active. */
+    getR2L(this: jsOFD): boolean;
+    /**
+     * Apply a graphics state.
+     *
+     * Only `opacity` is supported; other GState keys are ignored (OFD models
+     * blend modes differently from PDF).
+     */
+    setGState(this: jsOFD, gs: GState): jsOFD;
+    /** Set the rendering opacity for subsequent objects (0-1). */
+    setOpacity(this: jsOFD, opacity: number): jsOFD;
+};
+type StateApi = typeof StateApi;
+declare module '../jsofd' {
+    interface jsOFD extends StateApi {
+    }
+}
+
+/**
+ * `doc.svg()` — embed an SVG by rasterizing it through the browser canvas.
+ *
+ * The SVG is loaded into an `Image` via a blob URL, drawn to a canvas at a
+ * 2× device scale for crispness, and embedded as PNG. Requires a browser
+ * (jsPDF's `addSvgAsImage` has the same constraint); Node throws a clear
+ * error suggesting pre-rasterized bytes via `addImage`.
+ */
+
+interface SvgOptions {
+    x: number;
+    y: number;
+    /** Width (active unit); defaults to the intrinsic size at 72dpi */
+    w?: number;
+    /** Height (active unit); defaults to w scaled by the viewBox ratio */
+    h?: number;
+    /** Raster scale factor (default 2 — retina-crisp) */
+    scale?: number;
+    rotation?: number;
+    opacity?: number;
+    /** Background color painted behind transparent areas (CSS color) */
+    background?: string;
+}
+declare const SvgApi: {
+    /**
+     * Rasterize an SVG markup string and embed it as a PNG image.
+     *
+     * Browser only (uses `Image` + canvas). The SVG is rendered at `scale`
+     * (default 2×) for crisp output. Use `addImage` when you already have
+     * raster bytes.
+     */
+    svg(this: jsOFD, svgMarkup: string, options: SvgOptions): Promise<void>;
+};
+type SvgApi = typeof SvgApi;
+declare module '../jsofd' {
+    interface jsOFD extends SvgApi {
+    }
+}
+
+/**
+ * `doc.table()` — a lightweight table engine in the spirit of jspdf-autotable:
+ * grid lines, header row with fill, per-column width/align, zebra striping and
+ * automatic pagination with a repeated header.
+ *
+ * All internal computation uses points (the model unit); public inputs and the
+ * return value use the active unit.
+ */
+
+interface TableColumn {
+    /** Header caption */
+    header?: string;
+    /** Column width (active unit); omitted columns share the remaining width */
+    width?: number;
+    /** Cell text alignment (default 'left') */
+    align?: 'left' | 'center' | 'right';
+}
+interface TableCell {
+    text: string;
+    bold?: boolean;
+    align?: TableColumn['align'];
+    /** Horizontal span (skip the covered cells in the row data) */
+    colSpan?: number;
+}
+type TableCellInput = string | TableCell;
+interface TableStyle {
+    /** Body font size (pt) */
+    fontSize?: number;
+    /** Header font size (pt); defaults to fontSize */
+    headFontSize?: number;
+    /** Header fill; null disables the fill (default: blue) */
+    headFill?: RGB | null;
+    /** Header text color (default white) */
+    headColor?: RGB;
+    /** Body text color (default: current text color) */
+    textColor?: RGB;
+    /** Grid line color (default light gray); null disables all grid lines */
+    borderColor?: RGB | null;
+    /** Grid line width (active unit, default 0.2) */
+    lineWidth?: number;
+    /** Cell padding (active unit, default 2) */
+    cellPadding?: number;
+    /** Fixed row height (active unit); default: fits the tallest cell */
+    rowHeight?: number;
+    /** Alternating [even, odd] row fills; enables zebra striping */
+    zebra?: [RGB, RGB] | null;
+}
+interface TableOptions {
+    columns: TableColumn[];
+    rows?: TableCellInput[][];
+    style?: TableStyle;
+    /** Append pages as needed, repeating the header row (default true) */
+    autoPage?: boolean;
+    /** Page margin of the flow area when autoPage (active unit, default 20) */
+    bottomMargin?: number;
+    /** Called after each automatic page break */
+    onNewPage?: (doc: jsOFD, info: {
+        pageNumber: number;
+        pageCount: number;
+    }) => void;
+}
+declare const TableApi: {
+    /**
+     * Render a table at `(x, y)` and return the bottom Y (active unit).
+     *
+     * Column widths: explicit `width`, otherwise the remaining page width is
+     * shared equally. With `autoPage` (default) rows that would cross the
+     * bottom margin continue on a fresh page under a repeated header.
+     */
+    table(this: jsOFD, x: number, y: number, options: TableOptions): number;
+};
+type TableApi = typeof TableApi;
+declare module '../jsofd' {
+    interface jsOFD extends TableApi {
+    }
+}
+
+/** Text layout and rendering: measurement, line breaking and `text()`. */
+
+declare const TextApi: {
+    /**
+     * Measure the width of `text` in points for an explicit font and size.
+     *
+     * Exposed publicly because jsPDF relies on `doc.measure`-style hooks for
+     * plugins such as autotable.
+     */
+    measure(this: jsOFD, text: string, fontDef: FontDef, style: FontStyle, sizePt: number, charSpacePt: number): number;
+    /** String width in font units (jsPDF `getStringUnitWidth`). */
+    getStringUnitWidth(this: jsOFD, text: string): number;
+    /**
+     * Per-character widths in points (jsPDF `getCharWidthsArray`).
+     *
+     * @param options override `fontSize` (default: active) and `charSpace`
+     */
+    getCharWidthsArray(this: jsOFD, text: string, options?: {
+        fontSize?: number;
+        charSpace?: number;
+    }): number[];
+    /** Width of `text` at the active font and size, in the active unit. */
+    getTextWidth(this: jsOFD, text: string): number;
+    /** Split `text` into lines that fit `maxWidth` (active unit). */
+    splitTextToSize(this: jsOFD, text: string, maxWidth: number): string[];
+    /**
+     * Line-breaking core.
+     *
+     * Breaks Latin text at spaces, CJK text between any two characters, and
+     * hard-splits words longer than the line width (jsPDF behaviour).
+     *
+     * @internal maxWidthPt is in points
+     */
+    _splitCore(this: jsOFD, text: string, maxWidthPt: number, fontDef: FontDef, style: FontStyle): string[];
+    /**
+     * Write text at `(x, y)`.
+     *
+     * The anchor is the left end of the baseline unless changed through the
+     * `baseline` option. Multi-line input is accepted as `\n` separated text
+     * or an array of lines; `maxWidth` enables automatic wrapping.
+     *
+     * Supports the legacy jsPDF argument order `text(x, y, text, options)`.
+     */
+    text(this: jsOFD, text: string | string[] | number, x: number | string | string[], y: number | string | TextOptions, optionsOrNothing?: TextOptions): jsOFD;
+    /**
+     * Write text wrapped in a clickable link annotation.
+     *
+     * Pass `url` for an external target or `pageNumber` for an in-document jump.
+     */
+    textWithLink(this: jsOFD, text: string, x: number, y: number, options?: TextOptions & LinkOptions): jsOFD;
+};
+/** Structural type of the mixin (merged into jsOFD via declaration merging). */
+type TextApi = typeof TextApi;
+declare module '../jsofd' {
+    interface jsOFD extends TextApi {
+    }
+}
+
+/**
+ * Dependency-free ZIP writer (STORE method).
+ *
+ * An OFD package is a ZIP container; stored (uncompressed) entries are accepted by every
+ * unzip implementation and keep output() synchronous. OFD.xml is written as the first entry.
+ */
+interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+}
+
+declare const ViewApi: {
+    /** Set document metadata (title, subject, author, keywords, creator). */
+    setProperties(this: jsOFD, properties: DocProperties): jsOFD;
+    /** Override the document creation date. */
+    setCreationDate(this: jsOFD, date: Date | string | number): jsOFD;
+    /**
+     * Read the creation date.
+     *
+     * @param type `'array'` returns `[y, m, d, h, min, s]`; anything else
+     *              returns a `Date` (jsPDF `'jsDate'` semantics)
+     */
+    getCreationDate(this: jsOFD, type?: "jsDate" | "array"): Date | number[];
+    /**
+     * Configure the initial viewer presentation.
+     *
+     * @param zoom     numeric multiplier, `'N%'`, or `'fullwidth'` /
+     *                 `'fullheight'` / `'fullpage'` / `'original'`
+     * @param layout   `'continuous'` / `'single'` / `'twoleft'` / `'tworight'` / `'two'`
+     * @param pageMode `'UseNone'` / `'UseOutlines'` / `'UseThumbs'` / `'FullScreen'`
+     * @throws on unrecognized values, mirroring jsPDF
+     */
+    setDisplayMode(this: jsOFD, zoom?: number | string, layout?: "continuous" | "single" | "twoleft" | "tworight" | "two" | string, pageMode?: string): jsOFD;
+    /**
+     * Set reader interface preferences.
+     *
+     * Supported flags: `HideToolbar`, `HideMenubar`, `HideWindowUI`, `FitWindow`.
+     * Pass `doReset` to clear previously set flags first.
+     */
+    viewerPreferences(this: jsOFD, options: ViewerPreferences, doReset?: boolean): jsOFD;
+    /**
+     * Register a total-page-count placeholder (jsPDF `putTotalPages`).
+     *
+     * At output time every occurrence of `pageIndicator` in text objects is
+     * replaced with the page count.
+     */
+    putTotalPages(this: jsOFD, pageIndicator?: string): jsOFD;
+    /** API-compatibility no-op (OFD carries no language field). */
+    setLanguage(this: jsOFD): jsOFD;
+    /**
+     * @internal Serialize to OFD ZIP entries (`OFD.xml` first).
+     *
+     * Applies the `putTotalPages` substitution on a copy, leaving the live
+     * document untouched so `output()` stays repeatable.
+     */
+    _buildFiles(this: jsOFD): ZipEntry[];
+    /**
+     * Serialize the document.
+     *
+     * @param type `'arraybuffer'` (default) / `'uint8array'` / `'blob'` /
+     *             `'dataurlstring'` / `'dataurlnewwindow'` / `'binarystring'` /
+     *             `'bloburl'`
+     */
+    output(this: jsOFD, type?: string): OutputResult;
+    /** Shorthand for `output('dataurlstring')`. */
+    getDataUrl(this: jsOFD): string;
+    /**
+     * Save the document to a file.
+     *
+     * Browser: triggers a download. Node (CJS): writes into the working
+     * directory. Node ESM has no synchronous `require` — use
+     * `output('arraybuffer')` and write the bytes yourself.
+     */
+    save(this: jsOFD, filename?: string): jsOFD;
+};
+type ViewApi = typeof ViewApi;
+declare module '../jsofd' {
+    interface jsOFD extends ViewApi {
+    }
+}
+
+/**
+ * jsOFD document class.
+ *
+ * The public API mirrors jsPDF while the serialized output follows the Chinese
+ * national fixed-layout document standard GB/T 33190-2016 (OFD).
+ *
+ * This module holds document state, the constructor, page management and the
+ * graphics-state helpers. Feature methods are contributed by the mixins in
+ * `src/modules/` and merged onto the prototype at the bottom of this file:
+ *
+ * - {@link modules/state.ts}  fonts, colors, metrics, graphics state
+ * - {@link modules/text.ts}   measurement, line breaking, `text()`
+ * - {@link modules/shapes.ts} vector primitives
+ * - {@link modules/images.ts} image embedding
+ * - {@link modules/annotations.ts} links and attachments
+ * - {@link modules/view.ts}   metadata, viewer preferences, output
+ */
+
+type OrientationResolved = 'p' | 'l';
+declare class jsOFD {
+    #private;
+    /** Active measurement unit. */
+    readonly unit: string;
+    /** Unit → point scale factor (jsPDF-compatible `internal.scaleFactor`). */
+    readonly scaleFactor: number;
+    /** Decimal places used when serializing numbers. */
+    readonly floatPrecision: number;
+    /** @internal Default orientation for `addPage()` without arguments. */
+    readonly defaultOrientation: OrientationResolved;
+    /** Pages in the document (internal coordinates are points). */
+    pages: PageData[];
+    /** Zero-based index of the current page. */
+    page: number;
+    /** User-registered fonts. */
+    customFonts: Record<string, FontDef>;
+    /** Image resources, keyed by alias, plus insertion order. */
+    images: Record<string, ImageRun['imageRef']>;
+    imageList: ImageRun['imageRef'][];
+    /** Embedded file attachments. */
+    attachments: AttachmentData[];
+    /** Bookmark tree root. */
+    outlineRoot: {
+        children: OutlineNode[];
+    };
+    /** Document metadata (see `setProperties`). */
+    properties: {
+        title: string;
+        subject: string;
+        author: string;
+        keywords: string;
+        creator: string;
+        creatorVersion: string;
+    };
+    /** Random document identifier. */
+    docID: string;
+    creationDate: Date;
+    modDate: Date | null;
+    displayMode: {
+        zoom: number | string;
+        layout: string;
+        pageMode?: string;
+    } | null;
+    viewerPrefs: Record<string, boolean>;
+    /** Placeholder (e.g. `{total}`) replaced at output time, see `putTotalPages`. */
+    totalPagesPattern: string | null;
+    activeFontKey: string;
+    activeFontStyle: 'normal' | 'bold' | 'italic' | 'bolditalic';
+    /** Font size in points. Like jsPDF, the size is always in pt regardless of unit. */
+    fontSize: number;
+    textColor: RGB;
+    drawColor: RGB;
+    fillColor: RGB;
+    lineWidth: number;
+    lineDash: {
+        pattern: number[];
+        phase: number;
+    } | null;
+    lineCap: number;
+    lineJoin: number;
+    /** Miter limit in points; 0 omits the attribute. */
+    miterLimit: number;
+    charSpace: number;
+    lineHeightFactor: number;
+    opacity: number | null;
+    r2l: boolean;
+    /** @internal Paper format used by `addPage()` without arguments. */
+    _lastFormat: PageFormat;
+    /** jsPDF-style introspection surface. */
+    readonly internal: {
+        version: string;
+        scaleFactor: number;
+        pageSize: {
+            getWidth(): number;
+            getHeight(): number;
+        };
+        numberOfPages: number;
+        pages: PageData[];
+        getFileId(): string;
+    };
+    /** Bookmark API: `doc.outline.add(parent, title, options)`. */
+    readonly outline: {
+        add(parent: OutlineNode | null, title: string, options?: OutlineOptions): OutlineNode;
+    };
+    /**
+     * Canvas-style drawing context (subset of `CanvasRenderingContext2D`).
+     * Draw calls land on the current page as vector objects.
+     */
+    get context2d(): CanvasRenderingContext2D;
+    constructor(options?: jsOFDOptions | Orientation | string, unitArg?: string, formatArg?: PageFormat);
+    /** @internal Resolve a named or `[w, h]` format to a pt size pair. */
+    _resolveFormat(format: PageFormat, orientation: OrientationResolved): [number, number];
+    /** @internal Convert a coordinate in the active unit to points. */
+    _u(v: number): number;
+    /** @internal Append a page sized in points and make it current. */
+    _addPageWithSize(wPt: number, hPt: number): this;
+    /** Append a page, optionally with a different format and orientation. */
+    addPage(format?: PageFormat, orientation?: string): this;
+    /** Switch to a one-based page number. */
+    setPage(n: number): this;
+    /** Insert an empty page before the given one-based position. */
+    insertPage(beforePage?: number): this;
+    /** Move a page (default: the current one) to before another position. */
+    movePage(targetPage?: number, beforePage?: number): this;
+    /** Delete a page (the last page is replaced by an empty one). */
+    deletePage(target?: number): this;
+    /** Number of pages in the document. */
+    getNumberOfPages(): number;
+    /** Width of the current page in the active unit. */
+    getPageWidth(): number;
+    /** Height of the current page in the active unit. */
+    getPageHeight(): number;
+}
+
+/**
+ * PDF to OFD conversion by replaying the pdfjs-dist operator list.
+ *
+ * Converts: text (position, size, color, weight/style, advances per glyph),
+ * fonts (embedded font files are carried over and embedded into the OFD),
+ * vector paths (lines, rectangles, Bezier, fills, strokes, dashes, caps,
+ * miter), raster images (RGB/RGBA/grayscale re-encoded as PNG), opacity,
+ * multiple pages and page rotation.
+ *
+ * Not converted: clipping paths, blend modes, pattern and shading fills,
+ * Type 3 fonts, and annotations.
+ *
+ * Usage: `const doc = await pdfToOfd(pdfBytes); doc.save("out.ofd");`
+ */
+
+interface PdfImgData {
+    width: number;
+    height: number;
+    kind?: number;
+    data: Uint8Array | Uint8ClampedArray;
+    bitmap?: unknown;
+}
+/** @internal Exposed for tests. */
+declare function imgDataToPng(img: PdfImgData): Promise<Uint8Array | null>;
+/** pdfjs extras (browsers should pass workerSrc / standardFontDataUrl). */
+interface PdfToOfdOptions {
+    /** Page size scale (default 1; output unit is pt). */
+    scale?: number;
+    /** Progress callback (0-based page index). */
+    onProgress?: (pageIndex: number, totalPages: number) => void;
+    /** pdfjs worker URL (recommended in browsers, e.g. a CDN pdf.worker.min.mjs). */
+    workerSrc?: string;
+    /** Standard-font data directory (optional; silences Base14 warnings). */
+    standardFontDataUrl?: string;
+    /** CMap directory (required for CJK CID fonts; auto-detected in Node). */
+    cMapUrl?: string;
+    cMapPacked?: boolean;
+}
+/** Globally configure pdfjs worker/font asset URLs (browsers). */
+declare function configurePdfImport(opts: {
+    workerSrc?: string;
+    standardFontDataUrl?: string;
+    cMapUrl?: string;
+}): void;
+declare function pdfToOfd(data: Uint8Array | ArrayBuffer, options?: PdfToOfdOptions): Promise<jsOFD>;
+
+export { type PdfToOfdOptions, configurePdfImport, imgDataToPng, pdfToOfd };