@stll/folio-core 0.1.3 → 0.2.0

package/dist/utils/fontResolver.js

@@ -1,20 +1,62 @@
 //#region src/utils/fontResolver.ts
 /**
-* Default OS/2 single-line ratio for unmapped fonts.
+* Default single-line ratio for unmapped fonts.
 * Middle of the common range (1.07–1.27) for standard DOCX fonts.
 */
 const DEFAULT_SINGLE_LINE_RATIO = 1.15;
 /**
+* Single-line height ratio (single-line height ÷ font size) for a
+* `FontLineHeight`. This is the ONLY place the derivation formula lives.
+*
+* For `"hhea"` sources: `(hheaAscent + |hheaDescent| + hheaLineGap) / unitsPerEm`.
+* This matches Word's rendered single-line pitch (11pt, single spacing) for
+* every font measured against real Word output so far (16 fonts, no
+* exceptions) — Word does NOT drop the font's line gap. Earlier revisions of
+* this table hand-transcribed ratios from the OS/2 table and omitted the line
+* gap for most fonts, which undershot Word's rendered line height for several
+* of them (confirmed against real Word for cambria, trebuchet ms, palatino
+* linotype, book antiqua, century gothic, consolas, and lucida console; arial
+* and times new roman were fixed in a prior revision). Future readers: to
+* correct or add a font, edit its `hhea*`/`unitsPerEm` metric fields, never the
+* resulting ratio.
+*
+* Most CJK fonts are intentionally left on `DEFAULT_SINGLE_LINE_RATIO`: Word's
+* East-Asian line height is not the run font's hhea ratio (it derives from the
+* paragraph's `w:eastAsia` slot and East-Asian grid layout, not the ascii
+* font), so a single per-font constant cannot capture it correctly. The
+* Japanese Mincho/Gothic entries carry a `"measured"` ratio instead — see
+* `JP_MEASURED_LINE_HEIGHT`.
+*/
+const singleLineRatioOf = (lineHeight) => lineHeight.source === "hhea" ? (lineHeight.hheaAscent - lineHeight.hheaDescent + lineHeight.hheaLineGap) / lineHeight.unitsPerEm : lineHeight.ratio;
+/**
+* Word's East-Asian single-line height for the Japanese Mincho/Gothic faces,
+* measured against real Word output on a NON-grid Japanese document
+* (10.5pt body renders at 13.68pt line pitch → 13.68 / 10.5 ≈ 1.303). Word
+* font-links CJK glyphs to the OS default East-Asian face and takes THAT
+* face's height, so the declared font's own `hhea` table is not the source of
+* truth here; a section with a `w:docGrid` line grid would override this value
+* entirely (out of scope). The ratio is approximate for the CJK long tail
+* (e.g. Yu Mincho renders taller, ≈1.60, when actually installed); it matches
+* the common MS Mincho/Gothic default.
+*/
+const JP_MEASURED_LINE_HEIGHT = {
+	source: "measured",
+	ratio: 1.303,
+	note: "Measured against real Word: 10.5pt Japanese body, non-grid section, renders at 13.68pt line pitch."
+};
+/**
 * Mapping of common DOCX fonts to Google Fonts equivalents
 *
 * These are metrically compatible fonts that preserve document layout.
 * See: https://wiki.archlinux.org/title/Metric-compatible_fonts
 *
-* singleLineRatio values are derived from each font's OS/2 table:
-* (usWinAscent + usWinDescent) / unitsPerEm
-* These define the Windows GDI "single line" height that OOXML lineRule="auto" uses.
-* sTypoLineGap (external leading) is NOT included — Word excludes it from the
-* lineRule="auto" calculation (ECMA-376 §17.3.1.33).
+* `singleLineRatio` values are computed by `singleLineRatioOf` from each
+* font's `FontLineHeight`, never hand-written. For "hhea" entries the raw
+* `hheaAscent`/`hheaDescent`/`hheaLineGap`/`unitsPerEm` fields below are read
+* directly from the real font files' `hhea` table; the ratio is whatever
+* falls out of the formula in `singleLineRatioOf`. "legacy" entries (e.g.
+* garamond, lucida sans, lucida console) are unverified hand-transcribed
+* ratios carried over unchanged, pending measurement.
 */
 const FONT_MAPPINGS = {
 	calibri: {
@@ -27,7 +69,13 @@ const FONT_MAPPINGS = {
 			"Helvetica",
 			"sans-serif"
 		],
-		singleLineRatio: 1.2207
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1950,
+			hheaDescent: -550,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	cambria: {
 		googleFont: "Caladea",
@@ -38,7 +86,13 @@ const FONT_MAPPINGS = {
 			"Georgia",
 			"serif"
 		],
-		singleLineRatio: 1.2676
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1946,
+			hheaDescent: -455,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	arial: {
 		googleFont: "Arimo",
@@ -49,7 +103,13 @@ const FONT_MAPPINGS = {
 			"Helvetica",
 			"sans-serif"
 		],
-		singleLineRatio: 1.1172
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1854,
+			hheaDescent: -434,
+			hheaLineGap: 67,
+			unitsPerEm: 2048
+		})
 	},
 	"times new roman": {
 		googleFont: "Tinos",
@@ -60,7 +120,13 @@ const FONT_MAPPINGS = {
 			"Times",
 			"serif"
 		],
-		singleLineRatio: 1.1074
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1825,
+			hheaDescent: -443,
+			hheaLineGap: 87,
+			unitsPerEm: 2048
+		})
 	},
 	"courier new": {
 		googleFont: "Cousine",
@@ -71,7 +137,13 @@ const FONT_MAPPINGS = {
 			"Courier",
 			"monospace"
 		],
-		singleLineRatio: 1.1328
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1705,
+			hheaDescent: -615,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	georgia: {
 		googleFont: "Tinos",
@@ -82,7 +154,13 @@ const FONT_MAPPINGS = {
 			"Times New Roman",
 			"serif"
 		],
-		singleLineRatio: 1.1362
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1878,
+			hheaDescent: -449,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	verdana: {
 		googleFont: "Open Sans",
@@ -93,7 +171,13 @@ const FONT_MAPPINGS = {
 			"Arial",
 			"sans-serif"
 		],
-		singleLineRatio: 1.2153
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2059,
+			hheaDescent: -430,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	tahoma: {
 		googleFont: "Open Sans",
@@ -104,7 +188,13 @@ const FONT_MAPPINGS = {
 			"Arial",
 			"sans-serif"
 		],
-		singleLineRatio: 1.2075
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2049,
+			hheaDescent: -423,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	"trebuchet ms": {
 		googleFont: "Fira Sans",
@@ -115,7 +205,13 @@ const FONT_MAPPINGS = {
 			"Arial",
 			"sans-serif"
 		],
-		singleLineRatio: 1.1431
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1923,
+			hheaDescent: -455,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	"comic sans ms": {
 		googleFont: "Comic Neue",
@@ -125,7 +221,13 @@ const FONT_MAPPINGS = {
 			"Comic Neue",
 			"cursive"
 		],
-		singleLineRatio: 1.3936
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2257,
+			hheaDescent: -597,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	impact: {
 		googleFont: "Anton",
@@ -136,7 +238,13 @@ const FONT_MAPPINGS = {
 			"Arial Black",
 			"sans-serif"
 		],
-		singleLineRatio: 1.2197
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2066,
+			hheaDescent: -432,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	"palatino linotype": {
 		googleFont: "EB Garamond",
@@ -148,7 +256,13 @@ const FONT_MAPPINGS = {
 			"Georgia",
 			"serif"
 		],
-		singleLineRatio: 1.0259
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2150,
+			hheaDescent: -613,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	"book antiqua": {
 		googleFont: "EB Garamond",
@@ -160,7 +274,13 @@ const FONT_MAPPINGS = {
 			"Georgia",
 			"serif"
 		],
-		singleLineRatio: 1.0259
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1891,
+			hheaDescent: -578,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	garamond: {
 		googleFont: "EB Garamond",
@@ -171,7 +291,11 @@ const FONT_MAPPINGS = {
 			"Georgia",
 			"serif"
 		],
-		singleLineRatio: 1.068
+		singleLineRatio: singleLineRatioOf({
+			source: "legacy",
+			ratio: 1.068,
+			note: "Unverified hand-transcribed ratio; not yet measured against real Word output."
+		})
 	},
 	"century gothic": {
 		googleFont: "Questrial",
@@ -182,7 +306,13 @@ const FONT_MAPPINGS = {
 			"Arial",
 			"sans-serif"
 		],
-		singleLineRatio: 1.1611
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 2060,
+			hheaDescent: -451,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	"lucida sans": {
 		googleFont: "Open Sans",
@@ -193,7 +323,11 @@ const FONT_MAPPINGS = {
 			"Arial",
 			"sans-serif"
 		],
-		singleLineRatio: 1.1655
+		singleLineRatio: singleLineRatioOf({
+			source: "legacy",
+			ratio: 1.1655,
+			note: "Unverified hand-transcribed ratio; not yet measured against real Word output."
+		})
 	},
 	"lucida console": {
 		googleFont: "Cousine",
@@ -204,7 +338,13 @@ const FONT_MAPPINGS = {
 			"Courier New",
 			"monospace"
 		],
-		singleLineRatio: 1.1387
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1616,
+			hheaDescent: -432,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
 	},
 	consolas: {
 		googleFont: "Inconsolata",
@@ -216,7 +356,13 @@ const FONT_MAPPINGS = {
 			"Courier New",
 			"monospace"
 		],
-		singleLineRatio: 1.1626
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1521,
+			hheaDescent: -527,
+			hheaLineGap: 350,
+			unitsPerEm: 2048
+		})
 	},
 	"ms mincho": {
 		googleFont: "Noto Serif JP",
@@ -226,7 +372,7 @@ const FONT_MAPPINGS = {
 			"Noto Serif JP",
 			"serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	"ｍｓ 明朝": {
 		googleFont: "Noto Serif JP",
@@ -237,7 +383,7 @@ const FONT_MAPPINGS = {
 			"Noto Serif JP",
 			"serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	"ｍｓ ｐ明朝": {
 		googleFont: "Noto Serif JP",
@@ -248,7 +394,7 @@ const FONT_MAPPINGS = {
 			"Noto Serif JP",
 			"serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	"ms gothic": {
 		googleFont: "Noto Sans JP",
@@ -258,7 +404,7 @@ const FONT_MAPPINGS = {
 			"Noto Sans JP",
 			"sans-serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	"ｍｓ ゴシック": {
 		googleFont: "Noto Sans JP",
@@ -269,7 +415,7 @@ const FONT_MAPPINGS = {
 			"Noto Sans JP",
 			"sans-serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	"ｍｓ ｐゴシック": {
 		googleFont: "Noto Sans JP",
@@ -280,7 +426,7 @@ const FONT_MAPPINGS = {
 			"Noto Sans JP",
 			"sans-serif"
 		],
-		singleLineRatio: DEFAULT_SINGLE_LINE_RATIO
+		singleLineRatio: singleLineRatioOf(JP_MEASURED_LINE_HEIGHT)
 	},
 	simhei: {
 		googleFont: "Noto Sans SC",
@@ -530,6 +676,45 @@ const CJK_FONT_ALIASES = {
 	游明朝: "ms mincho"
 };
 /**
+* The Noto families every CJK entry in `FONT_MAPPINGS` maps to. A mapping
+* whose `googleFont` is one of these is an East-Asian face; this is the single
+* classification source for `isCjkFont`, kept as an explicit set (not a name
+* heuristic) so a future non-Noto CJK mapping must extend it deliberately.
+*/
+const CJK_NOTO_FAMILIES = /* @__PURE__ */ new Set([
+	"Noto Serif JP",
+	"Noto Sans JP",
+	"Noto Serif SC",
+	"Noto Sans SC",
+	"Noto Serif TC",
+	"Noto Sans TC",
+	"Noto Serif KR",
+	"Noto Sans KR"
+]);
+/**
+* True when `family` is a known East-Asian (CJK) typeface — a direct
+* `FONT_MAPPINGS` CJK entry or a romanized alias of one. Used by the measurer
+* to decide whether a run's `w:eastAsia` font can supply the line height for
+* CJK text, or whether Word would font-link to a default East-Asian face
+* instead (see `CJK_FALLBACK_FONT_FAMILY`). Unmapped families return false:
+* we cannot know their metrics, so the caller falls back.
+*/
+function isCjkFont(family) {
+	const normalizedName = family.trim().toLowerCase();
+	const mapping = FONT_MAPPINGS[CJK_FONT_ALIASES[normalizedName] ?? normalizedName];
+	return mapping !== void 0 && CJK_NOTO_FAMILIES.has(mapping.googleFont);
+}
+/**
+* Font family whose `singleLineRatio` stands in for Word's default East-Asian
+* face when a CJK-text run declares no usable CJK font (its `w:eastAsia` slot
+* is absent or names a Latin face like "Century"). Word font-links those
+* glyphs to the OS default East-Asian font and takes THAT face's taller line
+* height; MS Mincho carries the measured ratio for it
+* (`JP_MEASURED_LINE_HEIGHT`, ≈1.303). Line-height resolution only — never
+* used for width measurement or painting.
+*/
+const CJK_FALLBACK_FONT_FAMILY = "MS Mincho";
+/**
 * Resolve a DOCX font name to a Google Font and CSS fallback stack
 *
 * @param docxFontName - The font name from the DOCX file
@@ -648,4 +833,4 @@ function hasGoogleFontEquivalent(docxFontName) {
 	return docxFontName.trim().toLowerCase() in FONT_MAPPINGS;
 }
 //#endregion
-export { DEFAULT_SINGLE_LINE_RATIO, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsToLoad, hasGoogleFontEquivalent, resolveFontFamily, resolveThemeFont };
+export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, resolveFontFamily, resolveThemeFont };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -69,10 +69,18 @@
       "types": "./dist/prosemirror/conversion/index.d.ts",
       "import": "./dist/prosemirror/conversion/index.js"
     },
+    "./prosemirror/extensions": {
+      "types": "./dist/prosemirror/extensions/index.d.ts",
+      "import": "./dist/prosemirror/extensions/index.js"
+    },
     "./prosemirror/schema": {
       "types": "./dist/prosemirror/schema/index.d.ts",
       "import": "./dist/prosemirror/schema/index.js"
     },
+    "./docx": {
+      "types": "./dist/docx/index.d.ts",
+      "import": "./dist/docx/index.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js"