@hufe921/jsofd 1.0.0

package/dist/jsofd.d.cts

@@ -0,0 +1,1127 @@
+/**
+ * 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;
+}
+/** addImage object-signature options */
+interface AddImageOptions {
+    /** Placement and size (active unit) */
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    /** Format PNG/JPEG/GIF/BMP/TIFF (optional for data URLs) */
+    format?: string;
+    /** Alias; identical data shares one resource */
+    alias?: string;
+    /** Rotation in degrees around the image center */
+    rotation?: number;
+    /** Opacity 0-1 (reserved) */
+    opacity?: number;
+}
+/** Graphics state */
+interface GState {
+    /** Opacity 0-1 */
+    opacity?: number;
+}
+/** Reader interface preferences (jsPDF viewerPreferences) */
+interface ViewerPreferences {
+    HideToolbar?: boolean;
+    HideMenubar?: boolean;
+    HideWindowUI?: boolean;
+    FitWindow?: boolean;
+}
+/** Initial view (setDisplayMode) */
+interface DisplayMode {
+    zoom: number | string;
+    layout: string;
+    pageMode: string;
+}
+/** 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;
+}
+declare const BUILTIN_FONTS: Record<string, FontDef>;
+declare const FONT_ALIASES: Record<string, string>;
+
+/** 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
+ */
+
+declare const JSOFD_VERSION = "1.0.0";
+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;
+}
+
+/**
+ * Paper sizes (millimetres) and measurement units.
+ *
+ * Paper sizes are stored in mm because OFD coordinates are natively mm;
+ * serialising (pt to mm) then yields exact sizes (A4 is exactly 210x297).
+ */
+
+declare const PAGE_FORMATS_MM: Record<string, [number, number]>;
+/** Points per unit. */
+declare const UNIT_FACTORS: Record<Unit, number>;
+
+/**
+ * XML generation helpers (GB/T 33190 uses the `ofd:` namespace prefix).
+ */
+
+declare const OFD_NAMESPACE = "http://www.ofdspec.org/2016";
+
+/**
+ * jsOFD - generate OFD fixed-layout documents (GB/T 33190-2016) with JavaScript/TypeScript.
+ *
+ * The API mirrors jsPDF (https://github.com/parallax/jsPDF);
+ * the output target is the Chinese national standard OFD (Open Fixed-layout Document) instead of PDF.
+ */
+
+declare const version = "1.0.0";
+
+export { type AddFontOptions, type AddImageOptions, type AnnotationOptions, type AnnotationType, type AttachmentData, type AttachmentOptions, type AutoPagingOptions, BUILTIN_FONTS, type DashState, type DisplayMode, type DocProperties, type EmbeddedFontFile, FONT_ALIASES, type FontDef, type FontInfo, type FontStyle, type FontWidths, type GState, type HeaderFooterOptions, type HtmlOptions, type ImageInput, type ImageProperties, type ImageResource, type ImageRun, JSOFD_VERSION, type LinkOptions, type LinkRun, OFD_NAMESPACE, type Orientation, type OutlineNode, type OutlineOptions, type OutputResult, PAGE_FORMATS_MM, type PageData, type PageFormat, type PageInfo, type PageObject, type PathOp, type PathRun, type RGB, type SvgOptions, type TableCell, type TableCellInput, type TableColumn, type TableOptions, type TableStyle, type TextAlign, type TextBaseline, type TextOptions, type TextRenderingMode, type TextRun, UNIT_FACTORS, type Unit, type ViewerPreferences, jsOFD as default, jsOFD, type jsOFDOptions, version };