@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/styles-resolve.js

@@ -1,257 +1,257 @@
-// styles.xml -> docDefaults / style chain / effective-value resolver. Ported
-// from scripts/measure-style-inheritance.py's load_styles()/style_chain()/
-// resolve()/same_state() — the algorithm, not the aggregate-measurement
-// machinery (new_acc/measure_document), which belongs only to that
-// standalone script. ADR-0017: "Çözümleyici sıfırdan yazılmayacak."
-//
-// Resolution order (docDefaults -> style chain root-first, derived wins ->
-// direct), ported unchanged.
-
-import { getAttr, findChild, findChildren } from "./xml-scan.js";
-import { W_NS } from "./ns.js";
-import { rejectCharacterStyle } from "./import-gate.js";
-
-const OFF_VALUES = new Set(["0", "false", "none"]);
-
-/**
- * A `w:pPr` element -> flat {field: value}. Absent field = not set here.
- * @param {import("./xml-scan.js").XmlElement | undefined} pPrEl
- * @returns {Record<string, string>}
- */
-export function readPPr(pPrEl) {
-  /** @type {Record<string, string>} */
-  const out = {};
-  if (!pPrEl) return out;
-  const jc = findChild(pPrEl, W_NS, "jc");
-  if (jc) {
-    const val = getAttr(jc, W_NS, "val");
-    if (val !== undefined) out.jc = val;
-  }
-  const ind = findChild(pPrEl, W_NS, "ind");
-  if (ind) {
-    for (const a of ["left", "right", "firstLine", "hanging"]) {
-      const v = getAttr(ind, W_NS, a);
-      if (v !== undefined) out[`ind.${a}`] = v;
-    }
-  }
-  const sp = findChild(pPrEl, W_NS, "spacing");
-  if (sp) {
-    for (const a of ["before", "after", "line", "lineRule"]) {
-      const v = getAttr(sp, W_NS, a);
-      if (v !== undefined) out[`spacing.${a}`] = v;
-    }
-  }
-  // Raw numId/ilvl only -- resolving them to a display marker needs
-  // numbering.xml, which this function has no access to (it is called for
-  // BOTH a style's own pPr and a paragraph's direct pPr, same as jc/ind/
-  // spacing above, so direct numPr correctly overrides a style's numPr
-  // through the existing resolve() cascade). import.js's internPPrRef adds
-  // the resolved `numPr.marker` field after this cascade runs.
-  const numPr = findChild(pPrEl, W_NS, "numPr");
-  if (numPr) {
-    const ilvl = findChild(numPr, W_NS, "ilvl");
-    if (ilvl) {
-      const v = getAttr(ilvl, W_NS, "val");
-      if (v !== undefined) out["numPr.ilvl"] = v;
-    }
-    const numId = findChild(numPr, W_NS, "numId");
-    if (numId) {
-      const v = getAttr(numId, W_NS, "val");
-      if (v !== undefined) out["numPr.numId"] = v;
-    }
-  }
-  return out;
-}
-
-/**
- * A `w:rPr` element -> flat {field: value}. `font` collapses w:rFonts'
- * ascii/hAnsi/cs in that order; a theme-only rFonts yields the sentinel
- * "(tema)" — theme1.xml is deliberately not opened (ADR-0017 DOĞRULANMALI
- * #6), and pretending the field is unset would hide that.
- * A `w:rStyle` child (a reference to a character style) is rejected rather
- * than silently ignored — ADR-0020 Karar 4: 0/81.973 real corpus runs carry
- * one, so a run that does is corpus-external and this resolver has no
- * mechanism to fold the referenced style's properties in.
- * `color` is DISPLAY-only (render, not the `Marks`/toggle path — 2026-08-31
- * decision, ADR-0026): a 6-hex-digit `w:val` is read straight through; a
- * `w:themeColor` reference or `w:val="auto"` is left unset rather than
- * guessed — measured 211 real corpus `w:color` elements, 0 carry either
- * (theme1.xml is deliberately not opened, same reason as the `rFonts` theme
- * sentinel above), so this is not a real-corpus gap today, only a documented
- * refusal to invent a value.
- * `vertAlign` is DISPLAY-only, same class as `color` (2026-09-01): only the
- * three ST_VerticalAlignRun enum values (`superscript`/`subscript`/
- * `baseline`) are read straight through; anything else is left unset rather
- * than guessed — measured 0/576 real corpus `w:vertAlign` elements carry a
- * fourth value.
- * @param {import("./xml-scan.js").XmlElement | undefined} rPrEl
- * @returns {Record<string, string>}
- */
-export function readRPr(rPrEl) {
-  /** @type {Record<string, string>} */
-  const out = {};
-  if (!rPrEl) return out;
-  if (findChild(rPrEl, W_NS, "rStyle")) {
-    rejectCharacterStyle(`w:rPr at byte ${rPrEl.start}`);
-  }
-  const sz = findChild(rPrEl, W_NS, "sz");
-  if (sz) {
-    const val = getAttr(sz, W_NS, "val");
-    if (val) out.sz = val;
-  }
-  const rf = findChild(rPrEl, W_NS, "rFonts");
-  if (rf) {
-    let name;
-    for (const a of ["ascii", "hAnsi", "cs"]) {
-      const v = getAttr(rf, W_NS, a);
-      if (v) {
-        name = v;
-        break;
-      }
-    }
-    if (name === undefined) {
-      for (const a of ["asciiTheme", "hAnsiTheme", "cstheme"]) {
-        if (getAttr(rf, W_NS, a)) {
-          name = "(tema)";
-          break;
-        }
-      }
-    }
-    if (name !== undefined) out.font = name;
-  }
-  const color = findChild(rPrEl, W_NS, "color");
-  if (color) {
-    const val = getAttr(color, W_NS, "val");
-    // Only a genuine 6-hex-digit value — "auto" and a themeColor reference
-    // (both absent from this val, or this val itself non-hex) are left
-    // unset rather than guessed, see this function's own doc comment above.
-    if (val !== undefined && /^[0-9A-Fa-f]{6}$/.test(val)) {
-      out.color = val;
-    }
-  }
-  const vertAlign = findChild(rPrEl, W_NS, "vertAlign");
-  if (vertAlign) {
-    const val = getAttr(vertAlign, W_NS, "val");
-    if (val === "superscript" || val === "subscript" || val === "baseline") {
-      out.vertAlign = val;
-    }
-  }
-  for (const tag of ["b", "i", "u"]) {
-    const el = findChild(rPrEl, W_NS, tag);
-    if (el) {
-      const val = getAttr(el, W_NS, "val");
-      out[tag] = val !== undefined && OFF_VALUES.has(val) ? "off" : "on";
-    }
-  }
-  return out;
-}
-
-/**
- * Compares two resolved values, treating an absent toggle and an explicit
- * "off" as the SAME state — `w:u w:val="none"` is not a deviation from "no
- * underline", it IS no underline spelled out (measured: 542/622 corpus
- * w:u are val="none"). Ported from same_state(), caught by that script's own
- * self-test after a first version that missed this.
- * @param {string | undefined} a
- * @param {string | undefined} b
- * @returns {boolean}
- */
-export function sameState(a, b) {
-  /** @param {string | undefined} v */
-  const isOff = (v) => v === undefined || v === "off";
-  if (isOff(a) && isOff(b)) return true;
-  return a === b;
-}
-
-/**
- * @typedef {object} StyleEntry
- * @property {string | null} basedOn
- * @property {Record<string, string>} pPr
- * @property {Record<string, string>} rPr
- */
-
-/**
- * @typedef {object} LoadedStyles
- * @property {{pPr: Record<string,string>, rPr: Record<string,string>}} docDefaults
- * @property {Record<string, StyleEntry>} styles  paragraph styles only, keyed by styleId
- * @property {string | null} defaultParagraphStyle
- */
-
-/**
- * docDefaults + every PARAGRAPH style, keyed by styleId. Character/table/
- * numbering styles are read (for `total`/`custom` bookkeeping parity with
- * the measurement script) but not stored — `rStyle` (character styles) is
- * 0/81,973 in the corpus (ADR-0017), so this scope matches what is actually
- * used.
- * @param {import("./xml-scan.js").XmlElement} stylesRoot
- * @returns {LoadedStyles}
- */
-export function loadStyles(stylesRoot) {
-  const dd = findChild(stylesRoot, W_NS, "docDefaults");
-  const pPrDefault = dd && findChild(dd, W_NS, "pPrDefault");
-  const rPrDefault = dd && findChild(dd, W_NS, "rPrDefault");
-  const docPPr = readPPr(pPrDefault && findChild(pPrDefault, W_NS, "pPr"));
-  const docRPr = readRPr(rPrDefault && findChild(rPrDefault, W_NS, "rPr"));
-
-  /** @type {Record<string, StyleEntry>} */
-  const styles = {};
-  let defaultPara = null;
-  for (const st of findChildren(stylesRoot, W_NS, "style")) {
-    if (getAttr(st, W_NS, "type") !== "paragraph") continue;
-    const sid = getAttr(st, W_NS, "styleId");
-    if (sid === undefined) continue;
-    const bo = findChild(st, W_NS, "basedOn");
-    styles[sid] = {
-      basedOn: bo ? (getAttr(bo, W_NS, "val") ?? null) : null,
-      pPr: readPPr(findChild(st, W_NS, "pPr")),
-      rPr: readRPr(findChild(st, W_NS, "rPr")),
-    };
-    if (getAttr(st, W_NS, "default") === "1") defaultPara = sid;
-  }
-  return { docDefaults: { pPr: docPPr, rPr: docRPr }, styles, defaultParagraphStyle: defaultPara };
-}
-
-/**
- * Root-first chain: [Normal, BodyText]. Cycle-safe.
- * @param {Record<string, StyleEntry>} styles
- * @param {string | null | undefined} styleId
- * @returns {string[]}
- */
-export function styleChain(styles, styleId) {
-  /** @type {string[]} */
-  const chain = [];
-  const seen = new Set();
-  let cur = styleId;
-  while (cur && styles[cur] && !seen.has(cur)) {
-    seen.add(cur);
-    chain.push(cur);
-    cur = styles[cur].basedOn;
-  }
-  chain.reverse();
-  return chain;
-}
-
-/**
- * @typedef {[string, "docDefaults" | "style" | "direct"]} ResolvedValue
- */
-
-/**
- * Effective value + WHERE it came from, per field. Order: docDefaults ->
- * style chain root-first (derived wins) -> direct.
- * @param {Record<string,string>} defaults
- * @param {Record<string, StyleEntry>} styles
- * @param {string | null | undefined} styleId
- * @param {Record<string,string>} direct
- * @param {"pPr" | "rPr"} which
- * @returns {Record<string, ResolvedValue>}
- */
-export function resolve(defaults, styles, styleId, direct, which) {
-  /** @type {Record<string, ResolvedValue>} */
-  const eff = {};
-  for (const [f, v] of Object.entries(defaults)) eff[f] = [v, "docDefaults"];
-  for (const sid of styleChain(styles, styleId)) {
-    for (const [f, v] of Object.entries(styles[sid][which])) eff[f] = [v, "style"];
-  }
-  for (const [f, v] of Object.entries(direct)) eff[f] = [v, "direct"];
-  return eff;
-}
+// styles.xml -> docDefaults / style chain / effective-value resolver. Ported
+// from scripts/measure-style-inheritance.py's load_styles()/style_chain()/
+// resolve()/same_state() — the algorithm, not the aggregate-measurement
+// machinery (new_acc/measure_document), which belongs only to that
+// standalone script. ADR-0017: "Çözümleyici sıfırdan yazılmayacak."
+//
+// Resolution order (docDefaults -> style chain root-first, derived wins ->
+// direct), ported unchanged.
+
+import { getAttr, findChild, findChildren } from "./xml-scan.js";
+import { W_NS } from "./ns.js";
+import { rejectCharacterStyle } from "./import-gate.js";
+
+const OFF_VALUES = new Set(["0", "false", "none"]);
+
+/**
+ * A `w:pPr` element -> flat {field: value}. Absent field = not set here.
+ * @param {import("./xml-scan.js").XmlElement | undefined} pPrEl
+ * @returns {Record<string, string>}
+ */
+export function readPPr(pPrEl) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!pPrEl) return out;
+  const jc = findChild(pPrEl, W_NS, "jc");
+  if (jc) {
+    const val = getAttr(jc, W_NS, "val");
+    if (val !== undefined) out.jc = val;
+  }
+  const ind = findChild(pPrEl, W_NS, "ind");
+  if (ind) {
+    for (const a of ["left", "right", "firstLine", "hanging"]) {
+      const v = getAttr(ind, W_NS, a);
+      if (v !== undefined) out[`ind.${a}`] = v;
+    }
+  }
+  const sp = findChild(pPrEl, W_NS, "spacing");
+  if (sp) {
+    for (const a of ["before", "after", "line", "lineRule"]) {
+      const v = getAttr(sp, W_NS, a);
+      if (v !== undefined) out[`spacing.${a}`] = v;
+    }
+  }
+  // Raw numId/ilvl only -- resolving them to a display marker needs
+  // numbering.xml, which this function has no access to (it is called for
+  // BOTH a style's own pPr and a paragraph's direct pPr, same as jc/ind/
+  // spacing above, so direct numPr correctly overrides a style's numPr
+  // through the existing resolve() cascade). import.js's internPPrRef adds
+  // the resolved `numPr.marker` field after this cascade runs.
+  const numPr = findChild(pPrEl, W_NS, "numPr");
+  if (numPr) {
+    const ilvl = findChild(numPr, W_NS, "ilvl");
+    if (ilvl) {
+      const v = getAttr(ilvl, W_NS, "val");
+      if (v !== undefined) out["numPr.ilvl"] = v;
+    }
+    const numId = findChild(numPr, W_NS, "numId");
+    if (numId) {
+      const v = getAttr(numId, W_NS, "val");
+      if (v !== undefined) out["numPr.numId"] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * A `w:rPr` element -> flat {field: value}. `font` collapses w:rFonts'
+ * ascii/hAnsi/cs in that order; a theme-only rFonts yields the sentinel
+ * "(tema)" — theme1.xml is deliberately not opened (ADR-0017 DOĞRULANMALI
+ * #6), and pretending the field is unset would hide that.
+ * A `w:rStyle` child (a reference to a character style) is rejected rather
+ * than silently ignored — ADR-0020 Karar 4: 0/81.973 real corpus runs carry
+ * one, so a run that does is corpus-external and this resolver has no
+ * mechanism to fold the referenced style's properties in.
+ * `color` is DISPLAY-only (render, not the `Marks`/toggle path — 2026-08-31
+ * decision, ADR-0026): a 6-hex-digit `w:val` is read straight through; a
+ * `w:themeColor` reference or `w:val="auto"` is left unset rather than
+ * guessed — measured 211 real corpus `w:color` elements, 0 carry either
+ * (theme1.xml is deliberately not opened, same reason as the `rFonts` theme
+ * sentinel above), so this is not a real-corpus gap today, only a documented
+ * refusal to invent a value.
+ * `vertAlign` is DISPLAY-only, same class as `color` (2026-09-01): only the
+ * three ST_VerticalAlignRun enum values (`superscript`/`subscript`/
+ * `baseline`) are read straight through; anything else is left unset rather
+ * than guessed — measured 0/576 real corpus `w:vertAlign` elements carry a
+ * fourth value.
+ * @param {import("./xml-scan.js").XmlElement | undefined} rPrEl
+ * @returns {Record<string, string>}
+ */
+export function readRPr(rPrEl) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!rPrEl) return out;
+  if (findChild(rPrEl, W_NS, "rStyle")) {
+    rejectCharacterStyle(`w:rPr at byte ${rPrEl.start}`);
+  }
+  const sz = findChild(rPrEl, W_NS, "sz");
+  if (sz) {
+    const val = getAttr(sz, W_NS, "val");
+    if (val) out.sz = val;
+  }
+  const rf = findChild(rPrEl, W_NS, "rFonts");
+  if (rf) {
+    let name;
+    for (const a of ["ascii", "hAnsi", "cs"]) {
+      const v = getAttr(rf, W_NS, a);
+      if (v) {
+        name = v;
+        break;
+      }
+    }
+    if (name === undefined) {
+      for (const a of ["asciiTheme", "hAnsiTheme", "cstheme"]) {
+        if (getAttr(rf, W_NS, a)) {
+          name = "(tema)";
+          break;
+        }
+      }
+    }
+    if (name !== undefined) out.font = name;
+  }
+  const color = findChild(rPrEl, W_NS, "color");
+  if (color) {
+    const val = getAttr(color, W_NS, "val");
+    // Only a genuine 6-hex-digit value — "auto" and a themeColor reference
+    // (both absent from this val, or this val itself non-hex) are left
+    // unset rather than guessed, see this function's own doc comment above.
+    if (val !== undefined && /^[0-9A-Fa-f]{6}$/.test(val)) {
+      out.color = val;
+    }
+  }
+  const vertAlign = findChild(rPrEl, W_NS, "vertAlign");
+  if (vertAlign) {
+    const val = getAttr(vertAlign, W_NS, "val");
+    if (val === "superscript" || val === "subscript" || val === "baseline") {
+      out.vertAlign = val;
+    }
+  }
+  for (const tag of ["b", "i", "u"]) {
+    const el = findChild(rPrEl, W_NS, tag);
+    if (el) {
+      const val = getAttr(el, W_NS, "val");
+      out[tag] = val !== undefined && OFF_VALUES.has(val) ? "off" : "on";
+    }
+  }
+  return out;
+}
+
+/**
+ * Compares two resolved values, treating an absent toggle and an explicit
+ * "off" as the SAME state — `w:u w:val="none"` is not a deviation from "no
+ * underline", it IS no underline spelled out (measured: 542/622 corpus
+ * w:u are val="none"). Ported from same_state(), caught by that script's own
+ * self-test after a first version that missed this.
+ * @param {string | undefined} a
+ * @param {string | undefined} b
+ * @returns {boolean}
+ */
+export function sameState(a, b) {
+  /** @param {string | undefined} v */
+  const isOff = (v) => v === undefined || v === "off";
+  if (isOff(a) && isOff(b)) return true;
+  return a === b;
+}
+
+/**
+ * @typedef {object} StyleEntry
+ * @property {string | null} basedOn
+ * @property {Record<string, string>} pPr
+ * @property {Record<string, string>} rPr
+ */
+
+/**
+ * @typedef {object} LoadedStyles
+ * @property {{pPr: Record<string,string>, rPr: Record<string,string>}} docDefaults
+ * @property {Record<string, StyleEntry>} styles  paragraph styles only, keyed by styleId
+ * @property {string | null} defaultParagraphStyle
+ */
+
+/**
+ * docDefaults + every PARAGRAPH style, keyed by styleId. Character/table/
+ * numbering styles are read (for `total`/`custom` bookkeeping parity with
+ * the measurement script) but not stored — `rStyle` (character styles) is
+ * 0/81,973 in the corpus (ADR-0017), so this scope matches what is actually
+ * used.
+ * @param {import("./xml-scan.js").XmlElement} stylesRoot
+ * @returns {LoadedStyles}
+ */
+export function loadStyles(stylesRoot) {
+  const dd = findChild(stylesRoot, W_NS, "docDefaults");
+  const pPrDefault = dd && findChild(dd, W_NS, "pPrDefault");
+  const rPrDefault = dd && findChild(dd, W_NS, "rPrDefault");
+  const docPPr = readPPr(pPrDefault && findChild(pPrDefault, W_NS, "pPr"));
+  const docRPr = readRPr(rPrDefault && findChild(rPrDefault, W_NS, "rPr"));
+
+  /** @type {Record<string, StyleEntry>} */
+  const styles = {};
+  let defaultPara = null;
+  for (const st of findChildren(stylesRoot, W_NS, "style")) {
+    if (getAttr(st, W_NS, "type") !== "paragraph") continue;
+    const sid = getAttr(st, W_NS, "styleId");
+    if (sid === undefined) continue;
+    const bo = findChild(st, W_NS, "basedOn");
+    styles[sid] = {
+      basedOn: bo ? (getAttr(bo, W_NS, "val") ?? null) : null,
+      pPr: readPPr(findChild(st, W_NS, "pPr")),
+      rPr: readRPr(findChild(st, W_NS, "rPr")),
+    };
+    if (getAttr(st, W_NS, "default") === "1") defaultPara = sid;
+  }
+  return { docDefaults: { pPr: docPPr, rPr: docRPr }, styles, defaultParagraphStyle: defaultPara };
+}
+
+/**
+ * Root-first chain: [Normal, BodyText]. Cycle-safe.
+ * @param {Record<string, StyleEntry>} styles
+ * @param {string | null | undefined} styleId
+ * @returns {string[]}
+ */
+export function styleChain(styles, styleId) {
+  /** @type {string[]} */
+  const chain = [];
+  const seen = new Set();
+  let cur = styleId;
+  while (cur && styles[cur] && !seen.has(cur)) {
+    seen.add(cur);
+    chain.push(cur);
+    cur = styles[cur].basedOn;
+  }
+  chain.reverse();
+  return chain;
+}
+
+/**
+ * @typedef {[string, "docDefaults" | "style" | "direct"]} ResolvedValue
+ */
+
+/**
+ * Effective value + WHERE it came from, per field. Order: docDefaults ->
+ * style chain root-first (derived wins) -> direct.
+ * @param {Record<string,string>} defaults
+ * @param {Record<string, StyleEntry>} styles
+ * @param {string | null | undefined} styleId
+ * @param {Record<string,string>} direct
+ * @param {"pPr" | "rPr"} which
+ * @returns {Record<string, ResolvedValue>}
+ */
+export function resolve(defaults, styles, styleId, direct, which) {
+  /** @type {Record<string, ResolvedValue>} */
+  const eff = {};
+  for (const [f, v] of Object.entries(defaults)) eff[f] = [v, "docDefaults"];
+  for (const sid of styleChain(styles, styleId)) {
+    for (const [f, v] of Object.entries(styles[sid][which])) eff[f] = [v, "style"];
+  }
+  for (const [f, v] of Object.entries(direct)) eff[f] = [v, "direct"];
+  return eff;
+}

package/dist/io/ooxml/units.js

@@ -1,43 +1,43 @@
-// EMU <-> pt, in ONE place. OOXML measures geometry in EMU (English Metric
-// Units); the model measures it in points. Import needs one direction, the
-// geometry export (P6) needs the other, and a second copy of the constant in a
-// second file is exactly how the two directions drift apart.
-
-export const EMU_PER_PT = 12700;
-
-/**
- * `round(value / 12700, 2)` — measured 2026-08-27: across all 7,297 unique EMU
- * values actually present in the 46-document corpus (posOffset, extent, off,
- * ext), Python's round() (round-half-to-even) and this expression never
- * disagree. A bit-exact port of Python's round() was NOT written — there was
- * nothing, measured, for it to fix.
- * @param {number} emu
- * @returns {number}
- */
-export function emuToPt(emu) {
-  return Math.round((emu / EMU_PER_PT) * 100) / 100;
-}
-
-/**
- * pt -> EMU, the geometry export's write direction.
- *
- * 🔴 NOT a lossless inverse of `emuToPt`, and callers must not treat it as one:
- * `emuToPt` rounds to 2 decimals (~0.005 pt ~ 64 EMU), so a value that made a
- * round trip can differ from the original integer. Measured 2026-08-29 on the
- * corpus: 791 of 7,990 `cx` values and 482 `cy` values do NOT survive
- * `emuToPt -> ptToEmu` (AA01's first box: 6674484 -> 525.55 pt -> 6674485).
- * That is why the splice writes ONLY the coordinates the user actually changed
- * and carries every untouched one through as its original bytes.
- *
- * Throws on a non-finite input rather than emitting it: `Math.round(NaN)` is
- * `NaN` and `String(NaN)` is `"NaN"`, which would reach document.xml and make
- * Word refuse the file.
- * @param {number} pt
- * @returns {number}  integer EMU
- */
-export function ptToEmu(pt) {
-  if (!Number.isFinite(pt)) {
-    throw new TypeError(`ptToEmu: non-finite pt value (${pt}) — refusing to write it to document.xml`);
-  }
-  return Math.round(pt * EMU_PER_PT);
-}
+// EMU <-> pt, in ONE place. OOXML measures geometry in EMU (English Metric
+// Units); the model measures it in points. Import needs one direction, the
+// geometry export (P6) needs the other, and a second copy of the constant in a
+// second file is exactly how the two directions drift apart.
+
+export const EMU_PER_PT = 12700;
+
+/**
+ * `round(value / 12700, 2)` — measured 2026-08-27: across all 7,297 unique EMU
+ * values actually present in the 46-document corpus (posOffset, extent, off,
+ * ext), Python's round() (round-half-to-even) and this expression never
+ * disagree. A bit-exact port of Python's round() was NOT written — there was
+ * nothing, measured, for it to fix.
+ * @param {number} emu
+ * @returns {number}
+ */
+export function emuToPt(emu) {
+  return Math.round((emu / EMU_PER_PT) * 100) / 100;
+}
+
+/**
+ * pt -> EMU, the geometry export's write direction.
+ *
+ * 🔴 NOT a lossless inverse of `emuToPt`, and callers must not treat it as one:
+ * `emuToPt` rounds to 2 decimals (~0.005 pt ~ 64 EMU), so a value that made a
+ * round trip can differ from the original integer. Measured 2026-08-29 on the
+ * corpus: 791 of 7,990 `cx` values and 482 `cy` values do NOT survive
+ * `emuToPt -> ptToEmu` (AA01's first box: 6674484 -> 525.55 pt -> 6674485).
+ * That is why the splice writes ONLY the coordinates the user actually changed
+ * and carries every untouched one through as its original bytes.
+ *
+ * Throws on a non-finite input rather than emitting it: `Math.round(NaN)` is
+ * `NaN` and `String(NaN)` is `"NaN"`, which would reach document.xml and make
+ * Word refuse the file.
+ * @param {number} pt
+ * @returns {number}  integer EMU
+ */
+export function ptToEmu(pt) {
+  if (!Number.isFinite(pt)) {
+    throw new TypeError(`ptToEmu: non-finite pt value (${pt}) — refusing to write it to document.xml`);
+  }
+  return Math.round(pt * EMU_PER_PT);
+}