Plate pagination plugin (headers / footers / footnotes) with pretext (variant B)

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant B of 2 parallel framings of the same goal.
Sibling variant: #353. Please compare and tell us which assumption is load-bearing.
A bigger carrot, but pickled in the document model.

My goal

Ship a Plate plugin (@platejs/pagination) that adds print-grade pagination — fixed-size pages (A4 by default) with per-page headers, footers, and footnotes — leveraging chenglou/pretext (text measurement / height oracle, MIT, ESM, v0.0.6) for the line-break and height math that Plate currently lacks.

To do so, do this (variant B — document-model section nodes; pretext as auto-paginator oracle)

1. Add BasePaginationPlugin (createTSlatePlugin, key: KEYS.pagination) under packages/pagination/src/lib. Define a top-level section node schema mirroring DOCX w:sectPr: { type: 'section', sectPr: { pageSize, margins, columns, header?, footer? }, children: Descendant[] }. editor.children becomes Section[].
2. Add BaseSectionPlugin, BaseHeaderPlugin, BaseFooterPlugin, BasePageBreakPlugin as sibling base plugins. Header / footer are children of Section, scoped to that section. Manual page_break is a block-level void node. Compose existing packages/footnote/ plugins for the footnote sub-feature.
3. withPagination editor override (overrideEditor) enforces invariants: top level is always Section[]; non-section content gets wrapped on normalizeNode; nested sections flatten; orphan headers/footers move under their parent section.
4. Auto-paginator runs as a debounced withNormalizeNode pass: walk a section's children, call pretext.prepare() + layout() to compute cumulative height, insert page_break nodes when content exceeds pageSize.height - margins - headerHeight - footerHeight. Manual page breaks always honoured.
5. React layer: toTPlatePlugin(BaseSectionPlugin) renders each Section as a stack of fixed-size <div class="page"> between explicit page_break nodes. Header / footer render once per <div class="page">. Footnote definitions stay in document order at the section tail; footnote refs paint a marker; per-page placement of footnote bodies happens via portal driven by the auto-paginator's break positions.
6. Print mode = no React change. The same <div class="page"> elements + @media print { .page { page-break-after: always; } } produce a deterministic PDF that exactly matches on-screen pagination — pretext-derived breaks are baked into the document tree, not recomputed per print.

Acceptance: opening a 500-block document materializes correct page breaks within 200ms; editing a paragraph re-runs the auto-paginator only on its containing section within 100ms; two Yjs clients with the same editor.children see identical paginations regardless of viewport; DOCX export round-trips section properties + header / footer references with byte-stable w:sectPr.

Because the code is

• packages/core/src/lib/plugin/createSlatePlugin.ts:91-159 and :246-259 — createTSlatePlugin + overrideEditor are the canonical pair when the real ownership is editor behaviour and schema invariants.
• packages/core/src/lib/plugin/SlatePlugin.ts:56-63 and :151-163 — decorate and inject.nodeProps exist; we don't need them. This variant prefers real schema over decoration.
• packages/core/src/lib/plugin/BasePlugin.ts:213-229 (editOnly) — auto-paginator gets editOnly: { handlers: false, normalizeInitialValue: true } so static / read-only renders use last-good break positions without re-running.
• packages/table/src/lib/withTable.ts (and friends in packages/table/) — direct precedent: a complex spatial structure managed via withNormalizeNode + dedicated transforms (withInsertFragmentTable, withNormalizeTable, withDeleteTable). Sections are simpler than tables.
• packages/footnote/src/lib/BaseFootnoteDefinitionPlugin.ts (and Reference / Input) — composed, not re-authored. Footnote definitions become Section-scoped instead of document-scoped.
• packages/utils/src/lib/plate-keys.ts — KEYS.section, KEYS.header, KEYS.footer, KEYS.pageBreak, KEYS.pagination registered here.
• .claude/skills/plate-plugin-creator/SKILL.md — Slate-first hard law explicitly satisfied: this variant gives pagination real document semantics and uses React only for chrome rendering.
• Google docs - like pagination udecode/plate#4380 — OP danolekh (2025-06-19) shipped a working POC of this approach (BasePaginationPlugin with documentSettings, PageElement with explicit width / height, normalization wrapping non-page nodes); auto-flow was the single weakness, exactly the problem pretext solves.
• pretext README (commit bb224e0, 2026-04-22) — pretext as cumulative-height oracle inside withNormalizeNode is its sweet spot: arithmetic-only after prepare(), no DOM reads.

Assumptions deliberately shuffled vs variant A

Axis	Variant A (#353)	Variant B (this)
Layer	render-time overlay; pages derived	document-model; section / page_break nodes
When	every measure cycle (rAF, coalesced)	on insert / delete normalization
Granularity	per-block measurement	per-section structure
Yjs	derived per-client view; pagination diverges per viewport, doc converges	deterministic shared pagination, viewport-locked
DOCX round-trip	flat doc + section meta on top-level header / footer siblings	direct mapping to w:sectPr + w:hdrRef / w:ftrRef
Reversibility	feature-flag toggle; turning pagination off is a no-op	schema migration in both directions
editor.children shape	unchanged from non-paginated docs	top-level becomes section[]
Failure mode	over-budget repagination = visible jank, doc still correct	over-budget normalization = stale layout, doc structurally correct
Risk	pretext perf is the load-bearing primitive	break-maintenance transforms on every edit are the load-bearing primitive

Validate this approach — especially but not limited to

• Static analysis of packages/table/src/lib/withTable.ts and packages/core/src/lib/plugin/{BasePlugin.ts,SlatePlugin.ts} — confirm withNormalizeNode semantics + editOnly + overrideEditor compose cleanly for Section[] invariants without infinite normalization loops on page_break insertion.
• Review of our own code in packages/footnote/ — verify that scoping footnote definitions to a Section instead of the document tail does not break Reference linking or DOCX round-trip.
• Comparative analysis vs sibling Plate pagination plugin (headers / footers / footnotes) with pretext (variant A) #353 — name the load-bearing assumption as a single sentence in the form "If <X> matters more than <Y>, variant <A|B> wins; otherwise the other." Specifically: which matters more, deterministic shared pagination + DOCX section fidelity (favours B) or liquid editing UX + zero schema migration (favours A)? Do not pick a winner yet — name the axis.
• Stress-test withNormalizeNode cost on the hot path: measure cost of running pretext-driven height accumulation inside normalization on every insert.
• Selection / paste behaviour across Section / page_break boundaries — confirm Slate's withInsertFragment handles cross-section pastes without losing structure.

Full plan

1. New package packages/pagination/ (tsdown, bun test); add to root pnpm-workspace. Run pnpm brl after file scaffolding lands.
2. Add KEYS.pagination, KEYS.section, KEYS.header, KEYS.footer, KEYS.pageBreak to packages/utils/src/lib/plate-keys.ts.
3. src/lib/: base-pagination-plugin.ts, base-section-plugin.ts, base-header-plugin.ts, base-footer-plugin.ts, base-page-break-plugin.ts, with-pagination.ts (override + normalize), auto-paginate.ts (pretext-backed cumulative-height pass), internal/font-from-style.ts, internal/measure-cache.ts, internal/section-invariants.ts, types.ts. Helpers in internal/.
4. src/react/: pagination-plugin.ts (toTPlatePlugin), section-plugin.ts, header-plugin.ts, footer-plugin.ts, page-break-plugin.ts, page-element.tsx, section-element.tsx, header-element.tsx, footer-element.tsx, internal/use-pretext-measurer.ts.
5. Compose with packages/footnote/: PaginationPlugin = toTPlatePlugin(BasePaginationPlugin, { plugins: [SectionPlugin, HeaderPlugin, FooterPlugin, PageBreakPlugin, FootnoteDefinitionPlugin, FootnoteReferencePlugin, FootnoteInputPlugin] }).
6. Public surface: editor.api.pagination.{getSections, getPagesInSection, getPageOf, measure}; editor.tf.pagination.{insertSection, setSectionHeader, setSectionFooter, insertPageBreak, repaginateSection, repaginateAll}. Inference from createTSlatePlugin<Config>; no SlateEditor annotations.
7. Schema migration: migrateLegacyDocument(doc): SectionDocument for adopters of pre-pagination docs; called once on normalizeInitialValue.
8. Tests in packages/pagination/src/**/*.spec.ts with bun: invariant maintenance under fuzzed edits, auto-paginator break positions with golden cases, DOCX section round-trip.
9. DOCX import/export: full w:sectPr mapping; header / footer reference resolution; footnote scoping per section.
10. Changeset under .changeset/ per .agents/rules/changeset.mdc before completing.

References

• Google docs - like pagination udecode/plate#4380 (read with pretext-specific content trimmed) — OP's POC + maintainer commentary on container-node trade-offs
• packages/core/src/lib/plugin/{createSlatePlugin.ts, SlatePlugin.ts, BasePlugin.ts}
• packages/core/src/react/plugin/toPlatePlugin.ts
• packages/table/src/lib/withTable.ts and friends — closest precedent for normalize-driven structural plugin
• packages/footnote/src/lib/BaseFootnote*Plugin.ts
• .claude/skills/plate-plugin-creator/SKILL.md and rules/{creation-flow,typing,composition}.md
• pretext README and src/{layout,line-break,analysis,rich-inline}.ts at commit bb224e0

[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 #353.

Plate pagination plugin (headers / footers / footnotes) with pretext (variant A) (#353)

Similarity score: 99%

This comment was generated by Kilo Auto-Triage.

[arthrod]

🥕 Sibling variant: #353. Same goal, shuffled assumptions (document-model vs render-overlay). Please compare before recommending — the load-bearing assumption is the deliverable, not the winner.

[coderabbitai]

Coding Plan

Summary

• Follow the table plugin precedent for structural normalization, using overrideEditor with early-return patterns to enforce Section[] as the top-level document structure
• Integrate pretext as a lazy-loaded direct dependency for height measurement, running auto-pagination as a debounced pass within the normalization cycle
• Compose existing footnote plugins via configurePlugin to add section-scoping without forking the footnote package
• Implement DOCX round-trip by extending the existing export pipeline's w:sectPr generation and adding a pre-Mammoth XML extraction step for import

Design Choices

Design Choice 1: Pretext Dependency Strategy

Options Considered:

1. Direct dependency in @platejs/pagination with lazy initialization
2. Peer dependency requiring consumers to install separately
3. Abstract measurement interface with pretext as the default implementation

Chosen Option: 1

Rationale: Option 1: Direct dependency with lazy initialization—pretext is MIT/ESM and small; lazy loading avoids startup cost for editors that don't enable pagination.

Design Choice 2: Footnote Section Scoping Approach

Options Considered:

1. Extend existing footnote registry with an optional section scope parameter
2. Fork/wrap the footnote plugins entirely within pagination package
3. Use configurePlugin to inject section-awareness into composed footnote plugins

Chosen Option: 3

Rationale: Option 3: Use configurePlugin to extend footnote behavior within the pagination plugin composition—this follows the established pattern (like table composing cell plugins) without modifying the core footnote package.

Design Choice 3: Auto vs Manual Page Break Distinction

Options Considered:

1. Single page_break node type with a manual: boolean property
2. Two distinct node types: page_break (manual) and auto_break (computed)
3. Single node type; auto-breaks are inserted/removed by normalizer, indistinguishable from manual

Chosen Option: 1

Rationale: Option 1: Single page_break node with manual property—allows the normalizer to preserve user-inserted breaks while freely managing computed ones, and simplifies the node type system.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Package Foundation

Establish the pagination package scaffolding, register new node keys, and define the core type system that all subsequent phases depend on.

Task 1: Scaffold Package Structure

Create the pagination package with standard Plate conventions for a dual-layer (lib + react) plugin.

• Create packages/pagination/ directory with src/lib/, src/react/, and src/internal/ subdirectories
• Add package.json with @platejs/pagination name, dual exports (. → lib, ./react → react), peer deps on platejs >=53.0.0, react >=18.0.0, and direct dep on pretext ^0.0.6
• Add tsconfig.json and tsconfig.build.json extending tooling base configs
• Workspace is auto-registered via pnpm-workspace.yaml glob pattern

Task 2: Register Node Keys

Add pagination-related keys to the central KEYS registry.

• Update packages/utils/src/lib/plate-keys.ts to add KEYS.pagination, KEYS.section, KEYS.header, KEYS.footer, KEYS.pageBreak
• Follow existing naming patterns (camelCase keys, snake_case or lowercase values as appropriate)

Task 3: Define Core Types

Establish the TypeScript interfaces for section properties, page configuration, and plugin options.

• Create packages/pagination/src/lib/types.ts defining:
  • SectPr interface mirroring DOCX section properties (pageSize, margins, columns, orientation)
  • SectionElement extending TElement with sectPr and optional header/footer children
  • HeaderElement and FooterElement types (block elements, section-scoped)
  • PageBreakElement with manual?: boolean property
  • PaginationConfig plugin config type with options for default page size, margins, auto-pagination debounce

🤖 Prompt for AI agents

Scaffold the `@platejs/pagination` package foundation, including directory
structure, package configuration, node key registration, and core TypeScript
types.

- Create `packages/pagination/` with subdirectories `src/lib/`, `src/react/`,
and `src/internal/`
- Add `package.json` named `@platejs/pagination` with:
  - Dual exports: `.` → lib, `./react` → react
  - Peer deps: `platejs >=53.0.0`, `react >=18.0.0`
  - Direct dep: `pretext ^0.0.6`
- Add `tsconfig.json` and `tsconfig.build.json` extending tooling base configs
- Update `packages/utils/src/lib/plate-keys.ts` to add: `KEYS.pagination`,
`KEYS.section`, `KEYS.header`, `KEYS.footer`, `KEYS.pageBreak` using existing
naming conventions (camelCase keys)
- Create `packages/pagination/src/lib/types.ts` with:
- `SectPr` interface (pageSize, margins, columns, orientation — mirroring DOCX
section properties)
- `SectionElement` extending `TElement` with `sectPr` and optional header/footer
children
  - `HeaderElement` and `FooterElement` types as block elements
  - `PageBreakElement` with `manual?: boolean` property
- `PaginationConfig` plugin config type with options for default page size,
margins, and auto-pagination debounce

Phase 2: Core Plugins & Structural Normalization

Implement the base Slate plugins for all pagination node types and the withPagination editor override that enforces the Section[] top-level invariant.

Task 1: Implement BaseSectionPlugin

Define the section container as the top-level document structure.

• Create packages/pagination/src/lib/BaseSectionPlugin.ts using createTSlatePlugin
• Node config: isElement: true, type from KEYS.section
• Default sectPr in options with A4 dimensions (595×842 pt), standard margins
• No inline, no void—sections are structural containers

Task 2: Implement BaseHeaderPlugin and BaseFooterPlugin

Define header and footer as section-scoped block elements.

• Create packages/pagination/src/lib/BaseHeaderPlugin.ts and BaseFooterPlugin.ts
• Node config: isElement: true, types from KEYS.header / KEYS.footer
• These are block elements that must be direct children of a section
• Add rules.normalize.removeEmpty: false—empty headers/footers should persist

Task 3: Implement BasePageBreakPlugin

Define the page break as a void block element.

• Create packages/pagination/src/lib/BasePageBreakPlugin.ts
• Node config: isElement: true, isVoid: true, type from KEYS.pageBreak
• Schema allows manual?: boolean property to distinguish user-inserted from auto-generated breaks

Task 4: Implement withPagination Normalization

Create the editor override that enforces section structure invariants.

• Create packages/pagination/src/lib/withPagination.ts as an OverrideEditor<PaginationConfig> function
• Override normalizeNode following the table plugin early-return pattern:
  • If root has non-section children → wrap them in a default section, return
  • If section is nested inside another section → unwrap inner section, return
  • If header/footer is not direct child of section → move to nearest ancestor section or wrap in section, return
  • If section has no content children (only header/footer) → insert empty paragraph, return
• Always fall through to normalizeNode([n, path]) at end to chain properly

Task 5: Implement Section Transforms and API

Add the public transform and query functions for section manipulation.

• Extend BaseSectionPlugin with .extendEditorApi() to add:
  • editor.api.pagination.getSections()
  • editor.api.pagination.getPageOf(path)
  • editor.api.pagination.measure(node) (stub for pretext integration)
• Extend with .extendEditorTransforms() to add:
  • editor.tf.pagination.insertSection(options)
  • editor.tf.pagination.setSectionHeader(sectionPath, header)
  • editor.tf.pagination.setSectionFooter(sectionPath, footer)
• Add editor.tf.insert.pageBreak({ manual: true }) transform for manual breaks

Task 6: Compose BasePaginationPlugin

Bundle all base plugins into the main pagination plugin.

• Create packages/pagination/src/lib/BasePaginationPlugin.ts
• Use createTSlatePlugin with key: KEYS.pagination
• Set plugins: [BaseSectionPlugin, BaseHeaderPlugin, BaseFooterPlugin, BasePageBreakPlugin]
• Apply .overrideEditor(withPagination) for structural normalization
• Set editOnly: { normalizeInitialValue: true } so read-only mode uses last-good pagination

🤖 Prompt for AI agents

Implement the core base Slate plugins for all pagination node types and the
`withPagination` editor override that enforces structural invariants.

**BaseSectionPlugin** (`packages/pagination/src/lib/BaseSectionPlugin.ts`):
- Use `createTSlatePlugin`, `isElement: true`, type from `KEYS.section`
- Default `sectPr` in options: A4 dimensions (595×842 pt), standard margins
- Not inline, not void
- Extend with `.extendEditorApi()` for: `editor.api.pagination.getSections()`,
`editor.api.pagination.getPageOf(path)`, `editor.api.pagination.measure(node)`
(stub)
- Extend with `.extendEditorTransforms()` for:
`editor.tf.pagination.insertSection(options)`,
`editor.tf.pagination.setSectionHeader(sectionPath, header)`,
`editor.tf.pagination.setSectionFooter(sectionPath, footer)`
- Add `editor.tf.insert.pageBreak({ manual: true })` transform

**BaseHeaderPlugin** (`packages/pagination/src/lib/BaseHeaderPlugin.ts`) and
**BaseFooterPlugin** (`packages/pagination/src/lib/BaseFooterPlugin.ts`):
- `isElement: true`, types from `KEYS.header` / `KEYS.footer`
- Direct children of section only
- `rules.normalize.removeEmpty: false` — empty headers/footers must persist

**BasePageBreakPlugin** (`packages/pagination/src/lib/BasePageBreakPlugin.ts`):
- `isElement: true`, `isVoid: true`, type from `KEYS.pageBreak`
- Schema includes `manual?: boolean` property

**withPagination** (`packages/pagination/src/lib/withPagination.ts`):
- `OverrideEditor<PaginationConfig>` function, overrides `normalizeNode` with
early-return pattern (following table plugin precedent):
  1. Root has non-section children → wrap in default section, return
  2. Section nested inside another section → unwrap inner section, return
3. Header/footer not a direct child of section → move to nearest ancestor
section or wrap in section, return
4. Section has no content children (only header/footer) → insert empty
paragraph, return
- Always fall through to `normalizeNode([n, path])` to chain properly

**BasePaginationPlugin**
(`packages/pagination/src/lib/BasePaginationPlugin.ts`):
- `createTSlatePlugin` with `key: KEYS.pagination`
- `plugins: [BaseSectionPlugin, BaseHeaderPlugin, BaseFooterPlugin,
BasePageBreakPlugin]`
- Apply `.overrideEditor(withPagination)`
- `editOnly: { normalizeInitialValue: true }`

Phase 3: Auto-Pagination Engine

Implement the pretext-backed height measurement and automatic page break insertion system.

Task 1: Create Pretext Measurement Infrastructure

Set up the measurement cache and font extraction utilities for pretext integration.

• Create packages/pagination/src/internal/measure-cache.ts with a WeakMap-based cache for measured node heights
• Create packages/pagination/src/internal/font-from-style.ts to extract font family, size, weight from element styles for pretext's prepare() call
• Create packages/pagination/src/internal/pretext-measurer.ts that wraps pretext's prepare() + layout() API with Plate-friendly interfaces

Task 2: Implement Auto-Pagination Algorithm

Create the height accumulation logic that determines where page breaks should be inserted.

• Create packages/pagination/src/lib/auto-paginate.ts containing:
  • computePageBreaks(section, measurer): walks section children, accumulates heights via pretext, returns paths where breaks should exist
  • reconcilePageBreaks(editor, sectionPath, computedBreaks): compares computed break positions against existing page_break nodes, inserts/removes as needed (preserving manual breaks)
• Algorithm respects: pageSize.height - margins.top - margins.bottom - headerHeight - footerHeight as available content height

Task 3: Integrate Auto-Pagination into Normalization

Wire the auto-paginator into the normalization cycle with appropriate debouncing.

• Extend withPagination.ts to add a debounced auto-pagination pass after structural invariants are satisfied
• Use editor.tf.withoutNormalizing() when inserting/removing auto-breaks to batch the changes
• Track dirty sections (via apply override or options store) to only re-paginate affected sections, not entire document
• Add editor.tf.pagination.repaginateSection(path) and editor.tf.pagination.repaginateAll() for manual trigger

Task 4: Implement Pagination API Queries

Complete the query API for pagination state inspection.

• Implement editor.api.pagination.getPagesInSection(sectionPath): returns array of path ranges between page breaks
• Implement editor.api.pagination.getPageOf(path): returns the page index and section for a given content path
• Implement editor.api.pagination.measure(node): returns cached or freshly computed height for a node

🤖 Prompt for AI agents

Implement the pretext-backed height measurement infrastructure and the
auto-pagination engine, wired into the normalization cycle.

**Measurement Infrastructure** (in `packages/pagination/src/internal/`):
- `measure-cache.ts`: WeakMap-based cache for measured node heights
- `font-from-style.ts`: extracts font family, size, and weight from element
styles for pretext's `prepare()` call
- `pretext-measurer.ts`: wraps pretext's `prepare()` + `layout()` API with
Plate-friendly interfaces; pretext is lazy-loaded to avoid startup cost

**Auto-Pagination Algorithm** (`packages/pagination/src/lib/auto-paginate.ts`):
- `computePageBreaks(section, measurer)`: walks section children, accumulates
heights via pretext, returns paths where breaks should exist
- `reconcilePageBreaks(editor, sectionPath, computedBreaks)`: compares computed
break positions against existing `page_break` nodes; inserts/removes auto breaks
as needed while preserving any node with `manual: true`
- Available height formula: `pageSize.height - margins.top - margins.bottom -
headerHeight - footerHeight`

**Integration into `withPagination.ts`**:
- Add a debounced auto-pagination pass that runs after all structural invariants
are satisfied
- Use `editor.tf.withoutNormalizing()` when inserting/removing auto-breaks to
batch changes
- Track dirty sections (via `apply` override or options store) to scope
re-pagination to affected sections only
- Add transforms: `editor.tf.pagination.repaginateSection(path)` and
`editor.tf.pagination.repaginateAll()`

**Complete Pagination API Queries** (extend editor API):
- `editor.api.pagination.getPagesInSection(sectionPath)`: returns array of path
ranges between page breaks
- `editor.api.pagination.getPageOf(path)`: returns page index and section for a
given content path
- `editor.api.pagination.measure(node)`: returns cached or freshly computed
height using the measurement infrastructure

Phase 4: React Layer & Footnote Integration

Elevate base plugins to React with element components and integrate section-scoped footnotes.

Task 1: Create React Element Components

Implement the visual rendering components for pagination elements.

• Create packages/pagination/src/react/components/SectionElement.tsx: renders section as a stack of <div className="plate-page"> elements split by page breaks
• Create packages/pagination/src/react/components/HeaderElement.tsx and FooterElement.tsx: render within each page div at top/bottom
• Create packages/pagination/src/react/components/PageBreakElement.tsx: renders as a visual page separator (dashed line or similar)
• Add print CSS: @media print { .plate-page { page-break-after: always; } }

Task 2: Create React Plugins

Elevate base plugins to React with component bindings.

• Create packages/pagination/src/react/SectionPlugin.tsx via toTPlatePlugin(BaseSectionPlugin, { render: { node: SectionElement } })
• Create packages/pagination/src/react/HeaderPlugin.tsx, FooterPlugin.tsx, PageBreakPlugin.tsx similarly
• Create packages/pagination/src/react/PaginationPlugin.tsx composing all React plugins

Task 3: Integrate Section-Scoped Footnotes

Configure the existing footnote plugins to work within section boundaries.

• Import FootnoteDefinitionPlugin, FootnoteReferencePlugin, FootnoteInputPlugin from @platejs/footnote
• Use configurePlugin on footnote plugins within PaginationPlugin to inject section-scoping behavior:
  • Override footnote definition queries to search within containing section, not entire document
  • Override createFootnoteDefinition transform to insert at section tail, not document tail
  • Override getNextFootnoteIdentifier to scope numbering per section

Task 4: Implement Footnote Per-Page Placement

Add the portal-based rendering for footnote bodies at page bottoms.

• Create packages/pagination/src/react/hooks/usePageFootnotes.ts: given a page's path range, finds footnote references and resolves their definitions
• Modify SectionElement.tsx to render footnote definitions at the bottom of each page div via portals, ordered by first reference appearance on that page
• Footnote definitions in the document model stay at section tail; visual placement is render-time only

🤖 Prompt for AI agents

Implement the React layer for all pagination elements and integrate
section-scoped footnotes.

**React Element Components** (in `packages/pagination/src/react/components/`):
- `SectionElement.tsx`: renders the section as a stack of `<div
className="plate-page">` elements, split at page breaks
- `HeaderElement.tsx` and `FooterElement.tsx`: render within each page div at
top/bottom
- `PageBreakElement.tsx`: renders as a visual page separator (e.g., dashed line)
- Add print CSS: `@media print { .plate-page { page-break-after: always; } }`

**React Plugins** (in `packages/pagination/src/react/`):
- `SectionPlugin.tsx`: `toTPlatePlugin(BaseSectionPlugin, { render: { node:
SectionElement } })`
- `HeaderPlugin.tsx`, `FooterPlugin.tsx`, `PageBreakPlugin.tsx`: follow same
pattern
- `PaginationPlugin.tsx`: compose all React plugins

**Section-Scoped Footnote Integration** (in `PaginationPlugin.tsx`):
- Import `FootnoteDefinitionPlugin`, `FootnoteReferencePlugin`,
`FootnoteInputPlugin` from `@platejs/footnote`
- Use `configurePlugin` to inject section-scoping into each footnote plugin:
- Override footnote definition queries to search within the containing section
only
- Override `createFootnoteDefinition` to insert at section tail (not document
tail)
  - Override `getNextFootnoteIdentifier` to scope numbering per section

**Footnote Per-Page Placement**:
- Create `packages/pagination/src/react/hooks/usePageFootnotes.ts`: given a
page's path range, finds footnote references and resolves their definitions
- Update `SectionElement.tsx` to render footnote definitions at the bottom of
each page div via portals, ordered by first reference appearance on that page
- Footnote definitions stay at section tail in the document model; visual
placement is render-time only

Phase 5: DOCX Round-Trip & Finalization

Implement DOCX import/export for section properties and complete the package with migration utilities and tests.

Task 1: Implement DOCX Export for Sections

Extend DOCX export to properly serialize section structure.

• Extend packages/docx-io (or add integration in pagination package) to:
  • Recognize section nodes and emit w:sectPr with page size, margins, orientation from sectPr properties
  • Emit w:headerReference / w:footerReference when section has header/footer children
  • Generate word/header{N}.xml and word/footer{N}.xml files for each section's header/footer content
• Page breaks export as <w:p><w:r><w:br w:type="page"/></w:r></w:p>

Task 2: Implement DOCX Import for Sections

Add section property parsing to DOCX import pipeline.

• This requires bypassing or extending Mammoth (which strips w:sectPr)
• Option: Post-process the original DOCX XML before Mammoth conversion to extract section metadata, then inject section nodes into deserialized content
• Parse w:sectPr for page size, margins; parse w:headerReference/w:footerReference relationship IDs to extract header/footer content from their XML files
• Wrap imported content in section nodes with reconstructed sectPr

Task 3: Implement Legacy Document Migration

Create the migration utility for non-section documents.

• Create packages/pagination/src/lib/migrateLegacyDocument.ts
• Function migrateLegacyDocument(children: Descendant[]): SectionElement[]: wraps all content in a default section with standard A4 sectPr
• Wire into BasePaginationPlugin.normalizeInitialValue: detect if document lacks section structure, run migration once

Task 4: Add Tests and Changeset

Complete the package with comprehensive tests and release documentation.

• Create test files in packages/pagination/src/**/*.spec.ts:
  • Invariant tests: non-section content gets wrapped, nested sections flatten, orphan headers re-parent
  • Auto-pagination tests: golden cases with known content heights and expected break positions
  • Cross-section paste tests: verify insertFragment behavior across section boundaries
  • DOCX round-trip tests: export then re-import preserves section structure
• Add changeset under .changeset/ with patch for new package, describing the new pagination feature

🤖 Prompt for AI agents

Implement DOCX round-trip support for sections, the legacy document migration
utility, and finalize the package with tests and a changeset.

**DOCX Export** (extend `packages/docx-io` or add integration in pagination
package):
- Recognize `section` nodes and emit `w:sectPr` with page size, margins, and
orientation from `sectPr` properties
- Emit `w:headerReference` / `w:footerReference` when the section has
header/footer children
- Generate `word/header{N}.xml` and `word/footer{N}.xml` for each section's
header/footer content
- Page breaks export as `<w:p><w:r><w:br w:type="page"/></w:r></w:p>`

**DOCX Import** (extend `packages/docx-io` import pipeline):
- Mammoth strips `w:sectPr`, so pre-process the original DOCX XML before Mammoth
conversion to extract section metadata
- Parse `w:sectPr` for page size and margins; resolve
`w:headerReference`/`w:footerReference` relationship IDs to extract
header/footer XML
- After Mammoth conversion, inject `section` nodes with reconstructed `sectPr`
and header/footer children

**Legacy Document Migration**
(`packages/pagination/src/lib/migrateLegacyDocument.ts`):
- Export function `migrateLegacyDocument(children: Descendant[]):
SectionElement[]` that wraps all content in a default section with standard A4
`sectPr`
- Wire into `BasePaginationPlugin.normalizeInitialValue`: detect if document
lacks section structure, run migration once

**Tests** (`packages/pagination/src/**/*.spec.ts`):
- Invariant tests: non-section content gets wrapped, nested sections flatten,
orphan headers re-parent
- Auto-pagination tests: golden cases with known content heights and expected
break positions
- Cross-section paste tests: verify `insertFragment` behavior across section
boundaries
- DOCX round-trip tests: export then re-import preserves section structure

**Changeset**: add `.changeset/` entry with `patch` for the new
`@platejs/pagination` package describing the new pagination feature

Research

The Plate codebase follows a Slate-first plugin architecture where base plugins are defined in packages/*/src/lib/ using createTSlatePlugin, then elevated to React plugins via toTPlatePlugin in packages/*/src/react/. The table plugin (packages/table/) serves as the closest precedent for complex structural normalization—it uses withNormalizeTable with early-return patterns to enforce invariants and composes multiple OverrideEditor functions via object spreading. The footnote plugin (packages/footnote/) uses a document-wide registry keyed by string identifiers, currently with no section scoping. DOCX export (packages/docx-io/) already generates w:sectPr with page size, margins, and header/footer references from DocumentOptions, but import strips all section properties via Mammoth's HTML conversion.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Scaffold the `@platejs/pagination` package foundation, including directory
structure, package configuration, node key registration, and core TypeScript
types.

- Create `packages/pagination/` with subdirectories `src/lib/`, `src/react/`,
and `src/internal/`
- Add `package.json` named `@platejs/pagination` with:
  - Dual exports: `.` → lib, `./react` → react
  - Peer deps: `platejs >=53.0.0`, `react >=18.0.0`
  - Direct dep: `pretext ^0.0.6`
- Add `tsconfig.json` and `tsconfig.build.json` extending tooling base configs
- Update `packages/utils/src/lib/plate-keys.ts` to add: `KEYS.pagination`,
`KEYS.section`, `KEYS.header`, `KEYS.footer`, `KEYS.pageBreak` using existing
naming conventions (camelCase keys)
- Create `packages/pagination/src/lib/types.ts` with:
- `SectPr` interface (pageSize, margins, columns, orientation — mirroring DOCX
section properties)
- `SectionElement` extending `TElement` with `sectPr` and optional header/footer
children
  - `HeaderElement` and `FooterElement` types as block elements
  - `PageBreakElement` with `manual?: boolean` property
- `PaginationConfig` plugin config type with options for default page size,
margins, and auto-pagination debounce
===============================================================================

Task: 2

Implement the core base Slate plugins for all pagination node types and the
`withPagination` editor override that enforces structural invariants.

**BaseSectionPlugin** (`packages/pagination/src/lib/BaseSectionPlugin.ts`):
- Use `createTSlatePlugin`, `isElement: true`, type from `KEYS.section`
- Default `sectPr` in options: A4 dimensions (595×842 pt), standard margins
- Not inline, not void
- Extend with `.extendEditorApi()` for: `editor.api.pagination.getSections()`,
`editor.api.pagination.getPageOf(path)`, `editor.api.pagination.measure(node)`
(stub)
- Extend with `.extendEditorTransforms()` for:
`editor.tf.pagination.insertSection(options)`,
`editor.tf.pagination.setSectionHeader(sectionPath, header)`,
`editor.tf.pagination.setSectionFooter(sectionPath, footer)`
- Add `editor.tf.insert.pageBreak({ manual: true })` transform

**BaseHeaderPlugin** (`packages/pagination/src/lib/BaseHeaderPlugin.ts`) and
**BaseFooterPlugin** (`packages/pagination/src/lib/BaseFooterPlugin.ts`):
- `isElement: true`, types from `KEYS.header` / `KEYS.footer`
- Direct children of section only
- `rules.normalize.removeEmpty: false` — empty headers/footers must persist

**BasePageBreakPlugin** (`packages/pagination/src/lib/BasePageBreakPlugin.ts`):
- `isElement: true`, `isVoid: true`, type from `KEYS.pageBreak`
- Schema includes `manual?: boolean` property

**withPagination** (`packages/pagination/src/lib/withPagination.ts`):
- `OverrideEditor<PaginationConfig>` function, overrides `normalizeNode` with
early-return pattern (following table plugin precedent):
  1. Root has non-section children → wrap in default section, return
  2. Section nested inside another section → unwrap inner section, return
3. Header/footer not a direct child of section → move to nearest ancestor
section or wrap in section, return
4. Section has no content children (only header/footer) → insert empty
paragraph, return
- Always fall through to `normalizeNode([n, path])` to chain properly

**BasePaginationPlugin**
(`packages/pagination/src/lib/BasePaginationPlugin.ts`):
- `createTSlatePlugin` with `key: KEYS.pagination`
- `plugins: [BaseSectionPlugin, BaseHeaderPlugin, BaseFooterPlugin,
BasePageBreakPlugin]`
- Apply `.overrideEditor(withPagination)`
- `editOnly: { normalizeInitialValue: true }`
===============================================================================

Task: 3

Implement the pretext-backed height measurement infrastructure and the
auto-pagination engine, wired into the normalization cycle.

**Measurement Infrastructure** (in `packages/pagination/src/internal/`):
- `measure-cache.ts`: WeakMap-based cache for measured node heights
- `font-from-style.ts`: extracts font family, size, and weight from element
styles for pretext's `prepare()` call
- `pretext-measurer.ts`: wraps pretext's `prepare()` + `layout()` API with
Plate-friendly interfaces; pretext is lazy-loaded to avoid startup cost

**Auto-Pagination Algorithm** (`packages/pagination/src/lib/auto-paginate.ts`):
- `computePageBreaks(section, measurer)`: walks section children, accumulates
heights via pretext, returns paths where breaks should exist
- `reconcilePageBreaks(editor, sectionPath, computedBreaks)`: compares computed
break positions against existing `page_break` nodes; inserts/removes auto breaks
as needed while preserving any node with `manual: true`
- Available height formula: `pageSize.height - margins.top - margins.bottom -
headerHeight - footerHeight`

**Integration into `withPagination.ts`**:
- Add a debounced auto-pagination pass that runs after all structural invariants
are satisfied
- Use `editor.tf.withoutNormalizing()` when inserting/removing auto-breaks to
batch changes
- Track dirty sections (via `apply` override or options store) to scope
re-pagination to affected sections only
- Add transforms: `editor.tf.pagination.repaginateSection(path)` and
`editor.tf.pagination.repaginateAll()`

**Complete Pagination API Queries** (extend editor API):
- `editor.api.pagination.getPagesInSection(sectionPath)`: returns array of path
ranges between page breaks
- `editor.api.pagination.getPageOf(path)`: returns page index and section for a
given content path
- `editor.api.pagination.measure(node)`: returns cached or freshly computed
height using the measurement infrastructure
===============================================================================

Task: 4

Implement the React layer for all pagination elements and integrate
section-scoped footnotes.

**React Element Components** (in `packages/pagination/src/react/components/`):
- `SectionElement.tsx`: renders the section as a stack of `<div
className="plate-page">` elements, split at page breaks
- `HeaderElement.tsx` and `FooterElement.tsx`: render within each page div at
top/bottom
- `PageBreakElement.tsx`: renders as a visual page separator (e.g., dashed line)
- Add print CSS: `@media print { .plate-page { page-break-after: always; } }`

**React Plugins** (in `packages/pagination/src/react/`):
- `SectionPlugin.tsx`: `toTPlatePlugin(BaseSectionPlugin, { render: { node:
SectionElement } })`
- `HeaderPlugin.tsx`, `FooterPlugin.tsx`, `PageBreakPlugin.tsx`: follow same
pattern
- `PaginationPlugin.tsx`: compose all React plugins

**Section-Scoped Footnote Integration** (in `PaginationPlugin.tsx`):
- Import `FootnoteDefinitionPlugin`, `FootnoteReferencePlugin`,
`FootnoteInputPlugin` from `@platejs/footnote`
- Use `configurePlugin` to inject section-scoping into each footnote plugin:
- Override footnote definition queries to search within the containing section
only
- Override `createFootnoteDefinition` to insert at section tail (not document
tail)
  - Override `getNextFootnoteIdentifier` to scope numbering per section

**Footnote Per-Page Placement**:
- Create `packages/pagination/src/react/hooks/usePageFootnotes.ts`: given a
page's path range, finds footnote references and resolves their definitions
- Update `SectionElement.tsx` to render footnote definitions at the bottom of
each page div via portals, ordered by first reference appearance on that page
- Footnote definitions stay at section tail in the document model; visual
placement is render-time only
===============================================================================

Task: 5

Implement DOCX round-trip support for sections, the legacy document migration
utility, and finalize the package with tests and a changeset.

**DOCX Export** (extend `packages/docx-io` or add integration in pagination
package):
- Recognize `section` nodes and emit `w:sectPr` with page size, margins, and
orientation from `sectPr` properties
- Emit `w:headerReference` / `w:footerReference` when the section has
header/footer children
- Generate `word/header{N}.xml` and `word/footer{N}.xml` for each section's
header/footer content
- Page breaks export as `<w:p><w:r><w:br w:type="page"/></w:r></w:p>`

**DOCX Import** (extend `packages/docx-io` import pipeline):
- Mammoth strips `w:sectPr`, so pre-process the original DOCX XML before Mammoth
conversion to extract section metadata
- Parse `w:sectPr` for page size and margins; resolve
`w:headerReference`/`w:footerReference` relationship IDs to extract
header/footer XML
- After Mammoth conversion, inject `section` nodes with reconstructed `sectPr`
and header/footer children

**Legacy Document Migration**
(`packages/pagination/src/lib/migrateLegacyDocument.ts`):
- Export function `migrateLegacyDocument(children: Descendant[]):
SectionElement[]` that wraps all content in a default section with standard A4
`sectPr`
- Wire into `BasePaginationPlugin.normalizeInitialValue`: detect if document
lacks section structure, run migration once

**Tests** (`packages/pagination/src/**/*.spec.ts`):
- Invariant tests: non-section content gets wrapped, nested sections flatten,
orphan headers re-parent
- Auto-pagination tests: golden cases with known content heights and expected
break positions
- Cross-section paste tests: verify `insertFragment` behavior across section
boundaries
- DOCX round-trip tests: export then re-import preserves section structure

**Changeset**: add `.changeset/` entry with `patch` for the new
`@platejs/pagination` package describing the new pagination feature

💡 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]

🔗 Related PRs

#16 - Add DOCX export feature with Slate plugin and UI components [merged]
#97 - Revert staging to ebf750c [merged]
#126 - feat: DOCX tracked changes and comments export [merged]
#166 - Migrate to pnpm and introduce @plate/sConsolidate skill definitions and reorganize agent configurationipts package [merged]
#170 - Cr [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!