fix(docx): hang a list item's marker into the margin by its signed indent

[developer0hye]

File submission policy

Before attaching or committing files, read the submission policy.
Complete a security review and obtain your organization's internal approval for
public sharing where applicable. You are responsible for lawful disclosure;
the project and maintainers disclaim related liability to the extent permitted
by applicable law.

• Any submitted sample files or attachments satisfy the submission policy, or none are submitted.

Summary

Second milestone of #2233: body list items now take a signed indent. Word puts a list item's marker at the margin plus its w:ind w:left minus its hanging span, and its lines at the margin plus w:left, even when that lies left of the margin. paragraph_list_indent clamped both the left indent and the marker origin at zero. When the marker origin clamped onto the left indent, it returned no geometry at all, and Typst's default enum layout took over. In docxide-pdf case97 (w:left="-100" w:hanging="5"), Word draws "1." at 66.775pt and the tabbed body at 80.525pt; main drew them at 72pt and 88pt. They now land at 66.75pt and 80.55pt.

• Renderer (typst_gen_lists.rs): paragraph_list_indent keeps the sign when a new ListEojeolWrap::hangs_into_margin flag is set. Typst's enum/list indent: takes a negative length, so the marker and body start left of the margin. Only the Word flow body sets the flag. Table cells keep the clamp under TODO(#2261 cell clip), like cell paragraphs since fix(docx): hang a body paragraph with a negative indent into the margin #2382, and slide lists keep theirs.
• Gate (docx_lists.rs, docx.rs): a corpus scan showed that a paragraph style's w:ind still stands in for a direct w:numPr level's indent (filed as DOCX: a paragraph style's w:ind overrides a direct w:numPr level's indent, so the marker starts 18pt left of Word #2383). With signed geometry that wrong indent would hang such markers further from Word: docxide slovak_fuel_pricing_report would go from 17.95pt to 35.95pt off Word's 88.80pt. Until DOCX: a paragraph style's w:ind overrides a direct w:numPr level's indent, so the marker starts 18pt left of Word #2383 is fixed, a list paragraph whose style chain supplies an indent its level also declares keeps main's geometry (TODO(#2383)). A dedicated test pins the gate and should be deleted along with it.

Corpus scan

Base ca194434 and candidate release CLIs were built in separate run-owned targets (cmp differ). Both converted the 648 DOCX files that have a numbering part (fixtures-v1 bulk corpus, docxide-pdf fe7b8bea cases/ and scraped/) plus 40 random documents without one. I compared mutool draw -F stext per-glyph positions. All 688 conversions succeeded on both builds. The controls and the three gated documents (slovak, poi/checkboxes, libreoffice/2129393649) are unchanged. Four documents moved:

Document	Change	Reference
docxide case97	"1." 72 → 66.75, body 88 → 80.55	Word 66.775 / 80.525
bulk libreoffice/tdf123054 (w:ind w:left="0" w:hanging="284")	first body glyph 83.35 → 70.85; wrapped lines (page 4) 87.34 → 70.85; "I." 70.85 → 56.65	LibreOffice 24.2 (labelled): body 70.95, "I." ends at the 56.65pt origin because its level is lvlJc="right", filed as #2385
bulk poi/bug65649 p13 (w:left="0", level hanging 18.75pt)	"3." 85.05 → 66.3, body stays 85.05	LibreOffice centres the whole line (w:jc="center"), which list items ignore before and after; filed as #2386
bulk poi/bug59058 p54	an empty item's "o" 72 → 54 (w:left="0", hanging 18pt)	the paragraph mark is w:vanish; under the paragraph-mark rule in #2384 Word would hide this bullet (no Word reference)

Follow-ups filed with compare images in this PR: #2383 (style indent beats a direct numbering level), #2384 (marker formatted from the runs instead of the paragraph mark), #2385 (w:lvlJc ignored) and #2386 (list items ignore w:jc).

Related issue

Related: #2233. The issue stays open: table-cell paragraphs and lists still clamp until cells clip at their edge (#2261).

Testing

• cargo test --locked -p office2pdf --profile ci --lib -- docx_list_marker_and_body_hang docx_list_hanging_into_the_margin: both new tests failed on the unfixed code (marker at 85.05pt instead of 31.05pt; "1." at 72pt instead of 66.775pt) and pass now.
• docx_style_indent_under_direct_numbering_keeps_the_marker_at_the_margin fails with the gate disabled (marker at 67.05pt) and passes with it.
• cargo test --locked --workspace --profile ci: all suites pass (office2pdf lib 3863 passed, 0 failed).
• cargo fmt --all -- --check; cargo clippy --locked --workspace --all-targets -- -D warnings: clean.
• Corpus scan and evidence as described above and below.

Visual impact

• No rendered PDF change
• Rendered PDF change or visual evidence added
• Reason: Not applicable; list item markers and lines move.

Visual audit

• Issue: DOCX: a negative w:ind w:left is clamped to zero, so a paragraph that hangs into the margin starts 71pt right of Word #2233
• Fixture: tests/fixtures/docx/docxide/numbering_negative_indent.docx (docxide-pdf case97, unmodified; GT is its Microsoft Word reference.pdf)
• Page(s): 1
• Renderer and DPI: pdftoppm, 150 DPI
• Evidence mode: fix
• Baseline failure report: None
• Layout audit report: assets/bugfixes/issue-2233/layout-audit.json
• Render cluster reports: assets/bugfixes/issue-2233/render-clusters-page-1.json
• Reference exporter differences: None
• Fine-detail threshold: 0.5pt
• Layout audit page count: Pass
• Layout audit text flow: Pass
• Layout audit visible fills: Pass
• Layout audit rectangle geometry: Pass
• Layout audit large shifts: Pass
• Layout audit fine shifts: Pass
• New follow-up issues found in this audit: DOCX: a list marker takes its runs' formatting instead of the paragraph mark's, so case97's "1." paints in Times 14pt where Word uses Aptos 12pt #2384
• Model vision findings: I inspected the full GT, before and after pages, the 5% diff and 150 DPI crops of the list line.
  • Before: "1. Test marker" starts at the margin, 5.2pt right of Word's.
  • After: the marker and "Test" sit where Word's do. The diff shows the "T" matched (grey).
  • The marker "1." is a serif Times New Roman 14pt glyph where Word paints a smaller sans Aptos 12pt one (DOCX: a list marker takes its runs' formatting instead of the paragraph mark's, so case97's "1." paints in Times 14pt where Word uses Aptos 12pt #2384). It shows red in the diff but stays under the cluster area floor.
  • "est marker" is offset right by one pair kern (Word kerns T-e; 1.07pt) with the same glyph shapes and weight: clusters p1-fdf16f925882, p1-bab31bb1f25c, p1-cdf915b18a72 and p1-56013fea6996, dispositioned under Tracker: sub-materiality visual deviations (revisit in bulk) #1874.
  • No hairlines, borders, fills, italic or underline on the page.
• GT: assets/bugfixes/issue-2233/gt.jpg
• Before: assets/bugfixes/issue-2233/before.jpg
• After: assets/bugfixes/issue-2233/after.jpg
• Native: None
• Compare: None

Visual comparison

GT	Before	After

Required inspection

• Rendered all evidence at 150 DPI or higher
• Stored progressive JPEG quality 86 assets with metadata stripped
• Used Codex/Claude vision to inspect the full GT/output pages, diff, and matched crops
• Inspected matched region crops at full resolution
• Ran compare_layout.py --audit --fine-shift PT and dispositioned every fine/large text-instance shift, rectangle geometry deviation, painted-text visibility mismatch, and visible-fill occlusion
• Ran compare_render.py --cluster-report PATH --strict-clusters and dispositioned every material 5% fuzz diff cluster by explicit ID
• Inventoried hairlines and border dash styles
• Inventoried font weight, italic, and underline emphasis

Deviation audit

Check	Result
Page count/order	Matches GT: one page
Element presence	Matches GT: marker and body text present
Position/size	Remaining: #1874. The marker (66.75pt vs Word 66.775pt) and body (80.55pt vs 80.525pt) are fixed. "est marker" sits 1.07pt right of Word's pair-kerned T-e
Rotation/flip	No deviation observed
Fill	No deviation observed
Stroke/border	No deviation observed
Shape outline geometry	No deviation observed
Text content	Matches GT: normalized text identical (compare_text_layer.py)
Font family/weight/style	Remaining: #2384. The marker is Times New Roman 14pt where Word uses the paragraph mark's Aptos 12pt
Text color	Matches GT: black
Alignment	Matches GT: left-aligned line
Line/paragraph spacing	Matches GT: baseline within 0.21pt
Clipping/overflow	Matches GT: the marker hangs 5.25pt into the margin, unclipped, as in Word

Final performance pass

• Status: Complete
• Measurements: release CLIs from base ca194434 and this branch, built in separate run-owned targets (cmp differ). /usr/bin/time -f "%e %M" (elapsed s, peak RSS); one warm-up pass, then 12 interleaved base/branch runs per input, warm page cache, output to /tmp. Intel i5-10400 (12 threads), Linux 7.0.0-38, dev-box fonts (Liberation/Noto substitutes, no MS core fonts). Medians, base → branch:
  • case97 (reported): 0.260 → 0.260 s, 42.2 → 42.2 MiB.
  • bulk tdf123054 (mover): 0.465 → 0.460 s, 57.3 → 57.1 MiB.
  • bulk bug65649 (178 pages, list-heavy, mover): 4.325 → 4.300 s, 1152.3 → 1138.7 MiB.
  • control spaced_section_mark.docx (unchanged output): 0.265 → 0.260 s, 42.4 → 42.3 MiB.
• Outcome and revalidation: no measurable cost. The change adds one style lookup per directly numbered paragraph and a sign check in the list geometry, and every delta is within run-to-run noise (RSS noise on this box reaches about 3 MiB on small inputs, and more on the 1.1 GiB bug65649 run). There is no bottleneck to optimize, so no optimization code changed. The tests and the visual comparison above are the final revalidation.

Checklist

• Commits include a Signed-off-by line
• Final memory/speed pass completed after visual acceptance, or no conversion runtime impact is explained
• PR scope contains one root cause
• Remaining converter or harness deviations each reference an open issue

🤖 Generated with Claude Code