html-native-pptx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davin Surya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# html-native-pptx
+
+Convert HTML/CSS layouts into native, fully-editable PowerPoint (`.pptx`) presentations via OpenXML DrawingML.
+
+## Overview
+
+Unlike screenshot-based or wrapper libraries, `html-native-pptx` leverages headless Chromium to resolve modern CSS (Flexbox, CSS Grid, custom fonts, rounded corners), constructs a strongly-typed Abstract Syntax Tree (IR), and compiles directly into clean OpenXML PresentationML.
+
+- **Fully Editable:** Texts remain real PowerPoint text runs, shapes remain vector shapes.
+- **Accurate CSS:** Flexbox, Grid, absolute positions, padding, and borders are resolved natively by the browser engine.
+- **High Performance:** Lightweight, zero external PowerPoint runtime dependencies (no LibreOffice required).
+
+## Key Features
+
+- **Fully Editable & Native:** Output contains real PowerPoint shapes and text runs with authentic typography, alignments, and colors—never rasterized screenshots.
+- **Accurate CSS Engine:** Headless Chromium accurately evaluates Flexbox, CSS Grid, absolute positioning, borders, and rounded corners.
+- **Multi-Slide Harvesting:** Split presentation decks across multiple slides seamlessly via `slideSelector` (e.g. `.slide`).
+- **Portable Custom Font Embedding:** Automatically parses `@font-face` rules or accepts custom `.ttf`/`.otf` files, converts them to Microsoft EOT (`.fntdata`), and embeds them directly inside the `.pptx` container so custom fonts render identically across all computers without requiring local OS installation!
+- **Pure Node.js & Zero Office Dependencies:** Generates compliant OpenXML PresentationML archives directly with JSZip. No LibreOffice or MS Office installation required on the server.
+
+## Installation
+
+```bash
+npm install html-native-pptx
+```
+
+## Quick Start
+
+### Basic HTML to PPTX Conversion
+
+```ts
+import * as fs from 'node:fs/promises';
+import { convertHtmlToPptx } from 'html-native-pptx';
+
+const html = `
+  <div style="width: 100vw; height: 100vh; background: #0f172a; display: flex; flex-direction: column; justify-content: center; align-items: center; color: white; font-family: sans-serif;">
+    <h1 style="font-size: 48px; margin-bottom: 16px;">Hello from HTML</h1>
+    <p style="font-size: 24px; color: #94a3b8;">Rendered as native vector OpenXML PowerPoint shapes!</p>
+  </div>
+`;
+
+const pptxBuffer = await convertHtmlToPptx(html, {
+  aspect: '16:9',
+  viewport: { width: 1920, height: 1080 },
+});
+
+await fs.writeFile('presentation.pptx', pptxBuffer);
+```
+
+### Multi-Slide Presentation Deck with Embedded Custom Fonts
+
+```ts
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { convertHtmlToPptx } from 'html-native-pptx';
+
+const html = await fs.readFile('curatorial-deck.html', 'utf-8');
+
+const pptxBuffer = await convertHtmlToPptx(html, {
+  slideSelector: '.slide',        // Target each slide container
+  aspect: '16:9',
+  basePath: './fonts',           // Auto-resolve @font-face local font files
+  autoEmbedFonts: true,          // Automatically embed custom fonts into PPTX
+});
+
+await fs.writeFile('curatorial-deck.pptx', pptxBuffer);
+```
+
+### Explicit Font Embedding
+
+You can also pass font files or buffers directly:
+
+```ts
+const pptxBuffer = await convertHtmlToPptx(html, {
+  slideSelector: '.slide',
+  fonts: [
+    {
+      typeface: 'Telkomsel Batik Sans',
+      src: './fonts/Telkomsel-Batik-Sans-Reconstructed.ttf',
+    },
+  ],
+});
+```
+
+## Pipeline Architecture
+
+```
+[ HTML / CSS String or URL ]
+             │
+             ▼
+   Phase 1: Headless DOM Harvester (Puppeteer)
+   - Evaluates computed styles, bounding rects, and @font-face rules
+             │
+             ▼
+   Phase 2: Intermediate Representation (IR Normalizer)
+   - Normalizes coordinates into Inches/EMU and parses typography
+             │
+             ▼
+   Phase 3: OpenXML PresentationML Compiler (JSZip)
+   - Injects embedded fonts (.fntdata), layouts, themes, and DrawingML trees
+             │
+             ▼
+      [ Output .pptx Buffer ]
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Typecheck
+npm run typecheck
+
+# Run test suites
+npm test
+
+# Build dual ESM / CJS bundle
+npm run build
+```
+
+## License
+
+MIT © Davin Surya

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+import { Browser } from 'puppeteer';
+
+/**
+ * Intermediate Representation (IR) AST for html-native-pptx.
+ * Decouples the DOM crawler (Harvester) from the PresentationML generator (Compiler).
+ */
+declare const UNITS: {
+    readonly DPI: 96;
+    readonly PT_PER_INCH: 72;
+    readonly EMU_PER_INCH: 914400;
+    readonly SLIDE_16_9_WIDTH_INCHES: 13.333333;
+    readonly SLIDE_16_9_HEIGHT_INCHES: 7.5;
+    readonly SLIDE_16_9_WIDTH_EMU: 12192000;
+    readonly SLIDE_16_9_HEIGHT_EMU: 6858000;
+    readonly SLIDE_4_3_WIDTH_INCHES: 10;
+    readonly SLIDE_4_3_HEIGHT_INCHES: 7.5;
+    readonly SLIDE_4_3_WIDTH_EMU: 9144000;
+    readonly SLIDE_4_3_HEIGHT_EMU: 6858000;
+};
+type ElementType = 'container' | 'text' | 'image' | 'table';
+type TextAlign = 'left' | 'center' | 'right' | 'justify';
+/**
+ * Normalized bounding box in Inches.
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Visual styling for rectangular containers and shapes.
+ */
+interface ShapeStyle {
+    fillColor?: string;
+    fillOpacity?: number;
+    borderColor?: string;
+    borderWidth?: number;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    radius?: number;
+    shadow?: {
+        color: string;
+        blur: number;
+        offsetX: number;
+        offsetY: number;
+        opacity?: number;
+    };
+}
+/**
+ * Individual formatted text run inside a paragraph (maps to OpenXML <a:r>).
+ */
+interface TextRun {
+    content: string;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+/**
+ * Paragraph containing one or more formatted text runs (maps to OpenXML <a:p>).
+ */
+interface ParagraphIR {
+    align?: TextAlign;
+    lineHeight?: number;
+    spaceBefore?: number;
+    spaceAfter?: number;
+    runs: TextRun[];
+}
+/**
+ * Flat text style convenience interface (for simple, single-style text elements).
+ */
+interface TextStyle {
+    fontFamily: string;
+    fontSize: number;
+    color: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    align?: TextAlign;
+}
+/**
+ * Primary Abstract Syntax Tree (AST) node.
+ */
+interface IRNode {
+    id?: string | number;
+    name?: string;
+    type: ElementType;
+    box: BoundingBox;
+    zIndex?: number;
+    shapeStyle?: ShapeStyle;
+    content?: string;
+    textStyle?: TextStyle;
+    paragraphs?: ParagraphIR[];
+    children?: IRNode[];
+}
+/**
+ * Embedded font IR representing a portable font stream for OpenXML (.fntdata).
+ */
+interface EmbeddedFontIR {
+    typeface: string;
+    fntData: Buffer;
+}
+/**
+ * Complete Intermediate Representation for a single slide.
+ */
+interface SlideIR {
+    width: number;
+    height: number;
+    backgroundColor?: string;
+    elements: IRNode[];
+    fonts?: EmbeddedFontIR[];
+}
+/**
+ * Multi-slide presentation IR container with global presentation metadata.
+ */
+interface PresentationIR {
+    slides: SlideIR[];
+    fonts?: EmbeddedFontIR[];
+}
+
+type SlideAspect = '16:9' | '4:3';
+interface ViewportOptions {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+interface EmbeddedFontOption {
+    /**
+     * Font family / typeface name (e.g. "Telkomsel Batik Sans").
+     */
+    typeface: string;
+    /**
+     * Source font file path (.ttf, .otf, .eot, .fntdata), HTTP(S) URL, data URI, or raw Buffer.
+     */
+    src: string | Buffer;
+}
+interface ConvertOptions {
+    /**
+     * Presentation aspect ratio. Defaults to '16:9'.
+     */
+    aspect?: SlideAspect;
+    /**
+     * Browser viewport dimensions for headless layout resolution.
+     * Defaults to 1920x1080 for 16:9, or 1024x768 for 4:3.
+     */
+    viewport?: ViewportOptions;
+    /**
+     * CSS selector for the root container element to capture as slide.
+     * Defaults to 'body'.
+     */
+    selector?: string;
+    /**
+     * Optional CSS selector to detect and extract multi-slide presentations.
+     * e.g., '.slide' or 'section.slide'. If matching elements are found,
+     * every slide will be extracted into a separate slide in the presentation.
+     */
+    slideSelector?: string;
+    /**
+     * Timeout in milliseconds for rendering/waiting.
+     * Defaults to 30000ms (30s).
+     */
+    timeout?: number;
+    /**
+     * Wait until specific condition before harvesting DOM.
+     * 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
+     */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    /**
+     * Optional pre-existing Puppeteer browser instance.
+     * If supplied, html-native-pptx will reuse it rather than launching a new Chromium process.
+     */
+    browser?: Browser;
+    /**
+     * Optional WebSocket endpoint to connect to a remote Chromium (e.g. Browserless.io).
+     */
+    browserWSEndpoint?: string;
+    /**
+     * Optional list of custom fonts to embed into the PowerPoint presentation.
+     */
+    fonts?: EmbeddedFontOption[];
+    /**
+     * Whether to automatically detect @font-face rules in HTML/CSS and embed them.
+     * Defaults to true.
+     */
+    autoEmbedFonts?: boolean;
+    /**
+     * Base directory path used to resolve relative font paths and asset URLs.
+     * Defaults to process.cwd().
+     */
+    basePath?: string;
+}
+
+/**
+ * Convert pixels to inches given a DPI and optional coordinate scale factor.
+ */
+declare function pxToInches(px: number, dpi?: number, scale?: number): number;
+/**
+ * Convert inches to English Metric Units (EMU).
+ * 1 inch = 914,400 EMU.
+ */
+declare function inchesToEmu(inches: number): number;
+/**
+ * Direct conversion from pixels to EMU.
+ */
+declare function pxToEmu(px: number, dpi?: number, scale?: number): number;
+/**
+ * Convert pixel font size to points (pt).
+ * 1 inch = 72 pt = 96 px -> 1 px = 0.75 pt.
+ */
+declare function pxToPt(px: number, dpi?: number): number;
+/**
+ * Convert points to hundredths of a point (used by OpenXML sz attribute).
+ * e.g., 16pt -> 1600.
+ */
+declare function ptToHundredthPt(pt: number): number;
+/**
+ * Convert CSS border-radius (in pixels) to OpenXML rounded rectangle adjustment guide value (0 - 50000).
+ * In OpenXML, an adj value of 50000 represents a radius equal to half the shortest dimension.
+ */
+declare function borderRadiusToGuide(radiusPx: number, widthPx: number, heightPx: number): number;
+
+interface ColorResult {
+    hex: string;
+    opacity?: number;
+}
+/**
+ * Normalizes any CSS color string (rgb, rgba, hex, named) into a 6-character uppercase hex string.
+ * Returns undefined if transparent or invalid.
+ */
+declare function normalizeHexColor(cssColor?: string): ColorResult | undefined;
+/**
+ * Normalizes CSS font-weight into a boolean representing bold.
+ */
+declare function normalizeFontWeight(fontWeight?: string | number): boolean;
+/**
+ * Normalizes CSS font-style into a boolean representing italic.
+ */
+declare function normalizeFontStyle(fontStyle?: string): boolean;
+/**
+ * Normalizes CSS font-family string by extracting the primary font family without quotes.
+ */
+declare function normalizeFontFamily(fontFamily?: string): string;
+/**
+ * Normalizes CSS text-align to IR TextAlign.
+ */
+declare function normalizeTextAlign(textAlign?: string): TextAlign;
+/**
+ * Normalizes CSS border-style to supported IR border types.
+ */
+declare function normalizeBorderStyle(borderStyle?: string): 'solid' | 'dashed' | 'dotted';
+
+/**
+ * Normalizes a typeface name by stripping quotes and taking the primary family.
+ */
+declare function cleanTypeface(name: string): string;
+/**
+ * Checks if a buffer contains Microsoft Embedded OpenType (EOT) binary data.
+ */
+declare function isEotBuffer(buf: Buffer): boolean;
+/**
+ * Converts TrueType (TTF) or OpenType (OTF) font buffer into Microsoft EOT format.
+ */
+declare function convertTtfToEot(buf: Buffer): Buffer;
+/**
+ * Loads font data from a buffer, data URI, web URL, or local file path.
+ */
+declare function loadFontBuffer(src: string | Buffer, basePath?: string): Promise<Buffer | null>;
+/**
+ * Extracts @font-face rules from raw HTML string or CSS text.
+ */
+declare function extractFontFacesFromHtml(html: string): Array<{
+    typeface: string;
+    src: string;
+}>;
+/**
+ * Resolves, deduplicates, and converts font options and discovered @font-face rules into EmbeddedFontIR items.
+ */
+declare function resolveAndEmbedFonts(options: {
+    html?: string;
+    userFonts?: EmbeddedFontOption[];
+    autoEmbedFonts?: boolean;
+    basePath?: string;
+    discoveredFonts?: Array<{
+        typeface: string;
+        src: string;
+    }>;
+}): Promise<EmbeddedFontIR[]>;
+
+declare function harvestHtmlToIR(htmlOrUrl: string, options?: ConvertOptions): Promise<SlideIR | SlideIR[]>;
+
+interface HarvestOptions {
+    selector?: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    aspect?: '16:9' | '4:3';
+}
+/**
+ * In-browser evaluation function to harvest DOM tree and compile it to SlideIR.
+ * Designed to execute inside Puppeteer's page.evaluate().
+ */
+declare function extractDomToSlideIR(options: HarvestOptions): SlideIR;
+
+interface CompileOptions {
+    fonts?: EmbeddedFontIR[];
+}
+/**
+ * Compiles a single SlideIR, an array of SlideIRs, or a PresentationIR into a valid PowerPoint (.pptx) file Buffer using OpenXML and JSZip.
+ */
+declare function compileSlideToPptx(slideOrSlidesOrPres: SlideIR | SlideIR[] | PresentationIR, options?: CompileOptions): Promise<Buffer>;
+
+/**
+ * Compiles a container IRNode into OpenXML <p:sp> element.
+ */
+declare function compileContainerShape(node: IRNode, id: number): string;
+
+/**
+ * Compiles a text IRNode into an OpenXML <p:sp> textbox element with zero internal margins.
+ */
+declare function compileTextShape(node: IRNode, id: number): string;
+
+/**
+ * Main conversion API: Converts an HTML string or URL into a native, editable PowerPoint (.pptx) buffer.
+ *
+ * @param html - Raw HTML string or valid http(s) URL.
+ * @param options - Configuration options for viewport, aspect ratio, or browser instance.
+ * @returns Promise resolving to a Node.js Buffer representing the .pptx file.
+ */
+declare function convertHtmlToPptx(html: string, options?: ConvertOptions): Promise<Buffer>;
+/**
+ * Helper to construct a blank SlideIR with standard 16:9 or 4:3 dimensions.
+ */
+declare function createSlideIR(aspect?: '16:9' | '4:3'): SlideIR;
+
+export { type BoundingBox, type ColorResult, type ConvertOptions, type ElementType, type EmbeddedFontIR, type EmbeddedFontOption, type IRNode, type ParagraphIR, type PresentationIR, type ShapeStyle, type SlideAspect, type SlideIR, type TextAlign, type TextRun, type TextStyle, UNITS, type ViewportOptions, borderRadiusToGuide, cleanTypeface, compileContainerShape, compileSlideToPptx, compileTextShape, convertHtmlToPptx, convertTtfToEot, createSlideIR, extractDomToSlideIR, extractFontFacesFromHtml, harvestHtmlToIR, inchesToEmu, isEotBuffer, loadFontBuffer, normalizeBorderStyle, normalizeFontFamily, normalizeFontStyle, normalizeFontWeight, normalizeHexColor, normalizeTextAlign, ptToHundredthPt, pxToEmu, pxToInches, pxToPt, resolveAndEmbedFonts };