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

package/dist/io/ooxml/import-gate.js

@@ -1,200 +1,200 @@
-// ADR-0010's two-granularity import gate, ported from check_group_identity()
-// and convert()'s own `is_locked` computation — never re-decided here.
-//
-// 1. A class with ZERO corpus examples (non-identity group transform, a
-//    nested group) -> REJECT THE WHOLE DOCUMENT rather than silently
-//    mis-place one shape.
-// 2. A class that DOES occur (a shape's own rotation/flip, independent of
-//    any group) -> never rejected, the shape is just marked `locked`.
-
-import { WPG_NS, A_NS } from "./ns.js";
-
-/**
- * Plain Error, not a custom class — matches every other src/ file's
- * convention (zip-reject.js, xml-scan.js): a distinguishing message, not a
- * type hierarchy.
- * @param {string} message
- * @returns {never}
- */
-function rejectImport(message) {
-  throw new Error(`import-gate: REJECTED — ${message}`);
-}
-
-/**
- * @param {import("./xml-scan.js").XmlNode} el
- * @returns {boolean}
- */
-function isNestedGroup(el) {
-  if (el.kind === "element" && ((el.uri === WPG_NS && el.localName === "grpSp") || (el.uri === A_NS && el.localName === "grpSp"))) {
-    return true;
-  }
-  if (el.kind !== "element") return false;
-  for (const child of el.children) {
-    if (isNestedGroup(child)) return true;
-  }
-  return false;
-}
-
-/**
- * Raises if the group's OWN transform is not identity (scale != 1.0 on
- * either axis, chOff != (0,0), rot != 0, or any flip), or if the group
- * contains a nested group at any depth (`wpg:grpSp` or `a:grpSp` — corpus-
- * measured as never occurring, but checked both ways since which spelling a
- * document might use was exactly the kind of thing a prior regex pass in
- * this project missed three times).
- *
- * A shape's OWN rotation (independent of its group) is NOT checked here —
- * see `isShapeLocked`. This function is about the GROUP's transform only.
- *
- * @param {import("./drawingml.js").Xfrm} gXfrm
- * @param {import("./xml-scan.js").XmlElement} groupEl
- * @param {string} context
- * @returns {{scaleX: number, scaleY: number}}
- */
-export function checkGroupIdentity(gXfrm, groupEl, context) {
-  const scaleX = gXfrm.chExtCx ? gXfrm.extCx / gXfrm.chExtCx : 1.0;
-  const scaleY = gXfrm.chExtCy ? gXfrm.extCy / gXfrm.chExtCy : 1.0;
-
-  /** @type {string[]} */
-  const problems = [];
-  if (scaleX !== 1.0 || scaleY !== 1.0) {
-    problems.push(`non-identity scale (scale_x=${scaleX}, scale_y=${scaleY})`);
-  }
-  if (gXfrm.chOffX !== 0 || gXfrm.chOffY !== 0) {
-    problems.push(`chOff != (0,0): (${gXfrm.chOffX},${gXfrm.chOffY})`);
-  }
-  if (gXfrm.rot !== 0) {
-    problems.push(`group rot != 0: ${gXfrm.rot}`);
-  }
-  if (gXfrm.flipH || gXfrm.flipV) {
-    problems.push(`group flip: flipH=${gXfrm.flipH} flipV=${gXfrm.flipV}`);
-  }
-  if (isNestedGroup(groupEl)) {
-    problems.push("nested group found (wpg:grpSp or a:grpSp)");
-  }
-
-  if (problems.length > 0) {
-    rejectImport(`${context}: ${problems.join("; ")}`);
-  }
-  return { scaleX, scaleY };
-}
-
-/**
- * @param {{rot: number, flipH: boolean, flipV: boolean}} ownXfrm
- * @returns {boolean}
- */
-export function isShapeLocked(ownXfrm) {
-  return ownXfrm.rot !== 0 || ownXfrm.flipH || ownXfrm.flipV;
-}
-
-/**
- * An anchor without `wp:posOffset` under positionH/positionV (an
- * alignment-based anchor using `wp:align` instead uses a different
- * addressing scheme this importer does not interpret), or without
- * `wp:extent`, has no safe on-page placement. Measured 2026-08-27: 0/8,737
- * real corpus anchors trigger this — every anchor in all 46 documents uses
- * absolute posOffset + extent. Silently dropping such an anchor (the
- * pre-2026-08-27 behavior, a bare `continue`) risked discarding real,
- * positioned content from a corpus-external document with no signal
- * anywhere that anything was lost. Call only when at least one of the three
- * booleans is true — matches the caller's own `if` guard, like `continue`
- * did before it.
- * @param {boolean} missingPosOffsetH
- * @param {boolean} missingPosOffsetV
- * @param {boolean} missingExtent
- * @param {string} context
- * @returns {never}
- */
-export function rejectAnchorPlacement(missingPosOffsetH, missingPosOffsetV, missingExtent, context) {
-  /** @type {string[]} */
-  const problems = [];
-  if (missingPosOffsetH || missingPosOffsetV) {
-    problems.push("missing wp:posOffset under positionH/positionV (an alignment-based anchor, e.g. wp:align, is not supported)");
-  }
-  if (missingExtent) {
-    problems.push("missing wp:extent");
-  }
-  rejectImport(`${context}: ${problems.join("; ")}`);
-}
-
-/**
- * An anchor with no `a:graphic/a:graphicData` at all wraps nothing this
- * importer can render. Measured 2026-08-27: 0/8,737 real corpus anchors
- * trigger this.
- * @param {string} context
- * @returns {never}
- */
-export function rejectMissingGraphicData(context) {
-  rejectImport(`${context}: anchor has no a:graphic/a:graphicData`);
-}
-
-/**
- * A group (`wpg:wgp`) with no parseable `a:xfrm` under its own
- * `wpg:grpSpPr` has no chOff/chExt to place or scale its children by —
- * `checkGroupIdentity` (which checks whether that transform IS identity)
- * can only run once this passes. Measured 2026-08-27: 0/459 real corpus
- * groups trigger this.
- * @param {string} context
- * @returns {never}
- */
-export function rejectMissingGroupTransform(context) {
-  rejectImport(`${context}: group has no parseable a:xfrm under wpg:grpSpPr`);
-}
-
-/**
- * A shape (`wps:wsp`) inside a group with no parseable `a:xfrm` under its
- * own `wps:spPr` has no off/ext to compute a position from — unlike a
- * non-grouped wsp (whose absolute size comes from the anchor's own
- * wp:extent instead, independent of spPr), a group child's position is
- * defined ONLY relative to the group's chOff/chExt via its own xfrm.
- * Measured 2026-08-27: 0/2,598 real corpus group-child shapes trigger this.
- * @param {string} context
- * @returns {never}
- */
-export function rejectMissingShapeTransform(context) {
-  rejectImport(`${context}: group child shape has no parseable a:xfrm under wps:spPr`);
-}
-
-/**
- * A non-grouped anchor's `a:graphicData` holding none of `wpg:wgp`,
- * `wps:wsp`, or `pic:pic` is some other graphic type this importer has no
- * model for (a chart, SmartArt diagram, OLE object, or ink annotation —
- * ADR-0020 §7's own reserved REJECTED class). Measured 2026-08-27: 0/8,278
- * real corpus non-group anchors trigger this.
- * @param {string} context
- * @returns {never}
- */
-export function rejectUnsupportedGraphicDataKind(context) {
-  rejectImport(`${context}: a:graphicData holds none of wpg:wgp, wps:wsp, pic:pic (unsupported graphic type — chart, diagram, OLE object, or ink)`);
-}
-
-/**
- * A `w:drawing` wrapping `wp:inline` (in-text-flow placement) instead of
- * `wp:anchor` (floating placement) uses an addressing scheme this importer
- * never reads any coordinate from — `collectAnchors` only walks for
- * `wp:anchor` children, so an inline drawing was previously absent from the
- * anchors array with no signal anywhere that anything had been dropped.
- * ADR-0020 Karar 4's own table (`wp:inline` -> REJECTED, "corpus'ta 0")
- * predates this function; measured again 2026-08-27 against the real
- * corpus: 0/46 documents contain one.
- * @param {string} context
- * @returns {never}
- */
-export function rejectInlineDrawing(context) {
-  rejectImport(`${context}: w:drawing wraps wp:inline (in-text-flow placement is not supported, only wp:anchor)`);
-}
-
-/**
- * A `w:rPr` carrying `w:rStyle` (a reference to a character style defined in
- * styles.xml) is never resolved by this importer — `readRPr` reads direct
- * toggles (b/i/u), size, and font only, and a character-style reference
- * silently produced whatever the run's OWN direct properties happened to be,
- * with no signal that the style's contribution was missing. ADR-0020 Karar
- * 4's own table (`w:rStyle` -> REJECTED, "0/81.973" runs); measured again
- * 2026-08-27 against the real corpus: still 0/46 documents contain one.
- * @param {string} context
- * @returns {never}
- */
-export function rejectCharacterStyle(context) {
-  rejectImport(`${context}: w:rPr carries w:rStyle (character-style reference is not resolved)`);
-}
+// ADR-0010's two-granularity import gate, ported from check_group_identity()
+// and convert()'s own `is_locked` computation — never re-decided here.
+//
+// 1. A class with ZERO corpus examples (non-identity group transform, a
+//    nested group) -> REJECT THE WHOLE DOCUMENT rather than silently
+//    mis-place one shape.
+// 2. A class that DOES occur (a shape's own rotation/flip, independent of
+//    any group) -> never rejected, the shape is just marked `locked`.
+
+import { WPG_NS, A_NS } from "./ns.js";
+
+/**
+ * Plain Error, not a custom class — matches every other src/ file's
+ * convention (zip-reject.js, xml-scan.js): a distinguishing message, not a
+ * type hierarchy.
+ * @param {string} message
+ * @returns {never}
+ */
+function rejectImport(message) {
+  throw new Error(`import-gate: REJECTED — ${message}`);
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlNode} el
+ * @returns {boolean}
+ */
+function isNestedGroup(el) {
+  if (el.kind === "element" && ((el.uri === WPG_NS && el.localName === "grpSp") || (el.uri === A_NS && el.localName === "grpSp"))) {
+    return true;
+  }
+  if (el.kind !== "element") return false;
+  for (const child of el.children) {
+    if (isNestedGroup(child)) return true;
+  }
+  return false;
+}
+
+/**
+ * Raises if the group's OWN transform is not identity (scale != 1.0 on
+ * either axis, chOff != (0,0), rot != 0, or any flip), or if the group
+ * contains a nested group at any depth (`wpg:grpSp` or `a:grpSp` — corpus-
+ * measured as never occurring, but checked both ways since which spelling a
+ * document might use was exactly the kind of thing a prior regex pass in
+ * this project missed three times).
+ *
+ * A shape's OWN rotation (independent of its group) is NOT checked here —
+ * see `isShapeLocked`. This function is about the GROUP's transform only.
+ *
+ * @param {import("./drawingml.js").Xfrm} gXfrm
+ * @param {import("./xml-scan.js").XmlElement} groupEl
+ * @param {string} context
+ * @returns {{scaleX: number, scaleY: number}}
+ */
+export function checkGroupIdentity(gXfrm, groupEl, context) {
+  const scaleX = gXfrm.chExtCx ? gXfrm.extCx / gXfrm.chExtCx : 1.0;
+  const scaleY = gXfrm.chExtCy ? gXfrm.extCy / gXfrm.chExtCy : 1.0;
+
+  /** @type {string[]} */
+  const problems = [];
+  if (scaleX !== 1.0 || scaleY !== 1.0) {
+    problems.push(`non-identity scale (scale_x=${scaleX}, scale_y=${scaleY})`);
+  }
+  if (gXfrm.chOffX !== 0 || gXfrm.chOffY !== 0) {
+    problems.push(`chOff != (0,0): (${gXfrm.chOffX},${gXfrm.chOffY})`);
+  }
+  if (gXfrm.rot !== 0) {
+    problems.push(`group rot != 0: ${gXfrm.rot}`);
+  }
+  if (gXfrm.flipH || gXfrm.flipV) {
+    problems.push(`group flip: flipH=${gXfrm.flipH} flipV=${gXfrm.flipV}`);
+  }
+  if (isNestedGroup(groupEl)) {
+    problems.push("nested group found (wpg:grpSp or a:grpSp)");
+  }
+
+  if (problems.length > 0) {
+    rejectImport(`${context}: ${problems.join("; ")}`);
+  }
+  return { scaleX, scaleY };
+}
+
+/**
+ * @param {{rot: number, flipH: boolean, flipV: boolean}} ownXfrm
+ * @returns {boolean}
+ */
+export function isShapeLocked(ownXfrm) {
+  return ownXfrm.rot !== 0 || ownXfrm.flipH || ownXfrm.flipV;
+}
+
+/**
+ * An anchor without `wp:posOffset` under positionH/positionV (an
+ * alignment-based anchor using `wp:align` instead uses a different
+ * addressing scheme this importer does not interpret), or without
+ * `wp:extent`, has no safe on-page placement. Measured 2026-08-27: 0/8,737
+ * real corpus anchors trigger this — every anchor in all 46 documents uses
+ * absolute posOffset + extent. Silently dropping such an anchor (the
+ * pre-2026-08-27 behavior, a bare `continue`) risked discarding real,
+ * positioned content from a corpus-external document with no signal
+ * anywhere that anything was lost. Call only when at least one of the three
+ * booleans is true — matches the caller's own `if` guard, like `continue`
+ * did before it.
+ * @param {boolean} missingPosOffsetH
+ * @param {boolean} missingPosOffsetV
+ * @param {boolean} missingExtent
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectAnchorPlacement(missingPosOffsetH, missingPosOffsetV, missingExtent, context) {
+  /** @type {string[]} */
+  const problems = [];
+  if (missingPosOffsetH || missingPosOffsetV) {
+    problems.push("missing wp:posOffset under positionH/positionV (an alignment-based anchor, e.g. wp:align, is not supported)");
+  }
+  if (missingExtent) {
+    problems.push("missing wp:extent");
+  }
+  rejectImport(`${context}: ${problems.join("; ")}`);
+}
+
+/**
+ * An anchor with no `a:graphic/a:graphicData` at all wraps nothing this
+ * importer can render. Measured 2026-08-27: 0/8,737 real corpus anchors
+ * trigger this.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectMissingGraphicData(context) {
+  rejectImport(`${context}: anchor has no a:graphic/a:graphicData`);
+}
+
+/**
+ * A group (`wpg:wgp`) with no parseable `a:xfrm` under its own
+ * `wpg:grpSpPr` has no chOff/chExt to place or scale its children by —
+ * `checkGroupIdentity` (which checks whether that transform IS identity)
+ * can only run once this passes. Measured 2026-08-27: 0/459 real corpus
+ * groups trigger this.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectMissingGroupTransform(context) {
+  rejectImport(`${context}: group has no parseable a:xfrm under wpg:grpSpPr`);
+}
+
+/**
+ * A shape (`wps:wsp`) inside a group with no parseable `a:xfrm` under its
+ * own `wps:spPr` has no off/ext to compute a position from — unlike a
+ * non-grouped wsp (whose absolute size comes from the anchor's own
+ * wp:extent instead, independent of spPr), a group child's position is
+ * defined ONLY relative to the group's chOff/chExt via its own xfrm.
+ * Measured 2026-08-27: 0/2,598 real corpus group-child shapes trigger this.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectMissingShapeTransform(context) {
+  rejectImport(`${context}: group child shape has no parseable a:xfrm under wps:spPr`);
+}
+
+/**
+ * A non-grouped anchor's `a:graphicData` holding none of `wpg:wgp`,
+ * `wps:wsp`, or `pic:pic` is some other graphic type this importer has no
+ * model for (a chart, SmartArt diagram, OLE object, or ink annotation —
+ * ADR-0020 §7's own reserved REJECTED class). Measured 2026-08-27: 0/8,278
+ * real corpus non-group anchors trigger this.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectUnsupportedGraphicDataKind(context) {
+  rejectImport(`${context}: a:graphicData holds none of wpg:wgp, wps:wsp, pic:pic (unsupported graphic type — chart, diagram, OLE object, or ink)`);
+}
+
+/**
+ * A `w:drawing` wrapping `wp:inline` (in-text-flow placement) instead of
+ * `wp:anchor` (floating placement) uses an addressing scheme this importer
+ * never reads any coordinate from — `collectAnchors` only walks for
+ * `wp:anchor` children, so an inline drawing was previously absent from the
+ * anchors array with no signal anywhere that anything had been dropped.
+ * ADR-0020 Karar 4's own table (`wp:inline` -> REJECTED, "corpus'ta 0")
+ * predates this function; measured again 2026-08-27 against the real
+ * corpus: 0/46 documents contain one.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectInlineDrawing(context) {
+  rejectImport(`${context}: w:drawing wraps wp:inline (in-text-flow placement is not supported, only wp:anchor)`);
+}
+
+/**
+ * A `w:rPr` carrying `w:rStyle` (a reference to a character style defined in
+ * styles.xml) is never resolved by this importer — `readRPr` reads direct
+ * toggles (b/i/u), size, and font only, and a character-style reference
+ * silently produced whatever the run's OWN direct properties happened to be,
+ * with no signal that the style's contribution was missing. ADR-0020 Karar
+ * 4's own table (`w:rStyle` -> REJECTED, "0/81.973" runs); measured again
+ * 2026-08-27 against the real corpus: still 0/46 documents contain one.
+ * @param {string} context
+ * @returns {never}
+ */
+export function rejectCharacterStyle(context) {
+  rejectImport(`${context}: w:rPr carries w:rStyle (character-style reference is not resolved)`);
+}