Plate pagination plugin — consolidated plan (variant A, pretext-backed, Word-faithful)

[arthrod]

@coderabbitai plan

🥕 Plate @platejs/pagination — consolidated plan (variant A, pretext-backed)

This supersedes #353 / #354 plan churn. New baseline pinned by interactive design review with the maintainer; CR is asked to plan from scratch against this brief, not to extend the older plans.

Goal

Ship a Plate plugin (@platejs/pagination) that delivers print-grade pagination — fixed-size pages (A4 default) with per-page headers, footers, footnotes — using chenglou/pretext (height oracle, MIT, ESM) for line-break + height math, with editor-faithful Word semantics (<w:sectPr> style metadata, separate header*.xml style H/F parts).

Architecture (locked)

#	Topic	Decision
1	Standard-mode footer	Hybrid: anchored to end of content; pinned to viewport bottom when doc is shorter than viewport
2	Mode + size	Single toolbar dropdown: Standard / A4 / Letter / Legal / Custom…. Custom opens dialog.
3	Margins	Word-style preset submenu + Custom dialog (4 inputs, unit selector in/cm/mm/px). Paged view also exposes drag handles on margin lines.
4	H/F variation	Word 6-slot model. Two toggles: Different first page, Different odd & even. Editable slots: header / header-first / header-even / footer / footer-first / footer-even.
5	Dynamic fields	Plate inline-void nodes: pageNumber, pageCount, date. Inserted via "Insert field" menu in H/F editor. Resolved at paint time per page.
6	Footnotes (standard)	End-of-document endnotes (renders before the hybrid footer).
6b	Footnotes (paged)	Per-page footer well via portal (existing variant-A spec).
7	Persistence	Sibling node. Single section-properties void at end of editor.children carrying { pageSize, margins, differentFirstPage, differentOddEven }. H/F content as separate top-level sibling nodes. Body = everything else; paginate() filters non-body siblings. Word-faithful: <w:sectPr> end-of-body + separate header*.xml.
8	Font for pretext	Per-block DOM scrape: editor.api.toDOMNode(block) → getComputedStyle(el).font. system-ui → Inter snap client-side. Cache key (node.id, marksFingerprint, font, width), rAF-coalesced.
9	Manual page break	Cmd/Ctrl+Enter + /page break slash menu. Inserts { type: 'page-break' } void. Labeled rule in standard mode, hard split in paged.
10	UI distribution	Plugin = base + react in @platejs/pagination. Toolbar dropdown + dialogs ship as a registry kit (Plate convention), not built into the package.
11	Print path	Paged mode renders real <section class="page"> DOM (the <PrintPagination> component) for both on-screen-paged and @media print. No overlay path on screen. One render for both.

Word's data model — what we're matching

<w:body>
  <w:p>…paragraph…</w:p>          ← body content
  …
  <w:sectPr>                       ← section properties (NOT a page node)
    <w:pgSz w:w=… w:h=…/>          ← page size
    <w:pgMar …/>                   ← margins
    <w:hdrRef w:type="default|first|even" r:id=…/>
    <w:ftrRef w:type="default|first|even" r:id=…/>
    <w:titlePg/>                   ← differentFirstPage
  </w:sectPr>
</w:body>
+ separate header1.xml, footer1.xml, … parts (referenced by id)

Pages are never in DOCX XML — they're a layout-engine output. Variant A's "no page nodes ever in editor.children" matches Word exactly. section-properties and H/F siblings are metadata + separate parts, not pages.

Editor.children shape

editor.children = [
  // body content (any normal Plate blocks):
  { type: 'p', children: [...] },
  { type: 'h1', children: [...] },
  { type: 'page-break' },           // manual hard break (void)
  ...

  // — siblings, filtered out of paginate() body input —
  { type: 'header',         children: [...] },                    // default
  { type: 'header-first',   children: [...] },                    // optional
  { type: 'header-even',    children: [...] },                    // optional
  { type: 'footer',         children: [...] },
  { type: 'footer-first',   children: [...] },
  { type: 'footer-even',    children: [...] },
  { type: 'footnoteDefinition', children: [...] }, ...            // existing plugin
  { type: 'section-properties',                                   // void
    pageSize: 'A4', margins: { top, right, bottom, left },
    differentFirstPage: true, differentOddEven: false },
]

What changes on codex/pagination-variant-a (it claims pretext, ships none)

Critical fixes:

1. Add pretext to packages/pagination/package.json dependencies.
2. Rewrite packages/pagination/src/react/use-pretext-measurer.ts — replace canvas+char-width estimator with real pretext.prepare() per (node.id, marksFingerprint, font, width) and pretext.layout(width) per cycle. Use prepareRichInline for blocks with mixed marks.
3. packages/pagination/src/react/internal/use-page-layout.ts:47 — replace ctx: { font: '', marksFingerprint: '', width } with per-block scraped values; build marksFingerprint per block via existing internal/marks-fingerprint.ts.
4. Wrap recompute in a requestAnimationFrame coalescer.
5. system-ui → Inter snap inside the per-block scrape.

New surface (not yet on the branch):
6. BaseSectionPropertiesPlugin — void node, end of editor.children, carries pageSize/margins/toggles. paginate() skips it.
7. BaseHeaderPlugin / BaseFooterPlugin — variant: 'default' | 'first' | 'even'. Six possible top-level sibling nodes.
8. BasePageNumberPlugin, BasePageCountPlugin, BaseDatePlugin — inline-void plugins, render value from page context at paint time.
9. BasePageBreakPlugin — Cmd/Ctrl+Enter keybinding + slash registration.
10. <PrintPagination> (paged on-screen + print) — real <section class="page"> per page + @media print { .page { page-break-after: always } }. Single render path.
11. <StandardLayout> (standard mode) — IntersectionObserver-driven hybrid footer; renders endnotes between last block and the hybrid footer.
12. <MarginDragHandles> — overlay in paged view, updates section-properties options.
13. <PaginationDropdown> — toolbar component owning mode + size + margins UX (presets, Custom dialog, two H/F toggles). Ships in registry kit, not the npm package.

Deferred to v2

• Per-section variation (multiple <w:sectPr> in one doc).
• Mirrored margins / gutter / binding offset.
• DOCX import/export adapter (data shapes are designed to round-trip; adapter is a separate ticket).
• Yjs deterministic acceptance test (sibling-node persistence makes Yjs work for free; just needs an explicit test).

Acceptance

• 500-block doc edits at ≥55fps with pagination on (rAF-coalesced pretext layout).
• Resizing the viewport repaginates within one frame.
• Print preview matches paged-on-screen page boundaries within ±1 line.
• Yjs co-edit produces identical pagination across clients (sibling-node persistence ⇒ deterministic, unlike the original variant-A "per-viewport" framing — see the architecture-locked persistence row).

References

• Google docs - like pagination udecode/plate#4380 — maintainer's preferred direction (no container nodes).
• pretext README @ bb224e0 — height oracle only, doesn't paginate.
• Issue Plate pagination plugin (headers / footers / footnotes) with pretext (variant A) #353 / Plate pagination plugin (headers / footers / footnotes) with pretext (variant B) #354 — earlier variant A / variant B framings (superseded by this plan).
• packages/core/src/lib/plugin/{createSlatePlugin,SlatePlugin,BasePlugin}.ts
• packages/footnote/src/lib/BaseFootnote*Plugin.ts
• .claude/skills/plate-plugin-creator/SKILL.md

---

@coderabbitai please plan from scratch against this brief (don't extend #353 / #354 plans). Implementation is starting in parallel — we're not waiting on the plan, but a fresh plan is welcome for cross-check.

[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: 96%

This comment was generated by Kilo Auto-Triage.

[coderabbitai]

Coding Plan

Summary

• Replace canvas-based measurement with @chenglou/pretext for accurate line-break and height calculation, using per-block DOM font scraping and rAF-coalesced recomputation
• Implement Word-faithful data model with section properties void node and 6-slot header/footer variants stored as top-level sibling nodes in editor.children
• Add inline-void dynamic field plugins (page number, page count, date) that resolve values at paint time from page context
• Create dual render mode system with PrintPagination for paged/print output and StandardLayout for standard mode with hybrid footer positioning

Design Choices

Design Choice 1: Pretext API surface for mixed-marks blocks

Options Considered:

1. Use prepare() per leaf segment and sum heights manually
2. Use prepareRichInline() with a spans array derived from Slate marks

Chosen Option: 2

Rationale: prepareRichInline aligns with how Slate represents mixed formatting as leaf spans, producing more accurate line-wrapping at style boundaries.

Design Choice 2: Header/Footer variant storage pattern

Options Considered:

1. Separate node types: { type: 'header-first', children: [...] }
2. Single type with variant property: { type: 'header', variant: 'first', children: [...] }

Chosen Option: 1

Rationale: Separate node types match the ticket's editor.children shape specification and simplify filtering in paginate() with explicit type checks.

💡 User Tips

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

Implementation Steps

Phase 1: Pretext-Backed Measurement System

Replace the canvas-based character-width estimator with real pretext integration, establishing accurate line-break and height measurement as the foundation for all pagination logic.

Task 1: Add Pretext Dependency

Add the @chenglou/pretext package as a production dependency.

• Update packages/pagination/package.json to add @chenglou/pretext to dependencies
• Verify the package is ESM-compatible and exports prepare, prepareRichInline, and layout functions

Task 2: Implement Per-Block Font Scraping

Create a utility that extracts computed font information from DOM nodes for accurate pretext measurement.

• Create packages/pagination/src/react/internal/scrape-block-font.ts
• Use editor.api.toDOMNode(block) to get the rendered DOM element
• Extract font via getComputedStyle(el).font
• Implement system-ui → Inter font-family snapping for deterministic cross-platform measurement
• Return structured font data (family, size, weight, lineHeight) suitable for pretext

Task 3: Rewrite Pretext Measurer Hook

Replace the canvas-based implementation with real pretext integration.

• Rewrite packages/pagination/src/react/use-pretext-measurer.ts to use pretext APIs
• For single-style blocks: use pretext.prepare(text, font) then pretext.layout(width)
• For mixed-marks blocks: use pretext.prepareRichInline(spans) where spans are derived from Slate leaf nodes
• Maintain the existing cache key structure: (node.id, marksFingerprint, font, width) using the existing measure-cache.ts
• Add content hash to cache key to invalidate on text edits (as current implementation does)

Task 4: Wire Font Context into Page Layout

Update the layout hook to pass real font data per block instead of empty strings.

• Update packages/pagination/src/react/internal/use-page-layout.ts
• Replace ctx: { font: '', marksFingerprint: '', width } with per-block scraped values
• Use marksFingerprint() from internal/marks-fingerprint.ts for each block
• Call the font scraper for each block's DOM node

Task 5: Add rAF Coalescing for Recomputation

Wrap pagination recomputation in requestAnimationFrame to prevent layout thrashing during rapid edits.

• Create packages/pagination/src/react/internal/use-raf-coalesced.ts utility hook
• Wrap the useMemo pagination logic in use-page-layout.ts with rAF coalescing
• Ensure pending computations are cancelled when new edits arrive before the frame fires
• Maintain synchronous initial computation for first render

🤖 Prompt for AI agents

Replace the canvas-based measurement system with real `@chenglou/pretext`
integration across several files in `packages/pagination/src/react/`.

**Task 1.1 – Add Pretext Dependency**
- In `packages/pagination/package.json`, add `@chenglou/pretext` to
`dependencies`

**Task 1.2 – Per-Block Font Scraping (`scrape-block-font.ts`)**
- Create `packages/pagination/src/react/internal/scrape-block-font.ts`
- Accept a block node and editor reference; use `editor.api.toDOMNode(block)` to
resolve the DOM element
- Read font properties using `getComputedStyle(el).font`
- Apply `system-ui → Inter` font-family snapping for deterministic
cross-platform results
- Return a structured object with `family`, `size`, `weight`, and `lineHeight`

**Task 1.3 – Rewrite Pretext Measurer Hook (`use-pretext-measurer.ts`)**
- Rewrite `packages/pagination/src/react/use-pretext-measurer.ts`
- For single-style blocks: call `pretext.prepare(text, font)` then
`pretext.layout(width)`
- For mixed-marks blocks: call `pretext.prepareRichInline(spans)` where `spans`
are derived from Slate leaf nodes
- Cache results using the existing `measure-cache.ts` with the key structure
`(node.id, marksFingerprint, font, width)`, augmented with a content hash for
text-edit invalidation

**Task 1.4 – Wire Font Context into Page Layout (`use-page-layout.ts`)**
- Update `packages/pagination/src/react/internal/use-page-layout.ts`
- Replace the placeholder `ctx: { font: '', marksFingerprint: '', width }` with
per-block scraped values
- Call the font scraper from Task 1.2 for each block's DOM node
- Call `marksFingerprint()` from `internal/marks-fingerprint.ts` per block

**Task 1.5 – rAF Coalescing Hook (`use-raf-coalesced.ts`)**
- Create `packages/pagination/src/react/internal/use-raf-coalesced.ts`
- Wrap the `useMemo` pagination logic in `use-page-layout.ts` with
`requestAnimationFrame` coalescing
- Cancel any pending frame when a new edit arrives before the frame fires
- Keep the first render synchronous

Phase 2: Section Properties & Document Structure

Establish the Word-faithful data model with section properties persistence and extended header/footer variant support.

Task 1: Create Section Properties Plugin

Implement the void node that persists page configuration at the document level.

• Create packages/pagination/src/lib/base-section-properties-plugin.ts
• Define as createSlatePlugin with node: { isElement: true, isVoid: true }
• Add key constant SECTION_PROPERTIES_KEY to internal/keys.ts
• Type definition in types.ts: TSectionPropertiesElement with pageSize, margins, differentFirstPage, differentOddEven
• Create React layer in packages/pagination/src/react/section-properties-plugin.ts

Task 2: Add Section Properties Transforms

Implement transforms for reading and updating section properties.

• Create packages/pagination/src/lib/transforms/setSectionProperties.ts for updating properties
• Create packages/pagination/src/lib/transforms/ensureSectionProperties.ts to guarantee the node exists
• Add query packages/pagination/src/lib/queries/getSectionProperties.ts
• Section properties node should always be at the end of editor.children
• Wire transforms into BasePaginationPlugin API extensions

Task 3: Extend Header/Footer Plugins for Variant Model

Expand the existing header/footer plugins to support the 6-slot Word model.

• Add new keys to internal/keys.ts: HEADER_FIRST_KEY, HEADER_EVEN_KEY, FOOTER_FIRST_KEY, FOOTER_EVEN_KEY
• Create variant plugins in packages/pagination/src/lib/:
  • base-header-first-plugin.ts, base-header-even-plugin.ts
  • base-footer-first-plugin.ts, base-footer-even-plugin.ts
• Each follows the same minimal pattern as existing base-header-plugin.ts
• Create corresponding React layer plugins in packages/pagination/src/react/

Task 4: Update Paginate Filtering Logic

Ensure the paginate function properly filters all chrome nodes.

• Update packages/pagination/src/lib/paginate.ts to skip SECTION_PROPERTIES_KEY
• Add filtering for all header/footer variant types
• Verify footnote definitions continue to be filtered correctly
• Document the complete list of filtered node types in function JSDoc

Task 5: Create Header/Footer Resolution Logic

Implement logic to select the correct header/footer variant based on page position.

• Create packages/pagination/src/lib/queries/resolveHeaderForPage.ts
• Create packages/pagination/src/lib/queries/resolveFooterForPage.ts
• Logic: check differentFirstPage/differentOddEven from section properties
• First page → use header-first/footer-first if exists, else default
• Even pages → use header-even/footer-even if exists, else default
• Return the resolved node or null

🤖 Prompt for AI agents

Establish the Word-faithful document structure by adding section properties and
all header/footer variant plugins across `packages/pagination/src/lib/` and
`packages/pagination/src/react/`.

**Task 2.1 – Section Properties Plugin**
- Create `packages/pagination/src/lib/base-section-properties-plugin.ts` using
`createSlatePlugin` with `node: { isElement: true, isVoid: true }`
- Add `SECTION_PROPERTIES_KEY` to `internal/keys.ts`
- Add `TSectionPropertiesElement` type to `types.ts` with fields: `pageSize`,
`margins`, `differentFirstPage`, `differentOddEven`
- Create React layer in
`packages/pagination/src/react/section-properties-plugin.ts`

**Task 2.2 – Section Properties Transforms**
- Create `packages/pagination/src/lib/transforms/setSectionProperties.ts`
- Create `packages/pagination/src/lib/transforms/ensureSectionProperties.ts`
(ensures the node exists at the end of `editor.children`)
- Create `packages/pagination/src/lib/queries/getSectionProperties.ts`
- Wire all transforms and queries into `BasePaginationPlugin` API extensions

**Task 2.3 – Header/Footer Variant Plugins**
- Add `HEADER_FIRST_KEY`, `HEADER_EVEN_KEY`, `FOOTER_FIRST_KEY`,
`FOOTER_EVEN_KEY` to `internal/keys.ts`
- Create `base-header-first-plugin.ts`, `base-header-even-plugin.ts`,
`base-footer-first-plugin.ts`, `base-footer-even-plugin.ts` in
`packages/pagination/src/lib/`, each following the existing
`base-header-plugin.ts` pattern
- Create corresponding React layer plugins in `packages/pagination/src/react/`

**Task 2.4 – Update Paginate Filtering**
- Update `packages/pagination/src/lib/paginate.ts` to skip
`SECTION_PROPERTIES_KEY` and all new header/footer variant types
- Verify footnote definitions remain filtered
- Document the complete set of filtered node types in the function JSDoc

**Task 2.5 – Header/Footer Resolution Queries**
- Create `packages/pagination/src/lib/queries/resolveHeaderForPage.ts` and
`resolveFooterForPage.ts`
- Check `differentFirstPage` / `differentOddEven` from section properties
- First page → prefer `header-first`/`footer-first`, fall back to default
- Even pages → prefer `header-even`/`footer-even`, fall back to default
- Return the resolved node or `null`

Phase 3: Dynamic Fields & Interactions

Add inline-void dynamic field plugins and enhance page break interactions.

Task 1: Create Page Number Plugin

Implement an inline-void that renders the current page number at paint time.

• Create packages/pagination/src/lib/base-page-number-plugin.ts
• Define as inline void: node: { isElement: true, isInline: true, isVoid: true }
• Add PAGE_NUMBER_KEY to internal/keys.ts
• React component receives page index from context and renders the number
• Create React layer in packages/pagination/src/react/page-number-plugin.ts

Task 2: Create Page Count Plugin

Implement an inline-void that renders the total page count at paint time.

• Create packages/pagination/src/lib/base-page-count-plugin.ts
• Define as inline void: node: { isElement: true, isInline: true, isVoid: true }
• Add PAGE_COUNT_KEY to internal/keys.ts
• React component receives total pages from context and renders the count
• Create React layer in packages/pagination/src/react/page-count-plugin.ts

Task 3: Create Date Field Plugin

Implement an inline-void that renders the current date at paint time.

• Create packages/pagination/src/lib/base-date-plugin.ts
• Define as inline void: node: { isElement: true, isInline: true, isVoid: true }
• Add DATE_KEY to internal/keys.ts
• Support optional format property on the node for date formatting
• React component renders formatted date
• Create React layer in packages/pagination/src/react/date-plugin.ts

Task 4: Add Page Break Keyboard Shortcut

Register Cmd/Ctrl+Enter keybinding for inserting page breaks.

• Update packages/pagination/src/react/page-break-plugin.ts
• Add shortcuts configuration to the plugin
• Use Key.Mod + Enter pattern matching existing keyboard conventions
• Handler calls the existing insertPageBreak transform

Task 5: Register Page Break in Slash Menu

Enable /page break slash command for inserting page breaks.

• Add slash menu rule to PageBreakPlugin configuration
• Follow existing slash command patterns from other plugins
• Configure appropriate icon and label for the command

🤖 Prompt for AI agents

Add inline-void dynamic field plugins for page number, page count, and date, and
enhance the page break plugin with keyboard and slash menu support.

**Task 3.1 – Page Number Plugin**
- Create `packages/pagination/src/lib/base-page-number-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `PAGE_NUMBER_KEY` to `internal/keys.ts`
- React component reads `pageIndex` from page context and renders the number
- Create React layer in `packages/pagination/src/react/page-number-plugin.ts`

**Task 3.2 – Page Count Plugin**
- Create `packages/pagination/src/lib/base-page-count-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `PAGE_COUNT_KEY` to `internal/keys.ts`
- React component reads `pageCount` from page context and renders the count
- Create React layer in `packages/pagination/src/react/page-count-plugin.ts`

**Task 3.3 – Date Field Plugin**
- Create `packages/pagination/src/lib/base-date-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `DATE_KEY` to `internal/keys.ts`
- Support an optional `format` property on the node for date formatting
- React component renders the formatted current date
- Create React layer in `packages/pagination/src/react/date-plugin.ts`

**Task 3.4 – Page Break Keyboard Shortcut**
- Update `packages/pagination/src/react/page-break-plugin.ts`
- Add a `shortcuts` configuration using `Key.Mod` + `Enter`, matching existing
keyboard conventions
- Handler calls the existing `insertPageBreak` transform

**Task 3.5 – Page Break Slash Menu**
- Add a slash menu rule to `PageBreakPlugin` configuration
- Follow existing slash command patterns from sibling plugins
- Set an appropriate icon and label

Phase 4: Render Components

Implement the dual-mode render system with PrintPagination for paged view and StandardLayout for standard mode.

Task 1: Create PrintPagination Component

Build the component that renders real page DOM elements for both on-screen paged view and print output.

• Create packages/pagination/src/react/print-pagination.tsx
• Render one <section class="page"> per page from the computed Page[] array
• Each page section contains: resolved header, body content, footnote well, resolved footer
• Add CSS: .page { page-break-after: always } for @media print
• Use header/footer resolution logic from Phase 2 to select correct variants per page
• Pass page context (pageIndex, pageCount) to dynamic field components

Task 2: Create Page Context Provider

Implement context that provides page-level data to dynamic field components.

• Create packages/pagination/src/react/page-context.tsx
• Context provides: pageIndex, pageCount, isFirstPage, isEvenPage
• Wrap each page's content in the provider within PrintPagination
• Dynamic field components consume this context to render their values

Task 3: Create StandardLayout Component

Build the standard mode layout with hybrid footer positioning.

• Create packages/pagination/src/react/standard-layout.tsx
• Implement IntersectionObserver to detect when document is shorter than viewport
• Footer positioning: anchored to end of content normally, pinned to viewport bottom when doc is short
• Render endnotes (footnote definitions) between last body block and the hybrid footer
• No pagination applied in this mode

Task 4: Create MarginDragHandles Overlay

Implement draggable handles for visual margin adjustment in paged view.

• Create packages/pagination/src/react/margin-drag-handles.tsx
• Render overlay lines at margin boundaries (top, bottom, left, right)
• Handle drag events to calculate new margin values
• On drag end, call setSectionProperties transform to persist new margins
• Show handles only in paged mode when margins are editable

Task 5: Integrate Render Modes into Pagination Plugin

Wire the render components into the plugin's render configuration.

• Update packages/pagination/src/react/pagination-plugin.ts
• Add mode switching logic based on section properties (or plugin options)
• Standard mode: use StandardLayout wrapper
• Paged mode: use PrintPagination with MarginDragHandles overlay
• Ensure both modes work with the same underlying Page[] computation

Task 6: Update Plugin Registration

Register all new plugins as sub-plugins of the main PaginationPlugin.

• Update packages/pagination/src/react/pagination-plugin.ts plugins array
• Include: SectionPropertiesPlugin, all header/footer variants, PageNumberPlugin, PageCountPlugin, DatePlugin
• Update barrel exports in packages/pagination/src/lib/index.ts and packages/pagination/src/react/index.ts
• Export all new types from types.ts

🤖 Prompt for AI agents

Implement the dual-mode render system and wire all components into the
pagination plugin.

**Task 4.1 – PrintPagination Component (`print-pagination.tsx`)**
- Create `packages/pagination/src/react/print-pagination.tsx`
- Render one `<section class="page">` per entry in the computed `Page[]` array
- Each page section contains: resolved header, body content, footnote well,
resolved footer (using resolution logic from Phase 2)
- Add `.page { page-break-after: always }` CSS under `@media print`
- Wrap each page in the `PageContext` provider, passing `pageIndex` and
`pageCount`

**Task 4.2 – Page Context Provider (`page-context.tsx`)**
- Create `packages/pagination/src/react/page-context.tsx`
- Context shape: `{ pageIndex, pageCount, isFirstPage, isEvenPage }`
- Wrap each page's content in the provider inside `PrintPagination`
- Dynamic field components (page number, page count, date) consume this context

**Task 4.3 – StandardLayout Component (`standard-layout.tsx`)**
- Create `packages/pagination/src/react/standard-layout.tsx`
- Use `IntersectionObserver` to detect when the document is shorter than the
viewport
- Footer is anchored to end of content normally, pinned to the viewport bottom
when the doc is short
- Render endnotes (footnote definitions) between the last body block and the
hybrid footer
- No pagination is applied in this mode

**Task 4.4 – MarginDragHandles Overlay (`margin-drag-handles.tsx`)**
- Create `packages/pagination/src/react/margin-drag-handles.tsx`
- Render overlay lines at top, bottom, left, and right margin boundaries
- On drag end, call `setSectionProperties` with the new margin values
- Visible only in paged mode when margins are editable

**Task 4.5 – Integrate Render Modes into Plugin**
- Update `packages/pagination/src/react/pagination-plugin.ts`
- Add mode switching: standard mode uses `StandardLayout`, paged mode uses
`PrintPagination` with `MarginDragHandles`
- Both modes consume the same underlying `Page[]` computation

**Task 4.6 – Plugin Registration & Barrel Exports**
- Add `SectionPropertiesPlugin`, all header/footer variant plugins,
`PageNumberPlugin`, `PageCountPlugin`, and `DatePlugin` to the
`PaginationPlugin` sub-plugins array
- Update barrel exports in `packages/pagination/src/lib/index.ts` and
`packages/pagination/src/react/index.ts`
- Export all new types from `types.ts`

Research

The packages/pagination package has foundational infrastructure in place: a canvas-based measurer (use-pretext-measurer.ts), basic header/footer/page-break plugins (minimal skeletons), a paginate() pure function that bin-packs blocks into pages while filtering chrome nodes, and a side-panel overlay preview system. The plugin follows the standard Plate pattern with lib/ containing framework-agnostic base plugins (createSlatePlugin) and react/ containing React-layer extensions (toPlatePlugin). Sibling node patterns from the footnote plugin demonstrate how top-level document nodes can live alongside body content while being filtered from the pagination flow.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Replace the canvas-based measurement system with real `@chenglou/pretext`
integration across several files in `packages/pagination/src/react/`.

**Task 1.1 – Add Pretext Dependency**
- In `packages/pagination/package.json`, add `@chenglou/pretext` to
`dependencies`

**Task 1.2 – Per-Block Font Scraping (`scrape-block-font.ts`)**
- Create `packages/pagination/src/react/internal/scrape-block-font.ts`
- Accept a block node and editor reference; use `editor.api.toDOMNode(block)` to
resolve the DOM element
- Read font properties using `getComputedStyle(el).font`
- Apply `system-ui → Inter` font-family snapping for deterministic
cross-platform results
- Return a structured object with `family`, `size`, `weight`, and `lineHeight`

**Task 1.3 – Rewrite Pretext Measurer Hook (`use-pretext-measurer.ts`)**
- Rewrite `packages/pagination/src/react/use-pretext-measurer.ts`
- For single-style blocks: call `pretext.prepare(text, font)` then
`pretext.layout(width)`
- For mixed-marks blocks: call `pretext.prepareRichInline(spans)` where `spans`
are derived from Slate leaf nodes
- Cache results using the existing `measure-cache.ts` with the key structure
`(node.id, marksFingerprint, font, width)`, augmented with a content hash for
text-edit invalidation

**Task 1.4 – Wire Font Context into Page Layout (`use-page-layout.ts`)**
- Update `packages/pagination/src/react/internal/use-page-layout.ts`
- Replace the placeholder `ctx: { font: '', marksFingerprint: '', width }` with
per-block scraped values
- Call the font scraper from Task 1.2 for each block's DOM node
- Call `marksFingerprint()` from `internal/marks-fingerprint.ts` per block

**Task 1.5 – rAF Coalescing Hook (`use-raf-coalesced.ts`)**
- Create `packages/pagination/src/react/internal/use-raf-coalesced.ts`
- Wrap the `useMemo` pagination logic in `use-page-layout.ts` with
`requestAnimationFrame` coalescing
- Cancel any pending frame when a new edit arrives before the frame fires
- Keep the first render synchronous
===============================================================================

Task: 2

Establish the Word-faithful document structure by adding section properties and
all header/footer variant plugins across `packages/pagination/src/lib/` and
`packages/pagination/src/react/`.

**Task 2.1 – Section Properties Plugin**
- Create `packages/pagination/src/lib/base-section-properties-plugin.ts` using
`createSlatePlugin` with `node: { isElement: true, isVoid: true }`
- Add `SECTION_PROPERTIES_KEY` to `internal/keys.ts`
- Add `TSectionPropertiesElement` type to `types.ts` with fields: `pageSize`,
`margins`, `differentFirstPage`, `differentOddEven`
- Create React layer in
`packages/pagination/src/react/section-properties-plugin.ts`

**Task 2.2 – Section Properties Transforms**
- Create `packages/pagination/src/lib/transforms/setSectionProperties.ts`
- Create `packages/pagination/src/lib/transforms/ensureSectionProperties.ts`
(ensures the node exists at the end of `editor.children`)
- Create `packages/pagination/src/lib/queries/getSectionProperties.ts`
- Wire all transforms and queries into `BasePaginationPlugin` API extensions

**Task 2.3 – Header/Footer Variant Plugins**
- Add `HEADER_FIRST_KEY`, `HEADER_EVEN_KEY`, `FOOTER_FIRST_KEY`,
`FOOTER_EVEN_KEY` to `internal/keys.ts`
- Create `base-header-first-plugin.ts`, `base-header-even-plugin.ts`,
`base-footer-first-plugin.ts`, `base-footer-even-plugin.ts` in
`packages/pagination/src/lib/`, each following the existing
`base-header-plugin.ts` pattern
- Create corresponding React layer plugins in `packages/pagination/src/react/`

**Task 2.4 – Update Paginate Filtering**
- Update `packages/pagination/src/lib/paginate.ts` to skip
`SECTION_PROPERTIES_KEY` and all new header/footer variant types
- Verify footnote definitions remain filtered
- Document the complete set of filtered node types in the function JSDoc

**Task 2.5 – Header/Footer Resolution Queries**
- Create `packages/pagination/src/lib/queries/resolveHeaderForPage.ts` and
`resolveFooterForPage.ts`
- Check `differentFirstPage` / `differentOddEven` from section properties
- First page → prefer `header-first`/`footer-first`, fall back to default
- Even pages → prefer `header-even`/`footer-even`, fall back to default
- Return the resolved node or `null`
===============================================================================

Task: 3

Add inline-void dynamic field plugins for page number, page count, and date, and
enhance the page break plugin with keyboard and slash menu support.

**Task 3.1 – Page Number Plugin**
- Create `packages/pagination/src/lib/base-page-number-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `PAGE_NUMBER_KEY` to `internal/keys.ts`
- React component reads `pageIndex` from page context and renders the number
- Create React layer in `packages/pagination/src/react/page-number-plugin.ts`

**Task 3.2 – Page Count Plugin**
- Create `packages/pagination/src/lib/base-page-count-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `PAGE_COUNT_KEY` to `internal/keys.ts`
- React component reads `pageCount` from page context and renders the count
- Create React layer in `packages/pagination/src/react/page-count-plugin.ts`

**Task 3.3 – Date Field Plugin**
- Create `packages/pagination/src/lib/base-date-plugin.ts` with `node: {
isElement: true, isInline: true, isVoid: true }`
- Add `DATE_KEY` to `internal/keys.ts`
- Support an optional `format` property on the node for date formatting
- React component renders the formatted current date
- Create React layer in `packages/pagination/src/react/date-plugin.ts`

**Task 3.4 – Page Break Keyboard Shortcut**
- Update `packages/pagination/src/react/page-break-plugin.ts`
- Add a `shortcuts` configuration using `Key.Mod` + `Enter`, matching existing
keyboard conventions
- Handler calls the existing `insertPageBreak` transform

**Task 3.5 – Page Break Slash Menu**
- Add a slash menu rule to `PageBreakPlugin` configuration
- Follow existing slash command patterns from sibling plugins
- Set an appropriate icon and label
===============================================================================

Task: 4

Implement the dual-mode render system and wire all components into the
pagination plugin.

**Task 4.1 – PrintPagination Component (`print-pagination.tsx`)**
- Create `packages/pagination/src/react/print-pagination.tsx`
- Render one `<section class="page">` per entry in the computed `Page[]` array
- Each page section contains: resolved header, body content, footnote well,
resolved footer (using resolution logic from Phase 2)
- Add `.page { page-break-after: always }` CSS under `@media print`
- Wrap each page in the `PageContext` provider, passing `pageIndex` and
`pageCount`

**Task 4.2 – Page Context Provider (`page-context.tsx`)**
- Create `packages/pagination/src/react/page-context.tsx`
- Context shape: `{ pageIndex, pageCount, isFirstPage, isEvenPage }`
- Wrap each page's content in the provider inside `PrintPagination`
- Dynamic field components (page number, page count, date) consume this context

**Task 4.3 – StandardLayout Component (`standard-layout.tsx`)**
- Create `packages/pagination/src/react/standard-layout.tsx`
- Use `IntersectionObserver` to detect when the document is shorter than the
viewport
- Footer is anchored to end of content normally, pinned to the viewport bottom
when the doc is short
- Render endnotes (footnote definitions) between the last body block and the
hybrid footer
- No pagination is applied in this mode

**Task 4.4 – MarginDragHandles Overlay (`margin-drag-handles.tsx`)**
- Create `packages/pagination/src/react/margin-drag-handles.tsx`
- Render overlay lines at top, bottom, left, and right margin boundaries
- On drag end, call `setSectionProperties` with the new margin values
- Visible only in paged mode when margins are editable

**Task 4.5 – Integrate Render Modes into Plugin**
- Update `packages/pagination/src/react/pagination-plugin.ts`
- Add mode switching: standard mode uses `StandardLayout`, paged mode uses
`PrintPagination` with `MarginDragHandles`
- Both modes consume the same underlying `Page[]` computation

**Task 4.6 – Plugin Registration & Barrel Exports**
- Add `SectionPropertiesPlugin`, all header/footer variant plugins,
`PageNumberPlugin`, `PageCountPlugin`, and `DatePlugin` to the
`PaginationPlugin` sub-plugins array
- Update barrel exports in `packages/pagination/src/lib/index.ts` and
`packages/pagination/src/react/index.ts`
- Export all new types from `types.ts`

💡 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]
#166 - Migrate to pnpm and introduce @plate/sConsolidate skill definitions and reorganize agent configurationipts package [merged]
#175 - Update .mcp.json format and add Next.js experimental config [merged]
#357 - feat(pagination): scaffold @platejs/pagination variant A (render-overlay) [merged]
#375 - Codex/pagination variant a [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!