@beyondwork/docx-react-component 1.0.70 → 1.0.72

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -8,6 +8,7 @@
 
 import type {
   CanonicalParagraphFormatting,
+  FrameProperties,
   ParagraphBorders,
   ParagraphIndentation,
   ParagraphShading,
@@ -49,9 +50,37 @@ const PPR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
   "suppressLineNumbers",
   "suppressAutoHyphens",
   "outlineLvl",
+  "framePr",
   "rPr",
 ]);
 
+const FRAME_H_RULE_VOCAB = new Set<NonNullable<FrameProperties["hRule"]>>(["auto", "atLeast", "exact"]);
+const FRAME_X_ALIGN_VOCAB = new Set<NonNullable<FrameProperties["xAlign"]>>([
+  "left",
+  "center",
+  "right",
+  "inside",
+  "outside",
+]);
+const FRAME_Y_ALIGN_VOCAB = new Set<NonNullable<FrameProperties["yAlign"]>>([
+  "top",
+  "center",
+  "bottom",
+  "inside",
+  "outside",
+  "inline",
+]);
+const FRAME_ANCHOR_VOCAB = new Set<NonNullable<FrameProperties["hAnchor"]>>(["text", "margin", "page"]);
+const FRAME_WRAP_VOCAB = new Set<NonNullable<FrameProperties["wrap"]>>([
+  "around",
+  "auto",
+  "none",
+  "notBeside",
+  "tight",
+  "through",
+]);
+const FRAME_DROP_CAP_VOCAB = new Set<NonNullable<FrameProperties["dropCap"]>>(["none", "drop", "margin"]);
+
 const PPR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
   modelledChildNames: PPR_MODELLED_CHILDREN,
   modelledChildAttributes: new Map(),
@@ -164,6 +193,76 @@ function readShading(node: XmlElementNode): ParagraphShading | undefined {
   };
 }
 
+/**
+ * `<w:framePr>` — paragraph text-frame properties (ECMA-376 §17.3.1.11).
+ *
+ * All children of framePr are attributes on a single self-closing element;
+ * this reader maps each modelled attribute to its typed field and ignores
+ * extension attributes (`w14:*`, `w15:*`, `mc:Ignorable`, etc.). Extension-
+ * attribute round-trip via `FrameProperties.rawXml` is a TODO — the current
+ * signature doesn't receive the source XML string, so rawXml is left unset.
+ * The typed attributes cover the CCEP cases we've seen (2-column inset
+ * text frames, drop-caps); extension attrs are rare in that corpus.
+ */
+function readFrameProperties(node: XmlElementNode): FrameProperties | undefined {
+  const out: FrameProperties = {};
+  const width = readIntAttr(node, "w:w");
+  if (width !== undefined) out.widthTwips = width;
+  const height = readIntAttr(node, "w:h");
+  if (height !== undefined) out.heightTwips = height;
+  const hRuleRaw = (node.attributes["w:hRule"] ?? node.attributes.hRule)?.trim();
+  if (hRuleRaw) {
+    const lower = hRuleRaw.charAt(0).toLowerCase() + hRuleRaw.slice(1);
+    const candidate = lower === "atleast" ? "atLeast" : lower;
+    if (FRAME_H_RULE_VOCAB.has(candidate as NonNullable<FrameProperties["hRule"]>)) {
+      out.hRule = candidate as NonNullable<FrameProperties["hRule"]>;
+    }
+  }
+  const x = readIntAttr(node, "w:x");
+  if (x !== undefined) out.xTwips = x;
+  const y = readIntAttr(node, "w:y");
+  if (y !== undefined) out.yTwips = y;
+  const xAlign = (node.attributes["w:xAlign"] ?? node.attributes.xAlign)?.toLowerCase().trim();
+  if (xAlign && FRAME_X_ALIGN_VOCAB.has(xAlign as NonNullable<FrameProperties["xAlign"]>)) {
+    out.xAlign = xAlign as NonNullable<FrameProperties["xAlign"]>;
+  }
+  const yAlign = (node.attributes["w:yAlign"] ?? node.attributes.yAlign)?.toLowerCase().trim();
+  if (yAlign && FRAME_Y_ALIGN_VOCAB.has(yAlign as NonNullable<FrameProperties["yAlign"]>)) {
+    out.yAlign = yAlign as NonNullable<FrameProperties["yAlign"]>;
+  }
+  const hAnchor = (node.attributes["w:hAnchor"] ?? node.attributes.hAnchor)?.toLowerCase().trim();
+  if (hAnchor && FRAME_ANCHOR_VOCAB.has(hAnchor as NonNullable<FrameProperties["hAnchor"]>)) {
+    out.hAnchor = hAnchor as NonNullable<FrameProperties["hAnchor"]>;
+  }
+  const vAnchor = (node.attributes["w:vAnchor"] ?? node.attributes.vAnchor)?.toLowerCase().trim();
+  if (vAnchor && FRAME_ANCHOR_VOCAB.has(vAnchor as NonNullable<FrameProperties["vAnchor"]>)) {
+    out.vAnchor = vAnchor as NonNullable<FrameProperties["vAnchor"]>;
+  }
+  const wrapRaw = (node.attributes["w:wrap"] ?? node.attributes.wrap)?.trim();
+  if (wrapRaw) {
+    const wrapLower = wrapRaw.charAt(0).toLowerCase() + wrapRaw.slice(1);
+    const wrapCandidate = wrapLower === "notbeside" ? "notBeside" : wrapLower;
+    if (FRAME_WRAP_VOCAB.has(wrapCandidate as NonNullable<FrameProperties["wrap"]>)) {
+      out.wrap = wrapCandidate as NonNullable<FrameProperties["wrap"]>;
+    }
+  }
+  const hSpace = readIntAttr(node, "w:hSpace");
+  if (hSpace !== undefined) out.hSpaceTwips = hSpace;
+  const vSpace = readIntAttr(node, "w:vSpace");
+  if (vSpace !== undefined) out.vSpaceTwips = vSpace;
+  const dropCap = (node.attributes["w:dropCap"] ?? node.attributes.dropCap)?.toLowerCase().trim();
+  if (dropCap && FRAME_DROP_CAP_VOCAB.has(dropCap as NonNullable<FrameProperties["dropCap"]>)) {
+    out.dropCap = dropCap as NonNullable<FrameProperties["dropCap"]>;
+  }
+  const lines = readIntAttr(node, "w:lines");
+  if (lines !== undefined) out.lines = lines;
+  const anchorLockRaw = (node.attributes["w:anchorLock"] ?? node.attributes.anchorLock)?.toLowerCase().trim();
+  if (anchorLockRaw !== undefined && anchorLockRaw.length > 0) {
+    out.anchorLock = !(anchorLockRaw === "false" || anchorLockRaw === "0" || anchorLockRaw === "off");
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 export function readParagraphProperties(
   node: XmlElementNode | undefined,
 ): CanonicalParagraphFormatting | undefined {
@@ -237,6 +336,12 @@ export function readParagraphProperties(
   const outline = readIntVal(findChildOptional(node, "outlineLvl"));
   if (outline !== undefined) out.outlineLevel = outline;
 
+  const framePrNode = findChildOptional(node, "framePr");
+  if (framePrNode) {
+    const frameProperties = readFrameProperties(framePrNode);
+    if (frameProperties) out.frameProperties = frameProperties;
+  }
+
   const rPrNode = findChildOptional(node, "rPr");
   const markRpr = readRunProperties(rPrNode);
   if (markRpr) out.paragraphMarkRunProperties = markRpr;

package/src/model/canonical-document.ts

@@ -697,6 +697,7 @@ export type DocumentNode =
   | HardBreakNode
   | TabNode
   | ColumnBreakNode
+  | PageBreakNode
   | SymbolNode
   | HyperlinkNode
   | ImageNode
@@ -874,6 +875,20 @@ export interface CanonicalParagraphFormatting {
   suppressLineNumbers?: boolean;
   suppressAutoHyphens?: boolean;
   paragraphMarkRunProperties?: CanonicalRunFormatting;
+  /**
+   * `<w:framePr>` — paragraph text-frame properties (ECMA-376 §17.3.1.11).
+   * Absent on ordinary paragraphs. When present, the paragraph renders
+   * inside a positioned text frame rather than in-flow. Used in CCEP-style
+   * templates for side-by-side "instructional column + body column"
+   * paragraphs and for drop-caps.
+   *
+   * Added 2026-04-23 per `docs/KNOWN-ISSUES-VISUAL.md §2.3 "w:framePr
+   * 2-column inset text frames"`. Before this type existed, L01's parser
+   * fell through to `OpaqueBlockNode` whenever `<w:pPr>` contained
+   * `<w:framePr>`, which hid the paragraph from L04 pagination and L11
+   * render. Canonical representation unblocks downstream adoption.
+   */
+  frameProperties?: FrameProperties;
   /**
    * Unmodelled direct children of `<w:pPr>` captured verbatim for round-trip.
    * See `src/io/ooxml/property-grab-bag.ts` for the mechanism and Lane 3 O2
@@ -888,6 +903,80 @@ export interface CanonicalParagraphFormatting {
   unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
+/**
+ * Paragraph text-frame properties from `<w:framePr>` (ECMA-376 §17.3.1.11).
+ * Pure data — describes a positioned text frame that contains the
+ * paragraph. When `frameProperties` is set on a paragraph's formatting,
+ * L04 pagination and L11 render treat the paragraph as an out-of-flow
+ * frame positioned according to the fields below, not as an in-flow
+ * block.
+ *
+ * All fields optional; absence carries its OOXML default.
+ */
+export interface FrameProperties {
+  /** `w:w` — frame width in twips. Absence = auto-width from content. */
+  widthTwips?: number;
+  /** `w:h` — frame height in twips. Interpretation depends on `hRule`. */
+  heightTwips?: number;
+  /**
+   * `w:hRule` — height rule.
+   * - `"auto"` (default): height follows content.
+   * - `"atLeast"`: content grows the frame; `heightTwips` is the floor.
+   * - `"exact"`: content is clipped to `heightTwips`.
+   */
+  hRule?: "auto" | "atLeast" | "exact";
+  /** `w:x` — horizontal absolute position in twips from `hAnchor`. */
+  xTwips?: number;
+  /** `w:y` — vertical absolute position in twips from `vAnchor`. */
+  yTwips?: number;
+  /**
+   * `w:xAlign` — horizontal alignment keyword; overrides `xTwips` if
+   * both are set (Word behavior). `"inside"` / `"outside"` are
+   * mirror-aware for even/odd pages.
+   */
+  xAlign?: "left" | "center" | "right" | "inside" | "outside";
+  /**
+   * `w:yAlign` — vertical alignment keyword; overrides `yTwips` if
+   * both are set. `"inline"` places the frame in the text flow.
+   */
+  yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+  /** `w:hAnchor` — what `x` / `xAlign` is measured from. */
+  hAnchor?: "text" | "margin" | "page";
+  /** `w:vAnchor` — what `y` / `yAlign` is measured from. */
+  vAnchor?: "text" | "margin" | "page";
+  /**
+   * `w:wrap` — how surrounding text flows around the frame.
+   * `"around"`: text wraps on both sides; `"notBeside"`: text stops
+   * above/below the frame; `"none"`: no text on the frame line;
+   * `"auto"` / `"tight"` / `"through"`: extended wrap modes.
+   */
+  wrap?: "around" | "auto" | "none" | "notBeside" | "tight" | "through";
+  /** `w:hSpace` — horizontal clear-space around the frame, twips. */
+  hSpaceTwips?: number;
+  /** `w:vSpace` — vertical clear-space around the frame, twips. */
+  vSpaceTwips?: number;
+  /**
+   * `w:dropCap` — drop-cap semantics when the frame holds an initial
+   * letter. `"none"` (default): not a drop-cap frame.
+   * `"drop"`: character spans `lines` lines, text wraps around it.
+   * `"margin"`: character hangs in the margin.
+   */
+  dropCap?: "none" | "drop" | "margin";
+  /** `w:lines` — number of lines the drop-cap spans. Only meaningful when `dropCap !== "none"`. */
+  lines?: number;
+  /** `w:anchorLock` — prevents the frame's anchor paragraph from moving between pages during reflow. */
+  anchorLock?: boolean;
+  /**
+   * Verbatim source XML of the `<w:framePr>` element. Populated by
+   * the parser for lossless round-trip of extension attributes
+   * (`w14:*`, `w15:*`, `mc:Ignorable`, etc.) that the fields above do
+   * not model. When re-serializing, the writer should prefer the
+   * modeled fields and merge in any extension attributes from
+   * `rawXml` that aren't covered by the modeled set.
+   */
+  rawXml?: string;
+}
+
 /**
  * A single unmodelled direct child of an OOXML property container (pPr,
  * rPr, tcPr, trPr, tblPr, sectPr). Captured verbatim so the serializer
@@ -956,6 +1045,24 @@ export interface ParagraphNode {
   bidi?: boolean;
   suppressLineNumbers?: boolean;
   cnfStyle?: string;
+  /**
+   * `<w:framePr>` — inline paragraph text-frame properties set
+   * directly on the paragraph (not through the style cascade).
+   * Mirrors `CanonicalParagraphFormatting.frameProperties`; the two
+   * slots coexist because Word writes framePr at both levels: a
+   * style may declare the frame in `docDefaults` / named style
+   * (cascade path), or an individual paragraph may override with
+   * its own `<w:pPr><w:framePr>` (direct path). L03's cascade
+   * resolver prefers the direct-paragraph value when both are set,
+   * matching Word's cascade semantics.
+   *
+   * Added 2026-04-23 per `cross-layer-coord-02.md §11 P1` follow-up
+   * to the earlier FrameProperties landing (`86961dcb`). Without
+   * this slot, direct-paragraph `<w:framePr>` would still flatten
+   * to `OpaqueBlockNode` because the parser had no canonical target
+   * at the node level.
+   */
+  frameProperties?: FrameProperties;
   /**
    * Preserved w14 extension identifiers for this paragraph.
    * Round-trip (§2 A.7) requires these to survive import → export so the
@@ -1514,6 +1621,7 @@ export type InlineNode =
   | TextNode
   | HardBreakNode
   | ColumnBreakNode
+  | PageBreakNode
   | TabNode
   | SymbolNode
   | HyperlinkNode
@@ -1570,6 +1678,24 @@ export interface ColumnBreakNode {
   type: "column_break";
 }
 
+/**
+ * Explicit page break — `<w:br w:type="page"/>` in OOXML (ECMA-376 §17.3.3.1).
+ * Forces the next content to start on a new page. Emitted by L01's
+ * `parse-main-document.ts` when `<w:br w:type="page"/>` is encountered
+ * inside a paragraph run; consumed by L04's pagination engine which
+ * pushes a page boundary after placing any block whose segments carry
+ * a `page_break`. Added 2026-04-23 per `cross-layer-coord-04.md §1.18.5`
+ * + `cross-layer-coord-03.md §11` to close the explicit-page-break
+ * silently-dropped visual regression.
+ *
+ * Not to be confused with `SectionBreakNode` (`<w:sectPr><w:type
+ * w:val="page"/>`) which is a section-level boundary and carries
+ * section properties; `PageBreakNode` is inline inside a run.
+ */
+export interface PageBreakNode {
+  type: "page_break";
+}
+
 export interface TabNode {
   type: "tab";
 }
@@ -1584,7 +1710,7 @@ export interface SymbolNode {
 export interface HyperlinkNode {
   type: "hyperlink";
   href: string;
-  children: Array<TextNode | HardBreakNode | ColumnBreakNode | TabNode | SymbolNode>;
+  children: Array<TextNode | HardBreakNode | ColumnBreakNode | PageBreakNode | TabNode | SymbolNode>;
 }
 
 export interface ImageNode {
@@ -2284,6 +2410,12 @@ export function validateCanonicalDocument(
   if (record.subParts !== undefined) {
     validateSubPartsCatalog(record.subParts, "$.subParts", issues);
   }
+  if (record.fieldRegistry !== undefined) {
+    validateFieldRegistry(record.fieldRegistry, "$.fieldRegistry", issues);
+  }
+  if (record.fontTable !== undefined) {
+    validateCanonicalFontTable(record.fontTable, "$.fontTable", issues);
+  }
   validateDocumentReferences(record, issues);
 
   return issues;
@@ -2646,6 +2778,7 @@ function validateDocumentNode(
       return;
     case "hard_break":
     case "column_break":
+    case "page_break":
     case "tab":
       return;
     case "symbol":
@@ -3794,6 +3927,273 @@ function validateExactObjectKeys(
   }
 }
 
+const SUPPORTED_FIELD_FAMILIES: ReadonlySet<SupportedFieldFamily> = new Set([
+  "REF",
+  "PAGEREF",
+  "NOTEREF",
+  "TOC",
+  "PAGE",
+  "NUMPAGES",
+  "STYLEREF",
+  "SECTIONPAGES",
+]);
+
+const PRESERVE_ONLY_FIELD_FAMILIES: ReadonlySet<PreserveOnlyFieldFamily> = new Set([
+  "DATE",
+  "TIME",
+  "AUTHOR",
+  "FILENAME",
+  "MERGEFIELD",
+  "IF",
+  "SEQ",
+  "INDEX",
+  "TC",
+  "FORMULA",
+  "UNKNOWN",
+]);
+
+const FIELD_REFRESH_STATUSES: ReadonlySet<FieldRefreshStatus> = new Set([
+  "current",
+  "stale",
+  "unresolvable",
+  "preserve-only",
+]);
+
+const FONT_FAMILY_VALUES: ReadonlySet<string> = new Set([
+  "roman",
+  "swiss",
+  "modern",
+  "script",
+  "decorative",
+]);
+
+const FONT_PITCH_VALUES: ReadonlySet<string> = new Set([
+  "fixed",
+  "variable",
+  "default",
+]);
+
+function validateFieldRegistry(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (!Array.isArray(record.supported)) {
+    issues.push({ path: `${path}.supported`, message: "supported must be an array." });
+  } else {
+    record.supported.forEach((entry, index) => {
+      validateFieldRegistryEntry(entry, `${path}.supported[${index}]`, issues);
+    });
+  }
+
+  if (!Array.isArray(record.preserveOnly)) {
+    issues.push({ path: `${path}.preserveOnly`, message: "preserveOnly must be an array." });
+  } else {
+    record.preserveOnly.forEach((entry, index) => {
+      validateFieldRegistryEntry(entry, `${path}.preserveOnly[${index}]`, issues);
+    });
+  }
+
+  if (record.tocStructure !== undefined) {
+    validateTocStructure(record.tocStructure, `${path}.tocStructure`, issues);
+  }
+}
+
+function validateFieldRegistryEntry(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (!Number.isInteger(record.fieldIndex) || (record.fieldIndex as number) < 0) {
+    issues.push({
+      path: `${path}.fieldIndex`,
+      message: "fieldIndex must be a non-negative integer.",
+    });
+  }
+
+  if (
+    typeof record.fieldFamily !== "string" ||
+    !(
+      SUPPORTED_FIELD_FAMILIES.has(record.fieldFamily as SupportedFieldFamily) ||
+      PRESERVE_ONLY_FIELD_FAMILIES.has(record.fieldFamily as PreserveOnlyFieldFamily)
+    )
+  ) {
+    issues.push({
+      path: `${path}.fieldFamily`,
+      message: "fieldFamily must be a SupportedFieldFamily or PreserveOnlyFieldFamily.",
+    });
+  }
+
+  if (typeof record.supported !== "boolean") {
+    issues.push({ path: `${path}.supported`, message: "supported must be a boolean." });
+  }
+
+  expectString(record.instruction, `${path}.instruction`, issues);
+
+  if (record.fieldTarget !== undefined) {
+    expectString(record.fieldTarget, `${path}.fieldTarget`, issues);
+  }
+
+  if (typeof record.displayText !== "string") {
+    issues.push({ path: `${path}.displayText`, message: "displayText must be a string." });
+  }
+
+  if (!Number.isInteger(record.paragraphIndex) || (record.paragraphIndex as number) < 0) {
+    issues.push({
+      path: `${path}.paragraphIndex`,
+      message: "paragraphIndex must be a non-negative integer.",
+    });
+  }
+
+  if (
+    typeof record.refreshStatus !== "string" ||
+    !FIELD_REFRESH_STATUSES.has(record.refreshStatus as FieldRefreshStatus)
+  ) {
+    issues.push({
+      path: `${path}.refreshStatus`,
+      message:
+        "refreshStatus must be one of: current, stale, unresolvable, preserve-only.",
+    });
+  }
+}
+
+function validateTocStructure(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.instruction, `${path}.instruction`, issues);
+
+  const levelRange = asPlainObject(record.levelRange, `${path}.levelRange`, issues);
+  if (levelRange) {
+    if (!Number.isInteger(levelRange.from) || (levelRange.from as number) < 1) {
+      issues.push({
+        path: `${path}.levelRange.from`,
+        message: "levelRange.from must be an integer ≥ 1.",
+      });
+    }
+    if (!Number.isInteger(levelRange.to) || (levelRange.to as number) < 1) {
+      issues.push({
+        path: `${path}.levelRange.to`,
+        message: "levelRange.to must be an integer ≥ 1.",
+      });
+    }
+  }
+
+  if (!Array.isArray(record.entries)) {
+    issues.push({ path: `${path}.entries`, message: "entries must be an array." });
+  } else {
+    record.entries.forEach((entry, index) => {
+      const entryRecord = asPlainObject(entry, `${path}.entries[${index}]`, issues);
+      if (!entryRecord) return;
+      if (typeof entryRecord.text !== "string") {
+        issues.push({
+          path: `${path}.entries[${index}].text`,
+          message: "text must be a string.",
+        });
+      }
+      if (
+        !Number.isInteger(entryRecord.level) ||
+        (entryRecord.level as number) < 1 ||
+        (entryRecord.level as number) > 9
+      ) {
+        issues.push({
+          path: `${path}.entries[${index}].level`,
+          message: "level must be an integer in [1..9].",
+        });
+      }
+      if (!Number.isInteger(entryRecord.paragraphIndex)) {
+        issues.push({
+          path: `${path}.entries[${index}].paragraphIndex`,
+          message: "paragraphIndex must be an integer.",
+        });
+      }
+      if (entryRecord.styleId !== undefined) {
+        expectString(entryRecord.styleId, `${path}.entries[${index}].styleId`, issues);
+      }
+      if (entryRecord.bookmarkName !== undefined) {
+        expectString(
+          entryRecord.bookmarkName,
+          `${path}.entries[${index}].bookmarkName`,
+          issues,
+        );
+      }
+    });
+  }
+
+  if (record.status !== "current" && record.status !== "stale") {
+    issues.push({
+      path: `${path}.status`,
+      message: "status must be 'current' or 'stale'.",
+    });
+  }
+}
+
+function validateCanonicalFontTable(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const fonts = asPlainObject(record.fonts, `${path}.fonts`, issues);
+  if (!fonts) {
+    return;
+  }
+
+  for (const [fontKey, fontEntry] of Object.entries(fonts)) {
+    const fontPath = `${path}.fonts[${JSON.stringify(fontKey)}]`;
+    const entry = asPlainObject(fontEntry, fontPath, issues);
+    if (!entry) continue;
+
+    expectString(entry.name, `${fontPath}.name`, issues);
+
+    if (entry.family !== undefined) {
+      if (typeof entry.family !== "string" || !FONT_FAMILY_VALUES.has(entry.family)) {
+        issues.push({
+          path: `${fontPath}.family`,
+          message: "family must be one of: roman, swiss, modern, script, decorative.",
+        });
+      }
+    }
+
+    if (entry.pitch !== undefined) {
+      if (typeof entry.pitch !== "string" || !FONT_PITCH_VALUES.has(entry.pitch)) {
+        issues.push({
+          path: `${fontPath}.pitch`,
+          message: "pitch must be one of: fixed, variable, default.",
+        });
+      }
+    }
+
+    if (entry.charset !== undefined && !Number.isInteger(entry.charset)) {
+      issues.push({ path: `${fontPath}.charset`, message: "charset must be an integer." });
+    }
+
+    if (entry.altName !== undefined) {
+      expectString(entry.altName, `${fontPath}.altName`, issues);
+    }
+  }
+}
+
 function validateSubPartsCatalog(
   value: unknown,
   path: string,

package/src/runtime/formatting/formatting-context.ts

@@ -98,7 +98,8 @@ export type ProjectedSurfaceMark =
   | "imprint"
   | "shadow"
   | "smallCaps"
-  | "allCaps";
+  | "allCaps"
+  | "highlight";
 
 export interface ProjectedRunMarks {
   readonly marks?: ReadonlyArray<ProjectedSurfaceMark>;

package/src/runtime/geometry/overlay-rects.ts

@@ -11,16 +11,13 @@
  * overlay-layer.tsx`) re-exports this via a direct import so its public
  * API surface is unchanged.
  *
- * **Coordinate-space caveat (known divergence).** The kernel stacks
- * pages with `PAGE_GAP_PX = 16` (see `src/runtime/render/render-kernel.ts`)
- * while the DOM stacks them with `interGapPx = 48` (see
- * `src/ui-tailwind/editor-surface/pm-page-break-decorations.ts`). Using
- * `page.frame.topPx` directly as an overlay rect is correct only for
- * page 0; for pages 2..N the overlay rect drifts by ~32 px per boundary.
- * This helper is the clean substrate; a subsequent Slice-3c reconciles
- * the two gap constants before any production consumer wires the warm
- * path. Until then the overlay component keeps its DOM-measurement path
- * as the default and treats the geometry path as experimental.
+ * **Coordinate-space reconciliation — RESOLVED 2026-04-23
+ * (`LAYOUT_ENGINE_VERSION 51 → 52`, refactor/10 Slice L11-3).** Kernel
+ * `PAGE_GAP_PX` was bumped from 16 to 48 to match the DOM page-break
+ * widget's `interGapPx`. `page.frame.topPx` is now usable as an overlay
+ * rect for every page, not just page 0. The overlay component flipped
+ * to geometry-as-warm-path; the DOM-measurement branch remains as the
+ * cold-open fallback only.
  */
 
 import type { GeometryFacet } from "./geometry-facet.ts";