Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant B — overlay store + sub-editors)

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant B of 3 parallel framings of the same goal.
Sibling variant(s): #384 and #386. Please compare and tell us which assumption is load-bearing.

My goal

Bring Plate's paged view to production parity with Word/Pages: page-layout state — margins, header/footer chrome and content, page-number position, first-page-different rule, and footnote placement (footer or document end) — becomes fully user-customizable via UI; clicking into a header or footer presents a friendly chrome shell instead of raw editable text; and the paged-view PlateStatic preview renders the same plugin surface as the live editor (currently AI, comments, suggestions, drag-handle, and other chrome-only or editOnly plugins are silently dropped by getElementOnlyStaticPlugins in packages/pagination/src/react/page-frame.tsx:322-362).

To do so, do this (variant B — overlay store + scoped chrome sub-editors)

1. Introduce pageLayoutStore (Zustand or React context, document-keyed by metadata) holding: margins, pageSize, headerHeight, footerHeight, footnoteWell, footnotePlacement, pageNumber: { region: 'header'|'footer', align, format, startAt, hideOnFirst }, firstPageDifferent: boolean, and IDs for chrome editors.
2. Header and footer become separate Plate editor instances mounted by PageOverlay instead of nodes in editor.children. Same plugin set as the body editor, scoped to a one-row content. State persists in document metadata, not in editor.children.
3. PageFrame (packages/pagination/src/react/page-frame.tsx) consumes the store; chrome regions render the live header/footer editors (paged mode) — not PlateStatic. The static filter now only matters for the print/PDF path, not for on-screen paged preview.
4. Selection UX: each chrome region is its own editor, so it gets its own focus state, toolbar, and a chrome shell label ("Header", "Footer", "First-page header"). Body editor visibly defocuses while chrome is active. No selection inside the body ever lands inside chrome → no "ugly text" artifact.
5. "First page different" → store flag mounts a second header editor + second footer editor; PageFrame swaps which to render based on page.pageIndex === 0.
6. Page number → independent slot inside chrome regions, positioned by store config; rendered as a non-editable React element, not a Slate void, so users cannot accidentally move/delete it via body selection.
7. Margin customization → Page Setup dialog mutates the store; PageOverlay re-renders. Same dialog UX as variant A but writes to the store, not editor options.
8. Footnote placement → store flag drives paginate.ts which path to take; allocator stays the same.
9. Print/PDF (PlateStatic) path: wraps body + each chrome editor in PlateStatic with the existing static-safe filter. The filter still drops some plugins for print, but on-screen paged editing is no longer affected.

Acceptance: in dev-browser, paged mode shows live, fully-functional header/footer editors (typing in header works without "ugly text"); selecting a chrome region focuses it with a label; first page can have a different header; page-number position is store-driven; Page Setup dialog edits margins/heights/footnote placement; on-screen paged preview renders ALL live editor plugins (AI, comments, suggestions, drag-handle) inside body since it is a real editor, not PlateStatic.

Because the code is

• packages/pagination/src/react/page-frame.tsx:107-158 — chrome regions today render via StaticPageValue (PlateStatic); replacing those with live sub-editors removes the static-filter surface for paged preview entirely.
• packages/pagination/src/react/page-frame.tsx:322-362 — getElementOnlyStaticPlugins is the source of "PlateStatic page viewer doesn't render several plugins". Variant B sidesteps it for paged preview by not using PlateStatic there.
• packages/pagination/src/lib/transforms/ensureHeader.ts / ensureFooter.ts — body-coupled chrome nodes; variant B stops persisting chrome inside editor.children, removing the need for these invariants.
• packages/pagination/src/lib/types.ts — BasePaginationOptions becomes a thin pointer to pageLayoutStore for runtime; backward-compat shim keeps setMargins/setMode etc. as transforms that proxy into the store.
• packages/pagination/src/react/use-pretext-measurer.ts — measurer is read-only over body content; unaffected by chrome sub-editors.
• packages/pagination/src/lib/paginate.ts — needs a small change: skip body-internal header/footer when computing page allocation since they no longer live in the body.

Assumptions deliberately shuffled vs variant A

Axis	Variant B	Variant A
Where layout state lives	external pageLayoutStore + scoped chrome sub-editors	editor.options + editor.children (chrome nodes)
Header/footer kind	separate Plate editors mounted by PageOverlay	top-level Slate nodes inside the body editor
Trigger for layout changes	render-time over the body editor	edit-time / option-set-time on the body editor
First-page-different	store flag swaps which chrome editor mounts on page 1	optional firstPageHeader/firstPageFooter node types
PlateStatic plugin coverage	sub-editors render natively in paged mode → ALL plugins work	per-plugin staticSafe opt-in extends the static filter
Reversibility	easy — store can be retired; chrome editors collapse back to body nodes	hard — schema migration if first-page nodes ship and are later removed
Body-editor cleanliness	body has zero chrome nodes	body owns chrome nodes
Implementation surface	new sub-editor mounts, store, overlay coordination, persistence shim	extends existing types + adds ChromeShell + 1 dialog
DOCX round-trip	adapter must merge store + chrome editor values	adapter reads body chrome nodes + options

Assumptions deliberately shuffled vs variant C

Axis	Variant B	Variant C
Where chrome lives	external store + sub-editor instances	ID-keyed chrome registry referenced from Section.sectPr nodes
Granularity	document-level	per-section
Data model	bespoke store shape	OOXML-shaped (sectPr, pgNumType, titlePg, footnotePr)
First-page-different	store flag	titlePg + titlePgHdrRef/titlePgFtrRef
DOCX round-trip	adapter on store	near-direct mapping
Reversibility	easy	medium (sections persist)
Section model	none — single section assumed	first-class multi-section

Validate this approach — especially but not limited to

• Static analysis of packages/pagination/src/react/page-frame.tsx, packages/pagination/src/react/page-overlay.tsx, packages/pagination/src/react/standard-frame.tsx, packages/pagination/src/lib/paginate.ts, packages/pagination/src/lib/transforms/, packages/pagination/src/lib/allocate-footnotes.ts.
• Review of our own code in packages/pagination/src/react/, packages/core/src/static/components/PlateStatic.tsx, apps/www/src/registry/components/editor/plugins/pagination-kit.tsx.
• Comparative analysis vs sibling Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant A — schema-first) #384 and Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant C — OOXML section model) #386 — name the load-bearing assumption as a single sentence in the form "If matters more than , variant <A|B|C> wins; otherwise the other." Do not pick a winner yet — name the axis. Specifically: is the load-bearing question "is mounting N+ live Plate editors per document acceptable for performance / shared selection / undo coherence" (→ if yes, B; if no, A), and is "do we need DOCX section-level fidelity" (→ if yes, C) orthogonal to that?
• Mounting one extra Plate editor per chrome region (potentially ×2 with first-page-different) — what's the perf cost, undo-stack story, copy/paste behavior between body and chrome?
• How do shared concerns (comments, AI suggestions, search) work across body + chrome editors? Is there a multi-editor coordination layer this assumes?
• Does removing chrome from editor.children break existing DOCX export adapters that read header/footer from those nodes?
• Persistence: where does pageLayoutStore actually live in user data — document JSON metadata, separate field, server-side?

Full plan

1. Define pageLayoutStore shape + persistence contract (document metadata field).
2. Build chrome sub-editor mount in PageOverlay; one editor per chrome ID, plugin set inherited from body.
3. Refactor PageFrame chrome regions to render sub-editors instead of StaticPageValue.
4. Update paginate.ts to ignore body-internal header/footer and consume store.
5. Add firstPageDifferent swap logic in PageOverlay based on page.pageIndex.
6. Wire Page Setup dialog to mutate store; keep editor.tf.pagination.* transforms as proxies for back-compat.
7. Build chrome shell (label + focus border + exit affordance) around each chrome sub-editor.
8. Page-number renders as non-editable React element inside chrome region per store config.
9. Print/PDF path wraps body + chrome editors in PlateStatic; on-screen paged preview no longer touches PlateStatic.
10. Migrate DOCX adapter to read store + chrome editor values; provide one-time migration from body chrome nodes to store.
11. dev-browser verification of all seven user-reported issues.

References

• packages/pagination/src/react/page-frame.tsx
• packages/pagination/src/react/page-overlay.tsx
• packages/pagination/src/lib/paginate.ts
• packages/pagination/src/lib/transforms/ensureHeader.ts
• packages/core/src/static/components/PlateStatic.tsx
• branch codex/pagination-variant-a

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

Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant A — schema-first) (#384)

Similarity score: 98%

This comment was generated by Kilo Auto-Triage.

[arthrod]

🥕 Sibling variants: #384 (schema-first) and #386 (OOXML section model). Same goal — paged-view production parity. Different assumptions on layer / state location / DOCX fidelity. Please compare the family before recommending; don't review in isolation.

[coderabbitai]

Coding Plan

Summary

• External pageLayoutStore (Zustand) replaces BasePaginationOptions for layout state, enabling reactive updates and clean persistence in document metadata
• Header/footer become separate Plate editor instances mounted by PageOverlay, eliminating selection collision with body content and enabling full plugin support in paged preview
• PageFrame chrome regions render live sub-editors wrapped in ChromeShell components with focus labels, replacing static text extraction
• First-page-different support via store flag that swaps which chrome editor renders on page 1; page numbers render as non-editable React elements positioned by store config

Design Choices

Design Choice 1: Performance of multiple Plate editors per document

Options Considered:

1. Accept multi-editor overhead for clean separation and full plugin support
2. Use a single editor with complex selection gating (Variant A approach)

Chosen Option: 1

Rationale: Chrome editors are tiny and the isolation benefits (no selection collision, separate undo, full plugin surface) outweigh the mount cost.

Design Choice 2: Undo/redo coherence across body and chrome editors

Options Considered:

1. Accept separate undo stacks per editor (simpler, matches Word behavior)
2. Build a unified undo coordinator across all editors (complex, non-standard)

Chosen Option: 1

Rationale: Word/Pages treat header/footer as separate undo contexts; users expect this. Cross-editor undo coordination is out of scope.

Design Choice 3: Persistence of pageLayoutStore data

Options Considered:

1. Store in a top-level document metadata field alongside children
2. Store in a separate database field
3. Store in localStorage (not portable)

Chosen Option: 1

Rationale: A pageLayout metadata field in the document JSON keeps everything portable and enables standard save/load.

Design Choice 4: Copy/paste between body and chrome editors

Options Considered:

1. Rely on system clipboard (HTML/plaintext) for cross-editor paste
2. Build custom clipboard bridge between editors

Chosen Option: 1

Rationale: System clipboard is sufficient; both editors serialize/deserialize identically since they share plugins.

💡 User Tips

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

Implementation Steps

Phase 1: Page Layout Store Foundation

Establish the external state layer that replaces BasePaginationOptions for layout configuration. This store becomes the single source of truth for page geometry, chrome configuration, and feature flags.

Task 1: Create pageLayoutStore Zustand Store

Define the store shape and create the Zustand store with all layout configuration fields.

• Create packages/pagination/src/react/stores/page-layout-store.ts with Zustand store
• Store shape: margins: PageMargins, pageSize: PageSize, headerHeight, footerHeight, footnoteWell, footnotePlacement: 'page' | 'documentEnd', pageNumber: { region, align, format, startAt, hideOnFirst }, firstPageDifferent: boolean
• Include chrome editor IDs: headerEditorId, footerEditorId, firstPageHeaderEditorId, firstPageFooterEditorId
• Export typed hooks: usePageLayoutStore, usePageLayoutValue, usePageLayoutActions

Task 2: Create PageLayoutProvider Context

Wrap the store in a React context provider for scoped access within the pagination overlay.

• Create packages/pagination/src/react/stores/PageLayoutProvider.tsx
• Provider accepts initial values from document metadata and creates store instance
• Export usePageLayout() hook that throws if used outside provider
• Support for document-keyed instances (store per document)

Task 3: Define Persistence Contract

Establish how store state serializes to/from document metadata.

• Define PageLayoutMetadata type in packages/pagination/src/lib/types.ts
• Add serializePageLayout() and deserializePageLayout() utilities
• Store chrome editor content as serialized Slate value arrays in metadata
• Update BasePaginationOptions to accept optional initialPageLayout for hydration

🤖 Prompt for AI agents

Implement the Page Layout Store Foundation, which establishes the external
Zustand-based state layer to replace `BasePaginationOptions` for all layout
configuration.

**Task 1: Create `packages/pagination/src/react/stores/page-layout-store.ts`**
- Define and create a Zustand store with the following shape:
  - `margins: PageMargins`
  - `pageSize: PageSize`
  - `headerHeight`, `footerHeight`, `footnoteWell`
  - `footnotePlacement: 'page' | 'documentEnd'`
  - `pageNumber: { region, align, format, startAt, hideOnFirst }`
  - `firstPageDifferent: boolean`
- Chrome editor IDs: `headerEditorId`, `footerEditorId`,
`firstPageHeaderEditorId`, `firstPageFooterEditorId`
- Export typed hooks: `usePageLayoutStore`, `usePageLayoutValue`,
`usePageLayoutActions`

**Task 2: Create `packages/pagination/src/react/stores/PageLayoutProvider.tsx`**
- Wrap the Zustand store in a React context provider for scoped access
- Provider accepts initial values from document metadata and creates a store
instance
- Export a `usePageLayout()` hook that throws if used outside the provider
- Support document-keyed instances (one store per document)

**Task 3: Define persistence contract in
`packages/pagination/src/lib/types.ts`**
- Define the `PageLayoutMetadata` type
- Add `serializePageLayout()` and `deserializePageLayout()` utility functions
- Chrome editor content should be stored as serialized Slate value arrays in
metadata
- Update `BasePaginationOptions` to accept an optional `initialPageLayout` field
for hydration

Phase 2: Chrome Sub-Editor Infrastructure

Create the machinery to mount separate Plate editor instances for header/footer regions, inheriting the body editor's plugin configuration.

Task 1: Create Chrome Editor Factory

Build a factory function that creates configured Plate editors for chrome regions.

• Create packages/pagination/src/react/chrome/createChromeEditor.ts
• Accept parent editor's plugin list and filter to element/leaf plugins only
• Generate unique editor IDs scoped to parent editor (e.g., ${bodyEditorId}-header)
• Initialize with single-paragraph content constraint
• Return configured PlateEditor instance ready for mounting

Task 2: Build ChromeEditorMount Component

Create the component that mounts a Plate editor instance for a chrome region.

• Create packages/pagination/src/react/chrome/ChromeEditorMount.tsx
• Accept editorId, initialValue, plugins, onChange props
• Render <Plate> with <PlateContent> sized to chrome region dimensions
• Apply single-line content constraints (prevent multi-block)
• Style for seamless integration (no visible editor chrome by default)

Task 3: Implement Focus Coordination

Coordinate focus states between body editor and chrome editors.

• Create packages/pagination/src/react/chrome/useChromeEditorFocus.ts
• Track which editor (body or which chrome) is currently active
• When chrome editor gains focus, visually defocus body editor
• When body editor gains focus, blur active chrome editor
• Use PlateController patterns for cross-editor awareness

🤖 Prompt for AI agents

Implement the Chrome Sub-Editor Infrastructure, building the machinery to mount
separate Plate editor instances for header/footer regions that inherit the body
editor's plugin configuration.

**Task 1: Create `packages/pagination/src/react/chrome/createChromeEditor.ts`**
- Build a factory function that creates configured Plate editors for chrome
regions
- Accept the parent editor's plugin list and filter to element/leaf plugins only
- Generate unique editor IDs scoped to the parent editor (e.g.,
`${bodyEditorId}-header`)
- Initialize with a single-paragraph content constraint
- Return a configured `PlateEditor` instance ready for mounting

**Task 2: Create `packages/pagination/src/react/chrome/ChromeEditorMount.tsx`**
- Accept props: `editorId`, `initialValue`, `plugins`, `onChange`
- Render `<Plate>` with `<PlateContent>` sized to the chrome region dimensions
- Apply single-line content constraints (prevent multi-block)
- Style for seamless integration (no visible editor chrome by default)

**Task 3: Create
`packages/pagination/src/react/chrome/useChromeEditorFocus.ts`**
- Track which editor (body or a specific chrome editor) is currently active
- When a chrome editor gains focus, visually defocus the body editor
- When the body editor gains focus, blur the active chrome editor
- Use `PlateController` patterns for cross-editor awareness

Phase 3: PageFrame Chrome Region Refactor

Transform PageFrame from rendering static text to mounting live sub-editors for chrome regions.

Task 1: Create ChromeShell Component

Build the visual wrapper that surrounds chrome editors with label and focus affordances.

• Create packages/pagination/src/react/chrome/ChromeShell.tsx
• Render label ("Header", "Footer", "First-page header") when focused
• Show focus ring/border on active chrome region
• Include exit affordance (click outside or Escape key)
• Accept children (the chrome editor) and label prop

Task 2: Refactor PageFrame Chrome Rendering

Replace inline text extraction with live sub-editor mounting.

• Update packages/pagination/src/react/page-frame.tsx
• Remove collectInlineText() usage for header/footer bands
• Header band: render ChromeShell + ChromeEditorMount for header editor
• Footer band: render ChromeShell + ChromeEditorMount for footer editor
• Consume store to determine which editor to render (regular vs first-page)
• Pass pageIndex to determine first-page swap

Task 3: Implement Page Number Component

Create non-editable page number element positioned within chrome regions.

• Create packages/pagination/src/react/chrome/PageNumber.tsx
• Read position config from store (region, align, format, startAt, hideOnFirst)
• Render as absolutely-positioned React element (not Slate void)
• Format options: arabic (1, 2, 3), roman (i, ii, iii), letter (a, b, c)
• Integrate into footer band positioning based on store config

🤖 Prompt for AI agents

Refactor the PageFrame chrome regions from static text rendering to live
sub-editor mounting, and add supporting UI components.

**Task 1: Create `packages/pagination/src/react/chrome/ChromeShell.tsx`**
- Visual wrapper surrounding chrome editors with label and focus affordances
- Accept `children` (the chrome editor) and a `label` prop
- Render the label (e.g., "Header", "Footer", "First-page header") when focused
- Show a focus ring/border on the active chrome region
- Include an exit affordance (click outside or Escape key)

**Task 2: Update `packages/pagination/src/react/page-frame.tsx`**
- Remove `collectInlineText()` usage for header/footer bands
- Header band: render `ChromeShell` + `ChromeEditorMount` for the header editor
- Footer band: render `ChromeShell` + `ChromeEditorMount` for the footer editor
- Consume the store to determine which editor to render (regular vs. first-page)
- Pass `pageIndex` to determine first-page swap

**Task 3: Create `packages/pagination/src/react/chrome/PageNumber.tsx`**
- Non-editable page number element positioned within chrome regions
- Read position config from the store: `region`, `align`, `format`, `startAt`,
`hideOnFirst`
- Render as an absolutely-positioned React element (not a Slate void)
- Support format options: arabic (1, 2, 3), roman (i, ii, iii), letter (a, b, c)
- Integrate into footer band positioning based on store config

Phase 4: PageOverlay and Paginate Updates

Update the overlay orchestration and pagination algorithm to work with store-based layout and chrome-free body content.

Task 1: Integrate PageLayoutProvider in PageOverlay

Mount the store provider at the root of the pagination overlay.

• Update packages/pagination/src/react/page-overlay.tsx
• Wrap overlay content with PageLayoutProvider
• Hydrate from document metadata or plugin options (back-compat)
• Create chrome editors lazily when overlay mounts
• Store chrome editor instances in refs for stable identity

Task 2: Update paginate.ts for Store-Based Layout

Modify the pagination algorithm to read from store and ignore body-internal chrome.

• Update packages/pagination/src/lib/paginate.ts
• Accept PageLayoutConfig instead of raw options
• Since chrome no longer lives in editor.children, remove header/footer/footnoteDefinition skip logic (only pageBreak remains special)
• Read footnotePlacement from config to determine allocation strategy

Task 3: Implement First-Page-Different Logic

Add swap logic for first-page chrome editors based on store flag.

• Update PageOverlay to conditionally create first-page chrome editors when firstPageDifferent is true
• Update PageFrame to check page.pageIndex === 0 and render first-page editors
• Ensure focus coordination handles the 4-editor case (2 headers + 2 footers)

🤖 Prompt for AI agents

Update the PageOverlay orchestration and pagination algorithm to work with
store-based layout and chrome-free body content.

**Task 1: Update `packages/pagination/src/react/page-overlay.tsx`**
- Wrap overlay content with `PageLayoutProvider`
- Hydrate the provider from document metadata or plugin options (for
back-compat)
- Create chrome editors lazily when the overlay mounts
- Store chrome editor instances in refs for stable identity

**Task 2: Update `packages/pagination/src/lib/paginate.ts`**
- Accept `PageLayoutConfig` instead of raw options
- Since chrome no longer lives in `editor.children`, remove
header/footer/footnoteDefinition skip logic (only `pageBreak` remains special)
- Read `footnotePlacement` from the config to determine the allocation strategy

**Task 3: Add first-page-different logic**
- Update `PageOverlay` to conditionally create first-page chrome editors when
`firstPageDifferent` is `true`
- Update `PageFrame` to check `page.pageIndex === 0` and render first-page
editors accordingly
- Ensure focus coordination handles the 4-editor case (2 headers + 2 footers)

Phase 5: Page Setup Dialog and Configuration UI

Build the user interface for customizing page layout settings.

Task 1: Create Page Setup Dialog Component

Build the primary dialog for margin and layout customization.

• Create packages/pagination/src/react/components/PageSetupDialog.tsx
• Tabbed interface: Page (size, orientation), Margins (top/bottom/left/right), Header/Footer (heights, first-page-different)
• Page size dropdown: A4, Letter, Legal, Custom
• Margin inputs with live preview thumbnail
• First-page-different checkbox
• Footnote placement radio: "Bottom of page" / "End of document"

Task 2: Create Page Number Settings Panel

Add page number configuration to the dialog.

• Extend Page Setup dialog with Page Number section
• Region selector: Header / Footer
• Alignment: Left / Center / Right
• Format dropdown: Arabic / Roman lowercase / Roman uppercase / Letter
• Start at input (number)
• Hide on first page checkbox
• Wire to pageNumber field in store

Task 3: Wire Transform Proxies for Back-Compat

Keep editor.tf.pagination.* transforms working by proxying to store.

• Update packages/pagination/src/lib/base-pagination-plugin.ts
• setMargins() → calls usePageLayoutStore.getState().setMargins()
• setPageSize() → calls store action
• toggleHeader(), toggleFooter() → create/destroy chrome editors via store
• Ensure existing API consumers continue to work unchanged

🤖 Prompt for AI agents

Build the Page Setup Dialog UI for customizing page layout settings, and wire up
back-compat transform proxies.

**Task 1: Create
`packages/pagination/src/react/components/PageSetupDialog.tsx`**
- Tabbed interface with the following tabs:
  - **Page**: size (A4, Letter, Legal, Custom dropdown) and orientation
  - **Margins**: top/bottom/left/right inputs with a live preview thumbnail
  - **Header/Footer**: heights and first-page-different checkbox
- Footnote placement radio: "Bottom of page" / "End of document"

**Task 2: Extend `PageSetupDialog` with a Page Number section**
- Region selector: Header / Footer
- Alignment: Left / Center / Right
- Format dropdown: Arabic / Roman lowercase / Roman uppercase / Letter
- Start at input (number)
- Hide on first page checkbox
- Wire all fields to the `pageNumber` field in the store

**Task 3: Update `packages/pagination/src/lib/base-pagination-plugin.ts`**
- Keep `editor.tf.pagination.*` transforms working by proxying to the store:
  - `setMargins()` → `usePageLayoutStore.getState().setMargins()`
  - `setPageSize()` → corresponding store action
  - `toggleHeader()`, `toggleFooter()` → create/destroy chrome editors via store
- Ensure existing API consumers continue to work unchanged

Phase 6: Print/PDF Static Rendering Path

Ensure the static rendering path (print, PDF export) properly renders all editors.

Task 1: Create StaticPageRenderer Component

Build a component that renders all editors (body + chrome) via PlateStatic for print.

• Create packages/pagination/src/react/static/StaticPageRenderer.tsx
• Accept body editor value and chrome editor values
• Render each page with PlateStatic for body content slice
• Render chrome regions with PlateStatic for header/footer values
• Apply proper print styling (page breaks, margins)

Task 2: Implement Print/Export Integration

Wire the static renderer into print and export workflows.

• Create usePrintPaginatedDocument() hook
• Serialize current state of all editors (body + chrome)
• Open print dialog with StaticPageRenderer content
• Ensure page numbers render correctly in static output

🤖 Prompt for AI agents

Implement the static rendering path for print/PDF export, ensuring all editors
(body and chrome) are properly rendered.

**Task 1: Create `packages/pagination/src/react/static/StaticPageRenderer.tsx`**
- Accept body editor value and chrome editor values as props
- Render each page with `PlateStatic` for the body content slice
- Render chrome regions with `PlateStatic` for header/footer values
- Apply proper print styling (page breaks, margins)

**Task 2: Create the `usePrintPaginatedDocument()` hook**
- Serialize the current state of all editors (body + chrome)
- Open the print dialog with `StaticPageRenderer` content
- Ensure page numbers render correctly in static output

Phase 7: Migration and DOCX Adapter

Handle migration from body-node chrome to store-based chrome and update export adapters.

Task 1: Create Migration Utility

Build one-time migration from existing body chrome nodes to store format.

• Create packages/pagination/src/lib/migrations/migrateBodyChromeToStore.ts
• Detect header/footer nodes in editor.children
• Extract content to chrome editor initial values
• Remove nodes from body
• Generate PageLayoutMetadata with extracted content
• Provide runMigration() function for upgrade path

Task 2: Update DOCX Export Adapter

Modify DOCX export to read from store and chrome editors instead of body nodes.

• Update export flow in packages/docx-io/src/lib/docx-export-plugin.tsx
• Read header content from store's header editor value
• Read footer content from store's footer editor value
• Pass serialized HTML to headerHTMLString / footerHTMLString params
• Apply margins from store to DOCX page setup

Task 3: Remove Deprecated Body Chrome Logic

Clean up the now-unused body-coupled chrome infrastructure.

• Remove or deprecate ensureHeader.ts, ensureFooter.ts transforms
• Update enforceHeaderFooterInvariants to no-op or remove
• Keep transforms as no-ops with deprecation warnings for API stability
• Update paginate.ts to remove header/footer type checks from skip logic

🤖 Prompt for AI agents

Handle migration from body-node chrome to store-based chrome and update the DOCX
export adapter and deprecated logic.

**Task 1: Create
`packages/pagination/src/lib/migrations/migrateBodyChromeToStore.ts`**
- Detect header/footer nodes in `editor.children`
- Extract their content to chrome editor initial values
- Remove those nodes from the body
- Generate `PageLayoutMetadata` with the extracted content
- Provide a `runMigration()` function as the upgrade entry point

**Task 2: Update `packages/docx-io/src/lib/docx-export-plugin.tsx`**
- Read header content from the store's header editor value
- Read footer content from the store's footer editor value
- Pass serialized HTML to `headerHTMLString` / `footerHTMLString` params
- Apply margins from the store to DOCX page setup

**Task 3: Clean up deprecated body chrome infrastructure**
- Remove or deprecate `ensureHeader.ts` and `ensureFooter.ts` transforms
- Update `enforceHeaderFooterInvariants` to a no-op or remove it
- Keep deprecated transforms as no-ops with deprecation warnings for API
stability
- Update `paginate.ts` to remove header/footer type checks from skip logic

Research

The @platejs/pagination package implements a render-time overlay pagination system where pages are derived from editor.children without mutating the Slate document. Currently, header/footer are stored as top-level nodes in editor.children and rendered as plain text in PageFrame. PageOverlay mounts via render.afterEditable and displays scaled page thumbnails. The core package has PlateController for multi-editor coordination, and each <Plate> instance maintains its own scoped Jotai store. The existing multi-editor pattern supports independent editors with separate undo stacks, but no shared selection/decoration across editors exists.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the Page Layout Store Foundation, which establishes the external
Zustand-based state layer to replace `BasePaginationOptions` for all layout
configuration.

**Task 1: Create `packages/pagination/src/react/stores/page-layout-store.ts`**
- Define and create a Zustand store with the following shape:
  - `margins: PageMargins`
  - `pageSize: PageSize`
  - `headerHeight`, `footerHeight`, `footnoteWell`
  - `footnotePlacement: 'page' | 'documentEnd'`
  - `pageNumber: { region, align, format, startAt, hideOnFirst }`
  - `firstPageDifferent: boolean`
- Chrome editor IDs: `headerEditorId`, `footerEditorId`,
`firstPageHeaderEditorId`, `firstPageFooterEditorId`
- Export typed hooks: `usePageLayoutStore`, `usePageLayoutValue`,
`usePageLayoutActions`

**Task 2: Create `packages/pagination/src/react/stores/PageLayoutProvider.tsx`**
- Wrap the Zustand store in a React context provider for scoped access
- Provider accepts initial values from document metadata and creates a store
instance
- Export a `usePageLayout()` hook that throws if used outside the provider
- Support document-keyed instances (one store per document)

**Task 3: Define persistence contract in
`packages/pagination/src/lib/types.ts`**
- Define the `PageLayoutMetadata` type
- Add `serializePageLayout()` and `deserializePageLayout()` utility functions
- Chrome editor content should be stored as serialized Slate value arrays in
metadata
- Update `BasePaginationOptions` to accept an optional `initialPageLayout` field
for hydration
===============================================================================

Task: 2

Implement the Chrome Sub-Editor Infrastructure, building the machinery to mount
separate Plate editor instances for header/footer regions that inherit the body
editor's plugin configuration.

**Task 1: Create `packages/pagination/src/react/chrome/createChromeEditor.ts`**
- Build a factory function that creates configured Plate editors for chrome
regions
- Accept the parent editor's plugin list and filter to element/leaf plugins only
- Generate unique editor IDs scoped to the parent editor (e.g.,
`${bodyEditorId}-header`)
- Initialize with a single-paragraph content constraint
- Return a configured `PlateEditor` instance ready for mounting

**Task 2: Create `packages/pagination/src/react/chrome/ChromeEditorMount.tsx`**
- Accept props: `editorId`, `initialValue`, `plugins`, `onChange`
- Render `<Plate>` with `<PlateContent>` sized to the chrome region dimensions
- Apply single-line content constraints (prevent multi-block)
- Style for seamless integration (no visible editor chrome by default)

**Task 3: Create
`packages/pagination/src/react/chrome/useChromeEditorFocus.ts`**
- Track which editor (body or a specific chrome editor) is currently active
- When a chrome editor gains focus, visually defocus the body editor
- When the body editor gains focus, blur the active chrome editor
- Use `PlateController` patterns for cross-editor awareness
===============================================================================

Task: 3

Refactor the PageFrame chrome regions from static text rendering to live
sub-editor mounting, and add supporting UI components.

**Task 1: Create `packages/pagination/src/react/chrome/ChromeShell.tsx`**
- Visual wrapper surrounding chrome editors with label and focus affordances
- Accept `children` (the chrome editor) and a `label` prop
- Render the label (e.g., "Header", "Footer", "First-page header") when focused
- Show a focus ring/border on the active chrome region
- Include an exit affordance (click outside or Escape key)

**Task 2: Update `packages/pagination/src/react/page-frame.tsx`**
- Remove `collectInlineText()` usage for header/footer bands
- Header band: render `ChromeShell` + `ChromeEditorMount` for the header editor
- Footer band: render `ChromeShell` + `ChromeEditorMount` for the footer editor
- Consume the store to determine which editor to render (regular vs. first-page)
- Pass `pageIndex` to determine first-page swap

**Task 3: Create `packages/pagination/src/react/chrome/PageNumber.tsx`**
- Non-editable page number element positioned within chrome regions
- Read position config from the store: `region`, `align`, `format`, `startAt`,
`hideOnFirst`
- Render as an absolutely-positioned React element (not a Slate void)
- Support format options: arabic (1, 2, 3), roman (i, ii, iii), letter (a, b, c)
- Integrate into footer band positioning based on store config
===============================================================================

Task: 4

Update the PageOverlay orchestration and pagination algorithm to work with
store-based layout and chrome-free body content.

**Task 1: Update `packages/pagination/src/react/page-overlay.tsx`**
- Wrap overlay content with `PageLayoutProvider`
- Hydrate the provider from document metadata or plugin options (for
back-compat)
- Create chrome editors lazily when the overlay mounts
- Store chrome editor instances in refs for stable identity

**Task 2: Update `packages/pagination/src/lib/paginate.ts`**
- Accept `PageLayoutConfig` instead of raw options
- Since chrome no longer lives in `editor.children`, remove
header/footer/footnoteDefinition skip logic (only `pageBreak` remains special)
- Read `footnotePlacement` from the config to determine the allocation strategy

**Task 3: Add first-page-different logic**
- Update `PageOverlay` to conditionally create first-page chrome editors when
`firstPageDifferent` is `true`
- Update `PageFrame` to check `page.pageIndex === 0` and render first-page
editors accordingly
- Ensure focus coordination handles the 4-editor case (2 headers + 2 footers)
===============================================================================

Task: 5

Build the Page Setup Dialog UI for customizing page layout settings, and wire up
back-compat transform proxies.

**Task 1: Create
`packages/pagination/src/react/components/PageSetupDialog.tsx`**
- Tabbed interface with the following tabs:
  - **Page**: size (A4, Letter, Legal, Custom dropdown) and orientation
  - **Margins**: top/bottom/left/right inputs with a live preview thumbnail
  - **Header/Footer**: heights and first-page-different checkbox
- Footnote placement radio: "Bottom of page" / "End of document"

**Task 2: Extend `PageSetupDialog` with a Page Number section**
- Region selector: Header / Footer
- Alignment: Left / Center / Right
- Format dropdown: Arabic / Roman lowercase / Roman uppercase / Letter
- Start at input (number)
- Hide on first page checkbox
- Wire all fields to the `pageNumber` field in the store

**Task 3: Update `packages/pagination/src/lib/base-pagination-plugin.ts`**
- Keep `editor.tf.pagination.*` transforms working by proxying to the store:
  - `setMargins()` → `usePageLayoutStore.getState().setMargins()`
  - `setPageSize()` → corresponding store action
  - `toggleHeader()`, `toggleFooter()` → create/destroy chrome editors via store
- Ensure existing API consumers continue to work unchanged
===============================================================================

Task: 6

Implement the static rendering path for print/PDF export, ensuring all editors
(body and chrome) are properly rendered.

**Task 1: Create `packages/pagination/src/react/static/StaticPageRenderer.tsx`**
- Accept body editor value and chrome editor values as props
- Render each page with `PlateStatic` for the body content slice
- Render chrome regions with `PlateStatic` for header/footer values
- Apply proper print styling (page breaks, margins)

**Task 2: Create the `usePrintPaginatedDocument()` hook**
- Serialize the current state of all editors (body + chrome)
- Open the print dialog with `StaticPageRenderer` content
- Ensure page numbers render correctly in static output
===============================================================================

Task: 7

Handle migration from body-node chrome to store-based chrome and update the DOCX
export adapter and deprecated logic.

**Task 1: Create
`packages/pagination/src/lib/migrations/migrateBodyChromeToStore.ts`**
- Detect header/footer nodes in `editor.children`
- Extract their content to chrome editor initial values
- Remove those nodes from the body
- Generate `PageLayoutMetadata` with the extracted content
- Provide a `runMigration()` function as the upgrade entry point

**Task 2: Update `packages/docx-io/src/lib/docx-export-plugin.tsx`**
- Read header content from the store's header editor value
- Read footer content from the store's footer editor value
- Pass serialized HTML to `headerHTMLString` / `footerHTMLString` params
- Apply margins from the store to DOCX page setup

**Task 3: Clean up deprecated body chrome infrastructure**
- Remove or deprecate `ensureHeader.ts` and `ensureFooter.ts` transforms
- Update `enforceHeaderFooterInvariants` to a no-op or remove it
- Keep deprecated transforms as no-ops with deprecation warnings for API
stability
- Update `paginate.ts` to remove header/footer type checks from skip logic

💡 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]
#126 - feat: DOCX tracked changes and comments export [merged]
#170 - Cr [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!