renderer.ts

import type {
  ChartDrawing,
  CustomGeometryData,
  DrawingBlock,
  DrawingFragment,
  DrawingGeometry,
  DropCapDescriptor,
  FieldAnnotationRun,
  FlowBlock,
  FlowMode,
  FlowRunLink,
  Fragment,
  GradientFill,
  ImageBlock,
  ImageDrawing,
  ImageFragment,
  ImageHyperlink,
  ImageRun,
  Layout,
  Line,
  LineSegment,
  ListBlock,
  ListItemFragment,
  ListMeasure,
  Measure,
  Page,
  PageMargins,
  ParaFragment,
  ParagraphAttrs,
  ParagraphBlock,
  ParagraphBorder,
  ParagraphMeasure,
  PositionedDrawingGeometry,
  Run,
  SdtMetadata,
  ShapeGroupChild,
  ShapeGroupDrawing,
  ShapeTextContent,
  SolidFillWithAlpha,
  TableAttrs,
  TableBlock,
  TableCellAttrs,
  TableFragment,
  TableMeasure,
  MathRun,
  TextRun,
  TrackedChangeKind,
  TrackedChangesMode,
  VectorShapeDrawing,
  VectorShapeStyle,
  ResolvedLayout,
  ResolvedFragmentItem,
  ResolvedPage,
  ResolvedPaintItem,
  ResolvedTableItem,
  ResolvedImageItem,
  ResolvedDrawingItem,
} from '@superdoc/contracts';
import {
  adjustAvailableWidthForTextIndent,
  calculateJustifySpacing,
  computeLinePmRange,
  getCellSpacingPx,
  normalizeBaselineShift,
  resolveBaseFontSizeForVerticalText,
  shouldApplyJustify,
  SPACE_CHARS,
} from '@superdoc/contracts';
import { toCssFontFamily } from '@superdoc/font-utils';
import { getPresetShapeSvg } from '@superdoc/preset-geometry';
import { encodeTooltip, sanitizeHref } from '@superdoc/url-validation';
import { DOM_CLASS_NAMES } from './constants.js';
import { createChartElement as renderChartToElement } from './chart-renderer.js';
import {
  getRunBooleanProp,
  getRunNumberProp,
  getRunStringProp,
  getRunUnderlineColor,
  getRunUnderlineStyle,
  hashCellBorders,
  hashParagraphBorders,
  hashTableBorders,
} from './paragraph-hash-utils.js';
import { assertFragmentPmPositions, assertPmPositions } from './pm-position-validation.js';
import { createRulerElement, ensureRulerStyles, generateRulerDefinitionFromPx } from './ruler/index.js';
import {
  CLASS_NAMES,
  containerStyles,
  containerStylesHorizontal,
  ensureFieldAnnotationStyles,
  ensureImageSelectionStyles,
  ensureLinkStyles,
  ensurePrintStyles,
  ensureSdtContainerStyles,
  ensureTrackChangeStyles,
  fragmentStyles,
  lineStyles,
  pageStyles,
  spreadStyles,
  type PageStyles,
} from './styles.js';
import { applyAlphaToSVG, applyGradientToSVG, validateHexColor } from './svg-utils.js';
import { renderTableFragment as renderTableFragmentElement } from './table/renderTableFragment.js';
import { applyImageClipPath } from './utils/image-clip-path.js';
import { isMinimalWordLayout as isMinimalWordLayoutShared } from '@superdoc/common/list-marker-utils';
import {
  computeTabWidth,
  resolvePainterListMarkerGeometry,
  resolvePainterListTextStartPx,
} from './utils/marker-helpers.js';
import {
  applySdtContainerStyling,
  getSdtContainerKey,
  shouldRebuildForSdtBoundary,
  type SdtBoundaryOptions,
} from './utils/sdt-helpers.js';
import {
  computeBetweenBorderFlags,
  getFragmentParagraphBorders,
  getFragmentHeight,
  createParagraphDecorationLayers,
  applyParagraphBorderStyles,
  applyParagraphShadingStyles,
  getParagraphBorderBox,
  stampBetweenBorderDataset,
  type BetweenBorderInfo,
} from './features/paragraph-borders/index.js';
import { applyRtlStyles, shouldUseSegmentPositioning } from './features/rtl-paragraph/index.js';
import { convertOmmlToMathml } from './features/math/index.js';

/**
 * Minimal type for WordParagraphLayoutOutput marker data used in rendering.
 * Extracted to avoid dependency on @superdoc/word-layout package.
 */
type WordLayoutMarker = {
  markerText?: string;
  justification?: 'left' | 'right' | 'center';
  gutterWidthPx?: number;
  markerBoxWidthPx?: number;
  suffix?: 'tab' | 'space' | 'nothing';
  /** Pre-calculated X position where the marker should be placed (used in firstLineIndentMode). */
  markerX?: number;
  /** Pre-calculated X position where paragraph text should begin after the marker (used in firstLineIndentMode). */
  textStartX?: number;
  run: {
    fontFamily: string;
    fontSize: number;
    bold?: boolean;
    italic?: boolean;
    color?: string;
    letterSpacing?: number;
    vanish?: boolean;
  };
};

/**
 * Minimal type for wordLayout property used in this renderer.
 *
 * This is a subset of the full WordParagraphLayoutOutput type from @superdoc/word-layout.
 * We extract only the fields needed for rendering to avoid a direct dependency on the
 * word-layout package from the renderer. This allows the renderer to work with any object
 * that provides these properties, maintaining loose coupling between packages.
 *
 * The wordLayout property is attached to ParagraphBlock.attrs during block processing
 * and contains layout metadata needed for proper list marker and indent rendering.
 *
 * @property marker - Optional list marker layout containing text, styling, and positioning info
 * @property indentLeftPx - Left indent in pixels (used for marker positioning calculations)
 * @property firstLineIndentMode - When true, indicates the paragraph uses firstLine indent
 *   pattern (marker at left+firstLine) instead of standard hanging indent (marker at left-hanging).
 *   This flag changes how markers are positioned and how tab spacing is calculated.
 * @property textStartPx - X position where paragraph text should begin (used for tab width calculation)
 * @property tabsPx - Array of explicit tab stop positions in pixels
 */
type MinimalWordLayout = {
  marker?: WordLayoutMarker;
  indentLeftPx?: number;
  /** True for firstLine indent pattern (marker at left+firstLine vs left-hanging). */
  firstLineIndentMode?: boolean;
  /** X position where paragraph text should begin. */
  textStartPx?: number;
  /** Array of explicit tab stop positions in pixels. */
  tabsPx?: number[];
};

type LineEnd = {
  type?: string;
  width?: string;
  length?: string;
};

type LineEnds = {
  head?: LineEnd;
  tail?: LineEnd;
};

type EffectExtent = {
  left: number;
  top: number;
  right: number;
  bottom: number;
};

type VectorShapeDrawingWithEffects = VectorShapeDrawing & {
  lineEnds?: LineEnds;
  effectExtent?: EffectExtent;
};

/**
 * Type guard narrowing to the renderer-local MinimalWordLayout type.
 * Delegates structural validation to the shared isMinimalWordLayout guard.
 */
function isMinimalWordLayout(value: unknown): value is MinimalWordLayout {
  return isMinimalWordLayoutShared(value);
}

/**
 * Layout mode for document rendering.
 * @typedef {('vertical'|'horizontal'|'book')} LayoutMode
 * - 'vertical': Standard page-by-page vertical layout (default)
 * - 'horizontal': Pages arranged horizontally side-by-side
 * - 'book': Book-style layout with facing pages
 */
export type LayoutMode = 'vertical' | 'horizontal' | 'book';
// FlowMode is re-exported from @superdoc/contracts
export type { FlowMode } from '@superdoc/contracts';

/**
 * Interface for position mapping from ProseMirror transactions.
 * Used to efficiently update DOM position attributes without full re-render.
 */
export interface PositionMapping {
  /** Transform a position from old to new document coordinates */
  map(pos: number, bias?: number): number;
  /** Array of step maps - length indicates transaction complexity */
  readonly maps: readonly unknown[];
}

export type RenderedLineInfo = {
  el: HTMLElement;
  top: number;
  height: number;
};

/**
 * Input to `DomPainter.paint()`.
 *
 * `resolvedLayout` is the canonical resolved data. The remaining fields are
 * bridge data carried for internal rendering of non-paragraph fragments
 * (tables, images, drawings) that have not yet been migrated to resolved items.
 */
export type DomPainterInput = {
  resolvedLayout: ResolvedLayout;
  /** Raw Layout for internal fragment access (bridge — will be removed once all fragment types are resolved). */
  sourceLayout: Layout;
  blocks: FlowBlock[];
  measures: Measure[];
  headerBlocks?: FlowBlock[];
  headerMeasures?: Measure[];
  footerBlocks?: FlowBlock[];
  footerMeasures?: Measure[];
};

type OptionalBlockMeasurePair = {
  blocks: FlowBlock[];
  measures: Measure[];
};

type PageDecorationPayload = {
  fragments: Fragment[];
  height: number;
  /** Optional measured content height to aid bottom alignment in footers. */
  contentHeight?: number;
  offset?: number;
  marginLeft?: number;
  // Optional explicit content width (px) for the decoration container
  contentWidth?: number;
  headerFooterRefId?: string;
  sectionType?: string;
  box?: { x: number; y: number; width: number; height: number };
  hitRegion?: { x: number; y: number; width: number; height: number };
};

/**
 * Provider function for page decorations (headers and footers).
 * Called for each page to generate header or footer content.
 *
 * @param {number} pageNumber - The page number (1-indexed)
 * @param {PageMargins} [pageMargins] - Page margin configuration
 * @param {Page} [page] - Full page object from the layout
 * @returns {PageDecorationPayload | null} Decoration payload containing fragments and layout info, or null if no decoration
 */
export type PageDecorationProvider = (
  pageNumber: number,
  pageMargins?: PageMargins,
  page?: Page,
) => PageDecorationPayload | null;

/**
 * Ruler configuration options for per-page rulers.
 */
export type RulerOptions = {
  /** Whether to show rulers on pages (default: false) */
  enabled?: boolean;
  /** Whether rulers are interactive with drag handles (default: false for per-page) */
  interactive?: boolean;
  /** Callback when margin handle drag ends (only used if interactive) */
  onMarginChange?: (side: 'left' | 'right', marginInches: number) => void;
};

type PainterOptions = {
  pageStyles?: PageStyles;
  layoutMode?: LayoutMode;
  flowMode?: FlowMode;
  /** Gap between pages in pixels (default: 24px for vertical, 20px for horizontal) */
  pageGap?: number;
  headerProvider?: PageDecorationProvider;
  footerProvider?: PageDecorationProvider;
  virtualization?: {
    enabled?: boolean;
    window?: number;
    overscan?: number;
    /** Virtualization gap override (defaults to 72px; independent of pageGap). */
    gap?: number;
    paddingTop?: number;
  };
  /** Per-page ruler options */
  ruler?: RulerOptions;
  /** Called with the paint snapshot after each paint cycle completes. */
  onPaintSnapshot?: (snapshot: PaintSnapshot) => void;
};

// BlockLookup lives in the shared types module (single source of truth)
import type { BlockLookupEntry, BlockLookup } from './features/paragraph-borders/types.js';
export type { BlockLookup, BlockLookupEntry };

type FragmentDomState = {
  key: string;
  signature: string;
  fragment: Fragment;
  element: HTMLElement;
  context: FragmentRenderContext;
};

type PageDomState = {
  element: HTMLElement;
  fragments: FragmentDomState[];
};

/**
 * Rendering context passed to fragment renderers containing page metadata.
 * Provides information about the current page position and section for dynamic content like page numbers.
 *
 * @typedef {Object} FragmentRenderContext
 * @property {number} pageNumber - Current page number (1-indexed)
 * @property {number} totalPages - Total number of pages in the document
 * @property {'body'|'header'|'footer'} section - Document section being rendered
 * @property {string} [pageNumberText] - Optional formatted page number text (e.g., "Page 1 of 10")
 */
export type FragmentRenderContext = {
  pageNumber: number;
  totalPages: number;
  section: 'body' | 'header' | 'footer';
  pageNumberText?: string;
  pageIndex?: number;
};

export type PaintSnapshotLineStyle = {
  paddingLeftPx?: number;
  paddingRightPx?: number;
  textIndentPx?: number;
  marginLeftPx?: number;
  marginRightPx?: number;
  leftPx?: number;
  topPx?: number;
  widthPx?: number;
  heightPx?: number;
  display?: string;
  position?: string;
  textAlign?: string;
  justifyContent?: string;
};

export type PaintSnapshotMarkerStyle = {
  text?: string;
  leftPx?: number;
  widthPx?: number;
  paddingRightPx?: number;
  display?: string;
  position?: string;
  textAlign?: string;
  fontWeight?: string;
  fontStyle?: string;
  color?: string;
};

export type PaintSnapshotTabStyle = {
  widthPx?: number;
  leftPx?: number;
  position?: string;
  borderBottom?: string;
};

export type PaintSnapshotAnnotationEntity = {
  element: HTMLElement;
  pageIndex: number;
  pmStart?: number;
  pmEnd?: number;
  fieldId?: string;
  fieldType?: string;
  type?: string;
};

export type PaintSnapshotStructuredContentBlockEntity = {
  element: HTMLElement;
  pageIndex: number;
  sdtId: string;
  pmStart?: number;
  pmEnd?: number;
};

export type PaintSnapshotStructuredContentInlineEntity = {
  element: HTMLElement;
  pageIndex: number;
  sdtId: string;
  pmStart?: number;
  pmEnd?: number;
};

export type PaintSnapshotImageEntity = {
  element: HTMLElement;
  pageIndex: number;
  kind: 'inline' | 'fragment';
  pmStart?: number;
  pmEnd?: number;
  blockId?: string;
};

export type PaintSnapshotEntities = {
  annotations: PaintSnapshotAnnotationEntity[];
  structuredContentBlocks: PaintSnapshotStructuredContentBlockEntity[];
  structuredContentInlines: PaintSnapshotStructuredContentInlineEntity[];
  images: PaintSnapshotImageEntity[];
};

export type PaintSnapshotLine = {
  index: number;
  inTableFragment: boolean;
  inTableParagraph: boolean;
  style: PaintSnapshotLineStyle;
  markers?: PaintSnapshotMarkerStyle[];
  tabs?: PaintSnapshotTabStyle[];
};

export type PaintSnapshotPage = {
  index: number;
  pageNumber?: number;
  lineCount: number;
  lines: PaintSnapshotLine[];
};

export type PaintSnapshot = {
  formatVersion: 1;
  pageCount: number;
  lineCount: number;
  markerCount: number;
  tabCount: number;
  pages: PaintSnapshotPage[];
  entities: PaintSnapshotEntities;
};

type PaintSnapshotPageBuilder = {
  index: number;
  pageNumber: number | null;
  lineCount: number;
  lines: PaintSnapshotLine[];
};

type PaintSnapshotBuilder = {
  formatVersion: 1;
  lineCount: number;
  markerCount: number;
  tabCount: number;
  pages: PaintSnapshotPageBuilder[];
};

type PaintSnapshotCaptureOptions = {
  inTableFragment?: boolean;
  inTableParagraph?: boolean;
  wrapperEl?: HTMLElement;
};

function roundSnapshotMetric(value: number): number | null {
  if (!Number.isFinite(value)) return null;
  return Math.round(value * 1000) / 1000;
}

function readSnapshotPxMetric(styleValue: string | null | undefined): number | null {
  if (typeof styleValue !== 'string' || styleValue.length === 0) return null;
  const parsed = Number.parseFloat(styleValue);
  return Number.isFinite(parsed) ? roundSnapshotMetric(parsed) : null;
}

function readSnapshotStyleValue(styleValue: string | null | undefined): string | null {
  if (typeof styleValue !== 'string' || styleValue.length === 0) return null;
  return styleValue;
}

function createEmptyPaintSnapshotEntities(): PaintSnapshotEntities {
  return {
    annotations: [],
    structuredContentBlocks: [],
    structuredContentInlines: [],
    images: [],
  };
}

function readSnapshotDatasetNumber(value: string | null | undefined): number | null {
  if (typeof value !== 'string' || value.length === 0) return null;
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

function resolveSnapshotPageIndex(element: HTMLElement): number | null {
  const pageEl = element.closest(`.${DOM_CLASS_NAMES.PAGE}`) as HTMLElement | null;
  if (!pageEl) return null;
  return readSnapshotDatasetNumber(pageEl.dataset.pageIndex);
}

function compactSnapshotObject<T extends Record<string, unknown>>(input: T): T {
  const out = {} as T;
  for (const [key, value] of Object.entries(input)) {
    if (value == null) continue;
    if (Array.isArray(value) && value.length === 0) continue;
    (out as Record<string, unknown>)[key] = value;
  }
  return out;
}

function shouldIncludeInlineImageSnapshotElement(element: HTMLElement): boolean {
  if (element.classList.contains(DOM_CLASS_NAMES.INLINE_IMAGE_CLIP_WRAPPER)) {
    return true;
  }

  if (!element.classList.contains(DOM_CLASS_NAMES.INLINE_IMAGE)) {
    return false;
  }

  return !element.closest(`.${DOM_CLASS_NAMES.INLINE_IMAGE_CLIP_WRAPPER}`);
}

function collectPaintSnapshotEntitiesFromDomRoot(rootEl: HTMLElement): PaintSnapshotEntities {
  const entities = createEmptyPaintSnapshotEntities();

  const annotationElements = Array.from(
    rootEl.querySelectorAll<HTMLElement>(`.${DOM_CLASS_NAMES.ANNOTATION}[data-pm-start]`),
  );
  for (const element of annotationElements) {
    const pageIndex = resolveSnapshotPageIndex(element);
    if (pageIndex == null) continue;

    entities.annotations.push(
      compactSnapshotObject({
        element,
        pageIndex,
        pmStart: readSnapshotDatasetNumber(element.dataset.pmStart),
        pmEnd: readSnapshotDatasetNumber(element.dataset.pmEnd),
        fieldId: element.dataset.fieldId || null,
        fieldType: element.dataset.fieldType || null,
        type: element.dataset.type || null,
      }) as PaintSnapshotAnnotationEntity,
    );
  }

  const blockSdtElements = Array.from(
    rootEl.querySelectorAll<HTMLElement>(`.${DOM_CLASS_NAMES.BLOCK_SDT}[data-sdt-id]`),
  );
  for (const element of blockSdtElements) {
    const pageIndex = resolveSnapshotPageIndex(element);
    const sdtId = element.dataset.sdtId;
    if (pageIndex == null || !sdtId) continue;

    entities.structuredContentBlocks.push(
      compactSnapshotObject({
        element,
        pageIndex,
        sdtId,
        pmStart: readSnapshotDatasetNumber(element.dataset.pmStart),
        pmEnd: readSnapshotDatasetNumber(element.dataset.pmEnd),
      }) as PaintSnapshotStructuredContentBlockEntity,
    );
  }

  const inlineSdtElements = Array.from(
    rootEl.querySelectorAll<HTMLElement>(`.${DOM_CLASS_NAMES.INLINE_SDT_WRAPPER}[data-sdt-id]`),
  );
  for (const element of inlineSdtElements) {
    const pageIndex = resolveSnapshotPageIndex(element);
    const sdtId = element.dataset.sdtId;
    if (pageIndex == null || !sdtId) continue;

    entities.structuredContentInlines.push(
      compactSnapshotObject({
        element,
        pageIndex,
        sdtId,
        pmStart: readSnapshotDatasetNumber(element.dataset.pmStart),
        pmEnd: readSnapshotDatasetNumber(element.dataset.pmEnd),
      }) as PaintSnapshotStructuredContentInlineEntity,
    );
  }

  const inlineImageElements = Array.from(
    rootEl.querySelectorAll<HTMLElement>(
      `.${DOM_CLASS_NAMES.INLINE_IMAGE_CLIP_WRAPPER}[data-pm-start], .${DOM_CLASS_NAMES.INLINE_IMAGE}[data-pm-start]`,
    ),
  );
  for (const element of inlineImageElements) {
    if (!shouldIncludeInlineImageSnapshotElement(element)) continue;

    const pageIndex = resolveSnapshotPageIndex(element);
    if (pageIndex == null) continue;

    entities.images.push(
      compactSnapshotObject({
        element,
        pageIndex,
        kind: 'inline',
        pmStart: readSnapshotDatasetNumber(element.dataset.pmStart),
        pmEnd: readSnapshotDatasetNumber(element.dataset.pmEnd),
      }) as PaintSnapshotImageEntity,
    );
  }

  const fragmentImageElements = Array.from(
    rootEl.querySelectorAll<HTMLElement>(`.${DOM_CLASS_NAMES.IMAGE_FRAGMENT}[data-pm-start]`),
  );
  for (const element of fragmentImageElements) {
    const pageIndex = resolveSnapshotPageIndex(element);
    if (pageIndex == null) continue;

    entities.images.push(
      compactSnapshotObject({
        element,
        pageIndex,
        kind: 'fragment',
        pmStart: readSnapshotDatasetNumber(element.dataset.pmStart),
        pmEnd: readSnapshotDatasetNumber(element.dataset.pmEnd),
        blockId: element.getAttribute('data-sd-block-id'),
      }) as PaintSnapshotImageEntity,
    );
  }

  return entities;
}

function snapshotLineStyleFromElement(lineEl: HTMLElement): PaintSnapshotLineStyle {
  const style = lineEl?.style;
  if (!style) return {};
  return compactSnapshotObject({
    paddingLeftPx: readSnapshotPxMetric(style.paddingLeft),
    paddingRightPx: readSnapshotPxMetric(style.paddingRight),
    textIndentPx: readSnapshotPxMetric(style.textIndent),
    marginLeftPx: readSnapshotPxMetric(style.marginLeft),
    marginRightPx: readSnapshotPxMetric(style.marginRight),
    leftPx: readSnapshotPxMetric(style.left),
    topPx: readSnapshotPxMetric(style.top),
    widthPx: readSnapshotPxMetric(style.width),
    heightPx: readSnapshotPxMetric(style.height),
    display: readSnapshotStyleValue(style.display),
    position: readSnapshotStyleValue(style.position),
    textAlign: readSnapshotStyleValue(style.textAlign),
    justifyContent: readSnapshotStyleValue(style.justifyContent),
  }) as PaintSnapshotLineStyle;
}

function applyWrapperMarginsToSnapshotStyle(
  lineStyle: PaintSnapshotLineStyle,
  wrapperEl?: HTMLElement,
): PaintSnapshotLineStyle {
  if (!wrapperEl?.style) return lineStyle;

  return compactSnapshotObject({
    ...lineStyle,
    marginLeftPx: readSnapshotPxMetric(wrapperEl.style.marginLeft) ?? lineStyle.marginLeftPx,
    marginRightPx: readSnapshotPxMetric(wrapperEl.style.marginRight) ?? lineStyle.marginRightPx,
  }) as PaintSnapshotLineStyle;
}

function snapshotMarkerStyleFromElement(markerEl: HTMLElement): PaintSnapshotMarkerStyle {
  const style = markerEl?.style;
  if (!style) return {};
  return compactSnapshotObject({
    text: markerEl?.textContent ?? '',
    leftPx: readSnapshotPxMetric(style.left),
    widthPx: readSnapshotPxMetric(style.width),
    paddingRightPx: readSnapshotPxMetric(style.paddingRight),
    display: readSnapshotStyleValue(style.display),
    position: readSnapshotStyleValue(style.position),
    textAlign: readSnapshotStyleValue(style.textAlign),
    fontWeight: readSnapshotStyleValue(style.fontWeight),
    fontStyle: readSnapshotStyleValue(style.fontStyle),
    color: readSnapshotStyleValue(style.color),
  }) as PaintSnapshotMarkerStyle;
}

function collectLineMarkersForSnapshot(lineEl: HTMLElement): PaintSnapshotMarkerStyle[] {
  const markers: PaintSnapshotMarkerStyle[] = [];
  const parent = lineEl?.parentElement;
  if (parent) {
    for (const child of Array.from(parent.children)) {
      if (!(child instanceof HTMLElement)) continue;
      if (!child.classList.contains('superdoc-paragraph-marker')) continue;
      markers.push(snapshotMarkerStyleFromElement(child));
    }
  }

  const inlineMarkers = lineEl?.querySelectorAll?.('.superdoc-paragraph-marker') ?? [];
  for (const markerEl of Array.from(inlineMarkers)) {
    if (!(markerEl instanceof HTMLElement)) continue;
    const markerStyle = snapshotMarkerStyleFromElement(markerEl);
    const markerText = markerEl.textContent ?? '';
    const markerLeft = readSnapshotPxMetric(markerEl.style.left);
    if (markers.some((existing) => existing.text === markerText && existing.leftPx === markerLeft)) {
      continue;
    }
    markers.push(markerStyle);
  }

  return markers;
}

function collectLineTabsForSnapshot(lineEl: HTMLElement): PaintSnapshotTabStyle[] {
  const tabs: PaintSnapshotTabStyle[] = [];
  const tabElements = lineEl?.querySelectorAll?.('.superdoc-tab') ?? [];
  for (const tabEl of Array.from(tabElements)) {
    if (!(tabEl instanceof HTMLElement)) continue;
    tabs.push(
      compactSnapshotObject({
        widthPx: readSnapshotPxMetric(tabEl.style.width),
        leftPx: readSnapshotPxMetric(tabEl.style.left),
        position: readSnapshotStyleValue(tabEl.style.position),
        borderBottom: readSnapshotStyleValue(tabEl.style.borderBottom),
      }) as PaintSnapshotTabStyle,
    );
  }
  return tabs;
}

const LIST_MARKER_GAP = 8;
/**
 * Default page height in pixels (11 inches at 96 DPI).
 * Used as a fallback when page size information is not available for ruler rendering.
 */
const DEFAULT_PAGE_HEIGHT_PX = 1056;
/** Default gap used when virtualization is enabled (kept in sync with PresentationEditor layout defaults). */
const DEFAULT_VIRTUALIZED_PAGE_GAP = 72;
// Comment highlight color tokens moved to CommentHighlightDecorator (super-editor).

type LinkRenderData = {
  href?: string;
  target?: string;
  rel?: string;
  tooltip?: string | null;
  dataset?: Record<string, string>;
  blocked: boolean;
};

const LINK_DATASET_KEYS = {
  blocked: 'linkBlocked',
  docLocation: 'linkDocLocation',
  history: 'linkHistory',
  rId: 'linkRid',
  truncated: 'linkTooltipTruncated',
} as const;

const MAX_HREF_LENGTH = 2048;

const SAFE_ANCHOR_PATTERN = /^[A-Za-z0-9._-]+$/;

/**
 * Maximum allowed length for data URLs (10MB).
 * Prevents denial of service attacks from extremely large embedded images.
 */
const MAX_DATA_URL_LENGTH = 10 * 1024 * 1024; // 10MB

/**
 * Regular expression to validate data URL format for images.
 * Only allows common, safe image MIME types with base64 encoding.
 * Prevents XSS and malformed data URL attacks.
 */
const VALID_IMAGE_DATA_URL = /^data:image\/(png|jpeg|jpg|gif|svg\+xml|webp|bmp|ico|tiff?);base64,/i;

/**
 * Maximum resize multiplier for image metadata.
 * Images can be resized up to 3x their original dimensions.
 */
const MAX_RESIZE_MULTIPLIER = 3;

/**
 * Fallback maximum dimension for image resizing when original size is small.
 * Ensures images can be resized to at least 1000px even if original is smaller.
 */
const FALLBACK_MAX_DIMENSION = 1000;

/**
 * Minimum image dimension in pixels.
 * Ensures images remain visible and interactive during resizing.
 */
const MIN_IMAGE_DIMENSION = 20;

/**
 * Pattern to detect ambiguous link text that doesn't convey destination (WCAG 2.4.4).
 * Matches common generic phrases like "click here", "read more", etc.
 */
const AMBIGUOUS_LINK_PATTERNS = /^(click here|read more|more|link|here|this|download|view)$/i;

/**
 * Hyperlink rendering metrics for observability.
 * Tracks sanitization, blocking, and security-related events.
 */
const linkMetrics = {
  sanitized: 0,
  blocked: 0,
  invalidProtocol: 0,
  homographWarnings: 0,

  reset() {
    this.sanitized = 0;
    this.blocked = 0;
    this.invalidProtocol = 0;
    this.homographWarnings = 0;
  },

  getMetrics() {
    return {
      'hyperlink.sanitized.count': this.sanitized,
      'hyperlink.blocked.count': this.blocked,
      'hyperlink.invalid_protocol.count': this.invalidProtocol,
      'hyperlink.homograph_warnings.count': this.homographWarnings,
    };
  },
};

// Export for testing/monitoring
export { linkMetrics };

const TRACK_CHANGE_BASE_CLASS: Record<TrackedChangeKind, string> = {
  insert: 'track-insert-dec',
  delete: 'track-delete-dec',
  format: 'track-format-dec',
};
// TRACK_CHANGE_FOCUSED_CLASS moved to CommentHighlightDecorator (super-editor).

const TRACK_CHANGE_MODIFIER_CLASS: Record<TrackedChangeKind, Record<TrackedChangesMode, string | undefined>> = {
  insert: {
    review: 'highlighted',
    original: 'hidden',
    final: 'normal',
    off: undefined,
  },
  delete: {
    review: 'highlighted',
    original: 'normal',
    final: 'hidden',
    off: undefined,
  },
  format: {
    review: 'highlighted',
    original: 'before',
    final: 'normal',
    off: undefined,
  },
};

type TrackedChangesRenderConfig = {
  mode: TrackedChangesMode;
  enabled: boolean;
};

/**
 * Sanitize a URL to prevent XSS attacks.
 * Only allows http, https, mailto, tel, and internal anchors.
 *
 * @param href - The URL to sanitize
 * @returns Sanitized URL or null if blocked
 */
export function sanitizeUrl(href: string): string | null {
  if (typeof href !== 'string') return null;
  const sanitized = sanitizeHref(href);
  return sanitized?.href ?? null;
}

const LINK_TARGET_SET = new Set(['_blank', '_self', '_parent', '_top']);

/**
 * Normalize and validate an anchor fragment identifier for use in hyperlinks.
 * Strips leading '#' if present and validates against safe character pattern.
 *
 * @param value - Raw anchor string (with or without leading '#')
 * @returns Normalized anchor with leading '#' (e.g., '#section-1'), or null if invalid
 *
 * @remarks
 * SECURITY: Only allows safe characters (A-Z, a-z, 0-9, ., _, -) to prevent HTML attribute injection.
 * Rejects characters like quotes, angle brackets, colons, and spaces that could break HTML structure
 * or enable XSS attacks when used in href attributes.
 *
 * @example
 * normalizeAnchor('section-1') // Returns: '#section-1'
 * normalizeAnchor('#bookmark') // Returns: '#bookmark'
 * normalizeAnchor('unsafe<script>') // Returns: null
 * normalizeAnchor('  whitespace  ') // Returns: null
 */
const normalizeAnchor = (value: string | null | undefined): string | null => {
  if (typeof value !== 'string') return null;
  const trimmed = value.trim();
  if (!trimmed) return null;

  // Remove leading # if present, then validate
  const anchor = trimmed.startsWith('#') ? trimmed.slice(1) : trimmed;

  // SECURITY: Only allow safe characters to prevent attribute injection
  // Rejects characters like quotes, angle brackets, spaces that could break HTML
  if (!SAFE_ANCHOR_PATTERN.test(anchor)) {
    return null;
  }

  return `#${anchor}`;
};

/**
 * Check if a fragment string contains only safe anchor characters.
 * Safe characters are alphanumeric, dots, underscores, and hyphens.
 *
 * @param {string} fragment - Fragment to validate
 * @returns {boolean} True if fragment matches safe pattern
 * @private
 */
const isValidSafeFragment = (fragment: string): boolean => {
  return SAFE_ANCHOR_PATTERN.test(fragment);
};

type ImageFilterSource = Pick<ImageBlock, 'grayscale' | 'gain' | 'blacklevel' | 'lum'>;

const clampLumUnit = (value: number): number => {
  return Math.max(-100000, Math.min(100000, value));
};

const parseVmlFixedFraction = (value: string | number | undefined): number | null => {
  if (typeof value === 'number' && Number.isFinite(value)) {
    return value;
  }
  if (typeof value !== 'string' || value.length === 0) {
    return null;
  }

  if (value.endsWith('f')) {
    const raw = Number.parseInt(value.slice(0, -1), 10);
    return Number.isFinite(raw) ? raw / 65536 : null;
  }

  const parsed = Number.parseFloat(value);
  return Number.isFinite(parsed) ? parsed : null;
};

const buildImageFilters = (source: ImageFilterSource): string[] => {
  const filters: string[] = [];

  if (source.grayscale) {
    filters.push('grayscale(100%)');
  }

  if (source.gain != null || source.blacklevel != null) {
    const gain = parseVmlFixedFraction(source.gain);
    const blacklevel = parseVmlFixedFraction(source.blacklevel);

    if (gain != null) {
      const contrast = Math.max(0, gain);
      if (contrast > 0) {
        filters.push(`contrast(${contrast})`);
      }
    }

    if (blacklevel != null) {
      // CSS has no black-point control, so approximate VML blacklevel with a linear
      // brightness shift using the same 0..32767 range Word's watermark UI uses.
      const brightness = Math.max(0, 1 + blacklevel * (65536 / 32767));
      if (brightness > 0) {
        filters.push(`brightness(${brightness})`);
      }
    }
  }

  if (source.lum) {
    // a:lum uses ST_FixedPercentage values expressed in thousandths of a percent.
    // Convert those percentage deltas into CSS filter multipliers.
    const contrastValue = typeof source.lum.contrast === 'number' ? clampLumUnit(source.lum.contrast) : null;
    const brightValue = typeof source.lum.bright === 'number' ? clampLumUnit(source.lum.bright) : null;

    if (contrastValue != null) {
      const contrast = Math.max(0, 1 + contrastValue / 100000);
      if (contrast >= 0) {
        filters.push(`contrast(${contrast})`);
      }
    }

    if (brightValue != null) {
      const brightness = Math.max(0, 1 + brightValue / 100000);
      if (brightness >= 0) {
        filters.push(`brightness(${brightness})`);
      }
    }
  }

  return filters;
};

/**
 * URL-encode a fragment string for use in a URL hash.
 * Returns null if encoding fails (rare edge case).
 *
 * @param {string} fragment - Fragment to encode
 * @returns {string | null} Encoded fragment or null if encoding fails
 * @private
 */
const encodeFragment = (fragment: string): string | null => {
  try {
    return encodeURIComponent(fragment);
  } catch {
    return null;
  }
};

/**
 * Append a document location fragment to an href.
 * CRITICAL FIX: URL-encode unsafe characters instead of destroying the entire href.
 *
 * @param href - Base URL or null
 * @param docLocation - Fragment identifier to append
 * @returns Combined URL with fragment, or original href if fragment is invalid
 */
const appendDocLocation = (href: string | null, docLocation?: string | null): string | null => {
  if (!docLocation?.trim()) return href;

  const fragment = docLocation.trim();
  if (href?.includes('#')) return href;

  const encoded = isValidSafeFragment(fragment) ? fragment : encodeFragment(fragment);

  if (!encoded) return href;
  return href ? `${href}#${encoded}` : `#${encoded}`;
};

/**
 * Build HTML data-* attributes object from hyperlink metadata for version 2 links.
 * Extracts relationship ID, document location fragment, and history preferences from link object.
 *
 * @param link - Flow run link object containing hyperlink metadata
 * @returns Record of data attribute keys and string values to be applied to anchor element
 *
 * @remarks
 * Only processes version 2 links (Office Open XML format). Version 1 links return empty object.
 * All dataset values are converted to strings for DOM compatibility.
 *
 * @example
 * buildLinkDataset({
 *   version: 2,
 *   rId: 'rId5',
 *   docLocation: 'bookmark1',
 *   history: true
 * })
 * // Returns: { rId: 'rId5', docLocation: 'bookmark1', history: 'true' }
 */
const buildLinkDataset = (link: FlowRunLink): Record<string, string> => {
  const dataset: Record<string, string> = {};
  if (link.version === 2) {
    if (link.rId) dataset[LINK_DATASET_KEYS.rId] = link.rId;
    if (link.docLocation) dataset[LINK_DATASET_KEYS.docLocation] = link.docLocation;
    if (typeof link.history === 'boolean') dataset[LINK_DATASET_KEYS.history] = String(link.history);
  }
  return dataset;
};

/**
 * Resolve the appropriate target attribute for a hyperlink anchor element.
 * Validates user-specified targets and auto-sets '_blank' for external HTTP(S) links.
 *
 * @param link - Flow run link object potentially containing target preference
 * @param sanitized - Sanitized URL metadata containing protocol information, or null if sanitization failed
 * @returns Valid target string ('_blank', '_self', '_parent', '_top') or undefined if not applicable
 *
 * @remarks
 * Target resolution follows this priority:
 * 1. If link.target is specified and valid (in LINK_TARGET_SET), use it
 * 2. If URL is external (http/https protocol), default to '_blank' for security
 * 3. Otherwise, return undefined (browser default behavior)
 *
 * @example
 * resolveLinkTarget(
 *   { target: '_self' },
 *   { protocol: 'https', href: 'https://example.com', isExternal: true }
 * ) // Returns: '_self' (user preference honored)
 *
 * resolveLinkTarget(
 *   {},
 *   { protocol: 'https', href: 'https://example.com', isExternal: true }
 * ) // Returns: '_blank' (external link default)
 */
const resolveLinkTarget = (
  link: FlowRunLink,
  sanitized?: ReturnType<typeof sanitizeHref> | null,
): string | undefined => {
  if (link.target && LINK_TARGET_SET.has(link.target)) {
    return link.target;
  }
  if (sanitized && (sanitized.protocol === 'http' || sanitized.protocol === 'https')) {
    return '_blank';
  }
  return undefined;
};

/**
 * Resolve the rel attribute value for a hyperlink, combining user-specified relationships
 * with security-critical values for external links.
 *
 * @param link - Flow run link object potentially containing rel preference (space-separated string)
 * @param target - Resolved target attribute value (e.g., '_blank', '_self')
 * @returns Space-separated rel values, or undefined if no rel values apply
 *
 * @remarks
 * SECURITY: Automatically adds 'noopener noreferrer' for target='_blank' links to prevent:
 * - Tabnabbing attacks (window.opener access)
 * - Referrer leakage to external sites
 *
 * User-specified rel values are parsed from link.rel (whitespace-separated string),
 * deduplicated, and merged with security values.
 *
 * @example
 * resolveLinkRel(
 *   { rel: 'nofollow external' },
 *   '_blank'
 * ) // Returns: 'nofollow external noopener noreferrer'
 *
 * resolveLinkRel(
 *   { rel: 'nofollow  noopener  ' },
 *   '_blank'
 * ) // Returns: 'nofollow noopener noreferrer' (deduplicated)
 *
 * resolveLinkRel({}, '_self') // Returns: undefined
 */
const resolveLinkRel = (link: FlowRunLink, target?: string): string | undefined => {
  const relValues = new Set<string>();
  if (typeof link.rel === 'string' && link.rel.trim()) {
    link.rel
      .trim()
      .split(/\s+/)
      .forEach((value) => {
        if (value) relValues.add(value);
      });
  }
  if (target === '_blank') {
    relValues.add('noopener');
    relValues.add('noreferrer');
  }
  if (relValues.size === 0) {
    return undefined;
  }
  return Array.from(relValues).join(' ');
};

/**
 * Apply data-* attributes to an HTML element from a dataset object.
 * Safely assigns dataset properties while filtering out null/undefined values.
 *
 * @param element - Target HTML element to receive data attributes
 * @param dataset - Object mapping data attribute keys to string values
 *
 * @remarks
 * Uses the element.dataset API which automatically prefixes keys with 'data-'.
 * Only assigns non-null, non-undefined values to prevent empty attributes.
 *
 * @example
 * const anchor = document.createElement('a');
 * applyLinkDataset(anchor, {
 *   rId: 'rId5',
 *   docLocation: 'bookmark1',
 *   history: 'true'
 * });
 * // Resulting HTML: <a data-r-id="rId5" data-doc-location="bookmark1" data-history="true"></a>
 */
const applyLinkDataset = (element: HTMLElement, dataset?: Record<string, string>): void => {
  if (!dataset) return;
  Object.entries(dataset).forEach(([key, value]) => {
    if (value != null) {
      element.dataset[key] = value;
    }
  });
};

/**
 * DOM-based document painter that renders layout fragments to HTML elements.
 * Manages page rendering, virtualization, headers/footers, and incremental updates.
 *
 * @class DomPainter
 *
 * @remarks
 * The DomPainter is responsible for:
 * - Rendering layout fragments (paragraphs, lists, images, tables, drawings) to DOM elements
 * - Managing page-level DOM structure and styling
 * - Providing virtualization for large documents (vertical mode only)
 * - Handling headers and footers via PageDecorationProvider
 * - Incremental re-rendering when only specific blocks change
 * - Hyperlink rendering with security sanitization and accessibility
 *
 * @example
 * ```typescript
 * const painter = new DomPainter(blocks, measures, {
 *   layoutMode: 'vertical',
 *   pageStyles: { width: '8.5in', height: '11in' }
 * });
 * painter.mount(document.getElementById('editor-container'));
 * painter.render(layout);
 * ```
 */
export class DomPainter {
  private blockLookup: BlockLookup;
  private readonly options: PainterOptions;
  private mount: HTMLElement | null = null;
  private doc: Document | null = null;
  private pageStates: PageDomState[] = [];
  private currentLayout: Layout | null = null;
  private changedBlocks = new Set<string>();
  private readonly layoutMode: LayoutMode;
  private readonly isSemanticFlow: boolean;
  private headerProvider?: PageDecorationProvider;
  private footerProvider?: PageDecorationProvider;
  private totalPages = 0;
  private linkIdCounter = 0; // Counter for generating unique link IDs
  private sdtLabelsRendered = new Set<string>(); // Tracks SDT labels rendered across pages

  /**
   * WeakMap storing tooltip data for hyperlink elements before DOM insertion.
   * Uses WeakMap to prevent memory leaks - entries are automatically garbage collected
   * when the corresponding element is removed from memory.
   * @private
   */
  private pendingTooltips = new WeakMap<HTMLElement, string>();
  // Page gap for normal (non-virtualized) rendering
  private pageGap = 24; // px, default for vertical mode
  // Virtualization state (vertical mode only)
  private virtualEnabled = false;
  private virtualWindow = 5;
  private virtualOverscan = 0;
  private virtualGap = DEFAULT_VIRTUALIZED_PAGE_GAP; // px, default for virtualized mode
  private virtualPaddingTop: number | null = null; // px; computed from mount if not provided
  private topSpacerEl: HTMLElement | null = null;
  private bottomSpacerEl: HTMLElement | null = null;
  private virtualPagesEl: HTMLElement | null = null;
  private virtualGapSpacers: HTMLElement[] = [];
  private virtualPinnedPages: number[] = [];
  private virtualMountedKey = '';
  private pageIndexToState: Map<number, PageDomState> = new Map();
  private virtualHeights: number[] = [];
  private virtualOffsets: number[] = [];
  private virtualStart = 0;
  private virtualEnd = -1;
  private layoutVersion = 0;
  private layoutEpoch = 0;
  private processedLayoutVersion = -1;
  /** Current transaction mapping for position updates (null if no mapping or complex transaction) */
  private currentMapping: PositionMapping | null = null;
  private onScrollHandler: ((e: Event) => void) | null = null;
  private onWindowScrollHandler: ((e: Event) => void) | null = null;
  private onResizeHandler: ((e: Event) => void) | null = null;
  /** CSS zoom/scale factor applied to the mount element via transform: scale(). Defaults to 1 (no zoom). */
  private zoomFactor = 1;
  /**
   * External scroll container (an ancestor element with overflow-y: auto/scroll).
   * When set, updateVirtualWindow() uses this element's position to compute scrollY
   * relative to the scroll container instead of relative to the browser viewport.
   * This fixes the scroll offset calculation when SuperDoc is mounted inside a
   * wrapper div that owns scrolling rather than the window.
   */
  private scrollContainer: HTMLElement | null = null;
  /**
   * Cached offset (in px) from the scroll container's content top to the mount's top.
   * Used for stable scrollY calculation that avoids feedback loops from spacer DOM mutations.
   * Invalidated when the mount, scroll container, or zoom changes.
   */
  private scrollContainerMountOffset: number | null = null;
  private paintSnapshotBuilder: PaintSnapshotBuilder | null = null;
  private lastPaintSnapshot: PaintSnapshot | null = null;
  private onPaintSnapshotCallback: ((snapshot: PaintSnapshot) => void) | null = null;
  private mountedPageIndices: number[] = [];
  /** Resolved layout for the next-gen paint pipeline. */
  private resolvedLayout: ResolvedLayout | null = null;

  constructor(options: PainterOptions = {}) {
    this.options = options;
    this.layoutMode = options.layoutMode ?? 'vertical';
    this.isSemanticFlow = (options.flowMode ?? 'paginated') === 'semantic';
    this.blockLookup = new Map();
    this.headerProvider = options.headerProvider;
    this.footerProvider = options.footerProvider;

    // Initialize page gap (defaults: 24px vertical, 20px horizontal)
    const defaultGap = this.layoutMode === 'horizontal' ? 20 : 24;
    this.pageGap =
      typeof options.pageGap === 'number' && Number.isFinite(options.pageGap)
        ? Math.max(0, options.pageGap)
        : defaultGap;

    // Initialize virtualization config (feature-flagged)
    if (!this.isSemanticFlow && this.layoutMode === 'vertical' && options.virtualization?.enabled) {
      this.virtualEnabled = true;
      this.virtualWindow = Math.max(1, options.virtualization.window ?? 5);
      this.virtualOverscan = Math.max(0, options.virtualization.overscan ?? 0);
      // Virtualization gap: use explicit virtualization.gap if provided,
      // otherwise default to legacy virtualized gap (72px).
      const maybeGap = options.virtualization.gap;
      if (typeof maybeGap === 'number' && Number.isFinite(maybeGap)) {
        this.virtualGap = Math.max(0, maybeGap);
      } else {
        this.virtualGap = DEFAULT_VIRTUALIZED_PAGE_GAP;
      }
      if (typeof options.virtualization.paddingTop === 'number' && Number.isFinite(options.virtualization.paddingTop)) {
        this.virtualPaddingTop = Math.max(0, options.virtualization.paddingTop);
      }
    }

    this.onPaintSnapshotCallback = options.onPaintSnapshot ?? null;
  }

  public setProviders(header?: PageDecorationProvider, footer?: PageDecorationProvider): void {
    this.headerProvider = header;
    this.footerProvider = footer;
  }

  /**
   * Pins specific page indices so they remain mounted when virtualization is enabled.
   *
   * Used by selection/drag logic to ensure endpoints can be resolved via DOM
   * even when they fall outside the current scroll window.
   */
  public setVirtualizationPins(pageIndices: number[] | null | undefined): void {
    const next = Array.from(new Set((pageIndices ?? []).filter((n) => Number.isInteger(n)))).sort((a, b) => a - b);
    this.virtualPinnedPages = next;
    if (this.virtualEnabled && this.mount) {
      this.updateVirtualWindow();
    }
  }

  /**
   * Sets the CSS zoom/scale factor applied to the mount element.
   *
   * When the mount element has `transform: scale(zoom)`, getBoundingClientRect()
   * returns screen-space coordinates (scaled), but internal layout offsets are in
   * unscaled layout space. This factor is used to convert between the two spaces
   * during virtualization window calculations.
   *
   * @param zoom - The zoom/scale factor (e.g., 0.75 for 75% zoom). Defaults to 1.
   */
  public setZoom(zoom: number): void {
    const next = typeof zoom === 'number' && Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
    if (next !== this.zoomFactor) {
      this.zoomFactor = next;
      this.scrollContainerMountOffset = null; // Invalidate on zoom change
      if (this.virtualEnabled && this.mount) {
        this.updateVirtualWindow();
      }
    }
  }

  /**
   * Sets the external scroll container element.
   *
   * When the scroll container is an ancestor element (e.g., a wrapper div with
   * overflow-y: auto), the default scrollY calculation using mount.getBoundingClientRect()
   * relative to the viewport produces an offset equal to the scroll container's distance
   * from the viewport top. This causes the virtualization window to be misaligned with the
   * actual visible area.
   *
   * Setting the scroll container allows updateVirtualWindow() to compute scrollY relative
   * to the scroll container instead, eliminating this offset.
   *
   * @param el - The scroll container element, or null to clear.
   */
  public setScrollContainer(el: HTMLElement | null): void {
    if (el !== this.scrollContainer) {
      this.scrollContainer = el;
      this.scrollContainerMountOffset = null; // Invalidate cached offset
      if (this.virtualEnabled && this.mount) {
        this.updateVirtualWindow();
      }
    }
  }

  /** Returns the resolved page for a given index, or null if resolved data is unavailable. */
  private getResolvedPage(pageIndex: number): ResolvedPage | null {
    return this.resolvedLayout?.pages[pageIndex] ?? null;
  }

  /** Returns the resolved fragment item for a given page/fragment index, or undefined. */
  private getResolvedFragmentItem(pageIndex: number, fragmentIndex: number): ResolvedPaintItem | undefined {
    const page = this.getResolvedPage(pageIndex);
    if (!page) return undefined;
    const item = page.items[fragmentIndex];
    return item?.kind === 'fragment' ? item : undefined;
  }

  /**
   * Returns the latest painter snapshot captured during the last paint cycle.
   */
  public getPaintSnapshot(): PaintSnapshot | null {
    return this.lastPaintSnapshot;
  }

  /**
   * Returns the page indices that are currently mounted in the DOM.
   *
   * Unlike paint snapshots, this reflects virtualization remounts that happen
   * during scroll without waiting for a full paint cycle.
   */
  public getMountedPageIndices(): number[] {
    return [...this.mountedPageIndices];
  }

  private createAllPageIndices(pageCount: number): number[] {
    return Array.from({ length: pageCount }, (_, pageIndex) => pageIndex);
  }

  private setMountedPageIndices(pageIndices: number[]): void {
    this.mountedPageIndices = [...pageIndices];
  }

  private emitPaintSnapshot(snapshot: PaintSnapshot): void {
    this.lastPaintSnapshot = snapshot;
    this.onPaintSnapshotCallback?.(snapshot);
  }

  private beginPaintSnapshot(layout: Layout): void {
    this.paintSnapshotBuilder = {
      formatVersion: 1,
      lineCount: 0,
      markerCount: 0,
      tabCount: 0,
      pages: layout.pages.map((page, index) => ({
        index,
        pageNumber: Number.isFinite(page.number) ? page.number : null,
        lineCount: 0,
        lines: [],
      })),
    };
  }

  private finalizePaintSnapshotFromBuilder(rootEl?: HTMLElement): void {
    const builder = this.paintSnapshotBuilder;
    if (!builder) {
      this.lastPaintSnapshot = null;
      return;
    }

    const pages = builder.pages.map((page) =>
      compactSnapshotObject({
        index: page.index,
        pageNumber: page.pageNumber,
        lineCount: page.lineCount,
        lines: page.lines,
      }),
    ) as PaintSnapshotPage[];

    this.emitPaintSnapshot({
      formatVersion: builder.formatVersion,
      pageCount: pages.length,
      lineCount: builder.lineCount,
      markerCount: builder.markerCount,
      tabCount: builder.tabCount,
      pages,
      entities: rootEl ? collectPaintSnapshotEntitiesFromDomRoot(rootEl) : createEmptyPaintSnapshotEntities(),
    });
    this.paintSnapshotBuilder = null;
  }

  private capturePaintSnapshotLine(
    lineEl: HTMLElement,
    context: FragmentRenderContext,
    options: PaintSnapshotCaptureOptions = {},
  ): void {
    const builder = this.paintSnapshotBuilder;
    if (!builder) return;
    const pageIndex = context.pageIndex;
    if (!Number.isInteger(pageIndex)) return;

    const page = builder.pages[pageIndex as number];
    if (!page) return;

    const markers = collectLineMarkersForSnapshot(lineEl);
    const tabs = collectLineTabsForSnapshot(lineEl);
    const lineIndex = page.lines.length;
    const style = applyWrapperMarginsToSnapshotStyle(snapshotLineStyleFromElement(lineEl), options.wrapperEl);

    page.lines.push(
      compactSnapshotObject({
        index: lineIndex,
        inTableFragment: options.inTableFragment === true,
        inTableParagraph: options.inTableParagraph === true,
        style,
        markers,
        tabs,
      }) as PaintSnapshotLine,
    );

    page.lineCount += 1;
    builder.lineCount += 1;
    builder.markerCount += markers.length;
    builder.tabCount += tabs.length;
  }

  private collectPaintSnapshotFromDomRoot(rootEl: HTMLElement): PaintSnapshot {
    const pageElements = Array.from(rootEl?.querySelectorAll?.('.superdoc-page') ?? []);
    const pages: PaintSnapshotPage[] = [];
    let lineCount = 0;
    let markerCount = 0;
    let tabCount = 0;

    for (let domPageIndex = 0; domPageIndex < pageElements.length; domPageIndex += 1) {
      const pageEl = pageElements[domPageIndex];
      if (!(pageEl instanceof HTMLElement)) continue;
      const pageIndexRaw = pageEl.dataset?.pageIndex;
      const pageIndexParsed = pageIndexRaw == null ? Number.NaN : Number(pageIndexRaw);
      const pageIndex = Number.isInteger(pageIndexParsed) ? pageIndexParsed : domPageIndex;

      const lineElements = Array.from(pageEl.querySelectorAll('.superdoc-line'));
      const lines: PaintSnapshotLine[] = [];
      for (let lineIndex = 0; lineIndex < lineElements.length; lineIndex += 1) {
        const lineEl = lineElements[lineIndex];
        if (!(lineEl instanceof HTMLElement)) continue;

        const markers = collectLineMarkersForSnapshot(lineEl);
        const tabs = collectLineTabsForSnapshot(lineEl);
        markerCount += markers.length;
        tabCount += tabs.length;
        lineCount += 1;

        lines.push(
          compactSnapshotObject({
            index: lineIndex,
            inTableFragment: Boolean(lineEl.closest('.superdoc-table-fragment')),
            inTableParagraph: Boolean(lineEl.closest('.superdoc-table-paragraph')),
            style: snapshotLineStyleFromElement(lineEl),
            markers,
            tabs,
          }) as PaintSnapshotLine,
        );
      }

      const pageNumberRaw = pageEl.dataset?.pageNumber;
      const pageNumberParsed = pageNumberRaw == null ? Number.NaN : Number(pageNumberRaw);

      pages.push(
        compactSnapshotObject({
          index: pageIndex,
          pageNumber: Number.isFinite(pageNumberParsed) ? pageNumberParsed : null,
          lineCount: lines.length,
          lines,
        }) as PaintSnapshotPage,
      );
    }

    return {
      formatVersion: 1,
      pageCount: pages.length,
      lineCount,
      markerCount,
      tabCount,
      pages,
      entities: collectPaintSnapshotEntitiesFromDomRoot(rootEl),
    };
  }

  /**
   * Builds a new block lookup from the input data, merging header/footer blocks,
   * and tracks which blocks changed since the last paint cycle.
   */
  private normalizeOptionalBlockMeasurePair(
    label: 'header' | 'footer',
    blocks: FlowBlock[] | undefined,
    measures: Measure[] | undefined,
  ): OptionalBlockMeasurePair | undefined {
    const hasBlocks = blocks !== undefined;
    const hasMeasures = measures !== undefined;

    if (hasBlocks !== hasMeasures) {
      throw new Error(
        `DomPainter.paint requires ${label}Blocks and ${label}Measures to both be provided or both be omitted`,
      );
    }

    if (!hasBlocks || !hasMeasures) {
      return undefined;
    }

    return { blocks, measures };
  }

  private updateBlockLookup(input: DomPainterInput): void {
    const { blocks, measures, headerBlocks, headerMeasures, footerBlocks, footerMeasures } = input;

    // Build lookup for main document blocks
    const nextLookup = this.buildBlockLookup(blocks, measures);

    const normalizedHeader = this.normalizeOptionalBlockMeasurePair('header', headerBlocks, headerMeasures);
    if (normalizedHeader) {
      const headerLookup = this.buildBlockLookup(normalizedHeader.blocks, normalizedHeader.measures);
      headerLookup.forEach((entry, id) => {
        nextLookup.set(id, entry);
      });
    }

    const normalizedFooter = this.normalizeOptionalBlockMeasurePair('footer', footerBlocks, footerMeasures);
    if (normalizedFooter) {
      const footerLookup = this.buildBlockLookup(normalizedFooter.blocks, normalizedFooter.measures);
      footerLookup.forEach((entry, id) => {
        nextLookup.set(id, entry);
      });
    }

    // Track changed blocks
    const changed = new Set<string>();
    nextLookup.forEach((entry, id) => {
      const previous = this.blockLookup.get(id);
      if (!previous || previous.version !== entry.version) {
        changed.add(id);
      }
    });
    this.blockLookup = nextLookup;
    this.changedBlocks = changed;
  }

  public paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void {
    const layout = input.sourceLayout;
    this.resolvedLayout = input.resolvedLayout;

    // Update block lookup and change tracking (absorbs former setData logic)
    this.updateBlockLookup(input);

    if (!(mount instanceof HTMLElement)) {
      throw new Error('DomPainter.paint requires a valid HTMLElement mount');
    }

    const doc = mount.ownerDocument ?? (typeof document !== 'undefined' ? document : null);
    if (!doc) {
      throw new Error('DomPainter.paint requires a DOM-like document');
    }
    this.doc = doc;
    this.sdtLabelsRendered.clear(); // Reset SDT label tracking for new render cycle

    // Simple transaction gate: only use position mapping optimization for single-step transactions.
    // Complex transactions (paste, multi-step replace, etc.) fall back to full rebuild.
    const isSimpleTransaction = mapping && mapping.maps.length === 1;
    if (mapping && !isSimpleTransaction) {
      // Complex transaction - force all fragments to rebuild (safe fallback)
      this.blockLookup.forEach((_, id) => this.changedBlocks.add(id));
      this.currentMapping = null;
    } else {
      this.currentMapping = mapping ?? null;
    }

    ensurePrintStyles(doc);
    ensureLinkStyles(doc);
    ensureTrackChangeStyles(doc);
    ensureFieldAnnotationStyles(doc);
    ensureSdtContainerStyles(doc);
    ensureImageSelectionStyles(doc);
    if (!this.isSemanticFlow && this.options.ruler?.enabled) {
      ensureRulerStyles(doc);
    }
    mount.classList.add(CLASS_NAMES.container);

    if (this.mount && this.mount !== mount) {
      this.resetState();
    }
    this.layoutVersion += 1;

    this.layoutEpoch = this.resolvedLayout?.layoutEpoch ?? layout.layoutEpoch ?? 0;
    this.mount = mount;
    this.beginPaintSnapshot(layout);

    this.totalPages = layout.pages.length;
    if (this.isSemanticFlow) {
      // Semantic mode always renders as a single continuous surface.
      applyStyles(mount, containerStyles);
      mount.style.gap = '0px';
      mount.style.alignItems = 'stretch';
      if (!this.currentLayout || this.pageStates.length === 0) {
        this.fullRender(layout);
      } else {
        this.patchLayout(layout);
      }
      this.setMountedPageIndices(this.createAllPageIndices(layout.pages.length));
      this.currentLayout = layout;
      this.changedBlocks.clear();
      this.currentMapping = null;
      return;
    }

    let useDomSnapshotFallback = false;
    const mode = this.layoutMode;
    if (mode === 'horizontal') {
      applyStyles(mount, containerStylesHorizontal);
      // Use configured page gap for horizontal rendering
      mount.style.gap = `${this.pageGap}px`;
      this.renderHorizontal(layout, mount);
      this.finalizePaintSnapshotFromBuilder(mount);
      this.setMountedPageIndices(this.createAllPageIndices(layout.pages.length));
      this.currentLayout = layout;
      this.pageStates = [];
      this.changedBlocks.clear();
      this.currentMapping = null;
      return;
    }
    if (mode === 'book') {
      applyStyles(mount, containerStyles);
      this.renderBookMode(layout, mount);
      this.finalizePaintSnapshotFromBuilder(mount);
      this.setMountedPageIndices(this.createAllPageIndices(layout.pages.length));
      this.currentLayout = layout;
      this.pageStates = [];
      this.changedBlocks.clear();
      this.currentMapping = null;
      return;
    }

    // Vertical mode
    applyStyles(mount, containerStyles);

    if (this.virtualEnabled) {
      // Keep container gap at 0 so spacer elements don't introduce extra offsets.
      mount.style.gap = '0px';
      this.renderVirtualized(layout, mount);
      useDomSnapshotFallback = true;
      this.currentLayout = layout;
      this.changedBlocks.clear();
      this.currentMapping = null;
    } else {
      // Use configured page gap for normal vertical rendering
      mount.style.gap = `${this.pageGap}px`;
      if (!this.currentLayout || this.pageStates.length === 0) {
        this.fullRender(layout);
      } else {
        this.patchLayout(layout);
        useDomSnapshotFallback = true;
      }
      this.setMountedPageIndices(this.createAllPageIndices(layout.pages.length));
    }

    if (useDomSnapshotFallback) {
      this.emitPaintSnapshot(this.collectPaintSnapshotFromDomRoot(mount));
      this.paintSnapshotBuilder = null;
    } else {
      this.finalizePaintSnapshotFromBuilder(mount);
    }

    this.currentLayout = layout;
    this.changedBlocks.clear();
    this.currentMapping = null;
  }

  // ----------------
  // Virtualized path
  // ----------------
  private renderVirtualized(layout: Layout, mount: HTMLElement): void {
    if (!this.doc) return;
    // Always keep the latest layout reference for handlers
    this.currentLayout = layout;

    // First-time init, mount changed, or spacers were detached (e.g., by innerHTML='' on zero-page layout)
    const needsInit =
      !this.topSpacerEl ||
      !this.bottomSpacerEl ||
      !this.virtualPagesEl ||
      this.mount !== mount ||
      this.topSpacerEl.parentElement !== mount;
    if (needsInit) {
      this.ensureVirtualizationSetup(mount);
    }

    this.computeVirtualMetrics();
    this.updateVirtualWindow();
  }

  private ensureVirtualizationSetup(mount: HTMLElement): void {
    if (!this.doc) return;

    // Reset any prior non-virtual state
    mount.innerHTML = '';
    this.pageStates = [];
    this.pageIndexToState.clear();
    this.virtualGapSpacers = [];
    this.virtualMountedKey = '';

    // Create and configure spacer elements
    this.topSpacerEl = this.doc.createElement('div');
    this.bottomSpacerEl = this.doc.createElement('div');
    this.configureSpacerElement(this.topSpacerEl, 'top');
    this.configureSpacerElement(this.bottomSpacerEl, 'bottom');

    // Create and configure pages container (handles the inter-page gap).
    // Virtualized rendering uses its own gap setting independent from normal pageGap.
    this.virtualPagesEl = this.doc.createElement('div');
    this.virtualPagesEl.style.display = 'flex';
    this.virtualPagesEl.style.flexDirection = 'column';
    this.virtualPagesEl.style.alignItems = 'center';
    this.virtualPagesEl.style.width = '100%';
    this.virtualPagesEl.style.gap = `${this.virtualGap}px`;
    // Prevent the browser from using this container as a scroll anchor.
    // When the top spacer grows during virtual window shifts, this element
    // moves down. If the browser anchors on it, scroll anchoring adjusts
    // scrollTop to compensate, which fires a new scroll event with a higher
    // scrollY, triggering another window shift — a positive feedback loop.
    // With this set, the browser anchors on page elements (children) instead,
    // which stay at stable positions regardless of spacer changes.
    this.virtualPagesEl.style.overflowAnchor = 'none';

    mount.appendChild(this.topSpacerEl);
    mount.appendChild(this.virtualPagesEl);
    mount.appendChild(this.bottomSpacerEl);

    // Bind scroll and resize handlers
    this.bindVirtualizationHandlers(mount);
  }

  private configureSpacerElement(element: HTMLElement, type: 'top' | 'bottom' | 'gap'): void {
    element.style.width = '1px';
    element.style.height = '0px';
    element.style.flex = '0 0 auto';
    // Prevent Chrome's scroll anchoring from using spacers as anchor nodes.
    // When spacer heights change during virtual window shifts, scroll anchoring
    // could adjust scrollTop and trigger cascading scroll events.
    element.style.overflowAnchor = 'none';
    element.setAttribute('data-virtual-spacer', type);
  }

  private bindVirtualizationHandlers(mount: HTMLElement): void {
    // Bind scroll handler for container
    if (this.onScrollHandler) {
      mount.removeEventListener('scroll', this.onScrollHandler);
    }
    this.onScrollHandler = () => {
      this.updateVirtualWindow();
    };
    mount.addEventListener('scroll', this.onScrollHandler);

    // Bind window scroll/resize for cases where the page scrolls the window
    const win = this.doc?.defaultView;
    if (win) {
      if (this.onWindowScrollHandler) {
        win.removeEventListener('scroll', this.onWindowScrollHandler);
      }
      this.onWindowScrollHandler = () => {
        this.updateVirtualWindow();
      };
      // passive to avoid blocking scrolling
      win.addEventListener('scroll', this.onWindowScrollHandler, { passive: true });

      if (this.onResizeHandler) {
        win.removeEventListener('resize', this.onResizeHandler);
      }
      this.onResizeHandler = () => {
        this.scrollContainerMountOffset = null; // Recompute on resize
        this.updateVirtualWindow();
      };
      win.addEventListener('resize', this.onResizeHandler);
    }
  }

  private computeVirtualMetrics(): void {
    if (!this.currentLayout) return;
    const N = this.currentLayout.pages.length;
    if (N !== this.virtualHeights.length) {
      this.virtualHeights = this.currentLayout.pages.map((p, i) => {
        const resolved = this.getResolvedPage(i);
        return resolved?.height ?? p.size?.h ?? this.currentLayout!.pageSize.h;
      });
    }
    // Build offsets where offsets[i] = sum_{k < i} (height[k] + gap).
    // Use virtualGap to match CSS gap on virtualPagesEl.
    const offsets: number[] = new Array(this.virtualHeights.length + 1);
    offsets[0] = 0;
    for (let i = 0; i < this.virtualHeights.length; i += 1) {
      offsets[i + 1] = offsets[i] + this.virtualHeights[i] + this.virtualGap;
    }
    this.virtualOffsets = offsets;
  }

  private topOfIndex(i: number): number {
    // Offset to the top of page i (0 for first). Includes gaps before page i.
    if (i <= 0) return 0;
    return this.virtualOffsets[i];
  }

  private contentTotalHeight(): number {
    // Total content height without trailing gap after last page
    const n = this.virtualHeights.length;
    if (n <= 0) return 0;
    return this.virtualOffsets[n] - this.virtualGap;
  }

  private getMountPaddingTopPx(): number {
    if (this.virtualPaddingTop != null) return this.virtualPaddingTop;
    if (!this.mount || !this.doc) return 0;
    const win = this.doc.defaultView;
    if (!win) return 0;
    const style = win.getComputedStyle(this.mount);
    const pt = style?.paddingTop ?? '0';
    const val = Number.parseFloat(pt.replace('px', ''));
    if (Number.isFinite(val)) return Math.max(0, val);
    return 0;
  }

  /**
   * Public method to trigger virtualization window update on scroll.
   * Call this from external scroll handlers when the scroll container
   * is different from the painter's mount element.
   */
  public onScroll(): void {
    if (this.virtualEnabled) {
      this.updateVirtualWindow();
    }
  }

  private updateVirtualWindow(): void {
    if (!this.mount || !this.topSpacerEl || !this.bottomSpacerEl || !this.virtualPagesEl || !this.currentLayout) return;
    const layout = this.currentLayout;
    const N = layout.pages.length;

    if (N === 0) {
      this.mount.innerHTML = '';
      this.setMountedPageIndices([]);
      this.processedLayoutVersion = this.layoutVersion;
      return;
    }

    // Map scrollTop -> anchor page index via prefix sums.
    // virtualOffsets are in layout (unscaled) space, so scrollY must also be in layout space.
    // When the mount has transform: scale(zoom), getBoundingClientRect() returns
    // screen-space values that must be divided by zoom to get layout-space coordinates.
    const paddingTop = this.getMountPaddingTopPx();
    const zoom = this.zoomFactor;
    let scrollY: number;
    const isContainerScrollable = this.mount.scrollHeight > this.mount.clientHeight + 1;
    // Check if the external scroll container is actually scrollable (content overflows its
    // visible area). An element can have overflow:auto but still not scroll if it's in an
    // unconstrained flex layout where the parent has only min-height (no height). In that
    // case the element grows to fit content and scrollTop stays 0 — fall through to the
    // viewport-based calculation instead.
    const scrollCont = this.scrollContainer;
    const isScrollContainerActive = scrollCont != null && scrollCont.scrollHeight > scrollCont.clientHeight + 1;
    if (isContainerScrollable) {
      scrollY = Math.max(0, this.mount.scrollTop - paddingTop);
    } else if (isScrollContainerActive) {
      // Intermediate scroll ancestor (e.g., a wrapper div with overflow-y: auto).
      // Use scrollContainer.scrollTop with a cached mount offset instead of
      // getBoundingClientRect(). Rects are affected by spacer DOM mutations
      // which can cause cascading scroll events and runaway scrolling.
      //
      // mountOffset = distance from scroll container's content top to mount's top.
      // Computed once and cached; invalidated on mount/container/zoom change.
      if (this.scrollContainerMountOffset == null) {
        const mountRect = this.mount.getBoundingClientRect();
        const containerRect = scrollCont.getBoundingClientRect();
        this.scrollContainerMountOffset = mountRect.top - containerRect.top + scrollCont.scrollTop;
      }
      scrollY = Math.max(0, (scrollCont.scrollTop - this.scrollContainerMountOffset) / zoom - paddingTop);
    } else {
      const rect = this.mount.getBoundingClientRect();
      // rect.top is in screen space (affected by CSS transform: scale).
      // Divide by zoom to convert to layout space for comparison with virtualOffsets.
      scrollY = Math.max(0, -rect.top / zoom - paddingTop);
    }

    // Binary search for anchor index such that topOfIndex(i) <= scrollY < topOfIndex(i+1)
    let lo = 0;
    let hi = N; // exclusive
    while (lo < hi) {
      const mid = (lo + hi) >>> 1;
      if (this.topOfIndex(mid) <= scrollY) lo = mid + 1;
      else hi = mid;
    }
    const anchor = Math.max(0, lo - 1);

    // Compute window centered around anchor (approximately), with overscan
    const baseWindow = this.virtualWindow;
    const overscan = this.virtualOverscan;
    let start = anchor - Math.floor(baseWindow / 2) - overscan;
    start = Math.max(0, Math.min(start, Math.max(0, N - baseWindow)));
    const end = Math.min(N - 1, start + baseWindow - 1 + overscan * 2);
    // Adjust start if we overshot end due to trailing clamp
    start = Math.max(0, Math.min(start, end - baseWindow + 1));

    const needed = new Set<number>();
    for (let i = start; i <= end; i += 1) needed.add(i);
    for (const pageIndex of this.virtualPinnedPages) {
      const idx = Math.max(0, Math.min(pageIndex, N - 1));
      needed.add(idx);
    }

    const mounted = Array.from(needed).sort((a, b) => a - b);
    const mountedKey = mounted.join(',');

    // No-op if mounted pages unchanged and nothing changed
    const alreadyProcessedLayout = this.processedLayoutVersion === this.layoutVersion;
    if (mountedKey === this.virtualMountedKey && this.changedBlocks.size === 0 && alreadyProcessedLayout) {
      this.virtualStart = start;
      this.virtualEnd = end;
      this.updateSpacersForMountedPages(mounted);
      return;
    }

    this.virtualMountedKey = mountedKey;
    this.virtualStart = start;
    this.virtualEnd = end;
    this.setMountedPageIndices(mounted);

    // Update spacers + rebuild gap spacers
    this.updateSpacersForMountedPages(mounted);
    this.clearGapSpacers();

    // Reset SDT label tracking so remounted start fragments get their labels back.
    this.sdtLabelsRendered.clear();

    // Remove pages that are no longer needed
    for (const [idx, state] of this.pageIndexToState.entries()) {
      if (!needed.has(idx)) {
        state.element.remove();
        this.pageIndexToState.delete(idx);
      }
    }

    // Insert or patch needed pages
    for (const i of mounted) {
      const page = layout.pages[i];
      const resolved = this.getResolvedPage(i);
      const pageSize = resolved ? { w: resolved.width, h: resolved.height } : (page.size ?? layout.pageSize);
      const existing = this.pageIndexToState.get(i);
      if (!existing) {
        const newState = this.createPageState(page, pageSize, i);
        newState.element.dataset.pageNumber = String(page.number);
        newState.element.dataset.pageIndex = String(i);
        // Ensure virtualization uses page margin 0
        applyStyles(newState.element, pageStyles(pageSize.w, pageSize.h, this.getEffectivePageStyles()));
        this.virtualPagesEl.appendChild(newState.element);
        this.pageIndexToState.set(i, newState);
      } else {
        // Patch in place
        this.patchPage(existing, page, pageSize, i);
      }
    }

    // Ensure top spacer is first, pages container is in the middle, and bottom spacer is last.
    if (this.mount.firstChild !== this.topSpacerEl) {
      this.mount.insertBefore(this.topSpacerEl, this.mount.firstChild);
    }
    if (this.virtualPagesEl.parentElement !== this.mount) {
      this.mount.insertBefore(this.virtualPagesEl, this.bottomSpacerEl);
    }
    this.mount.appendChild(this.bottomSpacerEl);

    // Ensure mounted pages are ordered (with gap spacers).
    // Use cursor-based reconciliation to skip DOM moves for elements already in
    // the correct position. Moving an element via appendChild/insertBefore triggers
    // a browser blur event on any focused descendant, which breaks header/footer
    // in-place editing where a PM editor lives inside a page element (SD-1993).
    let prevIndex: number | null = null;
    let cursor: ChildNode | null = this.virtualPagesEl.firstChild;
    for (const idx of mounted) {
      if (prevIndex != null && idx > prevIndex + 1) {
        const gap = this.doc!.createElement('div');
        this.configureSpacerElement(gap, 'gap');
        gap.dataset.gapFrom = String(prevIndex);
        gap.dataset.gapTo = String(idx);
        const gapHeight =
          this.topOfIndex(idx) - this.topOfIndex(prevIndex) - this.virtualHeights[prevIndex] - this.virtualGap * 2;
        gap.style.height = `${Math.max(0, Math.floor(gapHeight))}px`;
        this.virtualGapSpacers.push(gap);
        // Insert gap before cursor. cursor is NOT advanced because it still
        // points at the next page element that needs to be reconciled.
        this.virtualPagesEl.insertBefore(gap, cursor);
      }
      const state = this.pageIndexToState.get(idx)!;
      if (state.element === cursor) {
        // Already in the correct position. Skip the DOM mutation.
        cursor = state.element.nextSibling;
      } else {
        // Out of order. Move to the correct position.
        this.virtualPagesEl.insertBefore(state.element, cursor);
      }
      prevIndex = idx;
    }

    // Clear changed blocks now that current visible pages are patched
    this.changedBlocks.clear();
    this.processedLayoutVersion = this.layoutVersion;
  }

  private updateSpacers(start: number, end: number): void {
    if (!this.topSpacerEl || !this.bottomSpacerEl) return;
    const top = this.topOfIndex(start);
    const bottom = this.contentTotalHeight() - this.topOfIndex(end + 1);
    this.topSpacerEl.style.height = `${Math.max(0, Math.floor(top))}px`;
    this.bottomSpacerEl.style.height = `${Math.max(0, Math.floor(bottom))}px`;
  }

  private updateSpacersForMountedPages(mountedPageIndices: number[]): void {
    if (!this.topSpacerEl || !this.bottomSpacerEl) return;
    if (mountedPageIndices.length === 0) {
      this.topSpacerEl.style.height = '0px';
      this.bottomSpacerEl.style.height = '0px';
      return;
    }

    const first = mountedPageIndices[0];
    const last = mountedPageIndices[mountedPageIndices.length - 1];
    const n = this.virtualHeights.length;
    const clampedFirst = Math.max(0, Math.min(first, Math.max(0, n - 1)));
    const clampedLast = Math.max(0, Math.min(last, Math.max(0, n - 1)));

    const top = this.topOfIndex(clampedFirst);
    const bottom = this.topOfIndex(n) - this.topOfIndex(clampedLast + 1) - this.virtualGap;
    this.topSpacerEl.style.height = `${Math.max(0, Math.floor(top))}px`;
    this.bottomSpacerEl.style.height = `${Math.max(0, Math.floor(bottom))}px`;
  }

  private clearGapSpacers(): void {
    for (const el of this.virtualGapSpacers) {
      el.remove();
    }
    this.virtualGapSpacers = [];
  }

  private renderHorizontal(layout: Layout, mount: HTMLElement): void {
    if (!this.doc) return;
    mount.innerHTML = '';
    layout.pages.forEach((page, pageIndex) => {
      const resolved = this.getResolvedPage(pageIndex);
      const pageSize = resolved ? { w: resolved.width, h: resolved.height } : (page.size ?? layout.pageSize);
      const pageEl = this.renderPage(pageSize.w, pageSize.h, page, pageIndex);
      mount.appendChild(pageEl);
    });
  }

  private renderBookMode(layout: Layout, mount: HTMLElement): void {
    if (!this.doc) return;
    mount.innerHTML = '';
    const pages = layout.pages;
    if (pages.length === 0) return;

    const firstResolved = this.getResolvedPage(0);
    const firstPageSize = firstResolved
      ? { w: firstResolved.width, h: firstResolved.height }
      : (pages[0].size ?? layout.pageSize);
    const firstPageEl = this.renderPage(firstPageSize.w, firstPageSize.h, pages[0], 0);
    mount.appendChild(firstPageEl);

    for (let i = 1; i < pages.length; i += 2) {
      const spreadEl = this.doc!.createElement('div');
      spreadEl.classList.add(CLASS_NAMES.spread);
      applyStyles(spreadEl, spreadStyles);

      const leftPage = pages[i];
      const leftResolved = this.getResolvedPage(i);
      const leftPageSize = leftResolved
        ? { w: leftResolved.width, h: leftResolved.height }
        : (leftPage.size ?? layout.pageSize);
      const leftPageEl = this.renderPage(leftPageSize.w, leftPageSize.h, leftPage, i);
      spreadEl.appendChild(leftPageEl);

      if (i + 1 < pages.length) {
        const rightPage = pages[i + 1];
        const rightResolved = this.getResolvedPage(i + 1);
        const rightPageSize = rightResolved
          ? { w: rightResolved.width, h: rightResolved.height }
          : (rightPage.size ?? layout.pageSize);
        const rightPageEl = this.renderPage(rightPageSize.w, rightPageSize.h, rightPage, i + 1);
        spreadEl.appendChild(rightPageEl);
      }

      mount.appendChild(spreadEl);
    }
  }

  private renderPage(width: number, height: number, page: Page, pageIndex: number): HTMLElement {
    if (!this.doc) {
      throw new Error('DomPainter: document is not available');
    }
    const resolvedPage = this.getResolvedPage(pageIndex);
    const el = this.doc.createElement('div');
    el.classList.add(CLASS_NAMES.page);
    applyStyles(el, pageStyles(width, height, this.getEffectivePageStyles()));
    this.applySemanticPageOverrides(el);
    el.dataset.layoutEpoch = String(this.layoutEpoch);
    el.dataset.pageNumber = String(page.number);
    el.dataset.pageIndex = String(pageIndex);

    // Render per-page ruler if enabled (suppressed in semantic flow mode)
    if (!this.isSemanticFlow && this.options.ruler?.enabled) {
      const rulerEl = this.renderPageRuler(width, page, resolvedPage);
      if (rulerEl) {
        el.appendChild(rulerEl);
      }
    }

    const contextBase: FragmentRenderContext = {
      pageNumber: page.number,
      totalPages: this.totalPages,
      section: 'body',
      pageNumberText: resolvedPage?.numberText ?? page.numberText,
      pageIndex,
    };

    const sdtBoundaries = computeSdtBoundaries(
      page.fragments,
      this.blockLookup,
      this.sdtLabelsRendered,
      resolvedPage?.items,
    );
    const betweenBorderFlags = computeBetweenBorderFlags(page.fragments, this.blockLookup, resolvedPage?.items);

    page.fragments.forEach((fragment, index) => {
      const sdtBoundary = sdtBoundaries.get(index);
      const resolvedItem = this.getResolvedFragmentItem(pageIndex, index);
      el.appendChild(
        this.renderFragment(fragment, contextBase, sdtBoundary, betweenBorderFlags.get(index), resolvedItem),
      );
    });
    this.renderDecorationsForPage(el, page, pageIndex, resolvedPage);
    return el;
  }

  /**
   * Render a ruler element for a page.
   *
   * Creates a horizontal ruler with tick marks and optional interactive margin handles.
   * The ruler is positioned at the top of the page and displays inch measurements.
   *
   * @param pageWidthPx - Page width in pixels
   * @param page - Page data containing margins and optional size information
   * @returns Ruler element, or null if this.doc is unavailable or page margins are missing
   *
   * Side effects:
   * - Creates DOM elements and applies inline styles
   * - May invoke the onMarginChange callback if interactive mode is enabled
   *
   * Fallback behavior:
   * - Uses DEFAULT_PAGE_HEIGHT_PX (1056px = 11 inches) if page.size.h is not available
   * - Defaults margins to 0 if not explicitly provided
   */
  private renderPageRuler(pageWidthPx: number, page: Page, resolvedPage?: ResolvedPage | null): HTMLElement | null {
    if (!this.doc) {
      console.warn('[renderPageRuler] Cannot render ruler: document is not available.');
      return null;
    }

    const margins = resolvedPage?.margins ?? page.margins;
    if (!margins) {
      console.warn(`[renderPageRuler] Cannot render ruler for page ${page.number}: margins not available.`);
      return null;
    }

    const leftMargin = margins.left ?? 0;
    const rightMargin = margins.right ?? 0;

    try {
      const rulerDefinition = generateRulerDefinitionFromPx({
        pageWidthPx,
        pageHeightPx: page.size?.h ?? DEFAULT_PAGE_HEIGHT_PX,
        leftMarginPx: leftMargin,
        rightMarginPx: rightMargin,
      });

      const interactive = this.options.ruler?.interactive ?? false;
      const onMarginChange = this.options.ruler?.onMarginChange;

      const rulerEl = createRulerElement({
        definition: rulerDefinition,
        doc: this.doc,
        interactive,
        onDragEnd:
          interactive && onMarginChange
            ? (side, x) => {
                // Convert pixel position to inches for callback
                try {
                  const ppi = 96;
                  const marginInches = side === 'left' ? x / ppi : (pageWidthPx - x) / ppi;
                  onMarginChange(side, marginInches);
                } catch (error) {
                  console.error('[renderPageRuler] Error in onMarginChange callback:', error);
                }
              }
            : undefined,
      });

      // Position ruler at top of page (above content area)
      rulerEl.style.position = 'absolute';
      rulerEl.style.top = '0';
      rulerEl.style.left = '0';
      rulerEl.style.zIndex = '20';
      rulerEl.dataset.pageNumber = String(page.number);

      return rulerEl;
    } catch (error) {
      console.error(`[renderPageRuler] Failed to create ruler for page ${page.number}:`, error);
      return null;
    }
  }

  private renderDecorationsForPage(
    pageEl: HTMLElement,
    page: Page,
    pageIndex: number,
    resolvedPage?: ResolvedPage | null,
  ): void {
    if (this.isSemanticFlow) return;
    this.renderDecorationSection(pageEl, page, pageIndex, 'header', resolvedPage);
    this.renderDecorationSection(pageEl, page, pageIndex, 'footer', resolvedPage);
  }

  /**
   * Check if an anchored fragment has vRelativeFrom === 'page'.
   * Used to determine special Y positioning for page-relative anchored media
   * in header/footer decoration sections.
   */
  private isPageRelativeAnchoredFragment(fragment: Fragment): boolean {
    if (fragment.kind !== 'image' && fragment.kind !== 'drawing') {
      return false;
    }
    const lookup = this.blockLookup.get(fragment.blockId);
    if (!lookup) {
      return false;
    }
    const block = lookup.block;
    if (block.kind !== 'image' && block.kind !== 'drawing') {
      return false;
    }
    return block.anchor?.vRelativeFrom === 'page';
  }

  /**
   * Header/footer layout emits normalized anchor Y coordinates:
   * - headers: local to the header container origin
   * - footers: local to the top of the footer band (pageHeight - bottomMargin)
   *
   * Footer containers can grow upward when content overflows the reserved footer
   * band, so their top edge is not always the same as the footer band origin.
   * This helper returns the page-space origin that normalized anchor Y values
   * are measured from.
   */
  private getDecorationAnchorPageOriginY(
    pageEl: HTMLElement,
    page: Page,
    kind: 'header' | 'footer',
    effectiveOffset: number,
    resolvedPage?: ResolvedPage | null,
  ): number {
    if (kind === 'header') {
      return effectiveOffset;
    }

    const pageMargins = resolvedPage?.margins ?? page.margins;
    const bottomMargin = pageMargins?.bottom;
    if (bottomMargin == null) {
      return effectiveOffset;
    }

    const footnoteReserve = resolvedPage?.footnoteReserved ?? page.footnoteReserved ?? 0;
    const adjustedBottomMargin = Math.max(0, bottomMargin - footnoteReserve);
    const styledPageHeight = Number.parseFloat(pageEl.style.height || '');
    const pageHeight =
      page.size?.h ??
      this.currentLayout?.pageSize?.h ??
      (Number.isFinite(styledPageHeight) ? styledPageHeight : pageEl.clientHeight);

    return Math.max(0, pageHeight - adjustedBottomMargin);
  }

  private renderDecorationSection(
    pageEl: HTMLElement,
    page: Page,
    pageIndex: number,
    kind: 'header' | 'footer',
    resolvedPage?: ResolvedPage | null,
  ): void {
    if (!this.doc) return;
    const provider = kind === 'header' ? this.headerProvider : this.footerProvider;
    const className = kind === 'header' ? CLASS_NAMES.pageHeader : CLASS_NAMES.pageFooter;
    const existing = pageEl.querySelector(`.${className}`);
    // Provider still receives legacy page — its signature is not changed in this PR
    const data = provider ? provider(page.number, page.margins, page) : null;

    if (!data || data.fragments.length === 0) {
      existing?.remove();
      return;
    }

    const container = (existing as HTMLElement) ?? this.doc.createElement('div');
    container.className = className;
    container.innerHTML = '';
    const baseOffset = data.offset ?? (kind === 'footer' ? pageEl.clientHeight - data.height : 0);
    const marginLeft = data.marginLeft ?? 0;
    const pageMargins = resolvedPage?.margins ?? page.margins;
    const marginRight = pageMargins?.right ?? 0;

    // For footers, if content is taller than reserved space, expand container upward
    // The container bottom stays anchored at footerMargin from page bottom
    let effectiveHeight = data.height;
    let effectiveOffset = baseOffset;
    if (
      kind === 'footer' &&
      typeof data.contentHeight === 'number' &&
      Number.isFinite(data.contentHeight) &&
      data.contentHeight > 0 &&
      data.contentHeight > data.height
    ) {
      effectiveHeight = data.contentHeight;
      // Move container up to accommodate taller content while keeping bottom edge in place
      effectiveOffset = baseOffset - (data.contentHeight - data.height);
    }

    container.style.position = 'absolute';
    container.style.left = `${marginLeft}px`;
    if (typeof data.contentWidth === 'number') {
      container.style.width = `${Math.max(0, data.contentWidth)}px`;
    } else {
      container.style.width = `calc(100% - ${marginLeft + marginRight}px)`;
    }
    container.style.pointerEvents = 'none';
    container.style.height = `${effectiveHeight}px`;
    container.style.top = `${Math.max(0, effectiveOffset)}px`;
    container.style.zIndex = '1';
    // Allow header/footer content to overflow its container bounds.
    // In OOXML, headers and footers can extend past their allocated margin space
    // into the body region, similar to how body content can have negative indents.
    container.style.overflow = 'visible';

    // Footer page-relative anchors carry normalized Y coordinates (band-local,
    // computed from real page geometry). Compute the page-space origin so the
    // painter can convert them back to absolute page / container-local positions.
    // Header page-relative anchors use raw inner-layout Y and are handled with
    // the simpler effectiveOffset subtraction (unchanged from the baseline).
    const footerAnchorPageOriginY =
      kind === 'footer' ? this.getDecorationAnchorPageOriginY(pageEl, page, kind, effectiveOffset, resolvedPage) : 0;
    const footerAnchorContainerOffsetY = kind === 'footer' ? footerAnchorPageOriginY - effectiveOffset : 0;

    // For footers, calculate offset to push content to bottom of container
    // Fragments are absolutely positioned, so we need to adjust their y values
    // Use effectiveHeight (which accounts for overflow) rather than reserved height
    let footerYOffset = 0;
    if (kind === 'footer' && data.fragments.length > 0) {
      const contentHeight =
        typeof data.contentHeight === 'number'
          ? data.contentHeight
          : data.fragments.reduce((max, f) => {
              const fragHeight =
                'height' in f && typeof f.height === 'number' ? f.height : this.estimateFragmentHeight(f);
              return Math.max(max, f.y + Math.max(0, fragHeight));
            }, 0);
      // Offset to push content to bottom of container
      // When container has expanded (effectiveHeight >= contentHeight), offset is 0
      footerYOffset = Math.max(0, effectiveHeight - contentHeight);
    }

    const context: FragmentRenderContext = {
      pageNumber: page.number,
      totalPages: this.totalPages,
      section: kind,
      pageNumberText: resolvedPage?.numberText ?? page.numberText,
      pageIndex,
    };

    // Compute between-border flags for header/footer paragraph fragments
    const betweenBorderFlags = computeBetweenBorderFlags(data.fragments, this.blockLookup);

    // Separate behindDoc fragments from normal fragments.
    // Prefer explicit fragment.behindDoc when present. Keep zIndex===0 as a
    // compatibility fallback for older layouts that predate explicit metadata.
    // Track original index for between-border flag lookup.
    const behindDocFragments: { fragment: (typeof data.fragments)[number]; originalIndex: number }[] = [];
    const normalFragments: { fragment: (typeof data.fragments)[number]; originalIndex: number }[] = [];

    for (let fi = 0; fi < data.fragments.length; fi += 1) {
      const fragment = data.fragments[fi];
      let isBehindDoc = false;
      if (fragment.kind === 'image' || fragment.kind === 'drawing') {
        isBehindDoc =
          fragment.behindDoc === true || (fragment.behindDoc == null && 'zIndex' in fragment && fragment.zIndex === 0);
      }
      if (isBehindDoc) {
        behindDocFragments.push({ fragment, originalIndex: fi });
      } else {
        normalFragments.push({ fragment, originalIndex: fi });
      }
    }

    // Remove any previously rendered behindDoc fragments for this section before re-rendering.
    // Unlike the header/footer container (which uses innerHTML = '' to clear), behindDoc
    // fragments are placed directly on the page element and must be explicitly removed.
    const behindDocSelector = `[data-behind-doc-section="${kind}"]`;
    pageEl.querySelectorAll(behindDocSelector).forEach((el) => el.remove());

    // Render behindDoc fragments directly on the page with z-index: 0
    // and insert them at the beginning of the page so they render behind body content.
    // We can't use z-index: -1 because that goes behind the page's white background.
    // By inserting at the beginning and using z-index: 0, they render below body content
    // which also has z-index values but comes later in DOM order.
    behindDocFragments.forEach(({ fragment, originalIndex }) => {
      const fragEl = this.renderFragment(fragment, context, undefined, betweenBorderFlags.get(originalIndex));
      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment);

      let pageY: number;
      if (isPageRelative && kind === 'footer') {
        // Footer page-relative: fragment.y is normalized to band-local coords
        pageY = footerAnchorPageOriginY + fragment.y;
      } else if (isPageRelative) {
        // Header page-relative: fragment.y is raw inner-layout absolute Y
        pageY = fragment.y;
      } else {
        pageY = effectiveOffset + fragment.y + (kind === 'footer' ? footerYOffset : 0);
      }

      fragEl.style.top = `${pageY}px`;
      fragEl.style.left = `${marginLeft + fragment.x}px`;
      fragEl.style.zIndex = '0'; // Same level as page, but inserted first so renders behind
      fragEl.dataset.behindDocSection = kind; // Track for cleanup on re-render
      // Insert at beginning of page so it renders behind body content due to DOM order
      pageEl.insertBefore(fragEl, pageEl.firstChild);
    });

    // Render normal fragments in the header/footer container
    normalFragments.forEach(({ fragment, originalIndex }) => {
      const fragEl = this.renderFragment(fragment, context, undefined, betweenBorderFlags.get(originalIndex));
      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment);

      if (isPageRelative && kind === 'footer') {
        // Footer page-relative: fragment.y is normalized to band-local coords
        fragEl.style.top = `${fragment.y + footerAnchorContainerOffsetY}px`;
      } else if (isPageRelative) {
        // Header page-relative: convert raw inner-layout Y to container-local
        fragEl.style.top = `${fragment.y - effectiveOffset}px`;
      } else if (footerYOffset > 0) {
        // Non-anchored footer content: push to bottom of container
        const currentTop = parseFloat(fragEl.style.top) || fragment.y;
        fragEl.style.top = `${currentTop + footerYOffset}px`;
      }

      container.appendChild(fragEl);
    });

    if (!existing) {
      pageEl.appendChild(container);
    }
  }

  private resetState(): void {
    if (this.mount) {
      if (this.onScrollHandler) {
        try {
          this.mount.removeEventListener('scroll', this.onScrollHandler);
        } catch {}
      }
      if (this.onWindowScrollHandler && this.doc?.defaultView) {
        try {
          this.doc.defaultView.removeEventListener('scroll', this.onWindowScrollHandler);
        } catch {}
      }
      if (this.onResizeHandler && this.doc?.defaultView) {
        try {
          this.doc.defaultView.removeEventListener('resize', this.onResizeHandler);
        } catch {}
      }
      this.mount.innerHTML = '';
    }
    this.pageStates = [];
    this.currentLayout = null;
    this.pageIndexToState.clear();
    this.topSpacerEl = null;
    this.bottomSpacerEl = null;
    this.virtualPagesEl = null;
    this.onScrollHandler = null;
    this.onWindowScrollHandler = null;
    this.onResizeHandler = null;
    this.scrollContainerMountOffset = null;
    this.layoutVersion = 0;
    this.processedLayoutVersion = -1;
    this.paintSnapshotBuilder = null;
    this.lastPaintSnapshot = null;
    this.mountedPageIndices = [];
  }

  private fullRender(layout: Layout): void {
    if (!this.mount || !this.doc) return;
    this.mount.innerHTML = '';
    this.pageStates = [];

    layout.pages.forEach((page, pageIndex) => {
      const resolved = this.getResolvedPage(pageIndex);
      const pageSize = resolved ? { w: resolved.width, h: resolved.height } : (page.size ?? layout.pageSize);
      const pageState = this.createPageState(page, pageSize, pageIndex);
      pageState.element.dataset.pageNumber = String(page.number);
      pageState.element.dataset.pageIndex = String(pageIndex);
      this.mount!.appendChild(pageState.element);
      this.pageStates.push(pageState);
    });
  }

  private patchLayout(layout: Layout): void {
    if (!this.mount || !this.doc) return;

    const nextStates: PageDomState[] = [];

    layout.pages.forEach((page, index) => {
      const resolved = this.getResolvedPage(index);
      const pageSize = resolved ? { w: resolved.width, h: resolved.height } : (page.size ?? layout.pageSize);
      const prevState = this.pageStates[index];
      if (!prevState) {
        const newState = this.createPageState(page, pageSize, index);
        newState.element.dataset.pageNumber = String(page.number);
        newState.element.dataset.pageIndex = String(index);
        this.mount!.insertBefore(newState.element, this.mount!.children[index] ?? null);
        nextStates.push(newState);
        return;
      }
      this.patchPage(prevState, page, pageSize, index);
      nextStates.push(prevState);
    });

    if (this.pageStates.length > layout.pages.length) {
      for (let i = layout.pages.length; i < this.pageStates.length; i += 1) {
        this.pageStates[i]?.element.remove();
      }
    }

    this.pageStates = nextStates;
  }

  private patchPage(state: PageDomState, page: Page, pageSize: { w: number; h: number }, pageIndex: number): void {
    const resolvedPage = this.getResolvedPage(pageIndex);
    const pageEl = state.element;
    applyStyles(pageEl, pageStyles(pageSize.w, pageSize.h, this.getEffectivePageStyles()));
    this.applySemanticPageOverrides(pageEl);
    pageEl.dataset.pageNumber = String(page.number);
    pageEl.dataset.layoutEpoch = String(this.layoutEpoch);
    // pageIndex is already set during creation and doesn't change during patch

    const existing = new Map(state.fragments.map((frag) => [frag.key, frag]));
    const nextFragments: FragmentDomState[] = [];
    const sdtBoundaries = computeSdtBoundaries(
      page.fragments,
      this.blockLookup,
      this.sdtLabelsRendered,
      resolvedPage?.items,
    );
    const betweenBorderFlags = computeBetweenBorderFlags(page.fragments, this.blockLookup, resolvedPage?.items);

    const contextBase: FragmentRenderContext = {
      pageNumber: page.number,
      totalPages: this.totalPages,
      section: 'body',
      pageNumberText: resolvedPage?.numberText ?? page.numberText,
      pageIndex,
    };

    page.fragments.forEach((fragment, index) => {
      const key = fragmentKey(fragment);
      const current = existing.get(key);
      const sdtBoundary = sdtBoundaries.get(index);
      const betweenInfo = betweenBorderFlags.get(index);
      const resolvedItem = this.getResolvedFragmentItem(pageIndex, index);

      if (current) {
        existing.delete(key);
        const sdtBoundaryMismatch = shouldRebuildForSdtBoundary(current.element, sdtBoundary);
        // Detect mismatch in any between-border property
        const betweenBorderMismatch =
          (current.element.dataset.betweenBorder === 'true') !== (betweenInfo?.showBetweenBorder ?? false) ||
          (current.element.dataset.suppressTopBorder === 'true') !== (betweenInfo?.suppressTopBorder ?? false) ||
          (current.element.dataset.gapBelow ?? '') !== (betweenInfo?.gapBelow ? String(betweenInfo.gapBelow) : '');
        // Verify the position mapping is reliable: if mapping the old pmStart doesn't produce
        // the expected new pmStart, the mapping is degenerate (e.g. full-document paste) and
        // we must rebuild to get correct span position attributes.
        const newPmStart = (fragment as { pmStart?: number }).pmStart;
        const mappingUnreliable =
          this.currentMapping != null &&
          newPmStart != null &&
          current.element.dataset.pmStart != null &&
          this.currentMapping.map(Number(current.element.dataset.pmStart)) !== newPmStart;
        const resolvedSig =
          resolvedItem && 'version' in resolvedItem ? (resolvedItem as { version?: string }).version : undefined;
        const needsRebuild =
          this.changedBlocks.has(fragment.blockId) ||
          current.signature !== (resolvedSig ?? fragmentSignature(fragment, this.blockLookup)) ||
          sdtBoundaryMismatch ||
          betweenBorderMismatch ||
          mappingUnreliable;

        if (needsRebuild) {
          const replacement = this.renderFragment(fragment, contextBase, sdtBoundary, betweenInfo, resolvedItem);
          pageEl.replaceChild(replacement, current.element);
          current.element = replacement;
          current.signature = resolvedSig ?? fragmentSignature(fragment, this.blockLookup);
        } else if (this.currentMapping) {
          // Fragment NOT rebuilt - update position attributes to reflect document changes
          this.updatePositionAttributes(current.element, this.currentMapping);
        }

        this.updateFragmentElement(current.element, fragment, contextBase.section, resolvedItem);
        if (sdtBoundary?.widthOverride != null) {
          current.element.style.width = `${sdtBoundary.widthOverride}px`;
        }
        current.fragment = fragment;
        current.key = key;
        current.context = contextBase;
        nextFragments.push(current);

        return;
      }

      const fresh = this.renderFragment(fragment, contextBase, sdtBoundary, betweenInfo, resolvedItem);
      pageEl.insertBefore(fresh, pageEl.children[index] ?? null);
      const freshSig =
        resolvedItem && 'version' in resolvedItem ? (resolvedItem as { version?: string }).version : undefined;
      nextFragments.push({
        key,
        fragment,
        element: fresh,
        signature: freshSig ?? fragmentSignature(fragment, this.blockLookup),
        context: contextBase,
      });
    });

    existing.forEach((state) => state.element.remove());

    nextFragments.forEach((fragmentState, index) => {
      const desiredChild = pageEl.children[index];
      if (fragmentState.element !== desiredChild) {
        pageEl.insertBefore(fragmentState.element, desiredChild ?? null);
      }
    });

    state.fragments = nextFragments;
    this.renderDecorationsForPage(pageEl, page, pageIndex, resolvedPage);
  }

  /**
   * Updates data-pm-start/data-pm-end attributes on all elements within a fragment
   * using the transaction's mapping. Skips header/footer content (separate PM coordinate space).
   * Also skips fragments that end before the edit point (their positions don't change).
   */
  private updatePositionAttributes(fragmentEl: HTMLElement, mapping: PositionMapping): void {
    // Skip header/footer elements (they use a separate PM coordinate space)
    if (fragmentEl.closest('.superdoc-page-header, .superdoc-page-footer')) {
      return;
    }

    // Wrap mapping logic in try-catch to prevent corrupted mappings from crashing paint cycle
    try {
      // Quick check: if the fragment's end position doesn't change, nothing inside needs updating.
      // This happens for all content BEFORE the edit point.
      const fragEnd = fragmentEl.dataset.pmEnd;
      if (fragEnd !== undefined && fragEnd !== '') {
        const endNum = Number(fragEnd);
        if (Number.isFinite(endNum) && mapping.map(endNum, -1) === endNum) {
          // Fragment ends before edit point - no position changes needed
          return;
        }
      }

      // Get all elements with position attributes (including the fragment element itself)
      const elements = fragmentEl.querySelectorAll('[data-pm-start], [data-pm-end]');
      const allElements = [fragmentEl, ...Array.from(elements)] as HTMLElement[];

      for (const el of allElements) {
        const oldStart = el.dataset.pmStart;
        const oldEnd = el.dataset.pmEnd;

        if (oldStart !== undefined && oldStart !== '') {
          const num = Number(oldStart);
          if (Number.isFinite(num)) {
            el.dataset.pmStart = String(mapping.map(num));
          }
        }

        if (oldEnd !== undefined && oldEnd !== '') {
          const num = Number(oldEnd);
          if (Number.isFinite(num)) {
            // Use bias -1 for end positions to handle edge cases correctly
            el.dataset.pmEnd = String(mapping.map(num, -1));
          }
        }
      }
    } catch (error) {
      // Log the error but don't crash the paint cycle - corrupted mappings shouldn't break rendering
      console.error('Error updating position attributes with mapping:', error);
    }
  }

  private createPageState(page: Page, pageSize: { w: number; h: number }, pageIndex: number): PageDomState {
    if (!this.doc) {
      throw new Error('DomPainter.createPageState requires a document');
    }
    const resolvedPage = this.getResolvedPage(pageIndex);
    const el = this.doc.createElement('div');
    el.classList.add(CLASS_NAMES.page);
    applyStyles(el, pageStyles(pageSize.w, pageSize.h, this.getEffectivePageStyles()));
    this.applySemanticPageOverrides(el);
    el.dataset.layoutEpoch = String(this.layoutEpoch);

    const contextBase: FragmentRenderContext = {
      pageNumber: page.number,
      totalPages: this.totalPages,
      section: 'body',
      pageNumberText: resolvedPage?.numberText ?? page.numberText,
      pageIndex,
    };

    const sdtBoundaries = computeSdtBoundaries(
      page.fragments,
      this.blockLookup,
      this.sdtLabelsRendered,
      resolvedPage?.items,
    );
    const betweenBorderFlags = computeBetweenBorderFlags(page.fragments, this.blockLookup, resolvedPage?.items);
    const fragmentStates: FragmentDomState[] = page.fragments.map((fragment, index) => {
      const sdtBoundary = sdtBoundaries.get(index);
      const resolvedItem = this.getResolvedFragmentItem(pageIndex, index);
      const fragmentEl = this.renderFragment(
        fragment,
        contextBase,
        sdtBoundary,
        betweenBorderFlags.get(index),
        resolvedItem,
      );
      el.appendChild(fragmentEl);
      const initSig =
        resolvedItem && 'version' in resolvedItem ? (resolvedItem as { version?: string }).version : undefined;
      return {
        key: fragmentKey(fragment),
        signature: initSig ?? fragmentSignature(fragment, this.blockLookup),
        fragment,
        element: fragmentEl,
        context: contextBase,
      };
    });

    this.renderDecorationsForPage(el, page, pageIndex, resolvedPage);
    return { element: el, fragments: fragmentStates };
  }

  private applySemanticPageOverrides(el: HTMLElement): void {
    if (this.isSemanticFlow) {
      el.style.overflow = 'visible';
      el.style.width = '100%';
      el.style.minWidth = '100%';
    }
  }

  private getEffectivePageStyles(): PageStyles | undefined {
    if (this.isSemanticFlow) {
      const base = this.options.pageStyles ?? {};
      return {
        ...base,
        background: base.background ?? 'var(--sd-layout-page-bg, #fff)',
        boxShadow: 'none',
        border: 'none',
        margin: '0',
      };
    }
    if (this.virtualEnabled && this.layoutMode === 'vertical') {
      // Remove top/bottom margins to avoid double-counting with container gap during virtualization
      const base = this.options.pageStyles ?? {};
      return { ...base, margin: '0 auto' };
    }
    return this.options.pageStyles;
  }

  private renderFragment(
    fragment: Fragment,
    context: FragmentRenderContext,
    sdtBoundary?: SdtBoundaryOptions,
    betweenInfo?: BetweenBorderInfo,
    resolvedItem?: ResolvedPaintItem,
  ): HTMLElement {
    if (fragment.kind === 'para') {
      return this.renderParagraphFragment(
        fragment,
        context,
        sdtBoundary,
        betweenInfo,
        resolvedItem as ResolvedFragmentItem | undefined,
      );
    }
    if (fragment.kind === 'list-item') {
      return this.renderListItemFragment(
        fragment,
        context,
        sdtBoundary,
        betweenInfo,
        resolvedItem as ResolvedFragmentItem | undefined,
      );
    }
    if (fragment.kind === 'image') {
      return this.renderImageFragment(fragment, context, resolvedItem as ResolvedImageItem | undefined);
    }
    if (fragment.kind === 'drawing') {
      return this.renderDrawingFragment(fragment, context, resolvedItem as ResolvedDrawingItem | undefined);
    }
    if (fragment.kind === 'table') {
      return this.renderTableFragment(fragment, context, sdtBoundary, resolvedItem as ResolvedTableItem | undefined);
    }
    throw new Error(`DomPainter: unsupported fragment kind ${(fragment as Fragment).kind}`);
  }

  /**
   * Renders a paragraph fragment with defensive error handling.
   * Falls back to error placeholder on rendering errors to prevent full paint failure.
   *
   * @param fragment - The paragraph fragment to render
   * @param context - Rendering context with page and column information
   * @param sdtBoundary - Optional SDT boundary overrides for multi-fragment containers
   * @returns HTMLElement containing the rendered fragment or error placeholder
   */
  private renderParagraphFragment(
    fragment: ParaFragment,
    context: FragmentRenderContext,
    sdtBoundary?: SdtBoundaryOptions,
    betweenInfo?: BetweenBorderInfo,
    resolvedItem?: ResolvedFragmentItem,
  ): HTMLElement {
    try {
      if (!this.doc) {
        throw new Error('DomPainter: document is not available');
      }

      // Prefer pre-extracted block/measure from the resolved item; fall back to blockLookup
      // for header/footer fragments that don't have a resolved item.
      const { block, measure } = this.resolveBlockAndMeasure<ParagraphBlock, ParagraphMeasure>(
        fragment,
        resolvedItem?.block,
        resolvedItem?.measure,
        'paragraph',
        'paragraph',
        'paragraph block/measure',
      );
      const wordLayout = isMinimalWordLayout(block.attrs?.wordLayout) ? block.attrs.wordLayout : undefined;
      const content = resolvedItem?.content;

      // Prefer resolved item metadata over legacy fragment reads
      const paraContinuesFromPrev = resolvedItem?.continuesFromPrev ?? fragment.continuesFromPrev;
      const paraContinuesOnNext = resolvedItem?.continuesOnNext ?? fragment.continuesOnNext;
      const paraMarkerWidth = resolvedItem?.markerWidth ?? fragment.markerWidth;

      const fragmentEl = this.doc.createElement('div');
      fragmentEl.classList.add(CLASS_NAMES.fragment);

      // For TOC entries, override white-space to prevent wrapping
      const isTocEntry = block.attrs?.isTocEntry;
      // For fragments with markers, allow overflow to show markers positioned at negative left
      const hasMarker = !paraContinuesFromPrev && paraMarkerWidth && wordLayout?.marker;
      // SDT containers need overflow visible for tooltips/labels positioned above
      const hasSdtContainer =
        block.attrs?.sdt?.type === 'documentSection' ||
        block.attrs?.sdt?.type === 'structuredContent' ||
        block.attrs?.containerSdt?.type === 'documentSection' ||
        block.attrs?.containerSdt?.type === 'structuredContent';
      // Negative indents extend text into the margin area, requiring overflow:visible
      const paraIndentForOverflow = block.attrs?.indent;
      const hasNegativeIndent = (paraIndentForOverflow?.left ?? 0) < 0 || (paraIndentForOverflow?.right ?? 0) < 0;
      const styles = isTocEntry
        ? { ...fragmentStyles, whiteSpace: 'nowrap' }
        : hasMarker || hasSdtContainer || hasNegativeIndent
          ? { ...fragmentStyles, overflow: 'visible' }
          : fragmentStyles;
      applyStyles(fragmentEl, styles);
      if (resolvedItem) {
        this.applyResolvedFragmentFrame(fragmentEl, resolvedItem, fragment, context.section);
      } else {
        this.applyFragmentFrame(fragmentEl, fragment, context.section);
      }

      // Add TOC-specific styling class
      if (isTocEntry) {
        fragmentEl.classList.add('superdoc-toc-entry');
      }

      if (paraContinuesFromPrev) {
        fragmentEl.dataset.continuesFromPrev = 'true';
      }
      if (paraContinuesOnNext) {
        fragmentEl.dataset.continuesOnNext = 'true';
      }

      // Use fragment.lines if available (set when paragraph was remeasured for narrower column).
      // Otherwise, fall back to slicing from the original measure.
      const lines = fragment.lines ?? measure.lines.slice(fragment.fromLine, fragment.toLine);
      applyParagraphBlockStyles(fragmentEl, block.attrs);
      const { shadingLayer, borderLayer } = createParagraphDecorationLayers(
        this.doc,
        fragment.width,
        block.attrs,
        betweenInfo,
      );
      if (shadingLayer) {
        fragmentEl.appendChild(shadingLayer);
      }
      if (borderLayer) {
        fragmentEl.appendChild(borderLayer);
      }
      stampBetweenBorderDataset(fragmentEl, betweenInfo);
      if (block.attrs?.styleId) {
        fragmentEl.dataset.styleId = block.attrs.styleId;
        fragmentEl.setAttribute('styleid', block.attrs.styleId);
      }
      this.applySdtDataset(fragmentEl, block.attrs?.sdt);
      this.applyContainerSdtDataset(fragmentEl, block.attrs?.containerSdt);

      // Apply SDT container styling (document sections, structured content blocks)
      applySdtContainerStyling(this.doc, fragmentEl, block.attrs?.sdt, block.attrs?.containerSdt, sdtBoundary);

      // Render drop cap if present (only on the first fragment, not continuation)
      if (content?.dropCap) {
        const dc = content.dropCap;
        const dropCapEl = this.renderDropCap(
          {
            mode: dc.mode,
            run: {
              text: dc.text,
              fontFamily: dc.fontFamily,
              fontSize: dc.fontSize,
              bold: dc.bold,
              italic: dc.italic,
              color: dc.color,
              position: dc.position,
            },
            lines: 0,
          },
          dc.width != null && dc.height != null
            ? { width: dc.width, height: dc.height, lines: 0, mode: dc.mode }
            : undefined,
        );
        fragmentEl.appendChild(dropCapEl);
      } else {
        const dropCapDescriptor = block.attrs?.dropCapDescriptor;
        const dropCapMeasure = measure.dropCap;
        if (dropCapDescriptor && dropCapMeasure && !paraContinuesFromPrev) {
          const dropCapEl = this.renderDropCap(dropCapDescriptor, dropCapMeasure);
          fragmentEl.appendChild(dropCapEl);
        }
      }

      // Remove fragment-level indent so line-level indent handling doesn't double-apply.
      // Include margin properties for negative indents (which use margin instead of padding).
      if (fragmentEl.style.paddingLeft) fragmentEl.style.removeProperty('padding-left');
      if (fragmentEl.style.paddingRight) fragmentEl.style.removeProperty('padding-right');
      if (fragmentEl.style.marginLeft) fragmentEl.style.removeProperty('margin-left');
      if (fragmentEl.style.marginRight) fragmentEl.style.removeProperty('margin-right');
      if (fragmentEl.style.textIndent) fragmentEl.style.removeProperty('text-indent');

      if (content) {
        // ── Resolved path: read pre-computed values from ResolvedParagraphContent ──
        const resolvedMarker = content.marker;

        content.lines.forEach((resolvedLine) => {
          const lineEl = this.renderLine(
            block,
            resolvedLine.line,
            context,
            resolvedLine.availableWidth,
            resolvedLine.lineIndex,
            resolvedLine.skipJustify,
            resolvedLine.resolvedListTextStartPx,
            resolvedLine.indentOffset,
          );

          // Apply pre-computed indent values
          if (!resolvedLine.isListFirstLine) {
            if (resolvedLine.paddingLeftPx > 0) {
              lineEl.style.paddingLeft = `${resolvedLine.paddingLeftPx}px`;
            }
            if (resolvedLine.textIndentPx !== 0) {
              lineEl.style.textIndent = `${resolvedLine.textIndentPx}px`;
            } else if (resolvedLine.lineIndex > 0 || content.continuesFromPrev) {
              // Body lines: reset textIndent to 0 if firstLineOffset would have been set
              // (mirrors the legacy `else if (firstLineOffset && !isListFirstLine)` branch)
              const paraIndent = block.attrs?.indent;
              const suppressFLI = (block.attrs as Record<string, unknown>)?.suppressFirstLineIndent === true;
              const flo = suppressFLI ? 0 : (paraIndent?.firstLine ?? 0) - (paraIndent?.hanging ?? 0);
              if (flo && !resolvedLine.isListFirstLine) {
                lineEl.style.textIndent = '0px';
              }
            }
          }
          if (resolvedLine.paddingRightPx > 0) {
            lineEl.style.paddingRight = `${resolvedLine.paddingRightPx}px`;
          }

          // Render marker on list first line
          if (resolvedLine.isListFirstLine && resolvedMarker) {
            lineEl.style.paddingLeft = `${resolvedMarker.firstLinePaddingLeftPx}px`;

            if (!resolvedMarker.vanish) {
              const markerContainer = this.doc!.createElement('span');
              markerContainer.style.display = 'inline-block';
              markerContainer.style.wordSpacing = '0px';

              const markerEl = this.doc!.createElement('span');
              markerEl.classList.add('superdoc-paragraph-marker');
              markerEl.textContent = resolvedMarker.text;
              markerEl.style.pointerEvents = 'none';

              markerContainer.style.position = 'relative';
              if (resolvedMarker.justification === 'right') {
                markerContainer.style.position = 'absolute';
                markerContainer.style.left = `${resolvedMarker.markerStartPx}px`;
              } else if (resolvedMarker.justification === 'center') {
                markerContainer.style.position = 'absolute';
                markerContainer.style.left = `${resolvedMarker.markerStartPx - (resolvedMarker.centerPaddingAdjustPx ?? 0)}px`;
                lineEl.style.paddingLeft =
                  parseFloat(lineEl.style.paddingLeft) + (resolvedMarker.centerPaddingAdjustPx ?? 0) + 'px';
              }

              markerEl.style.fontFamily =
                toCssFontFamily(resolvedMarker.run.fontFamily) ?? resolvedMarker.run.fontFamily;
              markerEl.style.fontSize = `${resolvedMarker.run.fontSize}px`;
              markerEl.style.fontWeight = resolvedMarker.run.bold ? 'bold' : '';
              markerEl.style.fontStyle = resolvedMarker.run.italic ? 'italic' : '';
              if (resolvedMarker.run.color) {
                markerEl.style.color = resolvedMarker.run.color;
              }
              if (resolvedMarker.run.letterSpacing != null) {
                markerEl.style.letterSpacing = `${resolvedMarker.run.letterSpacing}px`;
              }
              markerContainer.appendChild(markerEl);

              if (resolvedMarker.suffix === 'tab') {
                const tabEl = this.doc!.createElement('span');
                tabEl.className = 'superdoc-tab';
                tabEl.innerHTML = '&nbsp;';
                tabEl.style.display = 'inline-block';
                tabEl.style.wordSpacing = '0px';
                tabEl.style.width = `${resolvedMarker.suffixWidthPx}px`;
                lineEl.prepend(tabEl);
              } else if (resolvedMarker.suffix === 'space') {
                const spaceEl = this.doc!.createElement('span');
                spaceEl.classList.add('superdoc-marker-suffix-space');
                spaceEl.style.wordSpacing = '0px';
                spaceEl.textContent = '\u00A0';
                lineEl.prepend(spaceEl);
              }
              lineEl.prepend(markerContainer);
            }
          }
          this.capturePaintSnapshotLine(lineEl, context, {
            inTableFragment: false,
            inTableParagraph: false,
          });
          fragmentEl.appendChild(lineEl);
        });
      } else {
        // ── Legacy path: compute everything from block attrs and measure ──
        const paraIndent = block.attrs?.indent;
        const paraIndentLeft = paraIndent?.left ?? 0;
        const paraIndentRight = paraIndent?.right ?? 0;
        const suppressFirstLineIndent = (block.attrs as Record<string, unknown>)?.suppressFirstLineIndent === true;
        const firstLineOffset = suppressFirstLineIndent ? 0 : (paraIndent?.firstLine ?? 0) - (paraIndent?.hanging ?? 0);

        const lastRun = block.runs.length > 0 ? block.runs[block.runs.length - 1] : null;
        const paragraphEndsWithLineBreak = lastRun?.kind === 'lineBreak';

        const listFirstLineTextStartPx =
          !paraContinuesFromPrev && paraMarkerWidth && wordLayout?.marker
            ? resolvePainterListTextStartPx({
                wordLayout,
                indentLeftPx: paraIndentLeft,
                hangingIndentPx: paraIndent?.hanging ?? 0,
                firstLineIndentPx: paraIndent?.firstLine ?? 0,
                markerTextWidthPx: fragment.markerTextWidth,
              })
            : undefined;

        const shouldUseSharedInlinePrefixGeometry =
          !paraContinuesFromPrev &&
          paraMarkerWidth &&
          wordLayout?.marker?.justification === 'left' &&
          wordLayout.firstLineIndentMode !== true &&
          typeof fragment.markerTextWidth === 'number' &&
          Number.isFinite(fragment.markerTextWidth) &&
          fragment.markerTextWidth >= 0;
        const listFirstLineMarkerGeometry = shouldUseSharedInlinePrefixGeometry
          ? resolvePainterListMarkerGeometry({
              wordLayout,
              indentLeftPx: paraIndentLeft,
              hangingIndentPx: paraIndent?.hanging ?? 0,
              firstLineIndentPx: paraIndent?.firstLine ?? 0,
              markerTextWidthPx: fragment.markerTextWidth,
            })
          : undefined;

        let listTabWidth = 0;
        let markerStartPos = 0;
        if (!paraContinuesFromPrev && paraMarkerWidth && wordLayout?.marker) {
          const markerTextWidth = fragment.markerTextWidth!;
          const anchorPoint = paraIndentLeft - (paraIndent?.hanging ?? 0) + (paraIndent?.firstLine ?? 0);
          const markerJustification = wordLayout.marker.justification ?? 'left';
          let currentPos: number;
          if (markerJustification === 'left') {
            markerStartPos = anchorPoint;
            currentPos = markerStartPos + markerTextWidth;
          } else if (markerJustification === 'right') {
            markerStartPos = anchorPoint - markerTextWidth;
            currentPos = anchorPoint;
          } else {
            markerStartPos = anchorPoint - markerTextWidth / 2;
            currentPos = markerStartPos + markerTextWidth;
          }

          const suffix = wordLayout.marker.suffix ?? 'tab';
          if (listFirstLineMarkerGeometry && (suffix === 'tab' || suffix === 'space')) {
            listTabWidth = listFirstLineMarkerGeometry.suffixWidthPx;
          } else if (suffix === 'tab') {
            listTabWidth = computeTabWidth(
              currentPos,
              markerJustification,
              wordLayout.tabsPx,
              paraIndent?.hanging,
              paraIndent?.firstLine,
              paraIndentLeft,
            );
          } else if (suffix === 'space') {
            listTabWidth = 4;
          }
        }

        lines.forEach((line, index) => {
          const hasExplicitSegmentPositioning = line.segments?.some((segment) => segment.x !== undefined) === true;
          const hasListFirstLineMarker = index === 0 && !paraContinuesFromPrev && paraMarkerWidth && wordLayout?.marker;
          const shouldUseResolvedListTextStart =
            hasListFirstLineMarker && hasExplicitSegmentPositioning && listFirstLineTextStartPx != null;

          const positiveIndentReduction = Math.max(0, paraIndentLeft) + Math.max(0, paraIndentRight);
          const fallbackAvailableWidth = Math.max(0, fragment.width - positiveIndentReduction);
          let availableWidthOverride =
            line.maxWidth != null ? Math.min(line.maxWidth, fallbackAvailableWidth) : fallbackAvailableWidth;

          if (shouldUseResolvedListTextStart) {
            availableWidthOverride = fragment.width - listFirstLineTextStartPx - Math.max(0, paraIndentRight);
          }

          // Adjust availableWidth for first-line text indent (hanging indent).
          const isFirstLine = index === 0 && !fragment.continuesFromPrev;
          const isListFirstLine = Boolean(hasListFirstLineMarker && fragment.markerTextWidth);
          if (isFirstLine && !isListFirstLine && !hasExplicitSegmentPositioning) {
            availableWidthOverride = adjustAvailableWidthForTextIndent(
              availableWidthOverride,
              firstLineOffset,
              line.maxWidth,
            );
          }

          const isLastLineOfFragment = index === lines.length - 1;
          const isLastLineOfParagraph = isLastLineOfFragment && !paraContinuesOnNext;
          const shouldSkipJustifyForLastLine = isLastLineOfParagraph && !paragraphEndsWithLineBreak;

          const lineEl = this.renderLine(
            block,
            line,
            context,
            availableWidthOverride,
            fragment.fromLine + index,
            shouldSkipJustifyForLastLine,
            shouldUseResolvedListTextStart ? listFirstLineTextStartPx : undefined,
          );

          if (!isListFirstLine) {
            if (hasExplicitSegmentPositioning) {
              if (isFirstLine && firstLineOffset !== 0) {
                const effectiveLeftIndent = paraIndentLeft < 0 ? 0 : paraIndentLeft;
                const adjustedPadding = effectiveLeftIndent + firstLineOffset;
                if (adjustedPadding > 0) {
                  lineEl.style.paddingLeft = `${adjustedPadding}px`;
                }
              }
            } else if (paraIndentLeft && paraIndentLeft > 0) {
              lineEl.style.paddingLeft = `${paraIndentLeft}px`;
            } else if (
              !isFirstLine &&
              paraIndent?.hanging &&
              paraIndent.hanging > 0 &&
              !(paraIndentLeft != null && paraIndentLeft < 0)
            ) {
              lineEl.style.paddingLeft = `${paraIndent.hanging}px`;
            }
          }
          if (paraIndentRight && paraIndentRight > 0) {
            lineEl.style.paddingRight = `${paraIndentRight}px`;
          }
          if (!paraContinuesFromPrev && index === 0 && firstLineOffset && !isListFirstLine) {
            if (!hasExplicitSegmentPositioning) {
              lineEl.style.textIndent = `${firstLineOffset}px`;
            }
          } else if (firstLineOffset && !isListFirstLine) {
            lineEl.style.textIndent = '0px';
          }

          if (isListFirstLine) {
            const marker = wordLayout?.marker;
            if (!marker) {
              return;
            }
            lineEl.style.paddingLeft = `${paraIndentLeft + (paraIndent?.firstLine ?? 0) - (paraIndent?.hanging ?? 0)}px`;

            if (!marker.run.vanish) {
              const markerContainer = this.doc!.createElement('span');
              markerContainer.style.display = 'inline-block';
              markerContainer.style.wordSpacing = '0px';

              const markerEl = this.doc!.createElement('span');
              markerEl.classList.add('superdoc-paragraph-marker');
              markerEl.textContent = marker.markerText ?? '';
              markerEl.style.pointerEvents = 'none';

              const markerJustification = marker.justification ?? 'left';

              markerContainer.style.position = 'relative';
              if (markerJustification === 'right') {
                markerContainer.style.position = 'absolute';
                markerContainer.style.left = `${markerStartPos}px`;
              } else if (markerJustification === 'center') {
                markerContainer.style.position = 'absolute';
                markerContainer.style.left = `${markerStartPos - fragment.markerTextWidth! / 2}px`;
                lineEl.style.paddingLeft = parseFloat(lineEl.style.paddingLeft) + fragment.markerTextWidth! / 2 + 'px';
              }

              markerEl.style.fontFamily = toCssFontFamily(marker.run.fontFamily) ?? marker.run.fontFamily;
              markerEl.style.fontSize = `${marker.run.fontSize}px`;
              markerEl.style.fontWeight = marker.run.bold ? 'bold' : '';
              markerEl.style.fontStyle = marker.run.italic ? 'italic' : '';
              if (marker.run.color) {
                markerEl.style.color = marker.run.color;
              }
              if (marker.run.letterSpacing != null) {
                markerEl.style.letterSpacing = `${marker.run.letterSpacing}px`;
              }
              markerContainer.appendChild(markerEl);

              const suffix = marker.suffix ?? 'tab';
              if (suffix === 'tab') {
                const tabEl = this.doc!.createElement('span');
                tabEl.className = 'superdoc-tab';
                tabEl.innerHTML = '&nbsp;';
                tabEl.style.display = 'inline-block';
                tabEl.style.wordSpacing = '0px';
                tabEl.style.width = `${listTabWidth}px`;
                lineEl.prepend(tabEl);
              } else if (suffix === 'space') {
                const spaceEl = this.doc!.createElement('span');
                spaceEl.classList.add('superdoc-marker-suffix-space');
                spaceEl.style.wordSpacing = '0px';
                spaceEl.textContent = '\u00A0';
                lineEl.prepend(spaceEl);
              }
              lineEl.prepend(markerContainer);
            }
          }
          this.capturePaintSnapshotLine(lineEl, context, {
            inTableFragment: false,
            inTableParagraph: false,
          });
          fragmentEl.appendChild(lineEl);
        });
      }

      return fragmentEl;
    } catch (error) {
      console.error('[DomPainter] Fragment rendering failed:', { fragment, error });
      return this.createErrorPlaceholder(fragment.blockId, error);
    }
  }

  /**
   * Creates an error placeholder element for failed fragment renders.
   * Prevents entire paint operation from failing due to single fragment error.
   *
   * @param blockId - The block ID that failed to render
   * @param error - The error that occurred
   * @returns HTMLElement showing the error
   */
  private createErrorPlaceholder(blockId: string, error: unknown): HTMLElement {
    if (!this.doc) {
      // Fallback if doc is not available
      const el = document.createElement('div');
      el.className = 'render-error-placeholder';
      el.style.cssText = 'color: red; padding: 4px; border: 1px solid red; background: #fee;';
      el.textContent = `[Render Error: ${blockId}]`;
      return el;
    }

    const el = this.doc.createElement('div');
    el.className = 'render-error-placeholder';
    el.style.cssText = 'color: red; padding: 4px; border: 1px solid red; background: #fee;';
    el.textContent = `[Render Error: ${blockId}]`;
    if (error instanceof Error) {
      el.title = error.message;
    }
    return el;
  }

  /**
   * Renders a drop cap element as a floated span at the start of a paragraph.
   *
   * Drop caps are large initial letters that span multiple lines of text.
   * This method creates a floated element with the drop cap letter styled
   * according to the descriptor's run properties.
   *
   * @param descriptor - The drop cap descriptor with text and styling info
   * @param measure - The measured dimensions of the drop cap
   * @returns HTMLElement containing the rendered drop cap
   */
  private renderDropCap(descriptor: DropCapDescriptor, measure: ParagraphMeasure['dropCap']): HTMLElement {
    const doc = this.doc!;
    const { run, mode } = descriptor;

    const dropCapEl = doc.createElement('span');
    dropCapEl.classList.add('superdoc-drop-cap');
    dropCapEl.textContent = run.text;

    // Apply styling from the run
    dropCapEl.style.fontFamily = run.fontFamily;
    dropCapEl.style.fontSize = `${run.fontSize}px`;
    if (run.bold) {
      dropCapEl.style.fontWeight = 'bold';
    }
    if (run.italic) {
      dropCapEl.style.fontStyle = 'italic';
    }
    if (run.color) {
      dropCapEl.style.color = run.color;
    }

    // Position the drop cap based on mode
    if (mode === 'drop') {
      // Float left so text wraps around it
      dropCapEl.style.float = 'left';
      dropCapEl.style.marginRight = '4px'; // Small gap between drop cap and text
      dropCapEl.style.lineHeight = '1'; // Prevent extra line height from affecting layout
    } else if (mode === 'margin') {
      // Position in the margin (left of the text area)
      dropCapEl.style.position = 'absolute';
      dropCapEl.style.left = '0';
      dropCapEl.style.lineHeight = '1';
    }

    // Apply vertical position offset if specified
    if (run.position && run.position !== 0) {
      dropCapEl.style.position = dropCapEl.style.position || 'relative';
      dropCapEl.style.top = `${run.position}px`;
    }

    // Set dimensions from measurement
    if (measure) {
      dropCapEl.style.width = `${measure.width}px`;
      dropCapEl.style.height = `${measure.height}px`;
    }

    return dropCapEl;
  }

  private renderListItemFragment(
    fragment: ListItemFragment,
    context: FragmentRenderContext,
    sdtBoundary?: SdtBoundaryOptions,
    betweenInfo?: BetweenBorderInfo,
    resolvedItem?: ResolvedFragmentItem,
  ): HTMLElement {
    try {
      if (!this.doc) {
        throw new Error('DomPainter: document is not available');
      }

      // Prefer pre-extracted block/measure from the resolved item; fall back to blockLookup
      // for header/footer fragments that don't have a resolved item.
      const { block, measure } = this.resolveBlockAndMeasure<ListBlock, ListMeasure>(
        fragment,
        resolvedItem?.block,
        resolvedItem?.measure,
        'list',
        'list',
        'list block/measure',
      );
      const item = block.items.find((entry) => entry.id === fragment.itemId);
      const itemMeasure = measure.items.find((entry) => entry.itemId === fragment.itemId);
      if (!item || !itemMeasure) {
        throw new Error(`DomPainter: missing list item ${fragment.itemId}`);
      }

      // Prefer resolved item metadata over legacy fragment reads
      const listContinuesFromPrev = resolvedItem?.continuesFromPrev ?? fragment.continuesFromPrev;
      const listContinuesOnNext = resolvedItem?.continuesOnNext ?? fragment.continuesOnNext;
      const listMarkerWidth = resolvedItem?.markerWidth ?? fragment.markerWidth;

      const fragmentEl = this.doc.createElement('div');
      fragmentEl.classList.add(CLASS_NAMES.fragment, `${CLASS_NAMES.fragment}-list-item`);
      applyStyles(fragmentEl, fragmentStyles);
      if (resolvedItem) {
        this.applyResolvedListItemWrapperFrame(fragmentEl, fragment, resolvedItem, context.section);
      } else {
        fragmentEl.style.left = `${fragment.x - fragment.markerWidth}px`;
        fragmentEl.style.top = `${fragment.y}px`;
        fragmentEl.style.width = `${fragment.markerWidth + fragment.width}px`;
        fragmentEl.dataset.blockId = fragment.blockId;
      }
      fragmentEl.dataset.itemId = fragment.itemId;

      const paragraphMetadata = item.paragraph.attrs?.sdt;
      this.applySdtDataset(fragmentEl, paragraphMetadata);

      // Apply SDT container styling (document sections, structured content blocks)
      applySdtContainerStyling(
        this.doc,
        fragmentEl,
        paragraphMetadata,
        item.paragraph.attrs?.containerSdt,
        sdtBoundary,
      );

      if (listContinuesFromPrev) {
        fragmentEl.dataset.continuesFromPrev = 'true';
      }
      if (listContinuesOnNext) {
        fragmentEl.dataset.continuesOnNext = 'true';
      }

      const markerEl = this.doc.createElement('span');
      markerEl.classList.add('superdoc-list-marker');

      // Track B: Use marker styling from wordLayout if available
      const wordLayout: MinimalWordLayout | undefined = item.paragraph.attrs?.wordLayout as
        | MinimalWordLayout
        | undefined;
      const marker = wordLayout?.marker;
      if (marker) {
        markerEl.textContent = marker.markerText ?? null;
        markerEl.style.display = 'inline-block';
        markerEl.style.width = `${Math.max(0, listMarkerWidth - LIST_MARKER_GAP)}px`;
        markerEl.style.paddingRight = `${LIST_MARKER_GAP}px`;
        markerEl.style.textAlign = marker.justification ?? 'left';

        // Apply marker run styling with font fallback chain
        markerEl.style.fontFamily = toCssFontFamily(marker.run.fontFamily) ?? marker.run.fontFamily;
        markerEl.style.fontSize = `${marker.run.fontSize}px`;
        if (marker.run.bold) markerEl.style.fontWeight = 'bold';
        if (marker.run.italic) markerEl.style.fontStyle = 'italic';
        if (marker.run.color) markerEl.style.color = marker.run.color;
        if (marker.run.letterSpacing) markerEl.style.letterSpacing = `${marker.run.letterSpacing}px`;
      } else {
        // Fallback: legacy behavior
        markerEl.textContent = item.marker.text;
        markerEl.style.display = 'inline-block';
        markerEl.style.width = `${Math.max(0, listMarkerWidth - LIST_MARKER_GAP)}px`;
        markerEl.style.paddingRight = `${LIST_MARKER_GAP}px`;
        if (item.marker.align) {
          markerEl.style.textAlign = item.marker.align;
        }
      }
      fragmentEl.appendChild(markerEl);

      const contentEl = this.doc.createElement('div');
      contentEl.classList.add('superdoc-list-content');
      this.applySdtDataset(contentEl, paragraphMetadata);
      contentEl.style.display = 'inline-block';
      contentEl.style.position = 'relative';
      contentEl.style.width = `${fragment.width}px`;
      const lines = itemMeasure.paragraph.lines.slice(fragment.fromLine, fragment.toLine);
      // Track B: preserve indent for wordLayout-based lists to show hierarchy
      const contentAttrs = wordLayout ? item.paragraph.attrs : stripListIndent(item.paragraph.attrs);
      applyParagraphBlockStyles(contentEl, contentAttrs);
      const { shadingLayer, borderLayer } = createParagraphDecorationLayers(
        this.doc,
        fragment.width,
        contentAttrs,
        betweenInfo,
      );
      if (shadingLayer) {
        contentEl.appendChild(shadingLayer);
      }
      if (borderLayer) {
        contentEl.appendChild(borderLayer);
      }
      stampBetweenBorderDataset(fragmentEl, betweenInfo);
      // INTENTIONAL DIVERGENCE: Force list content to left alignment
      // Microsoft Word DOES justify list paragraphs when alignment is 'justify',
      // but we intentionally keep lists left-aligned to match user expectations
      // and current behavior. This is a documented design decision, not a bug.
      // Applied AFTER applyParagraphBlockStyles (which may set justify from paragraph properties).
      contentEl.style.textAlign = 'left';
      // Override alignment to left for list content rendering
      const paraForList: ParagraphBlock = {
        ...item.paragraph,
        attrs: { ...(item.paragraph.attrs || {}), alignment: 'left' },
      };
      lines.forEach((line, idx) => {
        const lineEl = this.renderLine(paraForList, line, context, fragment.width, fragment.fromLine + idx, true);
        this.capturePaintSnapshotLine(lineEl, context, {
          inTableFragment: false,
          inTableParagraph: false,
        });
        contentEl.appendChild(lineEl);
      });
      fragmentEl.appendChild(contentEl);

      return fragmentEl;
    } catch (error) {
      console.error('[DomPainter] List item fragment rendering failed:', { fragment, error });
      return this.createErrorPlaceholder(fragment.blockId, error);
    }
  }

  private renderImageFragment(
    fragment: ImageFragment,
    context: FragmentRenderContext,
    resolvedItem?: ResolvedImageItem,
  ): HTMLElement {
    try {
      // Prefer pre-extracted block from the resolved item; fall back to blockLookup
      // for header/footer fragments that don't have a resolved item.
      const block = this.resolveBlock<ImageBlock>(fragment, resolvedItem?.block, 'image', 'image block');

      if (!this.doc) {
        throw new Error('DomPainter: document is not available');
      }

      const fragmentEl = this.doc.createElement('div');
      fragmentEl.classList.add(CLASS_NAMES.fragment, DOM_CLASS_NAMES.IMAGE_FRAGMENT);
      applyStyles(fragmentEl, fragmentStyles);
      if (resolvedItem) {
        this.applyResolvedFragmentFrame(fragmentEl, resolvedItem, fragment, context.section);
      } else {
        this.applyFragmentFrame(fragmentEl, fragment, context.section);
        fragmentEl.style.height = `${fragment.height}px`;
        this.applyFragmentWrapperZIndex(fragmentEl, fragment);
      }
      this.applySdtDataset(fragmentEl, block.attrs?.sdt);
      this.applyContainerSdtDataset(fragmentEl, block.attrs?.containerSdt);

      // Add block ID for PM transaction targeting
      if (block.id) {
        fragmentEl.setAttribute('data-sd-block-id', block.id);
      }

      // Add PM position markers for transaction targeting
      const imgPmStart = resolvedItem?.pmStart ?? fragment.pmStart;
      if (imgPmStart != null) {
        fragmentEl.dataset.pmStart = String(imgPmStart);
      }
      const imgPmEnd = resolvedItem?.pmEnd ?? fragment.pmEnd;
      if (imgPmEnd != null) {
        fragmentEl.dataset.pmEnd = String(imgPmEnd);
      }

      // Add metadata for interactive image resizing (skip watermarks - they should not be interactive)
      const imgMetadata = resolvedItem?.metadata ?? fragment.metadata;
      if (imgMetadata && !block.attrs?.vmlWatermark) {
        fragmentEl.setAttribute('data-image-metadata', JSON.stringify(imgMetadata));
      }

      // behindDoc images are supported via z-index; suppress noisy debug logs

      const img = this.doc.createElement('img');
      if (block.src) {
        img.src = block.src;
      }
      img.alt = block.alt ?? '';
      img.style.width = '100%';
      img.style.height = '100%';
      img.style.objectFit = block.objectFit ?? 'contain';
      // MS Word anchors stretched images to top-left, clipping from right/bottom
      if (block.objectFit === 'cover') {
        img.style.objectPosition = 'left top';
      }
      const imageClipPath = resolveBlockClipPath(block);
      applyImageClipPath(img, imageClipPath, { clipContainer: fragmentEl });
      img.style.display = block.display === 'inline' ? 'inline-block' : 'block';

      // Apply rotation and flip transforms from OOXML a:xfrm
      const transforms: string[] = [];

      // Calculate translation offset to keep top-left corner fixed when rotating
      if (block.rotation != null && block.rotation !== 0) {
        const angleRad = (block.rotation * Math.PI) / 180;
        const w = block.width ?? fragment.width;
        const h = block.height ?? fragment.height;

        // Calculate how much the top-left corner moves when rotating around center
        // Top-left corner starts at (0, 0) in element space
        // Center is at (w/2, h/2)
        // After rotation, we need to translate to keep top-left at (0, 0)
        const cosA = Math.cos(angleRad);
        const sinA = Math.sin(angleRad);

        // Position of top-left corner after rotation (relative to original top-left)
        const newTopLeftX = (w / 2) * (1 - cosA) + (h / 2) * sinA;
        const newTopLeftY = (w / 2) * sinA + (h / 2) * (1 - cosA);

        transforms.push(`translate(${-newTopLeftX}px, ${-newTopLeftY}px)`);
        transforms.push(`rotate(${block.rotation}deg)`);
      }
      if (block.flipH) {
        transforms.push('scaleX(-1)');
      }
      if (block.flipV) {
        transforms.push('scaleY(-1)');
      }

      if (transforms.length > 0) {
        img.style.transform = transforms.join(' ');
        img.style.transformOrigin = 'center';
      }

      const filters = buildImageFilters(block);
      if (filters.length > 0) {
        img.style.filter = filters.join(' ');
      }

      // Wrap in anchor when block has a DrawingML hyperlink (a:hlinkClick)
      const imageChild = this.buildImageHyperlinkAnchor(img, block.hyperlink, 'block');
      fragmentEl.appendChild(imageChild);

      return fragmentEl;
    } catch (error) {
      console.error('[DomPainter] Image fragment rendering failed:', { fragment, error });
      return this.createErrorPlaceholder(fragment.blockId, error);
    }
  }

  /**
   * Optionally wrap an image element in an anchor for DrawingML hyperlinks (a:hlinkClick).
   *
   * When `hyperlink` is present and its URL passes sanitization, returns an
   * `<a class="superdoc-link">` wrapping `imageEl`. The existing EditorInputManager
   * click-delegation on `a.superdoc-link` handles both viewing-mode navigation and
   * editing-mode event dispatch automatically, with no extra wiring needed here.
   *
   * When `hyperlink` is absent or the URL fails sanitization the original element
   * is returned unchanged.
   *
   * @param imageEl   - The image element (img or span wrapper) to potentially wrap.
   * @param hyperlink - Hyperlink metadata from the ImageBlock/ImageRun, or undefined.
   * @param display   - CSS display value for the anchor: 'block' for fragment images,
   *                    'inline-block' for inline runs.
   */
  private buildImageHyperlinkAnchor(
    imageEl: HTMLElement,
    hyperlink: ImageHyperlink | undefined,
    display: 'block' | 'inline-block',
  ): HTMLElement {
    if (!hyperlink?.url || !this.doc) return imageEl;

    const sanitized = sanitizeHref(hyperlink.url);
    if (!sanitized?.href) return imageEl;

    const anchor = this.doc.createElement('a');
    anchor.href = sanitized.href;
    anchor.classList.add('superdoc-link');

    if (sanitized.protocol === 'http' || sanitized.protocol === 'https') {
      anchor.target = '_blank';
      anchor.rel = 'noopener noreferrer';
    }

    const tooltipSource =
      typeof hyperlink.tooltip === 'string' && hyperlink.tooltip.trim().length > 0 ? hyperlink.tooltip : hyperlink.url;
    const tooltipResult = encodeTooltip(tooltipSource);
    if (tooltipResult?.text) {
      anchor.title = tooltipResult.text;
    }

    for (const titledElement of [imageEl, ...Array.from(imageEl.querySelectorAll('[title]'))]) {
      titledElement.removeAttribute('title');
    }

    // Accessibility: explicit role and keyboard focus (mirrors applyLinkAttributes for text links)
    anchor.setAttribute('role', 'link');
    anchor.setAttribute('tabindex', '0');

    if (display === 'block') {
      anchor.style.cssText = 'display: block; width: 100%; height: 100%; cursor: pointer;';
    } else {
      // inline-block preserves the image's layout box inside a paragraph line
      anchor.style.display = 'inline-block';
      anchor.style.lineHeight = '0';
      anchor.style.cursor = 'pointer';
      anchor.style.verticalAlign = imageEl.style.verticalAlign || 'bottom';
    }

    anchor.appendChild(imageEl);
    return anchor;
  }

  private renderDrawingFragment(
    fragment: DrawingFragment,
    context: FragmentRenderContext,
    resolvedItem?: ResolvedDrawingItem,
  ): HTMLElement {
    try {
      // Prefer pre-extracted block from the resolved item; fall back to blockLookup
      // for header/footer fragments that don't have a resolved item.
      const block = this.resolveBlock<DrawingBlock>(fragment, resolvedItem?.block, 'drawing', 'drawing block');
      if (!this.doc) {
        throw new Error('DomPainter: document is not available');
      }
      const isVectorShapeBlock = block.kind === 'drawing' && block.drawingKind === 'vectorShape';

      const fragmentEl = this.doc.createElement('div');
      fragmentEl.classList.add(CLASS_NAMES.fragment, 'superdoc-drawing-fragment');
      applyStyles(fragmentEl, fragmentStyles);
      if (resolvedItem) {
        this.applyResolvedFragmentFrame(fragmentEl, resolvedItem, fragment, context.section);
      } else {
        this.applyFragmentFrame(fragmentEl, fragment, context.section);
        fragmentEl.style.height = `${fragment.height}px`;
        this.applyFragmentWrapperZIndex(fragmentEl, fragment);
      }
      fragmentEl.style.position = 'absolute';
      fragmentEl.style.overflow = 'hidden';

      const innerWrapper = this.doc.createElement('div');
      innerWrapper.classList.add('superdoc-drawing-inner');
      innerWrapper.style.position = 'absolute';
      innerWrapper.style.left = '50%';
      innerWrapper.style.top = '50%';
      innerWrapper.style.width = `${fragment.geometry.width}px`;
      innerWrapper.style.height = `${fragment.geometry.height}px`;
      innerWrapper.style.transformOrigin = 'center';

      const scale = fragment.scale ?? 1;
      const transforms: string[] = ['translate(-50%, -50%)'];
      if (!isVectorShapeBlock) {
        transforms.push(`rotate(${fragment.geometry.rotation ?? 0}deg)`);
        transforms.push(`scaleX(${fragment.geometry.flipH ? -1 : 1})`);
        transforms.push(`scaleY(${fragment.geometry.flipV ? -1 : 1})`);
      }
      transforms.push(`scale(${scale})`);
      innerWrapper.style.transform = transforms.join(' ');

      innerWrapper.appendChild(this.renderDrawingContent(block, fragment, context));
      fragmentEl.appendChild(innerWrapper);

      return fragmentEl;
    } catch (error) {
      console.error('[DomPainter] Drawing fragment rendering failed:', { fragment, error });
      return this.createErrorPlaceholder(fragment.blockId, error);
    }
  }

  private renderDrawingContent(
    block: DrawingBlock,
    fragment: DrawingFragment,
    context?: FragmentRenderContext,
  ): HTMLElement {
    if (!this.doc) {
      throw new Error('DomPainter: document is not available');
    }
    if (block.drawingKind === 'image') {
      return this.createDrawingImageElement(block);
    }
    if (block.drawingKind === 'vectorShape') {
      return this.createVectorShapeElement(block, fragment.geometry, true, 1, 1, context);
    }
    if (block.drawingKind === 'shapeGroup') {
      return this.createShapeGroupElement(block, context);
    }
    if (block.drawingKind === 'chart') {
      return this.createChartElement(block);
    }
    return this.createDrawingPlaceholder();
  }

  private createDrawingImageElement(block: DrawingBlock): HTMLElement {
    const drawing = block as ImageDrawing;
    const img = this.doc!.createElement('img');
    img.classList.add('superdoc-drawing-image');
    if (drawing.src) {
      img.src = drawing.src;
    }
    img.alt = drawing.alt ?? '';
    img.style.width = '100%';
    img.style.height = '100%';
    img.style.objectFit = drawing.objectFit ?? 'contain';
    // MS Word anchors stretched images to top-left, clipping from right/bottom
    if (drawing.objectFit === 'cover') {
      img.style.objectPosition = 'left top';
    }
    const imageClipPath = resolveBlockClipPath(drawing);
    applyImageClipPath(img, imageClipPath);
    img.style.display = 'block';
    return img;
  }

  private createVectorShapeElement(
    block: VectorShapeDrawingWithEffects,
    geometry?: DrawingGeometry,
    applyTransforms = false,
    groupScaleX = 1,
    groupScaleY = 1,
    context?: FragmentRenderContext,
  ): HTMLElement {
    const container = this.doc!.createElement('div');
    container.classList.add('superdoc-vector-shape');
    container.style.width = '100%';
    container.style.height = '100%';
    container.style.position = 'relative';
    container.style.overflow = 'hidden';

    const { offsetX, offsetY, innerWidth, innerHeight } = this.getEffectExtentMetrics(block, geometry);
    const contentContainer = this.doc!.createElement('div');
    contentContainer.style.position = 'absolute';
    contentContainer.style.left = `${offsetX}px`;
    contentContainer.style.top = `${offsetY}px`;
    contentContainer.style.width = `${innerWidth}px`;
    contentContainer.style.height = `${innerHeight}px`;

    // Custom geometry takes priority — shapeKind may carry a schema default ('rect')
    // even when the source shape only had a:custGeom and no a:prstGeom.
    const customGeomSvg = block.customGeometry ? this.tryCreateCustomGeometrySvg(block, innerWidth, innerHeight) : null;
    const svgMarkup =
      !customGeomSvg && block.shapeKind ? this.tryCreatePresetSvg(block, innerWidth, innerHeight) : null;
    const resolvedSvgMarkup = customGeomSvg || svgMarkup;

    if (resolvedSvgMarkup) {
      const svgElement = this.parseSafeSvg(resolvedSvgMarkup);
      if (svgElement) {
        svgElement.setAttribute('width', '100%');
        svgElement.setAttribute('height', '100%');
        svgElement.style.display = 'block';

        // Apply gradient fill if present
        if (block.fillColor && typeof block.fillColor === 'object') {
          if ('type' in block.fillColor && block.fillColor.type === 'gradient') {
            applyGradientToSVG(svgElement, block.fillColor as GradientFill);
          } else if ('type' in block.fillColor && block.fillColor.type === 'solidWithAlpha') {
            applyAlphaToSVG(svgElement, block.fillColor as SolidFillWithAlpha);
          }
        }

        this.applyLineEnds(svgElement, block);
        if (applyTransforms && geometry) {
          this.applyVectorShapeTransforms(svgElement, geometry);
        }
        contentContainer.appendChild(svgElement);

        // Apply text content as an overlay div (not inside SVG to avoid viewBox scaling)
        if (block.textContent && block.textContent.parts.length > 0) {
          const textDiv = this.createFallbackTextElement(
            block.textContent,
            block.textAlign ?? 'center',
            block.textVerticalAlign,
            block.textInsets,
            groupScaleX,
            groupScaleY,
            context,
          );
          contentContainer.appendChild(textDiv);
        }

        container.appendChild(contentContainer);
        return container;
      }
    }

    // Fallback rendering when no preset shape SVG is available
    this.applyFallbackShapeStyle(contentContainer, block);

    // Apply text content to fallback rendering
    if (block.textContent && block.textContent.parts.length > 0) {
      const textDiv = this.createFallbackTextElement(
        block.textContent,
        block.textAlign ?? 'center',
        block.textVerticalAlign,
        block.textInsets,
        groupScaleX,
        groupScaleY,
        context,
      );
      contentContainer.appendChild(textDiv);
    }

    if (applyTransforms && geometry) {
      this.applyVectorShapeTransforms(contentContainer, geometry);
    }
    container.appendChild(contentContainer);
    return container;
  }

  /**
   * Apply fill and stroke styles to a fallback shape container
   */
  private applyFallbackShapeStyle(container: HTMLElement, block: VectorShapeDrawing): void {
    // Handle fill color
    if (block.fillColor === null) {
      container.style.background = 'none';
    } else if (typeof block.fillColor === 'string') {
      container.style.background = block.fillColor;
    } else if (typeof block.fillColor === 'object' && 'type' in block.fillColor) {
      if (block.fillColor.type === 'solidWithAlpha') {
        const alpha = (block.fillColor as SolidFillWithAlpha).alpha;
        const color = (block.fillColor as SolidFillWithAlpha).color;
        container.style.background = color;
        container.style.opacity = alpha.toString();
      } else if (block.fillColor.type === 'gradient') {
        // For CSS gradients in fallback, we'd need to convert
        // For now, use a placeholder color
        container.style.background = 'rgba(15, 23, 42, 0.1)';
      }
    } else {
      container.style.background = 'rgba(15, 23, 42, 0.1)';
    }

    // Handle stroke color
    if (block.strokeColor === null) {
      container.style.border = 'none';
    } else if (typeof block.strokeColor === 'string') {
      const strokeWidth = block.strokeWidth ?? 1;
      container.style.border = `${strokeWidth}px solid ${block.strokeColor}`;
    } else {
      container.style.border = '1px solid rgba(15, 23, 42, 0.3)';
    }
  }

  /**
   * Create a fallback text element for shapes without SVG
   * @param textContent - Text content with formatting
   * @param textAlign - Horizontal text alignment
   * @param textVerticalAlign - Vertical text alignment (top, center, bottom)
   * @param textInsets - Text insets in pixels (top, right, bottom, left)
   * @param groupScaleX - Scale factor applied by parent group (for counter-scaling)
   * @param groupScaleY - Scale factor applied by parent group (for counter-scaling)
   */
  private createFallbackTextElement(
    textContent: ShapeTextContent,
    textAlign: string,
    textVerticalAlign?: 'top' | 'center' | 'bottom',
    textInsets?: { top: number; right: number; bottom: number; left: number },
    groupScaleX = 1,
    groupScaleY = 1,
    context?: FragmentRenderContext,
  ): HTMLElement {
    const textDiv = this.doc!.createElement('div');
    textDiv.style.position = 'absolute';
    textDiv.style.top = '0';
    textDiv.style.left = '0';
    textDiv.style.width = '100%';
    textDiv.style.height = '100%';
    textDiv.style.display = 'flex';
    textDiv.style.flexDirection = 'column';

    // Use extracted vertical alignment or default to top per OOXML spec
    // In flex-direction: column, justifyContent controls vertical (main axis)
    const verticalAlign = textVerticalAlign ?? 'top';
    if (verticalAlign === 'top') {
      textDiv.style.justifyContent = 'flex-start';
    } else if (verticalAlign === 'bottom') {
      textDiv.style.justifyContent = 'flex-end';
    } else {
      textDiv.style.justifyContent = 'center';
    }

    // Use extracted text insets or default to 10px all around
    if (textInsets) {
      textDiv.style.padding = `${textInsets.top}px ${textInsets.right}px ${textInsets.bottom}px ${textInsets.left}px`;
    } else {
      textDiv.style.padding = '10px';
    }

    textDiv.style.boxSizing = 'border-box';
    textDiv.style.wordWrap = 'break-word';
    textDiv.style.overflowWrap = 'break-word';
    textDiv.style.overflow = 'hidden';
    // min-width: 0 allows flex container to shrink below content size for text wrapping
    textDiv.style.minWidth = '0';
    // Set explicit base font-size to prevent CSS inheritance issues
    // Individual spans will override with their own sizes from textContent.parts
    textDiv.style.fontSize = '12px';
    textDiv.style.lineHeight = '1.2';

    // Horizontal text alignment uses CSS text-align property
    // Note: justifyContent is already set above for vertical alignment
    if (textAlign === 'center') {
      textDiv.style.textAlign = 'center';
    } else if (textAlign === 'right' || textAlign === 'r') {
      textDiv.style.textAlign = 'right';
    } else {
      textDiv.style.textAlign = 'left';
    }

    // Create paragraphs by splitting on line breaks
    let currentParagraph = this.doc!.createElement('div');
    // Set width to 100% to enable text wrapping within the shape bounds
    currentParagraph.style.width = '100%';
    // min-width: 0 prevents flex item from overflowing (flexbox default is min-width: auto)
    currentParagraph.style.minWidth = '0';
    // Override inherited white-space: pre from parent fragment to allow text wrapping
    currentParagraph.style.whiteSpace = 'normal';

    const resolvePartText = (part: ShapeTextContent['parts'][number]) => {
      if (part.fieldType === 'PAGE') {
        return context?.pageNumberText ?? String(context?.pageNumber ?? 1);
      }
      if (part.fieldType === 'NUMPAGES') {
        return String(context?.totalPages ?? 1);
      }
      return part.text;
    };

    textContent.parts.forEach((part) => {
      if (part.isLineBreak) {
        // Finish current paragraph and start a new one
        textDiv.appendChild(currentParagraph);
        currentParagraph = this.doc!.createElement('div');
        currentParagraph.style.width = '100%';
        currentParagraph.style.minWidth = '0';
        currentParagraph.style.whiteSpace = 'normal';
        // Empty paragraphs create extra spacing (blank line)
        if (part.isEmptyParagraph) {
          currentParagraph.style.minHeight = '1em';
        }
      } else {
        const span = this.doc!.createElement('span');
        span.textContent = resolvePartText(part);
        if (part.formatting) {
          if (part.formatting.bold) {
            span.style.fontWeight = 'bold';
          }
          if (part.formatting.italic) {
            span.style.fontStyle = 'italic';
          }
          if (part.formatting.fontFamily) {
            span.style.fontFamily = part.formatting.fontFamily;
          }
          if (part.formatting.color) {
            // Validate and normalize color format (handles both with and without # prefix)
            const validatedColor = validateHexColor(part.formatting.color);
            if (validatedColor) {
              span.style.color = validatedColor;
            }
          }
          if (part.formatting.fontSize) {
            span.style.fontSize = `${part.formatting.fontSize}px`;
          }
          if (part.formatting.letterSpacing != null) {
            span.style.letterSpacing = `${part.formatting.letterSpacing}px`;
          }
        }
        currentParagraph.appendChild(span);
      }
    });

    // Add the final paragraph
    textDiv.appendChild(currentParagraph);

    return textDiv;
  }

  private tryCreatePresetSvg(
    block: VectorShapeDrawing,
    widthOverride?: number,
    heightOverride?: number,
  ): string | null {
    try {
      // For preset shapes, we need to pass string colors only
      // Gradients and alpha will be applied after SVG is created
      // null means explicitly "no fill" (from <a:noFill/> or fillRef idx="0"), so use 'none'
      // undefined means no explicit fill, so we let the preset library use its default
      let fillColor: string | undefined;
      if (block.fillColor === null) {
        fillColor = 'none';
      } else if (typeof block.fillColor === 'string') {
        fillColor = block.fillColor;
      }
      const strokeColor =
        block.strokeColor === null ? 'none' : typeof block.strokeColor === 'string' ? block.strokeColor : undefined;

      // Special case: handle line-like shapes directly since getPresetShapeSvg doesn't support them well
      if (block.shapeKind === 'line' || block.shapeKind === 'straightConnector1') {
        const width = widthOverride ?? block.geometry.width;
        const height = heightOverride ?? block.geometry.height;
        const stroke = strokeColor ?? '#000000';
        const strokeWidth = block.strokeWidth ?? 1;

        return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
  <line x1="0" y1="0" x2="${width}" y2="${height}" stroke="${stroke}" stroke-width="${strokeWidth}" />
</svg>`;
      }

      return getPresetShapeSvg({
        preset: block.shapeKind ?? '',
        styleOverrides: () => ({
          fill: fillColor,
          stroke: strokeColor,
          strokeWidth: block.strokeWidth ?? undefined,
        }),
        width: widthOverride ?? block.geometry.width,
        height: heightOverride ?? block.geometry.height,
      });
    } catch (error) {
      console.warn(`[DomPainter] Unable to render preset shape "${block.shapeKind}":`, error);
      return null;
    }
  }

  /**
   * Creates an SVG string from custom geometry path data (a:custGeom).
   * Each path in the custom geometry has its own coordinate space (w × h) which is
   * mapped to the shape's actual dimensions via the SVG viewBox.
   */
  private tryCreateCustomGeometrySvg(block: VectorShapeDrawing, width: number, height: number): string | null {
    const custGeom = block.customGeometry;
    if (!custGeom?.paths?.length) return null;

    let fillColor: string;
    if (block.fillColor === null) {
      fillColor = 'none';
    } else if (typeof block.fillColor === 'string') {
      fillColor = block.fillColor;
    } else {
      // Gradient / solidWithAlpha: use a placeholder fill so that downstream
      // applyGradientToSVG / applyAlphaToSVG (which skip fill="none") can
      // target these elements and replace the fill.
      fillColor = '#000000';
    }
    const strokeColor =
      block.strokeColor === null ? 'none' : typeof block.strokeColor === 'string' ? block.strokeColor : 'none';
    const strokeWidth = block.strokeColor === null ? 0 : (block.strokeWidth ?? 0);

    // Build SVG paths. Each path has its own coordinate space (w × h).
    // Use the first path's coordinate space for the viewBox, and scale subsequent paths if needed.
    const firstPath = custGeom.paths[0];
    const viewW = firstPath.w || width;
    const viewH = firstPath.h || height;

    // Degenerate: zero-dimension viewBox is invalid SVG — skip rendering.
    if (viewW === 0 || viewH === 0) return null;

    // When the SVG viewBox maps to a non-uniform aspect ratio (common with group transforms),
    // thin fill borders can become sub-pixel on one axis. Add a hairline stroke matching the
    // fill color with vector-effect="non-scaling-stroke" so edges remain at least 0.5px visible.
    const needsEdgeStroke = fillColor !== 'none' && strokeColor === 'none';
    const edgeStroke = needsEdgeStroke
      ? ` stroke="${fillColor}" stroke-width="0.5" vector-effect="non-scaling-stroke"`
      : '';

    const pathElements = custGeom.paths
      .map((p) => {
        // If this path has a different coordinate space, apply a transform to map it
        const pathW = p.w || viewW;
        const pathH = p.h || viewH;
        const needsTransform = pathW !== viewW || pathH !== viewH;
        const scaleX = viewW / pathW;
        const scaleY = viewH / pathH;
        const transform = needsTransform ? ` transform="scale(${scaleX}, ${scaleY})"` : '';
        const strokeAttr =
          strokeColor !== 'none' ? ` stroke="${strokeColor}" stroke-width="${strokeWidth}"` : edgeStroke;
        return `<path d="${p.d}" fill="${fillColor}" fill-rule="evenodd"${strokeAttr}${transform} />`;
      })
      .join('\n  ');

    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${viewW} ${viewH}" preserveAspectRatio="none">
  ${pathElements}
</svg>`;
  }

  private parseSafeSvg(markup: string): SVGElement | null {
    const DOMParserCtor = this.doc?.defaultView?.DOMParser ?? (typeof DOMParser !== 'undefined' ? DOMParser : null);
    if (!DOMParserCtor) {
      return null;
    }
    const parser = new DOMParserCtor();
    const parsed = parser.parseFromString(markup, 'image/svg+xml');
    if (!parsed || parsed.getElementsByTagName('parsererror').length > 0) {
      return null;
    }
    // documentElement might be HTMLElement or Element, use type guard via unknown
    const svgElement = parsed.documentElement as unknown as SVGElement | null;
    if (!svgElement) return null;
    this.stripUnsafeSvgContent(svgElement);
    // Safe cast: importNode preserves the element type, and we've verified it's an SVGElement
    const imported = this.doc?.importNode(svgElement, true);
    return imported ? (imported as unknown as SVGElement) : null;
  }

  private stripUnsafeSvgContent(element: Element): void {
    element.querySelectorAll('script').forEach((script) => script.remove());
    const sanitize = (node: Element) => {
      Array.from(node.attributes).forEach((attr) => {
        if (attr.name.toLowerCase().startsWith('on')) {
          node.removeAttribute(attr.name);
        }
      });
      Array.from(node.children).forEach((child) => {
        sanitize(child as Element);
      });
    };
    sanitize(element);
  }

  private getEffectExtentMetrics(
    block: VectorShapeDrawingWithEffects,
    geometry?: DrawingGeometry,
  ): {
    offsetX: number;
    offsetY: number;
    innerWidth: number;
    innerHeight: number;
  } {
    const left = block.effectExtent?.left ?? 0;
    const top = block.effectExtent?.top ?? 0;
    const right = block.effectExtent?.right ?? 0;
    const bottom = block.effectExtent?.bottom ?? 0;
    const sourceGeometry = geometry ?? block.geometry;
    const width = sourceGeometry.width ?? 0;
    const height = sourceGeometry.height ?? 0;
    const innerWidth = Math.max(0, width - left - right);
    const innerHeight = Math.max(0, height - top - bottom);
    return { offsetX: left, offsetY: top, innerWidth, innerHeight };
  }

  private applyLineEnds(svgElement: SVGElement, block: VectorShapeDrawingWithEffects): void {
    const lineEnds = block.lineEnds;
    if (!lineEnds) return;
    if (block.strokeColor === null) return;
    const strokeColor = typeof block.strokeColor === 'string' ? block.strokeColor : '#000000';
    const strokeWidth = block.strokeWidth ?? 1;
    if (strokeWidth <= 0) return;

    const target = this.findLineEndTarget(svgElement);
    if (!target) return;

    const defs = this.ensureSvgDefs(svgElement);
    const baseId = this.sanitizeSvgId(`sd-line-${block.id}`);

    if (lineEnds.tail) {
      const id = `${baseId}-tail`;
      this.appendLineEndMarker(
        defs,
        id,
        lineEnds.tail,
        strokeColor,
        strokeWidth,
        true,
        block.effectExtent ?? undefined,
      );
      target.setAttribute('marker-start', `url(#${id})`);
    }

    if (lineEnds.head) {
      const id = `${baseId}-head`;
      this.appendLineEndMarker(
        defs,
        id,
        lineEnds.head,
        strokeColor,
        strokeWidth,
        false,
        block.effectExtent ?? undefined,
      );
      target.setAttribute('marker-end', `url(#${id})`);
    }
  }

  private findLineEndTarget(svgElement: SVGElement): SVGElement | null {
    const line = svgElement.querySelector('line');
    if (line) return line as SVGElement;
    const path = svgElement.querySelector('path');
    if (path) return path as SVGElement;
    const polyline = svgElement.querySelector('polyline');
    return polyline as SVGElement | null;
  }

  private ensureSvgDefs(svgElement: SVGElement): SVGDefsElement {
    const existing = svgElement.querySelector('defs');
    if (existing) return existing as SVGDefsElement;
    const defs = this.doc!.createElementNS('http://www.w3.org/2000/svg', 'defs');
    svgElement.insertBefore(defs, svgElement.firstChild);
    return defs;
  }

  private appendLineEndMarker(
    defs: SVGDefsElement,
    id: string,
    lineEnd: LineEnd,
    strokeColor: string,
    _strokeWidth: number,
    isStart: boolean,
    effectExtent?: EffectExtent,
  ): void {
    if (defs.querySelector(`#${id}`)) return;

    const marker = this.doc!.createElementNS('http://www.w3.org/2000/svg', 'marker');
    marker.setAttribute('id', id);
    marker.setAttribute('viewBox', '0 0 10 10');
    marker.setAttribute('orient', 'auto');

    const sizeScale = (value?: string): number => {
      if (value === 'sm') return 0.75;
      if (value === 'lg') return 1.25;
      return 1;
    };
    const effectMax = effectExtent
      ? Math.max(effectExtent.left ?? 0, effectExtent.right ?? 0, effectExtent.top ?? 0, effectExtent.bottom ?? 0)
      : 0;
    const useEffectExtent = Number.isFinite(effectMax) && effectMax > 0;
    const markerWidth = useEffectExtent ? effectMax * 2 : 4 * sizeScale(lineEnd.length);
    const markerHeight = useEffectExtent ? effectMax * 2 : 4 * sizeScale(lineEnd.width);
    marker.setAttribute('markerUnits', useEffectExtent ? 'userSpaceOnUse' : 'strokeWidth');
    marker.setAttribute('markerWidth', markerWidth.toString());
    marker.setAttribute('markerHeight', markerHeight.toString());
    marker.setAttribute('refX', isStart ? '0' : '10');
    marker.setAttribute('refY', '5');

    const shape = this.createLineEndShape(lineEnd.type ?? 'triangle', strokeColor, isStart);
    marker.appendChild(shape);
    defs.appendChild(marker);
  }

  private createLineEndShape(type: string, strokeColor: string, isStart: boolean): SVGElement {
    const normalized = type.toLowerCase();
    if (normalized === 'diamond') {
      const path = this.doc!.createElementNS('http://www.w3.org/2000/svg', 'path');
      path.setAttribute('d', 'M 0 5 L 5 0 L 10 5 L 5 10 Z');
      path.setAttribute('fill', strokeColor);
      path.setAttribute('stroke', 'none');
      return path;
    }
    if (normalized === 'oval') {
      const circle = this.doc!.createElementNS('http://www.w3.org/2000/svg', 'circle');
      circle.setAttribute('cx', '5');
      circle.setAttribute('cy', '5');
      circle.setAttribute('r', '5');
      circle.setAttribute('fill', strokeColor);
      circle.setAttribute('stroke', 'none');
      return circle;
    }

    const path = this.doc!.createElementNS('http://www.w3.org/2000/svg', 'path');
    const d = isStart ? 'M 10 0 L 0 5 L 10 10 Z' : 'M 0 0 L 10 5 L 0 10 Z';
    path.setAttribute('d', d);
    path.setAttribute('fill', strokeColor);
    path.setAttribute('stroke', 'none');
    return path;
  }

  private sanitizeSvgId(value: string): string {
    return value.replace(/[^a-zA-Z0-9_-]/g, '');
  }

  private applyVectorShapeTransforms(target: HTMLElement | SVGElement, geometry: DrawingGeometry): void {
    const transforms: string[] = [];
    if (geometry.rotation) {
      transforms.push(`rotate(${geometry.rotation}deg)`);
    }
    if (geometry.flipH) {
      transforms.push('scaleX(-1)');
    }
    if (geometry.flipV) {
      transforms.push('scaleY(-1)');
    }
    if (transforms.length > 0) {
      target.style.transformOrigin = 'center';
      target.style.transform = transforms.join(' ');
    } else {
      target.style.removeProperty('transform');
      target.style.removeProperty('transform-origin');
    }
  }

  private createShapeGroupElement(block: ShapeGroupDrawing, context?: FragmentRenderContext): HTMLElement {
    const groupEl = this.doc!.createElement('div');
    groupEl.classList.add('superdoc-shape-group');
    groupEl.style.position = 'relative';
    groupEl.style.width = '100%';
    groupEl.style.height = '100%';

    const groupTransform = block.groupTransform;
    let contentContainer: HTMLElement = groupEl;

    const visibleWidth = groupTransform?.width ?? block.geometry.width ?? 0;
    const visibleHeight = groupTransform?.height ?? block.geometry.height ?? 0;

    if (groupTransform) {
      const inner = this.doc!.createElement('div');
      inner.style.position = 'absolute';
      inner.style.left = '0';
      inner.style.top = '0';
      // Container at visible dimensions. Children use pre-scaled positions/sizes.
      inner.style.width = `${Math.max(1, visibleWidth)}px`;
      inner.style.height = `${Math.max(1, visibleHeight)}px`;
      groupEl.appendChild(inner);
      contentContainer = inner;
    }

    block.shapes.forEach((child) => {
      const childContent = this.createGroupChildContent(child, 1, 1, context);
      if (!childContent) return;
      const attrs = (child as ShapeGroupChild).attrs ?? {};
      const wrapper = this.doc!.createElement('div');
      wrapper.classList.add('superdoc-shape-group__child');
      wrapper.style.position = 'absolute';

      // Children use pre-scaled (visual-space) positions/sizes from import.
      wrapper.style.left = `${Number(attrs.x ?? 0)}px`;
      wrapper.style.top = `${Number(attrs.y ?? 0)}px`;

      const childW = typeof attrs.width === 'number' ? attrs.width : block.geometry.width;
      const childH = typeof attrs.height === 'number' ? attrs.height : block.geometry.height;
      wrapper.style.width = `${Math.max(1, childW)}px`;
      wrapper.style.height = `${Math.max(1, childH)}px`;

      wrapper.style.transformOrigin = 'center';
      const transforms: string[] = [];
      if (attrs.rotation) {
        transforms.push(`rotate(${attrs.rotation}deg)`);
      }
      if (attrs.flipH) {
        transforms.push('scaleX(-1)');
      }
      if (attrs.flipV) {
        transforms.push('scaleY(-1)');
      }
      if (transforms.length > 0) {
        wrapper.style.transform = transforms.join(' ');
      }
      childContent.style.width = '100%';
      childContent.style.height = '100%';
      wrapper.appendChild(childContent);
      contentContainer.appendChild(wrapper);
    });

    return groupEl;
  }

  private createGroupChildContent(
    child: ShapeGroupChild,
    groupScaleX: number = 1,
    groupScaleY: number = 1,
    context?: FragmentRenderContext,
  ): HTMLElement | null {
    // Type narrowing with explicit checks to help TypeScript distinguish union members
    if (child.shapeType === 'vectorShape' && 'fillColor' in child.attrs) {
      // After this check, child should be ShapeGroupVectorChild
      const attrs = child.attrs as PositionedDrawingGeometry &
        VectorShapeStyle & {
          kind?: string;
          customGeometry?: CustomGeometryData;
          shapeId?: string;
          shapeName?: string;
          textContent?: ShapeTextContent;
          textAlign?: string;
          lineEnds?: LineEnds;
        };
      const childGeometry = {
        width: attrs.width ?? 0,
        height: attrs.height ?? 0,
        rotation: attrs.rotation ?? 0,
        flipH: attrs.flipH ?? false,
        flipV: attrs.flipV ?? false,
      };
      const vectorChild: VectorShapeDrawingWithEffects = {
        drawingKind: 'vectorShape',
        kind: 'drawing',
        id: `${attrs.shapeId ?? child.shapeType}`,
        geometry: childGeometry,
        padding: undefined,
        margin: undefined,
        anchor: undefined,
        wrap: undefined,
        attrs: child.attrs,
        drawingContentId: undefined,
        drawingContent: undefined,
        shapeKind: attrs.kind,
        customGeometry: attrs.customGeometry,
        fillColor: attrs.fillColor,
        strokeColor: attrs.strokeColor,
        strokeWidth: attrs.strokeWidth,
        lineEnds: attrs.lineEnds,
        textContent: attrs.textContent,
        textAlign: attrs.textAlign,
        textVerticalAlign: attrs.textVerticalAlign,
        textInsets: attrs.textInsets,
      };
      // Pass geometry and scale factors to ensure text overlay has correct dimensions
      return this.createVectorShapeElement(vectorChild, childGeometry, false, groupScaleX, groupScaleY, context);
    }
    if (child.shapeType === 'image' && 'src' in child.attrs) {
      // After this check, child should be ShapeGroupImageChild
      const attrs = child.attrs as PositionedDrawingGeometry & {
        src: string;
        alt?: string;
        clipPath?: string;
      };
      const img = this.doc!.createElement('img');
      img.src = attrs.src;
      img.alt = attrs.alt ?? '';
      img.style.objectFit = 'contain';
      img.style.display = 'block';
      applyImageClipPath(img, attrs.clipPath);
      return img;
    }
    return this.createDrawingPlaceholder();
  }

  private createDrawingPlaceholder(): HTMLElement {
    const placeholder = this.doc!.createElement('div');
    placeholder.classList.add('superdoc-drawing-placeholder');
    placeholder.style.width = '100%';
    placeholder.style.height = '100%';
    placeholder.style.background =
      'repeating-linear-gradient(45deg, rgba(15,23,42,0.1), rgba(15,23,42,0.1) 6px, rgba(15,23,42,0.2) 6px, rgba(15,23,42,0.2) 12px)';
    placeholder.style.border = '1px dashed rgba(15, 23, 42, 0.3)';
    return placeholder;
  }

  // ============================================================================
  // Chart Rendering
  // ============================================================================

  /**
   * Create an SVG chart element from a ChartDrawing block.
   * Delegates to the chart-renderer module for clean separation.
   */
  private createChartElement(block: ChartDrawing): HTMLElement {
    return renderChartToElement(this.doc!, block.chartData, block.geometry);
  }

  private resolveTableRenderData(
    fragment: TableFragment,
    resolvedItem?: ResolvedTableItem,
  ): {
    block: TableBlock;
    measure: TableMeasure;
    cellSpacingPx: number;
    effectiveColumnWidths: number[];
  } {
    if (resolvedItem) {
      return {
        block: resolvedItem.block,
        measure: resolvedItem.measure,
        cellSpacingPx: resolvedItem.cellSpacingPx,
        effectiveColumnWidths: resolvedItem.effectiveColumnWidths,
      };
    }

    const lookup = this.blockLookup.get(fragment.blockId);
    if (!lookup || lookup.block.kind !== 'table' || lookup.measure.kind !== 'table') {
      throw new Error(`DomPainter: missing table block for fragment ${fragment.blockId}`);
    }

    const block = lookup.block as TableBlock;
    const measure = lookup.measure as TableMeasure;

    return {
      block,
      measure,
      cellSpacingPx: measure.cellSpacingPx ?? getCellSpacingPx(block.attrs?.cellSpacing),
      effectiveColumnWidths: fragment.columnWidths ?? measure.columnWidths,
    };
  }

  private renderTableFragment(
    fragment: TableFragment,
    context: FragmentRenderContext,
    sdtBoundary?: SdtBoundaryOptions,
    resolvedItem?: ResolvedTableItem,
  ): HTMLElement {
    try {
      if (!this.doc) {
        throw new Error('DomPainter: document is not available');
      }

      // Wrap applyFragmentFrame to capture section from context.
      // Table cell inner fragments always stay on the legacy frame path for now.
      const applyFragmentFrameWithSection = (el: HTMLElement, frag: Fragment): void => {
        this.applyFragmentFrame(el, frag, context.section);
      };

      // Word justifies text inside table cells, but not the final line unless the
      // paragraph ends with an explicit line break.
      const renderLineForTableCell = (
        block: ParagraphBlock,
        line: Line,
        ctx: FragmentRenderContext,
        lineIndex: number,
        isLastLine: boolean,
        resolvedListTextStartPx?: number,
      ): HTMLElement => {
        const lastRun = block.runs.length > 0 ? block.runs[block.runs.length - 1] : null;
        const paragraphEndsWithLineBreak = lastRun?.kind === 'lineBreak';
        const shouldSkipJustify = isLastLine && !paragraphEndsWithLineBreak;

        return this.renderLine(block, line, ctx, undefined, lineIndex, shouldSkipJustify, resolvedListTextStartPx);
      };

      /**
       * Renders drawing content that lives inside a table cell.
       * Table-cell vector shapes intentionally skip outer geometry transforms.
       */
      const renderDrawingContentForTableCell = (block: DrawingBlock): HTMLElement => {
        if (block.drawingKind === 'image') {
          return this.createDrawingImageElement(block);
        }
        if (block.drawingKind === 'shapeGroup') {
          return this.createShapeGroupElement(block, context);
        }
        if (block.drawingKind === 'vectorShape') {
          return this.createVectorShapeElement(block, block.geometry, false, 1, 1, context);
        }
        if (block.drawingKind === 'chart') {
          return this.createChartElement(block);
        }
        return this.createDrawingPlaceholder();
      };

      const tableRenderData = this.resolveTableRenderData(fragment, resolvedItem);

      const el = renderTableFragmentElement({
        doc: this.doc,
        fragment,
        context,
        block: tableRenderData.block,
        measure: tableRenderData.measure,
        cellSpacingPx: tableRenderData.cellSpacingPx,
        effectiveColumnWidths: tableRenderData.effectiveColumnWidths,
        sdtBoundary,
        renderLine: renderLineForTableCell,
        captureLineSnapshot: (lineEl, lineContext, options) => {
          this.capturePaintSnapshotLine(lineEl, lineContext, {
            inTableFragment: true,
            inTableParagraph: options?.inTableParagraph ?? false,
            wrapperEl: options?.wrapperEl,
          });
        },
        renderDrawingContent: renderDrawingContentForTableCell,
        applyFragmentFrame: applyFragmentFrameWithSection,
        applySdtDataset: this.applySdtDataset.bind(this),
        applyContainerSdtDataset: this.applyContainerSdtDataset.bind(this),
        applyStyles,
      });

      // Override outer wrapper positioning with resolved data when available.
      // Inner cell fragments still use legacy applyFragmentFrame via deps closure.
      if (resolvedItem) {
        this.applyResolvedFragmentFrame(el, resolvedItem, fragment, context.section);
      }

      return el;
    } catch (error) {
      console.error('[DomPainter] Table fragment rendering failed:', { fragment, error });
      return this.createErrorPlaceholder(fragment.blockId, error);
    }
  }

  /**
   * Extract link data from a run, including sanitization.
   * @returns Sanitized link data or null if invalid/missing
   */
  private extractLinkData(run: Run): LinkRenderData | null {
    if (run.kind === 'tab' || run.kind === 'image' || run.kind === 'lineBreak' || run.kind === 'math') {
      return null;
    }
    const link = (run as TextRun).link as FlowRunLink | undefined;
    if (!link) {
      return null;
    }
    return this.buildLinkRenderData(link);
  }

  private buildLinkRenderData(link: FlowRunLink): LinkRenderData | null {
    const dataset = buildLinkDataset(link);
    const sanitized = typeof link.href === 'string' ? sanitizeHref(link.href) : null;
    const anchorHref = normalizeAnchor(link.anchor ?? link.name ?? '');
    let href: string | null = sanitized?.href ?? anchorHref;
    if (link.version === 2) {
      href = appendDocLocation(href, link.docLocation ?? null);
    }

    // Track metrics: successful sanitization
    if (sanitized) {
      linkMetrics.sanitized++;

      // Check for homograph if hostname has non-ASCII (in raw href before URL parsing)
      if (sanitized.href && typeof link.href === 'string') {
        const hostStartIndex = link.href.indexOf('://') + 3;
        let hostEndIndex = link.href.indexOf('/', hostStartIndex);
        if (hostEndIndex === -1) {
          hostEndIndex = link.href.indexOf('?', hostStartIndex);
        }
        if (hostEndIndex === -1) {
          hostEndIndex = link.href.indexOf('#', hostStartIndex);
        }
        if (hostEndIndex === -1) {
          hostEndIndex = link.href.length;
        }
        const rawHostname = link.href.slice(hostStartIndex, hostEndIndex);
        if (rawHostname && /[^\x00-\x7F]/.test(rawHostname)) {
          linkMetrics.homographWarnings++;
        }
      }
    }

    // Defense-in-depth: Enforce maximum URL length even if sanitization was bypassed
    if (sanitized && sanitized.href.length > MAX_HREF_LENGTH) {
      console.warn(`[DomPainter] Rejecting URL exceeding ${MAX_HREF_LENGTH} characters`);
      linkMetrics.blocked++;
      return { blocked: true, dataset: { [LINK_DATASET_KEYS.blocked]: 'true' } };
    }

    if (!href) {
      if (typeof link.href === 'string' && link.href.trim()) {
        dataset[LINK_DATASET_KEYS.blocked] = 'true';
        console.warn(`[DomPainter] Blocked potentially unsafe URL: ${link.href.slice(0, 50)}`);
        linkMetrics.blocked++;
        // Track invalid protocol if sanitized was null
        if (!sanitized) {
          linkMetrics.invalidProtocol++;
        }
        return { blocked: true, dataset };
      }
      // Check if there was an anchor/name that failed validation
      const hadAnchor = (link.anchor ?? link.name ?? null) != null;
      if (Object.keys(dataset).length > 0 || hadAnchor) {
        dataset[LINK_DATASET_KEYS.blocked] = 'true';
        linkMetrics.blocked++;
        return { blocked: true, dataset };
      }
      return null;
    }

    const target = resolveLinkTarget(link, sanitized);
    const rel = resolveLinkRel(link, target);
    const tooltipSource = link.version === 2 ? (link.tooltip ?? link.title) : link.title;
    const tooltipResult = tooltipSource ? encodeTooltip(tooltipSource) : null;
    // Use raw text - browser will escape when setting attribute
    const tooltip = tooltipResult?.text ?? null;

    // Signal when tooltip is truncated
    if (tooltipResult?.wasTruncated) {
      dataset[LINK_DATASET_KEYS.truncated] = 'true';
    }

    return {
      href,
      target,
      rel,
      tooltip,
      dataset: Object.keys(dataset).length > 0 ? dataset : undefined,
      blocked: false,
    };
  }

  /**
   * Apply tooltip accessibility using aria-describedby for better screen reader support.
   * Creates a visually-hidden element containing the tooltip text and links it to the anchor.
   *
   * @param elem - The anchor element to enhance
   * @param tooltip - The tooltip text to make accessible
   * @returns The unique ID generated for this link
   */
  private applyTooltipAccessibility(elem: HTMLAnchorElement, tooltip: string | null): string {
    const linkId = `superdoc-link-${++this.linkIdCounter}`;
    elem.id = linkId;

    if (!tooltip || !this.doc) return linkId;

    // Keep title attribute for visual tooltip (browser default)
    elem.setAttribute('title', tooltip);

    // Create visually-hidden element for screen readers
    const descId = `link-desc-${linkId}`;
    const descElem = this.doc.createElement('span');
    descElem.id = descId;
    descElem.className = 'superdoc-sr-only'; // Screen reader only class
    descElem.textContent = tooltip;

    // Insert description element after the link
    // Note: We'll insert it as a sibling in the parent line element
    if (elem.parentElement) {
      elem.parentElement.appendChild(descElem);
      // Reference from link only if we successfully added the description element
      elem.setAttribute('aria-describedby', descId);
    } else {
      // Element not yet in DOM - accessibility feature will degrade gracefully
      // The title attribute will still provide tooltip functionality
      console.warn('[DomPainter] Unable to add aria-describedby for tooltip (element not in DOM)');
    }

    return linkId;
  }

  /**
   * Enhance accessibility of a link element with ARIA labels and attributes.
   * Adds descriptive ARIA labels for ambiguous text and target=_blank links (WCAG 2.4.4).
   *
   * @param elem - The anchor element to enhance
   * @param linkData - Link metadata including href and target
   * @param textContent - The visible link text to analyze for ambiguity
   */
  private enhanceAccessibility(elem: HTMLAnchorElement, linkData: LinkRenderData, textContent: string): void {
    if (!linkData.href) return;

    const trimmedText = textContent.trim().toLowerCase();

    // Check if link text is ambiguous (e.g., "click here", "read more")
    if (AMBIGUOUS_LINK_PATTERNS.test(trimmedText)) {
      try {
        const url = new URL(linkData.href);
        const hostname = url.hostname.replace(/^www\./, '');

        // Generate descriptive aria-label for screen readers
        const ariaLabel = `${textContent.trim()} - ${hostname}`;
        elem.setAttribute('aria-label', ariaLabel);
        return; // Exit early since we've set the label
      } catch {
        // If URL parsing fails, add generic label
        elem.setAttribute('aria-label', `${textContent.trim()} - external link`);
        return;
      }
    }

    // Add aria-label for external links without one (indicates new tab)
    if (linkData.target === '_blank' && !elem.getAttribute('aria-label')) {
      elem.setAttribute('aria-label', `${textContent.trim()} (opens in new tab)`);
    }
  }

  /**
   * Apply link attributes to an anchor element.
   */
  private applyLinkAttributes(elem: HTMLAnchorElement, linkData: LinkRenderData): void {
    if (!linkData.href) return;
    elem.href = linkData.href;
    elem.classList.add('superdoc-link');

    if (linkData.target) {
      elem.target = linkData.target;
    } else {
      elem.removeAttribute('target');
    }
    if (linkData.rel) {
      elem.rel = linkData.rel;
    } else {
      elem.removeAttribute('rel');
    }
    if (linkData.tooltip) {
      elem.title = linkData.tooltip;
    } else {
      elem.removeAttribute('title');
    }

    // Explicitly set role for clarity (though <a> with href has implicit role="link")
    elem.setAttribute('role', 'link');

    // Ensure link is keyboard accessible (should be default for <a>, but verify)
    elem.setAttribute('tabindex', '0');

    // Note: Click handling is done via event delegation in EditorInputManager,
    // not per-element handlers. This avoids duplicate event dispatching.
  }

  /**
   * Render a single run as an HTML element (span or anchor).
   */
  /**
   * Type guard to check if a run is an image run.
   */
  private isImageRun(run: Run): run is ImageRun {
    return run.kind === 'image';
  }

  /**
   * Type guard to check if a run is a line break run.
   */
  private isLineBreakRun(run: Run): run is import('@superdoc/contracts').LineBreakRun {
    return run.kind === 'lineBreak';
  }

  /**
   * Type guard to check if a run is a break run.
   */
  private isBreakRun(run: Run): run is import('@superdoc/contracts').BreakRun {
    return run.kind === 'break';
  }

  /**
   * Type guard to check if a run is a field annotation run.
   */
  private isFieldAnnotationRun(run: Run): run is FieldAnnotationRun {
    return run.kind === 'fieldAnnotation';
  }

  /**
   * Type guard to check if a run is a math run.
   */
  private isMathRun(run: Run): run is MathRun {
    return run.kind === 'math';
  }

  /**
   * Render a math run as a MathML element wrapped in a span.
   * Follows the same pattern as renderImageRun — sets explicit dimensions.
   */
  private renderMathRun(run: MathRun): HTMLElement | null {
    if (!this.doc) return null;
    const wrapper = this.doc.createElement('span');
    wrapper.className = 'sd-math';
    wrapper.style.display = 'inline-block';
    wrapper.style.verticalAlign = 'middle';
    // Let browser auto-size to MathML content; estimated dimensions are for layout only
    wrapper.style.minWidth = `${run.width}px`;
    wrapper.style.minHeight = `${run.height}px`;
    wrapper.dataset.layoutEpoch = String(this.layoutEpoch ?? 0);

    const mathEl = convertOmmlToMathml(run.ommlJson, this.doc);
    if (mathEl) {
      wrapper.appendChild(mathEl);
    } else {
      // Fallback: render plain text content
      wrapper.textContent = run.textContent || '';
    }

    if (run.pmStart != null) wrapper.dataset.pmStart = String(run.pmStart);
    if (run.pmEnd != null) wrapper.dataset.pmEnd = String(run.pmEnd);

    return wrapper;
  }

  private renderRun(
    run: Run,
    context: FragmentRenderContext,
    trackedConfig?: TrackedChangesRenderConfig,
  ): HTMLElement | null {
    // Handle ImageRun
    if (this.isImageRun(run)) {
      return this.renderImageRun(run);
    }

    // Handle FieldAnnotationRun - inline pill-styled form fields
    if (this.isFieldAnnotationRun(run)) {
      return this.renderFieldAnnotationRun(run);
    }

    // Handle MathRun - inline math rendered as MathML
    if (this.isMathRun(run)) {
      return this.renderMathRun(run);
    }

    // Handle LineBreakRun - line breaks are handled by the measurer creating new lines,
    // so we don't render anything for them in the DOM. They exist in the run array for
    // proper PM position tracking but don't need visual representation.
    if (this.isLineBreakRun(run)) {
      return null;
    }

    // Handle BreakRun - similar to LineBreakRun, breaks are handled by the measurer
    if (this.isBreakRun(run)) {
      return null;
    }

    // Handle TextRun
    if (!('text' in run) || !run.text || !this.doc) {
      return null;
    }

    const linkData = this.extractLinkData(run);
    const isActiveLink = !!(linkData && !linkData.blocked && linkData.href);
    const elem = isActiveLink ? this.doc.createElement('a') : this.doc.createElement('span');
    const text = resolveRunText(run, context);
    elem.textContent = text;

    if (linkData?.dataset) {
      applyLinkDataset(elem, linkData.dataset);
    }
    if (linkData?.blocked) {
      elem.dataset[LINK_DATASET_KEYS.blocked] = 'true';
      // For blocked links rendered as spans, set appropriate role
      elem.setAttribute('role', 'text');
      elem.setAttribute('aria-label', 'Invalid link - not clickable');
    }
    if (isActiveLink && linkData) {
      this.applyLinkAttributes(elem as HTMLAnchorElement, linkData);
      // Enhance accessibility with ARIA labels for ambiguous text
      this.enhanceAccessibility(elem as HTMLAnchorElement, linkData, text);

      // Note: Tooltip accessibility (aria-describedby) will be applied after
      // the element is added to the DOM in renderLine, since it creates a sibling element
      // Store tooltip for later processing
      if (linkData.tooltip) {
        this.pendingTooltips.set(elem, linkData.tooltip);
      }
    }

    // Pass isLink flag to skip applying inline color/decoration styles for links
    applyRunStyles(elem as HTMLElement, run, isActiveLink);
    const textRun = run as TextRun;
    const commentAnnotations = textRun.comments;
    const hasAnyComment = !!commentAnnotations?.length;
    // Comment highlight styles are applied post-paint by CommentHighlightDecorator (super-editor).
    // The painter only stamps metadata attributes below.
    // We still need to preserve the comment ids
    if (hasAnyComment) {
      elem.dataset.commentIds = commentAnnotations.map((c) => c.commentId).join(',');
      if (commentAnnotations.some((c) => c.internal)) {
        elem.dataset.commentInternal = 'true';
      }
      // Per-comment internal flag so the editor-side decorator can pick the right color
      const internalIds = commentAnnotations.filter((c) => c.internal).map((c) => c.commentId);
      if (internalIds.length > 0) {
        elem.dataset.commentInternalIds = internalIds.join(',');
      }
      // importedId aliases so the decorator can match by either ID
      const importedEntries = commentAnnotations
        .filter((c) => c.importedId && c.importedId !== c.commentId)
        .map((c) => `${c.importedId}=${c.commentId}`);
      if (importedEntries.length > 0) {
        elem.dataset.commentImportedIds = importedEntries.join(',');
      }
      elem.classList.add('superdoc-comment-highlight');
    }
    // Ensure text renders above tab leaders (leaders are z-index: 0)
    elem.style.zIndex = '1';
    applyRunDataAttributes(elem as HTMLElement, (run as TextRun).dataAttrs);

    // Assert PM positions are present for cursor fallback
    assertPmPositions(run, 'paragraph text run');

    if (run.pmStart != null) elem.dataset.pmStart = String(run.pmStart);
    if (run.pmEnd != null) elem.dataset.pmEnd = String(run.pmEnd);
    elem.dataset.layoutEpoch = String(this.layoutEpoch);
    if (trackedConfig) {
      this.applyTrackedChangeDecorations(elem, run, trackedConfig);
    }
    this.applySdtDataset(elem, (run as TextRun).sdt);

    return elem;
  }

  /**
   * Renders an ImageRun as an inline <img> element.
   *
   * SECURITY NOTES:
   * - Data URLs are validated against VALID_IMAGE_DATA_URL regex to ensure proper format
   * - Size limit (MAX_DATA_URL_LENGTH) prevents DoS attacks from extremely large images
   * - Only allows safe image MIME types (png, jpeg, gif, etc.) with base64 encoding
   * - Non-data URLs are sanitized through sanitizeUrl to prevent XSS
   *
   * METADATA ATTRIBUTE:
   * - Adds `data-image-metadata` attribute to enable interactive resizing via ImageResizeOverlay
   * - Metadata includes: originalWidth, originalHeight, aspectRatio, min/max dimensions
   * - Only added when run.width > 0 && run.height > 0 to prevent invalid metadata
   * - Max dimensions: 3x original size or 1000px (whichever is larger)
   * - Min dimensions: 20px to ensure visibility and interactivity
   *
   * @param run - The ImageRun to render containing image source, dimensions, and spacing
   * @returns HTMLElement (img) or null if src is missing or invalid
   *
   * @example
   * ```typescript
   * // Valid data URL with metadata
   * renderImageRun({ kind: 'image', src: 'data:image/png;base64,iVBORw...', width: 100, height: 100 })
   * // Returns: <img> element with data-image-metadata attribute
   *
   * // Invalid dimensions - no metadata
   * renderImageRun({ kind: 'image', src: 'data:image/png;base64,iVBORw...', width: 0, height: 0 })
   * // Returns: <img> element WITHOUT data-image-metadata attribute
   *
   * // Invalid MIME type
   * renderImageRun({ kind: 'image', src: 'data:text/html;base64,PHNjcmlwdD4...', width: 100, height: 100 })
   * // Returns: null (blocked)
   *
   * // HTTP URL
   * renderImageRun({ kind: 'image', src: 'https://example.com/image.png', width: 100, height: 100 })
   * // Returns: <img> element (after sanitization) with data-image-metadata attribute
   * ```
   */
  private renderImageRun(run: ImageRun): HTMLElement | null {
    if (!this.doc || !run.src) {
      return null;
    }

    const hasClipPath = typeof run.clipPath === 'string' && run.clipPath.trim().length > 0;

    // Create img element
    const img = this.doc.createElement('img');
    img.classList.add(DOM_CLASS_NAMES.INLINE_IMAGE);

    // Set source - validate data URLs with strict format and size checks
    // Note: data: URLs are blocked by sanitizeUrl for hyperlinks (XSS risk),
    // but are safe for <img> elements when properly validated
    const isDataUrl = typeof run.src === 'string' && run.src.startsWith('data:');
    if (isDataUrl) {
      // SECURITY: Validate data URL format and size
      if (run.src.length > MAX_DATA_URL_LENGTH) {
        // Reject data URLs that are too large (DoS prevention)
        return null;
      }
      if (!VALID_IMAGE_DATA_URL.test(run.src)) {
        // Reject data URLs with invalid MIME types or encoding
        return null;
      }
      img.src = run.src;
    } else {
      const sanitized = sanitizeUrl(run.src);
      if (sanitized) {
        img.src = sanitized;
      } else {
        // Invalid URL - return null
        return null;
      }
    }

    // Set dimensions: when we have clipPath we put img in a wrapper that has the layout size and overflow:hidden; img fills wrapper so cropped portion stays within after resize
    if (!hasClipPath) {
      img.width = run.width;
      img.height = run.height;
    } else {
      Object.assign(img.style, {
        width: '100%',
        height: '100%',
        maxWidth: '100%',
        maxHeight: '100%',
        boxSizing: 'border-box',
        minWidth: '0',
        minHeight: '0',
      });
    }
    applyImageClipPath(img, run.clipPath);

    // Add metadata for interactive image resizing (inline images)
    // Only add metadata if dimensions are valid (positive, non-zero values)
    if (run.width > 0 && run.height > 0) {
      // This enables the ImageResizeOverlay to work with inline images
      const aspectRatio = run.width / run.height;
      const inlineImageMetadata = {
        originalWidth: run.width,
        originalHeight: run.height,
        // Max dimensions: MAX_RESIZE_MULTIPLIER x original size or FALLBACK_MAX_DIMENSION, whichever is larger
        // This provides generous constraints while preventing excessive scaling
        maxWidth: Math.max(run.width * MAX_RESIZE_MULTIPLIER, FALLBACK_MAX_DIMENSION),
        maxHeight: Math.max(run.height * MAX_RESIZE_MULTIPLIER, FALLBACK_MAX_DIMENSION),
        aspectRatio,
        // Min dimensions: MIN_IMAGE_DIMENSION to ensure images remain visible and interactive
        minWidth: MIN_IMAGE_DIMENSION,
        minHeight: MIN_IMAGE_DIMENSION,
      };
      img.setAttribute('data-image-metadata', JSON.stringify(inlineImageMetadata));
    }

    // Set alt text (required for accessibility)
    img.alt = run.alt ?? '';

    // Set title if present
    if (run.title) {
      img.title = run.title;
    }

    // Apply inline-block display
    img.style.display = 'inline-block';

    // When we use a wrapper (clipPath + positive dimensions), margins/verticalAlign/position/zIndex go on the wrapper only.
    // When we don't use a wrapper (no clipPath, or clipPath with width/height 0), apply them on the img so layout is correct.
    const useWrapper = hasClipPath && run.width > 0 && run.height > 0;
    if (!useWrapper) {
      // Apply vertical alignment (bottom-aligned to text baseline)
      img.style.verticalAlign = run.verticalAlign ?? 'bottom';

      // Apply spacing as CSS margins
      if (run.distTop) {
        img.style.marginTop = `${run.distTop}px`;
      }
      if (run.distBottom) {
        img.style.marginBottom = `${run.distBottom}px`;
      }
      if (run.distLeft) {
        img.style.marginLeft = `${run.distLeft}px`;
      }
      if (run.distRight) {
        img.style.marginRight = `${run.distRight}px`;
      }

      // Position and z-index on the image only (not the line) so resize overlay can stack above.
      img.style.position = 'relative';
      img.style.zIndex = '1';
    }

    // Apply rotation and flip transforms from OOXML a:xfrm
    const transforms: string[] = [];

    // Calculate translation offset to keep top-left corner fixed when rotating
    if (run.rotation != null && run.rotation !== 0) {
      const angleRad = (run.rotation * Math.PI) / 180;
      const w = run.width;
      const h = run.height;

      // Calculate how much the top-left corner moves when rotating around center
      // Top-left corner starts at (0, 0) in element space
      // Center is at (w/2, h/2)
      // After rotation, we need to translate to keep top-left at (0, 0)
      const cosA = Math.cos(angleRad);
      const sinA = Math.sin(angleRad);

      // Position of top-left corner after rotation (relative to original top-left)
      const newTopLeftX = (w / 2) * (1 - cosA) + (h / 2) * sinA;
      const newTopLeftY = (w / 2) * sinA + (h / 2) * (1 - cosA);

      transforms.push(`translate(${-newTopLeftX}px, ${-newTopLeftY}px)`);
      transforms.push(`rotate(${run.rotation}deg)`);
    }
    if (run.flipH) {
      transforms.push('scaleX(-1)');
    }
    if (run.flipV) {
      transforms.push('scaleY(-1)');
    }
    if (transforms.length > 0) {
      img.style.transform = transforms.join(' ');
      img.style.transformOrigin = 'center';
    }

    const filters = buildImageFilters(run);
    if (filters.length > 0) {
      img.style.filter = filters.join(' ');
    }

    // Assert PM positions are present for cursor fallback
    assertPmPositions(run, 'inline image run');

    // When clipPath is set, scale makes the img paint outside its box;
    // wrap in a clip container so only the cropped portion occupies space in the document.
    // Wrapper size is the only layout box (position calculation uses run.width/run.height).
    // PM position attributes go on the wrapper only so selection highlight and selection rects use the wrapper, not the scaled img.
    // Skip wrapper when width or height is 0 (no layout box); img already has margins/verticalAlign/position/zIndex from above.
    if (useWrapper) {
      const wrapper = this.doc.createElement('span');
      wrapper.classList.add(DOM_CLASS_NAMES.INLINE_IMAGE_CLIP_WRAPPER);
      wrapper.style.display = 'inline-block';
      wrapper.style.width = `${run.width}px`;
      wrapper.style.height = `${run.height}px`;
      wrapper.style.boxSizing = 'border-box';
      wrapper.style.overflow = 'hidden';
      wrapper.style.verticalAlign = run.verticalAlign ?? 'bottom';
      if (run.distTop) wrapper.style.marginTop = `${run.distTop}px`;
      if (run.distBottom) wrapper.style.marginBottom = `${run.distBottom}px`;
      if (run.distLeft) wrapper.style.marginLeft = `${run.distLeft}px`;
      if (run.distRight) wrapper.style.marginRight = `${run.distRight}px`;
      wrapper.style.position = 'relative';
      wrapper.style.zIndex = '1';
      if (run.pmStart != null) wrapper.dataset.pmStart = String(run.pmStart);
      if (run.pmEnd != null) wrapper.dataset.pmEnd = String(run.pmEnd);
      wrapper.dataset.layoutEpoch = String(this.layoutEpoch);
      this.applySdtDataset(wrapper, run.sdt);
      if (run.dataAttrs) applyRunDataAttributes(wrapper, run.dataAttrs);
      wrapper.appendChild(img);
      return this.buildImageHyperlinkAnchor(wrapper, run.hyperlink, 'inline-block');
    }

    // Apply PM position tracking for cursor placement (only on img when not wrapped)
    if (run.pmStart != null) {
      img.dataset.pmStart = String(run.pmStart);
    }
    if (run.pmEnd != null) {
      img.dataset.pmEnd = String(run.pmEnd);
    }
    img.dataset.layoutEpoch = String(this.layoutEpoch);

    // Apply SDT metadata
    this.applySdtDataset(img, run.sdt);

    // Apply data attributes
    if (run.dataAttrs) {
      applyRunDataAttributes(img, run.dataAttrs);
    }

    const runClipPath = readClipPathValue((run as { clipPath?: unknown }).clipPath);
    if (runClipPath && this.doc) {
      img.style.clipPath = runClipPath;
      img.style.display = 'block';
      img.style.marginTop = '';
      img.style.marginBottom = '';
      img.style.marginLeft = '';
      img.style.marginRight = '';
      img.style.verticalAlign = '';
      img.style.position = 'static';
      img.style.zIndex = '';

      const wrapper = this.doc.createElement('span');
      wrapper.classList.add('superdoc-inline-image-clip-wrapper');
      wrapper.style.display = 'inline-block';
      wrapper.style.width = `${run.width}px`;
      wrapper.style.height = `${run.height}px`;
      wrapper.style.verticalAlign = run.verticalAlign ?? 'bottom';
      wrapper.style.position = 'relative';
      wrapper.style.zIndex = '1';
      if (run.distTop) wrapper.style.marginTop = `${run.distTop}px`;
      if (run.distBottom) wrapper.style.marginBottom = `${run.distBottom}px`;
      if (run.distLeft) wrapper.style.marginLeft = `${run.distLeft}px`;
      if (run.distRight) wrapper.style.marginRight = `${run.distRight}px`;

      if (run.pmStart != null) {
        wrapper.dataset.pmStart = String(run.pmStart);
      }
      if (run.pmEnd != null) {
        wrapper.dataset.pmEnd = String(run.pmEnd);
      }
      wrapper.dataset.layoutEpoch = String(this.layoutEpoch);
      this.applySdtDataset(wrapper, run.sdt);

      wrapper.appendChild(img);
      return this.buildImageHyperlinkAnchor(wrapper, run.hyperlink, 'inline-block');
    }

    return this.buildImageHyperlinkAnchor(img, run.hyperlink, 'inline-block');
  }

  /**
   * Renders a FieldAnnotationRun as an inline "pill" element matching super-editor's visual appearance.
   *
   * Field annotations are styled inline elements that display form fields with:
   * - Outer span with border, border-radius, padding, and background color
   * - Inner span containing the displayLabel or type-specific content (image, link, etc.)
   *
   * @param run - The FieldAnnotationRun to render containing field configuration and styling
   * @returns HTMLElement (span) or null if document is not available
   *
   * @example
   * ```typescript
   * // Text variant
   * renderFieldAnnotationRun({ kind: 'fieldAnnotation', variant: 'text', displayLabel: 'Full Name', fieldColor: '#980043' })
   * // Returns: <span class="annotation" style="border: 2px solid #b015b3; ..."><span class="annotation-content">Full Name</span></span>
   *
   * // Image variant with imageSrc
   * renderFieldAnnotationRun({ kind: 'fieldAnnotation', variant: 'image', displayLabel: 'Photo', imageSrc: 'data:image/png;...' })
   * // Returns: <span class="annotation"><span class="annotation-content"><img src="..." /></span></span>
   *
   * // Link variant
   * renderFieldAnnotationRun({ kind: 'fieldAnnotation', variant: 'link', displayLabel: 'Website', linkUrl: 'https://example.com' })
   * // Returns: <span class="annotation"><span class="annotation-content"><a href="...">https://example.com</a></span></span>
   * ```
   */
  private renderFieldAnnotationRun(run: FieldAnnotationRun): HTMLElement | null {
    if (!this.doc) {
      return null;
    }

    // Handle hidden fields
    if (run.hidden) {
      const hidden = this.doc.createElement('span');
      hidden.style.display = 'none';
      if (run.pmStart != null) hidden.dataset.pmStart = String(run.pmStart);
      if (run.pmEnd != null) hidden.dataset.pmEnd = String(run.pmEnd);
      hidden.dataset.layoutEpoch = String(this.layoutEpoch);
      return hidden;
    }

    // Default styling values (matching super-editor's FieldAnnotationView)
    const defaultBorderColor = '#b015b3';
    const defaultFieldColor = '#980043';

    // Create outer annotation wrapper
    const annotation = this.doc.createElement('span');
    annotation.classList.add(DOM_CLASS_NAMES.ANNOTATION);
    annotation.setAttribute('aria-label', 'Field annotation');

    // Apply pill styling (unless highlighted is explicitly false)
    const showHighlight = run.highlighted !== false;
    if (showHighlight) {
      const borderColor = run.borderColor || defaultBorderColor;
      annotation.style.border = `2px solid ${borderColor}`;
      annotation.style.borderRadius = '2px';
      annotation.style.padding = '1px 2px';
      annotation.style.boxSizing = 'border-box';

      // Apply background color with alpha
      const fieldColor = run.fieldColor || defaultFieldColor;
      // Add alpha to make it semi-transparent (matching super-editor's behavior)
      const bgColor = fieldColor.length === 7 ? `${fieldColor}33` : fieldColor;
      // textHighlight takes precedence over fieldColor
      if (run.textHighlight) {
        annotation.style.backgroundColor = run.textHighlight;
      } else {
        annotation.style.backgroundColor = bgColor;
      }
    }

    // Apply visibility
    if (run.visibility === 'hidden') {
      annotation.style.visibility = 'hidden';
    }

    // Apply explicit size if present
    if (run.size) {
      if (run.size.width) {
        const requiresImage = run.variant === 'image' || run.variant === 'signature';
        if (!requiresImage || run.imageSrc) {
          annotation.style.width = `${run.size.width}px`;
          annotation.style.display = 'inline-block';
          annotation.style.overflow = 'hidden';
        }
      }
      if (run.size.height && run.variant !== 'html') {
        const requiresImage = run.variant === 'image' || run.variant === 'signature';
        if (!requiresImage || run.imageSrc) {
          annotation.style.height = `${run.size.height}px`;
        }
      }
    }

    // Apply typography to the annotation element
    if (run.fontFamily) {
      annotation.style.fontFamily = run.fontFamily;
    }
    if (run.fontSize) {
      const fontSize = typeof run.fontSize === 'number' ? `${run.fontSize}pt` : run.fontSize;
      annotation.style.fontSize = fontSize;
    }
    if (run.textColor) {
      annotation.style.color = run.textColor;
    }
    if (run.bold) {
      annotation.style.fontWeight = 'bold';
    }
    if (run.italic) {
      annotation.style.fontStyle = 'italic';
    }
    if (run.underline) {
      annotation.style.textDecoration = 'underline';
    }

    // Apply z-index for proper layering
    annotation.style.zIndex = '1';

    // Create inner content wrapper
    const content = this.doc.createElement('span');
    content.classList.add(DOM_CLASS_NAMES.ANNOTATION_CONTENT);
    content.style.pointerEvents = 'none';
    content.setAttribute('contenteditable', 'false');

    // Render type-specific content
    switch (run.variant) {
      case 'image':
      case 'signature': {
        if (run.imageSrc) {
          const img = this.doc.createElement('img');
          // SECURITY: Validate data URLs
          const isDataUrl = run.imageSrc.startsWith('data:');
          if (isDataUrl) {
            if (run.imageSrc.length <= MAX_DATA_URL_LENGTH && VALID_IMAGE_DATA_URL.test(run.imageSrc)) {
              img.src = run.imageSrc;
            } else {
              // Invalid data URL - fall back to displayLabel
              content.textContent = run.displayLabel;
              break;
            }
          } else {
            const sanitized = sanitizeHref(run.imageSrc);
            if (sanitized) {
              img.src = sanitized.href;
            } else {
              content.textContent = run.displayLabel;
              break;
            }
          }
          img.alt = run.displayLabel;
          img.style.height = 'auto';
          img.style.maxWidth = '100%';
          img.style.pointerEvents = 'none';
          img.style.verticalAlign = 'middle';
          if (run.variant === 'signature') {
            img.style.maxHeight = '28px';
          }
          content.appendChild(img);
          annotation.style.display = 'inline-block';
          content.style.display = 'inline-block';
          // Prevent line-height inheritance from the line container from breaking image layout.
          annotation.style.lineHeight = 'normal';
          content.style.lineHeight = 'normal';
        } else {
          content.textContent = run.displayLabel || (run.variant === 'signature' ? 'Signature' : '');
        }
        break;
      }

      case 'link': {
        if (run.linkUrl) {
          const link = this.doc.createElement('a');
          const sanitized = sanitizeHref(run.linkUrl);
          if (sanitized) {
            link.href = sanitized.href;
            link.target = '_blank';
            link.rel = 'noopener noreferrer';
            link.textContent = run.linkUrl;
            link.style.textDecoration = 'none';
            content.style.pointerEvents = 'all';
            content.appendChild(link);
          } else {
            content.textContent = run.displayLabel;
          }
        } else {
          content.textContent = run.displayLabel;
        }
        break;
      }

      case 'html': {
        if (run.rawHtml && typeof run.rawHtml === 'string') {
          // Note: rawHtml is expected to be sanitized upstream.
          content.innerHTML = run.rawHtml.trim();
          annotation.style.display = 'inline-block';
          content.style.display = 'inline-block';
          // Prevent line-height inheritance from the line container from affecting HTML layout.
          annotation.style.lineHeight = 'normal';
          content.style.lineHeight = 'normal';
        } else {
          content.textContent = run.displayLabel;
        }
        break;
      }

      case 'text':
      case 'checkbox':
      default: {
        content.textContent = run.displayLabel;
        break;
      }
    }

    annotation.appendChild(content);

    // Apply data attributes for field tracking
    annotation.dataset.type = run.variant;
    annotation.dataset.displayLabel = run.displayLabel;
    if (run.fieldId) {
      annotation.dataset.fieldId = run.fieldId;
    }
    if (run.fieldType) {
      annotation.dataset.fieldType = run.fieldType;
    }

    // Assert PM positions are present for cursor fallback
    assertPmPositions(run, 'field annotation run');

    // Apply PM position tracking
    if (run.pmStart != null) {
      annotation.dataset.pmStart = String(run.pmStart);
    }
    if (run.pmEnd != null) {
      annotation.dataset.pmEnd = String(run.pmEnd);
    }
    annotation.dataset.layoutEpoch = String(this.layoutEpoch);

    // Apply SDT metadata
    this.applySdtDataset(annotation, run.sdt);

    return annotation;
  }

  /**
   * Renders a single line of a paragraph block.
   *
   * @param block - The paragraph block containing the line
   * @param line - The line measurement data
   * @param context - Rendering context with fragment information
   * @param availableWidthOverride - Optional override for available width used in justification calculations
   * @param lineIndex - Optional zero-based index of the line within the fragment
   * @param skipJustify - When true, prevents justification even if alignment is 'justify'
   * @param resolvedListTextStartPx - Optional canonical text-start override for list first lines
   * @param indentOffsetOverride - When defined, used instead of re-deriving indentOffset from block attrs in the segment positioning path
   * @returns The rendered line element
   */
  private renderLine(
    block: ParagraphBlock,
    line: Line,
    context: FragmentRenderContext,
    availableWidthOverride?: number,
    lineIndex?: number,
    skipJustify?: boolean,
    resolvedListTextStartPx?: number,
    indentOffsetOverride?: number,
  ): HTMLElement {
    if (!this.doc) {
      throw new Error('DomPainter: document is not available');
    }

    const lineRange = computeLinePmRange(block, line);
    let runsForLine = sliceRunsForLine(block, line);

    const el = this.doc.createElement('div');
    el.classList.add(CLASS_NAMES.line);
    applyStyles(el, lineStyles(line.lineHeight));
    el.dataset.layoutEpoch = String(this.layoutEpoch);
    const paragraphAttrs = (block.attrs as ParagraphAttrs | undefined) ?? {};
    const styleId = paragraphAttrs.styleId;
    if (styleId) {
      el.setAttribute('styleid', styleId);
    }
    const pAttrs = block.attrs as ParagraphAttrs | undefined;
    const isRtl = applyRtlStyles(el, pAttrs);

    if (lineRange.pmStart != null) {
      el.dataset.pmStart = String(lineRange.pmStart);
    }
    if (lineRange.pmEnd != null) {
      el.dataset.pmEnd = String(lineRange.pmEnd);
    }
    const trackedConfig = this.resolveTrackedChangesConfig(block);

    // Preserve PM positions for DOM caret mapping on empty lines.
    if (runsForLine.length === 0) {
      const span = this.doc.createElement('span');
      span.classList.add('superdoc-empty-run');
      if (lineRange.pmStart != null) {
        span.dataset.pmStart = String(lineRange.pmStart);
      }
      if (lineRange.pmEnd != null) {
        span.dataset.pmEnd = String(lineRange.pmEnd);
      }
      span.innerHTML = '&nbsp;';
      el.appendChild(span);
    }

    // Render tab leaders (absolute positioned overlays)
    if (line.leaders && line.leaders.length > 0) {
      line.leaders.forEach((ld) => {
        const leaderEl = this.doc!.createElement('div');
        leaderEl.classList.add('superdoc-leader');
        leaderEl.setAttribute('data-style', ld.style);
        leaderEl.style.position = 'absolute';
        leaderEl.style.left = `${ld.from}px`;
        leaderEl.style.width = `${Math.max(0, ld.to - ld.from)}px`;
        // Align leaders closer to the text baseline using measured descent
        const baselineOffset = Math.max(1, Math.round(Math.max(1, line.descent * 0.5)));
        leaderEl.style.bottom = `${baselineOffset}px`;
        leaderEl.style.height = ld.style === 'heavy' ? '2px' : '1px';
        leaderEl.style.pointerEvents = 'none';
        leaderEl.style.zIndex = '0'; // Same layer as line, text will be z-index: 1

        // Map leader styles to CSS
        if (ld.style === 'dot' || ld.style === 'middleDot') {
          leaderEl.style.borderBottom = '1px dotted currentColor';
        } else if (ld.style === 'hyphen') {
          leaderEl.style.borderBottom = '1px dashed currentColor';
        } else if (ld.style === 'underscore') {
          leaderEl.style.borderBottom = '1px solid currentColor';
        } else if (ld.style === 'heavy') {
          leaderEl.style.borderBottom = '2px solid currentColor';
        }

        el.appendChild(leaderEl);
      });
    }

    // Render bar tabs (vertical hairlines)
    if (line.bars && line.bars.length > 0) {
      line.bars.forEach((bar) => {
        const barEl = this.doc!.createElement('div');
        barEl.classList.add('superdoc-tab-bar');
        barEl.style.position = 'absolute';
        barEl.style.left = `${bar.x}px`;
        barEl.style.top = '0px';
        barEl.style.bottom = '0px';
        barEl.style.width = '1px';
        barEl.style.background = 'currentColor';
        barEl.style.opacity = '0.6';
        barEl.style.pointerEvents = 'none';
        el.appendChild(barEl);
      });
    }

    // Check if any segments have explicit X positioning (from tab stops)
    const hasExplicitPositioning = line.segments?.some((seg) => seg.x !== undefined);
    const lineContainsTabRun = runsForLine.some((run) => run.kind === 'tab');
    const manualTabWithoutSegments = lineContainsTabRun && !hasExplicitPositioning;
    const availableWidth = availableWidthOverride ?? line.maxWidth ?? line.width;

    const justifyShouldApply = shouldApplyJustify({
      alignment: (block as ParagraphBlock).attrs?.alignment,
      hasExplicitPositioning: hasExplicitPositioning ?? false,
      // Caller already folds last-line + trailing lineBreak behavior into skipJustify.
      isLastLineOfParagraph: false,
      paragraphEndsWithLineBreak: false,
      skipJustifyOverride: skipJustify || manualTabWithoutSegments,
    });

    const countSpaces = (text: string): number => {
      let count = 0;
      for (let i = 0; i < text.length; i += 1) {
        if (SPACE_CHARS.has(text[i])) count += 1;
      }
      return count;
    };

    if (justifyShouldApply) {
      // The measurer trims wrap-point trailing spaces from line ranges, but slicing can still
      // produce whitespace-only runs at style boundaries. These runs are especially problematic
      // for justify because `word-spacing` behavior is inconsistent on pure-whitespace spans.
      //
      // Normalize by merging whitespace-only slices into adjacent runs with identical styling.
      const stableDataAttrs = (attrs: Record<string, string> | undefined): Record<string, string> | undefined => {
        if (!attrs) return undefined;
        const keys = Object.keys(attrs).sort();
        const out: Record<string, string> = {};
        keys.forEach((key) => {
          out[key] = attrs[key]!;
        });
        return out;
      };

      const mergeSignature = (run: TextRun): string =>
        JSON.stringify({
          kind: run.kind ?? 'text',
          fontFamily: run.fontFamily,
          fontSize: run.fontSize,
          bold: run.bold ?? false,
          italic: run.italic ?? false,
          letterSpacing: run.letterSpacing ?? null,
          color: run.color ?? null,
          underline: run.underline ?? null,
          strike: run.strike ?? false,
          highlight: run.highlight ?? null,
          textTransform: run.textTransform ?? null,
          token: run.token ?? null,
          pageRefMetadata: run.pageRefMetadata ?? null,
          trackedChange: run.trackedChange ?? null,
          sdt: run.sdt ?? null,
          link: run.link ?? null,
          comments: run.comments ?? null,
          dataAttrs: stableDataAttrs(run.dataAttrs) ?? null,
        });

      const isWhitespaceOnly = (text: string): boolean => {
        if (text.length === 0) return false;
        for (let i = 0; i < text.length; i += 1) {
          if (!SPACE_CHARS.has(text[i])) return false;
        }
        return true;
      };

      const cloneTextRun = (run: TextRun): TextRun => ({
        ...(run as TextRun),
        comments: run.comments ? [...run.comments] : undefined,
        dataAttrs: run.dataAttrs ? { ...run.dataAttrs } : undefined,
        underline: run.underline ? { ...run.underline } : undefined,
        pageRefMetadata: run.pageRefMetadata ? { ...run.pageRefMetadata } : undefined,
      });

      const normalized: Run[] = runsForLine.map((run) => {
        if ((run.kind !== 'text' && run.kind !== undefined) || !('text' in run)) return run;
        return cloneTextRun(run as TextRun);
      });

      const merged: Run[] = [];
      for (let i = 0; i < normalized.length; i += 1) {
        const run = normalized[i]!;
        if ((run.kind !== 'text' && run.kind !== undefined) || !('text' in run)) {
          merged.push(run);
          continue;
        }

        const textRun = run as TextRun;
        if (!isWhitespaceOnly(textRun.text ?? '')) {
          merged.push(textRun);
          continue;
        }

        const prev = merged[merged.length - 1];
        if (prev && (prev.kind === 'text' || prev.kind === undefined) && 'text' in prev) {
          const prevTextRun = prev as TextRun;
          if (mergeSignature(prevTextRun) === mergeSignature(textRun)) {
            const extra = textRun.text ?? '';
            prevTextRun.text = (prevTextRun.text ?? '') + extra;
            if (prevTextRun.pmStart != null) {
              prevTextRun.pmEnd = prevTextRun.pmStart + prevTextRun.text.length;
            } else if (prevTextRun.pmEnd != null) {
              prevTextRun.pmEnd = prevTextRun.pmEnd + extra.length;
            }
            continue;
          }
        }

        const next = normalized[i + 1];
        if (next && (next.kind === 'text' || next.kind === undefined) && 'text' in next) {
          const nextTextRun = next as TextRun;
          if (mergeSignature(nextTextRun) === mergeSignature(textRun)) {
            const extra = textRun.text ?? '';
            nextTextRun.text = extra + (nextTextRun.text ?? '');
            if (textRun.pmStart != null) {
              nextTextRun.pmStart = textRun.pmStart;
            } else if (nextTextRun.pmStart != null) {
              nextTextRun.pmStart = nextTextRun.pmStart - extra.length;
            }
            if (nextTextRun.pmStart != null && nextTextRun.pmEnd == null) {
              nextTextRun.pmEnd = nextTextRun.pmStart + nextTextRun.text.length;
            }
            continue;
          }
        }

        merged.push(textRun);
      }

      runsForLine = merged;

      // Suppress trailing wrap-point spaces on justified lines. With `white-space: pre`, they would
      // otherwise consume width and be stretched by word-spacing, producing a ragged visible edge.
      // Preserve intentionally space-only lines (rare but supported).
      const hasNonSpaceText = runsForLine.some(
        (run) => (run.kind === 'text' || run.kind === undefined) && 'text' in run && (run.text ?? '').trim().length > 0,
      );
      if (hasNonSpaceText) {
        for (let i = runsForLine.length - 1; i >= 0; i -= 1) {
          const run = runsForLine[i];
          if ((run.kind !== 'text' && run.kind !== undefined) || !('text' in run)) continue;
          const text = run.text ?? '';
          let trimCount = 0;
          for (let j = text.length - 1; j >= 0 && text[j] === ' '; j -= 1) {
            trimCount += 1;
          }
          if (trimCount === 0) break;

          const nextText = text.slice(0, Math.max(0, text.length - trimCount));
          if (nextText.length === 0) {
            runsForLine.splice(i, 1);
            continue;
          }
          (run as TextRun).text = nextText;
          if ((run as TextRun).pmEnd != null) {
            (run as TextRun).pmEnd = (run as TextRun).pmEnd! - trimCount;
          }
          break;
        }
      }
    }

    const spaceCount =
      line.spaceCount ??
      runsForLine.reduce((sum, run) => {
        if ((run.kind !== 'text' && run.kind !== undefined) || !('text' in run) || run.text == null) return sum;
        return sum + countSpaces(run.text);
      }, 0);
    const lineWidth = line.naturalWidth ?? line.width;
    const spacingPerSpace = calculateJustifySpacing({
      lineWidth,
      availableWidth,
      spaceCount,
      shouldJustify: justifyShouldApply,
    });

    if (spacingPerSpace !== 0) {
      // Each rendered line is its own block; relying on text-align-last is brittle, so we use word-spacing.
      el.style.wordSpacing = `${spacingPerSpace}px`;
    }

    if (shouldUseSegmentPositioning(hasExplicitPositioning ?? false, Boolean(line.segments), isRtl)) {
      // Use segment-based rendering with absolute positioning for tab-aligned text.
      // shouldUseSegmentPositioning returns false for RTL because the layout engine
      // computes tab positions in LTR order; RTL lines fall through to inline-flow
      // rendering where dir="rtl" lets the browser handle tab positioning.
      //
      // The segment x positions from layout are relative to the content area (left margin = 0).
      // We need to add the paragraph indent to ALL positions (both explicit and calculated).
      let indentOffset: number;
      if (indentOffsetOverride != null) {
        // Resolved path: indentOffset was pre-computed by the resolver.
        indentOffset = indentOffsetOverride;
      } else {
        // Legacy path: derive from block attrs.
        const paraIndent = (block.attrs as ParagraphAttrs | undefined)?.indent;
        const indentLeft = paraIndent?.left ?? 0;
        const firstLine = paraIndent?.firstLine ?? 0;
        const hanging = paraIndent?.hanging ?? 0;
        const isFirstLineOfPara = lineIndex === 0 || lineIndex === undefined;
        const firstLineOffsetForCumX = isFirstLineOfPara ? firstLine - hanging : 0;
        const wordLayoutValue = (block.attrs as ParagraphAttrs | undefined)?.wordLayout;
        const wordLayout = isMinimalWordLayout(wordLayoutValue) ? wordLayoutValue : undefined;
        const isListParagraph = Boolean(wordLayout?.marker);
        const fallbackListTextStartPx =
          typeof wordLayout?.marker?.textStartX === 'number' && Number.isFinite(wordLayout.marker.textStartX)
            ? wordLayout.marker.textStartX
            : typeof wordLayout?.textStartPx === 'number' && Number.isFinite(wordLayout.textStartPx)
              ? wordLayout.textStartPx
              : undefined;
        const listIndentOffset = isFirstLineOfPara
          ? (resolvedListTextStartPx ?? fallbackListTextStartPx ?? indentLeft)
          : indentLeft;
        indentOffset = isListParagraph ? listIndentOffset : indentLeft + firstLineOffsetForCumX;
      }
      let cumulativeX = 0; // Start at 0, we'll add indentOffset when positioning

      const segments = line.segments!;
      const segmentsByRun = new Map<number, LineSegment[]>();
      segments.forEach((segment) => {
        const list = segmentsByRun.get(segment.runIndex);
        if (list) {
          list.push(segment);
        } else {
          segmentsByRun.set(segment.runIndex, [segment]);
        }
      });

      /**
       * Finds the X position where the immediate next segment starts after a given run index.
       * Only returns the X if the very next run has a segment with explicit positioning.
       * This handles tab-aligned text where right/center alignment causes the text to start
       * before the tab stop target.
       *
       * WHY ONLY THE IMMEDIATE NEXT RUN:
       * When rendering a tab, we need to know where the content IMMEDIATELY after this tab begins
       * to correctly size the tab element. We don't look beyond the immediate next run because:
       * 1. Each tab is independent and should only consider its directly adjacent content
       * 2. Looking further ahead would incorrectly span multiple tabs or unrelated runs
       * 3. If there's another tab between this tab and some content, that intermediate tab is
       *    responsible for its own layout - we shouldn't reach across it
       *
       * For example, given: "Text[TAB1]Content[TAB2]MoreContent"
       * - When sizing TAB1, we only check "Content" (immediate next run)
       * - We don't check "MoreContent" because TAB2 is in between
       * - TAB2 will independently check "MoreContent" when it's rendered
       *
       * @param fromRunIndex - The run index to search after
       * @returns The X position of the immediate next segment, or undefined if not found or not immediate
       */
      const findImmediateNextSegmentX = (fromRunIndex: number): number | undefined => {
        // Only check the immediate next run - don't skip over other tabs
        const nextRunIdx = fromRunIndex + 1;
        if (nextRunIdx <= line.toRun) {
          const nextSegments = segmentsByRun.get(nextRunIdx);
          if (nextSegments && nextSegments.length > 0) {
            const firstSegment = nextSegments[0];
            // Return the segment's explicit X if it has one (from tab alignment)
            return firstSegment.x;
          }
        }
        return undefined;
      };

      // Inline SDT wrapping for geometry path (absolute-positioned elements).
      // Same concept as the run-based path's SDT wrapper, but here elements use
      // position:absolute so the wrapper itself must be absolutely positioned to
      // span from the leftmost to rightmost child element.
      let geoSdtWrapper: HTMLElement | null = null;
      let geoSdtId: string | null = null;
      let geoSdtWrapperLeft = 0;
      let geoSdtMaxRight = 0;

      const closeGeoSdtWrapper = () => {
        if (geoSdtWrapper) {
          geoSdtWrapper.style.width = `${geoSdtMaxRight - geoSdtWrapperLeft}px`;
          el.appendChild(geoSdtWrapper);
          geoSdtWrapper = null;
          geoSdtId = null;
        }
      };

      /**
       * Append an element to the line, routing through an inline SDT wrapper
       * when the run has inline structuredContent metadata.
       */
      const appendToLineGeo = (elem: HTMLElement, runForSdt: Run, elemLeftPx: number, elemWidthPx: number) => {
        const resolved = this.resolveRunSdtId(runForSdt);
        const thisRunSdtId = resolved?.sdtId ?? null;

        if (thisRunSdtId !== geoSdtId) {
          closeGeoSdtWrapper();
        }

        if (resolved && this.doc) {
          if (!geoSdtWrapper) {
            geoSdtWrapper = this.createInlineSdtWrapper(resolved.sdt);
            geoSdtId = thisRunSdtId;
            geoSdtWrapperLeft = elemLeftPx;
            geoSdtMaxRight = elemLeftPx;
            geoSdtWrapper.style.position = 'absolute';
            geoSdtWrapper.style.left = `${elemLeftPx}px`;
            geoSdtWrapper.style.top = '0px';
            geoSdtWrapper.style.height = `${line.lineHeight}px`;
          }
          elem.style.left = `${elemLeftPx - geoSdtWrapperLeft}px`;
          geoSdtMaxRight = Math.max(geoSdtMaxRight, elemLeftPx + elemWidthPx);
          this.expandSdtWrapperPmRange(geoSdtWrapper, (runForSdt as TextRun).pmStart, (runForSdt as TextRun).pmEnd);
          geoSdtWrapper.appendChild(elem);
        } else {
          el.appendChild(elem);
        }
      };

      for (let runIndex = line.fromRun; runIndex <= line.toRun; runIndex += 1) {
        const baseRun = block.runs[runIndex];
        if (!baseRun) continue;

        if (baseRun.kind === 'tab') {
          // Find where the immediate next content begins (if it's right after this tab)
          const immediateNextX = findImmediateNextSegmentX(runIndex);
          const tabStartX = cumulativeX;

          // The tab should span from where previous content ended to where next content begins.
          // If the immediate next segment has an explicit X (from tab alignment), use that.
          // Otherwise, use the tab's measured width to calculate the end position.
          const tabEndX = immediateNextX !== undefined ? immediateNextX : tabStartX + (baseRun.width ?? 0);
          const actualTabWidth = tabEndX - tabStartX;

          const tabEl = this.doc!.createElement('span');
          tabEl.style.position = 'absolute';
          tabEl.style.left = `${tabStartX + indentOffset}px`;
          tabEl.style.top = '0px';
          tabEl.style.width = `${actualTabWidth}px`;
          tabEl.style.height = `${line.lineHeight}px`;
          tabEl.style.display = 'inline-block';
          tabEl.style.pointerEvents = 'none';
          tabEl.style.zIndex = '1';

          // Apply underline styling to tab if present (common in signature lines)
          // TabRun can have RunMarks properties like underline, bold, etc.
          //
          // Signature line use case: In documents with signature lines, tabs are often used
          // to create underlined blank spaces where signatures should go. The underline mark
          // is inherited from a parent node (e.g., a paragraph with underline formatting) and
          // applied to the tab, creating a visible underline even though the tab itself has
          // no visible text content.
          if (baseRun.underline) {
            const underlineStyle = baseRun.underline.style ?? 'single';
            // We must use an explicit color instead of currentColor because tab content is
            // invisible (no text). If we used currentColor, the underline would inherit the
            // text color, which might be transparent or the same as the background, making
            // the underline invisible. Using an explicit color (defaulting to black) ensures
            // the underline is always visible for signature lines.
            const underlineColor = baseRun.underline.color ?? '#000000';
            const borderStyle = underlineStyle === 'double' ? 'double' : 'solid';
            tabEl.style.borderBottom = `1px ${borderStyle} ${underlineColor}`;
          } else {
            tabEl.style.visibility = 'hidden';
          }

          if (styleId) {
            tabEl.setAttribute('styleid', styleId);
          }
          if (baseRun.pmStart != null) tabEl.dataset.pmStart = String(baseRun.pmStart);
          if (baseRun.pmEnd != null) tabEl.dataset.pmEnd = String(baseRun.pmEnd);
          tabEl.dataset.layoutEpoch = String(this.layoutEpoch);
          appendToLineGeo(tabEl, baseRun, tabStartX + indentOffset, actualTabWidth);

          // Update cumulativeX to where the next content begins
          // This ensures proper positioning for subsequent elements
          cumulativeX = tabEndX;
          continue;
        }

        // Handle ImageRun - render as-is (no slicing needed, atomic unit)
        if (this.isImageRun(baseRun)) {
          const elem = this.renderRun(baseRun, context, trackedConfig);
          if (elem) {
            if (styleId) {
              elem.setAttribute('styleid', styleId);
            }
            // Position image using explicit segment X when available; fallback to cumulative flow
            // Add indentOffset to position content at the correct paragraph indent.
            const runSegments = segmentsByRun.get(runIndex);
            const baseSegX = runSegments && runSegments[0]?.x !== undefined ? runSegments[0].x : cumulativeX;
            const segX = baseSegX + indentOffset;
            const segWidth =
              (runSegments && runSegments[0]?.width !== undefined ? runSegments[0].width : elem.offsetWidth) ?? 0;
            elem.style.position = 'absolute';
            elem.style.left = `${segX}px`;
            appendToLineGeo(elem, baseRun, segX, segWidth);
            cumulativeX = baseSegX + segWidth;
          }
          continue;
        }

        // Handle LineBreakRun - line breaks are handled by line creation, skip here
        if (this.isLineBreakRun(baseRun)) {
          continue;
        }

        // Handle BreakRun - breaks are handled by line creation, skip here
        if (this.isBreakRun(baseRun)) {
          continue;
        }

        // Handle FieldAnnotationRun - render as-is (no slicing needed, atomic unit like images)
        if (this.isFieldAnnotationRun(baseRun)) {
          const elem = this.renderRun(baseRun, context, trackedConfig);
          if (elem) {
            if (styleId) {
              elem.setAttribute('styleid', styleId);
            }
            // Position using explicit segment X when available; fallback to cumulative flow
            // Add indentOffset to position content at the correct paragraph indent.
            const runSegments = segmentsByRun.get(runIndex);
            const baseSegX = runSegments && runSegments[0]?.x !== undefined ? runSegments[0].x : cumulativeX;
            const segX = baseSegX + indentOffset;
            const segWidth = (runSegments && runSegments[0]?.width !== undefined ? runSegments[0].width : 0) ?? 0;
            elem.style.position = 'absolute';
            elem.style.left = `${segX}px`;
            appendToLineGeo(elem, baseRun, segX, segWidth);
            cumulativeX = baseSegX + segWidth;
          }
          continue;
        }

        // Handle MathRun - render as-is (atomic unit like images)
        if (this.isMathRun(baseRun)) {
          const elem = this.renderRun(baseRun, context, trackedConfig);
          if (elem) {
            if (styleId) {
              elem.setAttribute('styleid', styleId);
            }
            const runSegments = segmentsByRun.get(runIndex);
            const baseSegX = runSegments && runSegments[0]?.x !== undefined ? runSegments[0].x : cumulativeX;
            const segX = baseSegX + indentOffset;
            const segWidth =
              (runSegments && runSegments[0]?.width !== undefined ? runSegments[0].width : baseRun.width) ?? 0;
            elem.style.position = 'absolute';
            elem.style.left = `${segX}px`;
            appendToLineGeo(elem, baseRun, segX, segWidth);
            cumulativeX = baseSegX + segWidth;
          }
          continue;
        }

        const runSegments = segmentsByRun.get(runIndex);
        if (!runSegments || runSegments.length === 0) {
          continue;
        }

        // At this point, baseRun must be TextRun (has .text property)
        if (!('text' in baseRun)) {
          continue;
        }

        const baseText = baseRun.text ?? '';
        const runPmStart = baseRun.pmStart ?? null;
        const fallbackPmEnd =
          runPmStart != null && baseRun.pmEnd == null ? runPmStart + baseText.length : (baseRun.pmEnd ?? null);

        runSegments.forEach((segment) => {
          const segmentText = baseText.slice(segment.fromChar, segment.toChar);
          if (!segmentText) return;

          const pmSliceStart = runPmStart != null ? runPmStart + segment.fromChar : undefined;
          const pmSliceEnd = runPmStart != null ? runPmStart + segment.toChar : (fallbackPmEnd ?? undefined);
          const segmentRun: TextRun = {
            ...(baseRun as TextRun),
            text: segmentText,
            pmStart: pmSliceStart,
            pmEnd: pmSliceEnd,
          };

          const elem = this.renderRun(segmentRun, context, trackedConfig);
          if (elem) {
            if (styleId) {
              elem.setAttribute('styleid', styleId);
            }
            // Determine X position for this segment
            // Layout positions are relative to content area start (0).
            // Add indentOffset to position content at the correct paragraph indent.
            const baseX = segment.x !== undefined ? segment.x : cumulativeX;
            const xPos = baseX + indentOffset;

            elem.style.position = 'absolute';
            elem.style.left = `${xPos}px`;
            appendToLineGeo(elem, segmentRun, xPos, segment.width ?? 0);

            // Update cumulative X for next segment by measuring this element's width
            // This applies to ALL segments (both with and without explicit X)
            // Use baseX (without indent) to keep cumulativeX relative to content area,
            // matching how segment.x values are calculated in layout.
            let width = segment.width ?? 0;
            if (width <= 0 && this.doc) {
              const measureEl = elem.cloneNode(true) as HTMLElement;
              measureEl.style.position = 'absolute';
              measureEl.style.visibility = 'hidden';
              measureEl.style.left = '-9999px';
              this.doc.body.appendChild(measureEl);
              width = measureEl.offsetWidth;
              this.doc.body.removeChild(measureEl);
            }
            cumulativeX = baseX + width;
            // Update SDT wrapper width if actual measured width differs from initial estimate
            if (geoSdtWrapper) {
              geoSdtMaxRight = Math.max(geoSdtMaxRight, xPos + width);
            }
          }
        });
      }
      // Close any remaining SDT wrapper at end of geometry rendering
      closeGeoSdtWrapper();
    } else {
      // Use run-based rendering for normal text flow
      // Track current inline SDT wrapper to group adjacent runs with the same SDT id
      let currentInlineSdtWrapper: HTMLElement | null = null;
      let currentInlineSdtId: string | null = null;

      const closeCurrentWrapper = () => {
        if (currentInlineSdtWrapper) {
          el.appendChild(currentInlineSdtWrapper);
          currentInlineSdtWrapper = null;
          currentInlineSdtId = null;
        }
      };

      runsForLine.forEach((run) => {
        // Check if this run has inline structuredContent SDT
        const resolved = this.resolveRunSdtId(run);
        const runSdtId = resolved?.sdtId ?? null;

        // If SDT context changed, close the current wrapper
        if (runSdtId !== currentInlineSdtId) {
          closeCurrentWrapper();
        }

        // Special handling for TabRuns (e.g., signature lines with underlines)
        let elem: HTMLElement | null = null;
        if (run.kind === 'tab') {
          const tabEl = this.doc!.createElement('span');
          tabEl.classList.add('superdoc-tab');

          // Calculate tab width - use measured width or estimate based on typical tab stop
          const tabWidth = run.width ?? 48; // Default tab width if not measured

          tabEl.style.display = 'inline-block';
          tabEl.style.width = `${tabWidth}px`;
          tabEl.style.height = `${line.lineHeight}px`;
          tabEl.style.verticalAlign = 'bottom';

          // Apply underline styling if present (common for signature lines)
          //
          // Signature line use case: In documents with signature lines, tabs are often used
          // to create underlined blank spaces where signatures should go. The underline mark
          // is inherited from a parent node (e.g., a paragraph with underline formatting) and
          // applied to the tab, creating a visible underline even though the tab itself has
          // no visible text content.
          if (run.underline) {
            const underlineStyle = run.underline.style ?? 'single';
            // We must use an explicit color instead of currentColor because tab content is
            // invisible (no text). If we used currentColor, the underline would inherit the
            // text color, which might be transparent or the same as the background, making
            // the underline invisible. Using an explicit color (defaulting to black) ensures
            // the underline is always visible for signature lines.
            const underlineColor = run.underline.color ?? '#000000';
            const borderStyle = underlineStyle === 'double' ? 'double' : 'solid';
            tabEl.style.borderBottom = `1px ${borderStyle} ${underlineColor}`;
          }

          if (styleId) {
            tabEl.setAttribute('styleid', styleId);
          }
          if (run.pmStart != null) tabEl.dataset.pmStart = String(run.pmStart);
          if (run.pmEnd != null) tabEl.dataset.pmEnd = String(run.pmEnd);
          tabEl.dataset.layoutEpoch = String(this.layoutEpoch);

          elem = tabEl;
        } else {
          elem = this.renderRun(run, context, trackedConfig);
        }
        if (elem) {
          if (styleId) {
            elem.setAttribute('styleid', styleId);
          }

          // If this run has inline SDT, add to or create wrapper
          if (resolved && this.doc) {
            if (!currentInlineSdtWrapper) {
              currentInlineSdtWrapper = this.createInlineSdtWrapper(resolved.sdt);
              currentInlineSdtId = runSdtId;
            }
            this.expandSdtWrapperPmRange(currentInlineSdtWrapper, run.pmStart, run.pmEnd);
            currentInlineSdtWrapper.appendChild(elem);
          } else {
            el.appendChild(elem);
          }
        }
      });

      // Close any remaining wrapper at end of line
      closeCurrentWrapper();
    }

    // Post-process: Apply tooltip accessibility for any links with pending tooltips
    // This must happen after elements are in the DOM so aria-describedby can reference siblings
    const anchors = el.querySelectorAll('a[href]');
    anchors.forEach((anchor) => {
      const pendingTooltip = this.pendingTooltips.get(anchor as HTMLElement);
      if (pendingTooltip) {
        this.applyTooltipAccessibility(anchor as HTMLAnchorElement, pendingTooltip);
        this.pendingTooltips.delete(anchor as HTMLElement); // Clean up memory
      }
    });

    return el;
  }

  private resolveTrackedChangesConfig(block: ParagraphBlock): TrackedChangesRenderConfig {
    const attrs = (block.attrs as ParagraphAttrs | undefined) ?? {};
    const mode = (attrs.trackedChangesMode as TrackedChangesMode | undefined) ?? 'review';
    const enabled = attrs.trackedChangesEnabled !== false;
    return { mode, enabled };
  }

  private applyTrackedChangeDecorations(elem: HTMLElement, run: Run, config: TrackedChangesRenderConfig): void {
    if (!config.enabled || config.mode === 'off') {
      return;
    }

    const textRun = run as TextRun;
    const meta = textRun.trackedChange;
    if (!meta) {
      return;
    }

    const baseClass = TRACK_CHANGE_BASE_CLASS[meta.kind];
    if (baseClass) {
      elem.classList.add(baseClass);
    }

    const modifier = TRACK_CHANGE_MODIFIER_CLASS[meta.kind]?.[config.mode];
    if (modifier) {
      elem.classList.add(modifier);
    }

    elem.dataset.trackChangeId = meta.id;
    elem.dataset.trackChangeKind = meta.kind;
    if (meta.author) {
      elem.dataset.trackChangeAuthor = meta.author;
    }
    if (meta.authorEmail) {
      elem.dataset.trackChangeAuthorEmail = meta.authorEmail;
    }
    if (meta.authorImage) {
      elem.dataset.trackChangeAuthorImage = meta.authorImage;
    }
    if (meta.date) {
      elem.dataset.trackChangeDate = meta.date;
    }
    // track-change-focused class is applied post-paint by CommentHighlightDecorator (super-editor).
  }

  /**
   * Updates an existing fragment element's position and dimensions in place.
   * Used during incremental updates to efficiently reposition fragments without full re-render.
   *
   * @param el - The HTMLElement representing the fragment to update
   * @param fragment - The fragment data containing updated position and dimensions
   * @param section - The document section ('body', 'header', 'footer') containing this fragment.
   *                  Affects PM position validation - only body sections validate PM positions.
   *                  If undefined, defaults to 'body' section behavior.
   */
  private updateFragmentElement(
    el: HTMLElement,
    fragment: Fragment,
    section?: 'body' | 'header' | 'footer',
    resolvedItem?: ResolvedPaintItem,
  ): void {
    // Narrow to fragment-kind resolved items (excludes ResolvedGroupItem)
    const fragmentItem = resolvedItem?.kind === 'fragment' ? resolvedItem : undefined;

    if (fragment.kind === 'list-item' && fragmentItem) {
      this.applyResolvedListItemWrapperFrame(el, fragment, fragmentItem as ResolvedFragmentItem, section);
      return;
    }

    if (fragmentItem) {
      this.applyResolvedFragmentFrame(el, fragmentItem, fragment, section);
    } else {
      this.applyFragmentFrame(el, fragment, section);
      if (fragment.kind === 'image' || fragment.kind === 'drawing') {
        el.style.height = `${fragment.height}px`;
        this.applyFragmentWrapperZIndex(el, fragment);
      }
    }
  }

  /**
   * Applies fragment positioning, dimensions, and metadata to an HTML element.
   * Sets CSS positioning, block ID, and PM position data attributes for paragraph fragments.
   *
   * @param el - The HTMLElement to apply fragment properties to
   * @param fragment - The fragment data containing position, dimensions, and PM position information
   * @param section - The document section ('body', 'header', 'footer') containing this fragment.
   *                  Controls PM position validation behavior:
   *                  - 'body' or undefined: PM positions are validated and required for paragraph fragments
   *                  - 'header' or 'footer': PM position validation is skipped (these sections have separate PM coordinate spaces)
   *                  When undefined, defaults to 'body' section behavior (validation enabled).
   */
  private applyFragmentFrame(el: HTMLElement, fragment: Fragment, section?: 'body' | 'header' | 'footer'): void {
    el.style.left = `${fragment.x}px`;
    el.style.top = `${fragment.y}px`;
    el.style.width = `${fragment.width}px`;
    el.dataset.blockId = fragment.blockId;
    el.dataset.layoutEpoch = String(this.layoutEpoch);

    // Footnote content is read-only: prevent cursor placement and typing (blockId prefix from FootnotesBuilder)
    if (typeof fragment.blockId === 'string' && fragment.blockId.startsWith('footnote-')) {
      el.setAttribute('contenteditable', 'false');
    }

    if (fragment.kind === 'para') {
      // Assert PM positions are present for paragraph fragments
      // Only validate for body sections - header/footer fragments have their own PM coordinate space
      // Note: undefined section defaults to body section behavior (validation enabled)
      if (section === 'body' || section === undefined) {
        assertFragmentPmPositions(fragment, 'paragraph fragment');
      }

      if (fragment.pmStart != null) {
        el.dataset.pmStart = String(fragment.pmStart);
      } else {
        delete el.dataset.pmStart;
      }
      if (fragment.pmEnd != null) {
        el.dataset.pmEnd = String(fragment.pmEnd);
      } else {
        delete el.dataset.pmEnd;
      }
      if (fragment.continuesFromPrev) {
        el.dataset.continuesFromPrev = 'true';
      } else {
        delete el.dataset.continuesFromPrev;
      }
      if (fragment.continuesOnNext) {
        el.dataset.continuesOnNext = 'true';
      } else {
        delete el.dataset.continuesOnNext;
      }
    }
  }

  /**
   * Applies PM position data attributes from a legacy Fragment.
   * Extracted from applyFragmentFrame for use in the resolved wrapper path.
   * When a resolvedItem is provided, its fields take precedence over fragment fields.
   */
  private applyFragmentPmAttributes(
    el: HTMLElement,
    fragment: Fragment,
    section?: 'body' | 'header' | 'footer',
    resolvedItem?: ResolvedFragmentItem | ResolvedTableItem | ResolvedImageItem | ResolvedDrawingItem,
  ): void {
    // Footnote content is read-only: prevent cursor placement and typing
    if (typeof fragment.blockId === 'string' && fragment.blockId.startsWith('footnote-')) {
      el.setAttribute('contenteditable', 'false');
    }

    if (fragment.kind === 'para') {
      if (section === 'body' || section === undefined) {
        assertFragmentPmPositions(fragment, 'paragraph fragment');
      }
      // Narrow to ResolvedFragmentItem to access para-specific resolved fields
      const resolvedFrag = resolvedItem as ResolvedFragmentItem | undefined;
      const pmStart = resolvedFrag?.pmStart ?? (fragment as ParaFragment).pmStart;
      if (pmStart != null) {
        el.dataset.pmStart = String(pmStart);
      } else {
        delete el.dataset.pmStart;
      }
      const pmEnd = resolvedFrag?.pmEnd ?? (fragment as ParaFragment).pmEnd;
      if (pmEnd != null) {
        el.dataset.pmEnd = String(pmEnd);
      } else {
        delete el.dataset.pmEnd;
      }
      const continuesFromPrev = resolvedFrag?.continuesFromPrev ?? (fragment as ParaFragment).continuesFromPrev;
      if (continuesFromPrev) {
        el.dataset.continuesFromPrev = 'true';
      } else {
        delete el.dataset.continuesFromPrev;
      }
      const continuesOnNext = resolvedFrag?.continuesOnNext ?? (fragment as ParaFragment).continuesOnNext;
      if (continuesOnNext) {
        el.dataset.continuesOnNext = 'true';
      } else {
        delete el.dataset.continuesOnNext;
      }
    }
  }

  /**
   * Applies fragment wrapper positioning from a ResolvedFragmentItem.
   * Uses resolved data for spatial properties and delegates PM attributes to the legacy path.
   */
  private isAnchoredMediaFragment(fragment: Fragment): fragment is ImageFragment | DrawingFragment {
    return (fragment.kind === 'image' || fragment.kind === 'drawing') && fragment.isAnchored === true;
  }

  /**
   * Only anchored images and drawings participate in explicit wrapper stacking.
   * Inline media intentionally rely on DOM order to preserve legacy paint order.
   */
  private resolveFragmentWrapperZIndex(fragment: Fragment, resolvedZIndex?: number): string {
    if (!this.isAnchoredMediaFragment(fragment)) {
      return '';
    }

    const zIndex = resolvedZIndex ?? fragment.zIndex;
    return zIndex != null ? String(zIndex) : '';
  }

  private applyFragmentWrapperZIndex(el: HTMLElement, fragment: Fragment, resolvedZIndex?: number): void {
    el.style.zIndex = this.resolveFragmentWrapperZIndex(fragment, resolvedZIndex);
  }

  private applyResolvedFragmentFrame(
    el: HTMLElement,
    item: ResolvedFragmentItem | ResolvedTableItem | ResolvedImageItem | ResolvedDrawingItem,
    fragment: Fragment,
    section?: 'body' | 'header' | 'footer',
  ): void {
    el.style.left = `${item.x}px`;
    el.style.top = `${item.y}px`;
    el.style.width = `${item.width}px`;
    el.dataset.blockId = item.blockId;
    el.dataset.layoutEpoch = String(this.layoutEpoch);
    this.applyFragmentWrapperZIndex(el, fragment, item.zIndex);

    if (item.fragmentKind === 'image' || item.fragmentKind === 'drawing' || item.fragmentKind === 'table') {
      el.style.height = `${item.height}px`;
    }

    this.applyFragmentPmAttributes(el, fragment, section, item);
  }

  /**
   * Applies the resolved wrapper frame for a list-item fragment.
   *
   * List-item wrappers intentionally extend into the marker gutter. The resolved
   * fragment item stores the paragraph content box, so the marker-width expansion
   * must be applied consistently on both initial render and incremental updates.
   */
  private applyResolvedListItemWrapperFrame(
    el: HTMLElement,
    fragment: ListItemFragment,
    item: ResolvedFragmentItem,
    section?: 'body' | 'header' | 'footer',
  ): void {
    this.applyResolvedFragmentFrame(el, item, fragment, section);
    const mw = item.markerWidth ?? fragment.markerWidth;
    el.style.left = `${item.x - mw}px`;
    el.style.width = `${item.width + mw}px`;
  }

  /**
   * Estimates the height of a fragment when explicit height is not available.
   *
   * This method provides fallback height calculations for footer bottom-alignment
   * by consulting measure data for paragraphs and list items, or using the
   * fragment's height property for tables, images, and drawings.
   *
   * @param fragment - The fragment to estimate height for
   * @returns Estimated height in pixels, or 0 if height cannot be determined
   */
  private estimateFragmentHeight(fragment: Fragment): number {
    const lookup = this.blockLookup.get(fragment.blockId);
    const measure = lookup?.measure;

    if (fragment.kind === 'para' && measure?.kind === 'paragraph') {
      return measure.totalHeight;
    }

    if (fragment.kind === 'list-item' && measure?.kind === 'list') {
      return measure.totalHeight;
    }

    if (fragment.kind === 'table') {
      return fragment.height;
    }

    if (fragment.kind === 'image' || fragment.kind === 'drawing') {
      return fragment.height;
    }

    return 0;
  }

  /**
   * Resolves the block + measure pair for a fragment. Body fragments get these from the
   * ResolvedFragmentItem; header/footer fragments fall back to the blockLookup map.
   */
  private resolveBlockAndMeasure<B extends FlowBlock, M extends Measure>(
    fragment: { blockId: string },
    resolvedBlock: FlowBlock | undefined,
    resolvedMeasure: Measure | undefined,
    blockKind: B['kind'],
    measureKind: M['kind'],
    errorLabel: string,
  ): { block: B; measure: M } {
    if (resolvedBlock?.kind === blockKind && resolvedMeasure?.kind === measureKind) {
      return { block: resolvedBlock as B, measure: resolvedMeasure as M };
    }
    const lookup = this.blockLookup.get(fragment.blockId);
    if (!lookup || lookup.block.kind !== blockKind || lookup.measure.kind !== measureKind) {
      throw new Error(`DomPainter: missing ${errorLabel} for fragment ${fragment.blockId}`);
    }
    return { block: lookup.block as B, measure: lookup.measure as M };
  }

  /**
   * Resolves only the block for a fragment (image/drawing rendering doesn't consume the measure).
   * Body fragments get this from the ResolvedImageItem/ResolvedDrawingItem; header/footer
   * fragments fall back to the blockLookup map.
   */
  private resolveBlock<B extends FlowBlock>(
    fragment: { blockId: string },
    resolvedBlock: B | undefined,
    blockKind: B['kind'],
    errorLabel: string,
  ): B {
    if (resolvedBlock?.kind === blockKind) {
      return resolvedBlock;
    }
    const lookup = this.blockLookup.get(fragment.blockId);
    if (!lookup || lookup.block.kind !== blockKind) {
      throw new Error(`DomPainter: missing ${errorLabel} for fragment ${fragment.blockId}`);
    }
    return lookup.block as B;
  }

  private buildBlockLookup(blocks: FlowBlock[], measures: Measure[]): BlockLookup {
    if (blocks.length !== measures.length) {
      throw new Error('DomPainter requires the same number of blocks and measures');
    }

    const lookup: BlockLookup = new Map();
    blocks.forEach((block, index) => {
      lookup.set(block.id, {
        block,
        measure: measures[index],
        version: deriveBlockVersion(block),
      });
    });
    return lookup;
  }

  /**
   * All dataset keys used for SDT metadata.
   * Shared between applySdtDataset and clearSdtDataset to ensure consistency.
   */
  private static readonly SDT_DATASET_KEYS = [
    'sdtType',
    'sdtId',
    'sdtFieldId',
    'sdtFieldType',
    'sdtFieldVariant',
    'sdtFieldVisibility',
    'sdtFieldHidden',
    'sdtFieldLocked',
    'sdtScope',
    'sdtTag',
    'sdtAlias',
    'lockMode',
    'sdtSectionTitle',
    'sdtSectionType',
    'sdtSectionLocked',
    'sdtDocpartGallery',
    'sdtDocpartId',
    'sdtDocpartInstruction',
  ] as const;

  /**
   * Helper to set a string dataset attribute if the value is truthy.
   */
  private setDatasetString(el: HTMLElement, key: string, value: string | null | undefined): void {
    if (value) {
      el.dataset[key] = value;
    }
  }

  /**
   * Helper to set a boolean dataset attribute if the value is not null/undefined.
   */
  private setDatasetBoolean(el: HTMLElement, key: string, value: boolean | null | undefined): void {
    if (value != null) {
      el.dataset[key] = String(value);
    }
  }

  /**
   * Resolve the inline SDT id from a run, or null if the run is not inside an inline SDT.
   */
  private resolveRunSdtId(run: Run): { sdtId: string; sdt: SdtMetadata } | null {
    const sdt = (run as TextRun).sdt;
    if (sdt?.type === 'structuredContent' && sdt?.scope === 'inline' && sdt?.id) {
      return { sdtId: String(sdt.id), sdt };
    }
    return null;
  }

  /**
   * Create an inline SDT wrapper `<span>` with className, layoutEpoch, dataset, and label.
   * Shared by both the geometry and run-based rendering paths.
   */
  private createInlineSdtWrapper(sdt: SdtMetadata): HTMLElement {
    const wrapper = this.doc!.createElement('span');
    wrapper.className = DOM_CLASS_NAMES.INLINE_SDT_WRAPPER;
    wrapper.dataset.layoutEpoch = String(this.layoutEpoch);
    this.applySdtDataset(wrapper, sdt);
    const alias = (sdt as { alias?: string })?.alias || 'Inline content';
    const labelEl = this.doc!.createElement('span');
    labelEl.className = `${DOM_CLASS_NAMES.INLINE_SDT_WRAPPER}__label`;
    labelEl.textContent = alias;
    wrapper.appendChild(labelEl);
    return wrapper;
  }

  /**
   * Expand the PM position range tracked on an SDT wrapper to include a new run's range.
   */
  private expandSdtWrapperPmRange(wrapper: HTMLElement, pmStart?: number | null, pmEnd?: number | null): void {
    if (pmStart != null) {
      const cur = wrapper.dataset.pmStart;
      if (!cur || pmStart < parseInt(cur, 10)) {
        wrapper.dataset.pmStart = String(pmStart);
      }
    }
    if (pmEnd != null) {
      const cur = wrapper.dataset.pmEnd;
      if (!cur || pmEnd > parseInt(cur, 10)) {
        wrapper.dataset.pmEnd = String(pmEnd);
      }
    }
  }

  /**
   * Applies SDT (Structured Document Tag) metadata to an element's dataset as data-sdt-* attributes.
   * Supports field annotations, structured content, document sections, and doc parts.
   * Clears existing SDT metadata before applying new values.
   *
   * @param el - The HTML element to annotate
   * @param metadata - The SDT metadata to render as data attributes
   */
  private applySdtDataset(el: HTMLElement | null, metadata?: SdtMetadata | null): void {
    if (!el?.dataset) return;
    this.clearSdtDataset(el);
    if (!metadata) return;

    el.dataset.sdtType = metadata.type;

    if ('id' in metadata && metadata.id != null) {
      el.dataset.sdtId = String(metadata.id);
    }

    if (metadata.type === 'fieldAnnotation') {
      this.setDatasetString(el, 'sdtFieldId', metadata.fieldId);
      this.setDatasetString(el, 'sdtFieldType', metadata.fieldType);
      this.setDatasetString(el, 'sdtFieldVariant', metadata.variant);
      this.setDatasetString(el, 'sdtFieldVisibility', metadata.visibility);
      this.setDatasetBoolean(el, 'sdtFieldHidden', metadata.hidden);
      this.setDatasetBoolean(el, 'sdtFieldLocked', metadata.isLocked);
    } else if (metadata.type === 'structuredContent') {
      this.setDatasetString(el, 'sdtScope', metadata.scope);
      this.setDatasetString(el, 'sdtTag', metadata.tag);
      this.setDatasetString(el, 'sdtAlias', metadata.alias);
      // Always set lockMode (defaulting to 'unlocked') so CSS can target all SDTs uniformly.
      this.setDatasetString(el, 'lockMode', metadata.lockMode || 'unlocked');
    } else if (metadata.type === 'documentSection') {
      this.setDatasetString(el, 'sdtSectionTitle', metadata.title);
      this.setDatasetString(el, 'sdtSectionType', metadata.sectionType);
      this.setDatasetBoolean(el, 'sdtSectionLocked', metadata.isLocked);
    } else if (metadata.type === 'docPartObject') {
      this.setDatasetString(el, 'sdtDocpartGallery', metadata.gallery);
      this.setDatasetString(el, 'sdtDocpartId', metadata.uniqueId);
      this.setDatasetString(el, 'sdtDocpartInstruction', metadata.instruction);
    }
  }

  private clearSdtDataset(el: HTMLElement): void {
    DomPainter.SDT_DATASET_KEYS.forEach((key) => {
      delete el.dataset[key];
    });
  }

  /**
   * Applies container SDT metadata to an element's dataset (data-sdt-container-* attributes).
   * Used when a block has both primary SDT metadata (e.g., docPartObject) and container
   * metadata (e.g., documentSection). The container metadata is rendered with a "Container"
   * prefix to distinguish it from the primary SDT metadata.
   *
   * @param el - The HTML element to annotate
   * @param metadata - The container SDT metadata (typically documentSection)
   */
  private applyContainerSdtDataset(el: HTMLElement | null, metadata?: SdtMetadata | null): void {
    if (!el?.dataset) return;
    if (!metadata) return;

    el.dataset.sdtContainerType = metadata.type;

    if ('id' in metadata && metadata.id != null) {
      el.dataset.sdtContainerId = String(metadata.id);
    }

    if (metadata.type === 'documentSection') {
      this.setDatasetString(el, 'sdtContainerSectionTitle', metadata.title);
      this.setDatasetString(el, 'sdtContainerSectionType', metadata.sectionType);
      this.setDatasetBoolean(el, 'sdtContainerSectionLocked', metadata.isLocked);
    }
    // Other container types can be added here if needed
  }
}

const getFragmentSdtContainerKey = (fragment: Fragment, blockLookup: BlockLookup): string | null => {
  const lookup = blockLookup.get(fragment.blockId);
  if (!lookup) return null;
  const block = lookup.block;

  if (fragment.kind === 'para' && block.kind === 'paragraph') {
    const attrs = (block as { attrs?: { sdt?: SdtMetadata; containerSdt?: SdtMetadata } }).attrs;
    return getSdtContainerKey(attrs?.sdt, attrs?.containerSdt);
  }

  if (fragment.kind === 'list-item' && block.kind === 'list') {
    const item = block.items.find((listItem) => listItem.id === fragment.itemId);
    const attrs = item?.paragraph.attrs;
    return getSdtContainerKey(attrs?.sdt, attrs?.containerSdt);
  }

  if (fragment.kind === 'table' && block.kind === 'table') {
    const attrs = (block as { attrs?: { sdt?: SdtMetadata; containerSdt?: SdtMetadata } }).attrs;
    return getSdtContainerKey(attrs?.sdt, attrs?.containerSdt);
  }

  return null;
};

const computeSdtBoundaries = (
  fragments: readonly Fragment[],
  blockLookup: BlockLookup,
  sdtLabelsRendered: Set<string>,
  resolvedItems?: readonly ResolvedPaintItem[],
): Map<number, SdtBoundaryOptions> => {
  const boundaries = new Map<number, SdtBoundaryOptions>();
  const containerKeys: (string | null)[] = resolvedItems
    ? resolvedItems.map((item) => {
        if ('sdtContainerKey' in item) {
          const key = (item as { sdtContainerKey?: string | null }).sdtContainerKey;
          return key ?? null;
        }
        return null;
      })
    : fragments.map((fragment) => getFragmentSdtContainerKey(fragment, blockLookup));

  let i = 0;
  while (i < fragments.length) {
    const currentKey = containerKeys[i];
    if (!currentKey) {
      i += 1;
      continue;
    }

    let groupRight = fragments[i].x + fragments[i].width;
    let j = i;

    while (j + 1 < fragments.length && containerKeys[j + 1] === currentKey) {
      j += 1;
      const fragmentRight = fragments[j].x + fragments[j].width;
      if (fragmentRight > groupRight) {
        groupRight = fragmentRight;
      }
    }

    for (let k = i; k <= j; k += 1) {
      const fragment = fragments[k];
      const isStart = k === i;
      const isEnd = k === j;

      let paddingBottomOverride: number | undefined;
      if (!isEnd) {
        const nextFragment = fragments[k + 1];
        const currentHeight = resolvedItems?.[k]?.height ?? getFragmentHeight(fragment, blockLookup);
        const currentBottom = fragment.y + currentHeight;
        const gapToNext = nextFragment.y - currentBottom;
        if (gapToNext > 0) {
          paddingBottomOverride = gapToNext;
        }
      }

      const showLabel = isStart && !sdtLabelsRendered.has(currentKey);
      if (showLabel) {
        sdtLabelsRendered.add(currentKey);
      }

      boundaries.set(k, {
        isStart,
        isEnd,
        widthOverride: groupRight - fragment.x,
        paddingBottomOverride,
        showLabel,
      });
    }

    i = j + 1;
  }

  return boundaries;
};

// getFragmentParagraphBorders, computeBetweenBorderFlags — moved to features/paragraph-borders/

const fragmentKey = (fragment: Fragment): string => {
  if (fragment.kind === 'para') {
    return `para:${fragment.blockId}:${fragment.fromLine}:${fragment.toLine}`;
  }
  if (fragment.kind === 'list-item') {
    return `list-item:${fragment.blockId}:${fragment.itemId}:${fragment.fromLine}:${fragment.toLine}`;
  }
  if (fragment.kind === 'image') {
    return `image:${fragment.blockId}:${fragment.x}:${fragment.y}`;
  }
  if (fragment.kind === 'drawing') {
    return `drawing:${fragment.blockId}:${fragment.x}:${fragment.y}`;
  }
  if (fragment.kind === 'table') {
    // Include row range and partial row info to uniquely identify table fragments
    // This is critical for mid-row splitting where multiple fragments can exist for the same table
    const partialKey = fragment.partialRow
      ? `:${fragment.partialRow.fromLineByCell.join(',')}-${fragment.partialRow.toLineByCell.join(',')}`
      : '';
    return `table:${fragment.blockId}:${fragment.fromRow}:${fragment.toRow}${partialKey}`;
  }
  // Exhaustive check - all fragment kinds should be handled above
  const _exhaustiveCheck: never = fragment;
  return _exhaustiveCheck;
};

const fragmentSignature = (fragment: Fragment, lookup: BlockLookup): string => {
  const base = lookup.get(fragment.blockId)?.version ?? 'missing';
  if (fragment.kind === 'para') {
    // Note: pmStart/pmEnd intentionally excluded to prevent O(n) change detection
    return [
      base,
      fragment.fromLine,
      fragment.toLine,
      fragment.continuesFromPrev ? 1 : 0,
      fragment.continuesOnNext ? 1 : 0,
      fragment.markerWidth ?? '', // Include markerWidth to trigger re-render when list status changes
    ].join('|');
  }
  if (fragment.kind === 'list-item') {
    return [
      base,
      fragment.itemId,
      fragment.fromLine,
      fragment.toLine,
      fragment.continuesFromPrev ? 1 : 0,
      fragment.continuesOnNext ? 1 : 0,
    ].join('|');
  }
  if (fragment.kind === 'image') {
    return [base, fragment.width, fragment.height].join('|');
  }
  if (fragment.kind === 'drawing') {
    return [
      base,
      fragment.drawingKind,
      fragment.drawingContentId ?? '',
      fragment.width,
      fragment.height,
      fragment.geometry.width,
      fragment.geometry.height,
      fragment.geometry.rotation ?? 0,
      fragment.scale ?? 1,
      fragment.zIndex ?? '',
    ].join('|');
  }
  if (fragment.kind === 'table') {
    // Include all properties that affect table fragment rendering
    const partialSig = fragment.partialRow
      ? `${fragment.partialRow.fromLineByCell.join(',')}-${fragment.partialRow.toLineByCell.join(',')}-${fragment.partialRow.partialHeight}`
      : '';
    return [
      base,
      fragment.fromRow,
      fragment.toRow,
      fragment.width,
      fragment.height,
      fragment.continuesFromPrev ? 1 : 0,
      fragment.continuesOnNext ? 1 : 0,
      fragment.repeatHeaderCount ?? 0,
      partialSig,
    ].join('|');
  }
  return base;
};

const getSdtMetadataId = (metadata: SdtMetadata | null | undefined): string => {
  if (!metadata) return '';
  if ('id' in metadata && metadata.id != null) {
    return String(metadata.id);
  }
  return '';
};

const getSdtMetadataLockMode = (metadata: SdtMetadata | null | undefined): string => {
  if (!metadata) return '';
  return metadata.type === 'structuredContent' ? (metadata.lockMode ?? '') : '';
};

const getSdtMetadataVersion = (metadata: SdtMetadata | null | undefined): string => {
  if (!metadata) return '';
  return [metadata.type, getSdtMetadataLockMode(metadata), getSdtMetadataId(metadata)].join(':');
};

/**
 * Type guard to validate list marker attributes structure.
 *
 * @param attrs - The paragraph attributes to validate
 * @returns True if the attrs contain valid list marker properties
 */
const hasListMarkerProperties = (
  attrs: unknown,
): attrs is {
  numberingProperties: { numId?: number | string; ilvl?: number };
  wordLayout?: { marker?: { markerText?: string } };
} => {
  if (!attrs || typeof attrs !== 'object') return false;
  const obj = attrs as Record<string, unknown>;

  if (!obj.numberingProperties || typeof obj.numberingProperties !== 'object') return false;
  const numProps = obj.numberingProperties as Record<string, unknown>;

  // Validate numId is number or string if present
  if ('numId' in numProps) {
    const numId = numProps.numId;
    if (typeof numId !== 'number' && typeof numId !== 'string') return false;
  }

  // Validate ilvl is number if present
  if ('ilvl' in numProps) {
    const ilvl = numProps.ilvl;
    if (typeof ilvl !== 'number') return false;
  }

  // Validate wordLayout structure if present
  if ('wordLayout' in obj && obj.wordLayout !== undefined) {
    if (typeof obj.wordLayout !== 'object' || obj.wordLayout === null) return false;
    const wordLayout = obj.wordLayout as Record<string, unknown>;

    if ('marker' in wordLayout && wordLayout.marker !== undefined) {
      if (typeof wordLayout.marker !== 'object' || wordLayout.marker === null) return false;
      const marker = wordLayout.marker as Record<string, unknown>;

      if ('markerText' in marker && marker.markerText !== undefined) {
        if (typeof marker.markerText !== 'string') return false;
      }
    }
  }

  return true;
};

/**
 * Derives a version string for a flow block based on its content and styling properties.
 *
 * This version string is used for cache invalidation - when any visual property of the block
 * changes, the version string changes, triggering a DOM rebuild instead of reusing cached elements.
 *
 * The version includes all properties that affect visual rendering:
 * - Text content
 * - Font properties (family, size, bold, italic)
 * - Text decorations (underline style/color, strike, highlight)
 * - Spacing (letterSpacing)
 * - Position markers (pmStart, pmEnd)
 * - Special tokens (page numbers, etc.)
 * - List marker properties (numId, ilvl, markerText) - for list indent changes
 * - Paragraph attributes (alignment, spacing, indent, borders, shading, direction, rtl, tabs)
 * - Table cell content and paragraph formatting within cells
 *
 * For table blocks, a deep hash is computed across all rows and cells, including:
 * - Cell block content (paragraph runs, text, formatting)
 * - Paragraph-level attributes in cells (alignment, spacing, line height, indent, borders, shading)
 * - Run-level formatting (color, highlight, bold, italic, fontSize, fontFamily, underline, strike)
 *
 * This ensures toolbar commands that modify paragraph or run formatting within tables
 * trigger proper DOM updates.
 *
 * @param block - The flow block to generate a version string for
 * @returns A pipe-delimited string representing all visual properties of the block.
 *          Changes to any included property will change the version string.
 */
const deriveBlockVersion = (block: FlowBlock): string => {
  if (block.kind === 'paragraph') {
    // Include list marker info in version to detect indent/marker changes
    const markerVersion = hasListMarkerProperties(block.attrs)
      ? `marker:${block.attrs.numberingProperties.numId ?? ''}:${block.attrs.numberingProperties.ilvl ?? 0}:${block.attrs.wordLayout?.marker?.markerText ?? ''}`
      : '';

    const runsVersion = block.runs
      .map((run) => {
        // Handle ImageRun
        if (run.kind === 'image') {
          const imgRun = run as ImageRun;
          return [
            'img',
            imgRun.src,
            imgRun.width,
            imgRun.height,
            imgRun.alt ?? '',
            imgRun.title ?? '',
            imgRun.clipPath ?? '',
            imgRun.distTop ?? '',
            imgRun.distBottom ?? '',
            imgRun.distLeft ?? '',
            imgRun.distRight ?? '',
            readClipPathValue((imgRun as { clipPath?: unknown }).clipPath),
            // Note: pmStart/pmEnd intentionally excluded to prevent O(n) change detection
          ].join(',');
        }

        // Handle LineBreakRun
        if (run.kind === 'lineBreak') {
          // Note: pmStart/pmEnd intentionally excluded to prevent O(n) change detection
          return 'linebreak';
        }

        // Handle TabRun
        if (run.kind === 'tab') {
          // Note: pmStart/pmEnd intentionally excluded to prevent O(n) change detection
          return [run.text ?? '', 'tab'].join(',');
        }

        // Handle FieldAnnotationRun
        if (run.kind === 'fieldAnnotation') {
          const size = run.size ? `${run.size.width ?? ''}x${run.size.height ?? ''}` : '';
          const highlighted = run.highlighted !== false ? 1 : 0;
          return [
            'field',
            run.variant ?? '',
            run.displayLabel ?? '',
            run.fieldColor ?? '',
            run.borderColor ?? '',
            highlighted,
            run.hidden ? 1 : 0,
            run.visibility ?? '',
            run.imageSrc ?? '',
            run.linkUrl ?? '',
            run.rawHtml ?? '',
            size,
            run.fontFamily ?? '',
            run.fontSize ?? '',
            run.textColor ?? '',
            run.textHighlight ?? '',
            run.bold ? 1 : 0,
            run.italic ? 1 : 0,
            run.underline ? 1 : 0,
            run.fieldId ?? '',
            run.fieldType ?? '',
          ].join(',');
        }

        // Handle TextRun (kind is 'text' or undefined)
        const textRun = run as TextRun;
        return [
          textRun.text ?? '',
          textRun.fontFamily,
          textRun.fontSize,
          textRun.bold ? 1 : 0,
          textRun.italic ? 1 : 0,
          textRun.color ?? '',
          // Text decorations - ensures DOM updates when decoration properties change.
          textRun.underline?.style ?? '',
          textRun.underline?.color ?? '',
          textRun.strike ? 1 : 0,
          textRun.highlight ?? '',
          textRun.letterSpacing != null ? textRun.letterSpacing : '',
          textRun.vertAlign ?? '',
          textRun.baselineShift != null ? textRun.baselineShift : '',
          // Note: pmStart/pmEnd intentionally excluded to prevent O(n) change detection
          textRun.token ?? '',
          // Tracked changes - force re-render when added or removed tracked change
          textRun.trackedChange ? 1 : 0,
          // Comment annotations - force re-render when comments are enabled/disabled
          textRun.comments?.length ?? 0,
        ].join(',');
      })
      .join('|');

    // Include paragraph-level attributes that affect rendering (alignment, spacing, indent, etc.)
    // This ensures DOM updates when toolbar commands like "align center" change these properties.
    const attrs = block.attrs as ParagraphAttrs | undefined;

    const paragraphAttrsVersion = attrs
      ? [
          attrs.alignment ?? '',
          attrs.spacing?.before ?? '',
          attrs.spacing?.after ?? '',
          attrs.spacing?.line ?? '',
          attrs.spacing?.lineRule ?? '',
          attrs.indent?.left ?? '',
          attrs.indent?.right ?? '',
          attrs.indent?.firstLine ?? '',
          attrs.indent?.hanging ?? '',
          attrs.borders ? hashParagraphBorders(attrs.borders) : '',
          attrs.shading?.fill ?? '',
          attrs.shading?.color ?? '',
          attrs.direction ?? '',
          attrs.rtl ? '1' : '',
          attrs.tabs?.length ? JSON.stringify(attrs.tabs) : '',
        ].join(':')
      : '';

    // Include SDT metadata so lock-mode (and other SDT property) changes invalidate the cache.
    const sdtAttrs = (block.attrs as ParagraphAttrs | undefined)?.sdt;
    const sdtVersion = getSdtMetadataVersion(sdtAttrs);

    // Combine marker version, runs version, paragraph attrs version, and SDT version
    const parts = [markerVersion, runsVersion, paragraphAttrsVersion, sdtVersion].filter(Boolean);
    return parts.join('|');
  }

  if (block.kind === 'list') {
    return block.items.map((item) => `${item.id}:${item.marker.text}:${deriveBlockVersion(item.paragraph)}`).join('|');
  }

  if (block.kind === 'image') {
    const imgSdt = (block as ImageBlock).attrs?.sdt;
    const imgSdtVersion = getSdtMetadataVersion(imgSdt);
    return [
      block.src ?? '',
      block.width ?? '',
      block.height ?? '',
      block.alt ?? '',
      block.title ?? '',
      resolveBlockClipPath(block),
      imgSdtVersion,
    ].join('|');
  }

  if (block.kind === 'drawing') {
    if (block.drawingKind === 'image') {
      // Type narrowing: block is ImageDrawing (not ImageBlock)
      const imageLike = block as ImageDrawing;
      return [
        'drawing:image',
        imageLike.src ?? '',
        imageLike.width ?? '',
        imageLike.height ?? '',
        imageLike.alt ?? '',
        resolveBlockClipPath(imageLike),
      ].join('|');
    }
    if (block.drawingKind === 'vectorShape') {
      const vector = block as VectorShapeDrawing;
      return [
        'drawing:vector',
        vector.shapeKind ?? '',
        vector.fillColor ?? '',
        vector.strokeColor ?? '',
        vector.strokeWidth ?? '',
        vector.geometry.width,
        vector.geometry.height,
        vector.geometry.rotation ?? 0,
        vector.geometry.flipH ? 1 : 0,
        vector.geometry.flipV ? 1 : 0,
      ].join('|');
    }
    if (block.drawingKind === 'shapeGroup') {
      const group = block as ShapeGroupDrawing;
      const childSignature = group.shapes
        .map((child) => `${child.shapeType}:${JSON.stringify(child.attrs ?? {})}`)
        .join(';');
      return [
        'drawing:group',
        group.geometry.width,
        group.geometry.height,
        group.groupTransform ? JSON.stringify(group.groupTransform) : '',
        childSignature,
      ].join('|');
    }
    if (block.drawingKind === 'chart') {
      return [
        'drawing:chart',
        block.chartData?.chartType ?? '',
        block.chartData?.series?.length ?? 0,
        block.geometry.width,
        block.geometry.height,
        block.chartRelId ?? '',
      ].join('|');
    }
    // Exhaustiveness check: if a new drawingKind is added, TypeScript will error here
    const _exhaustive: never = block;
    return `drawing:unknown:${(block as DrawingBlock).id}`;
  }

  if (block.kind === 'table') {
    const tableBlock = block as TableBlock;
    /**
     * Local hash function for strings using FNV-1a algorithm.
     * Used to create a robust hash across all table rows/cells so deep edits invalidate version.
     *
     * @param seed - Initial hash value
     * @param value - String value to hash
     * @returns Updated hash value
     */
    const hashString = (seed: number, value: string): number => {
      let hash = seed >>> 0;
      for (let i = 0; i < value.length; i++) {
        hash ^= value.charCodeAt(i);
        hash = Math.imul(hash, 16777619); // FNV-style mix
      }
      return hash >>> 0;
    };

    /**
     * Local hash function for numbers.
     * Handles undefined/null values safely by treating them as 0.
     *
     * @param seed - Initial hash value
     * @param value - Number value to hash (or undefined/null)
     * @returns Updated hash value
     */
    const hashNumber = (seed: number, value: number | undefined | null): number => {
      const n = Number.isFinite(value) ? (value as number) : 0;
      let hash = seed ^ n;
      hash = Math.imul(hash, 16777619);
      hash ^= hash >>> 13;
      return hash >>> 0;
    };

    let hash = 2166136261;
    hash = hashString(hash, block.id);
    hash = hashNumber(hash, tableBlock.rows.length);
    hash = (tableBlock.columnWidths ?? []).reduce((acc, width) => hashNumber(acc, Math.round(width * 1000)), hash);

    // Defensive guards: ensure rows array exists and iterate safely
    const rows = tableBlock.rows ?? [];
    for (const row of rows) {
      if (!row || !Array.isArray(row.cells)) continue;
      hash = hashNumber(hash, row.cells.length);
      for (const cell of row.cells) {
        if (!cell) continue;
        const cellBlocks = cell.blocks ?? (cell.paragraph ? [cell.paragraph] : []);
        hash = hashNumber(hash, cellBlocks.length);
        // Include cell attributes that affect rendering (rowSpan, colSpan, borders, etc.)
        hash = hashNumber(hash, cell.rowSpan ?? 1);
        hash = hashNumber(hash, cell.colSpan ?? 1);

        // Include cell-level attributes (borders, padding, background) that affect rendering
        // This ensures cache invalidation when cell formatting changes (e.g., remove borders).
        if (cell.attrs) {
          const cellAttrs = cell.attrs as TableCellAttrs;
          if (cellAttrs.borders) {
            hash = hashString(hash, hashCellBorders(cellAttrs.borders));
          }
          if (cellAttrs.padding) {
            const p = cellAttrs.padding;
            hash = hashNumber(hash, p.top ?? 0);
            hash = hashNumber(hash, p.right ?? 0);
            hash = hashNumber(hash, p.bottom ?? 0);
            hash = hashNumber(hash, p.left ?? 0);
          }
          if (cellAttrs.verticalAlign) {
            hash = hashString(hash, cellAttrs.verticalAlign);
          }
          if (cellAttrs.background) {
            hash = hashString(hash, cellAttrs.background);
          }
        }

        for (const cellBlock of cellBlocks) {
          hash = hashString(hash, cellBlock?.kind ?? 'unknown');
          if (cellBlock?.kind === 'paragraph') {
            const paragraphBlock = cellBlock as ParagraphBlock;
            const runs = paragraphBlock.runs ?? [];
            hash = hashNumber(hash, runs.length);

            // Include paragraph-level attributes that affect rendering
            // (alignment, spacing, indent, etc.) - fixes toolbar commands not updating tables
            const attrs = paragraphBlock.attrs as ParagraphAttrs | undefined;

            if (attrs) {
              hash = hashString(hash, attrs.alignment ?? '');
              hash = hashNumber(hash, attrs.spacing?.before ?? 0);
              hash = hashNumber(hash, attrs.spacing?.after ?? 0);
              hash = hashNumber(hash, attrs.spacing?.line ?? 0);
              hash = hashString(hash, attrs.spacing?.lineRule ?? '');
              hash = hashNumber(hash, attrs.indent?.left ?? 0);
              hash = hashNumber(hash, attrs.indent?.right ?? 0);
              hash = hashNumber(hash, attrs.indent?.firstLine ?? 0);
              hash = hashNumber(hash, attrs.indent?.hanging ?? 0);
              hash = hashString(hash, attrs.shading?.fill ?? '');
              hash = hashString(hash, attrs.shading?.color ?? '');
              hash = hashString(hash, attrs.direction ?? '');
              hash = hashString(hash, attrs.rtl ? '1' : '');
              if (attrs.borders) {
                hash = hashString(hash, hashParagraphBorders(attrs.borders));
              }
            }

            for (const run of runs) {
              // Only text runs have .text property; ImageRun does not
              if ('text' in run && typeof run.text === 'string') {
                hash = hashString(hash, run.text);
              }
              hash = hashNumber(hash, run.pmStart ?? -1);
              hash = hashNumber(hash, run.pmEnd ?? -1);

              // Include run formatting properties that affect rendering
              // (color, highlight, bold, italic, etc.) - fixes toolbar commands not updating tables
              hash = hashString(hash, getRunStringProp(run, 'color'));
              hash = hashString(hash, getRunStringProp(run, 'highlight'));
              hash = hashString(hash, getRunBooleanProp(run, 'bold') ? '1' : '');
              hash = hashString(hash, getRunBooleanProp(run, 'italic') ? '1' : '');
              hash = hashNumber(hash, getRunNumberProp(run, 'fontSize'));
              hash = hashString(hash, getRunStringProp(run, 'fontFamily'));
              hash = hashString(hash, getRunUnderlineStyle(run));
              hash = hashString(hash, getRunUnderlineColor(run));
              hash = hashString(hash, getRunBooleanProp(run, 'strike') ? '1' : '');
              hash = hashString(hash, getRunStringProp(run, 'vertAlign'));
              hash = hashNumber(hash, getRunNumberProp(run, 'baselineShift'));
            }
          }
        }
      }
    }

    // Include table-level attributes (borders, etc.) that affect rendering
    // This ensures cache invalidation when table formatting changes (e.g., remove borders).
    if (tableBlock.attrs) {
      const tblAttrs = tableBlock.attrs as TableAttrs;
      if (tblAttrs.borders) {
        hash = hashString(hash, hashTableBorders(tblAttrs.borders));
      }
      if (tblAttrs.borderCollapse) {
        hash = hashString(hash, tblAttrs.borderCollapse);
      }
      if (tblAttrs.cellSpacing !== undefined) {
        const cs = tblAttrs.cellSpacing;
        if (typeof cs === 'number') {
          hash = hashNumber(hash, cs);
        } else {
          // Stable key: value and type only (avoid JSON.stringify key-order variance)
          const v = (cs as { value?: number; type?: string }).value ?? 0;
          const t = (cs as { value?: number; type?: string }).type ?? 'px';
          hash = hashString(hash, `cs:${v}:${t}`);
        }
      }
      // Include SDT metadata so lock-mode changes invalidate the cache.
      if (tblAttrs.sdt) {
        hash = hashString(hash, tblAttrs.sdt.type);
        hash = hashString(hash, getSdtMetadataLockMode(tblAttrs.sdt));
        hash = hashString(hash, getSdtMetadataId(tblAttrs.sdt));
      }
    }

    return [block.id, tableBlock.rows.length, hash.toString(16)].join('|');
  }

  return block.id;
};

const DEFAULT_SUPERSCRIPT_RAISE_RATIO = 0.33;
const DEFAULT_SUBSCRIPT_LOWER_RATIO = 0.14;

const hasVerticalPositioning = (run: TextRun): boolean =>
  normalizeBaselineShift(run.baselineShift) != null || run.vertAlign === 'superscript' || run.vertAlign === 'subscript';

const applyRunVerticalPositioning = (element: HTMLElement, run: TextRun): void => {
  // Vertically shifted runs should use a tight inline box. If they inherit the
  // parent line's full line-height, the glyph remains visually low inside an
  // oversized inline box even when the superscript/subscript offset is correct.
  if (hasVerticalPositioning(run)) {
    element.style.lineHeight = '1';
  }

  const explicitBaselineShift = normalizeBaselineShift(run.baselineShift);
  if (explicitBaselineShift != null) {
    element.style.verticalAlign = `${explicitBaselineShift}pt`;
    return;
  }

  if (run.vertAlign === 'superscript') {
    const baseFontSize = resolveBaseFontSizeForVerticalText(run.fontSize, run);
    element.style.verticalAlign = `${baseFontSize * DEFAULT_SUPERSCRIPT_RAISE_RATIO}px`;
    return;
  }

  if (run.vertAlign === 'subscript') {
    const baseFontSize = resolveBaseFontSizeForVerticalText(run.fontSize, run);
    element.style.verticalAlign = `${-(baseFontSize * DEFAULT_SUBSCRIPT_LOWER_RATIO)}px`;
    return;
  }

  if (run.vertAlign === 'baseline') {
    element.style.verticalAlign = 'baseline';
  }
};

/**
 * Applies run styling properties to a DOM element.
 *
 * @param element - The HTML element to style
 * @param run - The run object containing styling information
 * @param _isLink - Whether this run is part of a hyperlink. Note: This parameter
 *                  is kept for API compatibility but no longer affects behavior -
 *                  inline colors are now applied to all runs (including links) to
 *                  ensure OOXML hyperlink character styles appear correctly.
 */
const applyRunStyles = (element: HTMLElement, run: Run, _isLink = false): void => {
  if (
    run.kind === 'tab' ||
    run.kind === 'image' ||
    run.kind === 'lineBreak' ||
    run.kind === 'break' ||
    run.kind === 'fieldAnnotation' ||
    run.kind === 'math'
  ) {
    // Tab, image, lineBreak, break, and fieldAnnotation runs don't have text styling properties
    return;
  }

  element.style.fontFamily = run.fontFamily;
  element.style.fontSize = `${run.fontSize}px`;
  if (run.bold) element.style.fontWeight = 'bold';
  if (run.italic) element.style.fontStyle = 'italic';

  // Apply inline color even for links so OOXML hyperlink styles appear when CSS is absent
  if (run.color) element.style.color = run.color;

  if (run.letterSpacing != null) {
    element.style.letterSpacing = `${run.letterSpacing}px`;
  }
  if (run.highlight) {
    element.style.backgroundColor = run.highlight;
  }
  if (run.textTransform) {
    element.style.textTransform = run.textTransform;
  }

  // Apply text decorations from the run. Even for links, inline decorations should reflect
  // the document styling (tests assert underline presence on anchors).
  const decorations: string[] = [];
  if (run.underline) {
    decorations.push('underline');
    const u = run.underline;
    element.style.textDecorationStyle = u.style && u.style !== 'single' ? u.style : 'solid';
    if (u.color) {
      element.style.textDecorationColor = u.color;
    }
  }
  if (run.strike) {
    decorations.push('line-through');
  }
  if (decorations.length > 0) {
    element.style.textDecorationLine = decorations.join(' ');
  }

  applyRunVerticalPositioning(element, run);
};

const CLIP_PATH_PREFIXES = ['inset(', 'polygon(', 'circle(', 'ellipse(', 'path(', 'rect('];

const readClipPathValue = (value: unknown): string => {
  if (typeof value !== 'string') return '';
  const normalized = value.trim();
  if (normalized.length === 0) return '';
  const lower = normalized.toLowerCase();
  if (!CLIP_PATH_PREFIXES.some((prefix) => lower.startsWith(prefix))) return '';
  return normalized;
};

const resolveClipPathFromAttrs = (attrs: unknown): string => {
  if (!attrs || typeof attrs !== 'object') return '';
  const record = attrs as Record<string, unknown>;
  return readClipPathValue(record.clipPath);
};

const resolveBlockClipPath = (block: unknown): string => {
  if (!block || typeof block !== 'object') return '';
  const record = block as Record<string, unknown>;
  return readClipPathValue(record.clipPath) || resolveClipPathFromAttrs(record.attrs);
};

/**
 * Applies data-* attributes from a text run to a DOM element.
 * Validates attribute names and safely sets them on the element.
 * Invalid or unsafe attributes are skipped with development-mode logging.
 *
 * @param element - The HTML element to apply attributes to
 * @param dataAttrs - Record of data-* attribute key-value pairs from the text run
 *
 * @example
 * ```typescript
 * const span = document.createElement('span');
 * applyRunDataAttributes(span, { 'data-id': '123', 'data-name': 'test' });
 * // span now has: <span data-id="123" data-name="test"></span>
 * ```
 */
export const applyRunDataAttributes = (element: HTMLElement, dataAttrs?: Record<string, string>): void => {
  if (!dataAttrs) return;
  Object.entries(dataAttrs).forEach(([key, value]) => {
    if (typeof key !== 'string' || !key.toLowerCase().startsWith('data-')) return;
    if (typeof value !== 'string') return;
    try {
      element.setAttribute(key, value);
    } catch (error) {
      if (process.env.NODE_ENV === 'development') {
        console.warn(`[DomPainter] Failed to set data attribute "${key}":`, error);
      }
    }
  });
};

const resolveParagraphDirection = (attrs?: ParagraphAttrs): 'ltr' | 'rtl' | undefined => {
  if (attrs?.direction) {
    return attrs.direction;
  }
  if (attrs?.rtl === true) {
    return 'rtl';
  }
  if (attrs?.rtl === false) {
    return 'ltr';
  }
  return undefined;
};

const applyParagraphDirection = (element: HTMLElement, attrs?: ParagraphAttrs): void => {
  const direction = resolveParagraphDirection(attrs);
  if (!direction) {
    return;
  }
  element.setAttribute('dir', direction);
  element.style.direction = direction;
};

const applyParagraphBlockStyles = (element: HTMLElement, attrs?: ParagraphAttrs): void => {
  if (!attrs) return;
  if (attrs.styleId) {
    element.setAttribute('styleid', attrs.styleId);
  }
  applyRtlStyles(element, attrs);
  if ((attrs as Record<string, unknown>).dropCap) {
    element.classList.add('sd-editor-dropcap');
  }
  const indent = attrs.indent;
  if (indent) {
    // Only apply positive indents as padding.
    // Negative indents are handled by fragment positioning in the layout engine.
    if (indent.left && indent.left > 0) {
      element.style.paddingLeft = `${indent.left}px`;
    }
    if (indent.right && indent.right > 0) {
      element.style.paddingRight = `${indent.right}px`;
    }
    // Skip textIndent when left indent is negative - fragment positioning handles the indent,
    // and per-line paddingLeft handles the hanging indent for body lines.
    const hasNegativeLeftIndent = indent.left != null && indent.left < 0;
    if (!hasNegativeLeftIndent) {
      const textIndent = (indent.firstLine ?? 0) - (indent.hanging ?? 0);
      if (textIndent) {
        element.style.textIndent = `${textIndent}px`;
      }
    }
  }
};

// getParagraphBorderBox, createParagraphDecorationLayers, applyParagraphBorderStyles,
// setBorderSideStyle, applyParagraphShadingStyles — moved to features/paragraph-borders/

const stripListIndent = (attrs?: ParagraphAttrs): ParagraphAttrs | undefined => {
  if (!attrs?.indent || attrs.indent.left == null) {
    return attrs;
  }
  const nextIndent = { ...attrs.indent };
  delete nextIndent.left;

  return {
    ...attrs,
    indent: Object.keys(nextIndent).length > 0 ? nextIndent : undefined,
  };
};

// applyParagraphShadingStyles — moved to features/paragraph-borders/border-layer.ts

/**
 * Extracts and slices text runs that belong to a specific line within a paragraph block.
 * Handles partial runs at line boundaries by creating sliced copies with correct character ranges.
 *
 * @param {ParagraphBlock} block - The paragraph block containing runs
 * @param {Line} line - The line definition with fromRun/toRun and fromChar/toChar ranges
 * @returns {Run[]} Array of runs (or sliced run portions) that comprise the line
 *
 * @remarks
 * - Preserves run styling and metadata (pmStart, pmEnd positions) in sliced runs
 * - Tab runs are only included if the slice contains the actual tab character
 * - Text runs are sliced to match exact character boundaries of the line
 * - Returns empty array if no valid runs are found within the line range
 *
 * @example
 * ```typescript
 * const line = { fromRun: 0, toRun: 2, fromChar: 5, toChar: 10 };
 * const runs = sliceRunsForLine(paragraphBlock, line);
 * // Returns runs or run slices that fall within the specified character range
 * ```
 */
export const sliceRunsForLine = (block: ParagraphBlock, line: Line): Run[] => {
  const result: Run[] = [];

  for (let runIndex = line.fromRun; runIndex <= line.toRun; runIndex += 1) {
    const run = block.runs[runIndex];
    if (!run) continue;

    // FIXED: ImageRun handling - images are atomic units, no slicing needed
    if (run.kind === 'image') {
      result.push(run);
      continue;
    }

    // LineBreakRun handling - line breaks don't have text content and are handled
    // by the measurer creating new lines. Include them for PM position tracking.
    if (run.kind === 'lineBreak') {
      result.push(run);
      continue;
    }

    // BreakRun handling - similar to LineBreakRun
    if (run.kind === 'break') {
      result.push(run);
      continue;
    }

    // TabRun handling - tabs don't need slicing
    if (run.kind === 'tab') {
      result.push(run);
      continue;
    }

    // FieldAnnotationRun handling - field annotations are atomic units like images
    if (run.kind === 'fieldAnnotation') {
      result.push(run);
      continue;
    }

    // MathRun handling - math runs are atomic units like images
    if (run.kind === 'math') {
      result.push(run);
      continue;
    }

    // At this point, run must be TextRun (has .text property)
    if (!('text' in run)) {
      continue;
    }

    const text = run.text ?? '';
    const isFirstRun = runIndex === line.fromRun;
    const isLastRun = runIndex === line.toRun;
    const runLength = text.length;
    const runPmStart = run.pmStart ?? null;
    const fallbackPmEnd = runPmStart != null && run.pmEnd == null ? runPmStart + runLength : (run.pmEnd ?? null);

    if (isFirstRun || isLastRun) {
      const start = isFirstRun ? line.fromChar : 0;
      const end = isLastRun ? line.toChar : text.length;
      const slice = text.slice(start, end);
      if (!slice) continue;

      const pmSliceStart = runPmStart != null ? runPmStart + start : undefined;
      const pmSliceEnd = runPmStart != null ? runPmStart + end : (fallbackPmEnd ?? undefined);

      // TextRun: return a sliced TextRun preserving styles
      const sliced: TextRun = {
        ...(run as TextRun),
        text: slice,
        pmStart: pmSliceStart,
        pmEnd: pmSliceEnd,
        comments: (run as TextRun).comments ? [...(run as TextRun).comments!] : undefined,
      };
      result.push(sliced);
    } else {
      result.push(run);
    }
  }

  return result;
};

const applyStyles = (el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void => {
  Object.entries(styles).forEach(([key, value]) => {
    if (value != null && value !== '' && key in el.style) {
      (el.style as unknown as Record<string, string>)[key] = String(value);
    }
  });
};

const resolveRunText = (run: Run, context: FragmentRenderContext): string => {
  const runToken = 'token' in run ? run.token : undefined;

  if (run.kind === 'tab') {
    return run.text;
  }
  if (run.kind === 'image') {
    // Image runs don't have text content
    return '';
  }
  if (run.kind === 'lineBreak') {
    // Line break runs don't render text - the measurer creates new lines for them
    return '';
  }
  if (run.kind === 'break') {
    // Break runs don't render text - the measurer creates new lines for them
    return '';
  }
  if (!('text' in run)) {
    // Safety check - if run doesn't have text property, return empty string
    return '';
  }
  if (!runToken) {
    return run.text ?? '';
  }
  if (runToken === 'pageNumber') {
    return context.pageNumberText ?? String(context.pageNumber);
  }
  if (runToken === 'totalPageCount') {
    return context.totalPages ? String(context.totalPages) : (run.text ?? '');
  }
  return run.text ?? '';
};