feat: support rendering of column line separators (#2088)

* feat: support column line separators

- Extracts 'w:sep' tag according to OOXML spec
- Renders one separator for each page column ('w:col' / 'w:num') in DOM painter

Closes #2067

* test: add docx file with line separator between columns enabled

* fix: rendering color of separators

* fix: reuse ColumnLayout and SINGLE_COLUMN_DEFAULT

* fix: ensure column width larger than separator width

* chore: lint

* chore: fix imports and missing SINGLE_COLUMN_DEFAULT usage

* chore: reuse type

* fix: render column separators per region on pages with continuous breaks

Two related fixes so the new column-line-separator feature works correctly
on pages where a continuous section break changes column layout mid-page.

1. isColumnConfigChanging now compares withSeparator. Before, a sep-only
   toggle (count+gap unchanged) returned false, so no mid-page region was
   created and the toggle was silently dropped. Applied in both
   section-breaks.ts and the inline fallback in index.ts.

2. constraintBoundaries captured during layout are serialized onto a new
   page.columnRegions contract field. renderColumnSeparators now iterates
   regions and draws each separator bounded by its yStart/yEnd instead of
   painting a single full-page overlay. When no mid-page change occurs,
   columnRegions is omitted and the renderer falls back to page.columns
   (unchanged behavior).

Verified by loading a fixture with 7 scenarios (2-col, 3-col, unequal
widths, separator on/off, continuous breaks toggling the separator).
Pages now show per-region separators tiled correctly; a 3-col region
followed by a 2-col region no longer paints a shared full-page line.

Out of scope here, tracked for follow-up: widths/equalWidth are still
dropped at pm-adapter extractColumns, so unequal-width separators render
at the equal-width midpoint; body-level w:sep is dropped at v2
docxImporter; there is no w:sep export.

* test: cover DomPainter renderColumnSeparators

13 unit tests over the separator renderer. Splits coverage into the
fallback path (page.columns only) and the region-aware path
(page.columnRegions).

Fallback path: pins the 2-col and 3-col geometry, and each early-return
guard (withSeparator false/undefined, single column, missing margins,
no columns at all, pathologically-small columnWidth).

Region path: verifies per-region yStart/yEnd bounding, mixed regions
(some draw, some skip for withSeparator=false or count<=1), zero-height
regions, and that columnRegions wins when both it and page.columns are
present.

Previously renderColumnSeparators had zero DOM-level coverage — the
region-aware refactor in the prior commit relied entirely on
layout-engine tests that never exercised the DOM output.

---------

Co-authored-by: Caio Pizzol <caio@harbourshare.com>

Author: JoaaoVerona

packages/layout-engine/contracts/src/column-layout.ts

@@ -19,6 +19,7 @@ export function cloneColumnLayout(columns?: ColumnLayout): ColumnLayout {
         gap: columns.gap,
         ...(Array.isArray(columns.widths) ? { widths: [...columns.widths] } : {}),
         ...(columns.equalWidth !== undefined ? { equalWidth: columns.equalWidth } : {}),
+        ...(columns.withSeparator !== undefined ? { withSeparator: columns.withSeparator } : {}),
       }
     : { count: 1, gap: 0 };
 }
@@ -62,6 +63,7 @@ export function normalizeColumnLayout(
       count: 1,
       gap: 0,
       width: Math.max(0, contentWidth),
+      ...(input?.withSeparator !== undefined ? { withSeparator: input.withSeparator } : {}),
     };
   }
 
@@ -70,6 +72,7 @@ export function normalizeColumnLayout(
     gap,
     ...(widths.length > 0 ? { widths } : {}),
     ...(input?.equalWidth !== undefined ? { equalWidth: input.equalWidth } : {}),
+    ...(input?.withSeparator !== undefined ? { withSeparator: input.withSeparator } : {}),
     width,
   };
 }

packages/layout-engine/contracts/src/index.ts

@@ -987,10 +987,7 @@ export type SectionBreakBlock = {
     even?: string;
     odd?: string;
   };
-  columns?: {
-    count: number;
-    gap: number;
-    widths?: number[];
+  columns?: ColumnLayout & {
     equalWidth?: boolean;
   };
   /**
@@ -1478,10 +1475,28 @@ export type FlowBlock =
 export type ColumnLayout = {
   count: number;
   gap: number;
+  withSeparator?: boolean;
   widths?: number[];
   equalWidth?: boolean;
 };
 
+/**
+ * A vertical region of a page that shares a single column configuration.
+ *
+ * Continuous section breaks can introduce multiple column configurations on the
+ * same page (see ECMA-376 §17.6.22 and §17.18.77). A page may therefore carry
+ * multiple regions stacked vertically. Consumers (e.g. DomPainter) use
+ * `yStart`/`yEnd` to bound any per-region overlays such as column separators.
+ */
+export type ColumnRegion = {
+  /** Inclusive top of the region, in pixels from the page top. */
+  yStart: number;
+  /** Exclusive bottom of the region, in pixels from the page top. */
+  yEnd: number;
+  /** Column configuration active within this region. */
+  columns: ColumnLayout;
+};
+
 /** A measured line within a block, output by the measurer. */
 export type Line = {
   fromRun: number;
@@ -1706,6 +1721,29 @@ export type Page = {
    * Sections are 0-indexed, matching the sectionIndex in SectionMetadata.
    */
   sectionIndex?: number;
+  /**
+   * Column layout configuration for this page.
+   *
+   * Reflects the column configuration at page start. For pages with continuous
+   * section breaks that change column layout mid-page, use `columnRegions` for
+   * accurate per-region information.
+   *
+   * Used by the renderer to draw column separator lines when `withSeparator`
+   * is set to true.
+   */
+  columns?: ColumnLayout;
+  /**
+   * Vertical column regions on this page, ordered top to bottom.
+   *
+   * Populated when continuous section breaks change column layout mid-page. Each
+   * region pairs a `{yStart, yEnd}` span with the column config active inside it
+   * (see ECMA-376 §17.6.22). Renderers should prefer this field over
+   * `columns` when drawing per-region overlays (e.g. column separators).
+   *
+   * If omitted, the page has a single column region and consumers can fall back
+   * to `columns`.
+   */
+  columnRegions?: ColumnRegion[];
 };
 
 /** A paragraph fragment positioned on a page. */

packages/layout-engine/layout-bridge/src/incrementalLayout.ts

@@ -19,6 +19,7 @@ import {
   resolvePageNumberTokens,
   type NumberingContext,
   SEMANTIC_PAGE_HEIGHT_PX,
+  SINGLE_COLUMN_DEFAULT,
 } from '@superdoc/layout-engine';
 import { remeasureParagraph } from './remeasure';
 import { computeDirtyRegions } from './diff';
@@ -183,7 +184,7 @@ const resolvePageColumns = (layout: Layout, options: LayoutOptions, blocks?: Flo
     );
     const contentWidth = pageSize.w - (marginLeft + marginRight);
     const sectionIndex = page.sectionIndex ?? 0;
-    const columnsConfig = sectionColumns.get(sectionIndex) ?? options.columns ?? { count: 1, gap: 0 };
+    const columnsConfig = sectionColumns.get(sectionIndex) ?? options.columns ?? SINGLE_COLUMN_DEFAULT;
     const normalized = normalizeColumnsForFootnotes(columnsConfig, contentWidth);
     result.set(pageIndex, { ...normalized, left: marginLeft, contentWidth });
   }
@@ -1503,7 +1504,7 @@ export async function incrementalLayout(
           );
           const pageContentWidth = pageSize.w - (marginLeft + marginRight);
           const fallbackColumns = normalizeColumnsForFootnotes(
-            options.columns ?? { count: 1, gap: 0 },
+            options.columns ?? SINGLE_COLUMN_DEFAULT,
             pageContentWidth,
           );
           const columns = pageColumns.get(pageIndex) ?? {

packages/layout-engine/layout-engine/src/index.test.ts

@@ -228,6 +228,100 @@ describe('layoutDocument', () => {
     expect(layout.columns).toMatchObject({ count: 2, gap: 20 });
   });
 
+  it('sets "page.columns" with separator when column separator is enabled', () => {
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 40, right: 40, bottom: 40, left: 40 },
+      columns: { count: 2, gap: 20, withSeparator: true },
+    };
+    const layout = layoutDocument([block], [makeMeasure([350, 350, 350])], options);
+
+    expect(layout.pages).toHaveLength(1);
+    expect(layout.pages[0].columns).toEqual({ count: 2, gap: 20, withSeparator: true });
+    expect(layout.columns).toMatchObject({ count: 2, gap: 20, withSeparator: true });
+  });
+
+  it('does not set "page.columns" on single column layout', () => {
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 40, right: 40, bottom: 40, left: 40 },
+    };
+    const layout = layoutDocument([block], [makeMeasure([350])], options);
+
+    expect(layout.pages).toHaveLength(1);
+    expect(layout.pages[0].columns).toBeUndefined();
+    expect(layout.columns).toBeUndefined();
+  });
+
+  it('sets "page.columns" without separator when column separator is not enabled', () => {
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 40, right: 40, bottom: 40, left: 40 },
+      columns: { count: 2, gap: 20, withSeparator: false },
+    };
+    const layout = layoutDocument([block], [makeMeasure([350, 350, 350])], options);
+
+    expect(layout.pages).toHaveLength(1);
+    expect(layout.pages[0].columns).toEqual({ count: 2, gap: 20, withSeparator: false });
+    expect(layout.columns).toEqual({ count: 2, gap: 20, withSeparator: false });
+  });
+
+  it('emits page.columnRegions for continuous section breaks that change column config mid-page', () => {
+    // Two sections on the same page: first 2-col with separator, then a
+    // continuous break that switches to 3-col still with separator. The
+    // layout engine should record a ConstraintBoundary and surface it on
+    // page.columnRegions so the renderer can bound each separator to the
+    // correct Y range.
+    const blocks: FlowBlock[] = [
+      { kind: 'paragraph', id: 'intro', runs: [] },
+      {
+        kind: 'sectionBreak',
+        id: 'sb-continuous',
+        type: 'continuous',
+        columns: { count: 3, gap: 20, withSeparator: true },
+      },
+      { kind: 'paragraph', id: 'body', runs: [] },
+    ];
+    const measures: Measure[] = [makeMeasure([30]), { kind: 'sectionBreak' }, makeMeasure([30, 30, 30])];
+
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 40, right: 40, bottom: 40, left: 40 },
+      columns: { count: 2, gap: 20, withSeparator: true },
+    };
+
+    const layout = layoutDocument(blocks, measures, options);
+
+    expect(layout.pages).toHaveLength(1);
+    const regions = layout.pages[0].columnRegions;
+    expect(regions).toBeDefined();
+    expect(regions!.length).toBeGreaterThanOrEqual(2);
+    // First region covers the initial 2-col layout from topMargin to the boundary.
+    expect(regions![0].yStart).toBe(40);
+    expect(regions![0].columns).toEqual({ count: 2, gap: 20, withSeparator: true });
+    // Second region picks up the continuous break's 3-col config and ends at
+    // the bottom of the content area.
+    const last = regions![regions!.length - 1];
+    expect(last.columns).toMatchObject({ count: 3, gap: 20, withSeparator: true });
+    expect(last.yEnd).toBe(800 - 40);
+    // Regions must tile (no gaps, no overlap).
+    for (let i = 1; i < regions!.length; i++) {
+      expect(regions![i].yStart).toBe(regions![i - 1].yEnd);
+    }
+  });
+
+  it('omits page.columnRegions when no mid-page column change occurs', () => {
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 40, right: 40, bottom: 40, left: 40 },
+      columns: { count: 2, gap: 20, withSeparator: true },
+    };
+    const layout = layoutDocument([block], [makeMeasure([350, 350, 350])], options);
+
+    expect(layout.pages).toHaveLength(1);
+    expect(layout.pages[0].columnRegions).toBeUndefined();
+  });
+
   it('applies spacing before and after paragraphs', () => {
     const spacingBlock: FlowBlock = {
       kind: 'paragraph',

packages/layout-engine/layout-engine/src/index.ts

@@ -1,5 +1,6 @@
 import type {
   ColumnLayout,
+  ColumnRegion,
   FlowBlock,
   Fragment,
   HeaderFooterLayout,
@@ -35,6 +36,7 @@ import {
   scheduleSectionBreak as scheduleSectionBreakExport,
   type SectionState,
   applyPendingToActive,
+  SINGLE_COLUMN_DEFAULT,
 } from './section-breaks.js';
 import { layoutParagraphBlock } from './layout-paragraph.js';
 import { layoutImageBlock } from './layout-image.js';
@@ -1001,14 +1003,18 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
     if (block.orientation) next.pendingOrientation = block.orientation;
     const sectionType = block.type ?? 'continuous';
     // Check if columns are changing: either explicitly to a different config,
-    // or implicitly resetting to single column (undefined = single column in OOXML)
+    // or implicitly resetting to single column (undefined = single column in OOXML).
+    // withSeparator must be compared because a sep-only toggle still needs a new
+    // column region so the renderer can draw (or stop drawing) the separator from
+    // the toggle point onward.
     const isColumnsChanging =
       (block.columns &&
         (block.columns.count !== next.activeColumns.count ||
           block.columns.gap !== next.activeColumns.gap ||
+          Boolean(block.columns.withSeparator) !== Boolean(next.activeColumns.withSeparator) ||
           block.columns.equalWidth !== next.activeColumns.equalWidth ||
           !widthsEqual(block.columns.widths, next.activeColumns.widths))) ||
-      (!block.columns && next.activeColumns.count > 1);
+      (!block.columns && (next.activeColumns.count > 1 || Boolean(next.activeColumns.withSeparator)));
     // Schedule section index change for next page (enables section-aware page numbering)
     const sectionIndexRaw = block.attrs?.sectionIndex;
     const metadataIndex = typeof sectionIndexRaw === 'number' ? sectionIndexRaw : Number(sectionIndexRaw ?? NaN);
@@ -1074,6 +1080,11 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
     if (activeOrientation) {
       page.orientation = activeOrientation;
     }
+
+    if (activeColumns.count > 1) {
+      page.columns = { count: activeColumns.count, gap: activeColumns.gap, withSeparator: activeColumns.withSeparator };
+    }
+
     // Set vertical alignment from active section state
     if (activeVAlign && activeVAlign !== 'top') {
       page.vAlign = activeVAlign;
@@ -2527,14 +2538,50 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
     }
   }
 
+  // Serialize constraint boundaries into page.columnRegions so DomPainter can
+  // draw per-region overlays (e.g. column separator lines) bounded by the
+  // correct Y span. Continuous section breaks with a changed column config
+  // push boundaries into PageState.constraintBoundaries during layout; without
+  // this step the renderer only sees the page-start column config and would
+  // draw a single full-page separator across regions it no longer applies to.
+  for (const state of states) {
+    const boundaries = state.constraintBoundaries;
+    if (boundaries.length === 0) continue;
+
+    const regions: ColumnRegion[] = [];
+    // First region spans from the top of the content area to the first boundary.
+    // Its columns come from page.columns (set at page creation before any
+    // mid-page region change) or fall back to a single-column default so the
+    // contract stays self-describing even when the page starts single-column.
+    const firstRegionColumns: ColumnLayout = state.page.columns ?? { count: 1, gap: 0 };
+    regions.push({
+      yStart: state.topMargin,
+      yEnd: boundaries[0].y,
+      columns: firstRegionColumns,
+    });
+    for (let i = 0; i < boundaries.length; i++) {
+      const start = boundaries[i];
+      const end = boundaries[i + 1];
+      regions.push({
+        yStart: start.y,
+        yEnd: end ? end.y : state.contentBottom,
+        columns: start.columns,
+      });
+    }
+    state.page.columnRegions = regions;
+  }
+
   return {
     pageSize,
     pages,
     // Note: columns here reflects the effective default for subsequent pages
     // after processing sections. Page/region-specific column changes are encoded
     // implicitly via fragment positions. Consumers should not assume this is
     // a static document-wide value.
-    columns: activeColumns.count > 1 ? { count: activeColumns.count, gap: activeColumns.gap } : undefined,
+    columns:
+      activeColumns.count > 1
+        ? { count: activeColumns.count, gap: activeColumns.gap, withSeparator: activeColumns.withSeparator }
+        : undefined,
   };
 }
 
@@ -2961,3 +3008,5 @@ export type { NumberingContext, ResolvePageTokensResult } from './resolvePageTok
 // Table utilities consumed by layout-bridge and cross-package sync tests
 export { getCellLines, getEmbeddedRowLines } from './layout-table.js';
 export { describeCellRenderBlocks, computeCellSliceContentHeight } from './table-cell-slice.js';
+
+export { SINGLE_COLUMN_DEFAULT } from './section-breaks.js';

packages/layout-engine/layout-engine/src/section-breaks.d.ts

@@ -1,4 +1,5 @@
-import type { SectionBreakBlock } from '@superdoc/contracts';
+import type { ColumnLayout, SectionBreakBlock } from '@superdoc/contracts';
+
 export type SectionState = {
   activeTopMargin: number;
   activeBottomMargin: number;
@@ -20,14 +21,8 @@ export type SectionState = {
     w: number;
     h: number;
   } | null;
-  activeColumns: {
-    count: number;
-    gap: number;
-  };
-  pendingColumns: {
-    count: number;
-    gap: number;
-  } | null;
+  activeColumns: ColumnLayout;
+  pendingColumns: ColumnLayout | null;
   activeOrientation: 'portrait' | 'landscape' | null;
   pendingOrientation: 'portrait' | 'landscape' | null;
   hasAnyPages: boolean;
@@ -37,6 +32,7 @@ export type BreakDecision = {
   forceMidPageRegion: boolean;
   requiredParity?: 'even' | 'odd';
 };
+
 /**
  * Schedule section break effects by updating pending/active state and returning a break decision.
  * This function is pure with respect to inputs/outputs and does not mutate external variables.
@@ -56,6 +52,7 @@ export declare function scheduleSectionBreak(
   decision: BreakDecision;
   state: SectionState;
 };
+
 /**
  * Apply pending margins/pageSize/columns/orientation to active values at a page boundary and clear pending.
  */