documentation-hub 5.7.2

package/src/services/document/list/ListNormalizer.ts

@@ -0,0 +1,947 @@
+/**
+ * ListNormalizer - Core list normalization for document processing
+ *
+ * Moved from docxmlater to dochub-app for processing-level customization.
+ * Detects typed list prefixes and converts them to proper Word list formatting.
+ * Integrates with NumberingManager for numId resolution.
+ */
+
+import type { Paragraph, Run, Table, TableCell, NumberingManager } from "docxmlater";
+import { isRun, inchesToTwips } from "docxmlater";
+import { logger } from "@/utils/logger";
+import type {
+  ListCategory,
+  ListAnalysis,
+  ListNormalizationOptions,
+  ListNormalizationReport,
+  NumberFormat,
+  IndentationLevel,
+} from "./list-types";
+import {
+  detectListType,
+  getListCategoryFromFormat,
+  inferLevelFromRelativeIndentation,
+} from "./list-detection";
+
+// =============================================================================
+// INDENTATION SETTINGS HELPERS
+// =============================================================================
+
+/**
+ * Apply user's indentation settings to an abstract numbering definition.
+ */
+function applyIndentationSettings(
+  abstractNum: ReturnType<NumberingManager["getAbstractNumbering"]>,
+  indentationLevels: IndentationLevel[],
+  isBulletList: boolean,
+  extraHangingIndentTwips: number = 0
+): void {
+  if (!abstractNum || !indentationLevels || indentationLevels.length === 0) return;
+
+  for (const levelConfig of indentationLevels) {
+    const level = abstractNum.getLevel(levelConfig.level);
+    if (level) {
+      const textIndentTwips = inchesToTwips(levelConfig.textIndent) + extraHangingIndentTwips;
+      const symbolIndentTwips = inchesToTwips(levelConfig.symbolIndent);
+      const hangingTwips = textIndentTwips - symbolIndentTwips;
+
+      level.setLeftIndent(textIndentTwips);
+      level.setHangingIndent(hangingTwips);
+
+      if (isBulletList && levelConfig.bulletChar) {
+        level.setText(levelConfig.bulletChar);
+      }
+      if (!isBulletList && levelConfig.numberedFormat) {
+        level.setFormat(levelConfig.numberedFormat as NumberFormat);
+      }
+    }
+  }
+}
+
+// =============================================================================
+// ANALYSIS FUNCTIONS
+// =============================================================================
+
+/** Internal type for analyzed paragraph data */
+interface AnalyzedParagraph {
+  paragraph: Paragraph;
+  text: string;
+  detection: ReturnType<typeof detectListType>;
+}
+
+/**
+ * Determine majority category using OVERALL counts.
+ * Counts ALL list items equally (Word lists + typed prefixes).
+ * NUMBERED wins ties (business document standard).
+ */
+function determineMajorityCategory(analyzed: AnalyzedParagraph[]): ListCategory {
+  let bulletCount = 0;
+  let numberedCount = 0;
+
+  for (const item of analyzed) {
+    // Count BOTH Word lists AND typed prefixes equally
+    if (item.detection.category === "bullet") {
+      bulletCount++;
+    } else if (item.detection.category === "numbered") {
+      numberedCount++;
+    }
+  }
+
+  // No list items at all
+  if (bulletCount === 0 && numberedCount === 0) return "none";
+
+  // NUMBERED wins ties (business document standard)
+  // Bullets only win if strictly more bullets than numbers
+  return numberedCount >= bulletCount ? "numbered" : "bullet";
+}
+
+/**
+ * Analyze all paragraphs in a cell for list properties.
+ */
+export function analyzeCellLists(
+  cell: TableCell,
+  numberingManager?: NumberingManager
+): ListAnalysis {
+  const paragraphs = cell.getParagraphs();
+
+  const analyzed: AnalyzedParagraph[] = paragraphs.map((p) => ({
+    paragraph: p,
+    text: p.getText(),
+    detection: detectListType(p),
+  }));
+
+  // Refine Word list categories using NumberingManager
+  // detectListType() defaults ALL Word lists to "numbered", but we need to
+  // look up the actual format to correctly identify bullets vs numbers
+  if (numberingManager) {
+    for (const item of analyzed) {
+      if (item.detection.isWordList && item.detection.numId !== null) {
+        // Look up the actual format from numbering.xml
+        const instance = numberingManager.getInstance(item.detection.numId);
+        if (instance) {
+          const abstractNum = numberingManager.getAbstractNumbering(
+            instance.getAbstractNumId()
+          );
+          if (abstractNum) {
+            const level = abstractNum.getLevel(item.detection.ilvl ?? 0);
+            if (level) {
+              const format = level.getFormat();
+              // Refine the category based on actual format
+              item.detection.category = getListCategoryFromFormat(format);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Count by category
+  const counts = { numbered: 0, bullet: 0, none: 0 };
+  let hasTypedLists = false;
+  let hasWordLists = false;
+
+  for (const item of analyzed) {
+    const cat = item.detection.category;
+    counts[cat]++;
+
+    if (!item.detection.isWordList && item.detection.typedPrefix) {
+      hasTypedLists = true;
+    }
+    if (item.detection.isWordList) {
+      hasWordLists = true;
+    }
+  }
+
+  // Determine majority using OVERALL counts (Word + typed equally)
+  const majorityCategory = determineMajorityCategory(analyzed);
+
+  // Determine if normalization is needed:
+  // - Has typed prefixes that need converting, OR
+  // - Has mixed categories (bullets AND numbers) that need unifying
+  const hasMixedCategories = counts.numbered > 0 && counts.bullet > 0;
+  const needsNormalization = hasTypedLists || hasMixedCategories;
+
+  return {
+    paragraphs: analyzed,
+    hasTypedLists,
+    hasWordLists,
+    hasMixedCategories,
+    majorityCategory,
+    counts,
+    recommendedAction: needsNormalization ? "normalize" : "none",
+  };
+}
+
+/**
+ * Analyze lists in an entire table.
+ * Returns analysis per cell.
+ */
+export function analyzeTableLists(
+  table: Table
+): Map<TableCell, ListAnalysis> {
+  const results = new Map<TableCell, ListAnalysis>();
+
+  for (const row of table.getRows()) {
+    for (const cell of row.getCells()) {
+      results.set(cell, analyzeCellLists(cell));
+    }
+  }
+
+  return results;
+}
+
+// =============================================================================
+// NORMALIZATION FUNCTIONS
+// =============================================================================
+
+/**
+ * Strip typed prefix from paragraph text.
+ * Handles prefixes that may be split across multiple runs.
+ * Also trims leading whitespace from the remaining content.
+ */
+export function stripTypedPrefix(paragraph: Paragraph, prefix: string): void {
+  const content = paragraph.getContent();
+  let remainingPrefix = prefix;
+  let prefixFullyStripped = false;
+  // Track whether the prefix was stripped mid-run with content remaining.
+  // When true, the next run's leading space is an inter-word separator, not
+  // leftover prefix whitespace, so it must NOT be trimmed.
+  let strippedMidRunWithContent = false;
+
+  for (const item of content) {
+    if (isRun(item)) {
+      const run = item as Run;
+      const text = run.getText();
+
+      if (!prefixFullyStripped && remainingPrefix.length > 0) {
+        if (text.length <= remainingPrefix.length) {
+          // Entire run is part of prefix
+          if (remainingPrefix.startsWith(text)) {
+            remainingPrefix = remainingPrefix.substring(text.length);
+            run.setText(""); // Clear this run
+            if (remainingPrefix.length === 0) {
+              prefixFullyStripped = true;
+            }
+          }
+        } else {
+          // Partial match - strip prefix portion
+          if (text.startsWith(remainingPrefix)) {
+            const afterPrefix = text.substring(remainingPrefix.length).trimStart();
+            run.setText(afterPrefix);
+            prefixFullyStripped = true;
+            // If there's actual content left in this run after stripping,
+            // the next run's leading space is an inter-word separator
+            if (afterPrefix.length > 0) {
+              strippedMidRunWithContent = true;
+            }
+          }
+        }
+      } else if (prefixFullyStripped && !strippedMidRunWithContent) {
+        // Only trim the next run if the prefix was consumed at a run boundary
+        // (not mid-run with content remaining). Otherwise the leading space
+        // is an inter-word separator (e.g., " spreadsheets" after "All").
+        const currentText = run.getText();
+        if (currentText.length > 0) {
+          const trimmed = currentText.trimStart();
+          if (trimmed !== currentText) {
+            run.setText(trimmed);
+          }
+          // Only break if we found actual content (not just whitespace that got trimmed away)
+          if (trimmed.length > 0) {
+            break;
+          }
+        }
+      } else if (strippedMidRunWithContent) {
+        // Prefix was stripped mid-run and content remains — stop processing
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Normalize all lists in a cell to consistent formatting.
+ * KEY BEHAVIORS:
+ * - ONE list type per cell - no mixing bullets and numbers
+ * - Format determines level: decimal=0, letter=1, roman=2
+ * - Word lists that don't match majority are converted
+ * - Non-list items are NEVER touched
+ * - User indentation settings are applied when provided
+ *
+ * FIX: Standalone typed decimal lists (1., 2., 3.) are no longer
+ * incorrectly assigned to level 2 based on paragraph indentation.
+ * Indentation-based nesting only applies when format also suggests nesting.
+ */
+export function normalizeListsInCell(
+  cell: TableCell,
+  options: ListNormalizationOptions,
+  numberingManager: NumberingManager
+): ListNormalizationReport {
+  const analysis = analyzeCellLists(cell, numberingManager);
+  const majorityCategory = analysis.majorityCategory;
+  const report: ListNormalizationReport = {
+    normalized: 0,
+    skipped: 0,
+    errors: [],
+    appliedCategory: majorityCategory,
+    details: [],
+  };
+
+  // Handle cells that don't need category normalization but may need indentation fixes
+  if (analysis.recommendedAction === "none") {
+    // Even if no normalization needed, still apply user indentation settings to Word lists.
+    // Modify existing abstract numbering definitions in-place rather than creating new
+    // numIds. This preserves original bullet characters, parent-child list semantics
+    // (shared numId across levels), and ilvl assignments.
+    if (options?.indentationLevels?.length && analysis.hasWordLists) {
+      const updatedAbstractNums = new Set<number>();
+
+      for (const item of analysis.paragraphs) {
+        if (item.detection.isWordList && item.detection.numId !== null) {
+          const para = item.paragraph as Paragraph;
+          const numbering = para.getNumbering();
+          if (numbering) {
+            const instance = numberingManager.getInstance(numbering.numId);
+            if (instance) {
+              const abstractNumId = instance.getAbstractNumId();
+              if (!updatedAbstractNums.has(abstractNumId)) {
+                const abstractNum = numberingManager.getAbstractNumbering(abstractNumId);
+                if (abstractNum) {
+                  const isBullet = item.detection.category === "bullet";
+                  applyIndentationSettings(abstractNum, options.indentationLevels!, isBullet, options.extraHangingIndentTwips ?? 0);
+                  updatedAbstractNums.add(abstractNumId);
+                }
+              }
+            }
+            // Do NOT change the paragraph's numId or ilvl — preserve original structure
+            report.normalized++;
+            report.details.push({
+              originalText: item.text.substring(0, 50),
+              action: "normalized",
+              reason: `Applied indentation settings in-place at level ${numbering.level}`,
+            });
+          }
+        }
+      }
+      normalizeOrphanListLevelsInCell(cell);
+      return report;
+    }
+    report.skipped = analysis.paragraphs.length;
+    // Always normalize orphan levels even when no other normalization needed
+    normalizeOrphanListLevelsInCell(cell);
+    return report;
+  }
+
+  // Calculate baseline (minimum) indentation for relative level inference
+  let baselineIndent = Infinity;
+  for (const item of analysis.paragraphs) {
+    if (item.detection.category !== "none") {
+      baselineIndent = Math.min(baselineIndent, item.detection.indentationTwips);
+    }
+  }
+  if (baselineIndent === Infinity) baselineIndent = 0;
+
+  // Calculate level shifts PER LIST GROUP based on ALL list items (majority + minority).
+  // Including minority items prevents shifting when low-level minority items exist
+  // (e.g., numbered items at ilvl=0 among bullet sub-items at ilvl=1+).
+  // A "list group" is a contiguous sequence of list items separated by non-list items.
+  const levelShiftByIndex = new Map<number, number>();
+  let currentGroupStart = -1;
+  let currentGroupMinLevel = Infinity;
+
+  for (let i = 0; i < analysis.paragraphs.length; i++) {
+    const item = analysis.paragraphs[i]!;
+
+    // Consider ALL list items for level shift calculation
+    if (item.detection.category !== "none") {
+      if (currentGroupStart === -1) {
+        currentGroupStart = i; // Start new group
+        currentGroupMinLevel = Infinity;
+      }
+      // Track minimum level in current group across all categories
+      currentGroupMinLevel = Math.min(currentGroupMinLevel, item.detection.inferredLevel);
+    } else {
+      // Non-list item - end current group if any
+      if (currentGroupStart !== -1) {
+        // Apply the group's level shift to ALL non-"none" items in the group
+        const shift = currentGroupMinLevel === Infinity ? 0 : currentGroupMinLevel;
+        for (let j = currentGroupStart; j < i; j++) {
+          if (analysis.paragraphs[j]!.detection.category !== "none") {
+            levelShiftByIndex.set(j, shift);
+          }
+        }
+        currentGroupStart = -1;
+        currentGroupMinLevel = Infinity;
+      }
+    }
+  }
+
+  // Handle last group if cell ends with list items
+  if (currentGroupStart !== -1) {
+    const shift = currentGroupMinLevel === Infinity ? 0 : currentGroupMinLevel;
+    for (let j = currentGroupStart; j < analysis.paragraphs.length; j++) {
+      if (analysis.paragraphs[j]!.detection.category !== "none") {
+        levelShiftByIndex.set(j, shift);
+      }
+    }
+  }
+
+  // === Context-aware sub-item detection ===
+  // Track which items should be treated as sub-items and their parent indices
+  const bulletAsSubItemIndices = new Set<number>();
+  const numberedAsSubItemIndices = new Set<number>();
+  const parentIndexByIndex = new Map<number, number>();
+
+  // Helper to calculate normalized level for an item (used for parent level lookup)
+  const getNormalizedLevel = (itemIndex: number): number => {
+    const item = analysis.paragraphs[itemIndex]!;
+    const detection = item.detection;
+    const hasTypedPrefix = !!detection.typedPrefix;
+    const levelShift = levelShiftByIndex.get(itemIndex) ?? 0;
+
+    if (hasTypedPrefix) {
+      const relativeIndent = detection.indentationTwips - baselineIndent;
+      const rawLevel = inferLevelFromRelativeIndentation(relativeIndent);
+      // Apply levelShift consistently for typed prefixes too
+      return Math.max(0, rawLevel - levelShift);
+    } else {
+      return Math.max(0, detection.inferredLevel - levelShift);
+    }
+  };
+
+  // Minimum indentation difference (in twips) to consider an item a sub-item
+  // 200 twips ~ 0.14 inches - small enough to catch real sub-items but avoid false positives
+  const INDENT_THRESHOLD = 200;
+
+  if (majorityCategory === "numbered") {
+    let lastNumberedItemIndex = -1;
+    let lastSubItemIndex = -1;
+
+    for (let i = 0; i < analysis.paragraphs.length; i++) {
+      const item = analysis.paragraphs[i]!;
+      const detection = item.detection;
+
+      if (detection.category === "numbered") {
+        lastNumberedItemIndex = i;
+        lastSubItemIndex = -1;
+      } else if (detection.category === "bullet" && lastNumberedItemIndex >= 0) {
+        // Only mark as sub-item if actually indented MORE than the parent
+        // This prevents level-0 bullets from being wrongly demoted to level-1
+        const parentDetection = analysis.paragraphs[lastNumberedItemIndex]!.detection;
+        if (detection.indentationTwips > parentDetection.indentationTwips + INDENT_THRESHOLD) {
+          bulletAsSubItemIndices.add(i);
+          parentIndexByIndex.set(i, lastNumberedItemIndex);
+          lastSubItemIndex = i;
+        } else if (
+          // 0-indentation fallback for table cells: when both parent and child have
+          // 0 indentation (common in table cells), use proximity to the last numbered
+          // or sub-item to infer sub-item status. Only apply when the bullet is at
+          // inferred level 0 (to avoid demoting items already at higher ilvl).
+          detection.indentationTwips === 0 &&
+          parentDetection.indentationTwips === 0 &&
+          detection.inferredLevel === 0 &&
+          (i - Math.max(lastNumberedItemIndex, lastSubItemIndex === -1 ? 0 : lastSubItemIndex)) <= 3
+        ) {
+          bulletAsSubItemIndices.add(i);
+          parentIndexByIndex.set(i, lastNumberedItemIndex);
+          lastSubItemIndex = i;
+        }
+      } else if (detection.category === "none") {
+        // Only reset on text-bearing "none" items — blank paragraphs (spacers)
+        // between list items should not break the parent-child chain
+        if (item.text.trim().length > 0) {
+          lastNumberedItemIndex = -1;
+          lastSubItemIndex = -1;
+        }
+      }
+    }
+  }
+
+  if (majorityCategory === "bullet") {
+    let lastBulletItemIndex = -1;
+
+    for (let i = 0; i < analysis.paragraphs.length; i++) {
+      const item = analysis.paragraphs[i]!;
+      const detection = item.detection;
+
+      if (detection.category === "bullet") {
+        lastBulletItemIndex = i;
+      } else if (detection.category === "numbered" && lastBulletItemIndex >= 0) {
+        // Only mark as sub-item if actually indented MORE than the parent
+        const parentDetection = analysis.paragraphs[lastBulletItemIndex]!.detection;
+        if (detection.indentationTwips > parentDetection.indentationTwips + INDENT_THRESHOLD) {
+          numberedAsSubItemIndices.add(i);
+          parentIndexByIndex.set(i, lastBulletItemIndex);
+        }
+      } else if (detection.category === "none") {
+        // Only reset on text-bearing "none" items — blank paragraphs (spacers)
+        // between list items should not break the parent-child chain
+        if (item.text.trim().length > 0) {
+          lastBulletItemIndex = -1;
+        }
+      }
+    }
+  }
+  // === End sub-item detection ===
+
+  // Track numId per level - will be reset when parent level appears
+  const numIdByLevel = new Map<number, number>();
+  let lastProcessedLevel = -1;
+
+  // Helper to get/create numId for a level (uses majority category)
+  const getNumId = (level: number): number => {
+    if (level < lastProcessedLevel) {
+      for (const existingLevel of numIdByLevel.keys()) {
+        if (existingLevel > level) {
+          numIdByLevel.delete(existingLevel);
+        }
+      }
+    }
+    lastProcessedLevel = level;
+
+    if (!numIdByLevel.has(level)) {
+      const numId =
+        majorityCategory === "numbered"
+          ? numberingManager.createNumberedList()
+          : numberingManager.createBulletList();
+      numIdByLevel.set(level, numId);
+
+      // Apply user's indentation settings if provided
+      if (options?.indentationLevels?.length) {
+        const instance = numberingManager.getInstance(numId);
+        if (instance) {
+          const abstractNum = numberingManager.getAbstractNumbering(instance.getAbstractNumId());
+          if (abstractNum) {
+            applyIndentationSettings(abstractNum, options.indentationLevels, majorityCategory !== "numbered", options.extraHangingIndentTwips ?? 0);
+          }
+        }
+      }
+    }
+    return numIdByLevel.get(level)!;
+  };
+
+  // Separate tracking for bullet numIds (used for trailing bullets in numbered-majority cells)
+  const bulletNumIdByLevel = new Map<number, number>();
+  let lastBulletProcessedLevel = -1;
+
+  const getBulletNumId = (level: number): number => {
+    if (level < lastBulletProcessedLevel) {
+      for (const existingLevel of bulletNumIdByLevel.keys()) {
+        if (existingLevel > level) {
+          bulletNumIdByLevel.delete(existingLevel);
+        }
+      }
+    }
+    lastBulletProcessedLevel = level;
+
+    if (!bulletNumIdByLevel.has(level)) {
+      const numId = numberingManager.createBulletList();
+      bulletNumIdByLevel.set(level, numId);
+
+      // Apply user's indentation settings if provided
+      if (options?.indentationLevels?.length) {
+        const instance = numberingManager.getInstance(numId);
+        if (instance) {
+          const abstractNum = numberingManager.getAbstractNumbering(instance.getAbstractNumId());
+          if (abstractNum) {
+            applyIndentationSettings(abstractNum, options.indentationLevels, true, options.extraHangingIndentTwips ?? 0);
+          }
+        }
+      }
+    }
+    return bulletNumIdByLevel.get(level)!;
+  };
+
+  // Track last typed format per level to detect numId boundary changes.
+  // null = last item was a Word list, string = typed prefix format (e.g., "decimal", "lowerLetter").
+  // When transitioning from Word list → typed prefix or changing typed format, the cached
+  // numId is cleared so the typed prefix starts a fresh numbered sequence.
+  const lastTypedFormatByLevel = new Map<number, string | null>();
+
+  // Process each paragraph
+  for (let index = 0; index < analysis.paragraphs.length; index++) {
+    const item = analysis.paragraphs[index]!;
+    const { paragraph, text, detection } = item;
+    const para = paragraph as Paragraph;
+
+    // Skip non-list items entirely - preserve "Note:", plain text, etc.
+    if (detection.category === "none") {
+      report.skipped++;
+      report.details.push({
+        originalText: text.substring(0, 50),
+        action: "skipped",
+        reason: "Not a list item - preserving original formatting",
+      });
+      continue;
+    }
+
+    try {
+      // Check if this item needs conversion (different category than majority)
+      const needsConversion = detection.category !== majorityCategory;
+      const hasTypedPrefix = !!detection.typedPrefix;
+      const isWordList = detection.isWordList;
+
+      // Get the level shift for this paragraph's list group
+      const levelShift = levelShiftByIndex.get(index) ?? 0;
+
+      // Calculate target level
+      // - For typed prefixes: use format-based level (decimal=0, letter=1, roman=2)
+      //   unless BOTH format AND indentation suggest nesting
+      // - For sub-items: use parent's normalized level + 1
+      // - For Word lists: use format-based level with level shift applied
+      let targetLevel: number;
+      if (hasTypedPrefix) {
+        const relativeIndent = detection.indentationTwips - baselineIndent;
+        const indentBasedLevel = inferLevelFromRelativeIndentation(relativeIndent);
+
+        if (indentBasedLevel === 0 && detection.inferredLevel > 0) {
+          // No extra indent but format suggests nesting (e.g., "a." at level 1)
+          targetLevel = Math.max(0, detection.inferredLevel - levelShift);
+        } else if (indentBasedLevel > 0 && detection.inferredLevel === 0) {
+          // FIX: Decimal/bullet typed prefix with extra indentation from cell baseline.
+          // Don't infer nesting from indentation alone when the format is top-level
+          // (e.g., "1.", "2.", "3." are decimal = level 0). The baseline may come from
+          // a non-list paragraph (header text), causing false nesting.
+          // The levelShift mechanism handles true multi-level lists correctly.
+          targetLevel = 0;
+        } else {
+          targetLevel = indentBasedLevel;
+        }
+      } else if (bulletAsSubItemIndices.has(index) || numberedAsSubItemIndices.has(index)) {
+        // Sub-item: use parent's NORMALIZED level + 1
+        const parentIndex = parentIndexByIndex.get(index);
+        const parentNormalizedLevel = parentIndex !== undefined ? getNormalizedLevel(parentIndex) : 0;
+        targetLevel = parentNormalizedLevel + 1;
+      } else {
+        targetLevel = Math.max(0, detection.inferredLevel - levelShift);
+      }
+
+      // Process based on what type of item this is
+      if (hasTypedPrefix && detection.typedPrefix) {
+        // Typed prefix: strip prefix and apply new formatting
+        stripTypedPrefix(para, detection.typedPrefix);
+
+        // Check if we need a fresh numId for this typed prefix.
+        // New numId when: previous at this level was a Word list item (null)
+        // or a different typed format (e.g., decimal → lowerLetter).
+        const lastFormat = lastTypedFormatByLevel.get(targetLevel);
+        if (lastFormat === null || (lastFormat !== undefined && lastFormat !== detection.format)) {
+          numIdByLevel.delete(targetLevel);
+        }
+        lastTypedFormatByLevel.set(targetLevel, detection.format ?? "unknown");
+
+        para.setNumbering(getNumId(targetLevel), targetLevel);
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Typed prefix → level ${targetLevel}`,
+        });
+      } else if (isWordList && bulletAsSubItemIndices.has(index)) {
+        // Sandwiched bullet following numbered → convert to numbered sub-item
+        lastTypedFormatByLevel.set(targetLevel, null);
+        para.setNumbering(getNumId(targetLevel), targetLevel);
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Bullet → numbered sub-item at level ${targetLevel}`,
+        });
+      } else if (isWordList && numberedAsSubItemIndices.has(index)) {
+        // Numbered following bullet → convert to bullet sub-item
+        lastTypedFormatByLevel.set(targetLevel, null);
+        para.setNumbering(getBulletNumId(targetLevel), targetLevel);
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Numbered → bullet at level ${targetLevel}`,
+        });
+      } else if (isWordList && detection.category === "bullet" && majorityCategory === "numbered" && !bulletAsSubItemIndices.has(index)) {
+        // Trailing bullet in numbered-majority cell - preserve as bullet
+        lastTypedFormatByLevel.set(targetLevel, null);
+        para.setNumbering(getBulletNumId(targetLevel), targetLevel);
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Trailing bullet preserved at level ${targetLevel}`,
+        });
+      } else if (isWordList && needsConversion) {
+        // Regular category conversion
+        lastTypedFormatByLevel.set(targetLevel, null);
+        if (majorityCategory === "bullet") {
+          para.setNumbering(getBulletNumId(targetLevel), targetLevel);
+        } else {
+          para.setNumbering(getNumId(targetLevel), targetLevel);
+        }
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Word ${detection.category} → ${majorityCategory} level ${targetLevel}`,
+        });
+      } else if (isWordList) {
+        // Preserve category but ensure consistent numId with user settings
+        lastTypedFormatByLevel.set(targetLevel, null);
+        if (detection.category === "bullet") {
+          para.setNumbering(getBulletNumId(targetLevel), targetLevel);
+        } else {
+          para.setNumbering(getNumId(targetLevel), targetLevel);
+        }
+        report.normalized++;
+        report.details.push({
+          originalText: text.substring(0, 50),
+          action: "normalized",
+          reason: `Updated numId for consistent numbering at level ${targetLevel}`,
+        });
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      report.errors.push(`Failed on "${text.substring(0, 30)}...": ${message}`);
+      report.details.push({
+        originalText: text.substring(0, 50),
+        action: "error",
+        reason: message,
+      });
+    }
+  }
+
+  // Ensure list items don't start at orphan levels (level 1+ without level 0 parent)
+  normalizeOrphanListLevelsInCell(cell);
+
+  return report;
+}
+
+/**
+ * Normalize lists across all cells in a table.
+ */
+export function normalizeListsInTable(
+  table: Table,
+  options: ListNormalizationOptions,
+  numberingManager: NumberingManager
+): ListNormalizationReport {
+  const aggregateReport: ListNormalizationReport = {
+    normalized: 0,
+    skipped: 0,
+    errors: [],
+    appliedCategory: "none",
+    details: [],
+  };
+
+  for (const row of table.getRows()) {
+    for (const cell of row.getCells()) {
+      const cellReport = normalizeListsInCell(cell, options, numberingManager);
+
+      aggregateReport.normalized += cellReport.normalized;
+      aggregateReport.skipped += cellReport.skipped;
+      aggregateReport.errors.push(...cellReport.errors);
+      aggregateReport.details.push(...cellReport.details);
+
+      if (cellReport.appliedCategory !== "none") {
+        aggregateReport.appliedCategory = cellReport.appliedCategory;
+      }
+    }
+  }
+
+  return aggregateReport;
+}
+
+/**
+ * Normalize orphan Level 1+ list items in a table cell.
+ *
+ * Detects when a cell's first list item starts at Level 1 or higher
+ * without a preceding Level 0 item. Shifts all list items down by the
+ * minimum level found, so they start at Level 0.
+ */
+export function normalizeOrphanListLevelsInCell(cell: TableCell): number {
+  const paragraphs = cell.getParagraphs();
+
+  // Find minimum level among all list items in the cell
+  let minLevel = Infinity;
+  let hasListItems = false;
+
+  for (const para of paragraphs) {
+    const numbering = para.getNumbering();
+    if (numbering) {
+      hasListItems = true;
+      minLevel = Math.min(minLevel, numbering.level);
+    }
+  }
+
+  // If no list items or already at Level 0, nothing to fix
+  if (!hasListItems || minLevel === 0 || minLevel === Infinity) {
+    return 0;
+  }
+
+  // Shift all list items down by minLevel
+  let normalizedCount = 0;
+  for (const para of paragraphs) {
+    const numbering = para.getNumbering();
+    if (numbering) {
+      const newLevel = numbering.level - minLevel;
+      para.setNumbering(numbering.numId, newLevel);
+      normalizedCount++;
+    }
+  }
+
+  return normalizedCount;
+}
+
+/**
+ * Normalize orphan Level 1+ list items across all cells in a table.
+ */
+export function normalizeOrphanListLevelsInTable(table: Table): number {
+  let totalNormalized = 0;
+
+  for (const row of table.getRows()) {
+    for (const cell of row.getCells()) {
+      totalNormalized += normalizeOrphanListLevelsInCell(cell);
+    }
+  }
+
+  return totalNormalized;
+}
+
+// =============================================================================
+// NUMBERING MANAGER HELPERS
+// =============================================================================
+
+/**
+ * Get existing or create new numbered list numId.
+ */
+function getOrCreateNumberedListNumId(
+  numberingManager: NumberingManager
+): number {
+  const instances = numberingManager.getAllInstances();
+  for (const instance of instances) {
+    const abstractNum = numberingManager.getAbstractNumbering(
+      instance.getAbstractNumId()
+    );
+    if (abstractNum) {
+      const level0 = abstractNum.getLevel(0);
+      if (level0) {
+        const format = level0.getFormat();
+        if (getListCategoryFromFormat(format) === "numbered") {
+          return instance.getNumId();
+        }
+      }
+    }
+  }
+
+  return numberingManager.createNumberedList();
+}
+
+/**
+ * Get existing or create new bullet list numId.
+ */
+function getOrCreateBulletListNumId(
+  numberingManager: NumberingManager
+): number {
+  const instances = numberingManager.getAllInstances();
+  for (const instance of instances) {
+    const abstractNum = numberingManager.getAbstractNumbering(
+      instance.getAbstractNumId()
+    );
+    if (abstractNum) {
+      const level0 = abstractNum.getLevel(0);
+      if (level0) {
+        const format = level0.getFormat();
+        if (format === "bullet") {
+          return instance.getNumId();
+        }
+      }
+    }
+  }
+
+  return numberingManager.createBulletList();
+}
+
+// =============================================================================
+// PUBLIC API CLASS
+// =============================================================================
+
+/**
+ * Main entry point for list normalization.
+ */
+export class ListNormalizer {
+  private numberingManager: NumberingManager;
+
+  constructor(numberingManager: NumberingManager) {
+    this.numberingManager = numberingManager;
+  }
+
+  analyzeCell(cell: TableCell): ListAnalysis {
+    return analyzeCellLists(cell);
+  }
+
+  analyzeTable(table: Table): Map<TableCell, ListAnalysis> {
+    return analyzeTableLists(table);
+  }
+
+  normalizeCell(
+    cell: TableCell,
+    options: Partial<ListNormalizationOptions> = {}
+  ): ListNormalizationReport {
+    const fullOptions = this.resolveOptions(options);
+    return normalizeListsInCell(cell, fullOptions, this.numberingManager);
+  }
+
+  normalizeTable(
+    table: Table,
+    options: Partial<ListNormalizationOptions> = {}
+  ): ListNormalizationReport {
+    const fullOptions = this.resolveOptions(options);
+    return normalizeListsInTable(table, fullOptions, this.numberingManager);
+  }
+
+  normalizeAllTables(
+    tables: Table[],
+    options: Partial<ListNormalizationOptions> = {}
+  ): ListNormalizationReport {
+    const aggregateReport: ListNormalizationReport = {
+      normalized: 0,
+      skipped: 0,
+      errors: [],
+      appliedCategory: "none",
+      details: [],
+    };
+
+    for (const table of tables) {
+      const tableReport = this.normalizeTable(table, options);
+      aggregateReport.normalized += tableReport.normalized;
+      aggregateReport.skipped += tableReport.skipped;
+      aggregateReport.errors.push(...tableReport.errors);
+      aggregateReport.details.push(...tableReport.details);
+
+      if (tableReport.appliedCategory !== "none") {
+        aggregateReport.appliedCategory = tableReport.appliedCategory;
+      }
+    }
+
+    if (aggregateReport.normalized > 0) {
+      logger.info(
+        `List normalization complete: ${aggregateReport.normalized} items normalized`
+      );
+    }
+
+    return aggregateReport;
+  }
+
+  private resolveOptions(
+    partial: Partial<ListNormalizationOptions>
+  ): ListNormalizationOptions {
+    return {
+      numberedStyleNumId:
+        partial.numberedStyleNumId ??
+        getOrCreateNumberedListNumId(this.numberingManager),
+      bulletStyleNumId:
+        partial.bulletStyleNumId ??
+        getOrCreateBulletListNumId(this.numberingManager),
+      scope: partial.scope ?? "cell",
+      forceMajority: partial.forceMajority ?? false,
+      preserveIndentation: partial.preserveIndentation ?? false,
+      indentationLevels: partial.indentationLevels,
+    };
+  }
+}