fix(doc-codec): snap table column boundaries within a point when unioning rows into one grid

[Mearman]

Fixes #898.

The issue reported two failure modes in table/read.ts's column-grid union. They turned out to be different in kind, so only one of them is a bug: mode 1 (one-twip drift) is real and fixed here; mode 2 (rows carrying different left insets) reproduces identically in a real independent [MS-DOC] implementation, so the current reading is correct and the follow-up was documentation, not an algorithm change. Both are covered below with the evidence rather than asserted.

Mode 1: one-twip drift is a real bug

canonicalColumnBoundariesTwips compared boundaries by exact integer equality. Two rows meaning the identical grid but differing by a single twip split into a phantom hairline column, with a spurious colSpan on the cells of every row either side of it — columnWidthsPt [116.9, 0.05, 144.95, 220] instead of [116.9, 145, 220]. That exact output is what the two new drift tests produce when the fix is reverted, so the reproduction is confirmed rather than reasoned about.

LibreOffice is not the producer that would emit this drift, but it is the implementation that proves a tolerance belongs here. Five LibreOffice 26.2.5.2 tables were generated (soffice --headless --convert-to doc from hand-written .fodt), deliberately including widths that cannot land on whole twips (2.5cm/3.1cm/4.7cm, 0.77in/1.13in/1.61in). Every row of every table wrote a byte-identical rgdxaCenter — e.g. [0, 2338, 5238, 9638] for all three rows of the cm case — so LibreOffice rounds a table's columns to twips once for the whole table, not once per row. That is exactly why none of this package's existing LibreOffice-derived fixtures trips this.

The decisive evidence is what that implementation does on the read side. Patching a single int16 inside a_cm.doc's second row (through archive-codec's own readCompoundFile/writeCompoundFile, so the CFB stays valid), sweeping the drift, and running each patched file back through LibreOffice's own .doc importer (--convert-to fodt, counting real table:table-column / table:covered-table-cell elements):

drift (twips)	LibreOffice reads	doc-codec read, before this PR
1 … 20	3 columns, 0 covered cells	4 columns, spurious colSpan
21 … 200	4 columns, 3 covered cells	4 columns, spurious colSpan

The changeover is exact and sharp at 20/21.

Why one point is a derivation, not a picked number. Three independent lines agree on it:

1. columnWidthsPt states the reconstructed grid in points, and read.ts already defines TWIPS_PER_POINT = 20. A segment narrower than one point is below the smallest unit the grid can meaningfully distinguish, so the tolerance is TWIPS_PER_POINT itself rather than a literal.
2. LibreOffice faces the same inference — its table model is per-row too (SwTableLine → SwTableBox, each box with its own width) — and answers it with a named constant, #define COLFUZZY 20 in sw/source/filter/inc/wrtswtbl.hxx, where SwWriteTableCol::operator== treats positions differing by at most that as equal and SwXMLTableColumn_Impl's column set is an o3tl::sorted_vector ordered by that fuzzy comparator. a < b ⟺ a + 20 < b makes two boundaries equivalent exactly when |a − b| ≤ 20, which is precisely the measured changeover.
3. COLFUZZY (20) < MINLAY (23), LibreOffice's own minimum cell width (sw/inc/swtypes.hxx), which WW8TabDesc::CalcDefaults (sw/source/filter/ww8/ww8par2.cxx) actively widens a narrower imported cell up to — so the snap provably cannot swallow a legitimately minimum-width column. That same CalcDefaults mutating nCenter[] per row on import is also one real mechanism by which a .doc in the wild comes to carry per-row drift at all, with Word nowhere in the picture.

What changed

• The union sorts every row's boundaries and clusters greedily, opening a new canonical boundary only beyond the tolerance. Sorting first makes the result depend on the boundary values alone rather than on row order (unlike LibreOffice's own insertion-ordered set), and taking each cluster's smallest member as its representative keeps the array non-decreasing and anchored on the leftmost row's own left edge.
• logicalCellsForRow's two indexOf calls become a snap lookup with the same tolerance, since a row's raw boundary need not appear in the clustered array at all. A boundary matching nothing now throws rather than silently yielding a negative startGridIndex. It is an internal invariant — every boundary looked up went into building the grid — so it is labelled as one.
• A physical cell whose two boundaries land on one canonical entry is handled explicitly. rgdxaCenter need only be "in non-decreasing order" ([MS-DOC] 2.9.321), so equal adjacent entries — a legal zero-width cell — were previously computing colSpan: 0 and reaching the schema as an ordinary cell only because 0 > 1 happens to be false.

Mode 2: differing left insets are read correctly already

a_cm.doc patched so only row 1's first boundary moves 0 → 108, run back through LibreOffice's importer, yields a 4-column table with row 1 gaining a filler cell and rows 0 and 2 carrying table:number-columns-spanned="2" plus a real table:covered-table-cell. doc-codec produces columnWidthsPt [5.4, 111.5, 145, 220] with spans [2,1,1] [1,1,1] [2,1,1] — the same grid and the same spans. The sweep confirms LibreOffice keeps that phantom column for every inset ≥ 21 twips, and the issue's own real-world figure (108) is five times the tolerance.

This is not drift, and the tolerance deliberately does not absorb it. [MS-DOC] 2.9.321 defines rgdxaCenter[0] as "the horizontal position of the logical left edge of the table, as indented from the logical left page margin" — margin-relative, stated independently by each row — and 2.6.4 makes a per-row leading indent a first-class construct (sprmTWidthBefore, "the preferred additional leading indent of the first cell of the row, relative to the leading edge of the table as a whole"; sprmTDxaLeft/sprmTDxaGapHalf likewise row-scoped). Rows disagreeing about it genuinely occupy different horizontal extents. LibreOffice's WW8 importer even carries Word's own -108 as a named comment in CalcDefaults ("Word sets the first nCenter value to -108 when no indent is used"), matching the spec's own 108-twip sprmTCellPaddingDefault.

The only difference from LibreOffice is cosmetic: it pads the short row with an empty filler cell. That is deliberately not adopted — ContentTableRow.cells carries no grid-position field, so a reader-invented empty cell would be indistinguishable from real empty content on the write side, and table/write.ts already reconstructs each row's own narrower rgdxaCenter from spans without needing one.

What mode 2 did surface is a genuine, permanent limitation the README did not state: ContentTable is { kind, rows, columnWidthsPt, sourcePath?, source?, frames? } and ContentTableRow is { cells, heightPt? } — neither has a field that could hold a horizontal offset, so a table indent is dropped on read even in the simple case where every row agrees on it (a LibreOffice table with fo:margin-left="1.27cm" writes rgdxaCenter = [720, 2884, 5567, 9638] in every row and reads back as [108.2, 134.15, 203.55]). That is family-wide rather than a doc-codec gap — nothing in ooxml.js reads or writes w:tblInd/w:tblPrEx, and no codec here produces a table indent — and the Tables section now says so.

Tests

Eight new cases in src/table/read.test.ts, driven off rgdxaCenter arrays hand-assembled straight from [MS-DOC]'s own field tables rather than binary fixtures, matching the file's existing approach (this package deliberately has no real-world corpus). They cover the whole prototype table the investigation verified against LibreOffice's own import: no drift, drift of one twip, drift of exactly one point, drift of one point and one twip, Word's -108 stated by every row, a 108-twip indent stated by one row only, the real #895 LibreOffice merged-row arrays, and a legal zero-width cell. The tolerance cases are phrased as fractions of a point derived from TWIPS_PER_POINT, never as bare 20/21.

Reverting the read.ts change and re-running fails exactly two of them — the one-twip and one-point drift cases, with [116.9, 0.05, 144.95, 220] and [116.9, 1, 144, 220] against the expected [116.9, 145, 220]. Every other new case passes both before and after, which is the point: they pin behaviour the tolerance must not change, including #895's merge reconstruction and mode 2's deliberate phantom column.

Verification

pnpm exec turbo run _lint _typecheck _test _test:workers --filter=doc-codec --force — 6/6 tasks, 162 unit tests and 5 workerd tests passing. pnpm exec turbo run _lint _typecheck --force across the workspace — 57/57. pnpm exec turbo run _test across the workspace — 36/36.

A real regression found and fixed on independent review

The one-point tolerance's own "provably cannot swallow a legitimately narrow column" claim was false: that guarantee is LibreOffice's own writer-side MINLAY minimum-cell-width widening, which this package's writer has no equivalent of. Proven by round-tripping through the package itself: writing a genuinely 0.5pt-wide column and reading it back silently deleted it ([50,0.5,50] -> [50,50.5]), a regression against the pre-PR behaviour, where all four such cases round-tripped exactly.

Fixed by clamping the tolerance, per table, to one twip below the narrowest strictly-positive gap any single row states between two of its own adjacent boundaries -- two boundaries a row itself distinguishes are never folded together, however close. Confirmed against a mutation reverting the clamp: the new regression tests fail, restoring the clamp passes them.

Also corrected two claims that attributed the confirmed 20/21-twip changeover to LibreOffice's own .doc importer -- the import side preserves per-row drift untouched; the fuzz is applied on its ODF export instead, the actual point where a per-row table model is projected onto one shared grid -- and hedged the -108/sprmTCellPaddingDefault causal link as a plausible inference rather than a sourced fact.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-04T02:56:41.718255Z	76fbd4c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.