@masumdev/markforge 0.2.5 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import * as http from 'node:http';
+
 declare enum OutputFormat {
     DOCX = "docx",
     PDF = "pdf",
@@ -151,6 +153,210 @@ interface WatermarkOptions {
     rotate?: number;
     position?: "diagonal" | "center" | "top-right" | "bottom-right" | WatermarkPosition;
 }
+declare enum CoverPagePreset {
+    MODERN = "modern",
+    CORPORATE_SPLIT = "corporate-split",
+    MINIMAL = "minimal",
+    CARD = "card"
+}
+type CoverPreset = "modern" | "corporate-split" | "minimal" | "card" | CoverPagePreset;
+interface CoverPageConfig {
+    /**
+     * Whether the dedicated cover page is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Cover page visual layout template.
+     * @default "modern"
+     */
+    preset?: CoverPreset;
+    /**
+     * Title shown on the cover page (falls back to document title).
+     */
+    title?: string;
+    /**
+     * Subtitle shown on the cover page (falls back to document subtitle).
+     */
+    subtitle?: string;
+    /**
+     * Author(s) shown on the cover page (falls back to document author).
+     */
+    author?: string | string[];
+    /**
+     * Organization / Company name shown on the cover page.
+     */
+    company?: string;
+    /**
+     * Document version shown on the cover page.
+     */
+    version?: string;
+    /**
+     * Date shown on the cover page (falls back to document date or current date).
+     */
+    date?: string | boolean;
+    /**
+     * Status / Confidentiality badge (e.g. "CONFIDENTIAL", "DRAFT", "TECHNICAL SPECIFICATION").
+     */
+    badge?: string;
+    /**
+     * Badge background and text colors.
+     */
+    badgeColor?: string;
+    badgeTextColor?: string;
+    /**
+     * Corporate logo image path, URL, or Base64 data URI.
+     */
+    logo?: string;
+    /**
+     * Width or height of the logo (e.g. 120, "120px", "3.5cm").
+     */
+    logoWidth?: number | string;
+    /**
+     * Custom background color or CSS gradient for the cover page.
+     */
+    bgGradient?: string;
+    /**
+     * Custom text color for cover typography.
+     */
+    textColor?: string;
+    /**
+     * Custom footer notes at the bottom of the cover page.
+     */
+    footerText?: string;
+}
+type BackCoverPreset = "modern" | "corporate" | "minimal" | "contact-card";
+interface BackCoverSocial {
+    github?: string;
+    twitter?: string;
+    linkedin?: string;
+    website?: string;
+    [key: string]: string | undefined;
+}
+interface BackCoverConfig {
+    /**
+     * Whether the standalone back cover / closing page is enabled.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Visual layout preset for the back cover:
+     * - "modern": Accent colored background with centered logo, thank you typography, and contact footer.
+     * - "corporate": Navy/cyan split layout with comprehensive company details, legal notice, and social links.
+     * - "minimal": Clean white card with minimalist contact table and copyright line.
+     * - "contact-card": Floating elevated glassmorphic contact card with full metadata grid.
+     * @default "modern"
+     */
+    preset?: BackCoverPreset;
+    /**
+     * Headline title shown on the back cover.
+     * @default "Thank You"
+     */
+    title?: string;
+    /**
+     * Subtitle / closing statement shown on the back cover.
+     */
+    subtitle?: string;
+    /**
+     * Organization or company name (falls back to document company).
+     */
+    company?: string;
+    /**
+     * Office address or headquarters location.
+     */
+    address?: string;
+    /**
+     * Official contact email address.
+     */
+    email?: string;
+    /**
+     * Official contact phone number.
+     */
+    phone?: string;
+    /**
+     * Official company website URL.
+     */
+    website?: string;
+    /**
+     * Social media links dictionary (e.g. { github: "https://github.com/masumrpg", ... }).
+     */
+    social?: BackCoverSocial;
+    /**
+     * Copyright notice at the bottom (supports tokens like {company}, {date}, {year}).
+     */
+    copyright?: string;
+    /**
+     * Brand logo path, URL, or Base64 data URI.
+     */
+    logo?: string;
+    /**
+     * Logo width (e.g. 140, "140px", "3.5cm").
+     */
+    logoWidth?: number | string;
+    /**
+     * Status / confidentiality badge.
+     */
+    badge?: string;
+    /**
+     * Badge colors.
+     */
+    badgeColor?: string;
+    badgeTextColor?: string;
+    /**
+     * Custom CSS background gradient or solid hex color for the back cover.
+     */
+    bgGradient?: string;
+    /**
+     * Custom text color for back cover typography.
+     */
+    textColor?: string;
+}
+interface NumberHeadingsOptions {
+    /**
+     * Whether hierarchical heading numbering is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum heading level depth to number (e.g. 3 for H1..H3, 4 for H1..H4).
+     * @default 3
+     */
+    depth?: number;
+    /**
+     * Whether to skip numbering the main H1 document heading.
+     * @default false
+     */
+    skipH1?: boolean;
+    /**
+     * Custom prefix string prepended to all heading numbers.
+     * @default ""
+     */
+    prefix?: string;
+}
+type NumberHeadingsConfig = boolean | NumberHeadingsOptions;
+interface PdfPermissions {
+    printing?: "highResolution" | "lowResolution" | "none" | boolean;
+    modifying?: boolean;
+    copying?: boolean;
+    annotating?: boolean;
+    fillingForms?: boolean;
+    contentAccessibility?: boolean;
+    documentAssembly?: boolean;
+}
+interface SecurityConfig {
+    /**
+     * Password required to open and view the document.
+     */
+    userPassword?: string;
+    /**
+     * Master password required to change document permissions.
+     */
+    ownerPassword?: string;
+    /**
+     * Granular permission restrictions on the PDF document.
+     */
+    permissions?: PdfPermissions;
+}
 /**
  * Pure document metadata dictionary (author, title, date, version, etc.).
  */
@@ -162,9 +368,83 @@ interface DocumentMetadata {
     version?: string;
     company?: string;
     lang?: string;
-    coverPage?: boolean;
+    coverPage?: boolean | CoverPageConfig;
+    backCover?: boolean | BackCoverConfig;
     [key: string]: unknown;
 }
+type SignatureAlign = "left" | "center" | "right" | "space-between";
+type SignatureStyle = "line" | "box" | "clean";
+interface SignatureItem {
+    /**
+     * Title or sign-off label above signature (e.g. "Prepared by", "Approved by", "Acknowledged by").
+     */
+    title?: string;
+    /**
+     * Signatory person name (supports metadata tokens like {author}, {company}).
+     */
+    name: string;
+    /**
+     * Signatory job title, role, or department (e.g. "Lead System Architect", "Chief Technology Officer").
+     */
+    role?: string;
+    /**
+     * Signature date string or template (e.g. "2026-08-29", "{date}", or true for auto-formatted current date).
+     */
+    date?: string | boolean;
+    /**
+     * Optional signature image path, URL, or Base64 data URI (stamp, digital seal, or handwritten signature).
+     */
+    image?: string;
+    /**
+     * Height reserved for physical handwriting signature (e.g. 60, "60px", "1.5cm").
+     * @default 60
+     */
+    signatureHeight?: number | string;
+}
+interface SignatureBlockConfig {
+    /**
+     * List of 1 to 4 signature slots.
+     */
+    items: SignatureItem[];
+    /**
+     * Horizontal alignment of the signature block.
+     * @default "right" for 1 item, "space-between" for >= 2 items
+     */
+    align?: SignatureAlign;
+    /**
+     * Visual layout style of the signature block:
+     * - "line": Traditional signature with a horizontal separator line above name.
+     * - "box": Formal bordered rectangular approval card.
+     * - "clean": Minimalist blank vertical space without borders.
+     * @default "line"
+     */
+    style?: SignatureStyle;
+    /**
+     * Border or divider line color.
+     * @default "#CBD5E1"
+     */
+    borderColor?: string;
+    /**
+     * Color of the signature title / label.
+     * @default "#64748B"
+     */
+    titleColor?: string;
+    /**
+     * Color of the signatory name.
+     * @default "#0F172A"
+     */
+    nameColor?: string;
+    /**
+     * Color of the role and date text.
+     * @default "#64748B"
+     */
+    roleColor?: string;
+    /**
+     * Vertical spacing before the signature block (e.g. "2.5rem", 480).
+     * @default "2.5rem"
+     */
+    spacingBefore?: number | string;
+}
 /**
  * Document visual & layout options (theme, orientation, margins, headers, footers, etc.).
  */
@@ -201,6 +481,11 @@ interface DocumentLayoutConfig {
      * @default false
      */
     toc?: boolean;
+    /**
+     * Document signature and approval block at the bottom of the document.
+     * Supports 1-4 signature items, flexible alignment, and multiple styles ("line", "box", "clean").
+     */
+    signatures?: SignatureBlockConfig | SignatureItem[];
     /**
      * Optional watermark configuration to display across pages.
      * @default false
@@ -210,6 +495,28 @@ interface DocumentLayoutConfig {
      * Path(s) to custom CSS stylesheets to inject into the document.
      */
     css?: string | string[];
+    /**
+     * Dedicated standalone Cover Page builder.
+     */
+    coverPage?: boolean | CoverPageConfig;
+    /**
+     * Dedicated standalone Back Cover / Closing Page builder.
+     */
+    backCover?: boolean | BackCoverConfig;
+    /**
+     * Hierarchical heading numbering (e.g. 1., 1.1, 1.1.1).
+     * @default false
+     */
+    numberHeadings?: NumberHeadingsConfig;
+    /**
+     * Document security and password protection for PDF outputs.
+     */
+    security?: SecurityConfig;
+    /**
+     * Whether LaTeX math equations ($inline$ and $$block$$) are parsed and rendered.
+     * @default true
+     */
+    math?: boolean;
     /**
      * Code syntax highlighting theme.
      * @default "github-dark"
@@ -294,9 +601,9 @@ declare function formatServerTimestamp(date?: Date): string;
  */
 declare function compileMarkdown(inputFilePathOrContent: string, userConfig?: MarkforgeConfig, onProgress?: (msg: string) => void): Promise<CompilationResult>;
 
-type MarkdownNodeType = "heading" | "paragraph" | "blockquote" | "callout" | "list" | "listItem" | "table" | "tableRow" | "tableCell" | "codeBlock" | "mermaid" | "htmlBlock" | "thematicBreak" | "image" | "toc";
+type MarkdownNodeType = "heading" | "paragraph" | "blockquote" | "callout" | "list" | "listItem" | "table" | "tableRow" | "tableCell" | "codeBlock" | "mermaid" | "mathBlock" | "footnoteDef" | "columns" | "column" | "htmlBlock" | "thematicBreak" | "image" | "toc";
 interface MarkdownInlineSpan {
-    type: "text" | "bold" | "italic" | "code" | "link" | "strikethrough" | "image" | "htmlInline";
+    type: "text" | "bold" | "italic" | "code" | "link" | "strikethrough" | "image" | "htmlInline" | "mathInline" | "footnoteRef";
     content: string;
     url?: string;
     title?: string;
@@ -305,6 +612,7 @@ interface MarkdownInlineSpan {
     height?: number | string;
     children?: MarkdownInlineSpan[];
     style?: Record<string, string>;
+    footnoteId?: string;
 }
 interface MarkdownASTNode {
     type: MarkdownNodeType;
@@ -321,6 +629,14 @@ interface MarkdownASTNode {
     rawHtml?: string;
     id?: string;
     style?: Record<string, string>;
+    columnsCount?: number;
+    columnGap?: string;
+    footnoteId?: string;
+}
+interface FootnoteDefinition {
+    id: string;
+    text: string;
+    inlines: MarkdownInlineSpan[];
 }
 interface ParsedMarkdownDocument {
     metadata: FrontmatterMetadata;
@@ -332,9 +648,10 @@ interface ParsedMarkdownDocument {
         level: number;
     }[];
     inlinedStyles: string[];
+    footnoteDefs: FootnoteDefinition[];
 }
 /**
- * Parses inline formatting (bold, italic, code, links, images, HTML spans)
+ * Parses inline formatting (bold, italic, code, links, images, math, footnotes, HTML spans)
  */
 declare function parseInlineSpans(text: string): MarkdownInlineSpan[];
 /**
@@ -355,6 +672,235 @@ declare function parseMarginToTwip(margin?: string | number, defaultTwip?: numbe
  */
 declare function buildDocxDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<Buffer>;
 
+/**
+ * Standard paper dimensions in Word Twips (1/20th of a point, 1440 twips = 1 inch).
+ */
+declare const PAPER_DIMENSIONS_TWIP: Record<PaperSize, {
+    width: number;
+    height: number;
+}>;
+interface NormalizedMargins {
+    top: string;
+    bottom: string;
+    left: string;
+    right: string;
+    topTwip: number;
+    bottomTwip: number;
+    leftTwip: number;
+    rightTwip: number;
+}
+interface NormalizedWatermark {
+    text: string;
+    color: string;
+    opacity: number;
+    fontSize: number;
+    rotate: number;
+    position: "diagonal" | "center" | "top-right" | "bottom-right";
+}
+interface NormalizedHeaderFooterZone {
+    text: string;
+    color: string;
+    fontSize: number;
+    fontFamily: string;
+    bold: boolean;
+    italic: boolean;
+}
+interface NormalizedHeaderFooter {
+    left?: NormalizedHeaderFooterZone;
+    center?: NormalizedHeaderFooterZone;
+    right?: NormalizedHeaderFooterZone;
+    font: string;
+    size: number;
+    color: string;
+    divider: boolean;
+    dividerColor: string;
+}
+interface NormalizedSignatureItem {
+    title?: string;
+    name: string;
+    role?: string;
+    date?: string;
+    image?: string;
+    signatureHeight: number;
+}
+interface NormalizedSignatureBlock {
+    items: NormalizedSignatureItem[];
+    align: SignatureAlign;
+    style: SignatureStyle;
+    borderColor: string;
+    titleColor: string;
+    nameColor: string;
+    roleColor: string;
+    spacingBefore: string;
+    spacingBeforeTwip: number;
+}
+interface NormalizedCoverPage {
+    enabled: boolean;
+    preset: "modern" | "corporate-split" | "minimal" | "card";
+    title: string;
+    subtitle?: string;
+    author?: string;
+    company?: string;
+    version?: string;
+    date?: string;
+    badge?: string;
+    badgeColor?: string;
+    badgeTextColor?: string;
+    logo?: string;
+    logoWidth?: number | string;
+    bgGradient?: string;
+    textColor?: string;
+    footerText?: string;
+}
+interface NormalizedBackCover {
+    enabled: boolean;
+    preset: "modern" | "corporate" | "minimal" | "contact-card";
+    title: string;
+    subtitle?: string;
+    company?: string;
+    address?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    social?: Record<string, string>;
+    copyright?: string;
+    badge?: string;
+    badgeColor?: string;
+    badgeTextColor?: string;
+    logo?: string;
+    logoWidth?: number | string;
+    bgGradient?: string;
+    textColor?: string;
+}
+interface NormalizedNumberHeadings {
+    enabled: boolean;
+    depth: number;
+    skipH1: boolean;
+    prefix: string;
+}
+interface NormalizedSecurity {
+    userPassword?: string;
+    ownerPassword?: string;
+    permissions?: {
+        printing?: "highResolution" | "lowResolution" | "none";
+        modifying?: boolean;
+        copying?: boolean;
+        annotating?: boolean;
+        fillingForms?: boolean;
+        contentAccessibility?: boolean;
+        documentAssembly?: boolean;
+    };
+}
+interface ResolvedDocumentConfig {
+    title: string;
+    subtitle?: string;
+    author?: string;
+    date?: string;
+    version?: string;
+    company?: string;
+    lang: string;
+    theme: MarkforgeTheme;
+    orientation: DocumentOrientation;
+    paperSize: PaperSize;
+    paperDimensions: {
+        widthTwip: number;
+        heightTwip: number;
+    };
+    margins: NormalizedMargins;
+    header?: NormalizedHeaderFooter;
+    footer?: NormalizedHeaderFooter;
+    toc: boolean;
+    signatures?: NormalizedSignatureBlock;
+    watermark?: NormalizedWatermark;
+    coverPage?: NormalizedCoverPage;
+    backCover?: NormalizedBackCover;
+    numberHeadings?: NormalizedNumberHeadings;
+    security?: NormalizedSecurity;
+    math: boolean;
+    css: string[];
+    embedImages: boolean;
+    bundleHtml: boolean;
+    syntaxTheme: string;
+}
+/**
+ * Replaces dynamic variables ({title}, {subtitle}, {author}, {version}, {date}, {company}) in text templates.
+ */
+declare function replaceDocumentTokens(template: string | undefined, meta: {
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    version?: string;
+    date?: string;
+    company?: string;
+    year?: string;
+    [key: string]: string | undefined;
+}): string;
+/**
+ * Normalizes watermark configuration into a consistent structured object.
+ */
+declare function normalizeWatermark(rawWatermark?: string | WatermarkOptions | false): NormalizedWatermark | undefined;
+/**
+ * Normalizes an individual left, center, or right header/footer zone slot.
+ */
+declare function normalizeHeaderFooterSlot(rawSlot: string | HeaderFooterSlot | undefined, parent: HeaderFooterItem | undefined, meta: {
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    version?: string;
+    date?: string;
+    company?: string;
+}): NormalizedHeaderFooterZone | undefined;
+/**
+ * Normalizes a header or footer item into a structured NormalizedHeaderFooter object.
+ */
+declare function normalizeHeaderFooter(raw: HeaderFooterItem | undefined, meta: {
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    version?: string;
+    date?: string;
+    company?: string;
+}): NormalizedHeaderFooter | undefined;
+/**
+ * Normalizes signature and approval block configuration.
+ */
+declare function normalizeSignatures(raw?: SignatureBlockConfig | SignatureItem[], meta?: Record<string, unknown>): NormalizedSignatureBlock | undefined;
+/**
+ * Normalizes Cover Page configuration with token replacement.
+ */
+declare function normalizeCoverPage(rawCover?: boolean | CoverPageConfig | Record<string, unknown>, tokenCtx?: {
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    version?: string;
+    date?: string;
+    company?: string;
+}): NormalizedCoverPage | undefined;
+/**
+ * Normalizes Back Cover / Closing Page configuration with token replacement.
+ */
+declare function normalizeBackCover(rawBack?: boolean | BackCoverConfig | Record<string, unknown>, tokenCtx?: {
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    version?: string;
+    date?: string;
+    company?: string;
+}): NormalizedBackCover | undefined;
+/**
+ * Normalizes numberHeadings configuration.
+ */
+declare function normalizeNumberHeadings(raw?: NumberHeadingsConfig | Record<string, unknown>): NormalizedNumberHeadings | undefined;
+/**
+ * Normalizes security / PDF password encryption configuration.
+ */
+declare function normalizeSecurity(raw?: SecurityConfig | Record<string, unknown>): NormalizedSecurity | undefined;
+/**
+ * Centralized Single Source of Truth for resolving document configuration.
+ * Priority hierarchy: Frontmatter metadata > Project Config File / User Config > DEFAULT_CONFIG
+ */
+declare function resolveDocumentConfig(frontmatter?: Record<string, unknown>, userConfig?: MarkforgeConfig): ResolvedDocumentConfig;
+
 /**
  * Escapes HTML characters safely.
  */
@@ -363,6 +909,24 @@ declare function escapeHtml(str: string): string;
  * Converts Markdown inline spans to HTML markup.
  */
 declare function renderInlinesToHtml(spans?: MarkdownInlineSpan[], baseDir?: string): Promise<string>;
+/**
+ * Renders an AST node array to HTML.
+ */
+declare function renderNodesToHtml(nodes: MarkdownASTNode[], resolved: ResolvedDocumentConfig, baseDir?: string): Promise<string>;
+/**
+ * Renders the Cover Page HTML and returns { html, css }.
+ */
+declare function renderCoverPageHtml(cover: NormalizedCoverPage, baseDir?: string): Promise<{
+    html: string;
+    css: string;
+}>;
+/**
+ * Renders the Back Cover / Closing Page HTML & CSS.
+ */
+declare function renderBackCoverHtml(backCover: NormalizedBackCover, baseDir?: string): Promise<{
+    html: string;
+    css: string;
+}>;
 /**
  * Builds standalone self-contained HTML from a parsed Markdown document.
  */
@@ -437,6 +1001,15 @@ declare function highlightCodeToHtml(code: string, lang?: string, theme?: string
  */
 declare function renderMermaidToPng(mermaidCode: string, _baseDir?: string): Promise<Buffer | null>;
 
+/**
+ * Renders a LaTeX math formula into clean HTML/MathML markup using KaTeX.
+ */
+declare function renderMathToHtml(latex: string, displayMode?: boolean): string;
+/**
+ * Minimal inlined KaTeX CSS required for rendering formulas without external network requests.
+ */
+declare const KATEX_INLINE_CSS = "\n.katex { font: normal 1.21em KaTeX_Main, Times New Roman, serif; line-height: 1.2; text-indent: 0; text-rendering: auto; border-color: currentColor; }\n.katex * { -ms-high-contrast-adjust: none !important; }\n.katex .katex-html { display: inline-block; }\n.katex .katex-mathml { clip: rect(1px, 1px, 1px, 1px); border: 0; height: 1px; overflow: hidden; padding: 0; position: absolute; width: 1px; }\n.katex-display { display: block; margin: 1em 0; text-align: center; }\n.katex-display > .katex { display: inline-block; text-align: initial; }\n.katex .base { position: relative; white-space: nowrap; width: min-content; }\n.katex .strut { display: inline-block; }\n.katex .mord { display: inline-block; }\n.katex .mbin { display: inline-block; }\n.katex .mrel { display: inline-block; }\n.katex .mopen { display: inline-block; }\n.katex .mclose { display: inline-block; }\n.katex .mpunct { display: inline-block; }\n.katex .minner { display: inline-block; }\n.katex .mop { display: inline-block; }\n.katex .frac-line { width: 100%; border-bottom-style: solid; }\n.katex .vlist-t { display: inline-table; table-layout: fixed; }\n.katex .vlist-r { display: table-row; }\n.katex .vlist { display: table-cell; vertical-align: bottom; position: relative; }\n.katex .msupsub { text-align: left; }\n.katex .sqrt > .root { margin-left: 0.27777778em; margin-right: -0.55555556em; }\n";
+
 /**
  * Flagship corporate theme — full design system with Blu-by-BCA-Digital cyan palette.
  */
@@ -449,17 +1022,41 @@ declare const THEMES: Record<string, string>;
  */
 declare function generateThemeCss(theme?: MarkforgeTheme): string;
 
+interface PreviewServerOptions {
+    filePath: string;
+    port?: number;
+    open?: boolean;
+    config?: MarkforgeConfig;
+}
+interface PreviewServerInstance {
+    server: http.Server;
+    port: number;
+    url: string;
+    close: () => Promise<void>;
+}
+/**
+ * Launches an interactive dual-pane Markdown Editor & Live-Reload Preview Server.
+ * Left Pane: Code Editor with line numbers, shortcut triggers, auto-save, and formatting toolbar.
+ * Right Pane: Real-time rendered document preview iframe with scroll preservation.
+ */
+declare function startPreviewServer(options: PreviewServerOptions): Promise<PreviewServerInstance>;
+
 /**
  * Type-safe configuration helper for markforge.config.ts
  */
 declare function defineConfig(config: MarkforgeConfig): MarkforgeConfig;
 
-declare const DEFAULT_CONFIG: Required<Omit<MarkforgeConfig, "outputDir" | "css" | "margins" | "header" | "footer" | "watermark" | "metadata" | "syntaxTheme">> & {
+declare const DEFAULT_CONFIG: Required<Omit<MarkforgeConfig, "outputDir" | "css" | "margins" | "header" | "footer" | "watermark" | "metadata" | "syntaxTheme" | "signatures" | "coverPage" | "backCover" | "numberHeadings" | "security">> & {
     outputDir?: string;
     css?: string | string[];
     margins?: MarkforgeConfig["margins"];
     header?: MarkforgeConfig["header"];
     footer?: MarkforgeConfig["footer"];
+    signatures?: MarkforgeConfig["signatures"];
+    coverPage?: MarkforgeConfig["coverPage"];
+    backCover?: MarkforgeConfig["backCover"];
+    numberHeadings?: MarkforgeConfig["numberHeadings"];
+    security?: MarkforgeConfig["security"];
     watermark?: string;
     metadata?: MarkforgeConfig["metadata"];
     syntaxTheme?: string;
@@ -472,117 +1069,6 @@ declare function loadConfig(customPath?: string, startDir?: string): Promise<{
     configPath: string | null;
 }>;
 
-/**
- * Standard paper dimensions in Word Twips (1/20th of a point, 1440 twips = 1 inch).
- */
-declare const PAPER_DIMENSIONS_TWIP: Record<PaperSize, {
-    width: number;
-    height: number;
-}>;
-interface NormalizedMargins {
-    top: string;
-    bottom: string;
-    left: string;
-    right: string;
-    topTwip: number;
-    bottomTwip: number;
-    leftTwip: number;
-    rightTwip: number;
-}
-interface NormalizedWatermark {
-    text: string;
-    color: string;
-    opacity: number;
-    fontSize: number;
-    rotate: number;
-    position: "diagonal" | "center" | "top-right" | "bottom-right";
-}
-interface NormalizedHeaderFooterZone {
-    text: string;
-    color: string;
-    fontSize: number;
-    fontFamily: string;
-    bold: boolean;
-    italic: boolean;
-}
-interface NormalizedHeaderFooter {
-    left?: NormalizedHeaderFooterZone;
-    center?: NormalizedHeaderFooterZone;
-    right?: NormalizedHeaderFooterZone;
-    font: string;
-    size: number;
-    color: string;
-    divider: boolean;
-    dividerColor: string;
-}
-interface ResolvedDocumentConfig {
-    title: string;
-    subtitle?: string;
-    author?: string;
-    date?: string;
-    version?: string;
-    company?: string;
-    lang: string;
-    theme: MarkforgeTheme;
-    orientation: DocumentOrientation;
-    paperSize: PaperSize;
-    paperDimensions: {
-        widthTwip: number;
-        heightTwip: number;
-    };
-    margins: NormalizedMargins;
-    header?: NormalizedHeaderFooter;
-    footer?: NormalizedHeaderFooter;
-    toc: boolean;
-    watermark?: NormalizedWatermark;
-    css: string[];
-    embedImages: boolean;
-    bundleHtml: boolean;
-    syntaxTheme: string;
-}
-/**
- * Replaces dynamic variables ({title}, {subtitle}, {author}, {version}, {date}, {company}) in text templates.
- */
-declare function replaceDocumentTokens(template: string | undefined, meta: {
-    title?: string;
-    subtitle?: string;
-    author?: string;
-    version?: string;
-    date?: string;
-    company?: string;
-}): string;
-/**
- * Normalizes watermark configuration into a consistent structured object.
- */
-declare function normalizeWatermark(rawWatermark?: string | WatermarkOptions | false): NormalizedWatermark | undefined;
-/**
- * Normalizes an individual left, center, or right header/footer zone slot.
- */
-declare function normalizeHeaderFooterSlot(rawSlot: string | HeaderFooterSlot | undefined, parent: HeaderFooterItem | undefined, meta: {
-    title?: string;
-    subtitle?: string;
-    author?: string;
-    version?: string;
-    date?: string;
-    company?: string;
-}): NormalizedHeaderFooterZone | undefined;
-/**
- * Normalizes a header or footer item into a structured NormalizedHeaderFooter object.
- */
-declare function normalizeHeaderFooter(raw: HeaderFooterItem | undefined, meta: {
-    title?: string;
-    subtitle?: string;
-    author?: string;
-    version?: string;
-    date?: string;
-    company?: string;
-}): NormalizedHeaderFooter | undefined;
-/**
- * Centralized Single Source of Truth for resolving document configuration.
- * Priority hierarchy: Frontmatter metadata > Project Config File / User Config > DEFAULT_CONFIG
- */
-declare function resolveDocumentConfig(frontmatter?: Record<string, unknown>, userConfig?: MarkforgeConfig): ResolvedDocumentConfig;
-
 /**
  * Dynamically resolved version — reads from the nearest package.json at runtime.
  * Falls back to the hardcoded FALLBACK_VERSION constant if not found.
@@ -593,4 +1079,4 @@ declare const MARKFORGE_VERSION: string;
  */
 declare function getMarkforgeVersion(fromDir?: string): string;
 
-export { type CompilationResult, DEFAULT_CONFIG, type DocumentLayoutConfig, type DocumentMetadata, type DocumentOrientation, type FrontmatterMetadata, type GeneratedOutputFile, type HeaderFooterItem, type HeaderFooterSlot, MARKFORGE_VERSION, type MarkdownASTNode, type MarkdownInlineSpan, type MarkdownNodeType, type MarkforgeConfig, type MarkforgeFormat, type MarkforgeTheme, type NormalizedHeaderFooter, type NormalizedHeaderFooterZone, type NormalizedMargins, type NormalizedWatermark, Orientation, OutputFormat, PAPER_DIMENSIONS_TWIP, type PageMargins, type PaperSize, PaperSizeEnum, type ParsedMarkdownDocument, type ResolvedDocumentConfig, type ResolvedImage, SYNTAX_COLORS, SyntaxTheme, type SyntaxToken, THEMES, THEME_CORPORATE, THEME_DEFAULT, Theme, type ThemeProps, type WatermarkOptions, WatermarkPosition, buildDocxDocument, buildHtmlDocument, buildPdfDocument, compileMarkdown, defineConfig, escapeHtml, findChromeExecutable, formatServerTimestamp, generateThemeCss, getMarkforgeVersion, getMimeType, highlightCodeToHtml, injectPagedMediaStyles, inlineHtmlImages, loadConfig, compileMarkdown as markforge, normalizeHeaderFooter, normalizeHeaderFooterSlot, normalizeWatermark, parseInlineSpans, parseMarginToTwip, parseMarkdownDocument, renderInlinesToHtml, renderMermaidToPng, replaceDocumentTokens, resolveDocumentConfig, resolveImage, slugify, tokenizeCodeLine };
+export { type BackCoverConfig, type BackCoverPreset, type BackCoverSocial, type CompilationResult, type CoverPageConfig, CoverPagePreset, DEFAULT_CONFIG, type DocumentLayoutConfig, type DocumentMetadata, type DocumentOrientation, type FootnoteDefinition, type FrontmatterMetadata, type GeneratedOutputFile, type HeaderFooterItem, type HeaderFooterSlot, KATEX_INLINE_CSS, MARKFORGE_VERSION, type MarkdownASTNode, type MarkdownInlineSpan, type MarkdownNodeType, type MarkforgeConfig, type MarkforgeFormat, type MarkforgeTheme, type NormalizedBackCover, type NormalizedCoverPage, type NormalizedHeaderFooter, type NormalizedHeaderFooterZone, type NormalizedMargins, type NormalizedNumberHeadings, type NormalizedSecurity, type NormalizedSignatureBlock, type NormalizedSignatureItem, type NormalizedWatermark, type NumberHeadingsConfig, Orientation, OutputFormat, PAPER_DIMENSIONS_TWIP, type PageMargins, type PaperSize, PaperSizeEnum, type ParsedMarkdownDocument, type PdfPermissions, type PreviewServerInstance, type PreviewServerOptions, type ResolvedDocumentConfig, type ResolvedImage, SYNTAX_COLORS, type SecurityConfig, type SignatureAlign, type SignatureBlockConfig, type SignatureItem, type SignatureStyle, SyntaxTheme, type SyntaxToken, THEMES, THEME_CORPORATE, THEME_DEFAULT, Theme, type ThemeProps, type WatermarkOptions, WatermarkPosition, buildDocxDocument, buildHtmlDocument, buildPdfDocument, compileMarkdown, defineConfig, escapeHtml, findChromeExecutable, formatServerTimestamp, generateThemeCss, getMarkforgeVersion, getMimeType, highlightCodeToHtml, injectPagedMediaStyles, inlineHtmlImages, loadConfig, compileMarkdown as markforge, normalizeBackCover, normalizeCoverPage, normalizeHeaderFooter, normalizeHeaderFooterSlot, normalizeNumberHeadings, normalizeSecurity, normalizeSignatures, normalizeWatermark, parseInlineSpans, parseMarginToTwip, parseMarkdownDocument as parseMarkdown, parseMarkdownDocument, renderBackCoverHtml, renderCoverPageHtml, renderInlinesToHtml, renderMathToHtml, renderMermaidToPng, renderNodesToHtml, replaceDocumentTokens, resolveDocumentConfig, resolveImage, slugify, startPreviewServer, tokenizeCodeLine };