feat: support wide tables rendering outside of margins

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

@@ -1790,6 +1790,8 @@ export type PartialRowInfo = {
 export type TableFragment = {
   kind: 'table';
   blockId: BlockId;
+  /** Flow column that owns this fragment, distinct from visual x when overflow crosses margins. */
+  columnIndex?: number;
   fromRow: number;
   toRow: number;
   x: number;

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

@@ -9,7 +9,7 @@ import type {
   SectionBreakBlock,
   NormalizedColumnLayout,
 } from '@superdoc/contracts';
-import { cloneColumnLayout, normalizeColumnLayout } from '@superdoc/contracts';
+import { cloneColumnLayout, normalizeColumnLayout, rescaleColumnWidths } from '@superdoc/contracts';
 import {
   layoutDocument,
   layoutHeaderFooter,
@@ -19,6 +19,7 @@ import {
   resolvePageNumberTokens,
   type NumberingContext,
   SEMANTIC_PAGE_HEIGHT_PX,
+  resolveTableFrame,
 } from '@superdoc/layout-engine';
 import { remeasureParagraph } from './remeasure';
 import { computeDirtyRegions } from './diff';
@@ -223,7 +224,9 @@ const assignFootnotesToColumns = (
 
     if (columns && columns.count > 1 && page) {
       const fragment = findFragmentForPos(page, ref.pos);
-      if (fragment && typeof fragment.x === 'number') {
+      if (fragment?.kind === 'table' && typeof fragment.columnIndex === 'number') {
+        columnIndex = Math.max(0, Math.min(columns.count - 1, fragment.columnIndex));
+      } else if (fragment && typeof fragment.x === 'number') {
         const widths = Array.isArray(columns.widths) && columns.widths.length > 0 ? columns.widths : undefined;
         if (widths) {
           let cursorX = columns.left;
@@ -1633,46 +1636,26 @@ export async function incrementalLayout(
                   const block = blockById.get(range.blockId);
                   if (!measure || measure.kind !== 'table') return;
                   if (!block || block.kind !== 'table') return;
-                  const tableWidthRaw = Math.max(0, measure.totalWidth ?? 0);
-                  let tableWidth = Math.min(contentWidth, tableWidthRaw);
-                  let tableX = columnX;
-                  const justification =
-                    typeof block.attrs?.justification === 'string' ? block.attrs.justification : undefined;
-                  if (justification === 'center') {
-                    tableX = columnX + Math.max(0, (contentWidth - tableWidth) / 2);
-                  } else if (justification === 'right' || justification === 'end') {
-                    tableX = columnX + Math.max(0, contentWidth - tableWidth);
-                  } else {
-                    const indentValue = (block.attrs?.tableIndent as { width?: unknown } | undefined)?.width;
-                    const indent = typeof indentValue === 'number' && Number.isFinite(indentValue) ? indentValue : 0;
-                    tableX += indent;
-                    tableWidth = Math.max(0, tableWidth - indent);
-                  }
+                  const tableWidthRaw = Math.max(0, measure.totalWidth ?? contentWidth);
+                  const { x: tableX, width: tableWidth } = resolveTableFrame(
+                    columnX,
+                    contentWidth,
+                    tableWidthRaw,
+                    block.attrs,
+                  );
                   // Rescale column widths when table was clamped to section width.
                   // This happens in mixed-orientation docs where measurement uses the
                   // widest section but rendering is per-section (SD-1859).
-                  let fragmentColumnWidths: number[] | undefined;
-                  if (
-                    tableWidthRaw > tableWidth &&
-                    measure.columnWidths &&
-                    measure.columnWidths.length > 0 &&
-                    tableWidthRaw > 0
-                  ) {
-                    const scale = tableWidth / tableWidthRaw;
-                    fragmentColumnWidths = measure.columnWidths.map((w: number) => Math.max(1, Math.round(w * scale)));
-                    const scaledSum = fragmentColumnWidths.reduce((a: number, b: number) => a + b, 0);
-                    const target = Math.round(tableWidth);
-                    if (scaledSum !== target && fragmentColumnWidths.length > 0) {
-                      fragmentColumnWidths[fragmentColumnWidths.length - 1] = Math.max(
-                        1,
-                        fragmentColumnWidths[fragmentColumnWidths.length - 1] + (target - scaledSum),
-                      );
-                    }
-                  }
+                  const fragmentColumnWidths = rescaleColumnWidths(
+                    measure.columnWidths,
+                    measure.totalWidth,
+                    tableWidth,
+                  );
 
                   page.fragments.push({
                     kind: 'table',
                     blockId: range.blockId,
+                    columnIndex,
                     fromRow: 0,
                     toRow: block.rows.length,
                     x: tableX,

packages/layout-engine/layout-bridge/src/position-hit.ts

@@ -143,6 +143,14 @@ export const determineColumn = (layout: Layout, fragmentX: number): number => {
   return Math.max(0, Math.min(columns.count - 1, raw));
 };
 
+const determineTableColumn = (layout: Layout, fragment: TableFragment): number => {
+  if (typeof fragment.columnIndex === 'number') {
+    const count = layout.columns?.count ?? 1;
+    return Math.max(0, Math.min(Math.max(0, count - 1), fragment.columnIndex));
+  }
+  return determineColumn(layout, fragment.x);
+};
+
 // ---------------------------------------------------------------------------
 // Line / position helpers
 // ---------------------------------------------------------------------------
@@ -901,7 +909,7 @@ export function clickToPositionGeometry(
           layoutEpoch,
           blockId: tableHit.fragment.blockId,
           pageIndex,
-          column: determineColumn(layout, tableHit.fragment.x),
+          column: determineTableColumn(layout, tableHit.fragment),
           lineIndex,
         };
       }
@@ -915,7 +923,7 @@ export function clickToPositionGeometry(
         layoutEpoch,
         blockId: tableHit.fragment.blockId,
         pageIndex,
-        column: determineColumn(layout, tableHit.fragment.x),
+        column: determineTableColumn(layout, tableHit.fragment),
         lineIndex: 0,
       };
     }

packages/layout-engine/layout-bridge/test/clickToPosition.test.ts

@@ -1,6 +1,15 @@
 import { describe, it, expect } from 'vitest';
 import { clickToPosition, hitTestPage, hitTestTableFragment } from '../src/index.ts';
-import type { Layout, FlowBlock, Measure, Line, ParaFragment } from '@superdoc/contracts';
+import type {
+  Layout,
+  FlowBlock,
+  Measure,
+  Line,
+  ParaFragment,
+  TableBlock,
+  TableMeasure,
+  TableFragment,
+} from '@superdoc/contracts';
 import {
   simpleLayout,
   blocks,
@@ -42,6 +51,90 @@ describe('clickToPosition', () => {
     expect(result?.blockId).toBe('drawing-0');
     expect(result?.pos).toBe(20);
   });
+
+  it('uses table fragment columnIndex instead of visual x for multi-column overflow tables', () => {
+    const cellParagraph: FlowBlock = {
+      kind: 'paragraph',
+      id: 'table-cell-para',
+      runs: [{ text: 'Wide table', fontFamily: 'Arial', fontSize: 16, pmStart: 100, pmEnd: 110 }],
+    };
+
+    const tableBlock: TableBlock = {
+      kind: 'table',
+      id: 'wide-table',
+      rows: [
+        {
+          id: 'row-0',
+          cells: [{ id: 'cell-0-0', blocks: [cellParagraph] }],
+        },
+      ],
+    };
+
+    const cellParagraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [
+        {
+          fromRun: 0,
+          fromChar: 0,
+          toRun: 0,
+          toChar: 10,
+          width: 120,
+          ascent: 12,
+          descent: 4,
+          lineHeight: 20,
+        },
+      ],
+      totalHeight: 20,
+    };
+
+    const tableMeasure: TableMeasure = {
+      kind: 'table',
+      rows: [
+        {
+          cells: [
+            {
+              blocks: [cellParagraphMeasure],
+              paragraph: cellParagraphMeasure,
+              width: 320,
+              height: 28,
+              gridColumnStart: 0,
+              colSpan: 1,
+              rowSpan: 1,
+            },
+          ],
+          height: 28,
+        },
+      ],
+      columnWidths: [320],
+      totalWidth: 320,
+      totalHeight: 28,
+    };
+
+    const tableFragment: TableFragment = {
+      kind: 'table',
+      blockId: 'wide-table',
+      columnIndex: 1,
+      fromRow: 0,
+      toRow: 1,
+      x: 220,
+      y: 40,
+      width: 320,
+      height: 28,
+      pmStart: 100,
+      pmEnd: 110,
+    };
+
+    const layout: Layout = {
+      pageSize: { w: 600, h: 800 },
+      columns: { count: 2, gap: 20 },
+      pages: [{ number: 1, fragments: [tableFragment] }],
+    };
+
+    const result = clickToPosition(layout, [tableBlock], [tableMeasure], { x: 340, y: 54 });
+
+    expect(result?.blockId).toBe('wide-table');
+    expect(result?.column).toBe(1);
+  });
 });
 
 describe('hitTestPage with pageGap', () => {

packages/layout-engine/layout-bridge/test/footnoteColumnPlacement.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import type { FlowBlock, Measure } from '@superdoc/contracts';
+import type { FlowBlock, Measure, TableBlock, TableMeasure } from '@superdoc/contracts';
 import { incrementalLayout } from '../src/incrementalLayout';
 
 const makeParagraph = (id: string, text: string, pmStart: number): FlowBlock => ({
@@ -80,4 +80,92 @@ describe('Footnotes in columns', () => {
     expect(footnoteOneFragment?.x).toBeCloseTo(columnOneX, 2);
     expect(footnoteTwoFragment?.x).toBeCloseTo(columnTwoX, 2);
   });
+
+  it('keeps footnotes in the owning column for wide overflow tables', async () => {
+    const paragraphOne = makeParagraph('para-1', 'Column 1 text', 0);
+    const columnBreak: FlowBlock = { kind: 'columnBreak', id: 'col-break-1' };
+
+    const tableCellParagraph = makeParagraph('table-cell-para', 'Wide table ref', 80);
+    const wideTable: TableBlock = {
+      kind: 'table',
+      id: 'wide-table',
+      attrs: { justification: 'right' },
+      rows: [
+        {
+          id: 'row-0',
+          cells: [{ id: 'cell-0-0', blocks: [tableCellParagraph] }],
+        },
+      ],
+    };
+
+    const footnote = makeParagraph('footnote-wide-0-paragraph', 'Wide table footnote', 0);
+
+    const tableCellMeasure = makeMeasure(18, 'Wide table ref'.length);
+    const wideTableMeasure: TableMeasure = {
+      kind: 'table',
+      rows: [
+        {
+          cells: [
+            {
+              blocks: [tableCellMeasure],
+              paragraph: tableCellMeasure,
+              width: 320,
+              height: 28,
+              gridColumnStart: 0,
+              colSpan: 1,
+              rowSpan: 1,
+            },
+          ],
+          height: 28,
+        },
+      ],
+      columnWidths: [320],
+      totalWidth: 320,
+      totalHeight: 28,
+    };
+
+    const measureBlock = vi.fn(async (block: FlowBlock) => {
+      if (block.kind === 'columnBreak') {
+        return { kind: 'columnBreak' } as Measure;
+      }
+      if (block.kind === 'table') {
+        return wideTableMeasure;
+      }
+      const textLength = block.kind === 'paragraph' ? (block.runs?.[0]?.text?.length ?? 1) : 1;
+      const lineHeight = block.id.startsWith('footnote-') ? 10 : 18;
+      return makeMeasure(lineHeight, textLength);
+    });
+
+    const columns = { count: 2, gap: 20 };
+    const margins = { top: 60, right: 60, bottom: 60, left: 60 };
+    const pageSize = { w: 600, h: 800 };
+
+    const result = await incrementalLayout(
+      [],
+      null,
+      [paragraphOne, columnBreak, wideTable],
+      {
+        pageSize,
+        margins,
+        columns,
+        footnotes: {
+          refs: [{ id: 'wide', pos: 82 }],
+          blocksById: new Map([['wide', [footnote]]]),
+        },
+      },
+      measureBlock,
+    );
+
+    const page = result.layout.pages[0];
+    const columnWidth = (pageSize.w - margins.left - margins.right - columns.gap) / columns.count;
+    const columnTwoX = margins.left + columnWidth + columns.gap;
+
+    const tableFragment = page.fragments.find((fragment) => fragment.blockId === wideTable.id);
+    const footnoteFragment = page.fragments.find((fragment) => fragment.blockId === footnote.id);
+
+    expect(tableFragment?.kind).toBe('table');
+    expect(tableFragment && 'columnIndex' in tableFragment ? tableFragment.columnIndex : undefined).toBe(1);
+    expect(tableFragment?.x).toBeLessThan(columnTwoX);
+    expect(footnoteFragment?.x).toBeCloseTo(columnTwoX, 2);
+  });
 });

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

@@ -2916,5 +2916,5 @@ export { resolvePageNumberTokens } from './resolvePageTokens.js';
 export type { NumberingContext, ResolvePageTokensResult } from './resolvePageTokens.js';
 
 // Table utilities consumed by layout-bridge and cross-package sync tests
-export { getCellLines, getEmbeddedRowLines } from './layout-table.js';
+export { getCellLines, getEmbeddedRowLines, resolveTableFrame, resolveRenderedTableWidth } from './layout-table.js';
 export { describeCellRenderBlocks, computeCellSliceContentHeight } from './table-cell-slice.js';