fix(pm-adapter): emit pending section break before TOC/docPartObj SDTs (SD-2557) (#2872)

* fix(pm-adapter): emit pending section break before TOC/docPartObj SDTs (SD-2557)

When a Word document stores a `w:sectPr` on a paragraph immediately before a
TOC (or other `docPartObj`) SDT, the section break was dropped. The TOC
ended up rendering on the same page as the prior section's content instead
of starting a new page as Word does.

Root cause in pm-adapter:

  - `findParagraphsWithSectPr` (sections/analysis.ts) recurses into `index`,
    `bibliography`, and `tableOfAuthorities` to count their children as
    paragraphs, but NOT into `documentPartObject` / `tableOfContents`.
  - As a result, section ranges treat a TOC SDT as a single opaque unit —
    its children don't occupy paragraph indices.
  - When processing flow, `handleParagraphNode` / `handleIndexNode` /
    `handleBibliographyNode` / `handleTableOfAuthoritiesNode` each emit a
    pending section break before the paragraph whose index matches
    `nextSection.startParagraphIndex`.
  - `handleDocumentPartObjectNode` and `handleTableOfContentsNode` did NOT
    run this check, so the deferred break only fired on the next body
    paragraph AFTER the SDT. The SDT's content rendered in the PREVIOUS
    section, with no page break before it.

Fix:

  - Add `emitPendingSectionBreakForParagraph(sectionState, nextBlockId,
    blocks, recordBlockKind)` helper in sections/breaks.ts that centralizes
    the "check, emit, advance" pattern.
  - Call the helper at the top of `handleDocumentPartObjectNode` and
    `handleTableOfContentsNode` — once per SDT. Since the SDT's children
    don't affect `currentParagraphIndex` (`findParagraphsWithSectPr` skips
    them), the check fires correctly at the SDT boundary: if the SDT sits
    at a section boundary, the nextPage break is emitted so the SDT renders
    on a new page.
  - No changes to section-range computation — counting stays consistent.

Verified against both fixtures from the issue (Highstreet Proposal Sample,
Heffernan Proposal Sample): cover stays on its own page, TOC starts on a
new page, matching Word.

Tests:

  - 3 new unit tests in document-part-object.test.ts covering:
    - Section break emitted at SDT boundary
    - No emission when SDT is not at a section boundary
    - No-op when sectionState is undefined
  - 1740 pm-adapter tests pass (up from 1737), 604 layout-engine tests pass.

* fix(pm-adapter): recurse into docPartObj for section ranges + per-child emission (SD-2557)

The initial fix only handled the sectPr BEFORE a TOC docPartObj (on the
empty paragraph that precedes the SDT). It missed the SECOND sectPr that
Word commonly stores on the trailing empty paragraph INSIDE the TOC SDT —
which signals "TOC section ends here, next section starts on new page".

Because `findParagraphsWithSectPr` did not recurse into `documentPartObject`
or `tableOfContents`, that inner sectPr was never discovered, so no
section-range boundary was built between the TOC and the following body
content. SuperDoc rendered the TOC and the first body section stacked on
the same page (just one page later than before the first fix).

Complete fix:

1. `findParagraphsWithSectPr` (sections/analysis.ts) now recurses into
   `documentPartObject` and `tableOfContents` in addition to `index` /
   `bibliography` / `tableOfAuthorities`. This lets section-range analysis
   see sectPrs stored anywhere inside a TOC SDT.

2. `handleDocumentPartObjectNode` (non-TOC branch) emits the pending
   section break before each child paragraph and advances
   `currentParagraphIndex` — matching the pattern in `handleIndexNode`,
   `handleBibliographyNode`, and `handleTableOfAuthoritiesNode`.

3. `processTocChildren` (toc.ts) accepts `sectionState` via its context
   arg and performs the same per-child emit + increment dance as the
   paragraph handlers. This handles the TOC branch of
   `handleDocumentPartObjectNode` and the nested `tableOfContents`
   recursion path.

With all three changes, the Highstreet fixture now renders exactly like
Word:

  - Page 1: cover
  - Page 2: TOC alone
  - Page 3: ABOUT US body
  - Page 4: ON BEHALF OF HIGHSTREET
  - Page 5: WORKERS COMPENSATION

Tests:
  - 4 new tests in document-part-object.test.ts (non-TOC emission,
    non-boundary no-op, undefined state, sectionState passthrough to
    processTocChildren)
  - 1741/1741 pm-adapter, 604/604 layout-engine, 11377/11377 super-editor

* refactor(pm-adapter): unify TOC handling via processTocChildren (SD-2557)

Collapse handleTableOfContentsNode into a delegation to processTocChildren
so direct `tableOfContents` nodes share the same code path as the
`documentPartObject` TOC gallery. Keeps the section-range counting contract
from findParagraphsWithSectPr consistent across both paths: every TOC child
paragraph advances sectionState.currentParagraphIndex, so deferred section
breaks fire at the correct boundary.

- Gate applyTocMetadata sdt fabrication on gallery — a direct
  tableOfContents PM node has no enclosing w:sdt, so we no longer invent
  a docPartObject SDT metadata entry on its entries.
- Forward themeColors through processTocChildren to the paragraph
  converter; also pass it in from handleDocumentPartObjectNode.
- Add regression tests for per-child index advancement, sdt gating, and
  themeColors pass-through.

Addresses PR #2872 review feedback.

---------

Co-authored-by: Nick Bernal <117235294+harbournick@users.noreply.github.com>

Author: tupizz

packages/layout-engine/pm-adapter/src/sdt/document-part-object.test.ts

@@ -473,5 +473,124 @@ describe('document-part-object', () => {
         expect(callArgs[1].tocInstruction).toBeUndefined();
       });
     });
+
+    // ==================== Pending section-break emission (SD-2557) ====================
+    describe('pending section break at SDT boundary', () => {
+      const sectionFixture = (startParagraphIndex: number) => ({
+        ranges: [
+          {
+            sectionIndex: 0,
+            startParagraphIndex: 0,
+            endParagraphIndex: 0,
+            sectPr: null,
+            margins: null,
+            headerRefs: {},
+            footerRefs: {},
+            type: 'nextPage',
+          },
+          {
+            sectionIndex: 1,
+            startParagraphIndex,
+            endParagraphIndex: 10,
+            sectPr: null,
+            margins: null,
+            headerRefs: {},
+            footerRefs: {},
+            type: 'nextPage',
+          },
+        ],
+        currentSectionIndex: 0,
+        currentParagraphIndex: startParagraphIndex,
+      });
+
+      // For the TOC branch, per-child emission now lives inside `processTocChildren`
+      // (which is mocked in these tests). The non-TOC branch below exercises the
+      // inline per-child emission path directly.
+      it('emits a section break before a docPartObj non-TOC child at a section boundary', () => {
+        // Repro for SD-2557 at the non-TOC path: same root cause — the handler
+        // processes child paragraphs but previously skipped the section-break check.
+        const node: PMNode = {
+          type: 'documentPartObject',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Page Number' }] }],
+        };
+        vi.mocked(metadataModule.getDocPartGallery).mockReturnValue('Building Block Gallery');
+        vi.mocked(metadataModule.getDocPartObjectId).mockReturnValue('bb-1');
+        vi.mocked(metadataModule.getNodeInstruction).mockReturnValue(undefined);
+        vi.mocked(metadataModule.resolveNodeSdtMetadata).mockReturnValue({ type: 'docPartObject' });
+
+        // currentParagraphIndex === nextSection.startParagraphIndex → the first
+        // child paragraph is the start of section 1.
+        mockContext.sectionState = sectionFixture(3) as unknown as NodeHandlerContext['sectionState'];
+
+        handleDocumentPartObjectNode(node, mockContext);
+
+        const sectionBreak = mockContext.blocks.find((b) => b.kind === 'sectionBreak');
+        expect(sectionBreak).toBeDefined();
+        expect(mockContext.sectionState!.currentSectionIndex).toBe(1);
+        // Counter must advance past the child paragraph so subsequent body
+        // content sees the correct paragraph index.
+        expect(mockContext.sectionState!.currentParagraphIndex).toBe(4);
+      });
+
+      it('does not emit a section break when the child is not at a section boundary', () => {
+        const node: PMNode = {
+          type: 'documentPartObject',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Page Number' }] }],
+        };
+        vi.mocked(metadataModule.getDocPartGallery).mockReturnValue('Building Block Gallery');
+        vi.mocked(metadataModule.getDocPartObjectId).mockReturnValue('bb-1');
+        vi.mocked(metadataModule.getNodeInstruction).mockReturnValue(undefined);
+        vi.mocked(metadataModule.resolveNodeSdtMetadata).mockReturnValue({ type: 'docPartObject' });
+
+        // currentParagraphIndex (2) < startParagraphIndex (5): not at boundary.
+        const state = sectionFixture(5);
+        state.currentParagraphIndex = 2;
+        mockContext.sectionState = state as unknown as NodeHandlerContext['sectionState'];
+
+        handleDocumentPartObjectNode(node, mockContext);
+
+        expect(mockContext.blocks.find((b) => b.kind === 'sectionBreak')).toBeUndefined();
+        expect(mockContext.sectionState!.currentSectionIndex).toBe(0);
+        // Counter still advances past the processed child.
+        expect(mockContext.sectionState!.currentParagraphIndex).toBe(3);
+      });
+
+      it('is a no-op when sectionState is undefined', () => {
+        const node: PMNode = {
+          type: 'documentPartObject',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Page Number' }] }],
+        };
+        vi.mocked(metadataModule.getDocPartGallery).mockReturnValue('Building Block Gallery');
+        vi.mocked(metadataModule.getDocPartObjectId).mockReturnValue('bb-1');
+        vi.mocked(metadataModule.getNodeInstruction).mockReturnValue(undefined);
+        vi.mocked(metadataModule.resolveNodeSdtMetadata).mockReturnValue({ type: 'docPartObject' });
+
+        mockContext.sectionState = undefined;
+
+        expect(() => handleDocumentPartObjectNode(node, mockContext)).not.toThrow();
+        expect(mockContext.blocks.find((b) => b.kind === 'sectionBreak')).toBeUndefined();
+      });
+
+      it('passes sectionState through to processTocChildren for TOC gallery', () => {
+        const node: PMNode = {
+          type: 'documentPartObject',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'TOC Entry' }] }],
+        };
+        vi.mocked(metadataModule.getDocPartGallery).mockReturnValue('Table of Contents');
+        vi.mocked(metadataModule.getDocPartObjectId).mockReturnValue('toc-1');
+        vi.mocked(metadataModule.getNodeInstruction).mockReturnValue(undefined);
+        vi.mocked(metadataModule.resolveNodeSdtMetadata).mockReturnValue({ type: 'docPartObject' });
+
+        const state = sectionFixture(3);
+        mockContext.sectionState = state as unknown as NodeHandlerContext['sectionState'];
+
+        handleDocumentPartObjectNode(node, mockContext);
+
+        // processTocChildren is mocked; just verify it received sectionState
+        // so the helper-inside-processTocChildren pattern can work end-to-end.
+        const callArgs = vi.mocked(tocModule.processTocChildren).mock.calls[0];
+        expect(callArgs[2]).toMatchObject({ sectionState: state });
+      });
+    });
   });
 });

packages/layout-engine/pm-adapter/src/sdt/document-part-object.ts

@@ -6,6 +6,7 @@
  */
 
 import type { PMNode, NodeHandlerContext } from '../types.js';
+import { emitPendingSectionBreakForParagraph } from '../sections/index.js';
 import { getDocPartGallery, getDocPartObjectId, getNodeInstruction, resolveNodeSdtMetadata } from './metadata.js';
 import { processTocChildren } from './toc.js';
 
@@ -14,6 +15,14 @@ import { processTocChildren } from './toc.js';
  * Processes TOC children for Table of Contents galleries.
  * For other gallery types (page numbers, etc.), processes child paragraphs normally.
  *
+ * If a preceding paragraph carried a `w:sectPr` whose next section starts at
+ * this SDT, emit the pending section break BEFORE processing children so the
+ * SDT's paragraphs render on the new page (see SD-2557). `findParagraphsWithSectPr`
+ * doesn't recurse into `documentPartObject`, so its child paragraphs don't bump
+ * `currentParagraphIndex` — and without this call, the deferred break would only
+ * fire on the next body paragraph AFTER the SDT, leaving e.g. a TOC on the
+ * prior page with the cover content.
+ *
  * @param node - Document part object node to process
  * @param context - Shared handler context
  */
@@ -27,12 +36,14 @@ export function handleDocumentPartObjectNode(node: PMNode, context: NodeHandlerC
     positions,
     bookmarks,
     hyperlinkConfig,
+    sectionState,
     converters,
     converterContext,
     enableComments,
     trackedChangesConfig,
     themeColors,
   } = context;
+
   const docPartGallery = getDocPartGallery(node);
   const docPartObjectId = getDocPartObjectId(node);
   const tocInstruction = getNodeInstruction(node);
@@ -50,15 +61,21 @@ export function handleDocumentPartObjectNode(node: PMNode, context: NodeHandlerC
         hyperlinkConfig,
         enableComments,
         trackedChangesConfig,
+        themeColors,
         converters,
         converterContext,
+        sectionState,
       },
       { blocks, recordBlockKind },
     );
   } else if (paragraphToFlowBlocks) {
-    // For non-ToC gallery types (page numbers, etc.), process child paragraphs normally
+    // For non-ToC gallery types (page numbers, etc.), process child paragraphs normally.
+    // `findParagraphsWithSectPr` recurses into documentPartObject (SD-2557), so child
+    // paragraph indices ARE counted — we must mirror that by emitting pending section
+    // breaks and advancing currentParagraphIndex per child.
     for (const child of node.content) {
       if (child.type === 'paragraph') {
+        emitPendingSectionBreakForParagraph({ sectionState, nextBlockId, blocks, recordBlockKind });
         const childBlocks = paragraphToFlowBlocks({
           para: child,
           nextBlockId,
@@ -75,6 +92,7 @@ export function handleDocumentPartObjectNode(node: PMNode, context: NodeHandlerC
           blocks.push(block);
           recordBlockKind?.(block.kind);
         }
+        if (sectionState) sectionState.currentParagraphIndex++;
       }
     }
   }