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

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant A of 2 parallel framings of the same goal.
Sibling variant: #354. Please compare and tell us which assumption is load-bearing.
Carrots are crunchier when the layer is right.

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 A — render-time overlay; pages as derived view)

1. Add BasePaginationPlugin (createTSlatePlugin, key: KEYS.pagination) under packages/pagination/src/lib. Pure options: pageSize, margins, headerHeight, footerHeight, footnoteWell. No page nodes ever enter editor.children.
2. Add BaseHeaderPlugin, BaseFooterPlugin, BasePageBreakPlugin (manual hard-break escape hatch) as sibling base plugins. Compose with the existing packages/footnote/ (BaseFootnoteDefinitionPlugin + Reference + Input) — do NOT re-author footnotes.
3. Author paginate(doc, ctx, measurer) -> Page[] as a pure Slate-only selector in src/lib/paginate.ts. measurer: (text, font, width) => number is injected — lib/ stays React-free and unit-testable with a fake monospace measurer.
4. Lift to React via toTPlatePlugin(BasePaginationPlugin, { plugins: [...], render: { aboveSlate: PageOverlay } }). PageOverlay paints absolutely-positioned PageFrames (header / footer / footnote well) above the normal Editable. Footnote definitions are hidden in main flow and portaled into the footer well of the page that contains their footnote_ref.
5. Real-time measurer = a React hook that calls pretext.prepare() once per (node.id, marks-fingerprint, font, width) and pretext.layout() per pagination cycle, rAF-coalesced. Use prepareRichInline for mixed-mark runs. Snap to a named font (Inter) when the theme uses system-ui (pretext caveat).
6. Print mode swaps PageOverlay for real <section class="page"> elements + @media print { .page { page-break-after: always; } } so Chromium honours pretext-derived breaks.

Acceptance: a 500-block document edits at ≥55fps with pagination on; resizing the viewport repaginates within one frame; print preview matches on-screen page boundaries within ±1 line; Yjs co-edit produces visually different paginations per viewport without doc divergence.

Because the code is

• packages/core/src/lib/plugin/createSlatePlugin.ts:91-159 — createTSlatePlugin is the right factory; pagination owns explicit options + typed transforms, so the T-variant is correct.
• packages/core/src/lib/plugin/SlatePlugin.ts:341-384 — render.aboveSlate / render.belowRootNodes are the slot mechanism for a chrome overlay; no portal infra to invent.
• packages/core/src/react/plugin/toPlatePlugin.ts:70-107 — base→Plate lift preserves all extend* chains; canonical "wrap base, child plugins in wrapper" pattern.
• packages/footnote/src/lib/BaseFootnoteDefinitionPlugin.ts (and Reference / Input) — existing semantic base plugins; this variant composes them rather than reinventing.
• packages/utils/src/lib/plate-keys.ts — KEYS.pagination belongs here, not as a string literal.
• .claude/skills/plate-plugin-creator/SKILL.md — Slate-first hard law: pages are derived presentation, not document state, so the base plugin stays React-free.
• Google docs - like pagination udecode/plate#4380 — zbeyens (maintainer, 2025-07-02): "rewriting slate-react to support virtual pages without container nodes in the document structure" — explicitly his preferred direction. Same thread: closed-source predecessor was bottlenecked by container-node normalization on every keystroke.
• pretext README (commit bb224e0, 2026-04-22) — pretext does NOT paginate; it is a height oracle. This variant treats it as such.

Assumptions deliberately shuffled vs variant B

Axis	Variant A (this)	Variant B (#354)
Layer	render-time overlay; pages derived	document-model; section / page 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/core/src/lib/plugin/SlatePlugin.ts — confirm render.aboveSlate survives read-only mode, plays with selection coords, and does not break Editable event delegation.
• Review of our own code in packages/footnote/, packages/comment/, packages/core/src/internal/plugin/pluginInjectNodeProps.ts:25-122 — check that the portal+overlay pattern this variant proposes is not already invalidated by an existing convention.
• Comparative analysis vs sibling Plate pagination plugin (headers / footers / footnotes) with pretext (variant B) #354 — 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, liquid editing UX + per-keystroke perf (favours A) or deterministic paged structure + DOCX section fidelity (favours B)? Do not pick a winner yet — name the axis.
• pretext SSR posture — confirm we can hydrate without re-running prepare() on the server.
• Yjs implications of derived pagination — verify two clients with different viewport widths don't fight on editor.children.

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.header, KEYS.footer, KEYS.pageBreak to packages/utils/src/lib/plate-keys.ts. Footnote keys reuse what packages/footnote/ already exposes.
3. src/lib/: base-pagination-plugin.ts, base-header-plugin.ts, base-footer-plugin.ts, base-page-break-plugin.ts, paginate.ts, allocate-footnotes.ts, internal/font-from-style.ts, internal/measure-cache.ts, types.ts. Helpers (matchers, fallbacks, fingerprint hashing) live in internal/ per repo barrel rules.
4. src/react/: pagination-plugin.ts (toTPlatePlugin), header-plugin.ts, footer-plugin.ts, page-break-plugin.ts, page-overlay.tsx, page-frame.tsx, footnote-portal.tsx, use-pretext-measurer.ts, internal/use-page-layout.ts.
5. Compose with existing packages/footnote/ plugins — no re-author. PaginationPlugin = toTPlatePlugin(BasePaginationPlugin, { plugins: [HeaderPlugin, FooterPlugin, PageBreakPlugin, FootnoteDefinitionPlugin, FootnoteReferencePlugin, FootnoteInputPlugin] }).
6. Public surface: editor.api.pagination.{getPages, getPageOf, getFootnotes, measure}; editor.tf.pagination.{insertFootnote, setHeader, setFooter, insertPageBreak, recomputePages}. No ({ editor }: { editor: SlateEditor }) annotations — inference from createTSlatePlugin<Config>.
7. Print path: alternative PrintPagination component injecting real <section> elements + @media print rules; same paginate() selector.
8. Tests in packages/pagination/src/**/*.spec.ts with bun: pure paginator with fake measurer (golden cases), allocator, schema round-trip; React tests only for overlay positioning.
9. DOCX import/export: round-trip headers/footers via w:hdrRef/w:ftrRef; footnotes through existing packages/footnote/ adapters.
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)
• packages/core/src/lib/plugin/{createSlatePlugin.ts, SlatePlugin.ts, BasePlugin.ts}
• packages/core/src/react/plugin/toPlatePlugin.ts
• 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

[arthrod]

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

[coderabbitai]

Coding Plan

Summary

• Pages are derived presentation computed at render-time via render.aboveSlate wrapper — editor.children remains entirely unmodified (no page/section nodes ever inserted), enabling Yjs compatibility across different viewport widths
• Pure paginate() algorithm in src/lib/ is React-free and unit-testable with injected measurer function
• React layer uses render.aboveSlate slot to wrap the editor with a positioned container that overlays page frames above the content
• Print mode swaps PageOverlay for real <section class="page"> DOM elements with @media print CSS rules, rather than using overlay-based print handling
• Composes with existing packages/footnote/ plugins rather than re-authoring; footnotes are hidden in main flow via CSS and portaled to appropriate page wells

Design Choices

Design Choice 1: Overlay rendering slot for page frames

Options Considered:

1. Use render.aboveSlate — wraps entire Slate provider, provides positioning context for page overlay
2. Use render.afterEditable — rendered as sibling inside Slate context

Chosen Option: 1

Rationale: aboveSlate provides the wrapper positioning context needed for the page overlay chrome. Editor and container access is available via useEditorRef() and useEditorContainerRef() from PlateStore. This matches the ticket's explicit specification and the Variant A render-time overlay approach.

Design Choice 2: Footnote visibility in main flow

Options Considered:

1. Use CSS visibility: hidden on footnote definitions in main flow, portal copies to footer wells
2. Use display: none and only render footnotes in footer wells
3. Keep footnote definitions at original position but render a duplicate in footer well for visual display

Chosen Option: 1

Rationale: CSS hiding preserves DOM structure for selection/editing while the portal shows the visual representation. This maintains Slate's editing model while achieving the visual goal.

Design Choice 3: Measurement cache invalidation strategy

Options Considered:

1. Cache by (node.id, marks-fingerprint, font, width) as ticket suggests
2. Cache by node path + content hash
3. No caching, measure on every pagination cycle

Chosen Option: 1

Rationale: The node ID + marks fingerprint approach is stable across edits and handles mark changes correctly without being tied to volatile path positions.

💡 User Tips

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

Implementation Steps

Phase 1: Package Infrastructure & Plugin Foundations

Create the package scaffolding, register plugin keys, and establish the base plugin structure with typed configurations.

Task 1: Create Package Structure

Set up the packages/pagination/ package following the established monorepo patterns.

• Create packages/pagination/ directory with package.json using the standard template (dual exports for . and ./react)
• Add pretext as a regular dependency in package.json (not peer dependency, following @platejs/floating pattern)
• Create tsconfig.json and tsconfig.build.json extending shared tooling configs
• Create directory structure: src/lib/, src/react/, src/internal/
• Run pnpm brl to generate barrel files after scaffolding

Task 2: Register Plugin Keys

Add pagination-related keys to the central key registry.

• Add pagination, header, footer, pageBreak to NODES object in packages/utils/src/lib/plate-keys.ts
• Footnote keys (footnoteDefinition, footnoteReference, footnoteInput) already exist — reuse them

Task 3: Define Type Contracts

Establish the TypeScript type definitions for pagination configuration and page structures.

• Create src/lib/types.ts with PaginationConfig type extending PluginConfig with options: pageSize, margins, headerHeight, footerHeight, footnoteWell
• Define Page interface representing a derived page (startIndex, endIndex, headerContent, footerContent, footnotes)
• Define Measurer function type: (text: string, font: FontConfig, width: number) => number
• Define PageSize type with presets (A4, Letter, etc.) as width/height in pixels at 96 DPI

🤖 Prompt for AI agents

Set up the `@platejs/pagination` package infrastructure from scratch, following
the established Plate monorepo patterns.

- Create `packages/pagination/` with a `package.json` using the standard
template, including dual exports for `.` and `./react`. Add `pretext` as a
regular dependency (not peer dependency), following the `@platejs/floating`
pattern.
- Create `tsconfig.json` and `tsconfig.build.json` files extending the shared
tooling configs used by other packages.
- Create the directory structure: `src/lib/`, `src/react/`, `src/internal/`.
- Run `pnpm brl` to generate barrel files after scaffolding.
- In `packages/utils/src/lib/plate-keys.ts`, add `pagination`, `header`,
`footer`, and `pageBreak` keys to the `NODES` object. Do not modify existing
footnote keys.
- Create `src/lib/types.ts` with the following type definitions:
- `PaginationConfig`: extends `PluginConfig` with options `pageSize`, `margins`,
`headerHeight`, `footerHeight`, `footnoteWell`
- `Page`: interface with `startIndex`, `endIndex`, `headerContent`,
`footerContent`, `footnotes`
- `Measurer`: function type `(text: string, font: FontConfig, width: number) =>
number`
- `PageSize`: type with presets (A4, Letter, Legal, etc.) as width/height in
pixels at 96 DPI

Phase 2: Slate Layer (Base Plugins & Pagination Algorithm)

Implement the framework-agnostic base plugins and the pure pagination algorithm that can be tested without React.

Task 1: Create BasePaginationPlugin

Implement the main pagination plugin with options and typed API/transforms contract.

• Create src/lib/BasePaginationPlugin.ts using createTSlatePlugin<PaginationConfig>
• Set key: KEYS.pagination with node: { isElement: true, isVoid: true } (for optional page break markers)
• Define options: pageSize (default A4), margins, headerHeight, footerHeight, footnoteWell, enabled
• Stub out API surface: getPages, getPageOf, getFootnotes, measure
• Stub out transforms: insertPageBreak, setHeader, setFooter, recomputePages

Task 2: Create Sibling Base Plugins

Implement header, footer, and page break base plugins.

• Create src/lib/BaseHeaderPlugin.ts — element plugin for header content blocks, key: KEYS.header
• Create src/lib/BaseFooterPlugin.ts — element plugin for footer content blocks, key: KEYS.footer
• Create src/lib/BasePageBreakPlugin.ts — void inline element for manual hard breaks, key: KEYS.pageBreak
• Each plugin uses createSlatePlugin (no explicit type contract needed for these simple element types)

Task 3: Implement Pure Pagination Algorithm

Create the core paginate() function as a pure Slate-only selector.

• Create src/lib/paginate.ts with paginate(doc, ctx, measurer) -> Page[] signature
• Accept ctx containing page dimensions, margins, header/footer heights, footnote well height
• Inject measurer function to keep the algorithm React-free and unit-testable
• Iterate through editor.children, accumulating block heights until page capacity exceeded
• Handle page breaks (manual pageBreak nodes force new page)
• Return array of Page objects with block ranges and content assignments

Task 4: Implement Footnote Allocation Logic

Create the footnote-to-page allocation algorithm.

• Create src/lib/allocate-footnotes.ts with allocateFootnotes(pages, footnoteRefs, doc) -> Page[]
• For each footnoteReference node, determine which page contains it
• Assign the corresponding footnoteDefinition to that page's footnote well
• Recalculate page breaks if footnote content overflows the well (iterative allocation)
• Handle footnote overflow to subsequent pages if definition exceeds single page well

Task 5: Create Internal Helpers

Implement supporting utilities in the internal directory.

• Create src/internal/font-from-style.ts — extract font configuration from Slate node marks/styles
• Create src/internal/measure-cache.ts — LRU cache keyed by (nodeId, marksFingerprint, font, width)
• Create src/internal/marks-fingerprint.ts — deterministic hash of a node's marks for cache key
• Create src/internal/page-size-presets.ts — A4, Letter, Legal dimensions at 96 DPI

🤖 Prompt for AI agents

Implement the framework-agnostic Slate layer for the pagination package,
including base plugins, the pure pagination algorithm, footnote allocation, and
internal utilities.

**BasePaginationPlugin** (`src/lib/BasePaginationPlugin.ts`):
- Use `createTSlatePlugin<PaginationConfig>` with `key: KEYS.pagination` and
`node: { isElement: true, isVoid: true }`
- Define options: `pageSize` (default A4), `margins`, `headerHeight`,
`footerHeight`, `footnoteWell`, `enabled`
- Stub out API: `getPages`, `getPageOf`, `getFootnotes`, `measure`
- Stub out transforms: `insertPageBreak`, `setHeader`, `setFooter`,
`recomputePages`

**Sibling Base Plugins**:
- `src/lib/BaseHeaderPlugin.ts`: element plugin, `key: KEYS.header`, using
`createSlatePlugin`
- `src/lib/BaseFooterPlugin.ts`: element plugin, `key: KEYS.footer`, using
`createSlatePlugin`
- `src/lib/BasePageBreakPlugin.ts`: void inline element, `key: KEYS.pageBreak`,
using `createSlatePlugin`

**Pure Pagination Algorithm** (`src/lib/paginate.ts`):
- Signature: `paginate(doc, ctx, measurer) -> Page[]`
- `ctx` contains page dimensions, margins, header/footer heights, footnote well
height
- `measurer` is injected to keep algorithm React-free and unit-testable
- Iterate through `editor.children`, accumulate block heights, create new page
when capacity exceeded
- Manual `pageBreak` nodes force a new page
- Return array of `Page` objects with block ranges and content assignments

**Footnote Allocation** (`src/lib/allocate-footnotes.ts`):
- Signature: `allocateFootnotes(pages, footnoteRefs, doc) -> Page[]`
- For each `footnoteReference`, determine its containing page
- Assign the matching `footnoteDefinition` to that page's footnote well
- Recalculate page breaks if footnote content overflows the well (iterative
allocation)
- Handle footnote overflow to subsequent pages

**Internal Helpers**:
- `src/internal/font-from-style.ts`: extract font config from Slate node
marks/styles
- `src/internal/measure-cache.ts`: LRU cache keyed by `(nodeId,
marksFingerprint, font, width)`
- `src/internal/marks-fingerprint.ts`: deterministic hash of a node's marks
- `src/internal/page-size-presets.ts`: A4, Letter, Legal dimensions at 96 DPI

Phase 3: React Layer & Overlay Rendering

Lift base plugins to React and implement the visual page overlay system with pretext integration.

Task 1: Lift Plugins to React

Create React versions of all base plugins.

• Create src/react/PaginationPlugin.tsx using toTPlatePlugin(BasePaginationPlugin, {...})
• Compose child plugins: HeaderPlugin, FooterPlugin, PageBreakPlugin
• Add render.aboveSlate: PageOverlay to wrap the editor with page chrome positioning context
• Create src/react/HeaderPlugin.tsx, FooterPlugin.tsx, PageBreakPlugin.tsx as thin toPlatePlugin wrappers

Task 2: Implement Pretext Measurer Hook

Create the React hook that interfaces with pretext for real text measurement.

• Create src/react/hooks/usePretextMeasurer.ts returning the Measurer function
• Call pretext.prepare() once per unique (nodeId, marksFingerprint, font, width) tuple
• Use prepareRichInline for nodes with mixed marks (bold + italic runs, etc.)
• Implement rAF coalescing to batch pretext.layout() calls per animation frame
• Handle system-ui font fallback: snap to named font (Inter) when theme uses system-ui
• Memoize results in the measure cache from Task 2.5

Task 3: Implement Page Overlay Component

Create the main overlay component that wraps the editor and renders page frames.

• Create src/react/components/PageOverlay.tsx as the aboveSlate wrapper component receiving children
• Use useEditorRef() and useEditorContainerRef() from PlateStore to access editor and container dimensions
• Call paginate() with the pretext measurer to compute current pages
• Render a positioned wrapper div containing both the children (Slate provider) and absolutely-positioned PageFrame components
• Apply position: relative to the wrapper to establish containing block for page frame overlays

Task 4: Implement Page Frame Component

Create the individual page frame component with header, footer, and footnote wells.

• Create src/react/components/PageFrame.tsx accepting page data and position props
• Render header region at top of frame with configured height
• Render footer region at bottom of frame with configured height
• Render footnote well above footer, sized dynamically based on allocated footnotes
• Apply page border/shadow styling for visual page boundary indication

Task 5: Implement Footnote Portaling

Handle footnote definitions being hidden in main flow and displayed in page wells.

• Create src/react/components/FootnotePortal.tsx for rendering footnotes in wells
• Use CSS to hide footnoteDefinition elements in the main editor flow (visibility: hidden)
• For each page's allocated footnotes, render the definition content in that page's footnote well
• Maintain proper footnote numbering/reference linking across pages

Task 6: Create Page Layout Hook

Implement the hook that manages pagination state and triggers re-computation.

• Create src/react/hooks/usePageLayout.ts managing the derived Page[] state
• Subscribe to editor changes and trigger repagination on content mutations
• Debounce/throttle repagination using rAF coalescing for performance
• Handle viewport resize events to trigger repagination with new dimensions
• Target ≥55fps editing performance as per acceptance criteria

🤖 Prompt for AI agents

Implement the React layer for the pagination package, lifting base plugins to
React and building the visual overlay rendering system with pretext integration.
The key change from the previous plan is that the overlay uses
`render.aboveSlate` (wrapping the entire Slate provider) instead of
`render.afterEditable`.

**Lift Plugins to React**:
- `src/react/PaginationPlugin.tsx`: use `toTPlatePlugin(BasePaginationPlugin,
{...})`, compose `HeaderPlugin`, `FooterPlugin`, `PageBreakPlugin` as child
plugins, and register `render.aboveSlate: PageOverlay`
- `src/react/HeaderPlugin.tsx`, `FooterPlugin.tsx`, `PageBreakPlugin.tsx`: thin
`toPlatePlugin` wrappers around their respective base plugins

**Pretext Measurer Hook** (`src/react/hooks/usePretextMeasurer.ts`):
- Return a `Measurer` function
- Call `pretext.prepare()` once per unique `(nodeId, marksFingerprint, font,
width)` tuple
- Use `prepareRichInline` for nodes with mixed marks (bold + italic runs)
- Implement rAF coalescing to batch `pretext.layout()` calls per animation frame
- Snap system-ui font to named font (Inter) as fallback
- Memoize results using the measure cache from the internal helpers

**Page Overlay Component** (`src/react/components/PageOverlay.tsx`):
- Used as the `aboveSlate` wrapper component; receives `children` (the Slate
provider subtree)
- Use `useEditorRef()` and `useEditorContainerRef()` from PlateStore to access
the editor and container dimensions
- Call `paginate()` with the pretext measurer to compute current pages
- Render a positioned wrapper `div` (with `position: relative`) containing both
the `children` and absolutely-positioned `PageFrame` components to establish the
containing block for overlays

**Page Frame Component** (`src/react/components/PageFrame.tsx`):
- Accept page data and position props
- Render header region at top with configured height
- Render footer region at bottom with configured height
- Render footnote well above footer, dynamically sized based on allocated
footnotes
- Apply page border/shadow styling for visual page boundary indication

**Footnote Portal Component** (`src/react/components/FootnotePortal.tsx`):
- Use CSS `visibility: hidden` to hide `footnoteDefinition` elements in the main
editor flow
- Render definition content for each page's allocated footnotes inside that
page's footnote well
- Maintain proper footnote numbering/reference linking across pages

**Page Layout Hook** (`src/react/hooks/usePageLayout.ts`):
- Manage derived `Page[]` state
- Subscribe to editor changes and trigger repagination on content mutations
- Debounce/throttle repagination using rAF coalescing for performance
- Handle viewport resize events to trigger repagination with new dimensions
- Target ≥55fps editing performance

Phase 4: Print Mode Support

Implement alternative rendering for print that swaps the overlay for real DOM page sections.

Task 1: Create Print Pagination Component

Implement the print-specific renderer that outputs proper page section elements.

• Create src/react/components/PrintPagination.tsx that replaces PageOverlay in print mode
• Render actual <section class="page"> DOM elements instead of overlay frames
• Use same paginate() algorithm to determine page boundaries
• Insert content into proper page sections with headers/footers as real DOM children
• This is a complete swap of the rendering approach — overlay is removed, real sectioned DOM is rendered

Task 2: Add Print CSS Styles

Implement the CSS rules for print media that honor page breaks.

• Create print styles with @media print { .page { page-break-after: always; } }
• Hide overlay chrome in print mode (only show sectioned content)
• Ensure pretext-derived breaks match Chromium print preview within ±1 line tolerance
• Handle header/footer repetition per printed page

Task 3: Add Print Mode Toggle

Enable switching between overlay mode and print mode.

• Add printMode option to PaginationConfig
• When printMode: true, swap PageOverlay for PrintPagination component
• Expose editor.api.pagination.setPrintMode(boolean) for programmatic control
• Consider auto-detection of print context via window.matchMedia('print')

🤖 Prompt for AI agents

Implement print mode support for the pagination package, providing a complete
swap of the rendering approach from overlays to real DOM page sections.

**Print Pagination Component** (`src/react/components/PrintPagination.tsx`):
- Completely replaces `PageOverlay` when print mode is active (not an addition —
a full swap)
- Render actual `<section class="page">` DOM elements instead of overlay frames
- Reuse the same `paginate()` algorithm to determine page boundaries
- Insert content into page sections with headers/footers as real DOM children

**Print CSS Styles**:
- Create print styles: `@media print { .page { page-break-after: always; } }`
- Hide overlay chrome in print mode (only show sectioned content)
- Ensure pretext-derived breaks match Chromium print preview within ±1 line
tolerance
- Handle header/footer repetition per printed page

**Print Mode Toggle**:
- Add `printMode` option to `PaginationConfig`
- When `printMode: true`, swap `PageOverlay` for `PrintPagination` in the
`render.aboveSlate` slot
- Expose `editor.api.pagination.setPrintMode(boolean)` for programmatic control
- Consider auto-detection of print context via `window.matchMedia('print')`

Phase 5: Finalization & Integration

Complete the API surface, add tests, and prepare for release.

Task 1: Implement Full API Surface

Wire up all API methods and transforms to the pagination algorithm.

• Implement editor.api.pagination.getPages() returning current Page[]
• Implement editor.api.pagination.getPageOf(path) returning page index for a node
• Implement editor.api.pagination.getFootnotes(pageIndex) returning footnotes for a page
• Implement editor.tf.pagination.insertPageBreak() inserting a manual break
• Implement editor.tf.pagination.setHeader/setFooter(content) updating page chrome

Task 2: Add Unit Tests

Create tests for the pure pagination logic.

• Create src/lib/__tests__/paginate.spec.ts with fake monospace measurer
• Test page boundary calculation with various content lengths
• Test manual page break handling
• Test footnote allocation across pages
• Test edge cases: empty doc, single block, oversized blocks

Task 3: Create Changeset

Document the new package for release.

• Create .changeset/pagination-plugin.md with "@platejs/pagination": patch
• Use imperative voice describing user-visible changes: "Add PaginationPlugin with render-time page overlay..."
• Single package per changeset file per repository rules

🤖 Prompt for AI agents

Complete the pagination package by wiring up the full API surface, adding unit
tests for pure logic, and creating the release changeset.

**Full API Surface** (wire up stubs from Phase 2):
- `editor.api.pagination.getPages()`: return current `Page[]` derived from the
pagination algorithm
- `editor.api.pagination.getPageOf(path)`: return the page index for a given
node path
- `editor.api.pagination.getFootnotes(pageIndex)`: return footnotes allocated to
a given page
- `editor.tf.pagination.insertPageBreak()`: insert a manual page break node at
the current selection
- `editor.tf.pagination.setHeader(content)` / `setFooter(content)`: update page
chrome content

**Unit Tests** (`src/lib/__tests__/paginate.spec.ts`):
- Use a fake monospace measurer (returns deterministic values)
- Test: page boundary calculation with various content lengths
- Test: manual `pageBreak` node forces a new page
- Test: footnote allocation across multiple pages
- Test edge cases: empty document, single block, blocks larger than one page

**Changeset**:
- Create `.changeset/pagination-plugin.md` with `"@platejs/pagination": patch`
- Write in imperative voice: "Add PaginationPlugin with render-time page
overlay..."
- One package per changeset file, following repository rules

Research

The Plate codebase follows a Slate-first, Plate-second architecture where semantic base plugins are created in src/lib/ using createTSlatePlugin, then lifted to React via toTPlatePlugin in src/react/. The render.aboveSlate slot allows plugins to wrap the entire <Slate> provider, enabling chrome overlays that position relative to the editor container. The packages/footnote/ package already provides BaseFootnoteDefinitionPlugin, BaseFootnoteReferencePlugin, and BaseFootnoteInputPlugin which this implementation will compose rather than re-author. Plugin keys are centralized in packages/utils/src/lib/plate-keys.ts. External libraries are added as regular dependencies (not peer dependencies).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the `@platejs/pagination` package infrastructure from scratch, following
the established Plate monorepo patterns.

- Create `packages/pagination/` with a `package.json` using the standard
template, including dual exports for `.` and `./react`. Add `pretext` as a
regular dependency (not peer dependency), following the `@platejs/floating`
pattern.
- Create `tsconfig.json` and `tsconfig.build.json` files extending the shared
tooling configs used by other packages.
- Create the directory structure: `src/lib/`, `src/react/`, `src/internal/`.
- Run `pnpm brl` to generate barrel files after scaffolding.
- In `packages/utils/src/lib/plate-keys.ts`, add `pagination`, `header`,
`footer`, and `pageBreak` keys to the `NODES` object. Do not modify existing
footnote keys.
- Create `src/lib/types.ts` with the following type definitions:
- `PaginationConfig`: extends `PluginConfig` with options `pageSize`, `margins`,
`headerHeight`, `footerHeight`, `footnoteWell`
- `Page`: interface with `startIndex`, `endIndex`, `headerContent`,
`footerContent`, `footnotes`
- `Measurer`: function type `(text: string, font: FontConfig, width: number) =>
number`
- `PageSize`: type with presets (A4, Letter, Legal, etc.) as width/height in
pixels at 96 DPI
===============================================================================

Task: 2

Implement the framework-agnostic Slate layer for the pagination package,
including base plugins, the pure pagination algorithm, footnote allocation, and
internal utilities.

**BasePaginationPlugin** (`src/lib/BasePaginationPlugin.ts`):
- Use `createTSlatePlugin<PaginationConfig>` with `key: KEYS.pagination` and
`node: { isElement: true, isVoid: true }`
- Define options: `pageSize` (default A4), `margins`, `headerHeight`,
`footerHeight`, `footnoteWell`, `enabled`
- Stub out API: `getPages`, `getPageOf`, `getFootnotes`, `measure`
- Stub out transforms: `insertPageBreak`, `setHeader`, `setFooter`,
`recomputePages`

**Sibling Base Plugins**:
- `src/lib/BaseHeaderPlugin.ts`: element plugin, `key: KEYS.header`, using
`createSlatePlugin`
- `src/lib/BaseFooterPlugin.ts`: element plugin, `key: KEYS.footer`, using
`createSlatePlugin`
- `src/lib/BasePageBreakPlugin.ts`: void inline element, `key: KEYS.pageBreak`,
using `createSlatePlugin`

**Pure Pagination Algorithm** (`src/lib/paginate.ts`):
- Signature: `paginate(doc, ctx, measurer) -> Page[]`
- `ctx` contains page dimensions, margins, header/footer heights, footnote well
height
- `measurer` is injected to keep algorithm React-free and unit-testable
- Iterate through `editor.children`, accumulate block heights, create new page
when capacity exceeded
- Manual `pageBreak` nodes force a new page
- Return array of `Page` objects with block ranges and content assignments

**Footnote Allocation** (`src/lib/allocate-footnotes.ts`):
- Signature: `allocateFootnotes(pages, footnoteRefs, doc) -> Page[]`
- For each `footnoteReference`, determine its containing page
- Assign the matching `footnoteDefinition` to that page's footnote well
- Recalculate page breaks if footnote content overflows the well (iterative
allocation)
- Handle footnote overflow to subsequent pages

**Internal Helpers**:
- `src/internal/font-from-style.ts`: extract font config from Slate node
marks/styles
- `src/internal/measure-cache.ts`: LRU cache keyed by `(nodeId,
marksFingerprint, font, width)`
- `src/internal/marks-fingerprint.ts`: deterministic hash of a node's marks
- `src/internal/page-size-presets.ts`: A4, Letter, Legal dimensions at 96 DPI
===============================================================================

Task: 3

Implement the React layer for the pagination package, lifting base plugins to
React and building the visual overlay rendering system with pretext integration.
The key change from the previous plan is that the overlay uses
`render.aboveSlate` (wrapping the entire Slate provider) instead of
`render.afterEditable`.

**Lift Plugins to React**:
- `src/react/PaginationPlugin.tsx`: use `toTPlatePlugin(BasePaginationPlugin,
{...})`, compose `HeaderPlugin`, `FooterPlugin`, `PageBreakPlugin` as child
plugins, and register `render.aboveSlate: PageOverlay`
- `src/react/HeaderPlugin.tsx`, `FooterPlugin.tsx`, `PageBreakPlugin.tsx`: thin
`toPlatePlugin` wrappers around their respective base plugins

**Pretext Measurer Hook** (`src/react/hooks/usePretextMeasurer.ts`):
- Return a `Measurer` function
- Call `pretext.prepare()` once per unique `(nodeId, marksFingerprint, font,
width)` tuple
- Use `prepareRichInline` for nodes with mixed marks (bold + italic runs)
- Implement rAF coalescing to batch `pretext.layout()` calls per animation frame
- Snap system-ui font to named font (Inter) as fallback
- Memoize results using the measure cache from the internal helpers

**Page Overlay Component** (`src/react/components/PageOverlay.tsx`):
- Used as the `aboveSlate` wrapper component; receives `children` (the Slate
provider subtree)
- Use `useEditorRef()` and `useEditorContainerRef()` from PlateStore to access
the editor and container dimensions
- Call `paginate()` with the pretext measurer to compute current pages
- Render a positioned wrapper `div` (with `position: relative`) containing both
the `children` and absolutely-positioned `PageFrame` components to establish the
containing block for overlays

**Page Frame Component** (`src/react/components/PageFrame.tsx`):
- Accept page data and position props
- Render header region at top with configured height
- Render footer region at bottom with configured height
- Render footnote well above footer, dynamically sized based on allocated
footnotes
- Apply page border/shadow styling for visual page boundary indication

**Footnote Portal Component** (`src/react/components/FootnotePortal.tsx`):
- Use CSS `visibility: hidden` to hide `footnoteDefinition` elements in the main
editor flow
- Render definition content for each page's allocated footnotes inside that
page's footnote well
- Maintain proper footnote numbering/reference linking across pages

**Page Layout Hook** (`src/react/hooks/usePageLayout.ts`):
- Manage derived `Page[]` state
- Subscribe to editor changes and trigger repagination on content mutations
- Debounce/throttle repagination using rAF coalescing for performance
- Handle viewport resize events to trigger repagination with new dimensions
- Target ≥55fps editing performance
===============================================================================

Task: 4

Implement print mode support for the pagination package, providing a complete
swap of the rendering approach from overlays to real DOM page sections.

**Print Pagination Component** (`src/react/components/PrintPagination.tsx`):
- Completely replaces `PageOverlay` when print mode is active (not an addition —
a full swap)
- Render actual `<section class="page">` DOM elements instead of overlay frames
- Reuse the same `paginate()` algorithm to determine page boundaries
- Insert content into page sections with headers/footers as real DOM children

**Print CSS Styles**:
- Create print styles: `@media print { .page { page-break-after: always; } }`
- Hide overlay chrome in print mode (only show sectioned content)
- Ensure pretext-derived breaks match Chromium print preview within ±1 line
tolerance
- Handle header/footer repetition per printed page

**Print Mode Toggle**:
- Add `printMode` option to `PaginationConfig`
- When `printMode: true`, swap `PageOverlay` for `PrintPagination` in the
`render.aboveSlate` slot
- Expose `editor.api.pagination.setPrintMode(boolean)` for programmatic control
- Consider auto-detection of print context via `window.matchMedia('print')`
===============================================================================

Task: 5

Complete the pagination package by wiring up the full API surface, adding unit
tests for pure logic, and creating the release changeset.

**Full API Surface** (wire up stubs from Phase 2):
- `editor.api.pagination.getPages()`: return current `Page[]` derived from the
pagination algorithm
- `editor.api.pagination.getPageOf(path)`: return the page index for a given
node path
- `editor.api.pagination.getFootnotes(pageIndex)`: return footnotes allocated to
a given page
- `editor.tf.pagination.insertPageBreak()`: insert a manual page break node at
the current selection
- `editor.tf.pagination.setHeader(content)` / `setFooter(content)`: update page
chrome content

**Unit Tests** (`src/lib/__tests__/paginate.spec.ts`):
- Use a fake monospace measurer (returns deterministic values)
- Test: page boundary calculation with various content lengths
- Test: manual `pageBreak` node forces a new page
- Test: footnote allocation across multiple pages
- Test edge cases: empty document, single block, blocks larger than one page

**Changeset**:
- Create `.changeset/pagination-plugin.md` with `"@platejs/pagination": patch`
- Write in imperative voice: "Add PaginationPlugin with render-time page
overlay..."
- One package per changeset file, following repository rules

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

[arthrod]

🥕 Forcing follow-up: #355 (Yjs axis) and #356 (DOCX axis) demand the comparative verdict you skipped. @coderabbitai please answer there.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue view 355 --repo arthrod/plate --json title,body,comments | jq '{title,body, comments: [.comments[].body]}'
gh issue view 356 --repo arthrod/plate --json title,body,comments | jq '{title,body, comments: [.comments[].body]}'

Length of output: 9276

---

🏁 Script executed:

#!/bin/bash
# Yjs package structure
echo "=== YJS PACKAGE ==="
tree packages/yjs/src --filelimit 40 2>/dev/null || find packages/yjs/src -type f | head -40

echo "=== YJS KEY FILES ==="
rg -n "withNormalize|normalize|onChange|onchange|editOnly|debounce" packages/yjs/src/ -l

echo "=== DOCX PACKAGE ==="
find packages -type d -name "docx" | head -5
find packages -type f -name "*.ts" | xargs grep -l "sectPr\|hdrRef\|ftrRef\|w:sect" 2>/dev/null | head -20

echo "=== FOOTNOTE PLUGIN ==="
find packages/footnote -type f -name "BaseFootnoteDefinitionPlugin.ts" | head -3

echo "=== withNormalizeNode in YJS ==="
rg -n "withNormalizeNode\|normalizeNode\|onChange" packages/yjs/src/ -A2 | head -60

echo "=== Yjs undo/redo/awareness ==="
rg -n "awareness\|UndoManager\|undo" packages/yjs/src/ | head -30

Length of output: 1393

---

🏁 Script executed:

#!/bin/bash
echo "=== withTYjs.ts ==="
cat packages/yjs/src/lib/withTYjs.ts

echo "=== withPlateYjs.ts ==="
cat packages/yjs/src/lib/withPlateYjs.ts

echo "=== BaseYjsPlugin.ts (onChange/normalize) ==="
rg -n "normalize\|onChange\|debounce\|editOnly\|transact" packages/yjs/src/lib/BaseYjsPlugin.ts | head -40

echo "=== withTYHistory.ts ==="
cat packages/yjs/src/lib/withTYHistory.ts | head -60

echo "=== DOCX sectPr handling ==="
find packages/docx -type f -name "*.ts" | xargs grep -l "sectPr\|hdrRef\|ftrRef\|header\|footer" 2>/dev/null | head -10

echo "=== docx-io sectPr ==="
cat packages/docx-io/src/lib/internal/schemas/document.template.ts | head -80

echo "=== DOCX package structure ==="
find packages/docx/src -type f | head -40

echo "=== footnote definition plugin ==="
cat packages/footnote/src/lib/BaseFootnoteDefinitionPlugin.ts

Length of output: 7737

---

🏁 Script executed:

#!/bin/bash

gh issue comment 355 --repo arthrod/plate --body "## Verdict: **A**

**Canonical sentence:** If per-client liquid pagination (no Yjs sync overhead) matters more than identical page boundaries across all connected clients, variant A wins; otherwise B.

**Justification (2 lines):**
\`withTYHistory\` (\`packages/yjs/src/lib/withTYHistory.ts:32\`) wraps \`@slate-yjs/core\`'s \`withYHistory\` — every \`editor.apply()\` call from B's \`withNormalizeNode\` becomes a tracked Yjs transaction synced to all peers; \`BaseYjsPlugin.ts\` has zero debounce/editOnly/transact guards, so auto-inserted \`page_break\` nodes on every keystroke = O(pages) Yjs ops per edit = sync storm confirmed.

**Consistent with `#356` verdict:** Yes — both axes resolve to **A**."

gh issue comment 356 --repo arthrod/plate --body "## 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**."

Length of output: 136

---

@arthrod Done. Verdicts posted on both issues. Both axes resolve to A:

#355 (Yjs): withTYHistory.ts:32 wraps @slate-yjs/core's withYHistory — B's withNormalizeNode auto-inserts page_break nodes on every keystroke, each becoming a tracked Yjs transaction. BaseYjsPlugin.ts has zero debounce/editOnly guards. Sync storm is structural, not fixable at the margin. A wins.

#356 (DOCX): docx-io/src/lib/internal/schemas/document.template.ts:27-35 emits only w:pgSz + w:pgMar — no w:hdrRef/w:ftrRef exists. B's "byte-stable round-trip" is fictional; you'd build the serialization either way, but B additionally forces schema migration on every existing document. A wins.

The two axes are consistent — not in tension.