fix(tables): fix autofit column scaling, cell width overflow, and page break splitting

[tupizz]

Summary

Fixes three interrelated table rendering bugs that caused columns to disappear, cells to overflow page boundaries, and autofit tables to render at incorrect widths.

Closes SD-1797, SD-1859, SD-1895

SD-1797: Autofit tables losing columns

• Column count derived from cells.length instead of colSpan sums — rows with rowspan continuations have fewer physical cells, dropping the rightmost column
• Cell colwidth values (scaled from tcW during import) preferred over authoritative w:tblGrid values
• Auto-layout tables not scaled up to fill available page width
• Page breaks splitting rowspan groups instead of keeping them together

SD-1859: Percent-width table cell overflow in mixed-orientation docs

• Tables measured at the widest section's content width (e.g. 864px landscape) but rendered in narrower sections (e.g. 624px portrait)
• Cell X positions used rescaled column widths correctly, but cell widths still used the original measurement values — causing cells to overflow the fragment container

CleanShot.2026-02-12.at.11.53.59.mp4

SD-1895: Autofit DOCX tables rendering narrow

• Same root cause as SD-1797 (column width priority): tcW cell hints took priority over w:tblGrid, making tables render at their hint widths instead of filling the page

Changes

Column width priority (measuring/dom/index.ts)

• maxCellCount now sums colSpan values per row instead of counting physical cells
• Auto-layout tables scale both up and down to fill effectiveTargetWidth

Per-fragment column rescaling (layout-table.ts, incrementalLayout.ts)

• New rescaleColumnWidths() proportionally scales column widths when measured width exceeds fragment width
• TableFragment.columnWidths added to contracts — carries rescaled widths per fragment

Cell width from column widths (renderTableRow.ts, renderTableCell.ts)

• renderTableRow computes cell width by summing columnWidths[gridStart..gridStart+colSpan]
• renderTableCell accepts optional cellWidth parameter, using it instead of cellMeasure.width
• renderTableFragment uses fragment.columnWidths ?? measure.columnWidths as effectiveColumnWidths

Page break improvements (layout-table.ts)

• Rowspan-aware split point: tracks maxRowspanEnd and lastCleanFitRow to avoid splitting rowspan groups
• Ghost cell rendering for rowspan continuations across page breaks
• Header-skip for cantSplit rows when repeated headers would prevent fitting

Visual regression tests

• percent-width-table-overflow — validates 100% width table doesn't overflow in portrait pages
• autofit-table-fill-width — validates auto-layout tables fill page width (programmatic)
• autofit-table-docx-rendering — validates SD-1895 DOCX table renders correctly

Test plan

• pnpm --filter @superdoc/layout-engine test -- --run layout-table — rowspan-aware breaks, rescaleColumnWidths
• pnpm --filter @superdoc/painter-dom test -- --run renderTableFragment — effectiveColumnWidths, cell width from columnWidths
• pnpm --filter @superdoc/layout-bridge test — measurement constraint tests
• TypeScript compiles (pnpm build)
• Visual tests pass on chromium, firefox, webkit
• Manual: upload mixed-orientation DOCX → verify table fits within portrait page bounds
• Manual: upload SD-1895 autofit DOCX → verify table fills page width

[linear]

SD-1797 Bug: inaccurate rendering of autofit tables

SD-1859 Percent-width table overflows on portrait pages in mixed-orientation docs

SD-1895 Bug: Autofit table renders with column widths as defined by cell size (should be ignored)

[github-actions]

Based on my review of the code changes and my knowledge of ECMA-376 WordprocessingML specification, here is my assessment:

Status: PASS

The changes in legacy-handle-table-cell-node.js appear to be spec-compliant. Here's what the code is doing:

What Changed

The modification (lines 73-90, 97-98) adds logic to handle cells with w:gridSpan (colspan) where the cell's w:tcW (table cell width) exceeds the sum of the grid columns it spans.

OOXML Spec Compliance

The implementation correctly handles the ECMA-376 table model:

1. w:tcW (Table Cell Width): Lines 63-69 correctly extract the cell width from w:tcPr/w:tcW/@w:w and convert from twips to pixels. The spec allows this attribute on table cells.

2. w:gridSpan (Grid Span): Line 41 correctly reads w:tcPr/w:gridSpan/@w:val which specifies how many grid columns the cell spans. This is a valid ECMA-376 attribute.

3. Width Resolution Logic: The code computes total grid width (lines 87-89) and only scales when tcW > gridSpanTotal + 1 (line 90). This matches Word's behavior where cell width hints can exceed grid totals for autofit tables.

4. Proportional Distribution: Lines 97-98 distribute the excess width proportionally across spanned columns. While the spec doesn't mandate this exact algorithm, it's a reasonable interpretation of how to reconcile conflicting width values.

Minor Observations

• The +1 tolerance in line 90 (cellOwnWidth > gridSpanTotal + 1) is a practical rounding buffer, not from the spec, but this is reasonable for handling floating-point precision.
• The fallback defaultColwidth = 100 (line 94) is an implementation default when grid columns are missing, which is acceptable.

The code correctly interprets the relationship between w:tcW, w:gridSpan, and w:tblGrid elements as defined in ECMA-376 Part 1 §17.4.

For details on these elements, see https://ooxml.dev/spec?q=tcW and https://ooxml.dev/spec?q=gridSpan.

[Copilot]

Pull request overview

Fixes several table rendering/layout issues across measurement, layout, and DOM painting to prevent column loss, cell overflow in mixed-orientation docs, and incorrect autofit scaling; also improves table splitting behavior and adds regression/visual coverage.

Changes:

• Correct table measurement/scaling (colspan-aware column count; scale auto-layout tables up/down to effective width; adjust spacing.after handling).
• Add per-fragment column width rescaling for clamped tables and use those widths when computing/rendering cell widths.
• Improve page splitting for rowspans (clean split points + ghost cells) and add regression + visual tests/data.

Reviewed changes

Copilot reviewed 20 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/visual/tests/rendering/table-fixes.spec.ts	Adds visual rendering coverage for SD-1797/1859/1895 using doc-based screenshots.
packages/super-editor/src/tests/regression/table-autofit-colspan.test.js	Adds editor-level regression test ensuring colspan/autofit tables preserve grid columns.
packages/super-editor/src/tests/data/table.docx	Adds DOCX fixture for table-related tests.
packages/super-editor/src/tests/data/table-autofit-colspan.docx	Adds DOCX fixture reproducing colspan/autofit grid truncation.
packages/super-editor/src/tests/data/pci-table.docx	Adds DOCX fixture for rowspan/column-count scenarios.
packages/super-editor/src/core/super-converter/v3/handlers/w/tc/helpers/legacy-handle-table-cell-node.js	Adjusts cell colwidth generation to optionally scale tcW across grid spans when tcW exceeds grid total.
packages/layout-engine/pm-adapter/src/converters/table.ts	Changes width-priority to prefer OOXML tblGrid over cell colwidth when userEdited is false.
packages/layout-engine/pm-adapter/src/converters/table.test.ts	Updates converter tests to reflect new grid-over-colwidth priority and twips→px expectations.
packages/layout-engine/painters/dom/src/table/renderTableRow.ts	Computes rendered cell width from (possibly rescaled) columnWidths and passes it to cell renderer.
packages/layout-engine/painters/dom/src/table/renderTableFragment.ts	Uses per-fragment columnWidths when present; adds ghost-cell rendering for rowspan continuations.
packages/layout-engine/painters/dom/src/table/renderTableFragment.test.ts	Adds tests ensuring fragment.columnWidths drives rendered cell widths.
packages/layout-engine/painters/dom/src/table/renderTableCell.ts	Accepts optional computed cellWidth; changes spacing.after behavior for last paragraph in a cell.
packages/layout-engine/painters/dom/src/table/renderTableCell.test.ts	Updates tests to reflect last-paragraph spacing.after behavior change.
packages/layout-engine/measuring/dom/src/index.ts	Makes max column count colspan-aware; scales auto-layout tables up/down; updates cell spacing.after measurement.
packages/layout-engine/measuring/dom/src/index.test.ts	Adds tests for colspan/rowspan column preservation and updated spacing.after measurement expectations.
packages/layout-engine/layout-engine/src/layout-table.ts	Adds rescaleColumnWidths for clamped tables; improves split-point selection for rowspans; adds header-skip for cantSplit interactions.
packages/layout-engine/layout-engine/src/layout-table.test.ts	Adds tests validating per-fragment column width rescaling behavior.
packages/layout-engine/layout-bridge/test/resolveMeasurementConstraints.test.ts	Adds tests ensuring measurement width uses max section content width in mixed-orientation docs.
packages/layout-engine/layout-bridge/src/incrementalLayout.ts	Rescales fragment column widths during incremental layout when tables are clamped.
packages/layout-engine/contracts/src/index.ts	Extends TableFragment contract with optional per-fragment columnWidths.
devtools/visual-testing/tests/interactions/stories/tables/percent-width-table-overflow.ts	Adds interaction story verifying percent-width tables don’t overflow in portrait sections.
devtools/visual-testing/tests/interactions/stories/tables/autofit-table-fill-width.ts	Adds interaction story verifying inserted auto-layout tables fill available width.
devtools/visual-testing/tests/interactions/stories/tables/autofit-table-docx-rendering.ts	Adds interaction story validating DOCX autofit tables fill page width.
devtools/visual-testing/pnpm-lock.yaml	Updates lockfile for local superdoc tarball integrity.

Files not reviewed (1)

• devtools/visual-testing/pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a97b2c396

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[github-actions]

Visual diffs detected

Pixel differences were found in visual tests. This is not blocking — reproduce locally with cd tests/visual && pnpm docs:download && pnpm test to review diffs.