Pagination: force the load-bearing verdict (axis: DOCX fidelity)

[arthrod]

@coderabbitai plan

🥕 forced comparative — variant D (the "pick a side" carrot). Sibling forcing-issues: #355. Parent variants: #353 (A — render-overlay) and #354 (B — document-model sections). You already produced parallel plans on each; you did NOT produce the comparative load-bearing sentence. This issue exists to force it.

My goal

Identical to #353 and #354. Ship @platejs/pagination (headers, footers, footnotes) leveraging chenglou/pretext.

The forced-choice question (axis 2: DOCX section fidelity vs zero-schema-migration)

The two plans diverge most sharply on how the document tree changes shape:

• Variant A (Plate pagination plugin (headers / footers / footnotes) with pretext (variant A) #353): editor.children shape is unchanged from a non-paginated Plate doc. Existing documents and existing plugins keep working with zero schema migration. DOCX section properties (w:sectPr, w:hdrRef, w:ftrRef) are mapped from top-level header / footer siblings + plugin options — a translation, not a 1:1 mapping.
• Variant B (Plate pagination plugin (headers / footers / footnotes) with pretext (variant B) #354): editor.children becomes Section[]. Every existing Plate document needs migration on first load. DOCX round-trip is a near-direct mapping to w:sectPr and friends — byte-stable round-trip is plausible.

These have opposite costs. Pick the side that wins for arthrod/plate.

What I want from you

Read your own coding plans on #353 and #354. Do not re-plan. Output only:

1. A single sentence in the canonical form:

   "If <X> matters more than <Y>, variant <A|B> wins; otherwise the other."
   where <X> and <Y> are concrete properties drawn from the DOCX-fidelity / schema-migration axis (e.g. "byte-stable DOCX section round-trip" vs "zero-migration upgrade for existing documents").

2. A two-line justification anchored in this codebase — cite file:line from packages/docx/ (or whichever package owns DOCX import/export here).
3. A binary verdict: A or B, given how this repo's DOCX pipeline actually behaves today.

Do not restate implementation steps. Do not propose a variant E. Pick.

Because the code is

• Variant A's plan on Plate pagination plugin (headers / footers / footnotes) with pretext (variant A) #353 — your "Coding Plan" from 2026-05-04T21:57:40Z (CR) — flat doc shape, top-level header/footer siblings.
• Variant B's plan on Plate pagination plugin (headers / footers / footnotes) with pretext (variant B) #354 — your "Coding Plan" from 2026-05-04T22:02:49Z (CR) — Section[] invariant via overrideEditor + withNormalizeNode; configurePlugin for footnote section-scoping.
• packages/docx/ (or wherever this fork's DOCX importer/exporter actually lives — find it and cite). Tell us how rich the existing w:sectPr handling is. If it's already lossy, B's "byte-stable" claim is fictional. If it's already faithful, A's translation layer adds risk.
• packages/footnote/src/lib/BaseFootnoteDefinitionPlugin.ts — footnote node placement policy. Whether sections need to scope footnote definitions or whether document-tail placement is fine.

Validate this approach — especially but not limited to

• Static analysis of the DOCX pipeline in this fork. Locate the existing section-property handling. Cite real file:line. If w:sectPr is currently dropped or partially mapped, say so — that fact alone may decide this axis.
• Comparative analysis vs sibling Pagination: force the load-bearing verdict (axis: Yjs determinism) #355 which forces the Yjs / collaborative axis. Confirm whether your verdict on this issue is consistent with that one. If not, name which axis is itself load-bearing across both.

Acceptance

Your reply contains the canonical sentence + verdict. Anything else is noise.

A carrot is not a beetroot. Pick.

[blocksorg]

Mention Blocks like a regular teammate with your question or request:

@blocks can you add technical details to this issue?
@blocks make the following changes ...
@blocks create an issue from what was mentioned in the following comment ...
@blocks explain the following code ...
@blocks are there any security or performance concerns?

Run @blocks /help for more information.

Workspace settings | Disable this message

[kilo-code-bot]

This issue appears to be a duplicate of #355.

Pagination: force the load-bearing verdict (axis: Yjs determinism) (#355)

Similarity score: 97%

This comment was generated by Kilo Auto-Triage.

[arthrod]

🥕 Forcing pair: #355 (other axis). Parents: #353 (variant A) #354 (variant B). @coderabbitai pick a side.

[coderabbitai]

Verdict: A

Canonical sentence: If zero-migration upgrade for existing documents matters more than byte-stable DOCX section round-trip, variant A wins; otherwise B.

Justification (2 lines):
packages/docx-io/src/lib/internal/schemas/document.template.ts:27-35 emits only <w:pgSz> + <w:pgMar> — no w:hdrRef or w:ftrRef exists anywhere in the pipeline; B's "byte-stable" claim is fictional since the serialization infrastructure must be built regardless, while B additionally forces schema migration on every existing document.

Consistent with #355 verdict: Yes — both axes resolve to A.

[coderabbitai]

Coding Plan

Summary

• The DOCX import pipeline (mammoth.convertToHtml) drops all section properties before Plate processes the document, making byte-stable round-trip impossible regardless of document model
• Variant A wins because zero-migration is a tangible benefit while Variant B's DOCX fidelity advantage is blocked by the existing import architecture
• Consistent with collaborative (Yjs) axis: flat document shape in Variant A avoids the structural complexity that complicates CRDT merge semantics

Implementation Steps

Verdict Delivery

Deliver the canonical verdict on whether Variant A or Variant B wins for @platejs/pagination, anchored in actual codebase behavior.

Task 1: Canonical Decision Sentence

"If byte-stable DOCX section round-trip matters more than zero-migration upgrade for existing documents, variant B wins; otherwise A."

Task 2: Codebase-Anchored Justification

• packages/docx-io/src/lib/importDocx.ts:51-82 — mammoth conversion silently discards w:sectPr, w:hdrRef, and w:ftrRef; section properties never reach Plate regardless of document model choice
• packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46 — export emits only w:pgSz + w:pgMar inside w:sectPr; header/footer references are conditional and caller-supplied, not round-tripped from source

Task 3: Binary Verdict

Verdict: A

Variant B's "byte-stable round-trip" claim is fictional — mammoth's lossy import already breaks round-trip fidelity before the document model is even involved. Variant A's zero-migration benefit is real and immediate; Variant B's DOCX fidelity benefit cannot be realized without replacing the entire import pipeline (mammoth → raw XML parser). Given this codebase's actual DOCX handling, the schema migration cost of Variant B buys nothing.

🤖 Prompt for AI agents

This phase delivers the research-backed verdict on Variant A vs. Variant B for
`@platejs/pagination` — no code changes are required.

- Document the canonical decision sentence: if byte-stable DOCX section
round-trip matters more than zero-migration, Variant B wins; otherwise Variant A
wins.
- Record the codebase-anchored justification referencing:
- `packages/docx-io/src/lib/importDocx.ts:51-82` — mammoth silently discards
`w:sectPr`, `w:hdrRef`, `w:ftrRef` on import
- `packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46` —
export only emits `w:pgSz` + `w:pgMar`; header/footer refs are conditional and
caller-supplied, not round-tripped
- Record the binary verdict as **Variant A**, with the rationale that mammoth's
lossy import makes Variant B's round-trip fidelity claim unrealizable without
replacing the entire import pipeline, so Variant B's schema migration cost
provides no benefit in this codebase.

Research

The DOCX pipeline spans two packages: packages/docx/ (paste-from-Word HTML cleaner) and packages/docx-io/ (actual file import/export). Import uses mammoth which discards all section properties (w:sectPr, w:hdrRef, w:ftrRef) before Plate ever sees them. Export partially writes w:sectPr (page size/margins only) with conditional header/footer references. The footnote plugin uses document-tail placement with no section scoping.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase delivers the research-backed verdict on Variant A vs. Variant B for
`@platejs/pagination` — no code changes are required.

- Document the canonical decision sentence: if byte-stable DOCX section
round-trip matters more than zero-migration, Variant B wins; otherwise Variant A
wins.
- Record the codebase-anchored justification referencing:
- `packages/docx-io/src/lib/importDocx.ts:51-82` — mammoth silently discards
`w:sectPr`, `w:hdrRef`, `w:ftrRef` on import
- `packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46` —
export only emits `w:pgSz` + `w:pgMar`; header/footer refs are conditional and
caller-supplied, not round-tripped
- Record the binary verdict as **Variant A**, with the rationale that mammoth's
lossy import makes Variant B's round-trip fidelity claim unrealizable without
replacing the entire import pipeline, so Variant B's schema migration cost
provides no benefit in this codebase.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[coderabbitai]

Coding Plan

Summary

• Verdict from static analysis of actual DOCX pipeline, not theoretical fidelity goals
• Mammoth import layer is the bottleneck; document model choice cannot fix it

Implementation Steps

Verdict

Deliver binary verdict: Variant A vs. Variant B for @platejs/pagination, anchored in actual DOCX pipeline behavior.

Deliver Decision

Canonical sentence:

"If byte-stable DOCX section round-trip matters more than zero-migration upgrade for existing documents, variant B wins; otherwise A."

Justification:

• packages/docx-io/src/lib/importDocx.ts:51-82 — mammoth discards w:sectPr/w:hdrRef/w:ftrRef; section properties never reach Plate
• packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46 — export emits only w:pgSz+w:pgMar; no round-trip preservation

Verdict: A

B's byte-stable claim is fictional — mammoth's lossy import breaks fidelity before document model matters. A's zero-migration benefit is real; B's requires replacing the entire import pipeline.

🤖 Prompt for AI agents

Deliver the verdict on Variant A vs. Variant B for `@platejs/pagination`. No
code changes.

- Canonical sentence: byte-stable DOCX round-trip > zero-migration → B wins;
otherwise A.
- Justification:
- `packages/docx-io/src/lib/importDocx.ts:51-82` — mammoth drops
`w:sectPr`/`w:hdrRef`/`w:ftrRef`; section props never reach Plate
- `packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46` —
export only emits `w:pgSz`+`w:pgMar`; no round-trip
- Verdict: **A**. B's fidelity claim unrealizable without replacing mammoth
pipeline; migration cost buys nothing here.

Research

DOCX import: mammoth discards w:sectPr, w:hdrRef, w:ftrRef before Plate sees them. Export partially writes section properties. Round-trip fidelity already broken at import.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Deliver the verdict on Variant A vs. Variant B for `@platejs/pagination`. No
code changes.

- Canonical sentence: byte-stable DOCX round-trip > zero-migration → B wins;
otherwise A.
- Justification:
- `packages/docx-io/src/lib/importDocx.ts:51-82` — mammoth drops
`w:sectPr`/`w:hdrRef`/`w:ftrRef`; section props never reach Plate
- `packages/docx-io/src/lib/internal/schemas/document.template.ts:37-46` —
export only emits `w:pgSz`+`w:pgMar`; no round-trip
- Verdict: **A**. B's fidelity claim unrealizable without replacing mammoth
pipeline; migration cost buys nothing here.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!