quicklook-pptx-renderer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Frapporti
+
+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,266 @@
+# quicklook-pptx-renderer
+
+**An open-source, cross-platform PPTX rendering engine that replicates Apple's macOS QuickLook and iOS preview — pixel for pixel.**
+
+Build presentation pipelines that render identically across Microsoft PowerPoint, macOS Finder preview, iOS Files, and iPadOS. Runs on Linux, Docker, and the cloud — no Apple dependencies.
+
+Includes a **linter** that catches QuickLook compatibility issues before your users see them.
+
+---
+
+## The Problem
+
+You generate a `.pptx` with [python-pptx](https://python-pptx.readthedocs.io/), [PptxGenJS](https://gitbrent.github.io/PptxGenJS/), or any OOXML library. It looks perfect in PowerPoint. Then someone opens it on a Mac or iPhone and it looks **completely wrong**.
+
+This happens because Apple uses a private framework — `OfficeImport.framework` — that is a completely independent OOXML parser with its own bugs and rendering quirks. It converts slides to HTML+CSS, renders complex shapes as opaque PDF images, and silently drops unsupported geometries.
+
+### Common Symptoms
+
+- **Shapes disappear** — unsupported presets (heart, cloud, lightningBolt) are silently dropped
+- **Opaque white blocks** — rounded rectangles with shadows become solid PDF blocks covering content behind them
+- **Phantom shapes** — shapes from other slides appear due to a use-after-free cache bug
+- **Fonts shift** — Calibri becomes Helvetica Neue with different metrics, causing text reflow
+- **Table borders missing** — style references not resolved, borders vanish
+- **Gradients flattened** — 3+ color stops averaged to a single solid color
+- **Charts blank** — no fallback image means empty rectangle
+
+---
+
+## Quick Start
+
+```bash
+npm install quicklook-pptx-renderer
+```
+
+### Lint a PPTX for QuickLook Issues
+
+```bash
+npx quicklook-pptx lint presentation.pptx
+```
+
+```
+Slide 4:
+  [WARN] "roundRect" with effects renders as an opaque PDF image (Shape 9)
+         -> Remove drop shadow/glow effects, or use a plain rect
+  [ERR ] "cloud" is not supported by OfficeImport — shape will be invisible (Shape 12)
+         -> Use a supported preset or embed as an image
+
+0 errors, 3 warnings, 2 info across 18 slides
+```
+
+```bash
+# JSON output for CI integration
+npx quicklook-pptx lint presentation.pptx --json
+```
+
+### As a Library
+
+```typescript
+import { render } from "quicklook-pptx-renderer";
+import { readFileSync, writeFileSync } from "fs";
+
+const pptx = readFileSync("presentation.pptx");
+const result = await render(pptx);
+
+// Each slide has the exact HTML that QuickLook would generate
+for (const slide of result.slides) {
+  writeFileSync(`slide-${slide.index + 1}.html`, slide.html);
+}
+
+// Full HTML document with CSS (open in WebKit for pixel-perfect result)
+writeFileSync("preview.html", result.fullHtml);
+```
+
+### Lint Programmatically
+
+```typescript
+import { lint, formatIssues } from "quicklook-pptx-renderer";
+
+const result = await lint(pptxBuffer);
+
+// Human-readable output
+console.log(formatIssues(result));
+
+// Or work with structured issues
+for (const issue of result.issues) {
+  if (issue.severity === "error") {
+    console.error(`Slide ${issue.slide}: ${issue.message}`);
+  }
+}
+```
+
+### CLI Commands
+
+```bash
+# Render all slides to PNG (requires Playwright)
+npx quicklook-pptx render presentation.pptx --out ./slides/
+
+# Get raw HTML (same format as QuickLook's Preview.html)
+npx quicklook-pptx html presentation.pptx
+
+# Pixel-diff against actual QuickLook output (macOS only)
+npx quicklook-pptx diff presentation.pptx --quicklook-dir /tmp/ql-out/
+```
+
+---
+
+## Lint Rules
+
+| Rule | Severity | What It Catches |
+|------|----------|----------------|
+| `unsupported-geometry` | error | Shape preset not in OfficeImport's ~60 supported geometries — will be invisible |
+| `chart-no-fallback` | error | Chart without fallback image — renders as blank rectangle |
+| `opaque-pdf-block` | warn | Shape with effects rendered as opaque PDF covering content behind it |
+| `gradient-flattened` | warn | 3+ gradient stops collapsed to single average color |
+| `table-missing-borders` | warn | All table cells lack explicit borders — will appear borderless |
+| `table-style-unresolved` | warn | Table style reference that OfficeImport may not resolve |
+| `text-inscription-shift` | warn | Text in non-rect shape uses geometry-inscribed bounds |
+| `font-substitution` | info | Font will be substituted on macOS (Calibri → Helvetica Neue, etc.) |
+| `effect-forces-pdf` | info | Non-rect shape rendered as PDF instead of CSS |
+| `rotation-forces-pdf` | info | Rotated rect rendered as PDF instead of CSS |
+| `group-as-pdf` | info | Group rendered as single opaque PDF image |
+| `vertical-text` | info | Vertical text uses CSS writing-mode |
+
+---
+
+## Rendering Accuracy
+
+Pixel-level comparison against actual QuickLook output (`qlmanage -p`):
+
+| Source | Slides | Avg Pixel Diff | Perfect (< 0.05%) |
+|--------|--------|----------------|---------------------|
+| Real-world presentation | 18 | 0.15% | 16/18 |
+| python-pptx generated | 10 | 0.17% | 6/10 |
+| python-pptx stress test | 10 | 0.42% | 4/10 |
+| PptxGenJS generated | 10 | 0.11% | 6/10 |
+| Chart test suite | 7 | 0.08% | 7/7 |
+| **Overall** | **55** | **0.19%** | **39/55** |
+
+236/236 synthetic HTML structure tests pass.
+
+---
+
+## How It Works
+
+```
+PPTX (ZIP) → Package → Reader → Resolve → Mapper → HTML + PDF attachments
+```
+
+| Module | OfficeImport Equivalent | Purpose |
+|--------|------------------------|---------|
+| `package/` | OCP/OCX | ZIP extraction, `.rels` relationships |
+| `reader/` | PX/OAX | OOXML XML → typed domain objects |
+| `model/` | PD/OAD | TypeScript interfaces for slides, shapes, text, tables |
+| `resolve/` | — | Color themes, font substitution, property inheritance |
+| `mapper/` | PM/CM | HTML + CSS + PDF generation |
+| `lint` | — | Static analysis against known OfficeImport quirks |
+
+### Two Rendering Paths
+
+OfficeImport routes every shape through one of two paths:
+
+**CSS** — Only plain `rect` with no rotation and no effects → `<div>` with CSS properties.
+
+**PDF** — Everything else (roundRect, ellipse, stars, arrows, any rotation/effects) → inline PDF via `CMDrawingContext.copyPDF`, embedded as `<img src="AttachmentN.pdf">`.
+
+### Property Inheritance
+
+```
+shape local → slide placeholder → layout placeholder → master placeholder → master text style → theme
+```
+
+---
+
+## Key Discoveries
+
+These findings come from reverse engineering OfficeImport via Objective-C runtime introspection and ARM64 disassembly. They are not documented anywhere else:
+
+1. **Only `rect` takes the CSS path** — even `roundRect` and `ellipse` always go to PDF
+2. **~60 of 187 shape presets are supported** — the rest are silently dropped (no error, no fallback)
+3. **PDF shapes use the `B` operator** (simultaneous fill+stroke) with invisible default stroke
+4. **`CMArchiveManager` has a use-after-free** — PDF cache keyed by pointer identity causes cross-slide bleed
+5. **Table row heights use `EMU / 101600`**, not `EMU / 12700`
+6. **3+ gradient stops → average color** (not rendered as gradient)
+7. **Font substitution**: Calibri → Helvetica Neue, Arial → Helvetica, etc.
+8. **Text inscription for non-rect shapes** uses `float` radius and `trunc()` in pixel space
+
+---
+
+## Coordinate System
+
+| Measurement | Unit | Conversion |
+|------------|------|-----------|
+| Position / Size | EMU | 12,700 EMU = 1 CSS pixel |
+| Font size | Hundredths of a point | 1800 = 18pt |
+| Angles | 60,000ths of a degree | 5,400,000 = 90deg |
+| Color transforms | 1,000ths of percent | 100,000 = 100% |
+| Table row height | EMU / 101,600 | (OfficeImport quirk) |
+
+---
+
+## Compatibility
+
+| Platform | Status |
+|----------|--------|
+| Node.js 20+ (Linux, macOS, Windows) | Full support |
+| Docker / containers | Full support |
+| AWS Lambda / Cloud Functions | Full support (HTML; PNG needs Playwright) |
+| Bun | Untested |
+| Deno | Untested |
+
+---
+
+## Fixing Common Issues
+
+### python-pptx Table Borders Missing
+
+The #1 reported issue. python-pptx applies borders via table style reference, which OfficeImport doesn't fully resolve. Set borders explicitly:
+
+```python
+from pptx.util import Pt
+from pptx.dml.color import RGBColor
+
+for cell in table.iter_cells():
+    for border in [cell.border_top, cell.border_bottom,
+                   cell.border_left, cell.border_right]:
+        border.width = Pt(1)
+        border.color.rgb = RGBColor(0, 0, 0)
+```
+
+### Shapes Disappearing
+
+Your shape preset isn't in OfficeImport's supported list. Run `npx quicklook-pptx lint your-file.pptx` to find which shapes will be invisible. Use supported presets or embed complex shapes as images.
+
+### Opaque White Blocks
+
+Shapes with drop shadows render as opaque PDF images. The PDF has a non-transparent background that covers content behind it. Remove effects or restructure z-ordering.
+
+---
+
+## Related Projects
+
+| Project | Difference |
+|---------|-----------|
+| [LibreOffice headless](https://www.libreoffice.org/) | Renders like LibreOffice, not like QuickLook |
+| [python-pptx](https://python-pptx.readthedocs.io/) | Creates/reads PPTX; doesn't render |
+| [PptxGenJS](https://gitbrent.github.io/PptxGenJS/) | Creates PPTX; doesn't render |
+| [Apache POI](https://poi.apache.org/) | Java; renders like Java, not like QuickLook |
+
+**This is the only open-source project that replicates Apple's exact QuickLook rendering.**
+
+---
+
+## Dependencies
+
+| Package | Purpose | Required |
+|---------|---------|----------|
+| [jszip](https://stuk.github.io/jszip/) | ZIP extraction | Yes |
+| [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) | OOXML XML parsing | Yes |
+| [@napi-rs/canvas](https://github.com/nickthedude/napi-rs-canvas) | PDF image generation | Optional (for render) |
+| [playwright](https://playwright.dev/) | HTML-to-PNG screenshots | Optional (dev) |
+
+The linter (`quicklook-pptx lint`) needs only jszip + fast-xml-parser — no native dependencies.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve, basename } from "node:path";
+import { PptxPackage } from "./package/package.js";
+import { readPresentation } from "./reader/presentation.js";
+import { generateHtml } from "./mapper/html-generator.js";
+import { lint, formatIssues } from "./lint.js";
+const BIN = "quicklook-pptx";
+// ── Arg parsing ────────────────────────────────────────────────────
+function getFlag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+function positional(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--")) {
+            i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
+// ── Commands ───────────────────────────────────────────────────────
+async function cmdRender(args) {
+    const pos = positional(args);
+    const input = pos[0];
+    if (!input) {
+        console.error(`Usage: ${BIN} render <input.pptx> [--slide N] [--out output.png] [--width 1920] [--scale 2] [--all]`);
+        process.exit(1);
+    }
+    let renderSlide;
+    try {
+        ({ renderSlide } = await import("./render/renderer.js"));
+    }
+    catch {
+        console.error("The 'render' command requires @napi-rs/canvas. Install it with:\n  npm install @napi-rs/canvas");
+        process.exit(1);
+    }
+    const width = Number(getFlag(args, "--width") ?? 1920);
+    const scale = Number(getFlag(args, "--scale") ?? 2);
+    const slideNum = getFlag(args, "--slide");
+    const outPath = getFlag(args, "--out");
+    const all = hasFlag(args, "--all") || !slideNum;
+    const pptxBuf = await readFile(resolve(input));
+    const pkg = await PptxPackage.open(pptxBuf);
+    const pres = await readPresentation(pkg);
+    if (all) {
+        const outDir = outPath ? dirname(outPath) : ".";
+        await mkdir(outDir, { recursive: true });
+        for (let i = 0; i < pres.slides.length; i++) {
+            const png = await renderSlide(pres.slides[i], pres, { width, scale, pkg, slideIndex: i });
+            const dest = outPath && pres.slides.length === 1
+                ? resolve(outPath)
+                : resolve(outDir, `slide-${i + 1}.png`);
+            await writeFile(dest, png);
+            console.log(`slide ${i + 1} → ${dest}`);
+        }
+    }
+    else {
+        const idx = Number(slideNum) - 1;
+        if (idx < 0 || idx >= pres.slides.length) {
+            console.error(`Slide ${slideNum} out of range (1-${pres.slides.length})`);
+            process.exit(1);
+        }
+        const png = await renderSlide(pres.slides[idx], pres, { width, scale, pkg, slideIndex: idx });
+        const dest = resolve(outPath ?? `slide-${idx + 1}.png`);
+        await writeFile(dest, png);
+        console.log(`slide ${idx + 1} → ${dest}`);
+    }
+}
+async function cmdHtml(args) {
+    const pos = positional(args);
+    const input = pos[0];
+    if (!input) {
+        console.error(`Usage: ${BIN} html <input.pptx> [--out output.html]`);
+        process.exit(1);
+    }
+    const outPath = getFlag(args, "--out");
+    const pptxBuf = await readFile(resolve(input));
+    const pkg = await PptxPackage.open(pptxBuf);
+    const pres = await readPresentation(pkg);
+    const { html } = await generateHtml(pres, { pkg });
+    if (outPath) {
+        await writeFile(resolve(outPath), html, "utf8");
+        console.error(`HTML written to ${outPath}`);
+    }
+    else {
+        process.stdout.write(html);
+    }
+}
+async function cmdDiff(args) {
+    const pos = positional(args);
+    const input = pos[0];
+    const quicklookDir = getFlag(args, "--quicklook-dir");
+    if (!input || !quicklookDir) {
+        console.error(`Usage: ${BIN} diff <input.pptx> --quicklook-dir <dir> [--out-dir <dir>] [--width 960] [--slide N]`);
+        process.exit(1);
+    }
+    let compareSlidesToQuickLook;
+    try {
+        ({ compareSlidesToQuickLook } = await import("./diff/compare.js"));
+    }
+    catch {
+        console.error("The 'diff' command requires optional dependencies. Install them with:\n  npm install @napi-rs/canvas pixelmatch pngjs");
+        process.exit(1);
+    }
+    const width = Number(getFlag(args, "--width") ?? 960);
+    const scale = Number(getFlag(args, "--scale") ?? 2);
+    const slideFilter = getFlag(args, "--slide");
+    const outDir = resolve(getFlag(args, "--out-dir") ?? `diff-${basename(input, ".pptx")}`);
+    await mkdir(outDir, { recursive: true });
+    const comparisons = await compareSlidesToQuickLook(resolve(input), resolve(quicklookDir), { width, scale });
+    let hasOutput = false;
+    for (const c of comparisons) {
+        const num = c.slideIndex + 1;
+        if (slideFilter && num !== Number(slideFilter))
+            continue;
+        hasOutput = true;
+        await writeFile(`${outDir}/${num}-rendered.png`, c.rendered);
+        await writeFile(`${outDir}/${num}-diff.png`, c.diff);
+        const pct = c.diffPercent.toFixed(2);
+        const bar = c.diffPercent < 1 ? "OK" : c.diffPercent < 5 ? "WARN" : "FAIL";
+        console.log(`slide ${num}: ${pct}% diff (${c.diffPixels} px) [${bar}]`);
+    }
+    if (!hasOutput) {
+        console.error("No slides matched or no quicklook images found.");
+        process.exit(1);
+    }
+    console.log(`\nDiff images written to ${outDir}/`);
+}
+async function cmdLint(args) {
+    const pos = positional(args);
+    const input = pos[0];
+    if (!input) {
+        console.error(`Usage: ${BIN} lint <input.pptx> [--json]`);
+        process.exit(1);
+    }
+    const json = hasFlag(args, "--json");
+    const pptxBuf = await readFile(resolve(input));
+    const result = await lint(pptxBuf);
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(formatIssues(result));
+    }
+    if (result.summary.errors > 0)
+        process.exit(1);
+}
+// ── Main ───────────────────────────────────────────────────────────
+const [command, ...args] = process.argv.slice(2);
+switch (command) {
+    case "render":
+        await cmdRender(args);
+        break;
+    case "html":
+        await cmdHtml(args);
+        break;
+    case "diff":
+        await cmdDiff(args);
+        break;
+    case "lint":
+        await cmdLint(args);
+        break;
+    default:
+        console.error(`Usage: ${BIN} <render|html|lint|diff> [options]`);
+        process.exit(1);
+}

package/dist/diff/compare.d.ts

@@ -0,0 +1,17 @@
+import { type RenderOptions } from "../render/renderer.js";
+export interface CompareResult {
+    diffPercent: number;
+    diffPixels: number;
+    totalPixels: number;
+    diffImage: Buffer;
+}
+export interface SlideComparison {
+    slideIndex: number;
+    diffPercent: number;
+    diffPixels: number;
+    rendered: Buffer;
+    expected: Buffer;
+    diff: Buffer;
+}
+export declare function compareImages(actual: Buffer, expected: Buffer): Promise<CompareResult>;
+export declare function compareSlidesToQuickLook(pptxPath: string, quicklookDir: string, options?: RenderOptions): Promise<SlideComparison[]>;

package/dist/diff/compare.js

@@ -0,0 +1,71 @@
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { readFile } from "node:fs/promises";
+import { PptxPackage } from "../package/package.js";
+import { readPresentation } from "../reader/presentation.js";
+import { renderSlide } from "../render/renderer.js";
+function decodePng(buf) {
+    return PNG.sync.read(buf);
+}
+function encodePng(png) {
+    return PNG.sync.write(png);
+}
+/** Pad the smaller image with transparent pixels to match the larger dimensions. */
+function matchDimensions(a, b) {
+    const w = Math.max(a.width, b.width);
+    const h = Math.max(a.height, b.height);
+    return [padTo(a, w, h), padTo(b, w, h)];
+}
+function padTo(img, w, h) {
+    if (img.width === w && img.height === h)
+        return img;
+    const out = new PNG({ width: w, height: h, fill: true });
+    // fill white background so padding differences are visible
+    out.data.fill(255);
+    PNG.bitblt(img, out, 0, 0, img.width, img.height, 0, 0);
+    return out;
+}
+export async function compareImages(actual, expected) {
+    let a = decodePng(actual);
+    let b = decodePng(expected);
+    [a, b] = matchDimensions(a, b);
+    const { width, height } = a;
+    const totalPixels = width * height;
+    const diff = new PNG({ width, height });
+    const diffPixels = pixelmatch(a.data, b.data, diff.data, width, height, {
+        threshold: 0.1,
+    });
+    return {
+        diffPercent: totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0,
+        diffPixels,
+        totalPixels,
+        diffImage: encodePng(diff),
+    };
+}
+export async function compareSlidesToQuickLook(pptxPath, quicklookDir, options) {
+    const pptxBuf = await readFile(pptxPath);
+    const pkg = await PptxPackage.open(pptxBuf);
+    const pres = await readPresentation(pkg);
+    const results = [];
+    for (let i = 0; i < pres.slides.length; i++) {
+        const expectedPath = `${quicklookDir}/${i + 1}-quicklook.png`;
+        let expectedBuf;
+        try {
+            expectedBuf = await readFile(expectedPath);
+        }
+        catch {
+            continue; // no reference image for this slide
+        }
+        const rendered = await renderSlide(pres.slides[i], pres, { ...options, pkg, slideIndex: i });
+        const { diffPercent, diffPixels, diffImage } = await compareImages(rendered, expectedBuf);
+        results.push({
+            slideIndex: i,
+            diffPercent,
+            diffPixels,
+            rendered,
+            expected: expectedBuf,
+            diff: diffImage,
+        });
+    }
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * quicklook-pptx-renderer — Replicate macOS QuickLook PPTX rendering in pure TypeScript.
+ *
+ * Main entry point with both high-level render() API and raw building blocks.
+ */
+export interface SlideResult {
+    index: number;
+    html: string;
+    attachments: Map<string, Buffer>;
+}
+export interface RenderResult {
+    slides: SlideResult[];
+    fullHtml: string;
+    attachments: Map<string, Buffer>;
+}
+/**
+ * Render a PPTX buffer to QuickLook-identical HTML output.
+ *
+ * Returns per-slide HTML fragments plus the full HTML document with
+ * embedded CSS — ready to open in WebKit for pixel-perfect rendering.
+ */
+export declare function render(pptxBuffer: Buffer): Promise<RenderResult>;
+export { lint, formatIssues, type LintResult, type LintIssue, type Severity, type RuleId } from "./lint.js";
+export { PptxPackage } from "./package/package.js";
+export { readPresentation } from "./reader/presentation.js";
+export { generateHtml, type MapperOptions, type HtmlOutput } from "./mapper/html-generator.js";
+export { resolveColor } from "./resolve/color-resolver.js";
+export { resolveFontFamily } from "./resolve/font-map.js";
+export type { Presentation, Slide, SlideLayout, SlideMaster, Shape, Picture, Group, Connector, GraphicFrame, TextBody, Paragraph, TextRun, CharacterProperties, ParagraphProperties, Color, Fill, Stroke, Effect, Theme, Drawable, DrawableBase, OrientedBounds, } from "./model/types.js";

package/dist/index.js

@@ -0,0 +1,72 @@
+/**
+ * quicklook-pptx-renderer — Replicate macOS QuickLook PPTX rendering in pure TypeScript.
+ *
+ * Main entry point with both high-level render() API and raw building blocks.
+ */
+import { PptxPackage } from "./package/package.js";
+import { readPresentation } from "./reader/presentation.js";
+import { generateHtml } from "./mapper/html-generator.js";
+/**
+ * Render a PPTX buffer to QuickLook-identical HTML output.
+ *
+ * Returns per-slide HTML fragments plus the full HTML document with
+ * embedded CSS — ready to open in WebKit for pixel-perfect rendering.
+ */
+export async function render(pptxBuffer) {
+    const pkg = await PptxPackage.open(pptxBuffer);
+    const pres = await readPresentation(pkg);
+    const { html, attachments } = await generateHtml(pres, { pkg });
+    // Split full HTML into per-slide fragments
+    const slides = [];
+    const marker = '<div class="slide" style="top:0; left:0;">';
+    let pos = 0;
+    let idx = 0;
+    while (true) {
+        const start = html.indexOf(marker, pos);
+        if (start === -1)
+            break;
+        const contentStart = start;
+        // Find matching closing </div>
+        let depth = 0;
+        let j = start;
+        while (j < html.length) {
+            if (html[j] === '<') {
+                if (html.substring(j, j + 6) === '</div>') {
+                    depth--;
+                    if (depth === 0) {
+                        slides.push({
+                            index: idx,
+                            html: html.substring(contentStart, j + 6),
+                            attachments: new Map(),
+                        });
+                        break;
+                    }
+                    j += 6;
+                    continue;
+                }
+                if (html.substring(j, j + 4) === '<div')
+                    depth++;
+            }
+            j++;
+        }
+        pos = j;
+        idx++;
+    }
+    // Distribute attachments to their slides by scanning for src="AttachmentN.xxx"
+    for (const slide of slides) {
+        for (const [name, buf] of attachments) {
+            if (slide.html.includes(`src="${name}"`)) {
+                slide.attachments.set(name, buf);
+            }
+        }
+    }
+    return { slides, fullHtml: html, attachments };
+}
+// ── Linter (QuickLook compatibility checks) ─────────────────────
+export { lint, formatIssues } from "./lint.js";
+// ── Building blocks ─────────────────────────────────────────────
+export { PptxPackage } from "./package/package.js";
+export { readPresentation } from "./reader/presentation.js";
+export { generateHtml } from "./mapper/html-generator.js";
+export { resolveColor } from "./resolve/color-resolver.js";
+export { resolveFontFamily } from "./resolve/font-map.js";

package/dist/lint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * QuickLook PPTX Linter — detect compatibility issues before they surprise users.
+ *
+ * Parses a PPTX and checks every shape, text run, table, and fill against
+ * known OfficeImport quirks. No rendering required — just parse and check.
+ */
+export type Severity = "error" | "warn" | "info";
+export type RuleId = "unsupported-geometry" | "opaque-pdf-block" | "gradient-flattened" | "font-substitution" | "table-missing-borders" | "table-style-unresolved" | "group-as-pdf" | "chart-no-fallback" | "text-inscription-shift" | "rotation-forces-pdf" | "effect-forces-pdf" | "vertical-text";
+export interface LintIssue {
+    rule: RuleId;
+    severity: Severity;
+    slide: number;
+    element?: string;
+    message: string;
+    suggestion?: string;
+}
+export interface LintResult {
+    issues: LintIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+        slides: number;
+    };
+}
+export declare function lint(pptxBuffer: Buffer): Promise<LintResult>;
+export declare function formatIssues(result: LintResult): string;