@masumdev/markforge 0.3.0 → 0.4.1

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import * as http from 'node:http';
+
 declare enum OutputFormat {
     DOCX = "docx",
     PDF = "pdf",
@@ -151,6 +153,243 @@ 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;
+    backgroundColor?: string;
+    /**
+     * Custom typography colors.
+     */
+    textColor?: string;
+    titleColor?: string;
+    subtitleColor?: string;
+    accentColor?: string;
+    /**
+     * Contact details (for covers that render organization cards).
+     */
+    address?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    social?: BackCoverSocial;
+    copyright?: 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;
+    /**
+     * Author / signatory shown on the closing page.
+     */
+    author?: string | string[];
+    /**
+     * Organization or company name (falls back to document company).
+     */
+    company?: string;
+    /**
+     * Document version shown on the back cover.
+     */
+    version?: string;
+    /**
+     * Date shown on the back cover.
+     */
+    date?: string | boolean;
+    /**
+     * 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;
+    /**
+     * Custom footer text at the bottom.
+     */
+    footerText?: 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;
+    backgroundColor?: string;
+    /**
+     * Custom typography colors.
+     */
+    textColor?: string;
+    titleColor?: string;
+    subtitleColor?: string;
+    accentColor?: 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,7 +401,8 @@ 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";
@@ -288,6 +528,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"
@@ -372,9 +634,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;
@@ -383,6 +645,7 @@ interface MarkdownInlineSpan {
     height?: number | string;
     children?: MarkdownInlineSpan[];
     style?: Record<string, string>;
+    footnoteId?: string;
 }
 interface MarkdownASTNode {
     type: MarkdownNodeType;
@@ -399,6 +662,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;
@@ -410,15 +681,24 @@ 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[];
 /**
  * Extracts slug from heading text for TOC & anchor links.
  */
 declare function slugify(text: string): string;
+/**
+ * Applies hierarchical numbering to headings (e.g. "1.", "1.1.", "1.1.1.").
+ */
+declare function applyHeadingNumbering(nodes: MarkdownASTNode[], tocEntries: {
+    id: string;
+    text: string;
+    level: number;
+}[], options: NumberHeadingsOptions): void;
 /**
  * Parses raw markdown string into rich structured AST nodes.
  */
@@ -433,124 +713,6 @@ declare function parseMarginToTwip(margin?: string | number, defaultTwip?: numbe
  */
 declare function buildDocxDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<Buffer>;
 
-/**
- * Escapes HTML characters safely.
- */
-declare function escapeHtml(str: string): string;
-/**
- * Converts Markdown inline spans to HTML markup.
- */
-declare function renderInlinesToHtml(spans?: MarkdownInlineSpan[], baseDir?: string): Promise<string>;
-/**
- * Builds standalone self-contained HTML from a parsed Markdown document.
- */
-declare function buildHtmlDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<string>;
-
-/**
- * Finds available Chrome or Chromium binary for headless PDF rendering.
- */
-declare function findChromeExecutable(): string | null;
-/**
- * Injects CSS Paged Media styles into HTML for print & PDF formatting.
- */
-declare function injectPagedMediaStyles(html: string, config: MarkforgeConfig, metadata?: Record<string, unknown>): string;
-/**
- * Builds a true binary PDF document from parsed Markdown.
- */
-declare function buildPdfDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<Buffer>;
-
-interface ResolvedImage {
-    src: string;
-    buffer: Buffer;
-    mimeType: string;
-    width?: number;
-    height?: number;
-    dataUri: string;
-    isSvg: boolean;
-}
-/**
- * Infers MIME type from file extension or data URI header.
- */
-declare function getMimeType(filePathOrUrl: string): string;
-/**
- * Resolves an image source (relative path, remote URL, or base64 data URI) into a binary buffer.
- */
-declare function resolveImage(src: string, baseDir?: string): Promise<ResolvedImage | null>;
-/**
- * Inlines all image sources in an HTML string with Base64 data URIs.
- */
-declare function inlineHtmlImages(html: string, baseDir?: string): Promise<string>;
-
-/**
- * MarkForge Syntax Highlighter Engine
- * Provides tokenizer & styling for Markdown code blocks across DOCX, HTML, and PDF.
- */
-interface SyntaxToken {
-    text: string;
-    type: "keyword" | "string" | "comment" | "number" | "boolean" | "function" | "type" | "operator" | "punctuation" | "plain";
-    colorHex: string;
-    bold?: boolean;
-    italic?: boolean;
-}
-declare const SYNTAX_COLORS: {
-    keyword: string;
-    string: string;
-    comment: string;
-    number: string;
-    boolean: string;
-    function: string;
-    type: string;
-    operator: string;
-    punctuation: string;
-    plain: string;
-};
-declare function tokenizeCodeLine(line: string, lang?: string, theme?: string): SyntaxToken[];
-/**
- * Converts a code snippet to syntax-highlighted HTML with colored span tokens.
- */
-declare function highlightCodeToHtml(code: string, lang?: string, theme?: string): string;
-
-/**
- * Renders Mermaid diagram definition into an SVG/PNG buffer for DOCX and HTML embedding.
- */
-declare function renderMermaidToPng(mermaidCode: string, _baseDir?: string): Promise<Buffer | null>;
-
-/**
- * Flagship corporate theme — full design system with Blu-by-BCA-Digital cyan palette.
- */
-declare const THEME_CORPORATE = "\n:root {\n  --mf-bg: #ffffff;\n  --mf-text: #0f172a;\n  --mf-text-muted: #64748b;\n  --mf-primary: #33CDCF;\n  --mf-primary-dark: #009DA0;\n  --mf-primary-light: #ECFDFD;\n  --mf-border: #e2e8f0;\n  --mf-card-bg: #f8fafc;\n  --mf-code-bg: #0f172a;\n  --mf-code-text: #f8fafc;\n  --mf-font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n  --mf-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n}\nbody { background-color: var(--mf-bg); color: var(--mf-text); font-family: var(--mf-font-family); font-size: 15px; line-height: 1.65; margin: 0; padding: 2.5rem; }\n.document-container { max-width: 860px; margin: 0 auto; position: relative; z-index: 1; }\nh1, h2, h3, h4, h5, h6 { color: var(--mf-text); font-weight: 700; margin-top: 1.8rem; margin-bottom: 0.8rem; line-height: 1.25; }\nh1 { font-size: 2.2rem; border-bottom: 2px solid var(--mf-primary); padding-bottom: 0.5rem; }\nh2 { font-size: 1.6rem; color: var(--mf-primary-dark); border-bottom: 1px solid #CCFBF1; padding-bottom: 0.4rem; }\nh3 { font-size: 1.3rem; }\nh4 { font-size: 1.1rem; }\np  { margin: 0.8rem 0; }\n";
-declare const THEME_DEFAULT = "\n:root {\n  --mf-bg: #ffffff;\n  --mf-text: #0f172a;\n  --mf-text-muted: #64748b;\n  --mf-primary: #33CDCF;\n  --mf-primary-dark: #009DA0;\n  --mf-primary-light: #ECFDFD;\n  --mf-border: #e2e8f0;\n  --mf-card-bg: #f8fafc;\n  --mf-code-bg: #0f172a;\n  --mf-code-text: #f8fafc;\n  --mf-font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n  --mf-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n}\nbody { background-color: var(--mf-bg); color: var(--mf-text); font-family: var(--mf-font-family); font-size: 15px; line-height: 1.65; margin: 0; padding: 2.5rem; }\n.document-container { max-width: 860px; margin: 0 auto; position: relative; z-index: 1; }\nh1, h2, h3, h4, h5, h6 { color: var(--mf-text); font-weight: 700; margin-top: 1.8rem; margin-bottom: 0.8rem; line-height: 1.25; }\nh1 { font-size: 2.2rem; border-bottom: 2px solid var(--mf-primary); padding-bottom: 0.5rem; }\nh2 { font-size: 1.6rem; color: var(--mf-primary-dark); border-bottom: 1px solid #CCFBF1; padding-bottom: 0.4rem; }\nh3 { font-size: 1.3rem; }\nh4 { font-size: 1.1rem; }\np  { margin: 0.8rem 0; }\n";
-declare const THEMES: Record<string, string>;
-
-/**
- * Resolves theme CSS based on preset name or custom ThemeProps object.
- */
-declare function generateThemeCss(theme?: MarkforgeTheme): string;
-
-/**
- * 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" | "signatures">> & {
-    outputDir?: string;
-    css?: string | string[];
-    margins?: MarkforgeConfig["margins"];
-    header?: MarkforgeConfig["header"];
-    footer?: MarkforgeConfig["footer"];
-    signatures?: MarkforgeConfig["signatures"];
-    watermark?: string;
-    metadata?: MarkforgeConfig["metadata"];
-    syntaxTheme?: string;
-};
-/**
- * Resolves and loads markforge configuration from disk.
- */
-declare function loadConfig(customPath?: string, startDir?: string): Promise<{
-    config: MarkforgeConfig;
-    configPath: string | null;
-}>;
-
 /**
  * Standard paper dimensions in Word Twips (1/20th of a point, 1440 twips = 1 inch).
  */
@@ -613,6 +775,81 @@ interface NormalizedSignatureBlock {
     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;
+    backgroundColor?: string;
+    textColor?: string;
+    titleColor?: string;
+    subtitleColor?: string;
+    accentColor?: string;
+    footerText?: string;
+    address?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    social?: Record<string, string>;
+    copyright?: string;
+}
+interface NormalizedBackCover {
+    enabled: boolean;
+    preset: "modern" | "corporate" | "minimal" | "contact-card";
+    title: string;
+    subtitle?: string;
+    author?: string;
+    company?: string;
+    version?: string;
+    date?: string;
+    address?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    social?: Record<string, string>;
+    copyright?: string;
+    footerText?: string;
+    badge?: string;
+    badgeColor?: string;
+    badgeTextColor?: string;
+    logo?: string;
+    logoWidth?: number | string;
+    bgGradient?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    titleColor?: string;
+    subtitleColor?: string;
+    accentColor?: 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;
@@ -634,26 +871,24 @@ interface ResolvedDocumentConfig {
     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.
+ * Replaces dynamic variables ({title}, {subtitle}, {author}, {version}, {date}, {company}, {year}, and any custom metadata keys) in text templates.
  */
-declare function replaceDocumentTokens(template: string | undefined, meta: {
-    title?: string;
-    subtitle?: string;
-    author?: string;
-    version?: string;
-    date?: string;
-    company?: string;
-}): string;
+declare function replaceDocumentTokens(template?: string, meta?: Record<string, unknown>): string;
 /**
- * Normalizes watermark configuration into a consistent structured object.
+ * Normalizes watermark configuration into a consistent structured object with dynamic token replacement.
  */
-declare function normalizeWatermark(rawWatermark?: string | WatermarkOptions | false): NormalizedWatermark | undefined;
+declare function normalizeWatermark(rawWatermark?: string | WatermarkOptions | false, tokens?: Record<string, unknown>): NormalizedWatermark | undefined;
 /**
  * Normalizes an individual left, center, or right header/footer zone slot.
  */
@@ -680,6 +915,22 @@ declare function normalizeHeaderFooter(raw: HeaderFooterItem | undefined, meta:
  * 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?: Record<string, unknown>): NormalizedCoverPage | undefined;
+/**
+ * Normalizes Back Cover / Closing Page configuration with token replacement.
+ */
+declare function normalizeBackCover(rawBack?: boolean | BackCoverConfig | Record<string, unknown>, tokenCtx?: Record<string, unknown>): 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
@@ -687,8 +938,175 @@ declare function normalizeSignatures(raw?: SignatureBlockConfig | SignatureItem[
 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.
+ * Escapes HTML characters safely.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Renders inline Markdown spans (bold, italic, links, images, footnotes, math, etc.) to HTML with token replacement.
+ */
+declare function renderInlinesToHtml(spans?: MarkdownInlineSpan[], baseDir?: string, tokens?: Record<string, unknown>): Promise<string>;
+/**
+ * Renders an AST node array to HTML.
+ */
+declare function renderNodesToHtml(nodes: MarkdownASTNode[], resolved: ResolvedDocumentConfig, baseDir?: string, tokens?: Record<string, unknown>): 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.
+ */
+declare function buildHtmlDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<string>;
+
+/**
+ * Finds available Chrome or Chromium binary for headless PDF rendering.
+ */
+declare function findChromeExecutable(): string | null;
+/**
+ * Injects CSS Paged Media styles into HTML for print & PDF formatting.
+ */
+declare function injectPagedMediaStyles(html: string, config: MarkforgeConfig, metadata?: Record<string, unknown>): string;
+/**
+ * Builds a true binary PDF document from parsed Markdown.
+ */
+declare function buildPdfDocument(doc: ParsedMarkdownDocument, config: MarkforgeConfig, baseDir?: string): Promise<Buffer>;
+
+interface ResolvedImage {
+    src: string;
+    buffer: Buffer;
+    mimeType: string;
+    width?: number;
+    height?: number;
+    dataUri: string;
+    isSvg: boolean;
+}
+/**
+ * Infers MIME type from file extension or data URI header.
+ */
+declare function getMimeType(filePathOrUrl: string): string;
+/**
+ * Resolves an image source (relative path, remote URL, or base64 data URI) into a binary buffer.
+ */
+declare function resolveImage(src: string, baseDir?: string): Promise<ResolvedImage | null>;
+/**
+ * Inlines all image sources in an HTML string with Base64 data URIs.
+ */
+declare function inlineHtmlImages(html: string, baseDir?: string): Promise<string>;
+
+/**
+ * MarkForge Syntax Highlighter Engine
+ * Provides tokenizer & styling for Markdown code blocks across DOCX, HTML, and PDF.
+ */
+interface SyntaxToken {
+    text: string;
+    type: "keyword" | "string" | "comment" | "number" | "boolean" | "function" | "type" | "operator" | "punctuation" | "plain";
+    colorHex: string;
+    bold?: boolean;
+    italic?: boolean;
+}
+declare const SYNTAX_COLORS: {
+    keyword: string;
+    string: string;
+    comment: string;
+    number: string;
+    boolean: string;
+    function: string;
+    type: string;
+    operator: string;
+    punctuation: string;
+    plain: string;
+};
+declare function tokenizeCodeLine(line: string, lang?: string, theme?: string): SyntaxToken[];
+/**
+ * Converts a code snippet to syntax-highlighted HTML with colored span tokens.
+ */
+declare function highlightCodeToHtml(code: string, lang?: string, theme?: string): string;
+
+/**
+ * Renders Mermaid diagram definition into an SVG/PNG buffer for DOCX and HTML embedding.
+ */
+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.
+ */
+declare const THEME_CORPORATE = "\n:root {\n  --mf-bg: #ffffff;\n  --mf-text: #0f172a;\n  --mf-text-muted: #64748b;\n  --mf-primary: #33CDCF;\n  --mf-primary-dark: #009DA0;\n  --mf-primary-light: #ECFDFD;\n  --mf-border: #e2e8f0;\n  --mf-card-bg: #f8fafc;\n  --mf-code-bg: #0f172a;\n  --mf-code-text: #f8fafc;\n  --mf-font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n  --mf-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n}\nbody { background-color: var(--mf-bg); color: var(--mf-text); font-family: var(--mf-font-family); font-size: 15px; line-height: 1.65; margin: 0; padding: 2.5rem; }\n.document-container { max-width: 860px; margin: 0 auto; position: relative; z-index: 1; }\nh1, h2, h3, h4, h5, h6 { color: var(--mf-primary-dark); font-weight: 700; margin-top: 1.8rem; margin-bottom: 0.8rem; line-height: 1.25; }\nh1 { font-size: 2.2rem; color: var(--mf-primary-dark); border-bottom: 2.5px solid var(--mf-primary); padding-bottom: 0.5rem; }\nh2 { font-size: 1.6rem; color: var(--mf-primary-dark); border-bottom: 1px solid #CCFBF1; padding-bottom: 0.4rem; }\nh3 { font-size: 1.3rem; color: var(--mf-primary-dark); }\nh4 { font-size: 1.1rem; color: var(--mf-primary-dark); }\nh5 { font-size: 1.0rem; color: var(--mf-primary-dark); }\nh6 { font-size: 0.9rem; color: var(--mf-primary-dark); }\np  { margin: 0.8rem 0; }\n";
+declare const THEME_DEFAULT = "\n:root {\n  --mf-bg: #ffffff;\n  --mf-text: #0f172a;\n  --mf-text-muted: #64748b;\n  --mf-primary: #33CDCF;\n  --mf-primary-dark: #009DA0;\n  --mf-primary-light: #ECFDFD;\n  --mf-border: #e2e8f0;\n  --mf-card-bg: #f8fafc;\n  --mf-code-bg: #0f172a;\n  --mf-code-text: #f8fafc;\n  --mf-font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n  --mf-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n}\nbody { background-color: var(--mf-bg); color: var(--mf-text); font-family: var(--mf-font-family); font-size: 15px; line-height: 1.65; margin: 0; padding: 2.5rem; }\n.document-container { max-width: 860px; margin: 0 auto; position: relative; z-index: 1; }\nh1, h2, h3, h4, h5, h6 { color: var(--mf-primary-dark); font-weight: 700; margin-top: 1.8rem; margin-bottom: 0.8rem; line-height: 1.25; }\nh1 { font-size: 2.2rem; color: var(--mf-primary-dark); border-bottom: 2.5px solid var(--mf-primary); padding-bottom: 0.5rem; }\nh2 { font-size: 1.6rem; color: var(--mf-primary-dark); border-bottom: 1px solid #CCFBF1; padding-bottom: 0.4rem; }\nh3 { font-size: 1.3rem; color: var(--mf-primary-dark); }\nh4 { font-size: 1.1rem; color: var(--mf-primary-dark); }\nh5 { font-size: 1.0rem; color: var(--mf-primary-dark); }\nh6 { font-size: 0.9rem; color: var(--mf-primary-dark); }\np  { margin: 0.8rem 0; }\n";
+declare const THEMES: Record<string, string>;
+
+/**
+ * Resolves theme CSS based on preset name or custom ThemeProps object.
+ */
+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" | "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;
+};
+/**
+ * Resolves and loads markforge configuration from disk.
+ */
+declare function loadConfig(customPath?: string, startDir?: string): Promise<{
+    config: MarkforgeConfig;
+    configPath: string | null;
+}>;
+
+/**
+ * Dynamically resolved version — reads strictly from the nearest package.json at runtime.
  */
 declare const MARKFORGE_VERSION: string;
 /**
@@ -696,4 +1114,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 NormalizedSignatureBlock, type NormalizedSignatureItem, type NormalizedWatermark, Orientation, OutputFormat, PAPER_DIMENSIONS_TWIP, type PageMargins, type PaperSize, PaperSizeEnum, type ParsedMarkdownDocument, type ResolvedDocumentConfig, type ResolvedImage, SYNTAX_COLORS, 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, normalizeHeaderFooter, normalizeHeaderFooterSlot, normalizeSignatures, 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, applyHeadingNumbering, 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 };