quicklook-pptx-renderer 0.3.2 → 0.3.3

package/README.md

@@ -167,14 +167,14 @@ for (const issue of result.issues) {
       break;
 
     case "strip-embedded-fonts":
-      // issue.fix.fonts = [{ name: "Montserrat", replacement: "Nunito Sans" }]
+      // issue.fix.fonts = [{ name: "Montserrat", replacement: "DIN Alternate" }]
       // Strip embedded font data and replace with cross-platform alternatives
       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).
+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 with narrower-preference), `widthDelta()` (percentage width difference between fonts), `APPLE_SYSTEM_FONTS` (29 fonts preinstalled on both macOS and iOS), `MACOS_SYSTEM_FONTS` (38 fonts on macOS).
 
 ---
 
@@ -304,7 +304,7 @@ Plus CJK mappings: MS Gothic → Hiragino Sans, SimSun → STSong, Microsoft YaH
 
 ### 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):
+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 (106 fonts total):
 
 | Microsoft Font | Google Font Replacement | Width Δ vs Original | License |
 |---|---|---|---|
@@ -325,7 +325,14 @@ Verified by testing against actual OfficeImport output:
 - **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.
+**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. Use `APPLE_SYSTEM_FONT_LIST` as candidates to ensure results work on both macOS and iOS:
+
+```typescript
+import { findClosestFont, APPLE_SYSTEM_FONT_LIST } from "quicklook-pptx-renderer";
+
+// Montserrat → DIN Alternate (-4.3% width) — narrower is preferred over wider
+const [best] = findClosestFont("Montserrat", { candidates: APPLE_SYSTEM_FONT_LIST });
+```
 
 ---
 

package/dist/index.d.ts

@@ -26,6 +26,6 @@ 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, FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
-export { FONT_METRICS, findClosestFont, widthDelta, type FontMetrics, type FontMatch, type FontCategory } from "./resolve/font-metrics.js";
+export { FONT_METRICS, findClosestFont, widthDelta, APPLE_SYSTEM_FONTS, APPLE_SYSTEM_FONT_LIST, MACOS_SYSTEM_FONTS, MACOS_SYSTEM_FONT_LIST, 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

@@ -70,5 +70,5 @@ export { readPresentation } from "./reader/presentation.js";
 export { generateHtml } from "./mapper/html-generator.js";
 export { resolveColor } from "./resolve/color-resolver.js";
 export { resolveFontFamily, FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
-export { FONT_METRICS, findClosestFont, widthDelta } from "./resolve/font-metrics.js";
+export { FONT_METRICS, findClosestFont, widthDelta, APPLE_SYSTEM_FONTS, APPLE_SYSTEM_FONT_LIST, MACOS_SYSTEM_FONTS, MACOS_SYSTEM_FONT_LIST, } from "./resolve/font-metrics.js";
 export { SUPPORTED_GEOMETRIES } from "./mapper/shape-mapper.js";

package/dist/lint.js

@@ -12,7 +12,7 @@ import { PptxPackage } from "./package/package.js";
 import { readPresentation } from "./reader/presentation.js";
 import { SUPPORTED_GEOMETRIES } from "./mapper/shape-mapper.js";
 import { FONT_SUBSTITUTIONS } from "./resolve/font-map.js";
-import { FONT_METRICS, widthDelta, findClosestFont } from "./resolve/font-metrics.js";
+import { FONT_METRICS, widthDelta, findClosestFont, APPLE_SYSTEM_FONT_LIST } 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. */
@@ -111,7 +111,7 @@ export async function lint(pptxBuffer) {
     const embFontLst = presNode.embeddedFontLst?.embeddedFont;
     if (embFontLst) {
         const entries = Array.isArray(embFontLst) ? embFontLst : [embFontLst];
-        const safeCandidates = Object.keys(FONT_METRICS).filter(f => !FONT_SUBSTITUTIONS[f]);
+        const safeCandidates = APPLE_SYSTEM_FONT_LIST;
         const fonts = [];
         for (const entry of entries) {
             const name = entry.font?.["@_typeface"];
@@ -404,7 +404,7 @@ function lintTextBody(body, slide, element, issues) {
                 // Find metrically-closest alternatives (consumer decides which to use)
                 const alternatives = [];
                 if (FONT_METRICS[font]) {
-                    const matches = findClosestFont(font, { limit: 5 });
+                    const matches = findClosestFont(font, { candidates: APPLE_SYSTEM_FONT_LIST, limit: 5 });
                     for (const m of matches) {
                         alternatives.push({ font: m.font, widthDelta: m.widthDelta });
                     }

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

@@ -35,6 +35,22 @@ export interface FontMetrics {
  * @capsizecss/metrics (capsize.dev), which is approximate.
  */
 export declare const FONT_METRICS: Record<string, FontMetrics>;
+/**
+ * Fonts preinstalled on BOTH macOS and iOS.
+ * Only includes fonts that have entries in FONT_METRICS above.
+ * Use as `candidates` in findClosestFont() to ensure the result is a real system font.
+ */
+export declare const APPLE_SYSTEM_FONTS: ReadonlySet<string>;
+/** Array form for passing to findClosestFont({ candidates }) */
+export declare const APPLE_SYSTEM_FONT_LIST: readonly string[];
+/**
+ * macOS-only system fonts (not on iOS).
+ * Combined with APPLE_SYSTEM_FONTS for macOS-specific matching.
+ */
+export declare const MACOS_ONLY_FONTS: ReadonlySet<string>;
+/** All macOS system fonts (APPLE_SYSTEM_FONTS + MACOS_ONLY_FONTS) */
+export declare const MACOS_SYSTEM_FONTS: ReadonlySet<string>;
+export declare const MACOS_SYSTEM_FONT_LIST: readonly string[];
 /** Width delta (%) between two fonts. Positive = target is wider. */
 export declare function widthDelta(source: FontMetrics, target: FontMetrics): number;
 export interface FontMatch {
@@ -54,7 +70,7 @@ export interface FontMatch {
  * @param options.limit - Max results to return (default: 3)
  */
 export declare function findClosestFont(source: string | FontMetrics, options?: {
-    candidates?: string[];
+    candidates?: readonly string[];
     sameCategory?: boolean;
     limit?: number;
 }): FontMatch[];

package/dist/resolve/font-metrics.js

@@ -58,7 +58,26 @@ export const FONT_METRICS = {
     "Avenir Next": { cat: "sans-serif", upm: 1000, xWidthAvg: 624, capH: 708, xH: 498, asc: 1000, desc: -366, lineGap: 0 },
     "Avenir Next Medium": { cat: "sans-serif", upm: 1000, xWidthAvg: 630, capH: 708, xH: 498, asc: 1000, desc: -366, lineGap: 0 },
     "Geneva": { cat: "sans-serif", upm: 2048, xWidthAvg: 1225, capH: 1552, xH: 1117, asc: 2048, desc: -512, lineGap: 171 },
-    "Impact": { cat: "sans-serif", upm: 2048, xWidthAvg: 989, capH: 1620, xH: 1327, asc: 2066, desc: -432, lineGap: 0 },
+    "Impact": { cat: "display", upm: 2048, xWidthAvg: 989, capH: 1620, xH: 1327, asc: 2066, desc: -432, lineGap: 0 },
+    "Gill Sans": { cat: "sans-serif", upm: 2048, xWidthAvg: 1082, capH: 1407, xH: 921, asc: 1415, desc: -471, lineGap: 305 },
+    "Optima": { cat: "sans-serif", upm: 1000, xWidthAvg: 432, capH: 700, xH: 500, asc: 919, desc: -271, lineGap: 25 },
+    "Galvji": { cat: "sans-serif", upm: 2048, xWidthAvg: 1279, capH: 1443, xH: 1078, asc: 1948, desc: -426, lineGap: 0 },
+    "DIN Alternate": { cat: "sans-serif", upm: 2048, xWidthAvg: 986, capH: 1470, xH: 1470, asc: 1585, desc: -421, lineGap: 336 },
+    "DIN Condensed": { cat: "sans-serif", upm: 1000, xWidthAvg: 374, capH: 712, xH: 507, asc: 712, desc: -288, lineGap: 200 },
+    "Copperplate": { cat: "display", upm: 1000, xWidthAvg: 661, capH: 550, xH: 440, asc: 763, desc: -250, lineGap: 20 },
+    "Baskerville": { cat: "serif", upm: 2048, xWidthAvg: 1185, capH: 1370, xH: 819, asc: 1839, desc: -504, lineGap: 0 },
+    "Didot": { cat: "serif", upm: 1000, xWidthAvg: 549, capH: 721, xH: 436, asc: 941, desc: -299, lineGap: 26 },
+    "Cochin": { cat: "serif", upm: 1000, xWidthAvg: 583, capH: 658, xH: 372, asc: 712, desc: -250, lineGap: 72 },
+    "Big Caslon": { cat: "serif", upm: 1000, xWidthAvg: 540, capH: 725, xH: 478, asc: 726, desc: -252, lineGap: 18 },
+    "Hoefler Text": { cat: "serif", upm: 2000, xWidthAvg: 831, capH: 1379, xH: 850, asc: 1864, desc: -636, lineGap: 0 },
+    "Bodoni 72": { cat: "serif", upm: 1000, xWidthAvg: 367, capH: 702, xH: 439, asc: 936, desc: -266, lineGap: 0 },
+    "American Typewriter": { cat: "serif", upm: 1000, xWidthAvg: 479, capH: 671, xH: 501, asc: 691, desc: -180, lineGap: 199 },
+    "Rockwell": { cat: "serif", upm: 2048, xWidthAvg: 1285, capH: 1507, xH: 1051, asc: 1548, desc: -498, lineGap: 145 },
+    "Charter": { cat: "serif", upm: 2048, xWidthAvg: 898, capH: 1400, xH: 950, asc: 2007, desc: -492, lineGap: 0 },
+    "Monaco": { cat: "monospace", upm: 2048, xWidthAvg: 1228, capH: 1552, xH: 1117, asc: 2048, desc: -512, lineGap: 171 },
+    "PT Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 431, capH: 700, xH: 500, asc: 1018, desc: -276, lineGap: 0 },
+    "PT Serif": { cat: "serif", upm: 1000, xWidthAvg: 448, capH: 700, xH: 500, asc: 1039, desc: -286, lineGap: 0 },
+    "PT Mono": { cat: "monospace", upm: 1000, xWidthAvg: 500, capH: 700, xH: 500, asc: 1039, desc: -286, lineGap: 0 },
     // ── Google Fonts (from @capsizecss/metrics — raw glyph widths) ────
     "Roboto": { cat: "sans-serif", upm: 2048, xWidthAvg: 911, capH: 1456, xH: 1082, asc: 1900, desc: -500, lineGap: 0 },
     "Open Sans": { cat: "sans-serif", upm: 2048, xWidthAvg: 960, capH: 1462, xH: 1096, asc: 2189, desc: -600, lineGap: 0 },
@@ -80,8 +99,6 @@ export const FONT_METRICS = {
     "Noto Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 474, capH: 714, xH: 536, asc: 1069, desc: -293, lineGap: 0 },
     "Noto Serif": { cat: "serif", upm: 1000, xWidthAvg: 481, capH: 714, xH: 536, asc: 1069, desc: -293, lineGap: 0 },
     "Noto Sans Mono": { cat: "monospace", upm: 1000, xWidthAvg: 600, capH: 714, xH: 536, asc: 1069, desc: -293, lineGap: 0 },
-    "PT Sans": { cat: "sans-serif", upm: 1000, xWidthAvg: 431, capH: 700, xH: 500, asc: 1018, desc: -276, lineGap: 0 },
-    "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) ────────
@@ -111,6 +128,41 @@ export const FONT_METRICS = {
     "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 },
 };
+// ── Platform font sets ──────────────────────────────────────────────
+/**
+ * Fonts preinstalled on BOTH macOS and iOS.
+ * Only includes fonts that have entries in FONT_METRICS above.
+ * Use as `candidates` in findClosestFont() to ensure the result is a real system font.
+ */
+export const APPLE_SYSTEM_FONTS = new Set([
+    // Sans-serif
+    "Arial", "Helvetica", "Helvetica Neue", "Helvetica Neue Light", "Helvetica Neue Medium",
+    "Avenir", "Avenir Next", "Avenir Next Medium",
+    "Futura", "Gill Sans", "Optima", "Galvji",
+    "DIN Alternate", "DIN Condensed",
+    "Verdana", "Trebuchet MS",
+    // Serif
+    "Georgia", "Times New Roman", "Palatino",
+    "Baskerville", "Didot", "Cochin", "Hoefler Text",
+    "Bodoni 72", "American Typewriter", "Rockwell", "Charter",
+    // Monospace
+    "Menlo", "Courier New",
+]);
+/** Array form for passing to findClosestFont({ candidates }) */
+export const APPLE_SYSTEM_FONT_LIST = [...APPLE_SYSTEM_FONTS];
+/**
+ * macOS-only system fonts (not on iOS).
+ * Combined with APPLE_SYSTEM_FONTS for macOS-specific matching.
+ */
+export const MACOS_ONLY_FONTS = new Set([
+    "PT Sans", "PT Serif", "PT Mono",
+    "Tahoma", "Geneva", "Monaco",
+    "Times", "Courier",
+    "Big Caslon",
+]);
+/** All macOS system fonts (APPLE_SYSTEM_FONTS + MACOS_ONLY_FONTS) */
+export const MACOS_SYSTEM_FONTS = new Set([...APPLE_SYSTEM_FONTS, ...MACOS_ONLY_FONTS]);
+export const MACOS_SYSTEM_FONT_LIST = [...MACOS_SYSTEM_FONTS];
 // ── Similarity matching ─────────────────────────────────────────────
 /** Normalize a metric by unitsPerEm so fonts at different scales are comparable. */
 function norm(m) {
@@ -124,12 +176,14 @@ function norm(m) {
 }
 /**
  * Compute similarity score between two fonts. Lower = more similar.
- * Weights character width (60%) above vertical metrics (40%) because
- * width determines text reflow / overflow in bounded text boxes.
+ * Width cost is asymmetric: wider substitutes are penalised 3× more than
+ * narrower ones, because wider causes text overflow while narrower just
+ * leaves a small gap.
  */
 function similarity(a, b) {
     const na = norm(a), nb = norm(b);
-    const wd = Math.abs(na.w - nb.w) / (na.w || 1);
+    const rawWd = (nb.w - na.w) / (na.w || 1); // positive = wider
+    const wd = rawWd > 0 ? rawWd * 3 : Math.abs(rawWd); // 3× penalty for wider
     const lh = Math.abs(na.lh - nb.lh) / (na.lh || 1);
     // capH/xH might be 0 for some fonts — only include if both have data
     let vertScore = 0, vertWeight = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quicklook-pptx-renderer",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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",