jspdf-md-renderer 4.0.0 → 4.1.0

package/README.md

@@ -1,173 +1,83 @@
 # jsPDF Markdown Renderer
 
-A jsPDF utility to render Markdown directly into formatted PDFs with custom designs.
-
-## What's New in v4
-
-- Unified inline layout engine for consistent wrapping/alignment.
-- Safe wrapping for long unbroken tokens (long URLs, long inline code).
-- Heading scale controls (`heading.h1` ... `heading.h6`).
-- Task list support (`- [x]` / `- [ ]`).
-- Header/footer + page numbers.
-- Spacing system (`spacing.*`) and richer style options (`codeBlock`, `blockquote`, `list`, `paragraph`).
+A utility to render Markdown directly into formatted PDFs using `jsPDF`.
 
 [![npm version](https://img.shields.io/npm/v/jspdf-md-renderer.svg)](https://www.npmjs.com/package/jspdf-md-renderer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/npm/dm/jspdf-md-renderer.svg)](https://www.npmjs.com/package/jspdf-md-renderer)
 
-## Table of Contents
+## Highlights
 
-- [Installation](#installation)
-- [Usage](#usage)
-- [Browser Runtime Usage](#browser-runtime-usage)
-- [API](#api)
-- [Examples](#examples)
-- [Contributing](#contributing)
-- [License](#license)
+- Rich markdown support (headings, lists, tables, images, code, blockquotes, links)
+- Configurable typography, spacing, and block styling
+- Header/footer and page-number support
+- Safe inline layout and long-token wrapping
+- Optional security enforcement for untrusted markdown
 
 ## Installation
 
-To install the library, you can use npm:
-
 ```sh
 npm install jspdf-md-renderer
 ```
 
-## Usage
-
-### Basic Example
-
-Here is a basic example of how to use the library to generate a PDF from Markdown content:
+## Quick Start
 
 ```ts
-import { jsPDF } from 'jspdf';
-import { MdTextRender } from 'jspdf-md-renderer';
-
-const mdString = `
-# Main Title
-
-This is a brief introduction paragraph. It sets the tone for the document and introduces the main topic in a concise manner.
-
-## Section 1: Overview
-
-Here is a medium-length paragraph that goes into more detail about the first section. It explains the context, provides background information, and sets up the discussion for the subsections.
-
-## Section 2: Lists and Examples
+import { jsPDF } from 'jspdf'
+import { MdTextRender } from 'jspdf-md-renderer'
 
-This section showcases how to create simple and nested lists.
+const markdown = `
+# Project Report
 
-### Simple List
+This report includes **formatted markdown** content.
 
 - Item 1
 - Item 2
-- Item 3
-
-### Nested List
-
-1. First Level 1
-   - First Level 2
-     - First Level 3
-2. Second Level 1
-   - Second Level 2
-   - Another Second Level 2
-     - Nested deeper
-
-### Mixed List Example
-
-- Topic 1
-  1. Subtopic 1.1
-  2. Subtopic 1.2
-- Topic 2
-  - Subtopic 2.1
-  - Subtopic 2.2
-    1. Nested Subtopic 2.2.1
-    2. Nested Subtopic 2.2.2
-
-### Emphasis and Strong Emphasis
-- *Italic* text using asterisks.
-- _Italic_ text using underscores.
-- **Bold** text using double asterisks.
-- __Bold__ text using double underscores.
-- ***Bold and Italic*** text using triple asterisks.
-- ___Bold and Italic___ text using triple underscores.
-
-`;
-
-const generatePDF = async () => {
-    const doc = new jsPDF({
-        unit: 'mm',
-        format: 'a4',
-        orientation: 'portrait',
-    });
-
-    const options = {
-        cursor: { x: 10, y: 10 },
-        page: {
-            format: 'a4',
-            unit: 'mm',
-            orientation: 'portrait',
-            maxContentWidth: 190,
-            maxContentHeight: 277,
-            lineSpace: 1.5,
-            defaultLineHeightFactor: 1.2,
-            defaultFontSize: 12,
-            defaultTitleFontSize: 14,
-            topmargin: 10,
-            xpading: 10,
-            xmargin: 10,
-            indent: 10,
-        },
-        font: {
-            bold: { name: 'helvetica', style: 'bold' },
-            regular: { name: 'helvetica', style: 'normal' },
-            light: { name: 'helvetica', style: 'light' },
-        },
-        heading: {
-            h1: 24,
-            h2: 20,
-            h3: 17,
-            h4: 15,
-            h5: 13,
-            h6: 12,
-            color: '#1A365D',
-        },
-        spacing: {
-            afterParagraph: 4,
-            afterHeading: 2,
-            afterCodeBlock: 4,
-            betweenListItems: 1,
-        },
-        footer: {
-            showPageNumbers: true,
-            align: 'right',
-        },
-        endCursorYHandler: (y) => {
-            console.log('End cursor Y position:', y);
-        },
-    };
-
-    await MdTextRender(doc, mdString, options);
-    doc.save('example.pdf');
-};
-
-generatePDF();
-```
+`
+
+const doc = new jsPDF({ unit: 'mm', format: 'a4', orientation: 'portrait' })
+
+await MdTextRender(doc, markdown, {
+  cursor: { x: 10, y: 10 },
+  page: {
+    format: 'a4',
+    unit: 'mm',
+    orientation: 'portrait',
+    maxContentWidth: 190,
+    maxContentHeight: 277,
+    lineSpace: 1.5,
+    defaultLineHeightFactor: 1.2,
+    defaultFontSize: 12,
+    defaultTitleFontSize: 14,
+    topmargin: 10,
+    xpading: 10,
+    xmargin: 10,
+    indent: 10,
+  },
+  font: {
+    bold: { name: 'helvetica', style: 'bold' },
+    regular: { name: 'helvetica', style: 'normal' },
+    light: { name: 'helvetica', style: 'light' },
+  },
+  endCursorYHandler: (y) => {
+    console.log('Final Y:', y)
+  },
+})
 
-## Browser Runtime Usage
+doc.save('report.pdf')
+```
 
-### Option 1: Use with your app bundler (Vite/Webpack/Rollup)
+## Browser Usage
 
-Install dependencies and import from modules as usual:
+### Bundler (Vite/Webpack/Rollup)
 
 ```ts
-import { jsPDF } from 'jspdf';
-import autoTable from 'jspdf-autotable';
-import { MdTextRender } from 'jspdf-md-renderer';
+import { jsPDF } from 'jspdf'
+import 'jspdf-autotable'
+import { MdTextRender } from 'jspdf-md-renderer'
 ```
 
-### Option 2: Use directly via script tags (UMD)
-
-Load dependencies first, then load `jspdf-md-renderer` UMD bundle.
+### Script Tag (UMD)
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
@@ -177,127 +87,48 @@ Load dependencies first, then load `jspdf-md-renderer` UMD bundle.
 <script>
   const { jsPDF } = window.jspdf;
   const { MdTextRender } = window.JspdfMdRenderer;
-
-  (async () => {
-    const doc = new jsPDF();
-    await MdTextRender(doc, '# Hello from browser runtime');
-    doc.save('browser-runtime.pdf');
-  })();
 </script>
 ```
 
-> Note: For script-tag usage you must include `marked`, `jspdf`, and `jspdf-autotable` before the renderer bundle.
-
-## API
-
-### `MdTextRender`
-
-Renders parsed markdown text into a jsPDF document.
-
-#### Parameters
-
-- `doc`: The jsPDF document instance.
-- `text`: The markdown content to render.
-- `options`: The render options (fonts, page margins, etc.).
-
-### `MdTextParser`
-
-Parses markdown into tokens and converts to a custom parsed structure.
-
-#### Parameters
-
-- `text`: The markdown content to parse.
-
-#### Returns
-
-- `Promise<ParsedElement[]>`: Parsed markdown elements.
-
-## Supported Markdown Elements
-
-The following Markdown elements are currently supported by `jspdf-md-renderer`:
-
-- **Headings**: `#`, `##`, `###`, etc.
-- **Paragraphs**
-- **Lists**:
-    - Unordered lists: `-`, `*`, `+`
-    - Ordered lists: `1.`, `2.`, `3.`, etc.
-- **Horizontal Rules**: `---`, `***`, `___`
-- **Text Styles**:
-    - Bold: `**bold**` or `__bold__`
-    - Italic: `*italic*` or `_italic_`
-    - Bold Italic: `***bold italic***` or `___bold italic___`
-- **Code Blocks** (fenced and indented):
-    ````markdown
-    ```js
-    console.log('Hello, world!');
-    ```
-    ````
-- **Links**:
-    ```markdown
-    [GitHub](https://github.com)
-    ```
-- **Blockquotes**:
-    ```markdown
-    > This is a blockquote.
-    ```
-- **Images**:
-    ```markdown
-    ![Alt text](https://example.com/image.png)
-    ```
-    Images render at their **intrinsic (original) size** by default and scale down automatically if they exceed the available page width. You can control image dimensions and alignment using an optional attribute block `{...}` after the image syntax:
-
-    **Custom Attributes:**
-    | Attribute | Description | Example |
-    |-----------|-------------|---------|
-    | `width` or `w` | Image width in px | `{width=200}` or `{w=200}` |
-    | `height` or `h` | Image height in px | `{height=150}` or `{h=150}` |
-    | `align` | Alignment: `left`, `center`, `right` | `{align=center}` |
-
-    **Sizing Rules:**
-    - If only `width` is given, height is auto-calculated from aspect ratio
-    - If only `height` is given, width is auto-calculated from aspect ratio
-    - If both are given, the image uses exact dimensions (may distort if ratio differs)
-    - Images that exceed page bounds are always scaled down proportionally
-
-    **Examples:**
-    ```markdown
-    ![photo](https://example.com/photo.png)
-    ![photo](https://example.com/photo.png){width=200}
-    ![photo](https://example.com/photo.png){h=150 align=center}
-    ![photo](https://example.com/photo.png){width=200 height=150 align=right}
-    ```
-
-    **Global Default Alignment:**
-    You can set a default alignment for all images via the `image` option:
-    ```ts
-    const options = {
-        // ...other options
-        image: {
-            defaultAlign: 'center', // 'left' (default) | 'center' | 'right'
-        },
-    };
-    ```
-
-- **Inline Code**:
-    ```markdown
-    This is an `inline code` example.
-    ```
-- **Tables**:
-    ```markdown
-    | Header 1 | Header 2 | Header 3 |
-    | -------- | -------- | -------- |
-    | Row 1    | Data     | Value    |
-    | Row 2    | Data     | Value    |
-    ```
-
-## New Options (v4 quick reference)
+## Supported Markdown
+
+- Headings (`#` to `######`)
+- Paragraphs
+- Ordered/unordered/task lists
+- Links
+- Images (with optional `{width,height,align}` attributes)
+- Tables
+- Code blocks and inline code
+- Blockquotes
+- Horizontal rules
+- Inline styles (bold/italic)
+
+## Key Render Options
 
 ```ts
 const options = {
-  heading: { h1: 26, h2: 22, h3: 18, bottomSpacing: 3 },
-  list: { bulletChar: '• ', indentSize: 8, itemSpacing: 0 },
-  paragraph: { bottomSpacing: 3, color: '#111827' },
-  blockquote: { barColor: '#4A90D9', barWidth: 2, paddingLeft: 6 },
+  heading: {
+    bold: true,
+    h1: 26,
+    h2: 22,
+    h3: 18,
+    bottomSpacing: 3,
+  },
+  list: {
+    bulletChar: '\u2022 ',
+    indentSize: 8,
+    itemSpacing: 0,
+  },
+  paragraph: {
+    bottomSpacing: 3,
+    color: '#111827',
+  },
+  blockquote: {
+    barColor: '#4A90D9',
+    barWidth: 2,
+    paddingLeft: 6,
+    backgroundColor: '#F8FAFC',
+  },
   codeBlock: {
     backgroundColor: '#F6F8FA',
     borderColor: '#E1E4E8',
@@ -317,27 +148,104 @@ const options = {
     afterList: 3,
     afterTable: 3,
   },
-  header: { text: 'My Report', align: 'center', color: '#6b7280', fontSize: 9 },
-  footer: { showPageNumbers: true, align: 'right' },
+  header: {
+    text: 'My Report',
+    align: 'center',
+    color: '#6b7280',
+    fontSize: 9,
+  },
+  footer: {
+    showPageNumbers: true,
+    align: 'right',
+  },
 }
 ```
 
-## Examples
+Behavior notes:
+- Heading size fallback: `heading.hN` -> `page.defaultTitleFontSize`
+- `heading.bold` defaults to `true`
+- List spacing precedence: `spacing.betweenListItems` > `list.itemSpacing`
+- Table width follows `page.maxContentWidth` for consistent block layout
 
-You can explore complete rendered examples in the documentation site:
-- [Resume example](https://jeelgajera.github.io/jspdf-md-renderer/examples/resume)
-- [Invoice example](https://jeelgajera.github.io/jspdf-md-renderer/examples/invoice)
-- [Technical report example](https://jeelgajera.github.io/jspdf-md-renderer/examples/report)
-- [Custom fonts guide](https://jeelgajera.github.io/jspdf-md-renderer/examples/custom-fonts)
+## Security Controls (opt-in)
 
-## Contributing
+Security is disabled by default for backward compatibility.
 
-Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
+```ts
+const options = {
+  // ...other options
+  security: {
+    enabled: true,
+    violationMode: 'skip', // 'skip' | 'throw' | 'placeholder'
+    placeholderText: '[blocked]',
+    placeholderImageText: '[blocked image]',
+
+    // Link controls
+    allowedLinkProtocols: ['https:', 'http:', 'mailto:', 'tel:'],
+    disablePdfLinks: false,
+
+    // Image controls
+    allowRemoteImages: true,
+    allowedImageProtocols: ['https:', 'http:'],
+    allowedImageDomains: ['cdn.example.com'],
+    allowDataUrls: true,
+    allowSvgImages: true,
+
+    // SSRF controls
+    blockLocalhost: true,
+    blockPrivateIPs: true,
+    blockLinkLocalIPs: true,
+    blockMetadataIPs: true,
+
+    // Limits
+    maxMarkdownLength: 500000,
+    maxImageCount: 200,
+    maxImageSizeBytes: 10 * 1024 * 1024,
+    maxNestedDepth: 20,
+    renderTimeoutMs: 30000,
+
+    // Hooks
+    validateUrl: async (url, type) => true,
+    onSecurityViolation: (violation) => console.warn(violation),
+  },
+}
+```
+
+### Security Details
+
+- URL classes:
+  - explicit scheme (`https://...`) -> full protocol/domain/IP checks
+  - protocol-relative (`//host/path`) -> treated as external absolute URL
+  - relative path (`/a`, `./a`, `?q=1`, `#id`) -> allowed by default unless custom validator rejects
+- `allowedImageDomains` semantics:
+  - `undefined` -> allow all domains
+  - `[]` -> deny all domains
+- `maxImageSizeBytes` uses decoded bytes for data URLs
+- `SecurityViolationError` is exported for throw-mode handling
+
+Browser caveat:
+- IP-level SSRF checks are best-effort in browser runtime due to DNS API limitations.
+- For strict SSRF policy, fetch remote images through a trusted server-side proxy.
+
+## API Exports
 
-## Support
+- `MdTextRender`
+- `MdTextParser`
+- `SecurityViolationError`
+- `validateOptions`
+- Types: `RenderOption`, `RenderSecurityOptions`, `SecurityViolation`, `ViolationMode`, and others
+
+## Examples and Docs
+
+- Docs site: [https://jeelgajera.github.io/jspdf-md-renderer/](https://jeelgajera.github.io/jspdf-md-renderer/)
+- Resume example: [https://jeelgajera.github.io/jspdf-md-renderer/examples/resume](https://jeelgajera.github.io/jspdf-md-renderer/examples/resume)
+- Invoice example: [https://jeelgajera.github.io/jspdf-md-renderer/examples/invoice](https://jeelgajera.github.io/jspdf-md-renderer/examples/invoice)
+- Technical report example: [https://jeelgajera.github.io/jspdf-md-renderer/examples/report](https://jeelgajera.github.io/jspdf-md-renderer/examples/report)
+
+## Contributing
 
-If you find this library useful, please consider giving it a ⭐ on GitHub! It helps others find the project and motivates continued development.
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+MIT. See [LICENSE](LICENSE).

package/dist/index.d.mts

@@ -27,6 +27,94 @@
 import { UserOptions } from "jspdf-autotable";
 import jsPDF, { jsPDFOptions } from "jspdf";
 
+//#region src/types/security.d.ts
+type ViolationMode = 'skip' | 'throw' | 'placeholder';
+type ViolationAction = 'skip' | 'placeholder';
+type SecurityViolationType = 'link' | 'image' | 'markdown' | 'render';
+type SecurityViolationCode = 'MARKDOWN_TOO_LARGE' | 'MAX_NESTED_DEPTH_EXCEEDED' | 'MAX_IMAGE_COUNT_EXCEEDED' | 'RENDER_TIMEOUT_EXCEEDED' | 'INVALID_URL' | 'LINK_PROTOCOL_BLOCKED' | 'IMAGE_PROTOCOL_BLOCKED' | 'IMAGE_DOMAIN_BLOCKED' | 'DATA_URL_BLOCKED' | 'SVG_BLOCKED' | 'LOCALHOST_BLOCKED' | 'PRIVATE_IP_BLOCKED' | 'LINK_LOCAL_IP_BLOCKED' | 'METADATA_IP_BLOCKED' | 'IMAGE_SIZE_EXCEEDED' | 'CUSTOM_VALIDATOR_BLOCKED';
+interface SecurityViolation {
+  /** Machine-readable violation code. */
+  code: SecurityViolationCode;
+  /** High-level category of the violating input. */
+  type: SecurityViolationType;
+  /** Human-readable explanation of the violation. */
+  message: string;
+  /** Raw value that triggered the violation (URL, length, etc.). */
+  value?: string;
+  /** Optional execution context to help debugging (e.g. 'markdown-link'). */
+  context?: string;
+  /** ISO timestamp when the violation was recorded. */
+  timestamp: string;
+}
+declare class SecurityViolationError extends Error {
+  /** Structured violation payload used to construct this error. */
+  readonly violation: SecurityViolation;
+  constructor(violation: SecurityViolation);
+}
+interface RenderSecurityOptions {
+  /** Enables all built-in security checks. Default: false (opt-in). */
+  enabled?: boolean;
+  /** Allowed URI protocols for markdown links. Example: ['https:', 'mailto:']. */
+  allowedLinkProtocols?: string[];
+  /** If true, link text is rendered but PDF link actions are disabled. */
+  disablePdfLinks?: boolean;
+  /** Whether remote image fetching is allowed (http/https). */
+  allowRemoteImages?: boolean;
+  /** Allowed protocols for image URLs. Example: ['https:', 'http:']. */
+  allowedImageProtocols?: string[];
+  /**
+   * Optional domain allowlist for remote image hosts.
+   * - `undefined` (default): all domains are allowed.
+   * - `[]` (empty array): no domains are allowed.
+   * - `['example.com']`: only `example.com` and its subdomains are allowed.
+   */
+  allowedImageDomains?: string[];
+  /** Whether inline data: image URLs are allowed. */
+  allowDataUrls?: boolean;
+  /** Whether SVG images are allowed. */
+  allowSvgImages?: boolean;
+  /** Blocks localhost image/link destinations when true. */
+  blockLocalhost?: boolean;
+  /**
+   * Blocks private IPv4 ranges (10/8, 172.16/12, 192.168/16) when true.
+   * NOTE: In browser environments, IP-based checks cannot be enforced due to
+   * lack of DNS resolution APIs. Use a trusted server-side proxy for strict enforcement.
+   */
+  blockPrivateIPs?: boolean;
+  /**
+   * Blocks link-local IPv4 ranges (169.254/16) when true.
+   * NOTE: In browser environments, IP-based checks cannot be enforced due to
+   * lack of DNS resolution APIs. Use a trusted server-side proxy for strict enforcement.
+   */
+  blockLinkLocalIPs?: boolean;
+  /**
+   * Blocks known cloud metadata endpoints when true.
+   * NOTE: In browser environments, IP-based checks cannot be enforced due to
+   * lack of DNS resolution APIs. Use a trusted server-side proxy for strict enforcement.
+   */
+  blockMetadataIPs?: boolean;
+  /** Maximum markdown input length in characters. */
+  maxMarkdownLength?: number;
+  /** Maximum number of markdown images allowed per render. */
+  maxImageCount?: number;
+  /** Maximum image payload size in bytes (fetched blob size or decoded data URL bytes). */
+  maxImageSizeBytes?: number;
+  /** Maximum supported markdown nesting depth. */
+  maxNestedDepth?: number;
+  /** Maximum total render time in milliseconds. */
+  renderTimeoutMs?: number;
+  /** Action taken when a violation occurs. */
+  violationMode?: ViolationMode;
+  /** Placeholder text used for blocked text-like content in placeholder mode. */
+  placeholderText?: string;
+  /** Placeholder text used for blocked images in placeholder mode. */
+  placeholderImageText?: string;
+  /** Optional custom URL validator. Return false to reject the URL. */
+  validateUrl?: (url: URL, type: 'link' | 'image') => boolean | Promise<boolean>;
+  /** Callback fired for every security violation, regardless of mode. */
+  onSecurityViolation?: (violation: SecurityViolation) => void;
+}
+//#endregion
 //#region src/types/renderOption.d.ts
 type RenderOption = {
   cursor: {
@@ -52,10 +140,13 @@ type RenderOption = {
     bold: FontItem;
     regular: FontItem;
     light: FontItem;
+    italic?: FontItem;
+    boldItalic?: FontItem;
     code?: FontItem;
   };
   heading?: {
-    /** Font size for h1-h6. Values are absolute (e.g. 22, 20, 18, 16, 14, 12). */h1?: number;
+    /** Whether headings should use bold font. Default: true */bold?: boolean; /** Font size for h1-h6. Values are absolute (e.g. 22, 20, 18, 16, 14, 12). */
+    h1?: number;
     h2?: number;
     h3?: number;
     h4?: number;
@@ -72,7 +163,7 @@ type RenderOption = {
   };
   list?: {
     /** Bullet character for unordered lists. Default: '\u2022 ' */bulletChar?: string; /** Extra indent per nesting level in doc units. Default: uses page.indent */
-    indentSize?: number; /** Vertical space between list items. Default: 0 */
+    indentSize?: number; /** Vertical space between list items. Used when spacing.betweenListItems is not provided. */
     itemSpacing?: number;
   };
   paragraph?: {
@@ -140,6 +231,7 @@ type RenderOption = {
   };
   pageBreakHandler?: (doc: jsPDF) => void;
   endCursorYHandler: (y: number) => void;
+  security?: RenderSecurityOptions;
 };
 type Cursor = {
   x: number;
@@ -332,4 +424,4 @@ declare enum MdTokenType {
 //#region src/utils/options-validation.d.ts
 declare const validateOptions: (options: RenderOption) => RenderOption;
 //#endregion
-export { MdTextParser, MdTextRender, MdTokenType, type ParsedElement, type RenderOption, type StyledLine, type StyledWordInfo, type TextStyle, renderInlineContent, renderPlainText, validateOptions };
+export { MdTextParser, MdTextRender, MdTokenType, type ParsedElement, type RenderOption, type RenderSecurityOptions, type SecurityViolation, type SecurityViolationCode, SecurityViolationError, type StyledLine, type StyledWordInfo, type TextStyle, type ViolationAction, type ViolationMode, renderInlineContent, renderPlainText, validateOptions };