toFlowBlocks.ts

/**
 * ProseMirror to FlowBlock Converter
 *
 * Converts a ProseMirror document into FlowBlock[] for the layout engine.
 * Tracks pmStart/pmEnd positions for click-to-position mapping.
 */

import type { Node as PMNode, Mark } from "prosemirror-model";

import { convertBulletToUnicode } from "../../docx/bulletMarkers";
import { resolveDocumentGridLinePitch } from "../../docx/documentGrid";
import { padDecimal } from "../../docx/numberingParser";
import type {
  FlowBlock,
  ParagraphBlock,
  TableBlock,
  TableRow,
  TableCell,
  CellBorders,
  BorderStyle,
  ImageBlock,
  TextBoxBlock,
  PageBreakBlock,
  ColumnBreakBlock,
  SectionBreakBlock,
  Run,
  TextRun,
  TabRun,
  ImageRun,
  FieldRun,
  RunFormatting,
  ParagraphAttrs,
  SdtGroup,
  TabStop,
  FloatingTablePosition,
} from "../../layout-engine/types";
import { setTextBoxGroupId } from "../../layout-engine/textBoxGroup";
import { setParagraphFrame } from "../../layout-engine/paragraphFrame";
import { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH } from "../../layout-engine/types";
import { getColumns } from "../sectionColumns";
import {
  expectBlockSdtAttrs,
  expectCharacterSpacingMarkAttrs,
  expectCommentMarkAttrs,
  expectEmphasisMarkAttrs,
  expectFieldAttrs,
  expectFontFamilyMarkAttrs,
  expectLanguageMarkAttrs,
  expectFontSizeMarkAttrs,
  expectFootnoteRefMarkAttrs,
  expectHardBreakAttrs,
  expectHighlightMarkAttrs,
  expectHyperlinkMarkAttrs,
  expectImageAttrs,
  expectMathAttrs,
  expectParagraphAttrs,
  expectRunFormattingOverrideMarkAttrs,
  expectRunShadingMarkAttrs,
  expectTableAttrs,
  expectTableCellAttrs,
  expectTableRowAttrs,
  expectTextBoxAttrs,
  expectTextColorMarkAttrs,
  expectTextEffectMarkAttrs,
  expectTrackedChangeMarkAttrs,
  expectUnderlineMarkAttrs,
} from "../../prosemirror/attrs";
import { autospacingMatchesBase } from "../../prosemirror/autospacingBase";
import { runShadingAttrsToShading } from "../../prosemirror/conversion/runShadingMark";
import { directionIsRtl } from "../../prosemirror/paragraphDirection";
import type { RunFormattingOverrideAttrs } from "../../prosemirror/schema/marks";
import type {
  ImageAttrs,
  ParagraphAttrs as PMParagraphAttrs,
} from "../../prosemirror/schema/nodes";
import { assertValidProseMirrorDocument } from "../../prosemirror/validation";
import type {
  ColorValue,
  Theme,
  SectionProperties,
  NumberFormat,
  TextFormatting,
} from "../../types/document";
import { NUMBER_FORMAT_VALUES } from "../../types/documentEnumValues";
import { resolveColor, resolveHighlightToCss } from "../../utils/colorResolver";
import { resolveThemeFont } from "../../utils/fontResolver";
import { resolveShadingFill } from "../../utils/formatToStyle";
import {
  AUTO_PARAGRAPH_SPACING_PX,
  pointsToPixels,
  halfPointsToPixels,
  halfPointsToPoints,
} from "../../utils/units";
import { groupParagraphFrames } from "./paragraphFrames";

/**
 * Options for the conversion.
 */
export type ToFlowBlocksOptions = {
  /** Default font family. */
  defaultFont?: string;
  /** Default font size in points. */
  defaultSize?: number;
  /** Theme for resolving theme colors. */
  theme?: Theme | null;
  /** Page content height in pixels (pageHeight - marginTop - marginBottom). Images taller than this are scaled down to fit. */
  pageContentHeight?: number;
  /** Shared list counters for nested containers. */
  listCounters?: Map<number, number[]>;
  /** Latest concrete counters by abstract numbering definition. */
  listAbstractCounters?: Map<number, number[]>;
  /** Shared startOverride state for nested containers. */
  listSeenNumIds?: Set<string>;
  /**
   * Parallel counter state for the "original" (pre-revision) document, used to
   * number tracked-deletion list items. Word numbers inserted and deleted list
   * runs as if they never coexist: insertions get final-document numbering,
   * deletions keep their original numbering. Without a separate stream a deleted
   * item continues the counter of the inserted item before it (a, b → c, d, e
   * instead of a, b and a, b, c). Normal items advance both streams.
   */
  originalListCounters?: Map<number, number[]>;
  /** Latest concrete original-stream counters by abstract numbering definition. */
  originalListAbstractCounters?: Map<number, number[]>;
  /** Original-stream startOverride state. */
  originalListSeenNumIds?: Set<string>;
  /**
   * Document-wide `w:defaultTabStop` (§17.6.13) in twips. Stamped onto
   * every paragraph block so paragraph-local layout helpers (list marker
   * tab-stop math) can read it without taking a `Document` reference.
   * Defaults to the OOXML 720-twip value when absent.
   */
  defaultTabStopTwips?: number;
  /** Document-wide custom Word line-breaking settings. */
  lineBreakRules?: {
    noLineBreaksBefore?: { language?: string; characters: string };
    noLineBreaksAfter?: { language?: string; characters: string };
    useLegacyEthiopicAmharicRules?: boolean;
  };
  /** Document-generation policy for justified line fitting. */
  justificationCompatibility?: NonNullable<ParagraphAttrs["justificationCompatibility"]>;
  /** Document-wide automatic hyphenation policy. */
  automaticHyphenation?: NonNullable<ParagraphAttrs["automaticHyphenation"]>;
  /** Line pitch for the final body section, whose properties live outside the PM body. */
  finalSectionDocumentGridLinePitchTwips?: number;
};

const DEFAULT_FONT = "Calibri";
const DEFAULT_TABLE_CELL_MARGIN_TWIPS = {
  top: 0,
  right: 108,
  bottom: 0,
  left: 108,
} as const;
type TablePaddingSide = keyof typeof DEFAULT_TABLE_CELL_MARGIN_TWIPS;
const DEFAULT_BLACK_TEXT_COLOR_VALUES = new Set(["000000", "000"]);

function normalizeResolvedTextColor(color: string): string {
  return color.trim().toLowerCase().replace(/^#/u, "");
}

function isDefaultBlackResolvedTextColor(color: string): boolean {
  return DEFAULT_BLACK_TEXT_COLOR_VALUES.has(normalizeResolvedTextColor(color));
}

function areResolvedTextColorsEqual(left: string, right: string): boolean {
  return normalizeResolvedTextColor(left) === normalizeResolvedTextColor(right);
}

/**
 * Constrain image dimensions to fit within the page content area.
 * Scales proportionally if height exceeds pageContentHeight.
 */
function constrainImageToPage(
  width: number,
  height: number,
  pageContentHeight: number | undefined,
): { width: number; height: number } {
  if (!pageContentHeight || height <= pageContentHeight) {
    return { width, height };
  }
  const scale = pageContentHeight / height;
  return { width: Math.round(width * scale), height: pageContentHeight };
}

const DEFAULT_SIZE = 11; // points (Word 2007+ default)

/**
 * Convert twips to pixels (1 twip = 1/1440 inch, 1 inch = 96 CSS px).
 * No rounding — precision prevents cumulative layout drift across paragraphs.
 */
function twipsToPixels(twips: number): number {
  return (twips / 1440) * 96;
}

/**
 * Generate a unique block ID.
 */
let blockIdCounter = 0;
function nextBlockId(): string {
  return `block-${++blockIdCounter}`;
}

function formatNumberedMarker(counters: number[], level: number): string {
  const parts: number[] = [];
  for (let i = 0; i <= level; i += 1) {
    const value = counters[i] ?? 0;
    if (value <= 0) {
      break;
    }
    parts.push(value);
  }
  if (parts.length === 0) {
    return "1.";
  }
  return `${parts.join(".")}.`;
}

const ROMAN_PAIRS: [number, string][] = [
  [1000, "M"],
  [900, "CM"],
  [500, "D"],
  [400, "CD"],
  [100, "C"],
  [90, "XC"],
  [50, "L"],
  [40, "XL"],
  [10, "X"],
  [9, "IX"],
  [5, "V"],
  [4, "IV"],
  [1, "I"],
];

function toRoman(value: number, upper: boolean): string {
  if (value <= 0) {
    return "";
  }
  let remaining = value;
  let output = "";
  for (const [number, symbol] of ROMAN_PAIRS) {
    while (remaining >= number) {
      output += symbol;
      remaining -= number;
    }
  }
  return upper ? output : output.toLowerCase();
}

function toLetter(value: number, upper: boolean): string {
  if (value <= 0) {
    return "";
  }
  const zeroBased = value - 1;
  const baseCodePoint = upper ? 65 : 97;
  const letter = String.fromCodePoint(baseCodePoint + (zeroBased % 26));
  return letter.repeat(Math.floor(zeroBased / 26) + 1);
}

export function formatCounter(value: number, format: NumberFormat | undefined): string {
  if (!Number.isFinite(value)) {
    return "";
  }
  // NumberFormat is the OOXML w:numFmt enum (70+ values). This switch
  // handles every format whose counter-rendering differs from a simple
  // decimal; CJK/Hindi/Arabic counters fall through to the decimal
  // default. Matches Word's display when those font glyphs are absent.
  switch (format) {
    case "upperRoman":
      return toRoman(value, true);
    case "lowerRoman":
      return toRoman(value, false);
    case "upperLetter":
      return toLetter(value, true);
    case "lowerLetter":
      return toLetter(value, false);
    case "decimalZero":
      return padDecimal(value, 2);
    case "decimalZero3":
      return padDecimal(value, 3);
    case "decimalZero4":
      return padDecimal(value, 4);
    case "decimalZero5":
      return padDecimal(value, 5);
    case "none":
      return "";
    default:
      return String(value);
  }
}

export function resolveListTemplate(
  template: string,
  counters: number[],
  levelFormats: NumberFormat[] | undefined,
  forceDecimal = false,
): string {
  return template.replace(/%(?<digit>\d)(?<punct>[.):\]])?/gu, (...args) => {
    const { digit, punct = "" } = args.at(-1) as {
      digit: string;
      punct?: string;
    };
    const index = Number.parseInt(digit, 10) - 1;
    if (index < 0) {
      return "";
    }
    const counter = counters[index];
    if (counter === undefined || Number.isNaN(counter)) {
      return "";
    }
    const formatted = formatCounter(counter, forceDecimal ? "decimal" : levelFormats?.[index]);
    return formatted ? `${formatted}${punct}` : "";
  });
}

function getLastListCounters(listCounters: Map<number, number[]>): number[] | undefined {
  let lastCounters: number[] | undefined;
  for (const counters of listCounters.values()) {
    lastCounters = counters;
  }
  return lastCounters;
}

function applyMarkerAllCaps(marker: string | null, allCaps: boolean | undefined): string | null {
  if (marker === null || !allCaps) {
    return marker;
  }
  return marker.toLocaleUpperCase();
}

function computeListMarker(
  pmAttrs: PMParagraphAttrs,
  listCounters: Map<number, number[]>,
  abstractCounters: Map<number, number[]>,
  seenNumIds: Set<string>,
): string | null {
  const numId = pmAttrs.numPr?.numId;
  if (numId === undefined || numId === 0) {
    if (pmAttrs.listMarker?.includes("%") && !pmAttrs.listIsBullet) {
      const counters = getLastListCounters(listCounters);
      if (counters) {
        return resolveListTemplate(
          pmAttrs.listMarker,
          counters,
          pmAttrs.listLevelNumFmts,
          pmAttrs.listIsLegal,
        );
      }
    }
    return null;
  }

  if (pmAttrs.listIsBullet) {
    return convertBulletToUnicode(pmAttrs.listMarker || "");
  }

  const level = pmAttrs.numPr?.ilvl ?? 0;
  const counters =
    listCounters.get(numId) ?? (Array.from({ length: 9 }, () => Number.NaN) as number[]);
  const abstractNumId = pmAttrs.listAbstractNumId;
  if (level > 0) {
    const latestAbstractCounters =
      abstractNumId === undefined ? undefined : abstractCounters.get(abstractNumId);
    if (counters.slice(0, level).every(Number.isNaN)) {
      for (let i = 0; i < level; i += 1) {
        const latestCounter = latestAbstractCounters?.[i];
        counters[i] =
          latestCounter !== undefined && !Number.isNaN(latestCounter)
            ? latestCounter
            : (pmAttrs.listLevelStarts?.[i] ?? 1);
      }
    }
  }

  const seenKey = `${numId}:${level}`;
  if (!seenNumIds.has(seenKey)) {
    seenNumIds.add(seenKey);
    if (pmAttrs.listStartOverride != null) {
      counters[level] = pmAttrs.listStartOverride - 1;
    } else if (Number.isNaN(counters[level])) {
      counters[level] = (pmAttrs.listLevelStarts?.[level] ?? 1) - 1;
    }
  }

  counters[level] = (counters[level] ?? 0) + 1;
  for (let i = level + 1; i < counters.length; i += 1) {
    counters[i] = Number.NaN;
  }
  // Word's default LISTNUM field advances the counter at one ilvl deeper
  // than the host paragraph. Carrying the consumed advances forward here
  // means a later sibling at that depth (e.g. an OutNum3 "(b)" following an
  // OutNum2 "(a)") picks up the next letter instead of restarting at "(a)".
  const childAdvances = pmAttrs.listImplicitChildLevelAdvances ?? 0;
  if (childAdvances > 0 && level + 1 < counters.length) {
    const childCounter = counters[level + 1];
    counters[level + 1] =
      (childCounter === undefined || Number.isNaN(childCounter) ? 0 : childCounter) + childAdvances;
  }
  listCounters.set(numId, counters);
  if (abstractNumId !== undefined) {
    abstractCounters.set(abstractNumId, [...counters]);
  }

  const levelFormats =
    pmAttrs.listLevelNumFmts ?? (pmAttrs.listNumFmt ? [pmAttrs.listNumFmt] : undefined);
  if (pmAttrs.listMarker && pmAttrs.listMarker.includes("%")) {
    return resolveListTemplate(pmAttrs.listMarker, counters, levelFormats, pmAttrs.listIsLegal);
  }
  if (pmAttrs.listMarker) {
    return pmAttrs.listMarker;
  }
  // OOXML allows a list level to set lvlText="" with numFmt="none" to attach
  // numbering metadata (counters, indents) without painting a marker — Word
  // glossary/definition styles use this. An empty listMarker means the level
  // explicitly opts out; synthesising a decimal counter here would forge a
  // marker the source never authored.
  const levelFormat = levelFormats?.[level] ?? pmAttrs.listNumFmt;
  if (levelFormat === "none" || pmAttrs.listMarker === "") {
    return null;
  }
  return formatNumberedMarker(counters, level);
}

/**
 * Reset the block ID counter (useful for testing).
 */
export function resetBlockIdCounter(): void {
  blockIdCounter = 0;
}

/**
 * Extract run formatting from ProseMirror marks.
 */
function extractRunFormatting(marks: readonly Mark[], theme?: Theme | null): RunFormatting {
  const formatting: RunFormatting = {};
  let hasNoteRef = false;

  for (const mark of marks) {
    switch (mark.type.name) {
      case "bold":
        formatting.bold = true;
        break;

      case "italic":
        formatting.italic = true;
        break;

      case "underline": {
        const attrs = expectUnderlineMarkAttrs(mark);
        if (attrs.style || attrs.color) {
          const underlineObj: { style?: string; color?: string } = {};
          if (attrs.style) {
            underlineObj.style = attrs.style;
          }
          if (attrs.color) {
            underlineObj.color = resolveColor(attrs.color, theme);
          }
          formatting.underline = underlineObj;
        } else {
          formatting.underline = true;
        }
        break;
      }

      case "strike":
        formatting.strike = true;
        break;

      case "textColor": {
        const attrs = expectTextColorMarkAttrs(mark);
        if (attrs.themeColor || attrs.rgb) {
          const colorArg: ColorValue = {};
          if (attrs.rgb) {
            colorArg.rgb = attrs.rgb;
          }
          if (attrs.themeColor) {
            colorArg.themeColor = attrs.themeColor;
          }
          if (attrs.themeTint) {
            colorArg.themeTint = attrs.themeTint;
          }
          if (attrs.themeShade) {
            colorArg.themeShade = attrs.themeShade;
          }
          if (!isAutomaticTextColorValue(colorArg)) {
            formatting.color = resolveColor(colorArg, theme);
            formatting.textColorSource = "direct";
          }
        }
        break;
      }

      case "highlight":
        formatting.highlight = resolveHighlightToCss(expectHighlightMarkAttrs(mark).color);
        break;

      case "runShading": {
        const shadingCss = resolveShadingFill(
          runShadingAttrsToShading(expectRunShadingMarkAttrs(mark)),
          theme,
        );
        if (shadingCss) {
          formatting.shading = shadingCss;
        }
        break;
      }

      case "fontSize": {
        const attrs = expectFontSizeMarkAttrs(mark);
        // Convert half-points to points
        formatting.fontSize = attrs.size / 2;
        break;
      }

      case "fontFamily": {
        const attrs = expectFontFamilyMarkAttrs(mark);
        const font = resolveWesternThemeFont(attrs, theme);
        if (font) {
          formatting.fontFamily = font;
        }
        const eastAsiaFont = resolveEastAsiaThemeFont(attrs, theme);
        if (eastAsiaFont) {
          formatting.eastAsiaFontFamily = eastAsiaFont;
        }
        break;
      }

      case "language": {
        const attrs = expectLanguageMarkAttrs(mark);
        formatting.language = {
          ...(attrs.val ? { val: attrs.val } : {}),
          ...(attrs.eastAsia ? { eastAsia: attrs.eastAsia } : {}),
          ...(attrs.bidi ? { bidi: attrs.bidi } : {}),
        };
        break;
      }

      case "characterSpacing": {
        const attrs = expectCharacterSpacingMarkAttrs(mark);
        if (attrs.spacing !== undefined) {
          formatting.letterSpacing = twipsToPixels(attrs.spacing);
        }
        if (attrs.position !== undefined && attrs.position !== 0) {
          formatting.positionPx = halfPointsToPixels(attrs.position);
        }
        if (attrs.scale !== undefined && attrs.scale !== 100) {
          formatting.horizontalScale = attrs.scale;
        }
        if (attrs.kerning !== undefined && attrs.kerning > 0) {
          formatting.kerningMinPt = halfPointsToPoints(attrs.kerning);
        }
        break;
      }

      case "allCaps":
        formatting.allCaps = true;
        break;

      case "smallCaps":
        formatting.smallCaps = true;
        break;

      case "emboss":
        formatting.emboss = true;
        break;

      case "imprint":
        formatting.imprint = true;
        break;

      case "hidden":
        // eigenpal #424 (w:vanish gap 9): mark surfaces RunFormatting.hidden
        // so the painter can apply the dimmed dotted-underline treatment.
        formatting.hidden = true;
        break;

      case "textShadow":
        formatting.textShadow = true;
        break;

      case "textOutline":
        formatting.textOutline = true;
        break;

      case "rtl":
        formatting.rtl = true;
        break;

      case "textEffect":
        // The textEffect mark schema rejects "none"; only animated variants
        // ever reach this branch.
        formatting.textEffect = expectTextEffectMarkAttrs(mark).effect;
        break;

      case "runFormattingOverride":
        applyRunFormattingOverrides(formatting, expectRunFormattingOverrideMarkAttrs(mark));
        break;

      case "emphasisMark": {
        formatting.emphasisMark = expectEmphasisMarkAttrs(mark).type ?? "dot";
        break;
      }

      case "superscript":
        formatting.superscript = true;
        break;

      case "subscript":
        formatting.subscript = true;
        break;

      case "hyperlink": {
        const attrs = expectHyperlinkMarkAttrs(mark);
        const link: RunFormatting["hyperlink"] & object = {
          href: attrs.href,
        };
        if (attrs.tooltip !== undefined) {
          link.tooltip = attrs.tooltip;
        }
        formatting.hyperlink = link;
        break;
      }

      case "footnoteRef": {
        hasNoteRef = true;
        const attrs = expectFootnoteRefMarkAttrs(mark);
        if (attrs.vertAlign === "superscript") {
          formatting.superscript = true;
        }
        const id = typeof attrs.id === "string" ? Number.parseInt(attrs.id, 10) : attrs.id;
        if (attrs.noteType === "endnote") {
          formatting.endnoteRefId = id;
        } else {
          formatting.footnoteRefId = id;
        }
        break;
      }

      case "comment": {
        const commentId = expectCommentMarkAttrs(mark).commentId;
        if (commentId) {
          if (!formatting.commentIds) {
            formatting.commentIds = [];
          }
          formatting.commentIds.push(commentId);
        }
        break;
      }

      case "insertion": {
        const attrs = expectTrackedChangeMarkAttrs(mark);
        formatting.isInsertion = true;
        formatting.changeAuthor = attrs.author;
        if (attrs.date !== undefined) {
          formatting.changeDate = attrs.date;
        }
        formatting.changeRevisionId = attrs.revisionId;
        if (attrs.provenance === "suggested") {
          formatting.isSuggestion = true;
          if (attrs.suggestionId) {
            formatting.suggestionId = attrs.suggestionId;
          }
        }
        break;
      }

      case "deletion": {
        const attrs = expectTrackedChangeMarkAttrs(mark);
        formatting.isDeletion = true;
        formatting.changeAuthor = attrs.author;
        if (attrs.date !== undefined) {
          formatting.changeDate = attrs.date;
        }
        formatting.changeRevisionId = attrs.revisionId;
        if (attrs.provenance === "suggested") {
          formatting.isSuggestion = true;
          if (attrs.suggestionId) {
            formatting.suggestionId = attrs.suggestionId;
          }
        }
        break;
      }
      default:
        break;
    }
  }

  if (hasNoteRef && formatting.subscript) {
    delete formatting.superscript;
  }

  return formatting;
}

type ThemeFontAttributes = {
  ascii?: string | null;
  hAnsi?: string | null;
  eastAsia?: string | null;
  asciiTheme?: string | null;
  hAnsiTheme?: string | null;
  eastAsiaTheme?: string | null;
};

const resolveWesternThemeFont = (
  fontFamily: ThemeFontAttributes,
  theme?: Theme | null,
): string | undefined => {
  const themeRef = fontFamily.asciiTheme ?? fontFamily.hAnsiTheme;
  const themedFont = themeRef ? resolveThemeFont(themeRef, theme?.fontScheme) : null;
  return themedFont ?? fontFamily.ascii ?? fontFamily.hAnsi ?? undefined;
};

const resolveEastAsiaThemeFont = (
  fontFamily: ThemeFontAttributes,
  theme?: Theme | null,
): string | undefined => {
  const themedFont = fontFamily.eastAsiaTheme
    ? resolveThemeFont(fontFamily.eastAsiaTheme, theme?.fontScheme)
    : null;
  return themedFont ?? fontFamily.eastAsia ?? undefined;
};

function isAutomaticTextColorValue(color: ColorValue): boolean {
  const rgb = color.rgb?.trim().toLowerCase();
  return color.auto === true || rgb === "auto" || (!rgb && !color.themeColor);
}

function markDefaultBlackTextColorSource(
  formatting: RunFormatting,
  paraDefaults: RunFormatting,
): RunFormatting {
  if (
    formatting.textColorSource === "direct" ||
    formatting.color === undefined ||
    paraDefaults.color === undefined ||
    !isDefaultBlackResolvedTextColor(formatting.color) ||
    !areResolvedTextColorsEqual(formatting.color, paraDefaults.color)
  ) {
    return formatting;
  }

  return {
    ...formatting,
    textColorSource: "paragraphDefault",
  };
}

function mergeRunFormatting(paraDefaults: RunFormatting, formatting: RunFormatting): RunFormatting {
  const merged = {
    ...paraDefaults,
    ...markDefaultBlackTextColorSource(formatting, paraDefaults),
  };
  if (merged.letterSpacing === 0) {
    delete merged.letterSpacing;
  }
  return merged;
}

function applyRunFormattingOverrides(
  formatting: RunFormatting,
  attrs: RunFormattingOverrideAttrs,
): void {
  if (attrs.bold === false) {
    formatting.bold = false;
  }
  if (attrs.italic === false) {
    formatting.italic = false;
  }
  if (attrs.underline === "none") {
    formatting.underline = false;
  }
  if (attrs.strike === false) {
    formatting.strike = false;
  }
  if (attrs.allCaps === false) {
    formatting.allCaps = false;
  }
  if (attrs.smallCaps === false) {
    formatting.smallCaps = false;
  }
  if (attrs.emboss === false) {
    formatting.emboss = false;
  }
  if (attrs.imprint === false) {
    formatting.imprint = false;
  }
  if (attrs.shadow === false) {
    formatting.textShadow = false;
  }
  if (attrs.outline === false) {
    formatting.textOutline = false;
  }
  if (attrs.rtl === false) {
    formatting.rtl = false;
  }
}

function paragraphRunDefaults(pmAttrs: PMParagraphAttrs, theme?: Theme | null): RunFormatting {
  const defaultTextFormatting = pmAttrs.defaultTextFormatting as TextFormatting | undefined;
  if (!defaultTextFormatting) {
    return {};
  }

  const result: RunFormatting = {};
  const fontFamily = defaultTextFormatting.fontFamily
    ? resolveWesternThemeFont(defaultTextFormatting.fontFamily, theme)
    : undefined;
  if (fontFamily) {
    result.fontFamily = fontFamily;
  }
  // East-Asian font inherited from the paragraph style / docDefaults, so CJK
  // runs without a direct `w:eastAsia` still get per-character EA selection. A
  // run's own fontFamily mark overrides this via mergeRunFormatting.
  const eastAsiaFontFamily = defaultTextFormatting.fontFamily
    ? resolveEastAsiaThemeFont(defaultTextFormatting.fontFamily, theme)
    : undefined;
  if (eastAsiaFontFamily) {
    result.eastAsiaFontFamily = eastAsiaFontFamily;
  }
  if (defaultTextFormatting.language) {
    result.language = { ...defaultTextFormatting.language };
  }
  if (defaultTextFormatting.fontSize !== undefined) {
    result.fontSize = defaultTextFormatting.fontSize / 2;
  }
  if (defaultTextFormatting.bold !== undefined) {
    result.bold = defaultTextFormatting.bold;
  }
  if (defaultTextFormatting.italic !== undefined) {
    result.italic = defaultTextFormatting.italic;
  }
  if (defaultTextFormatting.underline && defaultTextFormatting.underline.style !== "none") {
    result.underline = { style: defaultTextFormatting.underline.style };
    if (defaultTextFormatting.underline.color) {
      result.underline.color = resolveColor(defaultTextFormatting.underline.color, theme);
    }
  }
  if (defaultTextFormatting.strike !== undefined) {
    result.strike = defaultTextFormatting.strike;
  }
  if (defaultTextFormatting.color && !isAutomaticTextColorValue(defaultTextFormatting.color)) {
    result.color = resolveColor(defaultTextFormatting.color, theme);
    result.textColorSource = "paragraphDefault";
  }
  if (defaultTextFormatting.highlight) {
    const highlight = resolveHighlightToCss(defaultTextFormatting.highlight);
    if (highlight) {
      result.highlight = highlight;
    }
  }
  if (defaultTextFormatting.vertAlign === "superscript") {
    result.superscript = true;
  }
  if (defaultTextFormatting.vertAlign === "subscript") {
    result.subscript = true;
  }
  if (defaultTextFormatting.allCaps !== undefined) {
    result.allCaps = defaultTextFormatting.allCaps;
  }
  if (defaultTextFormatting.smallCaps !== undefined) {
    result.smallCaps = defaultTextFormatting.smallCaps;
  }
  if (defaultTextFormatting.spacing !== undefined && defaultTextFormatting.spacing !== 0) {
    result.letterSpacing = twipsToPixels(defaultTextFormatting.spacing);
  }
  if (defaultTextFormatting.position !== undefined && defaultTextFormatting.position !== 0) {
    result.positionPx = halfPointsToPixels(defaultTextFormatting.position);
  }
  if (defaultTextFormatting.scale !== undefined && defaultTextFormatting.scale !== 100) {
    result.horizontalScale = defaultTextFormatting.scale;
  }
  if (defaultTextFormatting.kerning !== undefined && defaultTextFormatting.kerning > 0) {
    result.kerningMinPt = halfPointsToPoints(defaultTextFormatting.kerning);
  }
  if (defaultTextFormatting.emboss !== undefined) {
    result.emboss = defaultTextFormatting.emboss;
  }
  if (defaultTextFormatting.imprint !== undefined) {
    result.imprint = defaultTextFormatting.imprint;
  }
  if (defaultTextFormatting.shadow !== undefined) {
    result.textShadow = defaultTextFormatting.shadow;
  }
  if (defaultTextFormatting.outline !== undefined) {
    result.textOutline = defaultTextFormatting.outline;
  }
  if (defaultTextFormatting.emphasisMark && defaultTextFormatting.emphasisMark !== "none") {
    result.emphasisMark = defaultTextFormatting.emphasisMark;
  }
  return result;
}

/**
 * Build an ImageRun from ProseMirror node attrs, applying conditional property assignment
 * to satisfy exactOptionalPropertyTypes.
 */
function buildImageRun(
  attrs: ImageAttrs,
  constrained: { width: number; height: number },
  pmStart: number,
  pmEnd: number,
  // Tracked-change attrs lifted off the image node's PM marks. eigenpal #641.
  trackedChange?: Pick<
    RunFormatting,
    "isInsertion" | "isDeletion" | "changeAuthor" | "changeDate" | "changeRevisionId"
  >,
): ImageRun {
  const run: ImageRun = {
    kind: "image",
    src: attrs.src,
    width: constrained.width,
    height: constrained.height,
    pmStart,
    pmEnd,
  };
  if (attrs.alt !== undefined) {
    run.alt = attrs.alt;
  }
  if (attrs.transform !== undefined) {
    run.transform = attrs.transform;
  }
  // eigenpal #424 (opacity render pipeline): copy opacity verbatim. PM
  // schema defaults `opacity` to `null`, which survives the typed cast on
  // ImageAttrs (`number | undefined`). Gate with `!= null` so the model
  // never carries the schema sentinel.
  if (attrs.opacity != null) {
    run.opacity = attrs.opacity;
  }
  if (attrs.wrapType !== undefined) {
    run.wrapType = attrs.wrapType;
  }
  if (attrs.displayMode !== undefined) {
    run.displayMode = attrs.displayMode;
  }
  if (attrs.cssFloat !== undefined) {
    run.cssFloat = attrs.cssFloat;
  }
  if (attrs.distTop !== undefined) {
    run.distTop = attrs.distTop;
  }
  if (attrs.distBottom !== undefined) {
    run.distBottom = attrs.distBottom;
  }
  if (attrs.distLeft !== undefined) {
    run.distLeft = attrs.distLeft;
  }
  if (attrs.distRight !== undefined) {
    run.distRight = attrs.distRight;
  }
  if (attrs._docxObjectPreview === true) {
    run.exactLineHeight = true;
  }
  // eigenpal #424: pass crop fractions through to the painter so it can
  // emit CSS clip-path. PM defaults are `null`; treat null as "not set".
  if (attrs.cropTop != null) {
    run.cropTop = attrs.cropTop;
  }
  if (attrs.cropRight != null) {
    run.cropRight = attrs.cropRight;
  }
  if (attrs.cropBottom != null) {
    run.cropBottom = attrs.cropBottom;
  }
  if (attrs.cropLeft != null) {
    run.cropLeft = attrs.cropLeft;
  }
  // eigenpal #1096: image borders are authored on the PM image attrs and
  // painted by layout-painter. PM defaults are null; treat null as absent.
  if (attrs.borderWidth != null) {
    run.borderWidth = attrs.borderWidth;
  }
  if (attrs.borderColor) {
    run.borderColor = attrs.borderColor;
  }
  if (attrs.borderStyle) {
    run.borderStyle = attrs.borderStyle;
  }
  if (attrs.position !== undefined) {
    run.position = attrs.position;
  }
  if (attrs.layoutInCell !== undefined) {
    run.layoutInCell = attrs.layoutInCell;
  }
  if (trackedChange?.isInsertion) {
    run.isInsertion = true;
  }
  if (trackedChange?.isDeletion) {
    run.isDeletion = true;
  }
  if (trackedChange?.changeAuthor !== undefined) {
    run.changeAuthor = trackedChange.changeAuthor;
  }
  if (trackedChange?.changeDate !== undefined) {
    run.changeDate = trackedChange.changeDate;
  }
  if (trackedChange?.changeRevisionId !== undefined) {
    run.changeRevisionId = trackedChange.changeRevisionId;
  }
  return run;
}

/**
 * Paragraph styleId pattern used by Word for TOC entries (TOC, TOC1, TOC2, …).
 * Hyperlinks inside these paragraphs must render in the paragraph's own colour,
 * not the Hyperlink character style — see {@link stripTocHyperlinkStyle}.
 */
const TOC_STYLE_ID = /^TOC\d*$/iu;

/**
 * In TOC paragraphs, strip the resolved Hyperlink character-style colour and
 * underline so the painter's link fallback doesn't fire. The PM doc keeps the
 * original marks so copy/paste out of a TOC still carries the Hyperlink
 * styling like Word does. Applies to both text and field runs — a TOC entry's
 * page number is a PAGEREF field inside the entry's hyperlink.
 *
 * Mutates `formatting` in place; cheaper than re-cloning per run.
 */
function stripTocHyperlinkStyle(formatting: RunFormatting): void {
  if (!formatting.hyperlink) {
    return;
  }
  formatting.hyperlink = { ...formatting.hyperlink, noDefaultStyle: true };
  delete formatting.color;
  delete formatting.underline;
}

/**
 * Convert a paragraph node to runs.
 */
function paragraphToRuns(node: PMNode, startPos: number, _options: ToFlowBlocksOptions): Run[] {
  const runs: Run[] = [];
  const offset = startPos + 1; // +1 for opening tag
  const theme = _options.theme;
  const pmAttrs = expectParagraphAttrs(node);
  const paraDefaults = paragraphRunDefaults(pmAttrs, theme);
  const paragraphStyleId = pmAttrs.styleId;
  const inTocParagraph =
    typeof paragraphStyleId === "string" && TOC_STYLE_ID.test(paragraphStyleId);
  let leadingRenderedPageBreakPending = pmAttrs.renderedPageBreakBefore === true;

  // Single dispatcher for one inline PM child. Recurses on `sdt` so nested
  // content controls keep contributing runs at the right pmStart/pmEnd.
  // Used for both the top-level paragraph iteration and the descent into
  // SDT children — the previous SDT branch only handled text/hardBreak/
  // tab/image and silently dropped fields, math, and nested SDTs even
  // when the parser preserved them (see eigenpal #482).
  function pushRunsForChild(child: PMNode, childPos: number): void {
    if (child.type.name === "renderedPageBreak") {
      if (leadingRenderedPageBreakPending) {
        leadingRenderedPageBreakPending = false;
        return;
      }
      runs.push({
        kind: "renderedPageBreak",
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
      });
      return;
    }
    if (child.type.name !== "sdt") {
      leadingRenderedPageBreakPending = false;
    }
    if (child.isText && child.text) {
      const formatting = extractRunFormatting(child.marks, theme);
      if (inTocParagraph) {
        stripTocHyperlinkStyle(formatting);
      }
      const run: TextRun = {
        kind: "text",
        text: child.text,
        ...mergeRunFormatting(paraDefaults, formatting),
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
      };
      runs.push(run);
      return;
    }
    if (child.type.name === "hardBreak") {
      runs.push({
        kind: "lineBreak",
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
      });
      return;
    }
    if (child.type.name === "tab") {
      const formatting = extractRunFormatting(child.marks, theme);
      const run: TabRun = {
        kind: "tab",
        ...mergeRunFormatting(paraDefaults, formatting),
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
      };
      runs.push(run);
      return;
    }
    if (child.type.name === "image") {
      const attrs = expectImageAttrs(child);
      if (!attrs.src) {
        // Unsupported DrawingML shapes can survive the parser as image nodes
        // without a relationship target. They have no paintable payload; a
        // 100x100 fallback box would render a broken image and incorrectly
        // consume paragraph flow. Keep the host paragraph, but omit the run.
        return;
      }
      const constrained = constrainImageToPage(
        attrs.width ?? 100,
        attrs.height ?? 100,
        _options.pageContentHeight,
      );
      // Lift tracked-change marks off the image node so an inserted/deleted
      // picture paints in the revision colour and resolves with the rest of
      // the change. eigenpal #641.
      const trackedFmt = extractRunFormatting(child.marks, theme);
      const run = buildImageRun(
        attrs,
        constrained,
        childPos,
        childPos + child.nodeSize,
        trackedFmt,
      );
      runs.push(run);
      return;
    }
    if (child.type.name === "field") {
      // Marks on the field node (bold/italic/underline applied to the
      // field result inside `<w:fldChar separate>...</w:fldChar end>`)
      // must propagate to the run formatting, otherwise complex REF
      // fields whose visible text was authored as underlined (e.g.
      // cross-references like "Exhibit A" / "Section 1.3" in NVCA-style
      // templates) render with no underline. Reuse the same extractor
      // text runs use.
      const attrs = expectFieldAttrs(child);
      const ft = attrs.fieldType;
      let mappedType: FieldRun["fieldType"] = "OTHER";
      if (ft === "PAGE") {
        mappedType = "PAGE";
      } else if (ft === "NUMPAGES") {
        mappedType = "NUMPAGES";
      } else if (ft === "DATE") {
        mappedType = "DATE";
      } else if (ft === "TIME") {
        mappedType = "TIME";
      }
      const extractedFieldFormatting = extractRunFormatting(child.marks, theme);
      if (inTocParagraph) {
        stripTocHyperlinkStyle(extractedFieldFormatting);
      }
      const fieldFormatting = markDefaultBlackTextColorSource(
        extractedFieldFormatting,
        paraDefaults,
      );
      const run: FieldRun = {
        kind: "field",
        fieldType: mappedType,
        instruction: attrs.instruction,
        fallback: attrs.displayText || "",
        ...(attrs.fldLock ? { fldLock: true } : {}),
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
        ...fieldFormatting,
      };
      runs.push(run);
      return;
    }
    if (child.type.name === "math") {
      const attrs = expectMathAttrs(child);
      const plainText = attrs.plainText || "[equation]";
      runs.push({
        kind: "math",
        display: attrs.display ?? "inline",
        ommlXml: attrs.ommlXml,
        plainText,
        italic: true,
        fontFamily: "Cambria Math",
        pmStart: childPos,
        pmEnd: childPos + child.nodeSize,
      });
      return;
    }
    if (child.type.name === "sdt") {
      const sdtInnerOffset = childPos + 1; // +1 for opening tag
      // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
      child.forEach((sdtChild, sdtChildOffset) => {
        pushRunsForChild(sdtChild, sdtInnerOffset + sdtChildOffset);
      });
    }
  }

  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  node.forEach((child, childOffset) => {
    pushRunsForChild(child, offset + childOffset);
  });

  return runs;
}

/**
 * Convert PM paragraph attrs to layout engine paragraph attrs.
 */
type ListMarkerRevision = NonNullable<ParagraphAttrs["listMarkerRevision"]>;

type ListPropertyChange = {
  info?: { id?: unknown; author?: unknown; date?: unknown };
  previousFormatting?: Record<string, unknown> | null;
};

function toListMarkerRevision(
  kind: ListMarkerRevision["kind"],
  info: ListPropertyChange["info"],
): ListMarkerRevision {
  const revision: ListMarkerRevision = { kind };
  if (typeof info?.author === "string") {
    revision.author = info.author;
  }
  if (typeof info?.date === "string") {
    revision.date = info.date;
  }
  if (typeof info?.id === "number") {
    revision.revisionId = info.id;
  }
  return revision;
}

function isAddedNumberingChange(change: ListPropertyChange): change is ListPropertyChange & {
  previousFormatting: Record<string, unknown>;
} {
  const previousFormatting = change.previousFormatting;
  return (
    previousFormatting != null &&
    Object.hasOwn(previousFormatting, "numPr") &&
    previousFormatting["numPr"] == null
  );
}

function isRemovedNumberingChange(change: ListPropertyChange): change is ListPropertyChange & {
  previousFormatting: Record<string, unknown>;
} {
  const previousFormatting = change.previousFormatting;
  return (
    previousFormatting != null &&
    Object.hasOwn(previousFormatting, "numPr") &&
    isListNumPr(previousFormatting["numPr"])
  );
}

function isChangedNumberingChange(
  currentNumPr: NonNullable<PMParagraphAttrs["numPr"]>,
  change: ListPropertyChange,
): change is ListPropertyChange & {
  previousFormatting: Record<string, unknown>;
} {
  const previousFormatting = change.previousFormatting;
  return (
    previousFormatting != null &&
    Object.hasOwn(previousFormatting, "numPr") &&
    isListNumPr(previousFormatting["numPr"]) &&
    !areListNumPrEqual(previousFormatting["numPr"], currentNumPr)
  );
}

function areListNumPrEqual(
  left: NonNullable<PMParagraphAttrs["numPr"]>,
  right: NonNullable<PMParagraphAttrs["numPr"]>,
): boolean {
  return left.numId === right.numId && left.ilvl === right.ilvl;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function isListNumPr(value: unknown): value is NonNullable<PMParagraphAttrs["numPr"]> {
  if (!isRecord(value)) {
    return false;
  }
  const numId = value["numId"];
  const ilvl = value["ilvl"];
  return (
    (numId === undefined || typeof numId === "number") &&
    (ilvl === undefined || typeof ilvl === "number")
  );
}

function isNumberFormat(value: unknown): value is NumberFormat {
  return NUMBER_FORMAT_VALUES.some((format) => format === value);
}

function readNumberFormats(value: unknown): NumberFormat[] | undefined {
  if (!Array.isArray(value)) {
    return undefined;
  }

  const formats: NumberFormat[] = [];
  for (const item of value) {
    if (!isNumberFormat(item)) {
      return undefined;
    }
    formats.push(item);
  }
  return formats;
}

function readListMarkerSuffix(value: unknown): PMParagraphAttrs["listMarkerSuffix"] | undefined {
  if (value === "tab" || value === "space" || value === "nothing") {
    return value;
  }
  return undefined;
}

function readListMarkerAlignment(
  value: unknown,
): PMParagraphAttrs["listMarkerAlignment"] | undefined {
  if (value === "left" || value === "center" || value === "right") {
    return value;
  }
  return undefined;
}

function toPreviousListAttrs(previousFormatting: Record<string, unknown>): PMParagraphAttrs {
  const attrs: PMParagraphAttrs = {};
  const numPr = previousFormatting["numPr"];
  if (isListNumPr(numPr)) {
    attrs.numPr = numPr;
  }

  const listIsBullet = previousFormatting["listIsBullet"];
  if (typeof listIsBullet === "boolean") {
    attrs.listIsBullet = listIsBullet;
  }

  const listIsLegal = previousFormatting["listIsLegal"];
  if (typeof listIsLegal === "boolean") {
    attrs.listIsLegal = listIsLegal;
  }

  const listMarker = previousFormatting["listMarker"];
  if (typeof listMarker === "string") {
    attrs.listMarker = listMarker;
  }

  const listNumFmt = previousFormatting["listNumFmt"];
  if (isNumberFormat(listNumFmt)) {
    attrs.listNumFmt = listNumFmt;
  }

  const listLevelNumFmts = readNumberFormats(previousFormatting["listLevelNumFmts"]);
  if (listLevelNumFmts) {
    attrs.listLevelNumFmts = listLevelNumFmts;
  }

  const listLevelStarts = previousFormatting["listLevelStarts"];
  if (
    Array.isArray(listLevelStarts) &&
    listLevelStarts.every((value) => typeof value === "number")
  ) {
    attrs.listLevelStarts = listLevelStarts;
  }

  const listAbstractNumId = previousFormatting["listAbstractNumId"];
  if (typeof listAbstractNumId === "number") {
    attrs.listAbstractNumId = listAbstractNumId;
  }

  const listStartOverride = previousFormatting["listStartOverride"];
  if (typeof listStartOverride === "number") {
    attrs.listStartOverride = listStartOverride;
  }

  const listMarkerHidden = previousFormatting["listMarkerHidden"];
  if (typeof listMarkerHidden === "boolean") {
    attrs.listMarkerHidden = listMarkerHidden;
  }

  const listMarkerFontFamily = previousFormatting["listMarkerFontFamily"];
  if (typeof listMarkerFontFamily === "string") {
    attrs.listMarkerFontFamily = listMarkerFontFamily;
  }

  const listMarkerFontSize = previousFormatting["listMarkerFontSize"];
  if (typeof listMarkerFontSize === "number") {
    attrs.listMarkerFontSize = listMarkerFontSize;
  }

  const listMarkerBold = previousFormatting["listMarkerBold"];
  if (typeof listMarkerBold === "boolean") {
    attrs.listMarkerBold = listMarkerBold;
  }

  const listMarkerAlignment = readListMarkerAlignment(previousFormatting["listMarkerAlignment"]);
  if (listMarkerAlignment) {
    attrs.listMarkerAlignment = listMarkerAlignment;
  }

  const listMarkerSuffix = readListMarkerSuffix(previousFormatting["listMarkerSuffix"]);
  if (listMarkerSuffix) {
    attrs.listMarkerSuffix = listMarkerSuffix;
  }

  return attrs;
}

function resolveDeletedListMarker(
  previousListAttrs: PMParagraphAttrs,
  listCounters: Map<number, number[]> | undefined,
  listAbstractCounters: Map<number, number[]> | undefined,
  listSeenNumIds: Set<string> | undefined,
): string | null {
  if (listCounters && previousListAttrs.numPr) {
    // Advance the original counter stream in place (no clone): a
    // removed-numbering deletion occupied a number in the pre-revision
    // document, so it must progress the counter exactly like a deleted list
    // item — otherwise a following deletion on the same numId reuses it.
    const marker = computeListMarker(
      previousListAttrs,
      listCounters,
      listAbstractCounters ?? new Map<number, number[]>(),
      listSeenNumIds ?? new Set<string>(),
    );
    if (marker) {
      return marker;
    }
  }

  if (previousListAttrs.listMarker) {
    return previousListAttrs.listIsBullet
      ? convertBulletToUnicode(previousListAttrs.listMarker)
      : previousListAttrs.listMarker;
  }

  if (previousListAttrs.listIsBullet) {
    return "\u2022";
  }

  return null;
}

function applyDeletedListMarkerAttrs(
  attrs: ParagraphAttrs,
  change: ListPropertyChange & {
    previousFormatting: Record<string, unknown>;
  },
  listCounters: Map<number, number[]> | undefined,
  listAbstractCounters: Map<number, number[]> | undefined,
  listSeenNumIds: Set<string> | undefined,
): void {
  const previousListAttrs = toPreviousListAttrs(change.previousFormatting);
  const marker = resolveDeletedListMarker(
    previousListAttrs,
    listCounters,
    listAbstractCounters,
    listSeenNumIds,
  );
  if (!marker) {
    return;
  }

  attrs.listMarker = marker;
  attrs.listMarkerRevision = toListMarkerRevision("del", change.info);
  if (previousListAttrs.listIsBullet !== undefined) {
    attrs.listIsBullet = previousListAttrs.listIsBullet;
  }
  if (previousListAttrs.listMarkerHidden !== undefined) {
    attrs.listMarkerHidden = previousListAttrs.listMarkerHidden;
  }
  if (previousListAttrs.listMarkerFontFamily) {
    attrs.listMarkerFontFamily = previousListAttrs.listMarkerFontFamily;
  }
  if (previousListAttrs.listMarkerFontSize) {
    attrs.listMarkerFontSize = previousListAttrs.listMarkerFontSize;
  }
  if (previousListAttrs.listMarkerBold !== undefined) {
    attrs.listMarkerBold = previousListAttrs.listMarkerBold;
  }
  if (previousListAttrs.listMarkerAlignment) {
    attrs.listMarkerAlignment = previousListAttrs.listMarkerAlignment;
  }
  if (previousListAttrs.listMarkerSuffix) {
    attrs.listMarkerSuffix = previousListAttrs.listMarkerSuffix;
  }
}

function convertParagraphAttrs(
  pmAttrs: PMParagraphAttrs,
  theme?: Theme | null,
  listCounters?: Map<number, number[]>,
  listAbstractCounters?: Map<number, number[]>,
  listSeenNumIds?: Set<string>,
  defaultTabStopTwips?: number,
  originalListCounters?: Map<number, number[]>,
  originalListAbstractCounters?: Map<number, number[]>,
  originalListSeenNumIds?: Set<string>,
): ParagraphAttrs {
  const attrs: ParagraphAttrs = {};

  // Alignment - map DOCX values to CSS-compatible values
  // DOCX uses 'both' for justify, 'distribute' for distributed justify
  if (pmAttrs.alignment) {
    const align = pmAttrs.alignment;
    if (align === "both" || align === "distribute") {
      attrs.alignment = "justify";
    } else if (align === "left") {
      attrs.alignment = "left";
    } else if (align === "center") {
      attrs.alignment = "center";
    } else if (align === "right") {
      attrs.alignment = "right";
    }
    // Other DOCX alignments (mediumKashida, highKashida, lowKashida, thaiDistribute, justify)
    // default to no alignment set (inherits from style or defaults to left)
  }

  if (typeof pmAttrs.outlineLevel === "number") {
    attrs.outlineLevel = pmAttrs.outlineLevel;
  }

  // Spacing. HTML-origin auto spacing (w:beforeAutospacing/afterAutospacing)
  // renders Word's 14pt auto gap, overriding the imported before/after (which
  // Word writes as `0`) — surface it here so pagination matches the rendered
  // margins (eigenpal/docx-editor#823). But only while the effective spacing
  // still matches the import baseline; any later command or style change that
  // writes a different spacing value must win over the stale auto-spacing flag.
  const spaceBefore = pmAttrs.spaceBefore;
  const spaceAfter = pmAttrs.spaceAfter;
  const lineSpacing = pmAttrs.lineSpacing;
  if (typeof pmAttrs.snapToGrid === "boolean") {
    attrs.snapToGrid = pmAttrs.snapToGrid;
  }
  const autoBefore = autospacingMatchesBase(pmAttrs._autospacingBase, "before", spaceBefore);
  const autoAfter = autospacingMatchesBase(pmAttrs._autospacingBase, "after", spaceAfter);
  if (
    autoBefore ||
    autoAfter ||
    typeof spaceBefore === "number" ||
    typeof spaceAfter === "number" ||
    typeof lineSpacing === "number"
  ) {
    attrs.spacing = {};
    if (autoBefore) {
      attrs.spacing.before = AUTO_PARAGRAPH_SPACING_PX;
    } else if (typeof spaceBefore === "number") {
      attrs.spacing.before = twipsToPixels(spaceBefore);
    }
    if (autoAfter) {
      attrs.spacing.after = AUTO_PARAGRAPH_SPACING_PX;
    } else if (typeof spaceAfter === "number") {
      attrs.spacing.after = twipsToPixels(spaceAfter);
    }
    if (autoBefore || autoAfter) {
      attrs.automaticSpacing = {
        ...(autoBefore ? { before: true } : {}),
        ...(autoAfter ? { after: true } : {}),
      };
    }
    // Preserve spacing sides whose source Word renders on an empty paragraph:
    // direct formatting, document defaults, the implicit default paragraph
    // style, and automatic spacing. Layout consumes the combined provenance;
    // the authored PM attributes remain source-specific for serialization.
    const pmSpacingExplicit = pmAttrs.spacingExplicit as
      | { before?: boolean; after?: boolean }
      | null
      | undefined;
    const spacingFromDocDefaults = pmAttrs.spacingFromDocDefaults as
      | { before?: boolean; after?: boolean }
      | null
      | undefined;
    const spacingFromImplicitDefaultStyle = pmAttrs.spacingFromImplicitDefaultStyle as
      | { before?: boolean; after?: boolean }
      | null
      | undefined;
    const explicit: { before?: boolean; after?: boolean } = {};
    if (
      autoBefore ||
      pmSpacingExplicit?.before ||
      spacingFromDocDefaults?.before ||
      spacingFromImplicitDefaultStyle?.before
    ) {
      explicit.before = true;
    }
    if (
      autoAfter ||
      pmSpacingExplicit?.after ||
      spacingFromDocDefaults?.after ||
      spacingFromImplicitDefaultStyle?.after
    ) {
      explicit.after = true;
    }
    if (explicit.before !== undefined || explicit.after !== undefined) {
      attrs.spacingExplicit = explicit;
    }
    if (typeof lineSpacing === "number") {
      // Line spacing in twips - convert to multiplier or exact
      if (pmAttrs.lineSpacingRule === "exact" || pmAttrs.lineSpacingRule === "atLeast") {
        attrs.spacing.line = twipsToPixels(lineSpacing);
        attrs.spacing.lineUnit = "px";
        attrs.spacing.lineRule = pmAttrs.lineSpacingRule;
      } else {
        // Auto - line spacing is in 240ths of a line
        attrs.spacing.line = lineSpacing / 240;
        attrs.spacing.lineUnit = "multiplier";
        attrs.spacing.lineRule = "auto";
      }
    }
  }

  // Indentation - handle list item fallback calculation
  // For list items without explicit indentation, calculate based on level
  let indentLeft = typeof pmAttrs.indentLeft === "number" ? pmAttrs.indentLeft : undefined;
  let indentFirstLine =
    typeof pmAttrs.indentFirstLine === "number" ? pmAttrs.indentFirstLine : undefined;
  let hangingIndent = pmAttrs.hangingIndent;
  if (pmAttrs.numPr?.numId && indentLeft === undefined && indentFirstLine === undefined) {
    // Fallback: calculate indentation based on level
    // An authored first-line or hanging position is already a complete list
    // marker anchor. Adding a synthetic left indent would shift that anchor a
    // second time, while tab stops still resolve from the paragraph margin.
    // Each level indents 0.5 inch (720 twips) more
    const level = pmAttrs.numPr.ilvl ?? 0;
    // Base indentation: 0.5 inch (720 twips) per level
    // Level 0 = 720 twips, Level 1 = 1440 twips, etc.
    indentLeft = (level + 1) * 720;
    // Default hanging indent of 360 twips for the list marker
    if (indentFirstLine === undefined) {
      indentFirstLine = -360;
      hangingIndent = true;
    }
  }

  if (
    indentLeft !== undefined ||
    typeof pmAttrs.indentRight === "number" ||
    indentFirstLine !== undefined
  ) {
    attrs.indent = {};
    if (indentLeft !== undefined) {
      attrs.indent.left = twipsToPixels(indentLeft);
    }
    if (typeof pmAttrs.indentRight === "number") {
      attrs.indent.right = twipsToPixels(pmAttrs.indentRight);
    }
    if (indentFirstLine !== undefined) {
      if (hangingIndent) {
        // Hanging indent: indentFirstLine is stored as negative, convert to positive for rendering
        attrs.indent.hanging = Math.abs(twipsToPixels(indentFirstLine));
      } else {
        attrs.indent.firstLine = twipsToPixels(indentFirstLine);
      }
    }
  }

  // Style ID
  if (pmAttrs.styleId) {
    attrs.styleId = pmAttrs.styleId;
  }

  // Borders
  if (pmAttrs.borders) {
    const borders = pmAttrs.borders;
    attrs.borders = {};

    const convertBorder = (border: typeof borders.top) =>
      border ? convertBorderSpecToLayout(border, theme) : undefined;

    const topBorder = borders.top ? convertBorder(borders.top) : undefined;
    if (topBorder) {
      attrs.borders.top = topBorder;
    }
    const bottomBorder = borders.bottom ? convertBorder(borders.bottom) : undefined;
    if (bottomBorder) {
      attrs.borders.bottom = bottomBorder;
    }
    const leftBorder = borders.left ? convertBorder(borders.left) : undefined;
    if (leftBorder) {
      attrs.borders.left = leftBorder;
    }
    const rightBorder = borders.right ? convertBorder(borders.right) : undefined;
    if (rightBorder) {
      attrs.borders.right = rightBorder;
    }
    const betweenBorder = borders.between ? convertBorder(borders.between) : undefined;
    if (betweenBorder) {
      attrs.borders.between = betweenBorder;
    }
    const barBorder = borders.bar ? convertBorder(borders.bar) : undefined;
    if (barBorder) {
      attrs.borders.bar = barBorder;
    }

    // Only include if at least one border is set
    if (
      !attrs.borders.top &&
      !attrs.borders.bottom &&
      !attrs.borders.left &&
      !attrs.borders.right &&
      !attrs.borders.between &&
      !attrs.borders.bar
    ) {
      delete attrs.borders;
    }
  }

  // Shading (background color). Word's `Normal` paragraph style commonly
  // sets `<w:shd val="clear" fill="FFFFFF"/>` — semantically a no-op on
  // a white page, but folio's dark mode draws the literal `#FFFFFF`
  // fill as a visible white block over the dark canvas. Treat any white
  // shading as transparent (= page background) so it renders the same as
  // "no shading" in both modes. Other shading colors are preserved
  // verbatim so authored highlights stay visible.
  const shadingRgb = pmAttrs.shading?.fill?.rgb?.toUpperCase();
  if (shadingRgb && shadingRgb !== "FFFFFF" && shadingRgb !== "FFFFFE") {
    attrs.shading = `#${pmAttrs.shading?.fill?.rgb}`;
  }

  // Tab stops
  if (pmAttrs.tabs && pmAttrs.tabs.length > 0) {
    attrs.tabs = pmAttrs.tabs.map((tab) => {
      const tabStop: TabStop = {
        val: mapTabAlignment(tab.alignment),
        pos: tab.position,
      };
      if (tab.leader) {
        tabStop.leader = tab.leader as NonNullable<TabStop["leader"]>;
      }
      return tabStop;
    });
  }

  // Page break control
  if (pmAttrs.pageBreakBefore) {
    attrs.pageBreakBefore = true;
  }
  if (pmAttrs.kinsoku !== undefined && pmAttrs.kinsoku !== null) {
    attrs.kinsoku = pmAttrs.kinsoku;
  }
  if (pmAttrs.overflowPunctuation !== undefined && pmAttrs.overflowPunctuation !== null) {
    attrs.overflowPunctuation = pmAttrs.overflowPunctuation;
  }
  if (pmAttrs.suppressAutoHyphens !== undefined && pmAttrs.suppressAutoHyphens !== null) {
    attrs.suppressAutoHyphens = pmAttrs.suppressAutoHyphens;
  }
  if (pmAttrs.renderedPageBreakBefore) {
    attrs.renderedPageBreakBefore = true;
  }
  if (pmAttrs.keepNext) {
    attrs.keepNext = true;
  }
  if (pmAttrs.keepLines) {
    attrs.keepLines = true;
  }
  if (pmAttrs.widowControl === false) {
    attrs.widowControl = false;
  }
  if (pmAttrs.contextualSpacing) {
    attrs.contextualSpacing = true;
  }
  if (pmAttrs.runInWithNext) {
    attrs.runInWithNext = true;
  }
  if (directionIsRtl(pmAttrs.direction)) {
    attrs.bidi = true;
  }
  if (pmAttrs.styleId) {
    attrs.styleId = pmAttrs.styleId;
  }

  // List properties
  const pPrChange = pmAttrs._propertyChanges as ListPropertyChange[] | null;
  const propertyChanges = Array.isArray(pPrChange) ? pPrChange : [];
  let changedNumberingChange:
    | (ListPropertyChange & { previousFormatting: Record<string, unknown> })
    | undefined;
  if (pmAttrs.numPr) {
    const numPr: ParagraphAttrs["numPr"] & object = {};
    if (pmAttrs.numPr.numId !== undefined) {
      numPr.numId = pmAttrs.numPr.numId;
    }
    if (pmAttrs.numPr.ilvl !== undefined) {
      numPr.ilvl = pmAttrs.numPr.ilvl;
    }
    attrs.numPr = numPr;

    if (pmAttrs.pPrMark?.kind === "del") {
      attrs.listMarkerRevision = toListMarkerRevision("del", pmAttrs.pPrMark.info);
    } else if (pmAttrs.pPrMark?.kind === "ins") {
      attrs.listMarkerRevision = toListMarkerRevision("ins", pmAttrs.pPrMark.info);
    } else {
      const numberingAddedChange = propertyChanges.find(isAddedNumberingChange);
      const currentNumPr = pmAttrs.numPr;
      changedNumberingChange = propertyChanges.find(
        (
          change,
        ): change is ListPropertyChange & {
          previousFormatting: Record<string, unknown>;
        } => isChangedNumberingChange(currentNumPr, change),
      );
      const numberingInsertionChange = numberingAddedChange ?? changedNumberingChange;
      if (numberingInsertionChange) {
        attrs.listMarkerRevision = toListMarkerRevision("ins", numberingInsertionChange.info);
      }
    }
  }
  // Tracked-deletion list items number off a separate "original" stream so the
  // inserted list (a, b) and the deleted list (a, b, c) restart independently
  // instead of running one shared counter (a, b, c, d, e). Insertions and normal
  // items use the final stream; normal items also advance the original stream so
  // a later deleted sibling continues from the surviving count (Word parity).
  const useOriginalStream =
    attrs.listMarkerRevision?.kind === "del" && originalListCounters !== undefined;
  const streamCounters = useOriginalStream ? originalListCounters : listCounters;
  const streamAbstractCounters = useOriginalStream
    ? originalListAbstractCounters
    : listAbstractCounters;
  const streamSeenNumIds = useOriginalStream ? originalListSeenNumIds : listSeenNumIds;
  const resolvedMarker = applyMarkerAllCaps(
    streamCounters
      ? computeListMarker(
          pmAttrs,
          streamCounters,
          streamAbstractCounters ?? new Map(),
          streamSeenNumIds ?? new Set(),
        )
      : null,
    pmAttrs.listMarkerAllCaps,
  );
  const numberedNumId = pmAttrs.numPr?.numId;
  if (
    attrs.listMarkerRevision === undefined &&
    !pmAttrs.listIsBullet &&
    originalListCounters !== undefined &&
    numberedNumId !== undefined &&
    numberedNumId !== 0
  ) {
    computeListMarker(
      pmAttrs,
      originalListCounters,
      originalListAbstractCounters ?? new Map(),
      originalListSeenNumIds ?? new Set(),
    );
  } else if (changedNumberingChange !== undefined && originalListCounters !== undefined) {
    // Changed numbering is shown as an insertion of the new numId, but in the
    // pre-revision document the paragraph sat under its PREVIOUS numId. Advance
    // that original stream so a later deletion on the old numId continues from
    // the right count instead of reusing this item's number.
    const previousListAttrs = toPreviousListAttrs(changedNumberingChange.previousFormatting);
    if (previousListAttrs.numPr && !previousListAttrs.listIsBullet) {
      computeListMarker(
        previousListAttrs,
        originalListCounters,
        originalListAbstractCounters ?? new Map(),
        originalListSeenNumIds ?? new Set(),
      );
    }
  }
  if (resolvedMarker !== null) {
    attrs.listMarker = resolvedMarker;
  } else if (pmAttrs.listMarker) {
    attrs.listMarker = pmAttrs.listIsBullet
      ? convertBulletToUnicode(pmAttrs.listMarker)
      : pmAttrs.listMarker;
  }
  if (pmAttrs.listIsBullet !== undefined) {
    attrs.listIsBullet = pmAttrs.listIsBullet;
  }
  if (pmAttrs.listMarkerHidden) {
    attrs.listMarkerHidden = true;
  }
  if (pmAttrs.listMarkerFontFamily) {
    attrs.listMarkerFontFamily = pmAttrs.listMarkerFontFamily;
  }
  if (pmAttrs.listMarkerFontSize) {
    attrs.listMarkerFontSize = pmAttrs.listMarkerFontSize;
  }
  if (pmAttrs.listMarkerBold !== null && pmAttrs.listMarkerBold !== undefined) {
    attrs.listMarkerBold = pmAttrs.listMarkerBold;
  }
  if (pmAttrs.listMarkerAlignment) {
    attrs.listMarkerAlignment = pmAttrs.listMarkerAlignment;
  }
  if (pmAttrs.listMarkerSuffix) {
    attrs.listMarkerSuffix = pmAttrs.listMarkerSuffix;
  }
  if (pmAttrs.listMarkerSecondSlotOffsetTwips !== undefined) {
    attrs.listMarkerSecondSlotOffsetTwips = pmAttrs.listMarkerSecondSlotOffsetTwips;
  }
  if (!pmAttrs.numPr) {
    const numberingRemovedChange = propertyChanges.find(isRemovedNumberingChange);
    if (numberingRemovedChange) {
      // Number removed-numbering deletions off the original stream too (like
      // deleted list items): the struck-through marker must reflect the
      // pre-revision number, not the final counter that insertions advanced.
      applyDeletedListMarkerAttrs(
        attrs,
        numberingRemovedChange,
        originalListCounters,
        originalListAbstractCounters,
        originalListSeenNumIds,
      );
    }
  }
  if (defaultTabStopTwips !== undefined) {
    attrs.defaultTabStopTwips = defaultTabStopTwips;
  }
  // Default font for empty paragraph measurement (from style's rPr / pPr/rPr)
  const dtf = pmAttrs.defaultTextFormatting as TextFormatting | undefined;
  if (dtf) {
    if (dtf.fontSize !== undefined) {
      // fontSize in TextFormatting is in half-points, convert to points
      attrs.defaultFontSize = dtf.fontSize / 2;
    }
    if (
      attrs.listMarker !== undefined &&
      !attrs.listMarkerHidden &&
      dtf.fontSizeCs !== undefined &&
      (dtf.fontSize === undefined || dtf.fontSizeCs > dtf.fontSize)
    ) {
      attrs.listParagraphMarkFontSize = dtf.fontSizeCs / 2;
    }
    if (dtf.fontFamily) {
      const resolvedFamily = resolveWesternThemeFont(dtf.fontFamily, theme);
      if (resolvedFamily) {
        attrs.defaultFontFamily = resolvedFamily;
      }
    }
  }

  return attrs;
}

/**
 * Map document TabStopAlignment to layout engine TabAlignment
 */
function mapTabAlignment(
  align: "left" | "center" | "right" | "decimal" | "bar" | "clear" | "num",
): "start" | "end" | "center" | "decimal" | "bar" | "clear" {
  switch (align) {
    case "left":
      return "start";
    case "right":
      return "end";
    case "center":
      return "center";
    case "decimal":
      return "decimal";
    case "bar":
      return "bar";
    case "clear":
      return "clear";
    case "num":
      return "start"; // Number tab treated as left-aligned
    default:
      return "start";
  }
}

/**
 * Convert a paragraph node to a ParagraphBlock.
 */
function hasOnlyVisuallyEmptyTextRuns(runs: Run[]): boolean {
  return (
    runs.length > 0 &&
    runs.every(
      (run) => run.kind === "text" && run.text.replace(/\u00a0/gu, " ").trim().length === 0,
    )
  );
}

function convertParagraph(
  node: PMNode,
  startPos: number,
  options: ToFlowBlocksOptions,
): ParagraphBlock {
  const pmAttrs = expectParagraphAttrs(node);
  const runs = paragraphToRuns(node, startPos, options);
  const attrs = convertParagraphAttrs(
    pmAttrs,
    options.theme,
    options.listCounters,
    options.listAbstractCounters,
    options.listSeenNumIds,
    options.defaultTabStopTwips,
    options.originalListCounters,
    options.originalListAbstractCounters,
    options.originalListSeenNumIds,
  );
  if (options.lineBreakRules) {
    attrs.lineBreakRules = options.lineBreakRules;
  }
  if (options.justificationCompatibility) {
    attrs.justificationCompatibility = options.justificationCompatibility;
  }
  if (options.automaticHyphenation) {
    attrs.automaticHyphenation = options.automaticHyphenation;
  }
  const defaultTextFormatting = pmAttrs.defaultTextFormatting as TextFormatting | undefined;
  if (runs.length === 0 || hasOnlyVisuallyEmptyTextRuns(runs)) {
    const hasDirectParagraphFormatting =
      pmAttrs._originalFormatting &&
      Object.entries(pmAttrs._originalFormatting).some(
        ([key, value]) => key !== "runProperties" && value !== undefined && value !== null,
      );
    if (hasDirectParagraphFormatting) {
      attrs.hasDirectParagraphFormatting = true;
    }
    const paragraphMarkFormatting = pmAttrs._originalFormatting?.runProperties;
    if (
      paragraphMarkFormatting &&
      Object.values(paragraphMarkFormatting).some((value) => value !== undefined && value !== null)
    ) {
      attrs.hasDirectParagraphMarkFormatting = true;
    }
    if (paragraphMarkFormatting?.fontSize !== undefined) {
      attrs.defaultFontSize = paragraphMarkFormatting.fontSize / 2;
    }
    const paragraphMarkFontFamily = paragraphMarkFormatting?.fontFamily
      ? resolveWesternThemeFont(paragraphMarkFormatting.fontFamily, options.theme)
      : undefined;
    if (paragraphMarkFontFamily) {
      attrs.defaultFontFamily = paragraphMarkFontFamily;
    }
  }
  if (runs.length === 0 && defaultTextFormatting?.hidden === true) {
    attrs.suppressEmptyParagraphHeight = true;
    if (attrs.listMarker !== undefined) {
      attrs.listMarkerHidden = true;
    }
  }
  const hasVisibleParagraphPayload =
    (attrs.listMarker !== undefined && !attrs.listMarkerHidden) ||
    attrs.borders?.top !== undefined ||
    attrs.borders?.bottom !== undefined ||
    attrs.borders?.left !== undefined ||
    attrs.borders?.right !== undefined ||
    attrs.borders?.between !== undefined ||
    attrs.borders?.bar !== undefined ||
    attrs.shading !== undefined;
  if (runs.length === 0 && pmAttrs._pageBreakCarrier === true && !hasVisibleParagraphPayload) {
    attrs.suppressEmptyParagraphHeight = true;
  }

  const bookmarkNames = pmAttrs.bookmarks?.map((b) => b.name);

  const block: ParagraphBlock = {
    kind: "paragraph",
    id: nextBlockId(),
    runs,
    attrs,
    ...(pmAttrs.paraId ? { paraId: pmAttrs.paraId } : {}),
    ...(bookmarkNames && bookmarkNames.length > 0 ? { bookmarks: bookmarkNames } : {}),
    pmStart: startPos,
    pmEnd: startPos + node.nodeSize,
  };
  const frame = pmAttrs._originalFormatting?.frame;
  if (frame !== undefined && frame.dropCap !== "drop" && frame.dropCap !== "margin") {
    setParagraphFrame(block, {
      ...(frame.width !== undefined ? { width: twipsToPixels(frame.width) } : {}),
      ...(frame.height !== undefined ? { height: twipsToPixels(frame.height) } : {}),
      ...(frame.hSpace !== undefined ? { hSpace: twipsToPixels(frame.hSpace) } : {}),
      ...(frame.vSpace !== undefined ? { vSpace: twipsToPixels(frame.vSpace) } : {}),
      ...(frame.hAnchor !== undefined ? { hAnchor: frame.hAnchor } : {}),
      ...(frame.vAnchor !== undefined ? { vAnchor: frame.vAnchor } : {}),
      ...(frame.x !== undefined ? { x: twipsToPixels(frame.x) } : {}),
      ...(frame.y !== undefined ? { y: twipsToPixels(frame.y) } : {}),
      ...(frame.xAlign !== undefined ? { xAlign: frame.xAlign } : {}),
      ...(frame.yAlign !== undefined ? { yAlign: frame.yAlign } : {}),
      ...(frame.wrap !== undefined ? { wrap: frame.wrap } : {}),
    });
  }
  return block;
}

/**
 * Word keeps terminal empty body paragraphs after a final table as editable
 * anchors, but they do not create a page of their own. Preserve every block
 * and PM range while collapsing only the contiguous, run-free suffix; empty
 * paragraphs elsewhere still retain their normal line height.
 */
function isPaintlessTerminalParagraph(block: FlowBlock | undefined): block is ParagraphBlock {
  if (block?.kind !== "paragraph" || block.runs.length !== 0) {
    return false;
  }

  const attrs = block.attrs;
  return !(
    (attrs?.listMarker !== undefined && !attrs.listMarkerHidden) ||
    attrs?.borders?.top ||
    attrs?.borders?.bottom ||
    attrs?.borders?.left ||
    attrs?.borders?.right ||
    attrs?.borders?.between ||
    attrs?.borders?.bar ||
    attrs?.shading ||
    attrs?.spacingExplicit?.before ||
    attrs?.spacingExplicit?.after ||
    attrs?.pageBreakBefore ||
    attrs?.renderedPageBreakBefore
  );
}

function suppressTerminalEmptyParagraphsAfterTable(blocks: FlowBlock[]): void {
  let suffixStart = blocks.length;
  while (suffixStart > 0 && isPaintlessTerminalParagraph(blocks[suffixStart - 1])) {
    suffixStart -= 1;
  }

  if (
    suffixStart === blocks.length ||
    suffixStart === 0 ||
    blocks[suffixStart - 1]?.kind !== "table"
  ) {
    return;
  }

  for (let index = suffixStart; index < blocks.length; index += 1) {
    const block = blocks[index];
    if (isPaintlessTerminalParagraph(block)) {
      block.attrs = { ...block.attrs, suppressEmptyParagraphHeight: true };
    }
  }
}

function suppressFinalParagraphInRepeatedEmptySuffix(blocks: FlowBlock[]): void {
  let suffixStart = blocks.length;
  while (suffixStart > 0 && isPaintlessTerminalParagraph(blocks[suffixStart - 1])) {
    suffixStart -= 1;
  }

  if (
    suffixStart === 0 ||
    blocks.length - suffixStart < 2 ||
    blocks[suffixStart - 1]?.kind === "table"
  ) {
    return;
  }

  const finalBlock = blocks.at(-1);
  if (isPaintlessTerminalParagraph(finalBlock)) {
    finalBlock.attrs = { ...finalBlock.attrs, suppressEmptyParagraphHeight: true };
  }
}

function reserveLeadingEmptyOutlineHeight(blocks: FlowBlock[]): void {
  const firstBlock = blocks.at(0);
  if (
    firstBlock?.kind !== "paragraph" ||
    firstBlock.runs.length !== 0 ||
    firstBlock.attrs?.outlineLevel !== 0
  ) {
    return;
  }

  firstBlock.attrs = { ...firstBlock.attrs, reserveEmptyOutlineHeight: true };
}

/**
 * Convert border width from eighths of a point to pixels.
 * OOXML stores border widths in eighths of a point.
 */
function borderWidthToPixels(eighthsOfPoint: number): number {
  return pointsToPixels(eighthsOfPoint / 8);
}

// OOXML border style → CSS border-style mapping
const OOXML_TO_CSS_BORDER: Record<string, string> = {
  single: "solid",
  double: "double",
  dotted: "dotted",
  dashed: "dashed",
  thick: "solid",
  dashSmallGap: "dashed",
  dotDash: "dashed",
  dotDotDash: "dotted",
  triple: "double",
  wave: "solid",
  doubleWave: "double",
  threeDEmboss: "ridge",
  threeDEngrave: "groove",
  outset: "outset",
  inset: "inset",
};

/**
 * Convert an OOXML BorderSpec to a layout-engine BorderStyle.
 * Shared by paragraph borders, cell borders, and header/footer borders.
 */
export function convertBorderSpecToLayout(
  border: {
    style?: string;
    size?: number;
    space?: number;
    color?: {
      rgb?: string;
      themeColor?: string;
      themeTint?: string;
      themeShade?: string;
    };
  },
  theme?: Theme | null,
): BorderStyle | undefined {
  if (!border.style || border.style === "none" || border.style === "nil") {
    return undefined;
  }
  const result: BorderStyle = {
    style: OOXML_TO_CSS_BORDER[border.style] || "solid",
    width: border.size === undefined ? 1 : borderWidthToPixels(border.size),
    color: border.color
      ? resolveColor(border.color as Parameters<typeof resolveColor>[0], theme)
      : "#000000",
  };
  if (border.space !== undefined) {
    result.space = pointsToPixels(border.space);
  }
  return result;
}

/**
 * Extract cell borders from ProseMirror attributes.
 * Borders are full BorderSpec objects with style/size/color.
 */
function extractCellBorders(
  borders:
    | Record<
        string,
        {
          style?: string;
          size?: number;
          color?: {
            rgb?: string;
            themeColor?: string;
            themeTint?: string;
            themeShade?: string;
          };
        }
      >
    | null
    | undefined,
  theme?: Theme | null,
): CellBorders | undefined {
  if (!borders) {
    return undefined;
  }

  const result: CellBorders = {};
  const sides = ["top", "bottom", "left", "right"] as const;

  for (const side of sides) {
    const border = borders[side];
    const converted = border ? convertBorderSpecToLayout(border, theme) : undefined;
    if (!converted) {
      result[side] = { width: 0, style: "none" };
      continue;
    }

    result[side] = border?.size === 0 ? { ...converted, width: 0 } : converted;
  }

  const diagonalSides = ["topLeftToBottomRight", "topRightToBottomLeft"] as const;
  for (const side of diagonalSides) {
    const border = borders[side];
    const converted = border ? convertBorderSpecToLayout(border, theme) : undefined;
    if (converted) {
      result[side] = converted;
    }
  }

  return Object.keys(result).length > 0 ? result : undefined;
}

/**
 * Convert a table cell node.
 */
function convertTableCell(
  node: PMNode,
  startPos: number,
  options: ToFlowBlocksOptions,
  tableCellMargins?: {
    top?: number;
    bottom?: number;
    left?: number;
    right?: number;
  },
): TableCell {
  const blocks: FlowBlock[] = [];
  let offset = startPos + 1; // +1 for opening tag

  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  node.forEach((child) => {
    if (child.type.name === "paragraph") {
      const block = convertParagraph(child, offset, options);
      blocks.push(block);
    } else if (child.type.name === "table") {
      blocks.push(convertTable(child, offset, options));
    } else if (child.type.name === "textBox") {
      blocks.push(convertTextBoxNode(child, offset, options));
    }
    offset += child.nodeSize;
  });

  // A table cell whose final block is a nested table needs a trailing paragraph
  // as its editable cell-end marker. Keep that marker as a zero-height anchor.
  // Empty paragraphs after ordinary prose are authored content and retain their
  // normal line height.
  const trailingBlock = blocks.at(-1);
  const precedingBlock = blocks.at(-2);
  if (
    precedingBlock?.kind === "table" &&
    trailingBlock?.kind === "paragraph" &&
    trailingBlock.runs.every((run) => run.kind === "text" && run.text.length === 0)
  ) {
    trailingBlock.attrs = { ...trailingBlock.attrs, suppressEmptyParagraphHeight: true };
  }

  const attrs = expectTableCellAttrs(node);
  if (
    attrs.hideMark &&
    trailingBlock?.kind === "paragraph" &&
    trailingBlock.runs.every((run) => run.kind === "text" && run.text.length === 0)
  ) {
    trailingBlock.attrs = { ...trailingBlock.attrs, suppressEmptyParagraphHeight: true };
  }

  // Convert cell margins (twips) to pixel padding
  // OOXML TableNormal defaults: top=0, bottom=0, left=108 twips (~7px), right=108 twips (~7px)
  const margins = attrs.margins;
  const resolvePaddingSide = (
    side: TablePaddingSide,
    cellTwips: number | undefined,
    tableTwips: number | undefined,
  ): number => {
    if (cellTwips !== undefined) {
      return twipsToPixels(cellTwips);
    }
    if (tableTwips !== undefined) {
      return twipsToPixels(tableTwips);
    }
    return twipsToPixels(DEFAULT_TABLE_CELL_MARGIN_TWIPS[side]);
  };
  const padding = {
    top: resolvePaddingSide("top", margins?.top, tableCellMargins?.top),
    right: resolvePaddingSide("right", margins?.right, tableCellMargins?.right),
    bottom: resolvePaddingSide("bottom", margins?.bottom, tableCellMargins?.bottom),
    left: resolvePaddingSide("left", margins?.left, tableCellMargins?.left),
  };

  const cell: TableCell = {
    id: nextBlockId(),
    blocks: groupParagraphFrames(blocks, nextBlockId),
    colSpan: attrs.colspan,
    rowSpan: attrs.rowspan,
    padding,
  };
  if (attrs.width) {
    cell.width = twipsToPixels(attrs.width);
  }
  if (attrs.verticalAlign) {
    cell.verticalAlign = attrs.verticalAlign;
  }
  if (attrs.textDirection) {
    cell.textDirection = attrs.textDirection;
  }
  if (attrs.backgroundColor) {
    cell.background = `#${attrs.backgroundColor}`;
  }
  const cellBorders = extractCellBorders(attrs.borders, options.theme);
  if (cellBorders) {
    cell.borders = cellBorders;
  }
  if (attrs.noWrap) {
    cell.noWrap = true;
  }
  return cell;
}

/**
 * Convert a table row node.
 */
function convertTableRow(
  node: PMNode,
  startPos: number,
  options: ToFlowBlocksOptions,
  tableCellMargins?: {
    top?: number;
    bottom?: number;
    left?: number;
    right?: number;
  },
): TableRow {
  const cells: TableCell[] = [];
  let offset = startPos + 1; // +1 for opening tag

  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  node.forEach((child) => {
    if (child.type.name === "tableCell" || child.type.name === "tableHeader") {
      cells.push(convertTableCell(child, offset, options, tableCellMargins));
    }
    offset += child.nodeSize;
  });

  const attrs = expectTableRowAttrs(node);
  const row: TableRow = {
    id: nextBlockId(),
    cells,
  };
  if (attrs._originalFormatting?.gridBefore) {
    row.gridBefore = attrs._originalFormatting.gridBefore;
  }
  if (attrs._originalFormatting?.gridAfter) {
    row.gridAfter = attrs._originalFormatting.gridAfter;
  }
  if (attrs.height) {
    row.height = twipsToPixels(attrs.height);
  }
  if (attrs.heightRule) {
    row.heightRule = attrs.heightRule;
  }
  if (attrs.isHeader) {
    row.isHeader = attrs.isHeader;
  }
  if (attrs._originalFormatting?.cantSplit) {
    row.cantSplit = true;
  }
  if (attrs.hidden) {
    row.hidden = attrs.hidden;
  }
  return row;
}

/**
 * Convert a table node to a TableBlock.
 */
function convertTable(node: PMNode, startPos: number, options: ToFlowBlocksOptions): TableBlock {
  const rows: TableRow[] = [];
  let offset = startPos + 1; // +1 for opening tag
  const attrs = expectTableAttrs(node);
  const tableCellMargins = attrs.cellMargins;

  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  node.forEach((child) => {
    if (child.type.name === "tableRow") {
      rows.push(convertTableRow(child, offset, options, tableCellMargins));
    }
    offset += child.nodeSize;
  });

  // Extract columnWidths from node attributes and convert from twips to pixels
  const columnWidthsTwips = attrs.columnWidths;
  let columnWidths = columnWidthsTwips?.map(twipsToPixels);

  const width = attrs.width;
  const widthType = attrs.widthType;

  // Fallback: compute column widths from first row cell widths if table attr is missing
  if (!columnWidths && rows.length > 0) {
    // SAFETY: rows.length > 0 verified by condition above
    const firstRow = rows[0]!;
    const cellWidths = firstRow.cells.map((cell) => cell.width);
    // Only use if all cells have widths defined
    if (cellWidths.every((w) => w !== undefined && w > 0)) {
      columnWidths = cellWidths as number[];
    }
  }

  // Extract justification
  const justification = attrs.justification;

  // Extract table indent + RTL column order from _originalFormatting
  // (w:tblInd, w:bidiVisual). bidiVisual is import-only — folio has no UI to
  // toggle it — so reading the preserved formatting is sufficient
  // (eigenpal/docx-editor#940).
  const originalFormatting = attrs._originalFormatting as
    | {
        indent?: { value: number; type: string };
        bidi?: boolean;
        layout?: "fixed" | "autofit";
      }
    | undefined;
  const resolvedIndent = attrs._resolvedIndent as
    | { value: number; type: string }
    | null
    | undefined;
  const effectiveIndent = resolvedIndent ?? originalFormatting?.indent;
  const indentPx =
    effectiveIndent?.value !== undefined && effectiveIndent?.type === "dxa"
      ? twipsToPixels(effectiveIndent.value)
      : undefined;

  const floating = attrs.floating as
    | {
        horzAnchor?: "margin" | "page" | "text";
        vertAnchor?: "margin" | "page" | "text";
        tblpX?: number;
        tblpXSpec?: "left" | "center" | "right" | "inside" | "outside";
        tblpY?: number;
        tblpYSpec?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
        topFromText?: number;
        bottomFromText?: number;
        leftFromText?: number;
        rightFromText?: number;
      }
    | undefined;

  let floatingPx: FloatingTablePosition | undefined;
  if (floating) {
    const fp: FloatingTablePosition = {};
    if (floating.horzAnchor) {
      fp.horzAnchor = floating.horzAnchor;
    }
    if (floating.vertAnchor) {
      fp.vertAnchor = floating.vertAnchor;
    }
    if (floating.tblpX !== undefined) {
      fp.tblpX = twipsToPixels(floating.tblpX);
    }
    if (floating.tblpXSpec) {
      fp.tblpXSpec = floating.tblpXSpec;
    }
    if (floating.tblpY !== undefined) {
      fp.tblpY = twipsToPixels(floating.tblpY);
    }
    if (floating.tblpYSpec) {
      fp.tblpYSpec = floating.tblpYSpec;
    }
    if (floating.topFromText !== undefined) {
      fp.topFromText = twipsToPixels(floating.topFromText);
    }
    if (floating.bottomFromText !== undefined) {
      fp.bottomFromText = twipsToPixels(floating.bottomFromText);
    }
    if (floating.leftFromText !== undefined) {
      fp.leftFromText = twipsToPixels(floating.leftFromText);
    }
    if (floating.rightFromText !== undefined) {
      fp.rightFromText = twipsToPixels(floating.rightFromText);
    }
    floatingPx = fp;
  }

  const tableBlock: TableBlock = {
    kind: "table",
    id: nextBlockId(),
    rows,
    pmStart: startPos,
    pmEnd: startPos + node.nodeSize,
  };
  if (columnWidths) {
    tableBlock.columnWidths = columnWidths;
  }
  if (width !== undefined) {
    tableBlock.width = width;
  }
  if (widthType !== undefined) {
    tableBlock.widthType = widthType;
  }
  if (originalFormatting?.layout !== undefined) {
    tableBlock.layout = originalFormatting.layout;
  }
  if (justification) {
    tableBlock.justification = justification;
  }
  if (indentPx !== undefined) {
    tableBlock.indent = indentPx;
  }
  if (floatingPx) {
    tableBlock.floating = floatingPx;
  }
  if (originalFormatting?.bidi) {
    tableBlock.bidi = true;
  }
  return tableBlock;
}

/**
 * Convert an image node to an ImageBlock.
 */
function convertImage(node: PMNode, startPos: number, pageContentHeight?: number): ImageBlock {
  const attrs = expectImageAttrs(node);
  const wrapType = attrs.wrapType;

  // Only anchor images with 'behind' or 'inFront' wrap types
  // Other wrap types (square, tight, through, topAndBottom) need text wrapping
  // which we don't support yet, so treat them as block-level images
  const shouldAnchor = wrapType === "behind" || wrapType === "inFront";

  const constrained = constrainImageToPage(
    attrs.width ?? 100,
    attrs.height ?? 100,
    pageContentHeight,
  );

  const imgBlock: ImageBlock = {
    kind: "image",
    id: nextBlockId(),
    src: attrs.src,
    width: constrained.width,
    height: constrained.height,
    pmStart: startPos,
    pmEnd: startPos + node.nodeSize,
  };
  if (attrs.alt) {
    imgBlock.alt = attrs.alt;
  }
  if (attrs.transform) {
    imgBlock.transform = attrs.transform;
  }
  // eigenpal #424 (opacity render pipeline). `!= null` so PM's null schema
  // default doesn't leak into ImageBlock.opacity (`number | undefined`).
  if (attrs.opacity != null) {
    imgBlock.opacity = attrs.opacity;
  }
  if (shouldAnchor) {
    const anchor: NonNullable<ImageBlock["anchor"]> = {
      isAnchored: true,
      behindDoc: wrapType === "behind",
    };
    if (attrs.distLeft !== undefined) {
      anchor.offsetH = attrs.distLeft;
    }
    if (attrs.distTop !== undefined) {
      anchor.offsetV = attrs.distTop;
    }
    imgBlock.anchor = anchor;
  }
  if (attrs.hlinkHref) {
    imgBlock.hlinkHref = attrs.hlinkHref;
  }
  // eigenpal #424: thread wp:srcRect crop fractions to the floating-image
  // block so renderers can apply clip-path consistently across paths.
  if (attrs.cropTop != null) {
    imgBlock.cropTop = attrs.cropTop;
  }
  if (attrs.cropRight != null) {
    imgBlock.cropRight = attrs.cropRight;
  }
  if (attrs.cropBottom != null) {
    imgBlock.cropBottom = attrs.cropBottom;
  }
  if (attrs.cropLeft != null) {
    imgBlock.cropLeft = attrs.cropLeft;
  }
  // eigenpal #1096: preserve image border attrs for floating/block image
  // painting. PM defaults are null; treat null as absent.
  if (attrs.borderWidth != null) {
    imgBlock.borderWidth = attrs.borderWidth;
  }
  if (attrs.borderColor) {
    imgBlock.borderColor = attrs.borderColor;
  }
  if (attrs.borderStyle) {
    imgBlock.borderStyle = attrs.borderStyle;
  }
  return imgBlock;
}

/**
 * Convert a textBox PM node to a TextBoxBlock.
 */
function convertTextBoxNode(
  node: PMNode,
  startPos: number,
  opts: ToFlowBlocksOptions,
): TextBoxBlock {
  const attrs = expectTextBoxAttrs(node);
  const contentBlocks: (ParagraphBlock | TableBlock)[] = [];

  // Convert child blocks inside the text box
  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  node.forEach((child, offset) => {
    const childPos = startPos + 1 + offset;
    if (child.type.name === "paragraph") {
      contentBlocks.push(convertParagraph(child, childPos, opts));
      return;
    }
    if (child.type.name === "table") {
      contentBlocks.push(convertTable(child, childPos, opts));
    }
  });

  const textBox: TextBoxBlock = {
    kind: "textBox",
    id: nextBlockId(),
    width: attrs.width ?? DEFAULT_TEXTBOX_WIDTH,
    margins: {
      top: attrs.marginTop ?? DEFAULT_TEXTBOX_MARGINS.top,
      bottom: attrs.marginBottom ?? DEFAULT_TEXTBOX_MARGINS.bottom,
      left: attrs.marginLeft ?? DEFAULT_TEXTBOX_MARGINS.left,
      right: attrs.marginRight ?? DEFAULT_TEXTBOX_MARGINS.right,
    },
    content: contentBlocks,
    pmStart: startPos,
    pmEnd: startPos + node.nodeSize,
  };
  if (attrs.height !== undefined) {
    textBox.height = attrs.height;
  }
  if (attrs.autoFit !== undefined) {
    textBox.autoFit = attrs.autoFit;
  }
  if (attrs.fillColor !== undefined) {
    textBox.fillColor = attrs.fillColor;
  }
  if (attrs.outlineWidth !== undefined) {
    textBox.outlineWidth = attrs.outlineWidth;
  }
  if (attrs.outlineColor !== undefined) {
    textBox.outlineColor = attrs.outlineColor;
  }
  if (attrs.outlineStyle !== undefined) {
    textBox.outlineStyle = attrs.outlineStyle;
  }
  // Carry anchored-textbox wrap attributes through so the page renderer can
  // build exclusion rects (eigenpal #474).
  if (attrs.displayMode !== undefined) {
    textBox.displayMode = attrs.displayMode;
  }
  if (attrs.cssFloat !== undefined) {
    textBox.cssFloat = attrs.cssFloat;
  }
  if (attrs.wrapType !== undefined) {
    textBox.wrapType = attrs.wrapType;
  }
  if (attrs.wrapText !== undefined) {
    textBox.wrapText = attrs.wrapText;
  }
  if (attrs.distTop !== undefined) {
    textBox.distTop = attrs.distTop;
  }
  if (attrs.distBottom !== undefined) {
    textBox.distBottom = attrs.distBottom;
  }
  if (attrs.distLeft !== undefined) {
    textBox.distLeft = attrs.distLeft;
  }
  if (attrs.distRight !== undefined) {
    textBox.distRight = attrs.distRight;
  }
  if (attrs.position !== undefined) {
    textBox.position = attrs.position;
  }
  if (attrs._docxGroupId !== undefined) {
    setTextBoxGroupId(textBox, attrs._docxGroupId);
  }
  return textBox;
}

/**
 * Convert a ProseMirror document to FlowBlock array.
 *
 * Walks the document tree, converting each node to the appropriate block type.
 * Tracks pmStart/pmEnd positions for each block for click-to-position mapping.
 */
export function toFlowBlocks(doc: PMNode, options: ToFlowBlocksOptions = {}): FlowBlock[] {
  assertValidProseMirrorDocument(doc, "Cannot layout invalid ProseMirror document");

  resetBlockIdCounter();

  const opts: ToFlowBlocksOptions = {
    ...options,
    defaultFont: options.defaultFont ?? DEFAULT_FONT,
    defaultSize: options.defaultSize ?? DEFAULT_SIZE,
    listCounters: options.listCounters ?? new Map<number, number[]>(),
    listAbstractCounters: options.listAbstractCounters ?? new Map<number, number[]>(),
    listSeenNumIds: options.listSeenNumIds ?? new Set<string>(),
    originalListCounters: options.originalListCounters ?? new Map<number, number[]>(),
    originalListAbstractCounters:
      options.originalListAbstractCounters ?? new Map<number, number[]>(),
    originalListSeenNumIds: options.originalListSeenNumIds ?? new Set<string>(),
  };

  const blocks: FlowBlock[] = [];
  const offset = 0; // Start at document beginning; kept for clarity.
  void offset;
  let lastSectionMarginsTwips = {
    top: 1440,
    bottom: 1440,
    left: 1440,
    right: 1440,
  };

  let sdtSeq = 0;
  const sdtStack: SdtGroup[] = [];

  /**
   * Stamp the active SDT stack (outer→inner) onto every block produced by the
   * current call. ParagraphBlock/TableBlock accept `sdtGroups`; section breaks
   * and page breaks deliberately do not — they bracket layout, not content.
   */
  const tagBlockWithSdtStack = (block: FlowBlock): void => {
    if (sdtStack.length === 0) {
      return;
    }
    if (block.kind === "paragraph" || block.kind === "table") {
      block.sdtGroups = [...sdtStack];
    }
  };

  const trackedPush = (block: FlowBlock): void => {
    tagBlockWithSdtStack(block);
    blocks.push(block);
  };

  const trailingPageBreakSectionPositions = new Set<number>();
  const consumedPageBreakPositions = new Set<number>();
  const collectTrailingPageBreakSections = (parent: PMNode, contentStart: number): void => {
    let childStart = contentStart;
    for (let index = 0; index < parent.childCount; index += 1) {
      const child = parent.child(index);
      const next = index + 1 < parent.childCount ? parent.child(index + 1) : undefined;
      const paragraphAttrs =
        child.type.name === "paragraph" ? expectParagraphAttrs(child) : undefined;
      if (
        paragraphAttrs &&
        next?.type.name === "pageBreak" &&
        paragraphAttrs._trailingPageBreak === true &&
        (paragraphAttrs._sectionProperties || paragraphAttrs.sectionBreakType)
      ) {
        trailingPageBreakSectionPositions.add(childStart);
        consumedPageBreakPositions.add(childStart + child.nodeSize);
      }
      if (child.type.name === "blockSdt") {
        collectTrailingPageBreakSections(child, childStart + 1);
      }
      childStart += child.nodeSize;
    }
  };
  collectTrailingPageBreakSections(doc, offset);

  // Refactored visit-style traversal so blockSdt can recurse into its
  // children without duplicating the per-block conversion code.
  const visit = (node: PMNode, pos: number): void => {
    switch (node.type.name) {
      case "blockSdt": {
        const attrs = expectBlockSdtAttrs(node);
        sdtSeq += 1;
        const group: SdtGroup = {
          id: `sdt-${sdtSeq}`,
          pmPos: pos,
          sdtType: attrs.sdtType,
        };
        if (attrs.alias) {
          group.alias = attrs.alias;
        }
        if (attrs.tag) {
          group.tag = attrs.tag;
        }
        if (typeof attrs.id === "number") {
          group.sdtId = attrs.id;
        }
        if (attrs.lock) {
          group.lock = attrs.lock;
        }
        if (attrs.showingPlaceholder) {
          group.showingPlaceholder = true;
        }
        if (typeof attrs.checked === "boolean") {
          group.checked = attrs.checked;
        }
        if (attrs.dateFormat) {
          group.dateFormat = attrs.dateFormat;
        }
        if (attrs.listItems) {
          group.listItemsJson = attrs.listItems;
        }

        sdtStack.push(group);
        const startIndex = blocks.length;
        let childOffset = pos + 1; // skip the blockSdt opening token
        for (let i = 0; i < node.childCount; i += 1) {
          const child = node.child(i);
          visit(child, childOffset);
          childOffset += child.nodeSize;
        }
        sdtStack.pop();
        // Stamp first/middle/last/only on the innermost group of each block
        // that was emitted inside this SDT so the painter chrome continues
        // visually across the block sequence. Only paragraph/table blocks
        // carry sdtGroups; section breaks etc. were skipped at tag time.
        const groupBlocks: (ParagraphBlock | TableBlock)[] = [];
        for (let i = startIndex; i < blocks.length; i += 1) {
          const b = blocks[i];
          if (b && (b.kind === "paragraph" || b.kind === "table")) {
            groupBlocks.push(b);
          }
        }
        // We're finalizing the SDT that `group` represents — locate that
        // entry by `pmPos` instead of always taking `at(-1)`. For blocks
        // that sit inside an inner SDT, `at(-1)` is the inner group, and
        // overwriting it would clobber the inner SDT's first/middle/last
        // markers when the outer iterates the same range later. Matching
        // by pmPos keeps the inner positions intact.
        const ourPmPos = group.pmPos;
        for (let i = 0; i < groupBlocks.length; i += 1) {
          const b = groupBlocks[i];
          if (!b || !b.sdtGroups) {
            continue;
          }
          const idx = b.sdtGroups.findIndex((g) => g.pmPos === ourPmPos);
          if (idx === -1) {
            continue;
          }
          let position: NonNullable<SdtGroup["position"]>;
          if (groupBlocks.length === 1) {
            position = "only";
          } else if (i === 0) {
            position = "first";
          } else if (i === groupBlocks.length - 1) {
            position = "last";
          } else {
            position = "middle";
          }
          // Replace just the entry for this SDT, leaving inner/outer
          // sibling entries untouched. (SdtGroup objects are shared
          // across blocks of the same group; copy-on-write here keeps
          // the other blocks' references stable.)
          const next = [...b.sdtGroups];
          const existing = next[idx];
          if (!existing) {
            continue;
          }
          next[idx] = { ...existing, position };
          b.sdtGroups = next;
        }
        return;
      }
      default:
        break;
    }

    switch (node.type.name) {
      case "paragraph": {
        const pmAttrs = expectParagraphAttrs(node);
        const secProps = pmAttrs._sectionProperties as SectionProperties | undefined;
        const hasSectionBreak =
          secProps !== undefined ||
          (pmAttrs.sectionBreakType !== null && pmAttrs.sectionBreakType !== undefined);
        const hasListFormatting =
          (pmAttrs.numPr !== null && pmAttrs.numPr !== undefined) ||
          (pmAttrs.listMarker !== null && pmAttrs.listMarker !== undefined);
        const firstChild = node.firstChild;
        const startsWithColumnBreak =
          firstChild?.type.name === "hardBreak" &&
          expectHardBreakAttrs(firstChild).breakType === "column";
        const isStandaloneColumnBreak = node.childCount === 1 && startsWithColumnBreak;

        if (isStandaloneColumnBreak) {
          const columnBreak: ColumnBreakBlock = {
            kind: "columnBreak",
            id: nextBlockId(),
            pmStart: pos,
            pmEnd: pos + node.nodeSize,
          };
          trackedPush(columnBreak);
        } else if (startsWithColumnBreak && firstChild) {
          const columnBreak: ColumnBreakBlock = {
            kind: "columnBreak",
            id: nextBlockId(),
            pmStart: pos + 1,
            pmEnd: pos + 1 + firstChild.nodeSize,
          };
          trackedPush(columnBreak);

          const paragraph = convertParagraph(node, pos, opts);
          if (paragraph.runs.at(0)?.kind === "lineBreak") {
            paragraph.runs.shift();
          }
          trackedPush(paragraph);
        } else if (node.content.size > 0 || hasListFormatting || !hasSectionBreak) {
          // An empty paragraph carrying w:sectPr is Word's structural section
          // marker; it does not paint an additional blank line. Text-bearing
          // section-ending paragraphs still participate in normal layout.
          trackedPush(convertParagraph(node, pos, opts));
        }

        // Emit section break block if this paragraph ends a section
        if (hasSectionBreak) {
          if (trailingPageBreakSectionPositions.has(pos)) {
            const sourceParagraph = blocks.at(-1);
            if (sourceParagraph?.kind === "paragraph" && sourceParagraph.pmStart === pos) {
              const pageBreak: PageBreakBlock = {
                kind: "pageBreak",
                id: nextBlockId(),
                pmStart: pos + node.nodeSize,
                pmEnd: pos + node.nodeSize + 1,
              };
              trackedPush(pageBreak);
              const sourceAttrs = sourceParagraph.attrs;
              const carrierSpacing = sourceAttrs?.spacing ? { ...sourceAttrs.spacing } : undefined;
              if (carrierSpacing) {
                delete carrierSpacing.before;
              }
              const carrierAttrs: ParagraphAttrs = {
                ...(carrierSpacing ? { spacing: carrierSpacing } : {}),
                ...(sourceAttrs?.automaticSpacing?.after === true
                  ? { automaticSpacing: { after: true } }
                  : {}),
                ...(sourceAttrs?.spacingExplicit?.after === true
                  ? { spacingExplicit: { after: true } }
                  : {}),
                ...(sourceAttrs?.hasDirectParagraphFormatting === true
                  ? { hasDirectParagraphFormatting: true }
                  : {}),
                ...(sourceAttrs?.hasDirectParagraphMarkFormatting === true
                  ? { hasDirectParagraphMarkFormatting: true }
                  : {}),
                ...(sourceAttrs?.snapToGrid !== undefined
                  ? { snapToGrid: sourceAttrs.snapToGrid }
                  : {}),
                ...(sourceAttrs?.documentGridLinePitch !== undefined
                  ? { documentGridLinePitch: sourceAttrs.documentGridLinePitch }
                  : {}),
                ...(sourceAttrs?.defaultFontSize !== undefined
                  ? { defaultFontSize: sourceAttrs.defaultFontSize }
                  : {}),
                ...(sourceAttrs?.defaultFontFamily !== undefined
                  ? { defaultFontFamily: sourceAttrs.defaultFontFamily }
                  : {}),
              };
              const carrier: ParagraphBlock = {
                kind: "paragraph",
                id: nextBlockId(),
                runs: [],
                attrs: carrierAttrs,
                pmStart: pos + node.nodeSize,
                pmEnd: pos + node.nodeSize,
              };
              trackedPush(carrier);
            }
          }
          const sectionBreak: SectionBreakBlock = {
            kind: "sectionBreak",
            id: nextBlockId(),
          };
          const breakType = secProps?.sectionStart ?? pmAttrs.sectionBreakType;
          if (breakType) {
            sectionBreak.type = breakType as NonNullable<SectionBreakBlock["type"]>;
          }

          if (secProps) {
            const documentGridLinePitchTwips = resolveDocumentGridLinePitch(secProps.docGrid);
            if (documentGridLinePitchTwips !== undefined) {
              sectionBreak.documentGridLinePitchTwips = documentGridLinePitchTwips;
            }
            // Populate page size
            if (secProps.pageWidth || secProps.pageHeight) {
              sectionBreak.pageSize = {
                w: twipsToPixels(secProps.pageWidth ?? 12_240),
                h: twipsToPixels(secProps.pageHeight ?? 15_840),
              };
            }
            // Populate margins
            if (
              secProps.marginTop !== undefined ||
              secProps.marginBottom !== undefined ||
              secProps.marginLeft !== undefined ||
              secProps.marginRight !== undefined
            ) {
              lastSectionMarginsTwips = {
                top: secProps.marginTop ?? lastSectionMarginsTwips.top,
                bottom: secProps.marginBottom ?? lastSectionMarginsTwips.bottom,
                left: secProps.marginLeft ?? lastSectionMarginsTwips.left,
                right: secProps.marginRight ?? lastSectionMarginsTwips.right,
              };
              sectionBreak.margins = {
                top: twipsToPixels(lastSectionMarginsTwips.top),
                bottom: twipsToPixels(lastSectionMarginsTwips.bottom),
                left: twipsToPixels(lastSectionMarginsTwips.left),
                right: twipsToPixels(lastSectionMarginsTwips.right),
              };
              if (secProps.headerDistance !== undefined) {
                sectionBreak.margins.header = twipsToPixels(secProps.headerDistance);
              }
              if (secProps.footerDistance !== undefined) {
                sectionBreak.margins.footer = twipsToPixels(secProps.footerDistance);
              }
            }
            // Populate columns
            const columns = getColumns(secProps);
            if (columns) {
              sectionBreak.columns = columns;
            }
          }

          trackedPush(sectionBreak);
        }
        break;
      }

      case "table":
        trackedPush(convertTable(node, pos, opts));
        break;

      case "image":
        // Standalone image block (if not inline)
        trackedPush(convertImage(node, pos, opts.pageContentHeight));
        break;

      case "textBox":
        trackedPush(convertTextBoxNode(node, pos, opts));
        break;

      case "horizontalRule":
      case "pageBreak": {
        if (consumedPageBreakPositions.has(pos)) {
          break;
        }
        const pb: PageBreakBlock = {
          kind: "pageBreak",
          id: nextBlockId(),
          pmStart: pos,
          pmEnd: pos + node.nodeSize,
        };
        trackedPush(pb);
        break;
      }
      default:
        break;
    }
  };

  // oxlint-disable-next-line unicorn/no-array-for-each -- ProseMirror Node.forEach
  doc.forEach((node, nodeOffset) => {
    visit(node, offset + nodeOffset);
  });

  reserveLeadingEmptyOutlineHeight(blocks);
  suppressTerminalEmptyParagraphsAfterTable(blocks);
  suppressFinalParagraphInRepeatedEmptySuffix(blocks);
  const mergedBlocks = mergeRunInParagraphs(blocks);
  const griddedBlocks = applySectionDocumentGrid(
    mergedBlocks,
    opts.finalSectionDocumentGridLinePitchTwips,
  );
  return groupParagraphFrames(griddedBlocks, nextBlockId);
}

function applySectionDocumentGrid(
  blocks: FlowBlock[],
  finalLinePitchTwips: number | undefined,
): FlowBlock[] {
  const result = [...blocks];
  let sectionStart = 0;

  const stampSection = (end: number, linePitchTwips: number | undefined): void => {
    if (linePitchTwips === undefined || linePitchTwips <= 0) {
      return;
    }
    const linePitch = twipsToPixels(linePitchTwips);
    for (let index = sectionStart; index < end; index += 1) {
      const block = result[index];
      if (block?.kind !== "paragraph") {
        continue;
      }
      result[index] = {
        ...block,
        attrs: { ...block.attrs, documentGridLinePitch: linePitch },
      };
    }
  };

  for (let index = 0; index < blocks.length; index += 1) {
    const block = blocks[index];
    if (block?.kind !== "sectionBreak") {
      continue;
    }
    stampSection(index, block.documentGridLinePitchTwips);
    sectionStart = index + 1;
  }
  stampSection(blocks.length, finalLinePitchTwips);
  return result;
}

/**
 * Merge consecutive paragraph blocks where the first carries
 * `runInWithNext` (`<w:specVanish/>` on the paragraph mark).
 *
 * Word's run-in heading feature renders the next paragraph inline on
 * the same line, so for layout we collapse the pair into one
 * ParagraphBlock with combined runs. The merged block keeps the first
 * paragraph's attrs (heading formatting, list marker, indent) and
 * extends pmEnd to the second paragraph's range so click-to-position
 * resolution still maps both ranges back to body content.
 *
 * Chains: runInWithNext on the merged block is dropped because the
 * second paragraph's mark wasn't `specVanish`. If a chain of
 * specVanish paragraphs needs collapsing (rare in practice), the loop
 * naturally handles it by re-inspecting the merged block's flag (we
 * preserve runInWithNext only when the second paragraph itself has
 * specVanish).
 */
function sdtGroupStacksEqual(a: SdtGroup[] | undefined, b: SdtGroup[] | undefined): boolean {
  // pmPos is unique per SDT instance within a single toFlowBlocks call, so
  // comparing the pmPos stacks is enough to tell "same membership" vs.
  // "different membership" without copying the rest of the group payload.
  const lenA = a?.length ?? 0;
  const lenB = b?.length ?? 0;
  if (lenA !== lenB) {
    return false;
  }
  if (lenA === 0) {
    return true;
  }
  for (let i = 0; i < lenA; i++) {
    if (a?.[i]?.pmPos !== b?.[i]?.pmPos) {
      return false;
    }
  }
  return true;
}

function mergeRunInParagraphs(blocks: FlowBlock[]): FlowBlock[] {
  const out: FlowBlock[] = [];
  for (let i = 0; i < blocks.length; i++) {
    let current = blocks[i];
    if (!current) {
      continue;
    }
    // Chain merge: keep folding consecutive paragraphs while the
    // *current* (possibly already-merged) block carries
    // `runInWithNext` and the next block is also a paragraph. Per
    // ECMA-376 §17.3.1.32 and Word's behaviour, a sequence of
    // `<w:specVanish/>` paragraphs flows inline through the first
    // body paragraph that lacks it (Codex PR #258 review).
    while (
      current.kind === "paragraph" &&
      (current as ParagraphBlock).attrs?.runInWithNext &&
      i + 1 < blocks.length
    ) {
      const next = blocks[i + 1];
      if (!next || next.kind !== "paragraph") {
        break;
      }
      const a = current as ParagraphBlock;
      const b = next as ParagraphBlock;
      // Stop merging when the two paragraphs sit in different SDT stacks.
      // The merged ParagraphBlock would inherit only `a`'s sdtGroups via
      // spread, so a `<w:specVanish/>` adjacent to a paragraph across an
      // SDT boundary would either claim outside text as part of the SDT
      // or strip SDT membership from inside text — chrome and widget
      // click targets would line up against the wrong content range.
      if (!sdtGroupStacksEqual(a.sdtGroups, b.sdtGroups)) {
        break;
      }
      const mergedAttrs: ParagraphAttrs = { ...a.attrs };
      // Heading typically has no spaceAfter; the body's spaceAfter
      // governs the merged paragraph's trailing gap.
      if (b.attrs?.spacing?.after !== undefined) {
        mergedAttrs.spacing = {
          ...mergedAttrs.spacing,
          after: b.attrs.spacing.after,
        };
      }
      // Carry forward `runInWithNext` only if the *consumed* second
      // paragraph itself was specVanish — the while condition above
      // then triggers another fold against the paragraph after it.
      if (b.attrs?.runInWithNext) {
        mergedAttrs.runInWithNext = true;
      } else {
        delete mergedAttrs.runInWithNext;
      }
      const merged: ParagraphBlock = {
        ...a,
        runs: [...a.runs, ...b.runs],
        attrs: mergedAttrs,
      };
      const mergedPmEnd = b.pmEnd ?? a.pmEnd;
      if (mergedPmEnd !== undefined) {
        merged.pmEnd = mergedPmEnd;
      }
      current = merged;
      i += 1; // consumed `next`; fold further if the merged block still has the flag
    }
    out.push(current);
  }
  return out;
}