pptx-fix 0.2.0

package/README.md

@@ -0,0 +1,149 @@
+# pptx-fix
+
+**Fix PowerPoint files that render incorrectly on macOS QuickLook and iOS.** Rewrites PPTX internals so tables, shapes, gradients, and effects display correctly on Apple devices — no manual editing needed.
+
+If your `.pptx` looks perfect in PowerPoint but looks wrong when someone opens it on a Mac or iPhone, this tool fixes it.
+
+---
+
+## The Problem
+
+Apple's QuickLook (macOS Finder spacebar preview), iOS Files app, and iPadOS use a private rendering engine called `OfficeImport.framework` — a completely independent OOXML parser that renders slides differently than Microsoft PowerPoint. Presentations created by python-pptx, PptxGenJS, Google Slides, Canva, LibreOffice, Pandoc, and other tools contain patterns that PowerPoint handles fine but OfficeImport renders incorrectly.
+
+Common artifacts:
+
+- **Table borders vanish** — generators set a table style reference, but OfficeImport only reads explicit border properties
+- **Shapes disappear** — ~120 preset geometries (heart, cloud, lightningBolt, sun, moon...) are silently dropped
+- **Gradients become flat colors** — 3+ color stops are averaged to a single solid color
+- **Drop shadows become opaque blocks** — shapes with effects render as opaque PDF images that cover content behind them
+- **Fonts shift and text reflows** — Calibri becomes Helvetica Neue, Arial becomes Helvetica, with different metrics
+
+`pptx-fix` rewrites the OOXML XML inside the PPTX ZIP to work around these OfficeImport quirks. The output is a valid `.pptx` that looks correct in both PowerPoint and Apple's preview.
+
+---
+
+## Install
+
+```bash
+npm install pptx-fix
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Fix a PPTX file
+npx pptx-fix input.pptx -o output.pptx
+
+# Apply only specific transforms
+npx pptx-fix input.pptx -o output.pptx --only table-styles,gradients
+
+# See what was changed
+npx pptx-fix input.pptx -o output.pptx --report
+
+# Analyze without fixing (dry run)
+npx pptx-fix analyze input.pptx
+```
+
+### As a Library
+
+```typescript
+import { fix } from "pptx-fix";
+import { readFileSync, writeFileSync } from "fs";
+
+const input = readFileSync("presentation.pptx");
+const result = await fix(input, { report: true });
+
+writeFileSync("fixed.pptx", result.buffer);
+console.log(result.report);
+```
+
+### Analyze Only
+
+```typescript
+import { analyze } from "pptx-fix";
+
+const issues = await analyze(pptxBuffer);
+for (const issue of issues) {
+  console.log(`[${issue.severity}] Slide ${issue.slide}: ${issue.description}`);
+}
+```
+
+---
+
+## Transforms
+
+| Transform | Status | What it fixes |
+|-----------|--------|--------------|
+| **table-styles** | Done | Resolves `tableStyleId` references and inlines explicit `<a:lnL/R/T/B>` borders on every cell. Handles `firstRow`, `lastRow`, `bandRow` conditional formatting. Only adds borders where none are explicitly defined. |
+| **geometries** | Planned | Replace unsupported `<a:prstGeom>` (heart, cloud, lightningBolt, sun, moon, frame, arc, chord, etc.) with `<a:custGeom>` path data. |
+| **gradients** | Planned | Collapse 3+ stop gradients to 2-stop (start + end color) so QuickLook renders a gradient instead of a flat color. |
+| **effects** | Planned | Strip or adjust shapes with `<effectLst>` (drop shadow, glow, reflection) that render as opaque PDF blocks covering content. |
+
+Detection of all issues (including font substitution, chart fallbacks, text inscription shifts, and more) is handled by [quicklook-pptx-renderer](https://www.npmjs.com/package/quicklook-pptx-renderer)'s 12-rule linter. Run `pptx-fix analyze` to see all issues, or use the linter directly in CI.
+
+---
+
+## Which Tools Produce Affected Files
+
+| Tool | Primary issue on Mac/iPhone |
+|------|---|
+| **python-pptx** | Tables render without borders — the #1 reported issue. Style references not resolved by OfficeImport. |
+| **PptxGenJS** | Missing thumbnails, shape rendering differences, effect artifacts |
+| **Google Slides** export | Font substitution, formatting shifts, missing content types |
+| **Canva** export | Fonts substituted, layout differences, animation artifacts |
+| **LibreOffice Impress** | Table styles unresolved, gradient rendering differences |
+| **Pandoc** / **Quarto** | Content type corruption, missing shapes, "PowerPoint found a problem with content" errors |
+| **Apache POI** | Content type errors (`InvalidFormatException: Package should contain a content type part [M1.13]`) |
+| **Aspose.Slides** | Missing thumbnail if `refresh_thumbnail` not called |
+| **Open XML SDK** | Repair errors, missing relationships |
+
+---
+
+## How It Works
+
+```
+PPTX (ZIP) → extract XML → parse → detect issues → apply transforms → serialize → repack ZIP
+```
+
+1. **Extract** — JSZip opens the PPTX (which is a ZIP archive)
+2. **Parse** — fast-xml-parser converts slide XML to objects, preserving all unknown elements
+3. **Detect** — each transform scans for its class of issues
+4. **Apply** — transforms mutate the XML objects (e.g., inline borders from table style definitions)
+5. **Serialize** — XMLBuilder converts back to XML
+6. **Repack** — JSZip produces a new valid PPTX
+
+The round-trip preserves all XML elements the tool doesn't explicitly modify — the output is always a valid PPTX.
+
+---
+
+## Detecting Issues Without Fixing
+
+For comprehensive linting with 12 rules, CI integration, cross-platform rendering, and pixel-diff comparison against actual QuickLook output, see [**quicklook-pptx-renderer**](https://www.npmjs.com/package/quicklook-pptx-renderer) — a companion renderer + linter that replicates Apple's QuickLook output pixel for pixel, runs on Linux/Docker without a Mac.
+
+```bash
+# Lint (12 rules, JSON output for CI)
+npx quicklook-pptx lint presentation.pptx --json
+
+# Render slides as PNG (see exactly what Mac users see)
+npx quicklook-pptx render presentation.pptx --out ./slides/
+
+# Fix (this package)
+npx pptx-fix presentation.pptx -o fixed.pptx
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [jszip](https://stuk.github.io/jszip/) | ZIP extraction/repacking |
+| [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) | OOXML XML parsing and serialization |
+
+Zero native dependencies. Works everywhere Node.js 20+ runs.
+
+## License
+
+MIT

package/dist/analyze.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Analyze a PPTX for issues that will cause QuickLook rendering problems.
+ * Delegates to quicklook-pptx-renderer's linter — single source of truth.
+ */
+export { lint as analyze, formatIssues, type LintResult, type LintIssue } from "quicklook-pptx-renderer";

package/dist/analyze.js

@@ -0,0 +1,5 @@
+/**
+ * Analyze a PPTX for issues that will cause QuickLook rendering problems.
+ * Delegates to quicklook-pptx-renderer's linter — single source of truth.
+ */
+export { lint as analyze, formatIssues } from "quicklook-pptx-renderer";

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fix } from "./writer.js";
+import { analyze, formatIssues } from "./analyze.js";
+const args = process.argv.slice(2);
+function getFlag(name) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(name) {
+    return args.includes(name);
+}
+function positional() {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--") || args[i] === "-o") {
+            i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
+async function main() {
+    const pos = positional();
+    const command = pos[0];
+    if (command === "analyze") {
+        const input = pos[1];
+        if (!input) {
+            console.error("Usage: pptx-fix analyze <input.pptx>");
+            process.exit(1);
+        }
+        const buf = await readFile(resolve(input));
+        const result = await analyze(buf);
+        console.log(formatIssues(result));
+        process.exit(result.summary.errors > 0 ? 1 : 0);
+    }
+    // Default: fix
+    const input = command;
+    if (!input || input.startsWith("-")) {
+        console.error("Usage: pptx-fix <input.pptx> -o <output.pptx> [--only table-styles,gradients] [--report]");
+        console.error("       pptx-fix analyze <input.pptx>");
+        process.exit(1);
+    }
+    const outPath = getFlag("-o") ?? getFlag("--out");
+    if (!outPath) {
+        console.error("Error: output path required (-o <output.pptx>)");
+        process.exit(1);
+    }
+    const onlyStr = getFlag("--only");
+    const transforms = onlyStr
+        ? onlyStr.split(",").map(s => s.trim())
+        : undefined;
+    const wantReport = hasFlag("--report");
+    const buf = await readFile(resolve(input));
+    const result = await fix(buf, { transforms, report: wantReport });
+    await writeFile(resolve(outPath), result.buffer);
+    if (wantReport && result.report) {
+        console.log(result.report);
+    }
+    console.log(`Fixed → ${outPath}`);
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * pptx-fix — Fix PPTX files for macOS QuickLook / iOS preview rendering.
+ *
+ * Detection delegates to quicklook-pptx-renderer's linter.
+ * Transforms operate on raw XML (preserving all unknown elements) so the
+ * output is a valid PPTX that looks correct in Apple's OfficeImport pipeline.
+ */
+export { fix, type FixOptions, type FixResult } from "./writer.js";
+export { analyze, formatIssues, type LintResult, type LintIssue } from "./analyze.js";
+export { type TransformName, ALL_TRANSFORMS } from "./transforms/index.js";
+export { FONT_METRICS, findClosestFont, widthDelta, type FontMetrics, type FontMatch, type FontCategory } from "quicklook-pptx-renderer";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * pptx-fix — Fix PPTX files for macOS QuickLook / iOS preview rendering.
+ *
+ * Detection delegates to quicklook-pptx-renderer's linter.
+ * Transforms operate on raw XML (preserving all unknown elements) so the
+ * output is a valid PPTX that looks correct in Apple's OfficeImport pipeline.
+ */
+export { fix } from "./writer.js";
+export { analyze, formatIssues } from "./analyze.js";
+export { ALL_TRANSFORMS } from "./transforms/index.js";
+export { FONT_METRICS, findClosestFont, widthDelta } from "quicklook-pptx-renderer";

package/dist/transforms/effects.d.ts

@@ -0,0 +1,8 @@
+/**
+ * effects transform — Strip or adjust shapes with effectLst that render
+ * as opaque PDF blocks in QuickLook.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (opaque-pdf-block rule).
+ */
+import type { Transform } from "./index.js";
+export declare const effects: Transform;

package/dist/transforms/effects.js

@@ -0,0 +1,13 @@
+/**
+ * effects transform — Strip or adjust shapes with effectLst that render
+ * as opaque PDF blocks in QuickLook.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (opaque-pdf-block rule).
+ */
+export const effects = {
+    name: "effects",
+    apply(_slideXml, _slideNum, _ctx) {
+        // TODO: configurable — strip effects, reorder z-index, or no-op
+        return { changed: false, changes: [] };
+    },
+};

package/dist/transforms/fonts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * fonts transform — Add explicit <a:latin>, <a:ea>, <a:cs> fallback
+ * typefaces matching what OfficeImport's TCFontUtils would pick.
+ */
+import type { Transform } from "./index.js";
+export declare const fonts: Transform;

package/dist/transforms/fonts.js

@@ -0,0 +1,15 @@
+/**
+ * fonts transform — Add explicit <a:latin>, <a:ea>, <a:cs> fallback
+ * typefaces matching what OfficeImport's TCFontUtils would pick.
+ */
+export const fonts = {
+    name: "fonts",
+    detect(_slideXml, _slideNum) {
+        // TODO: detect text runs missing explicit font declarations
+        return [];
+    },
+    apply(_slideXml, _slideNum, _ctx) {
+        // TODO: implement — add fallback typefaces
+        return { changed: false, changes: [] };
+    },
+};

package/dist/transforms/geometries.d.ts

@@ -0,0 +1,8 @@
+/**
+ * geometries transform — Replace unsupported preset geometries with
+ * equivalent <a:custGeom> path data.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (unsupported-geometry rule).
+ */
+import type { Transform } from "./index.js";
+export declare const geometries: Transform;

package/dist/transforms/geometries.js

@@ -0,0 +1,13 @@
+/**
+ * geometries transform — Replace unsupported preset geometries with
+ * equivalent <a:custGeom> path data.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (unsupported-geometry rule).
+ */
+export const geometries = {
+    name: "geometries",
+    apply(_slideXml, _slideNum, _ctx) {
+        // TODO: replace prstGeom with custGeom containing equivalent path data
+        return { changed: false, changes: [] };
+    },
+};

package/dist/transforms/gradients.d.ts

@@ -0,0 +1,8 @@
+/**
+ * gradients transform — Collapse 3+ stop gradients to 2-stop so QuickLook
+ * renders a gradient instead of averaging to a flat color.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (gradient-flattened rule).
+ */
+import type { Transform } from "./index.js";
+export declare const gradients: Transform;

package/dist/transforms/gradients.js

@@ -0,0 +1,13 @@
+/**
+ * gradients transform — Collapse 3+ stop gradients to 2-stop so QuickLook
+ * renders a gradient instead of averaging to a flat color.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter (gradient-flattened rule).
+ */
+export const gradients = {
+    name: "gradients",
+    apply(_slideXml, _slideNum, _ctx) {
+        // TODO: collapse 3+ stop gradients to 2-stop (endpoints only)
+        return { changed: false, changes: [] };
+    },
+};

package/dist/transforms/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Transform registry — each transform fixes one class of
+ * OfficeImport rendering issues by mutating raw OOXML.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter.
+ * These transforms only apply fixes.
+ */
+export type TransformName = "table-styles" | "gradients" | "geometries" | "effects";
+export interface TransformContext {
+    tableStyleXml?: any;
+}
+export interface TransformResult {
+    changed: boolean;
+    changes: string[];
+}
+export interface Transform {
+    name: TransformName;
+    apply: (slideXml: any, slideNum: number, ctx: TransformContext) => TransformResult;
+}
+export declare const ALL_TRANSFORMS: Transform[];

package/dist/transforms/index.js

@@ -0,0 +1,17 @@
+/**
+ * Transform registry — each transform fixes one class of
+ * OfficeImport rendering issues by mutating raw OOXML.
+ *
+ * Detection is handled by quicklook-pptx-renderer's linter.
+ * These transforms only apply fixes.
+ */
+import { tableStyles } from "./table-styles.js";
+import { gradients } from "./gradients.js";
+import { geometries } from "./geometries.js";
+import { effects } from "./effects.js";
+export const ALL_TRANSFORMS = [
+    tableStyles,
+    gradients,
+    geometries,
+    effects,
+];

package/dist/transforms/properties.d.ts

@@ -0,0 +1,7 @@
+/**
+ * properties transform — Resolve full inheritance chain
+ * (theme → master → layout → slide) and write explicit fill, font, color
+ * on each element.
+ */
+import type { Transform } from "./index.js";
+export declare const properties: Transform;

package/dist/transforms/properties.js

@@ -0,0 +1,16 @@
+/**
+ * properties transform — Resolve full inheritance chain
+ * (theme → master → layout → slide) and write explicit fill, font, color
+ * on each element.
+ */
+export const properties = {
+    name: "properties",
+    detect(_slideXml, _slideNum) {
+        // TODO: detect elements relying on inherited properties
+        return [];
+    },
+    apply(_slideXml, _slideNum, _ctx) {
+        // TODO: implement — resolve inheritance and inline explicit properties
+        return { changed: false, changes: [] };
+    },
+};

package/dist/transforms/table-styles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * table-styles transform — Resolve table style conditional formatting into
+ * explicit borders on every <a:tcPr>.
+ *
+ * OfficeImport doesn't resolve tableStyleId references — it only sees
+ * explicit border properties. This inlines them from tableStyles.xml.
+ */
+import type { Transform } from "./index.js";
+export declare const tableStyles: Transform;

package/dist/transforms/table-styles.js

@@ -0,0 +1,148 @@
+/**
+ * table-styles transform — Resolve table style conditional formatting into
+ * explicit borders on every <a:tcPr>.
+ *
+ * OfficeImport doesn't resolve tableStyleId references — it only sees
+ * explicit border properties. This inlines them from tableStyles.xml.
+ */
+function findTables(node, path = "") {
+    const results = [];
+    if (!node || typeof node !== "object")
+        return results;
+    if (node.tbl) {
+        const tbls = Array.isArray(node.tbl) ? node.tbl : [node.tbl];
+        for (const t of tbls)
+            results.push({ table: t, path: path + "/tbl" });
+    }
+    for (const key of Object.keys(node)) {
+        if (key.startsWith("@_"))
+            continue;
+        const children = Array.isArray(node[key]) ? node[key] : [node[key]];
+        for (const child of children) {
+            results.push(...findTables(child, path + "/" + key));
+        }
+    }
+    return results;
+}
+function tableNeedsFix(table) {
+    const tblPr = table.tblPr;
+    if (!tblPr)
+        return false;
+    const styleId = tblPr["@_tblStyle"] ?? tblPr.tblStyle;
+    if (!styleId)
+        return false;
+    const rows = table.tr;
+    if (!rows)
+        return false;
+    const rowArr = Array.isArray(rows) ? rows : [rows];
+    for (const row of rowArr) {
+        const cells = row.tc;
+        if (!cells)
+            continue;
+        const cellArr = Array.isArray(cells) ? cells : [cells];
+        for (const cell of cellArr) {
+            const tcPr = cell.tcPr;
+            if (!tcPr)
+                return true;
+            if (!(tcPr.lnL || tcPr.lnR || tcPr.lnT || tcPr.lnB))
+                return true;
+        }
+    }
+    return false;
+}
+function findStyleDef(tableStyleXml, styleId) {
+    if (!tableStyleXml)
+        return undefined;
+    const styleLst = tableStyleXml.tblStyleLst;
+    if (!styleLst)
+        return undefined;
+    const styles = styleLst.tblStyle;
+    if (!styles)
+        return undefined;
+    const arr = Array.isArray(styles) ? styles : [styles];
+    return arr.find((s) => s["@_styleId"] === styleId);
+}
+function buildBorder(tcStyle, side) {
+    if (!tcStyle)
+        return undefined;
+    const borders = tcStyle.tcBdr;
+    if (!borders)
+        return undefined;
+    const border = borders[side];
+    if (!border)
+        return undefined;
+    return border.ln ?? border;
+}
+function applyTableStyle(table, styleDef) {
+    const changes = [];
+    const rows = table.tr;
+    if (!rows)
+        return changes;
+    const rowArr = Array.isArray(rows) ? rows : [rows];
+    const tblPr = table.tblPr ?? {};
+    const hasFirstRow = tblPr["@_firstRow"] === "1" || tblPr["@_firstRow"] === "true";
+    const hasLastRow = tblPr["@_lastRow"] === "1" || tblPr["@_lastRow"] === "true";
+    const hasBandRow = tblPr["@_bandRow"] === "1" || tblPr["@_bandRow"] === "true";
+    const wholeTbl = styleDef?.wholeTbl?.tcStyle;
+    const firstRowStyle = hasFirstRow ? styleDef?.firstRow?.tcStyle : undefined;
+    const lastRowStyle = hasLastRow ? styleDef?.lastRow?.tcStyle : undefined;
+    const band1H = hasBandRow ? styleDef?.band1H?.tcStyle : undefined;
+    const band2H = hasBandRow ? styleDef?.band2H?.tcStyle : undefined;
+    let cellCount = 0;
+    for (let ri = 0; ri < rowArr.length; ri++) {
+        const row = rowArr[ri];
+        const cells = row.tc;
+        if (!cells)
+            continue;
+        const cellArr = Array.isArray(cells) ? cells : [cells];
+        let activeStyle = wholeTbl;
+        if (ri === 0 && firstRowStyle)
+            activeStyle = firstRowStyle;
+        else if (ri === rowArr.length - 1 && lastRowStyle)
+            activeStyle = lastRowStyle;
+        else if (hasBandRow)
+            activeStyle = (ri % 2 === (hasFirstRow ? 1 : 0)) ? band1H ?? wholeTbl : band2H ?? wholeTbl;
+        for (const cell of cellArr) {
+            if (!cell.tcPr)
+                cell.tcPr = {};
+            const tcPr = cell.tcPr;
+            let modified = false;
+            for (const [xmlSide, styleSide] of [["lnL", "left"], ["lnR", "right"], ["lnT", "top"], ["lnB", "bottom"]]) {
+                if (tcPr[xmlSide])
+                    continue;
+                const border = buildBorder(activeStyle, styleSide) ?? buildBorder(wholeTbl, styleSide);
+                if (border) {
+                    tcPr[xmlSide] = border;
+                    modified = true;
+                }
+            }
+            if (modified)
+                cellCount++;
+        }
+    }
+    if (cellCount > 0) {
+        changes.push(`inlined borders on ${cellCount} table cells`);
+    }
+    return changes;
+}
+export const tableStyles = {
+    name: "table-styles",
+    apply(slideXml, _slideNum, ctx) {
+        const tables = findTables(slideXml);
+        const changes = [];
+        for (const { table } of tables) {
+            if (!tableNeedsFix(table))
+                continue;
+            const styleId = table.tblPr?.["@_tblStyle"] ?? table.tblPr?.tblStyle;
+            if (!styleId)
+                continue;
+            const styleDef = findStyleDef(ctx.tableStyleXml, styleId);
+            if (!styleDef) {
+                changes.push(`table style ${styleId} not found in tableStyles.xml — skipped`);
+                continue;
+            }
+            changes.push(...applyTableStyle(table, styleDef));
+        }
+        return { changed: changes.length > 0, changes };
+    },
+};

package/dist/writer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * XML round-trip writer: parse → mutate → serialize → repack ZIP.
+ *
+ * Transforms operate on fast-xml-parser parsed objects (preserving unknown elements),
+ * then XMLBuilder serializes them back to XML. JSZip repacks the modified ZIP.
+ */
+import { type TransformName } from "./transforms/index.js";
+export interface FixOptions {
+    /** Apply only these transforms (default: all) */
+    transforms?: TransformName[];
+    /** Return a human-readable report of changes */
+    report?: boolean;
+}
+export interface FixResult {
+    buffer: Buffer;
+    report?: string;
+}
+export declare function fix(pptxBuffer: Buffer, options?: FixOptions): Promise<FixResult>;

package/dist/writer.js

@@ -0,0 +1,62 @@
+/**
+ * XML round-trip writer: parse → mutate → serialize → repack ZIP.
+ *
+ * Transforms operate on fast-xml-parser parsed objects (preserving unknown elements),
+ * then XMLBuilder serializes them back to XML. JSZip repacks the modified ZIP.
+ */
+import JSZip from "jszip";
+import { XMLParser, XMLBuilder } from "fast-xml-parser";
+import { xmlParserOptions, xmlBuilderOptions } from "./xml.js";
+import { ALL_TRANSFORMS } from "./transforms/index.js";
+export async function fix(pptxBuffer, options) {
+    const zip = await JSZip.loadAsync(pptxBuffer);
+    const parser = new XMLParser(xmlParserOptions);
+    const builder = new XMLBuilder(xmlBuilderOptions);
+    const reportLines = [];
+    const enabledNames = new Set(options?.transforms ?? ALL_TRANSFORMS.map(t => t.name));
+    const enabled = ALL_TRANSFORMS.filter(t => enabledNames.has(t.name));
+    // Find all slide XML files
+    const slideFiles = Object.keys(zip.files)
+        .filter(f => /^ppt\/slides\/slide\d+\.xml$/.test(f))
+        .sort((a, b) => {
+        const na = parseInt(a.match(/\d+/)[0]);
+        const nb = parseInt(b.match(/\d+/)[0]);
+        return na - nb;
+    });
+    // Load table style XML if needed (for table-styles transform)
+    let tableStyleXml = undefined;
+    if (enabledNames.has("table-styles")) {
+        const tsPath = "ppt/tableStyles.xml";
+        const tsFile = zip.file(tsPath);
+        if (tsFile) {
+            tableStyleXml = parser.parse(await tsFile.async("string"));
+        }
+    }
+    // Process each slide
+    for (const slidePath of slideFiles) {
+        const slideNum = parseInt(slidePath.match(/\d+/)[0]);
+        const xml = await zip.file(slidePath).async("string");
+        const parsed = parser.parse(xml);
+        let changed = false;
+        for (const transform of enabled) {
+            const result = transform.apply(parsed, slideNum, { tableStyleXml });
+            if (result.changed) {
+                changed = true;
+                for (const line of result.changes) {
+                    reportLines.push(`Slide ${slideNum}: ${line}`);
+                }
+            }
+        }
+        if (changed) {
+            zip.file(slidePath, builder.build(parsed));
+        }
+    }
+    const outBuffer = Buffer.from(await zip.generateAsync({ type: "nodebuffer" }));
+    const result = { buffer: outBuffer };
+    if (options?.report) {
+        result.report = reportLines.length > 0
+            ? reportLines.join("\n")
+            : "No issues found — file unchanged.";
+    }
+    return result;
+}

package/dist/xml.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared XML parser/builder options matching OOXML conventions.
+ */
+export declare const xmlParserOptions: {
+    ignoreAttributes: boolean;
+    attributeNamePrefix: string;
+    removeNSPrefix: boolean;
+    parseTagValue: boolean;
+    parseAttributeValue: boolean;
+    trimValues: boolean;
+    isArray: (name: string) => boolean;
+};
+export declare const xmlBuilderOptions: {
+    ignoreAttributes: boolean;
+    attributeNamePrefix: string;
+    format: boolean;
+    suppressEmptyNode: boolean;
+    suppressBooleanAttributes: boolean;
+};

package/dist/xml.js

@@ -0,0 +1,28 @@
+/**
+ * Shared XML parser/builder options matching OOXML conventions.
+ */
+export const xmlParserOptions = {
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    removeNSPrefix: true,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: false,
+    isArray: (name) => ARRAY_ELEMENTS.has(name),
+};
+export const xmlBuilderOptions = {
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    format: false,
+    suppressEmptyNode: false,
+    suppressBooleanAttributes: false,
+};
+/** Elements that must always be parsed as arrays (even with a single child). */
+const ARRAY_ELEMENTS = new Set([
+    "sp", "pic", "cxnSp", "grpSp", "graphicFrame",
+    "p", "r", "br", "fld",
+    "gs", "ln", "solidFill", "gradFill",
+    "tr", "tc",
+    "tblStyleLst",
+    "ext",
+]);

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pptx-fix",
+  "version": "0.2.0",
+  "description": "Fix PowerPoint files that render incorrectly on macOS QuickLook and iOS — resolves missing table borders, invisible shapes, flattened gradients, and opaque blocks caused by OfficeImport rendering gaps.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pptx-fix": "dist/cli.js"
+  },
+  "keywords": [
+    "pptx",
+    "powerpoint",
+    "quicklook",
+    "macos",
+    "ios",
+    "fix",
+    "repair",
+    "officeimport",
+    "ooxml",
+    "office-open-xml",
+    "table-styles",
+    "python-pptx",
+    "pptxgenjs",
+    "presentation",
+    "apple",
+    "preview",
+    "slides",
+    "iphone",
+    "ipad",
+    "finder",
+    "thumbnail",
+    "table-borders",
+    "shapes",
+    "gradients",
+    "rendering",
+    "google-slides",
+    "canva",
+    "libreoffice",
+    "pandoc",
+    "cross-platform",
+    "compatibility"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "fast-xml-parser": "^5.2.0",
+    "jszip": "^3.10.1",
+    "quicklook-pptx-renderer": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}