feat: support paragraph bar borders

[iguit0]

Summary

Adds support for Word paragraph bar borders (w:pBdr/w:bar) in the layout/rendering pipeline.

w:bar is the vertical decorative line rendered on the left edge of a paragraph. It was already parsed upstream, but it never made it through the layout-engine path, so it could not render in DomPainter.

Root cause

w:bar was being dropped in normalizeParagraphBorders() inside the pm-adapter layer.

Because of that:

• ParagraphBorders did not expose bar
• normalized paragraph attrs never carried bar
• paragraph border hashes/equality checks ignored bar
• DomPainter never had any bar data to render

What changed

Contracts

• added bar?: ParagraphBorder to packages/layout-engine/contracts/src/index.ts

PM adapter

• updated normalizeParagraphBorders() to preserve bar
• kept the existing between special-case behavior scoped to between only
• bar now normalizes like the other paragraph border sides:
  • style mapping
  • width conversion
  • color normalization
  • space support

Hashing / invalidation / grouping

Updated the paragraph-border identity paths so bar-only changes are treated as real visual changes:

• packages/layout-engine/layout-bridge/src/paragraph-hash-utils.ts
• packages/layout-engine/painters/dom/src/paragraph-hash-utils.ts
• packages/layout-engine/layout-bridge/src/diff.ts
• packages/layout-engine/layout-engine/src/layout-paragraph.ts

This ensures:

• cache invalidation happens when only bar changes
• paragraphs that differ only by bar do not incorrectly group for between rendering

DomPainter rendering

• implemented bar rendering in packages/layout-engine/painters/dom/src/features/paragraph-borders/border-layer.ts
• renders bar as a separate absolutely-positioned vertical rule on the left side of the paragraph border box
• keeps bar independent from the normal left border so both can coexist
• does not change existing between behavior

Implementation detail:

• bar is rendered as a dedicated child decoration element attached to the existing paragraph border layer
• its horizontal offset is based on the rendered left border width plus normalized bar.space
• it uses the normalized style, width, and color values
• pointer events remain disabled

Test plan

• Import a .docx with a paragraph using only w:bar; verify a left-side vertical bar renders.
• Import a .docx with both w:left and w:bar; verify both render independently.
• Verify w:bar + paragraph shading renders correctly and the bar stays visible.
• Verify consecutive paragraphs with identical borders still group correctly with between.
• Verify consecutive paragraphs that differ only by bar no longer group.
• Inspect rendered DOM and confirm bar is a separate decoration element with pointer events disabled.

Closes #2282

[caio-pizzol]

@iguit0 nice work — the bar rendering is the best of the three apps we tested. Word ignores bar borders entirely, Google Docs renders them but loses the color, SuperDoc gets it right.

one thing to look at: both Word and Google Docs ignore bar when deciding whether to group paragraphs together. right now SuperDoc breaks the group when bars differ, but the other two don't. left an inline comment with more detail.

couple of small cleanup suggestions in the other comments. tests look good.

[caio-pizzol]

we tested this file in Word and Google Docs — both still group paragraphs together even when their bar borders are different. including bar here breaks that grouping in SuperDoc. the bar should still trigger a re-render when it changes, but it shouldn't affect whether paragraphs are grouped for between borders. worth splitting those two?

[iguit0]

Fixed! Removed bar from this hash (grouping) and the layout-engine's local hashBorders. The layout-bridge copy keeps bar for cache invalidation, so there's now an intentional divergence between the two copies. Added a comment explaining why.

[iguit0]

@iguit0 nice work — the bar rendering is the best of the three apps we tested. Word ignores bar borders entirely, Google Docs renders them but loses the color, SuperDoc gets it right.

one thing to look at: both Word and Google Docs ignore bar when deciding whether to group paragraphs together. right now SuperDoc breaks the group when bars differ, but the other two don't. left an inline comment with more detail.

couple of small cleanup suggestions in the other comments. tests look good.

Fixed the grouping behavior: bar is now excluded from the grouping hash in both the painter and layout-engine paths, so paragraphs that differ only by bar stay grouped. The layout-bridge hash (cache invalidation) still includes bar so bar changes trigger re-render. Updated tests to match.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[caio-pizzol]

Hey @iguit0, thanks for the work — the code and tests are solid.

I tested the doc in Word and Word never draws these bars. It keeps them in the file on save but doesn't show them on screen. The spec says apps can skip them, and Word does.

SuperDoc today doesn't draw them either, so main already matches Word. This PR would be the one thing that starts drawing them.

Suggest closing for now. If a real doc needs bars drawn later, we can revisit with that context. If you have a doc in mind, share it and I'll take another look.

Thank you for all the work still! We can add it in the future if relevant