@knowvah/dot-engine 0.1.0

package/src/common/textmeasure-lut-data-c.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Raw width tables for Verdana, Open Sans, Georgia, and Calibri.
+ * Ported from lib/common/textspan_lut.c (all_font_metrics[7..10]).
+ *
+ * Widths are in (unitsPerEm × 1) pt.  A value of -1 means unknown.
+ * @see lib/common/textspan_lut.c:all_font_metrics
+ */
+
+import type { FontFamilyData } from "./textmeasure-lut-data.js";
+
+// ── Verdana ───────────────────────────────────────────────────────────────────
+
+const VR: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,720,806,940,1676,1302,2204,1488,550,930,
+  930,1302,1676,745,930,745,930,1302,1302,1302,1302,1302,1302,1302,1302,
+  1302,1302,930,930,1676,1676,1676,1117,2048,1400,1404,1430,1578,1295,
+  1177,1588,1539,862,931,1419,1140,1726,1532,1612,1235,1612,1424,1400,
+  1262,1499,1400,2025,1403,1260,1403,930,930,930,1676,1302,1302,1230,
+  1276,1067,1276,1220,720,1276,1296,562,705,1212,562,1992,1296,1243,1276,
+  1276,874,1067,807,1296,1212,1676,1212,1212,1076,1300,930,1300,1676,-1,
+];
+
+const VB: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,700,824,1203,1776,1456,2605,1766,680,
+  1113,1113,1456,1776,740,983,740,1412,1456,1456,1456,1456,1456,1456,
+  1456,1456,1456,1456,824,824,1776,1776,1776,1263,1974,1590,1560,1482,
+  1700,1399,1332,1661,1715,1118,1137,1579,1305,1941,1734,1741,1501,1741,
+  1602,1455,1396,1663,1564,2311,1564,1509,1417,1113,1412,1113,1776,1456,
+  1456,1368,1432,1205,1432,1360,865,1432,1459,700,825,1374,700,2167,1459,
+  1406,1432,1432,1018,1215,933,1459,1331,2006,1370,1333,1222,1456,1113,
+  1456,1776,-1,
+];
+
+const VI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,720,806,940,1676,1302,2204,1488,550,930,
+  930,1302,1676,745,930,745,930,1302,1302,1302,1302,1302,1302,1302,1302,
+  1302,1302,930,930,1676,1676,1676,1117,2048,1398,1404,1430,1568,1295,
+  1177,1588,1539,862,931,1419,1140,1726,1532,1612,1235,1612,1424,1400,
+  1262,1499,1398,2028,1403,1260,1403,930,930,930,1676,1302,1302,1230,
+  1276,1067,1276,1220,720,1273,1296,562,705,1202,562,1993,1296,1243,1276,
+  1276,874,1067,807,1296,1210,1676,1212,1210,1076,1300,930,1300,1676,-1,
+];
+
+const VBI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,700,824,1203,1776,1456,2605,1766,680,
+  1113,1113,1456,1776,740,983,740,1412,1456,1456,1456,1456,1456,1456,
+  1456,1456,1456,1456,824,824,1776,1776,1776,1263,1974,1590,1560,1482,
+  1700,1399,1332,1661,1715,1118,1137,1579,1305,1941,1734,1741,1501,1741,
+  1602,1455,1396,1663,1564,2311,1564,1509,1417,1113,1412,1113,1776,1456,
+  1456,1368,1432,1205,1432,1360,865,1432,1459,700,825,1374,700,2167,1459,
+  1404,1432,1432,1018,1215,933,1459,1329,2006,1370,1333,1222,1456,1113,
+  1456,1776,-1,
+];
+
+export const VERDANA_FAMILY: FontFamilyData = {
+  names: ["verdana"],
+  unitsPerEm: 2048,
+  regular: VR, bold: VB, italic: VI, boldItalic: VBI,
+};
+
+// ── Open Sans ─────────────────────────────────────────────────────────────────
+// C source uses "OpenSans" as the key; normalized form is "opensans".
+
+const OR: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,532,547,821,1323,1171,1686,1495,453,606,
+  606,1130,1171,502,659,545,752,1171,1171,1171,1171,1171,1171,1171,1171,
+  1171,1171,545,545,1171,1171,1171,879,1841,1296,1327,1292,1493,1139,
+  1057,1491,1511,571,547,1257,1063,1849,1544,1595,1233,1595,1266,1124,
+  1133,1491,1219,1896,1182,1147,1169,674,752,674,1110,918,1182,1139,1255,
+  975,1255,1149,694,1122,1257,518,518,1075,518,1905,1257,1237,1255,1255,
+  836,977,723,1257,1026,1593,1073,1032,958,776,1128,776,1171,-1,
+];
+
+const OB: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,532,586,967,1323,1169,1845,1536,545,694,
+  694,1116,1169,594,659,584,846,1169,1169,1169,1169,1169,1169,1169,1169,
+  1169,1169,584,594,1169,1169,1169,977,1837,1413,1376,1305,1516,1147,
+  1124,1483,1567,678,678,1360,1157,1931,1665,1630,1286,1630,1352,1128,
+  1186,1548,1331,1980,1366,1278,1186,678,846,678,1090,842,1243,1237,1296,
+  1053,1296,1210,793,1157,1346,625,625,1270,625,2011,1346,1268,1296,1296,
+  930,1018,889,1346,1165,1753,1184,1165,999,807,1128,807,1169,-1,
+];
+
+const OI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,532,530,791,1323,1128,1624,1372,444,584,
+  584,1130,1128,492,639,518,717,1128,1128,1128,1128,1128,1128,1128,1128,
+  1128,1128,518,518,1128,1128,1128,874,1735,1137,1225,1198,1364,1047,967,
+  1386,1389,559,547,1141,971,1714,1438,1475,1159,1475,1165,1028,1020,
+  1384,1122,1745,1063,1030,1087,586,717,586,1059,807,1135,1157,1182,922,
+  1182,1010,641,1026,1182,520,520,999,520,1786,1182,1149,1182,1182,811,
+  877,664,1182,946,1468,979,946,909,715,1128,715,1128,-1,
+];
+
+const OBI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,532,586,928,1323,1128,1753,1450,522,694,
+  694,1116,1128,569,659,584,862,1128,1128,1128,1128,1128,1128,1128,1128,
+  1128,1128,584,584,1128,1128,1128,940,1753,1286,1270,1253,1386,1110,
+  1087,1413,1434,659,678,1255,1061,1802,1546,1495,1188,1495,1247,1085,
+  1087,1415,1208,1831,1241,1155,1098,678,862,678,1081,819,1135,1217,1219,
+  989,1217,1141,764,1108,1237,608,608,1163,608,1853,1237,1198,1219,1217,
+  862,969,840,1237,1049,1614,1087,1063,932,727,1128,727,1128,-1,
+];
+
+export const OPENSANS_FAMILY: FontFamilyData = {
+  names: ["opensans"],
+  unitsPerEm: 2048,
+  regular: OR, bold: OB, italic: OI, boldItalic: OBI,
+};
+
+// ── Georgia ───────────────────────────────────────────────────────────────────
+
+const GR: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,494,678,843,1317,1249,1674,1455,441,768,
+  768,967,1317,552,766,552,960,1257,880,1144,1130,1157,1082,1159,1029,
+  1221,1159,640,640,1317,1317,1317,980,1902,1374,1339,1315,1534,1338,
+  1227,1485,1669,798,1060,1422,1236,1899,1571,1524,1249,1524,1437,1149,
+  1267,1549,1365,1998,1455,1260,1232,768,960,768,1317,1317,1024,1032,
+  1147,930,1176,990,666,1043,1192,600,598,1097,586,1804,1210,1104,1170,
+  1146,839,885,707,1178,1017,1510,1034,1008,909,881,768,881,1317,-1,
+];
+
+const GB: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,520,771,1044,1440,1312,1801,1637,551,915,
+  915,987,1440,672,776,672,966,1436,1003,1283,1279,1330,1227,1327,1135,
+  1385,1327,752,752,1440,1440,1440,1123,1980,1553,1551,1465,1708,1477,
+  1375,1653,1870,913,1219,1673,1404,2096,1719,1679,1436,1679,1633,1329,
+  1401,1707,1561,2307,1656,1499,1412,915,966,915,1440,1440,1024,1220,
+  1322,1088,1358,1171,805,1181,1392,724,709,1294,705,2080,1413,1302,1347,
+  1328,1065,1050,814,1386,1161,1768,1204,1151,1076,1024,794,1024,1440,-1,
+];
+
+const GI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,494,678,843,1317,1249,1674,1455,441,768,
+  768,967,1317,552,766,552,960,1257,880,1144,1130,1157,1082,1159,1017,
+  1221,1159,786,786,1317,1317,1317,980,1902,1374,1339,1315,1534,1338,
+  1227,1485,1669,798,1060,1422,1236,1899,1571,1496,1249,1496,1437,1149,
+  1267,1549,1365,1998,1455,1260,1232,768,960,768,1317,1317,1024,1173,
+  1134,929,1178,966,673,1173,1152,609,596,1081,584,1801,1208,1100,1184,
+  1137,945,883,711,1178,1102,1684,1026,1146,909,881,768,881,1317,-1,
+];
+
+const GBI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,520,771,1044,1440,1312,1801,1637,551,915,
+  915,987,1440,672,776,672,966,1436,1003,1283,1279,1330,1227,1327,1160,
+  1385,1327,752,752,1440,1440,1440,1123,1980,1553,1555,1465,1708,1477,
+  1375,1653,1870,923,1219,1673,1404,2116,1699,1679,1446,1679,1633,1337,
+  1401,1707,1561,2307,1643,1499,1412,915,966,915,1440,1440,1024,1352,
+  1329,1097,1357,1141,780,1330,1383,749,747,1313,726,2052,1413,1302,1357,
+  1331,1093,1059,854,1403,1254,1912,1195,1371,1059,1024,794,1024,1440,-1,
+];
+
+export const GEORGIA_FAMILY: FontFamilyData = {
+  names: ["georgia"],
+  unitsPerEm: 2048,
+  regular: GR, bold: GB, italic: GI, boldItalic: GBI,
+};
+
+// ── Calibri ───────────────────────────────────────────────────────────────────
+
+const CALR: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,463,667,821,1020,1038,1464,1397,452,621,
+  621,1020,1020,511,627,517,791,1038,1038,1038,1038,1038,1038,1038,1038,
+  1038,1038,548,548,1020,1020,1020,949,1831,1185,1114,1092,1260,1000,941,
+  1292,1276,516,653,1064,861,1751,1322,1356,1058,1378,1112,941,998,1314,
+  1162,1822,1063,998,959,628,791,628,1020,1020,596,981,1076,866,1076,
+  1019,625,964,1076,470,490,931,470,1636,1076,1080,1076,1076,714,801,686,
+  1076,925,1464,887,927,809,644,943,644,1020,-1,
+];
+
+const CALB: readonly number[] = [
+  0,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,0,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,463,667,898,1020,1038,1493,1443,478,638,
+  638,1020,1020,528,627,547,880,1038,1038,1038,1038,1038,1038,1038,1038,
+  1038,1038,565,565,1020,1020,1020,949,1840,1241,1148,1084,1291,999,940,
+  1305,1292,546,678,1120,866,1790,1349,1385,1090,1405,1153,968,1014,1337,
+  1211,1856,1128,1064,979,665,880,665,1020,1020,615,1011,1099,857,1099,
+  1031,648,971,1099,503,523,983,503,1666,1099,1101,1099,1099,728,817,710,
+  1099,969,1526,941,970,814,704,973,704,1020,-1,
+];
+
+const CALI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,463,667,821,1020,1038,1464,1397,452,621,
+  621,1020,1020,511,627,517,794,1038,1038,1038,1038,1038,1038,1038,1038,
+  1038,1038,548,548,1020,1020,1020,949,1831,1185,1114,1070,1260,1000,941,
+  1292,1276,516,653,1064,861,1751,1320,1340,1058,1360,1112,926,998,1314,
+  1162,1823,1063,998,959,628,787,628,1020,1020,596,1053,1053,852,1053,
+  978,625,1053,1053,470,490,931,470,1620,1053,1051,1053,1053,702,797,686,
+  1053,913,1464,887,916,809,644,943,644,1020,-1,
+];
+
+const CALBI: readonly number[] = [
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,463,667,898,1020,1038,1493,1443,478,638,
+  638,1020,1020,528,627,547,889,1038,1038,1038,1038,1038,1038,1038,1038,
+  1038,1038,565,565,1020,1020,1020,949,1840,1241,1148,1062,1291,999,940,
+  1305,1292,546,678,1120,866,1790,1344,1369,1090,1387,1153,953,1014,1337,
+  1211,1857,1128,1064,979,665,870,665,1020,1020,615,1081,1081,843,1081,
+  1006,648,1081,1080,503,523,983,503,1646,1080,1080,1081,1081,721,807,
+  710,1080,961,1526,941,963,814,704,973,704,1020,-1,
+];
+
+export const CALIBRI_FAMILY: FontFamilyData = {
+  names: ["calibri"],
+  unitsPerEm: 2048,
+  regular: CALR, bold: CALB, italic: CALI, boldItalic: CALBI,
+};

package/src/common/textmeasure-lut-data.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Aggregated font-family metrics LUT.
+ * Individual per-family data lives in textmeasure-lut-data-{a,b,c}.ts.
+ *
+ * @see lib/common/textspan_lut.c:all_font_metrics
+ */
+
+/** Per-family glyph width data, ported from FontFamilyMetrics in textspan_lut.c. */
+export interface FontFamilyData {
+  /** Normalized (letters-only, lowercase) font names for this family. */
+  readonly names: readonly string[];
+  /** TrueType units per em (denominator for width scaling). */
+  readonly unitsPerEm: number;
+  /** Per-character widths in (unitsPerEm × 1) pt; -1 = unknown. */
+  readonly regular: readonly number[];
+  readonly bold: readonly number[];
+  readonly italic: readonly number[];
+  readonly boldItalic: readonly number[];
+}
+
+export {
+  TIMES_FAMILY,
+  ARIAL_FAMILY,
+  COURIER_FAMILY,
+  NUNITO_FAMILY,
+} from "./textmeasure-lut-data-a.js";
+
+export {
+  DEJAVU_FAMILY,
+  CONSOLAS_FAMILY,
+  TREBUCHET_FAMILY,
+} from "./textmeasure-lut-data-b.js";
+
+export {
+  VERDANA_FAMILY,
+  OPENSANS_FAMILY,
+  GEORGIA_FAMILY,
+  CALIBRI_FAMILY,
+} from "./textmeasure-lut-data-c.js";
+
+import {
+  TIMES_FAMILY,
+  ARIAL_FAMILY,
+  COURIER_FAMILY,
+  NUNITO_FAMILY,
+} from "./textmeasure-lut-data-a.js";
+
+import {
+  DEJAVU_FAMILY,
+  CONSOLAS_FAMILY,
+  TREBUCHET_FAMILY,
+} from "./textmeasure-lut-data-b.js";
+
+import {
+  VERDANA_FAMILY,
+  OPENSANS_FAMILY,
+  GEORGIA_FAMILY,
+  CALIBRI_FAMILY,
+} from "./textmeasure-lut-data-c.js";
+
+/**
+ * All font family metrics in the same order as the C source.
+ * @see lib/common/textspan_lut.c:all_font_metrics
+ */
+export const ALL_FONT_METRICS: readonly FontFamilyData[] = [
+  TIMES_FAMILY,
+  ARIAL_FAMILY,
+  COURIER_FAMILY,
+  NUNITO_FAMILY,
+  DEJAVU_FAMILY,
+  CONSOLAS_FAMILY,
+  TREBUCHET_FAMILY,
+  VERDANA_FAMILY,
+  OPENSANS_FAMILY,
+  GEORGIA_FAMILY,
+  CALIBRI_FAMILY,
+];

package/src/common/textmeasure.ts

@@ -0,0 +1,321 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Text measurement utilities: LUT-based and Canvas-based.
+ * Ported from lib/common/textspan_lut.c and lib/common/textspan.c.
+ *
+ * @see lib/common/textspan_lut.c
+ * @see lib/common/textspan.c:estimate_textspan_size
+ */
+
+import { type FontFamilyData } from "./textmeasure-lut-data.js";
+import { getFamilyMetrics, normalizeFontName } from "./textmeasure-lookup.js";
+
+/** Number of hard-coded font families in the LUT. */
+export const LUT_FAMILY_COUNT = 11;
+
+/** Estimated size of a text string in points. */
+export interface TextSize {
+  w: number;
+  h: number;
+  /**
+   * Baseline→centerline offset in points (C textspan_t.yoffset_centerline). The
+   * vertical metric is part of the measurement model: native graphviz's estimate
+   * uses 0.1·fontsize, while the font-plugin (pango) path is ≈0.05·fontsize. When
+   * omitted, callers default to the 0.05·fontsize (pango-calibrated) value.
+   * @see lib/common/textspan.c:estimate_textspan_size
+   */
+  yoffsetCenterline?: number;
+  /**
+   * Baseline→top (ascent) in points (C textspan_t.yoffset_layout). Native
+   * estimate uses `fontsize`; the freetype/pango path uses the font ascent
+   * (~0.89·fontsize). When omitted, callers fall back to the freetype ascent.
+   * @see lib/common/textspan.c:estimate_textspan_size
+   */
+  yoffsetLayout?: number;
+}
+
+/**
+ * Font variant flags (bold / italic) for text measurement.
+ * Mirrors textfont_t.flags in the C source.
+ * @see lib/common/textspan_lut.c:estimate_textspan_size (AD2)
+ */
+export interface TextVariantFlags {
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+}
+
+/** Abstraction over text measurement strategies. */
+export interface TextMeasurer {
+  measure(
+    text: string,
+    fontname: string,
+    fontsize: number,
+    flags?: TextVariantFlags,
+  ): TextSize;
+}
+
+// ── Variant selection ─────────────────────────────────────────────────────────
+
+/** @see lib/common/textspan_lut.c:get_metrics_for_font_variant */
+function getVariantWidths(
+  family: FontFamilyData,
+  bold: boolean,
+  italic: boolean,
+): readonly number[] {
+  if (bold && italic) return family.boldItalic;
+  if (bold) return family.bold;
+  if (italic) return family.italic;
+  return family.regular;
+}
+
+// ── Character width lookup ────────────────────────────────────────────────────
+
+const SPACE_CHAR_CODE = 32;
+
+/** @see lib/common/textspan_lut.c:estimate_character_width_canonical */
+function charWidthUnits(widths: readonly number[], charCode: number): number {
+  const code = charCode >= 128 ? SPACE_CHAR_CODE : charCode;
+  const w = widths[code] ?? -1;
+  return w < 0 ? 0 : w;
+}
+
+/**
+ * UTF-8 byte encoding of `text`, used to iterate text width per byte.
+ *
+ * C's estimate measures one canonical width per UTF-8 byte (it loops over
+ * `(unsigned char)*c`), mapping every byte ≥128 to the space-width fallback. A
+ * JS string is UTF-16, so iterating `text.charCodeAt(i)` under-counts non-ASCII
+ * glyphs (a 3-byte CJK glyph would measure as 1 space, not 3). Re-encoding to
+ * UTF-8 and iterating the bytes mirrors C exactly. `TextEncoder` is used instead
+ * of Node `Buffer` to remain browser-safe. ASCII is unchanged (byte == charCode
+ * for values <128).
+ * @see lib/common/textspan_lut.c:estimate_text_width_1pt
+ */
+const utf8Encoder = new TextEncoder();
+function utf8Bytes(text: string): Uint8Array {
+  return utf8Encoder.encode(text);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Estimates the width of text at 1 pt for the given font/variant.
+ * Multiply by fontsize to get width at N pt.
+ * @see lib/common/textspan_lut.c:estimate_text_width_1pt
+ */
+export function estimate_text_width_1pt(
+  fontName: string,
+  text: string,
+  bold: boolean,
+  italic: boolean,
+): number {
+  const family = getFamilyMetrics(fontName);
+  const widths = getVariantWidths(family, bold, italic);
+  let total = 0;
+  // Iterate UTF-8 bytes, not UTF-16 units, to mirror C's per-byte loop.
+  for (const byte of utf8Bytes(text)) {
+    total += charWidthUnits(widths, byte);
+  }
+  return total / family.unitsPerEm;
+}
+
+/**
+ * FreeType line-spacing ratio measured from graphviz 15.0.0 reference SVGs.
+ * 14pt Times-Roman label height = 16.5pt → ratio = 16.5/14.
+ * C's LINESPACING=1.20 is a fallback estimate; actual FreeType gives ~1.17857.
+ * Kept for callers that want the 14pt-calibrated linear approximation;
+ * the measurer itself uses the exact hinted model (freetypeLineHeight).
+ * @see lib/common/textspan.c:estimate_textspan_size
+ */
+export const FREETYPE_LINE_SPACING = 16.5 / 14;
+
+/**
+ * graphviz's text layout plugin rasterises at 96 dpi, so every glyph
+ * advance lands on an integer pixel and converts back at 72/96 pt per px.
+ * Reference values (Times 14pt): 'a' 0.444em → 8.29px → 8px → 6pt;
+ * 'b' 0.5em → 9.33px → 9px → 6.75pt.
+ */
+const FREETYPE_PX_PER_PT = 96 / 72;
+const PT_PER_FREETYPE_PX = 72 / 96;
+
+/**
+ * Per-character FreeType-hinted text width in points: each glyph advance is
+ * rounded to the 96 dpi pixel grid before summing.
+ * @see lib/common/textspan_lut.c:estimate_textspan_size
+ */
+export function freetypeHintedWidth(
+  fontName: string,
+  text: string,
+  fontsize: number,
+  bold = false,
+  italic = false,
+): number {
+  const family = getFamilyMetrics(fontName);
+  const widths = getVariantWidths(family, bold, italic);
+  let total = 0;
+  // Iterate UTF-8 bytes, not UTF-16 units, to mirror C's per-byte loop (AD-2).
+  for (const byte of utf8Bytes(text)) {
+    const units = charWidthUnits(widths, byte);
+    const px = Math.round((units / family.unitsPerEm) * fontsize * FREETYPE_PX_PER_PT);
+    total += px * PT_PER_FREETYPE_PX;
+  }
+  return total;
+}
+
+/**
+ * Times-Roman ascender ratio (TrueType hhea ascender 1825/2048em).
+ * Hinted to the 96 dpi grid: 14pt → 17px → 12.75pt, matching the baseline
+ * positions in graphviz reference SVGs.
+ */
+export const FREETYPE_ASCENT_RATIO = 1825 / 2048;
+
+/** Times-Roman descender ratio (hhea descender 443/2048em). */
+export const FREETYPE_DESCENT_RATIO = 443 / 2048;
+
+/**
+ * FreeType-hinted ascender/descender ratios (in em) for a font, used for the
+ * hinted line height. Vertical metrics are keyed by the *resolved font*, NOT
+ * the width family: the width LUT lumps Helvetica and Arial together (their
+ * advances match), but on the reference system their line boxes differ
+ * (Helvetica/Nimbus ≈ 1.0 em, real Arial ≈ taller, Times ≈ 1.107 em).
+ */
+interface VMetric {
+  readonly ascent: number;
+  readonly descent: number;
+}
+
+/** Times-Roman default (the historical hardcoded model). */
+const TIMES_VMETRIC: VMetric = {
+  ascent: FREETYPE_ASCENT_RATIO,
+  descent: FREETYPE_DESCENT_RATIO,
+};
+
+/**
+ * Helvetica / Nimbus Sans: ascender 1577/2048, descender 471/2048. Empirically
+ * pinned to the native-dot oracle's hinted line height across fontsizes 6-48
+ * (ceil(asc·px)+ceil(desc·px) reproduces every size exactly).
+ */
+const HELVETICA_VMETRIC: VMetric = { ascent: 1577 / 2048, descent: 471 / 2048 };
+
+/**
+ * Normalized font names whose line box matches Helvetica/Nimbus Sans on the
+ * reference system. This is every sans alias the width LUT groups as Arial
+ * EXCEPT the literal "arial": fontconfig resolves "Arial" to a real Arial face
+ * with a taller line box (55px vs 49px at 36pt) — distinct from both Helvetica
+ * and Times — so it keeps the Times default until pinned separately.
+ * @see src/common/textmeasure-lut-data-a.ts ARIAL_FAMILY
+ */
+const HELVETICA_VMETRIC_NAMES: ReadonlySet<string> = new Set([
+  "helvetica", "arialmt", "arimo", "albany",
+  "nimbussans", "nimbussansa", "texgyreheros", "freesans", "liberationsans",
+]);
+
+/** Resolve the vertical metric for a font name (defaults to Times). */
+function vMetricFor(fontname: string | undefined): VMetric {
+  if (fontname === undefined) return TIMES_VMETRIC;
+  return HELVETICA_VMETRIC_NAMES.has(normalizeFontName(fontname))
+    ? HELVETICA_VMETRIC
+    : TIMES_VMETRIC;
+}
+
+/**
+ * FreeType-hinted font ascent in points (baseline distance from line
+ * top). FreeType rounds the ascender UP to the pixel grid
+ * (FT_PIX_CEIL); at 14pt ceil and round coincide (16.63 → 17px).
+ * Font-aware: Helvetica's ascender differs from Times' (default when
+ * `fontname` is omitted or is not a known Helvetica-metric face).
+ */
+export function freetypeAscent(fontsize: number, fontname?: string): number {
+  const px = Math.ceil(vMetricFor(fontname).ascent * fontsize * FREETYPE_PX_PER_PT);
+  return px * PT_PER_FREETYPE_PX;
+}
+
+/**
+ * FreeType-hinted line height in points: ceil-hinted ascender plus
+ * ceil-hinted descender magnitude (FT_PIX_CEIL / FT_PIX_FLOOR on the
+ * negative descender). Verified against graphviz 15.0.0 two-line
+ * baseline deltas for fontsizes 6-48 (e.g. Times 14pt → 17+5 px = 16.5pt;
+ * Helvetica 36pt → 33+16 px = 36.75pt). Font-aware: defaults to Times when
+ * `fontname` is omitted or is not a known Helvetica-metric face.
+ */
+export function freetypeLineHeight(fontsize: number, fontname?: string): number {
+  const m = vMetricFor(fontname);
+  const asc = Math.ceil(m.ascent * fontsize * FREETYPE_PX_PER_PT);
+  const desc = Math.ceil(m.descent * fontsize * FREETYPE_PX_PER_PT);
+  return (asc + desc) * PT_PER_FREETYPE_PX;
+}
+
+/**
+ * LUT-based TextMeasurer. Width from LUT quantised to FreeType's 96 dpi
+ * pixel grid; height matches FreeType Times-Roman.
+ * @see lib/common/textspan.c:estimate_textspan_size
+ */
+export class LutTextMeasurer implements TextMeasurer {
+  measure(
+    text: string,
+    fontname: string,
+    fontsize: number,
+    flags?: TextVariantFlags,
+  ): TextSize {
+    const bold = flags?.bold === true;
+    const italic = flags?.italic === true;
+    const w = freetypeHintedWidth(fontname, text, fontsize, bold, italic);
+    return { w, h: freetypeLineHeight(fontsize, fontname) };
+  }
+}
+
+/**
+ * Canvas-based TextMeasurer via CanvasRenderingContext2D.
+ * Height is fontsize (matches C behavior).
+ * @see lib/common/textspan.c:estimate_textspan_size
+ */
+export class CanvasTextMeasurer implements TextMeasurer {
+  constructor(private readonly ctx: CanvasRenderingContext2D) {}
+
+  measure(
+    text: string,
+    fontname: string,
+    fontsize: number,
+    flags?: TextVariantFlags,
+  ): TextSize {
+    const bold = flags?.bold === true;
+    const italic = flags?.italic === true;
+    const style = bold && italic ? 'bold italic'
+      : bold ? 'bold'
+      : italic ? 'italic'
+      : '';
+    this.ctx.font = style ? `${style} ${fontsize}px ${fontname}` : `${fontsize}px ${fontname}`;
+    const m = this.ctx.measureText(text);
+    return { w: m.width, h: fontsize };
+  }
+}
+
+/** graphviz estimate_textspan_size line spacing. @see lib/common/const.h:70 */
+export const LINESPACING = 1.20;
+
+/**
+ * Raw textspan_lut.c estimate: un-hinted per-char widths summed once, no kerning,
+ * height = fontsize * LINESPACING. Reproduces graphviz's HEADLESS measurement
+ * (no textlayout plugin → estimate_textspan_size) exactly, making it the
+ * deterministic, font-stack-independent reference for layout-rules validation.
+ * Unlike LutTextMeasurer this does NOT apply per-char FreeType px hinting.
+ * @see lib/common/textspan.c:estimate_textspan_size
+ */
+export class EstimateTextMeasurer implements TextMeasurer {
+  measure(
+    text: string,
+    fontname: string,
+    fontsize: number,
+    flags?: TextVariantFlags,
+  ): TextSize {
+    const w = fontsize * estimate_text_width_1pt(
+      fontname, text, flags?.bold === true, flags?.italic === true,
+    );
+    // native estimate_textspan_size: size.y = fontsize*LINESPACING,
+    // yoffset_layout = fontsize, yoffset_centerline = 0.1*fontsize.
+    return {
+      w, h: fontsize * LINESPACING,
+      yoffsetCenterline: 0.1 * fontsize, yoffsetLayout: fontsize,
+    };
+  }
+}