quicklook-pptx-renderer 0.2.3 → 0.3.1

package/README.md

@@ -22,7 +22,7 @@ It happens because Apple uses a private framework called `OfficeImport.framework
 |---|---|
 | **Shapes disappear** — heart, cloud, lightningBolt, sun, moon, and ~120 more | OfficeImport's `CMCanonicalShapeBuilder` only supports ~60 of 187 preset geometries. The rest are silently dropped — no error, no fallback. |
 | **Opaque white blocks cover content** — rounded rectangles with shadows become solid rectangles | Any non-`rect` shape or any shape with effects (drop shadow, glow, reflection) is rendered as an opaque PDF image via `CMDrawingContext.copyPDF`. The PDF has a non-transparent background. |
-| **Table borders missing** — tables appear as plain text without any grid | OfficeImport doesn't resolve `tableStyleId` references. It only reads explicit `<a:lnL>`, `<a:lnR>`, `<a:lnT>`, `<a:lnB>` on each cell. python-pptx and most generators rely on style references. |
+| **Table borders missing** — tables appear as plain text without any grid | OfficeImport doesn't resolve `tableStyleId` references. It emits `border-style:none` per-cell unless borders are explicit in `<a:lnL>`, `<a:lnR>`, `<a:lnT>`, `<a:lnB>`. PowerPoint resolves the style and shows borders; QuickLook doesn't. python-pptx and most generators rely on style references. |
 | **Gradients become flat colors** — gradient fills show as a single solid color | Gradients with 3+ color stops are averaged to one color instead of being rendered as a gradient. |
 | **Fonts shift and text reflows** — text overflows boxes, lines break differently | Calibri → Helvetica Neue, Arial → Helvetica, Segoe UI → Helvetica Neue. Different metrics cause text reflow. |
 | **Charts are blank rectangles** — chart content simply vanishes | Charts without an embedded fallback image render as empty rectangles. |
@@ -114,24 +114,82 @@ for (const issue of result.issues) {
 }
 ```
 
+### Building Fix Tools
+
+The lint API is designed to power automated PPTX fixers. Each issue's `fix` object tells you exactly what to change — no re-detection needed.
+
+```typescript
+import { lint, SUPPORTED_GEOMETRIES, FONT_SUBSTITUTIONS, GEOMETRY_FALLBACKS } from "quicklook-pptx-renderer";
+
+const result = await lint(pptxBuffer);
+
+for (const issue of result.issues) {
+  if (!issue.fix) continue; // informational only
+
+  switch (issue.fix.action) {
+    case "replace-geometry":
+      // issue.fix.current = "heart", issue.fix.suggested = "ellipse"
+      // Replace <a:prstGeom prst="heart"> with <a:prstGeom prst="ellipse">
+      break;
+
+    case "strip-effects":
+      // Remove <a:effectLst> and <a:effectDag> from the shape
+      break;
+
+    case "reduce-stops":
+      // issue.fix.firstColor = "#FF0000", issue.fix.lastColor = "#0000FF"
+      // issue.fix.averageColor = "#7F007F", issue.fix.angle = 5400000
+      // Replace 3+ gradient stops with 2-stop using first/last colors
+      break;
+
+    case "replace-font":
+      // issue.fix.from = "Calibri", issue.fix.macTarget = "Helvetica Neue"
+      // issue.fix.widthDelta = 14.4, issue.fix.alternatives = [
+      //   { font: "Carlito", widthDelta: 2.1 },
+      //   { font: "Montserrat", widthDelta: 0.4 }
+      // ]
+      break;
+
+    case "inline-borders":
+      // issue.fix.tableStyleId = "{5C22544A-...}"
+      // Resolve table style and write explicit borders on each cell
+      // Note: tables without a style AND without borders are intentionally
+      // borderless — both PowerPoint and QuickLook render them the same way.
+      break;
+
+    case "add-fallback-image":
+      // Generate or embed a chart fallback image via mc:AlternateContent
+      break;
+
+    case "ungroup":
+      // issue.fix.childCount = 5, issue.fix.containsPictures = false
+      // Promote group children to slide-level drawables
+      break;
+  }
+}
+```
+
+Also available: `SUPPORTED_GEOMETRIES` (Set of 60 presets OfficeImport renders), `FONT_SUBSTITUTIONS` (Windows → macOS font map), `GEOMETRY_FALLBACKS` (unsupported → closest supported preset), `findClosestFont()` (metric-based font matching), `widthDelta()` (percentage width difference between fonts).
+
 ---
 
 ## 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 | Table cells lack explicit borders — will appear borderless |
-| `table-style-unresolved` | warn | Table style reference that OfficeImport won't resolve |
-| `text-inscription-shift` | warn | Text in non-rect shape uses geometry-inscribed bounds (text may shift) |
-| `font-substitution` | warn/info | Font will be substituted on macOS — includes width delta (warn if ≥10% reflow risk) |
-| `effect-forces-pdf` | warn | Non-rect shape rendered as opaque PDF instead of CSS |
-| `rotation-forces-pdf` | warn | Rotated rect rendered as opaque PDF instead of CSS |
-| `group-as-pdf` | warn | Group rendered as single opaque PDF image |
-| `vertical-text` | info | Vertical text uses CSS writing-mode |
+Every issue carries a typed `fix` object with machine-readable remediation data — downstream tools can apply transforms without re-detecting the problem.
+
+| Rule | Severity | What It Catches | `fix.action` |
+|------|----------|----------------|-------------|
+| `unsupported-geometry` | error | Shape preset not in OfficeImport's ~60 supported geometries — will be invisible | `replace-geometry` (includes closest supported preset) |
+| `chart-no-fallback` | error | Chart without fallback image — renders as blank rectangle | `add-fallback-image` |
+| `opaque-pdf-block` | warn | Shape with effects rendered as opaque PDF covering content behind it | `strip-effects` |
+| `gradient-flattened` | warn | 3+ gradient stops collapsed to single average color | `reduce-stops` (includes computed 2-stop colors + average) |
+| `table-style-unresolved` | warn | Table has style but cells lack explicit borders — PowerPoint shows borders, QL won't | `inline-borders` (includes `tableStyleId`) |
+| `font-substitution` | warn/info | Font will be substituted on macOS — includes width delta (warn if ≥10% reflow risk) | `replace-font` (includes macOS target, delta, metrically-closest alternatives) |
+| `group-as-pdf` | warn | Group rendered as single opaque PDF image | `ungroup` (includes child count, whether group contains pictures) |
+| `geometry-forces-pdf` | info | Non-rect geometry renders as PDF — opaque background may cover adjacent content | — |
+| `rotation-forces-pdf` | info | Rotated rect renders as PDF — enlarged bounding box may cover adjacent content | — |
+| `text-inscription-shift` | info | Text in non-rect shape uses geometry-inscribed bounds (text may shift) | `replace-geometry` (suggests `rect`) |
+| `vertical-text` | info | Vertical text uses CSS writing-mode | — |
 
 ---
 
@@ -234,10 +292,35 @@ macOS replaces Windows fonts at render time (from `TCFontUtils` in OfficeImport)
 
 **Highest reflow risk**: Calibri Light (+20.9%), Arial Narrow (+20.0%), Corbel (+18.8%), Franklin Gothic Medium (+17.8%), Arial Black (-15.9%), Calibri (+14.4%), Segoe UI (+14.0%), Tahoma (+10.0%).
 
-The linter now reports width deltas and upgrades font substitution to `warn` severity when the delta exceeds ±10%.
+The linter reports width deltas, upgrades font substitution to `warn` severity when the delta exceeds ±10%, and includes metrically-closest cross-platform alternatives in the `fix` data.
 
 Plus CJK mappings: MS Gothic → Hiragino Sans, SimSun → STSong, Microsoft YaHei → PingFang SC, Malgun Gothic → Apple SD Gothic Neo, and more.
 
+### Metric-Compatible Google Fonts (Croscore)
+
+These open-source fonts (SIL OFL) were designed as drop-in replacements for Microsoft core fonts. Width deltas measured from OS/2 tables and included in the font metrics database (135 fonts total):
+
+| Microsoft Font | Google Font Replacement | Width Δ vs Original | License |
+|---|---|---|---|
+| Calibri | **Carlito** | -2.1% | OFL |
+| Cambria | **Caladea** | -5.6% | OFL |
+| Arial | **Arimo** | -1.2% | Apache 2.0 |
+| Times New Roman | **Tinos** | +0.5% | Apache 2.0 |
+| Courier New | **Cousine** | 0.0% | Apache 2.0 |
+
+Compare: Calibri → Helvetica Neue (the QL substitution) is **+14.4%**. Carlito at -2.1% is 7x better.
+
+### What Doesn't Work for Font Fixes
+
+Verified by testing against actual OfficeImport output:
+
+- **Embedded fonts (`<p:embeddedFont>`)**: OfficeImport ignores them completely. No `OADEmbeddedFont` class exists in the framework. Embedding helps PowerPoint and LibreOffice, but not QuickLook.
+- **`pitchFamily` attribute**: OfficeImport ignores it. All unknown fonts produce `font-family:"FontName"` in CSS with no generic family fallback. WebKit then falls back to **serif (Times)** regardless of the pitchFamily hint.
+- **Font stacks / fallback chains**: OOXML supports only one `typeface` per text run. No CSS-like `font-family: "Carlito", "Calibri", sans-serif` — it's a single value.
+- **Parent font inheritance as fallback**: OOXML property inheritance only applies when the property is **missing**, not when the font isn't installed. If a run specifies `typeface="Carlito"`, the parent's `typeface="Arial"` is not used as a fallback.
+
+**The only way to control fonts in QuickLook is to use a font that macOS has installed.** The `FONT_SUBSTITUTIONS` map and `findClosestFont()` API provide the data to pick the best replacement.
+
 ---
 
 ## Key Discoveries
@@ -252,6 +335,8 @@ These findings come from reverse engineering OfficeImport via Objective-C runtim
 6. **3+ gradient stops → average color** (not rendered as gradient)
 7. **Font substitution**: Calibri → Helvetica Neue, Arial → Helvetica, etc. (full map above)
 8. **Text inscription for non-rect shapes** uses `float` radius and `trunc()` in pixel space
+9. **Embedded fonts are ignored** — no `OADEmbeddedFont` class; `TCImportFontCache` only does CoreText system font lookup
+10. **`pitchFamily` is ignored** — all unknown fonts get bare `font-family:"Name"` in CSS with no generic family fallback, regardless of pitchFamily value
 
 ---
 

package/dist/index.d.ts

@@ -20,11 +20,12 @@ export interface RenderResult {
  * 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 { lint, formatIssues, GEOMETRY_FALLBACKS, type LintResult, type LintIssue, type LintFix, 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 { resolveFontFamily, FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
 export { FONT_METRICS, findClosestFont, widthDelta, type FontMetrics, type FontMatch, type FontCategory } from "./resolve/font-metrics.js";
+export { SUPPORTED_GEOMETRIES } from "./mapper/shape-mapper.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

@@ -63,11 +63,12 @@ export async function render(pptxBuffer) {
     return { slides, fullHtml: html, attachments };
 }
 // ── Linter (QuickLook compatibility checks) ─────────────────────
-export { lint, formatIssues } from "./lint.js";
+export { lint, formatIssues, GEOMETRY_FALLBACKS } 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";
+export { resolveFontFamily, FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
 export { FONT_METRICS, findClosestFont, widthDelta } from "./resolve/font-metrics.js";
+export { SUPPORTED_GEOMETRIES } from "./mapper/shape-mapper.js";

package/dist/lint.d.ts

@@ -3,9 +3,45 @@
  *
  * Parses a PPTX and checks every shape, text run, table, and fill against
  * known OfficeImport quirks. No rendering required — just parse and check.
+ *
+ * Each issue carries a typed `fix` object with machine-readable remediation
+ * data so downstream tools (like pptx-fix) can apply transforms without
+ * re-detecting the problem.
  */
 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 type RuleId = "unsupported-geometry" | "opaque-pdf-block" | "gradient-flattened" | "font-substitution" | "table-style-unresolved" | "group-as-pdf" | "chart-no-fallback" | "text-inscription-shift" | "rotation-forces-pdf" | "geometry-forces-pdf" | "vertical-text";
+/** Machine-readable remediation data — one variant per fix strategy. */
+export type LintFix = {
+    action: "replace-geometry";
+    current: string;
+    suggested: string;
+} | {
+    action: "strip-effects";
+} | {
+    action: "reduce-stops";
+    firstColor: string;
+    lastColor: string;
+    averageColor: string;
+    angle?: number;
+} | {
+    action: "replace-font";
+    from: string;
+    macTarget: string;
+    widthDelta: number;
+    alternatives: Array<{
+        font: string;
+        widthDelta: number;
+    }>;
+} | {
+    action: "inline-borders";
+    tableStyleId: string;
+} | {
+    action: "add-fallback-image";
+} | {
+    action: "ungroup";
+    childCount: number;
+    containsPictures: boolean;
+};
 export interface LintIssue {
     rule: RuleId;
     severity: Severity;
@@ -13,6 +49,7 @@ export interface LintIssue {
     element?: string;
     message: string;
     suggestion?: string;
+    fix?: LintFix;
 }
 export interface LintResult {
     issues: LintIssue[];
@@ -23,5 +60,7 @@ export interface LintResult {
         slides: number;
     };
 }
+/** Maps commonly-used unsupported OOXML presets to visually-closest supported alternative. */
+export declare const GEOMETRY_FALLBACKS: Record<string, string>;
 export declare function lint(pptxBuffer: Buffer): Promise<LintResult>;
 export declare function formatIssues(result: LintResult): string;

package/dist/lint.js

@@ -3,35 +3,95 @@
  *
  * Parses a PPTX and checks every shape, text run, table, and fill against
  * known OfficeImport quirks. No rendering required — just parse and check.
+ *
+ * Each issue carries a typed `fix` object with machine-readable remediation
+ * data so downstream tools (like pptx-fix) can apply transforms without
+ * re-detecting the problem.
  */
 import { PptxPackage } from "./package/package.js";
 import { readPresentation } from "./reader/presentation.js";
 import { SUPPORTED_GEOMETRIES } from "./mapper/shape-mapper.js";
-import { FONT_METRICS, widthDelta } from "./resolve/font-metrics.js";
-// ── Font substitution table (same as resolve/font-map.ts) ───────────
-const SUBSTITUTED_FONTS = {
-    "Calibri": "Helvetica Neue",
-    "Calibri Light": "Helvetica Neue Light",
-    "Arial": "Helvetica",
-    "Arial Black": "Helvetica Neue",
-    "Arial Narrow": "Helvetica Neue",
-    "Cambria": "Georgia",
-    "Consolas": "Menlo",
-    "Courier New": "Courier",
-    "Times New Roman": "Times",
-    "Tahoma": "Geneva",
-    "Segoe UI": "Helvetica Neue",
-    "Segoe UI Light": "Helvetica Neue Light",
-    "Segoe UI Semibold": "Helvetica Neue Medium",
-    "Century Gothic": "Futura",
-    "Franklin Gothic Medium": "Avenir Next Medium",
-    "Corbel": "Avenir Next",
-    "Candara": "Avenir",
-    "Constantia": "Georgia",
+import { FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
+import { FONT_METRICS, widthDelta, findClosestFont } from "./resolve/font-metrics.js";
+import { resolveColor } from "./resolve/color-resolver.js";
+// ── Geometry fallback map (unsupported → closest supported) ────────
+/** Maps commonly-used unsupported OOXML presets to visually-closest supported alternative. */
+export const GEOMETRY_FALLBACKS = {
+    // Rounded rect variants → roundRect
+    round1Rect: "roundRect", round2SameRect: "roundRect", round2DiagRect: "roundRect",
+    snipRoundRect: "roundRect", plaque: "roundRect",
+    // Snip rect variants → rect
+    snip1Rect: "rect", snip2SameRect: "rect", snip2DiagRect: "rect",
+    // Organic shapes → ellipse
+    heart: "ellipse", donut: "ellipse", noSmoking: "ellipse",
+    smileyFace: "ellipse", sun: "ellipse", moon: "ellipse", blockArc: "ellipse",
+    // Angular shapes → closest polygon
+    decagon: "octagon", heptagon: "hexagon", dodecagon: "octagon",
+    // Arrows (unsupported variants → closest supported arrow)
+    bentArrow: "rightArrow", curvedLeftArrow: "leftArrow",
+    curvedRightArrow: "rightArrow", curvedUpArrow: "upArrow",
+    curvedDownArrow: "downArrow", notchedRightArrow: "rightArrow",
+    stripedRightArrow: "rightArrow", uturnArrow: "downArrow",
+    // Flowcharts → closest match
+    flowChartProcess: "rect", flowChartTerminator: "roundRect",
+    flowChartDocument: "rect", flowChartInputOutput: "parallelogram",
+    flowChartPreparation: "hexagon", flowChartManualInput: "trapezoid",
+    flowChartManualOperation: "trapezoid", flowChartConnector: "ellipse",
+    flowChartPredefinedProcess: "rect", flowChartInternalStorage: "rect",
+    flowChartMultidocument: "rect", flowChartOffpageConnector: "pentagon",
+    flowChartPunchedCard: "rect", flowChartPunchedTape: "rect",
+    flowChartSummingJunction: "ellipse", flowChartOr: "ellipse",
+    flowChartCollate: "diamond", flowChartSort: "diamond",
+    flowChartExtract: "triangle", flowChartMerge: "triangle",
+    flowChartOnlineStorage: "can", flowChartDelay: "roundRect",
+    flowChartMagneticTape: "ellipse", flowChartMagneticDisk: "can",
+    flowChartMagneticDrum: "can", flowChartDisplay: "roundRect",
+    // Misc
+    foldedCorner: "rect", frame: "rect", bevel: "rect",
+    lightningBolt: "rightArrow", cloud: "cloudCallout",
+    ribbon: "rect", ribbon2: "rect",
+    horizontalScroll: "verticalScroll",
+    wave: "rect", doubleWave: "rect",
+    // Callout variants → closest supported callout
+    callout1: "borderCallout1", callout2: "borderCallout1", callout3: "borderCallout1",
+    accentCallout1: "borderCallout1", accentCallout2: "borderCallout1", accentCallout3: "borderCallout1",
+    accentBorderCallout1: "borderCallout1", accentBorderCallout2: "borderCallout1", accentBorderCallout3: "borderCallout1",
+    borderCallout2: "borderCallout1", borderCallout3: "borderCallout1",
+    // Math → plus (only supported math-like shape)
+    mathPlus: "plus", mathMinus: "rect", mathMultiply: "plus",
+    mathDivide: "rect", mathEqual: "rect", mathNotEqual: "rect",
+    // Brackets/braces → rect fallback
+    leftBrace: "rect", rightBrace: "rect", leftBracket: "rect", rightBracket: "rect",
+    bracePair: "rect", bracketPair: "rect",
+    // Stars (unsupported sizes) → closest supported star
+    star7: "star8",
+    // Action buttons → rect
+    actionButtonBlank: "rect", actionButtonHome: "rect", actionButtonHelp: "rect",
+    actionButtonInformation: "rect", actionButtonBackPrevious: "rect",
+    actionButtonForwardNext: "rect", actionButtonBeginning: "rect",
+    actionButtonEnd: "rect", actionButtonReturn: "rect",
+    actionButtonDocument: "rect", actionButtonSound: "rect",
+    actionButtonMovie: "rect",
+    // Misc exotic
+    gear6: "hexagon", gear9: "octagon",
+    funnel: "triangle", pie: "ellipse", pieWedge: "triangle",
+    irregularSeal1: "diamond", irregularSeal2: "diamond",
 };
+// Geometries where text inscription differs from a simple rect inset
+const NON_RECT_TEXT_GEOMETRIES = new Set([
+    "roundRect", "ellipse", "diamond", "triangle", "rtTriangle",
+    "parallelogram", "trapezoid", "hexagon", "octagon", "pentagon",
+    "star4", "star5", "star6", "star8",
+]);
+function rgbaToHex(c) {
+    const r = c.r.toString(16).padStart(2, "0");
+    const g = c.g.toString(16).padStart(2, "0");
+    const b = c.b.toString(16).padStart(2, "0");
+    return `#${r}${g}${b}`;
+}
 /** Compute width delta between a source font and its OfficeImport substitute. */
 function fontWidthDelta(sourceName) {
-    const targetName = SUBSTITUTED_FONTS[sourceName];
+    const targetName = FONT_SUBSTITUTIONS[sourceName];
     if (!targetName)
         return null;
     const src = FONT_METRICS[sourceName];
@@ -40,12 +100,6 @@ function fontWidthDelta(sourceName) {
         return null;
     return widthDelta(src, tgt);
 }
-// Geometries where text inscription differs from a simple rect inset
-const NON_RECT_TEXT_GEOMETRIES = new Set([
-    "roundRect", "ellipse", "diamond", "triangle", "rtTriangle",
-    "parallelogram", "trapezoid", "hexagon", "octagon", "pentagon",
-    "star4", "star5", "star6", "star8",
-]);
 // ── Main API ────────────────────────────────────────────────────────
 export async function lint(pptxBuffer) {
     const pkg = await PptxPackage.open(pptxBuffer);
@@ -54,7 +108,14 @@ export async function lint(pptxBuffer) {
     for (let i = 0; i < pres.slides.length; i++) {
         const slide = pres.slides[i];
         const slideNum = i + 1;
-        lintDrawables(slide.drawables, slideNum, issues);
+        const master = slide.slideLayout.slideMaster;
+        const ctx = {
+            colorMap: slide.colorMapOverride
+                ?? slide.slideLayout.colorMapOverride
+                ?? master.colorMap,
+            colorScheme: master.theme.colorScheme,
+        };
+        lintDrawables(slide.drawables, slideNum, issues, ctx);
     }
     // Deduplicate font substitution warnings (one per font, not per run)
     deduplicateFonts(issues);
@@ -69,39 +130,41 @@ export async function lint(pptxBuffer) {
     };
 }
 // ── Drawable walker ─────────────────────────────────────────────────
-function lintDrawables(drawables, slide, issues) {
+function lintDrawables(drawables, slide, issues, ctx) {
     for (const d of drawables) {
         switch (d.drawableType) {
             case "sp":
-                lintShape(d, slide, issues);
+                lintShape(d, slide, issues, ctx);
                 break;
             case "pic":
                 lintPicture(d, slide, issues);
                 break;
             case "grpSp":
-                lintGroup(d, slide, issues);
+                lintGroup(d, slide, issues, ctx);
                 break;
             case "cxnSp":
                 lintConnector(d, slide, issues);
                 break;
             case "graphicFrame":
-                lintGraphicFrame(d, slide, issues);
+                lintGraphicFrame(d, slide, issues, ctx);
                 break;
         }
     }
 }
 // ── Shape checks ────────────────────────────────────────────────────
-function lintShape(shape, slide, issues) {
+function lintShape(shape, slide, issues, ctx) {
     const geom = shape.geometry?.preset ?? "rect";
     const name = shape.name || `shape #${shape.id}`;
     // 1. Unsupported geometry → invisible
     if (geom !== "rect" && !SUPPORTED_GEOMETRIES.has(geom)) {
+        const suggested = GEOMETRY_FALLBACKS[geom] ?? "rect";
         issues.push({
             rule: "unsupported-geometry",
             severity: "error",
             slide, element: name,
             message: `"${geom}" is not supported by OfficeImport — this shape will be invisible in QuickLook`,
-            suggestion: `Use a supported preset (rect, roundRect, ellipse, etc.) or embed as an image`,
+            suggestion: `Replace with "${suggested}" (closest supported preset) or embed as an image`,
+            fix: { action: "replace-geometry", current: geom, suggested },
         });
         return; // no point checking further
     }
@@ -116,24 +179,24 @@ function lintShape(shape, slide, issues) {
                 slide, element: name,
                 message: `"${geom}" with effects renders as an opaque PDF image — it will cover content behind it with a white background`,
                 suggestion: `Remove drop shadow/glow effects, or use a plain rect to keep CSS rendering`,
+                fix: { action: "strip-effects" },
             });
         }
         else if (geom !== "rect") {
             issues.push({
-                rule: "effect-forces-pdf",
-                severity: "warn",
+                rule: "geometry-forces-pdf",
+                severity: "info",
                 slide, element: name,
-                message: `"${geom}" renders as PDF in QuickLook (only plain rect uses CSS)`,
-                suggestion: `Use rect geometry to keep CSS rendering, or accept PDF output`,
+                message: `"${geom}" renders as PDF in QuickLook (only plain rect uses CSS) — opaque background may cover adjacent content`,
             });
         }
         if (hasRotation && geom === "rect") {
+            const rotDeg = Math.round((shape.bounds.rot / 60000) % 360);
             issues.push({
                 rule: "rotation-forces-pdf",
-                severity: "warn",
+                severity: "info",
                 slide, element: name,
-                message: `Rotated rect renders as PDF instead of CSS div`,
-                suggestion: `Remove rotation or accept PDF rendering`,
+                message: `Rotated rect (${rotDeg}°) renders as PDF — enlarged bounding box may cover adjacent content`,
             });
         }
     }
@@ -145,20 +208,22 @@ function lintShape(shape, slide, issues) {
             slide, element: name,
             message: `rect with effects (shadow/glow) renders as opaque PDF — covers content behind it`,
             suggestion: `Remove effects to keep lightweight CSS rendering`,
+            fix: { action: "strip-effects" },
         });
     }
     // 4. Non-rect text inscription shift
     if (NON_RECT_TEXT_GEOMETRIES.has(geom) && hasNonEmptyText(shape.textBody)) {
         issues.push({
             rule: "text-inscription-shift",
-            severity: "warn",
+            severity: "info",
             slide, element: name,
             message: `Text in "${geom}" uses geometry-inscribed bounds — text position will differ from PowerPoint`,
             suggestion: `Use rect for predictable text positioning, or test the specific geometry`,
+            fix: { action: "replace-geometry", current: geom, suggested: "rect" },
         });
     }
     // 5. Gradient flattening
-    lintFill(shape.fill, slide, name, issues);
+    lintFill(shape.fill, slide, name, issues, ctx);
     // 6. Font substitution in text
     if (shape.textBody)
         lintTextBody(shape.textBody, slide, name, issues);
@@ -177,24 +242,26 @@ function lintPicture(_pic, _slide, _issues) {
     // Pictures are straightforward — OfficeImport handles them well
 }
 // ── Group checks ────────────────────────────────────────────────────
-function lintGroup(group, slide, issues) {
+function lintGroup(group, slide, issues, ctx) {
     const name = group.name || `group #${group.id}`;
+    const containsPictures = group.children.some(c => c.drawableType === "pic");
     issues.push({
         rule: "group-as-pdf",
         severity: "warn",
         slide, element: name,
-        message: `Group renders as single PDF image in QuickLook — all children merged into one opaque block`,
+        message: `Group (${group.children.length} children) renders as single PDF image in QuickLook — all children merged into one opaque block`,
         suggestion: `Ungroup shapes for individual rendering, or accept merged PDF`,
+        fix: { action: "ungroup", childCount: group.children.length, containsPictures },
     });
     // Still lint children for their own issues
-    lintDrawables(group.children, slide, issues);
+    lintDrawables(group.children, slide, issues, ctx);
 }
 // ── Connector checks ────────────────────────────────────────────────
 function lintConnector(_conn, _slide, _issues) {
     // Connectors are always PDF, no special warnings needed
 }
 // ── GraphicFrame (tables/charts) ────────────────────────────────────
-function lintGraphicFrame(frame, slide, issues) {
+function lintGraphicFrame(frame, slide, issues, ctx) {
     const name = frame.name || `frame #${frame.id}`;
     // Chart without fallback image
     if (frame.chartRId && !frame.fallbackImageData) {
@@ -204,15 +271,19 @@ function lintGraphicFrame(frame, slide, issues) {
             slide, element: name,
             message: `Chart has no fallback image — will render as blank rectangle in QuickLook`,
             suggestion: `Save from PowerPoint (not python-pptx) to generate fallback images, or use mc:AlternateContent`,
+            fix: { action: "add-fallback-image" },
         });
     }
     // Table checks
     if (frame.tableData) {
-        lintTable(frame.tableData, slide, name, issues);
+        lintTable(frame.tableData, slide, name, issues, ctx);
     }
 }
-function lintTable(table, slide, element, issues) {
-    // Check for table style reference without explicit borders
+function lintTable(table, slide, element, issues, ctx) {
+    // Check for table style reference without explicit borders.
+    // OfficeImport emits `border-style:none` per-cell unless borders are explicit in XML.
+    // It ignores tableStyleId entirely — PowerPoint resolves the style and shows borders,
+    // but QuickLook shows a borderless grid. This is the #1 table issue for python-pptx users.
     if (table.tableStyleId) {
         const hasMissingBorders = table.rows.some(row => row.cells.some(cell => !hasExplicitBorders(cell)));
         if (hasMissingBorders) {
@@ -220,29 +291,21 @@ function lintTable(table, slide, element, issues) {
                 rule: "table-style-unresolved",
                 severity: "warn",
                 slide, element,
-                message: `Table uses style "${table.tableStyleId}" but some cells lack explicit borders — OfficeImport may not resolve the style`,
-                suggestion: `Set borders explicitly on each cell (cell.border_top, etc.)`,
+                message: `Table uses style "${table.tableStyleId}" but cells lack explicit borders — PowerPoint shows borders, QuickLook won't`,
+                suggestion: `Inline the style's borders as explicit <a:lnT>/<a:lnB>/<a:lnL>/<a:lnR> on each cell`,
+                fix: { action: "inline-borders", tableStyleId: table.tableStyleId },
             });
         }
     }
-    // Check for cells with no borders at all
-    const noBorderCells = table.rows.reduce((count, row) => count + row.cells.filter(cell => !cell.hMerge && !cell.vMerge && !hasAnyBorder(cell)).length, 0);
-    const totalCells = table.rows.reduce((count, row) => count + row.cells.filter(cell => !cell.hMerge && !cell.vMerge).length, 0);
-    if (noBorderCells > 0 && noBorderCells === totalCells) {
-        issues.push({
-            rule: "table-missing-borders",
-            severity: "warn",
-            slide, element,
-            message: `All ${totalCells} table cells have no explicit borders — table will appear borderless in QuickLook`,
-            suggestion: `Add explicit borders to cells if borders are expected`,
-        });
-    }
+    // Note: tables without a style AND without explicit borders are intentionally borderless.
+    // OfficeImport correctly renders them with border-style:none. No lint issue needed.
+    // (PowerPoint also shows these as borderless — no divergence.)
     // Lint text in table cells
     for (const row of table.rows) {
         for (const cell of row.cells) {
             if (cell.textBody)
                 lintTextBody(cell.textBody, slide, element, issues);
-            lintFill(cell.fill, slide, element, issues);
+            lintFill(cell.fill, slide, element, issues, ctx);
         }
     }
 }
@@ -252,24 +315,38 @@ function hasExplicitBorders(cell) {
     const b = cell.borders;
     return !!(b.top?.fill || b.bottom?.fill || b.left?.fill || b.right?.fill);
 }
-function hasAnyBorder(cell) {
-    if (!cell.borders)
-        return false;
-    const b = cell.borders;
-    return !!(b.top?.width || b.bottom?.width || b.left?.width || b.right?.width);
-}
 // ── Fill checks ─────────────────────────────────────────────────────
-function lintFill(fill, slide, element, issues) {
+function lintFill(fill, slide, element, issues, ctx) {
     if (!fill || fill.type !== "gradient")
         return;
     const grad = fill;
     if (grad.stops.length >= 3) {
+        // Compute resolved colors for fix data
+        let firstColor = "#888888", lastColor = "#888888", averageColor = "#888888";
+        try {
+            const first = resolveColor(grad.stops[0].color, ctx.colorMap, ctx.colorScheme);
+            const last = resolveColor(grad.stops[grad.stops.length - 1].color, ctx.colorMap, ctx.colorScheme);
+            firstColor = rgbaToHex(first);
+            lastColor = rgbaToHex(last);
+            let r = 0, g = 0, b = 0;
+            for (const stop of grad.stops) {
+                const c = resolveColor(stop.color, ctx.colorMap, ctx.colorScheme);
+                r += c.r;
+                g += c.g;
+                b += c.b;
+            }
+            const n = grad.stops.length;
+            averageColor = rgbaToHex({ r: Math.round(r / n), g: Math.round(g / n), b: Math.round(b / n), a: 1 });
+        }
+        catch { /* color resolution may fail for exotic color types */ }
+        const angle = grad.linear?.angle;
         issues.push({
             rule: "gradient-flattened",
             severity: "warn",
             slide, element,
-            message: `Gradient with ${grad.stops.length} stops will be flattened to a single average color in QuickLook`,
-            suggestion: `Use exactly 2 gradient stops for proper rendering, or accept flat color`,
+            message: `Gradient with ${grad.stops.length} stops will be flattened to a single average color (${averageColor}) in QuickLook`,
+            suggestion: `Use exactly 2 gradient stops for proper rendering — first: ${firstColor}, last: ${lastColor}`,
+            fix: { action: "reduce-stops", firstColor, lastColor, averageColor, angle },
         });
     }
 }
@@ -283,18 +360,37 @@ function lintTextBody(body, slide, element, issues) {
             if (!props)
                 continue;
             const font = props.latinFont;
-            if (font && SUBSTITUTED_FONTS[font]) {
+            if (font && FONT_SUBSTITUTIONS[font]) {
+                const macTarget = FONT_SUBSTITUTIONS[font];
                 const delta = fontWidthDelta(font);
                 const deltaStr = delta != null && Math.abs(delta) >= 0.5
                     ? ` (${delta > 0 ? "+" : ""}${delta.toFixed(1)}% width)`
                     : "";
                 const highRisk = delta != null && Math.abs(delta) >= 10;
+                // Find metrically-closest alternatives (consumer decides which to use)
+                const alternatives = [];
+                if (FONT_METRICS[font]) {
+                    const matches = findClosestFont(font, { limit: 5 });
+                    for (const m of matches) {
+                        alternatives.push({ font: m.font, widthDelta: m.widthDelta });
+                    }
+                }
+                const bestAlt = alternatives[0];
                 issues.push({
                     rule: "font-substitution",
                     severity: highRisk ? "warn" : "info",
                     slide, element,
-                    message: `"${font}" → "${SUBSTITUTED_FONTS[font]}" on macOS${deltaStr}${highRisk ? " — high risk of text reflow/overflow" : ""}`,
-                    suggestion: highRisk ? `Use a cross-platform font (Verdana, Georgia, Trebuchet MS, Arial) or test text layout on macOS` : undefined,
+                    message: `"${font}" → "${macTarget}" on macOS${deltaStr}${highRisk ? " — high risk of text reflow/overflow" : ""}`,
+                    suggestion: highRisk
+                        ? `Closest alternative: ${bestAlt ? `${bestAlt.font} (${bestAlt.widthDelta > 0 ? "+" : ""}${bestAlt.widthDelta.toFixed(1)}% width)` : "test on macOS"}`
+                        : undefined,
+                    fix: {
+                        action: "replace-font",
+                        from: font,
+                        macTarget,
+                        widthDelta: delta ?? 0,
+                        alternatives,
+                    },
                 });
             }
         }

package/dist/resolve/font-map.d.ts

@@ -1,2 +1,3 @@
 import type { FontScheme } from "../model/types.js";
+export declare const FONT_SUBSTITUTIONS: Record<string, string>;
 export declare function resolveFontFamily(family: string | undefined, fontScheme?: FontScheme): string;

package/dist/resolve/font-map.js

@@ -1,5 +1,5 @@
 // ── macOS font substitution (mirrors TCFontUtils from OfficeImport) ─
-const FONT_MAP = {
+export const FONT_SUBSTITUTIONS = {
     "Calibri": "Helvetica Neue",
     "Calibri Light": "Helvetica Neue Light",
     "Arial": "Helvetica",

package/dist/resolve/font-metrics.js

@@ -84,6 +84,32 @@ export const FONT_METRICS = {
     "PT Serif": { cat: "serif", upm: 1000, xWidthAvg: 448, capH: 700, xH: 500, asc: 1039, desc: -286, lineGap: 0 },
     "Ubuntu": { cat: "sans-serif", upm: 1000, xWidthAvg: 455, capH: 693, xH: 520, asc: 932, desc: -189, lineGap: 28 },
     "Ubuntu Mono": { cat: "monospace", upm: 1000, xWidthAvg: 500, capH: 693, xH: 520, asc: 830, desc: -170, lineGap: 0 },
+    // ── Croscore — metric-compatible Google Fonts (OS/2 table) ────────
+    "Carlito": { cat: "sans-serif", upm: 2048, xWidthAvg: 1048, capH: 1314, xH: 978, asc: 1536, desc: -512, lineGap: 452 },
+    "Caladea": { cat: "serif", upm: 1000, xWidthAvg: 510, capH: 667, xH: 467, asc: 900, desc: -250, lineGap: 0 },
+    "Arimo": { cat: "sans-serif", upm: 2048, xWidthAvg: 1190, capH: 1409, xH: 1082, asc: 1854, desc: -434, lineGap: 67 },
+    "Tinos": { cat: "serif", upm: 2048, xWidthAvg: 1116, capH: 1341, xH: 940, asc: 1420, desc: -442, lineGap: 307 },
+    "Cousine": { cat: "monospace", upm: 2048, xWidthAvg: 1229, capH: 1349, xH: 1082, asc: 1255, desc: -386, lineGap: 0 },
+    // ── More Google Fonts (OS/2 table) ────────────────────────────────
+    "DM Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 553, capH: 700, xH: 526, asc: 992, desc: -310, lineGap: 0 },
+    "Work Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 597, capH: 660, xH: 500, asc: 930, desc: -243, lineGap: 0 },
+    "Rubik": { cat: "sans-serif", upm: 1000, xWidthAvg: 622, capH: 700, xH: 520, asc: 935, desc: -250, lineGap: 0 },
+    "Libre Baskerville": { cat: "serif", upm: 1000, xWidthAvg: 654, capH: 770, xH: 530, asc: 970, desc: -270, lineGap: 0 },
+    "Libre Franklin": { cat: "sans-serif", upm: 1000, xWidthAvg: 589, capH: 742, xH: 530, asc: 966, desc: -246, lineGap: 0 },
+    "Barlow": { cat: "sans-serif", upm: 1000, xWidthAvg: 513, capH: 700, xH: 506, asc: 1000, desc: -200, lineGap: 0 },
+    "Josefin Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 547, capH: 702, xH: 378, asc: 750, desc: -250, lineGap: 0 },
+    "Quicksand": { cat: "sans-serif", upm: 1000, xWidthAvg: 541, capH: 700, xH: 503, asc: 1000, desc: -250, lineGap: 0 },
+    "Cabin": { cat: "sans-serif", upm: 2000, xWidthAvg: 1054, capH: 1400, xH: 980, asc: 1930, desc: -500, lineGap: 0 },
+    "Karla": { cat: "sans-serif", upm: 2000, xWidthAvg: 1055, capH: 1256, xH: 956, asc: 1834, desc: -504, lineGap: 0 },
+    "Manrope": { cat: "sans-serif", upm: 2000, xWidthAvg: 1131, capH: 1440, xH: 1080, asc: 2132, desc: -600, lineGap: 0 },
+    "Space Grotesk": { cat: "sans-serif", upm: 1000, xWidthAvg: 559, capH: 700, xH: 486, asc: 984, desc: -292, lineGap: 0 },
+    "IBM Plex Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 592, capH: 698, xH: 516, asc: 1025, desc: -275, lineGap: 0 },
+    "IBM Plex Mono": { cat: "monospace", upm: 1000, xWidthAvg: 600, capH: 698, xH: 516, asc: 1025, desc: -275, lineGap: 0 },
+    "JetBrains Mono": { cat: "monospace", upm: 1000, xWidthAvg: 602, capH: 730, xH: 550, asc: 1020, desc: -300, lineGap: 0 },
+    "Bitter": { cat: "serif", upm: 1000, xWidthAvg: 590, capH: 692, xH: 522, asc: 935, desc: -265, lineGap: 0 },
+    "Crimson Text": { cat: "serif", upm: 1024, xWidthAvg: 547, capH: 656, xH: 430, asc: 972, desc: -359, lineGap: 0 },
+    "EB Garamond": { cat: "serif", upm: 1000, xWidthAvg: 528, capH: 650, xH: 400, asc: 1007, desc: -298, lineGap: 0 },
+    "Zilla Slab": { cat: "serif", upm: 1000, xWidthAvg: 538, capH: 650, xH: 445, asc: 787, desc: -213, lineGap: 200 },
 };
 // ── Similarity matching ─────────────────────────────────────────────
 /** Normalize a metric by unitsPerEm so fonts at different scales are comparable. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quicklook-pptx-renderer",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Open-source PPTX rendering engine that replicates Apple's macOS QuickLook and iOS preview — pixel for pixel. Test how PowerPoint files look on Mac/iPhone without a Mac.",
   "type": "module",
   "main": "dist/index.js",