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

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant A of 3 parallel framings of the same goal.
Sibling variant(s): #385 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 A — schema-first, options-driven)

1. Extend BasePaginationOptions in packages/pagination/src/lib/types.ts with: pageNumber: { side: 'header'|'footer', align: 'left'|'center'|'right', format: '1'|'1/N'|'Page 1 of N', startAt: number, hideOnFirst: boolean }, firstPageDifferent: boolean, and a per-side margin preset list.
2. Add optional top-level node types firstPageHeader and firstPageFooter (parallel to existing header/footer); paginate.ts selects them on page index 0 when firstPageDifferent is true.
3. Replace the hardcoded page-number span at packages/pagination/src/react/page-frame.tsx:156 with a <PageNumber/> block that consumes BasePaginationOptions.pageNumber. Page-number slot positions are computed inside the existing header / footer chrome bands — no new chrome region.
4. Wrap header/footer node renderers in a ChromeShell component (new file packages/pagination/src/react/chrome-shell.tsx) that, when the selection is inside the chrome node, shows a label (Header, Footer, First-page header), a dotted focus border, and an "Exit chrome" affordance. Plain reading mode is unchanged.
5. Promote MarginsDialog (already at packages/pagination/src/react/margins-dialog.tsx) to a real Page Setup dialog: per-axis numeric inputs, cm/in/mm/px unit toggle, page-size presets, header/footer height, footnote placement toggle, first-page-different toggle, page-number config — all calling existing editor.tf.pagination.setMargins/setMode/setPageSize/setFootnotePlacement plus new transforms setPageNumber and setFirstPageDifferent.
6. Footnote "end of document" path: keep existing footnotePlacement: 'documentEnd' semantics (packages/pagination/src/lib/allocate-footnotes.ts); ensure end-of-doc allocation renders inside the last page's content box, not below the page sheet.
7. Plug-the-PlateStatic-hole: introduce a per-plugin opt-in staticSafe?: boolean on the plugin descriptor. Update getElementOnlyStaticPlugins in page-frame.tsx to include any plugin where staticSafe === true even if editOnly or missing node.type. Migrate AI-comment / suggestion / drag-handle plugins to flip the flag and provide a static-render fallback. Plugins that do not opt in keep being dropped (status quo).

Acceptance: in dev-browser, paged mode shows configurable page numbers (top-right vs bottom-center), first page chrome can differ from rest, Page Setup dialog edits all four margins with cm units, footnote placement toggles between footer and end-of-document without losing definitions, header selection shows a labeled chrome shell, and at least three previously-dropped plugins (e.g. comments, suggestions, drag-handle) render in the paged-view PlateStatic preview after opting into staticSafe.

Because the code is

• packages/pagination/src/lib/types.ts — BasePaginationOptions already owns margins, mode, footnotePlacement, headerHeight, footerHeight, footnoteWell, pageBorder, pageSize. No pageNumber, no firstPageDifferent. Extending here is additive.
• packages/pagination/src/react/page-frame.tsx:156 — <span style={{ float: 'right' }}>{pageIndex + 1}</span> is the entire page-number implementation. Hardcoded.
• packages/pagination/src/react/page-frame.tsx:322-362 — getElementOnlyStaticPlugins drops plugins with no node.type, editOnly: true, or missing node.component, AND wipes every render slot. This is the explicit reason "PlateStatic page viewer doesn't render several plugins."
• packages/pagination/src/react/margins-dialog.tsx — minimal v1 native <dialog>; only edits the four margin sides. No page-size, no chrome heights, no first-page, no page-number.
• packages/pagination/src/lib/transforms/ensureHeader.ts / ensureFooter.ts / toggleHeader.ts / toggleFooter.ts — single doc-level header/footer node only. No first-page concept.
• packages/pagination/src/lib/allocate-footnotes.ts — already supports documentEnd placement; the gap is UI surfacing.
• packages/pagination/src/lib/base-pagination-plugin.ts — defines transforms; adding setPageNumber and setFirstPageDifferent here keeps the schema-first contract.

Assumptions deliberately shuffled vs variant B

Axis	Variant A	Variant B
Where layout state lives	editor.options + editor.children (chrome nodes)	external pageLayoutStore + scoped chrome sub-editors
Header/footer kind	top-level Slate nodes inside the body editor	separate Plate editors mounted by PageOverlay
Trigger for layout changes	edit-time / option-set-time on the body editor	render-time over the body editor
First-page-different	optional firstPageHeader/firstPageFooter node types	store flag swaps which chrome editor mounts on page 1
Page number	structured option in BasePaginationOptions, painted inside header/footer chrome	independent slot in store, painted in dedicated chrome region
PlateStatic plugin coverage	per-plugin staticSafe opt-in extends the static filter	sub-editors render natively in paged mode; static filter only matters in print/PDF path
DOCX round-trip	adapter on options + chrome nodes, stays single-section	adapter on store + chrome editors, stays single-section
Reversibility	hard — schema migration if first-page nodes ship and are later removed	easy — store can be retired; chrome editors collapse back to body nodes
Implementation surface	extends existing types + adds ChromeShell + 1 dialog	adds new sub-editor mounts, store, and overlay coordination

Assumptions deliberately shuffled vs variant C

Axis	Variant A	Variant C
Granularity	document-level (one set of chrome, one margin box)	per-section (multi-section docs, per-section margins/chrome)
Data shape	flat options + chrome nodes in body	OOXML-shaped Section nodes with sectPr + ID-keyed chrome registry
First-page rule	dedicated node types	titlePg flag in sectPr plus titlePgHdrRef/titlePgFtrRef
Page number	flat pageNumber option	structured pgNumType inside sectPr
DOCX round-trip	adapter mapping per option	near-direct (matches OOXML)
Implementation cost	low (extend existing types)	high (new section abstraction across import/export)
Future-proofing	locked to single-section docs	multi-section, per-section everything

Validate this approach — especially but not limited to

• Static analysis of packages/pagination/src/lib/types.ts, packages/pagination/src/react/page-frame.tsx, packages/pagination/src/react/margins-dialog.tsx, packages/pagination/src/lib/transforms/*.ts, packages/pagination/src/lib/allocate-footnotes.ts.
• Review of our own code in packages/pagination/src/react/, packages/pagination/src/lib/, packages/pagination/src/static/, 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 B — overlay store + sub-editors) #385 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 "do we need multi-section / Word DOCX-fidelity" (→ C) vs "do we need to keep the body editor schema clean" (→ B) vs "do we need the smallest patch to existing types" (→ A)?
• Will a per-plugin staticSafe opt-in actually fix AI / comments / suggestions / drag-handle in PlateStatic, or do those plugins fundamentally require live-editor state that PlateStatic cannot provide? (If the latter, this whole rendering hole survives variant A.)
• Does adding firstPageHeader/firstPageFooter node types violate the existing single-header/footer invariant enforced by enforceHeaderFooterInvariants.ts? Spell out the migration path.
• Is pageNumber better as a structured option or as a void inline node inserted into chrome content (so users could also reorder/style it via existing inline tooling)?

Full plan

1. Extend BasePaginationOptions (types.ts) with pageNumber, firstPageDifferent, and presets.
2. Add setPageNumber/setFirstPageDifferent transforms; add firstPageHeader/firstPageFooter node types behind the flag.
3. Update paginate.ts to swap chrome on page index 0 when flag is true.
4. Refactor PageFrame to consume pageNumber config (drop hardcoded span).
5. Build ChromeShell wrapper for header/footer node renderers.
6. Promote MarginsDialog to full Page Setup dialog wired to all transforms.
7. Add staticSafe plugin descriptor field + extend getElementOnlyStaticPlugins.
8. Migrate AI / comments / suggestions / drag-handle to staticSafe: true with static-render fallbacks.
9. End-of-doc footnote rendering inside last page's content box.
10. dev-browser verification of all seven user-reported issues.

References

• packages/pagination/src/lib/types.ts
• packages/pagination/src/react/page-frame.tsx
• packages/pagination/src/react/margins-dialog.tsx
• packages/pagination/src/lib/transforms/
• packages/pagination/src/lib/allocate-footnotes.ts
• branch codex/pagination-variant-a (commits e56000a, aec21fb, 1e54d38, 500e5d8)

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

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

Similarity score: 95%

This comment was generated by Kilo Auto-Triage.

[arthrod]

🥕 Sibling variants: #385 (overlay store + sub-editors) 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

• Extend BasePaginationOptions with pageNumber, firstPageDifferent, and footnotePlacement configs, keeping state in the plugin options layer
• Add firstPageHeader/firstPageFooter as document-level node types parallel to existing header/footer, with invariant enforcement extended to handle all four types
• Replace hardcoded page number rendering with a configurable PageNumber component consuming the new options
• Create a ChromeShell wrapper that provides visual feedback and exit affordances when editing header/footer content
• Build a comprehensive Page Setup dialog from scratch that wires to all pagination transforms including footnote placement
• Implement document-end footnote mode in allocateFootnotes where all definitions render on the final page
• Replace BlockPreview with scaled PlateStatic rendering to enable plugin content in page thumbnails

Design Choices

Design Choice 1: PlateStatic vs Preview Rendering Gap

Options Considered:

1. Add staticSafe plugin opt-in and modify a non-existent filter function
2. Replace BlockPreview with actual PlateStatic rendering in page thumbnails
3. Defer preview rendering improvements to a separate ticket after clarifying requirements

Chosen Option: 2

Rationale: Replace BlockPreview with scaled-down PlateStatic rendering. This aligns with the ticket's acceptance criteria requiring plugins to render in the paged-view preview. Phase 8 addresses this with appropriate scope given the architectural discovery.

Design Choice 2: First-Page Chrome Implementation

Options Considered:

1. Add new node types firstPageHeader/firstPageFooter persisted in the document schema
2. Use an options flag that tells the renderer to show different content on page 0 (content stored in options, not nodes)

Chosen Option: 1

Rationale: Adding node types aligns with the existing schema pattern for header/footer, maintains DOCX round-trip compatibility, and allows users to edit first-page chrome directly in the document. Requires extending enforceHeaderFooterInvariants to handle these additional types.

Design Choice 3: Page Number as Option vs Inline Node

Options Considered:

1. Structured pageNumber option in BasePaginationOptions controlling a rendered component
2. Void inline node users can insert/position within header/footer content

Chosen Option: 1

Rationale: A structured option provides predictable positioning (header/footer + alignment), simpler implementation, and matches Word/Pages behavior where page numbers have dedicated insertion points. Users needing custom positioning can still manually type page numbers or extend later.

Design Choice 4: Margins Dialog Creation

Options Considered:

1. Create a minimal dialog focused only on margins
2. Create a comprehensive Page Setup dialog covering all layout options

Chosen Option: 2

Rationale: Building a full Page Setup dialog from the start avoids multiple iterations and provides the complete UX described in acceptance criteria (margins, page size, chrome heights, first-page toggle, page number config).

Design Choice 5: End-of-Document Footnote Placement

Options Considered:

1. Add a new footnotePlacement option with 'perPage' | 'documentEnd' values
2. Keep current per-page allocation and defer document-end mode

Chosen Option: 1

Rationale: Add the footnotePlacement option to support both modes. When documentEnd is selected, all footnote definitions render on the final page rather than being distributed to their first-reference pages.

💡 User Tips

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

Implementation Steps

Phase 1: Extend Type System and Plugin Keys

This phase establishes the foundational types and constants needed for the new features. All subsequent phases depend on these type definitions.

Task 1: Add Page Number Configuration Types

Define the structured pageNumber configuration type that controls where and how page numbers render.

• Add PageNumberConfig type to packages/pagination/src/lib/types.ts with fields: side: 'header' | 'footer', align: 'left' | 'center' | 'right', format: '1' | '1/N' | 'Page 1 of N', startAt: number, hideOnFirst: boolean
• Add pageNumber?: PageNumberConfig to BasePaginationOptions interface
• Add firstPageDifferent?: boolean to BasePaginationOptions interface
• Add setPageNumber and setFirstPageDifferent to BasePaginationTransforms interface

Task 2: Add First-Page Chrome Node Type Keys

Register the new node type keys for first-page header and footer blocks.

• Add FIRST_PAGE_HEADER_KEY and FIRST_PAGE_FOOTER_KEY constants to packages/pagination/src/lib/internal/keys.ts
• Export the new keys from the internal barrel file

Task 3: Add Footnote Placement Option Type

Define the option for controlling footnote placement mode.

• Add FootnotePlacement = 'perPage' | 'documentEnd' type to packages/pagination/src/lib/types.ts
• Add footnotePlacement?: FootnotePlacement to BasePaginationOptions interface (default: 'perPage')
• Add setFootnotePlacement to BasePaginationTransforms interface

🤖 Prompt for AI agents

Establish foundational types and constants for the new page number, first-page
chrome, and footnote placement features. All subsequent phases depend on these
definitions.

**File: `packages/pagination/src/lib/types.ts`**
- Add a new `PageNumberConfig` type with the following fields:
  - `side: 'header' | 'footer'`
  - `align: 'left' | 'center' | 'right'`
  - `format: '1' | '1/N' | 'Page 1 of N'`
  - `startAt: number`
  - `hideOnFirst: boolean`
- Add `pageNumber?: PageNumberConfig` to the `BasePaginationOptions` interface
- Add `firstPageDifferent?: boolean` to the `BasePaginationOptions` interface
- Add `FootnotePlacement = 'perPage' | 'documentEnd'` type
- Add `footnotePlacement?: FootnotePlacement` to `BasePaginationOptions`
(default: `'perPage'`)
- Add `setPageNumber`, `setFirstPageDifferent`, and `setFootnotePlacement`
method signatures to the `BasePaginationTransforms` interface

**File: `packages/pagination/src/lib/internal/keys.ts`**
- Add `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` constants
- Export the new keys from the internal barrel file

Phase 2: Implement Transforms and Invariant Handling

This phase adds the editor transforms for the new options and updates the invariant enforcer to recognize first-page chrome nodes.

Task 1: Create Page Number and First-Page Transforms

Add transform functions that allow setting the new options programmatically.

• Create packages/pagination/src/lib/transforms/setPageNumber.ts that calls setOption('pageNumber', config)
• Create packages/pagination/src/lib/transforms/setFirstPageDifferent.ts that calls setOption('firstPageDifferent', value)
• Export both transforms from the transforms barrel packages/pagination/src/lib/transforms/index.ts

Task 2: Create Footnote Placement Transform

Add transform for setting footnote placement mode.

• Create packages/pagination/src/lib/transforms/setFootnotePlacement.ts that calls setOption('footnotePlacement', value)
• Export from transforms barrel

Task 3: Update Base Pagination Plugin with New Transforms

Wire the new transforms into the plugin's transform API.

• Update packages/pagination/src/lib/base-pagination-plugin.ts to add setPageNumber, setFirstPageDifferent, and setFootnotePlacement to editor.tf.pagination
• Add default values for new options: pageNumber: undefined (disabled by default), firstPageDifferent: false, footnotePlacement: 'perPage'

Task 4: Extend Header/Footer Invariant Enforcement

Update the invariant enforcer to handle first-page chrome nodes without duplicating them or misplacing them.

• Update packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts to recognize FIRST_PAGE_HEADER_KEY and FIRST_PAGE_FOOTER_KEY
• Enforce: at most one firstPageHeader (at index 1 if header exists, else index 0), at most one firstPageFooter (second-to-last if footer exists, else last)
• Phase 1 deduplication should handle all four types; Phase 2 repositioning should maintain correct ordering

Task 5: Add First-Page Chrome Toggle and Ensure Transforms

Create transforms for managing first-page header/footer lifecycle.

• Create packages/pagination/src/lib/transforms/ensureFirstPageHeader.ts following the pattern of ensureHeader.ts
• Create packages/pagination/src/lib/transforms/ensureFirstPageFooter.ts following the pattern of ensureFooter.ts
• Create packages/pagination/src/lib/transforms/toggleFirstPageHeader.ts and toggleFirstPageFooter.ts following existing toggle patterns
• Export from transforms barrel

🤖 Prompt for AI agents

Implement the editor transforms for the new options and update the invariant
enforcer to handle first-page chrome nodes.

**New file: `packages/pagination/src/lib/transforms/setPageNumber.ts`**
- Implement a transform that calls `setOption('pageNumber', config)` with a
`PageNumberConfig` argument

**New file: `packages/pagination/src/lib/transforms/setFirstPageDifferent.ts`**
- Implement a transform that calls `setOption('firstPageDifferent', value)` with
a boolean argument

**New file: `packages/pagination/src/lib/transforms/setFootnotePlacement.ts`**
- Implement a transform that calls `setOption('footnotePlacement', value)` with
a `FootnotePlacement` argument

**File: `packages/pagination/src/lib/transforms/index.ts`**
- Export all three new transforms

**File: `packages/pagination/src/lib/base-pagination-plugin.ts`**
- Add `setPageNumber`, `setFirstPageDifferent`, and `setFootnotePlacement` to
`editor.tf.pagination`
- Set default option values: `pageNumber: undefined` (disabled by default),
`firstPageDifferent: false`, `footnotePlacement: 'perPage'`

**File:
`packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts`**
- Recognize `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` nodes
- Enforce at most one `firstPageHeader` node: positioned at index 1 if a header
exists, else at index 0
- Enforce at most one `firstPageFooter` node: positioned second-to-last if a
footer exists, else last
- Phase 1 (deduplication) should handle all four node types; Phase 2
(repositioning) should maintain correct ordering

**New files: `ensureFirstPageHeader.ts`, `ensureFirstPageFooter.ts`,
`toggleFirstPageHeader.ts`, `toggleFirstPageFooter.ts`**
- Follow the existing patterns of `ensureHeader.ts`, `ensureFooter.ts`, and the
existing toggle transforms
- Export all new transforms from the transforms barrel

Phase 3: Update Pagination Algorithm

This phase modifies the core pagination logic to select appropriate chrome based on page index when first-page-different is enabled.

Task 1: Modify Paginate to Support First-Page Chrome Selection

Update the pagination algorithm to skip first-page chrome nodes from general content and expose them for per-page rendering.

• Update packages/pagination/src/lib/paginate.ts to also skip FIRST_PAGE_HEADER_KEY and FIRST_PAGE_FOOTER_KEY nodes from content binning (same treatment as HEADER_KEY/FOOTER_KEY)
• The actual chrome selection logic will be handled at render time in PageFrame, not during pagination

Task 2: Update Page Layout Hook

Ensure the page layout hook passes first-page-different context to renderers.

• Update packages/pagination/src/react/internal/use-page-layout.ts to extract and pass through firstPageDifferent option
• The PageOverlay will receive this context for conditional chrome rendering

🤖 Prompt for AI agents

Update the core pagination algorithm and layout hook to handle first-page chrome
nodes.

**File: `packages/pagination/src/lib/paginate.ts`**
- Add `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` to the set of node
types skipped from content binning, applying the same treatment already used for
`HEADER_KEY` and `FOOTER_KEY`
- Do not implement chrome selection logic here; that will be handled at render
time in `PageFrame`

**File: `packages/pagination/src/react/internal/use-page-layout.ts`**
- Extract the `firstPageDifferent` option from the plugin options
- Pass `firstPageDifferent` through to consumers (e.g., `PageOverlay`) so it can
be used for conditional chrome rendering

Phase 4: Refactor Page Number Rendering

This phase replaces the hardcoded page number with a configurable component that respects the new pageNumber options.

Task 1: Create PageNumber Component

Build a reusable component that renders page numbers according to configuration.

• Create packages/pagination/src/react/page-number.tsx component
• Accept props: pageIndex, totalPages, config: PageNumberConfig | undefined
• Return null if config is undefined (disabled)
• Return null if config.hideOnFirst is true and pageIndex === 0
• Render formatted string based on config.format: '1' → pageIndex + startAt, '1/N' → ${pageIndex + startAt}/${totalPages}, 'Page 1 of N' → Page ${pageIndex + startAt} of ${totalPages}
• Style with textAlign based on config.align

Task 2: Integrate PageNumber into PageFrame

Replace the hardcoded page number span with the new configurable component.

• Update packages/pagination/src/react/page-frame.tsx to import PageNumber component
• Pass pageNumber config from chrome props (derived from plugin options)
• Render PageNumber in either header or footer band based on config.side
• Remove the hardcoded <span style={{ float: 'right' }}>{page.pageIndex + 1}</span> at line 119

Task 3: Support First-Page Chrome in PageFrame

Update PageFrame to select between regular and first-page chrome based on page index.

• Update packages/pagination/src/react/page-frame.tsx to accept firstPageHeader, firstPageFooter, and firstPageDifferent props
• When firstPageDifferent is true and page.pageIndex === 0, render first-page chrome nodes instead of regular header/footer
• Fall back to regular header/footer if first-page nodes don't exist

🤖 Prompt for AI agents

Replace the hardcoded page number rendering with a configurable component and
add first-page chrome selection logic to `PageFrame`.

**New file: `packages/pagination/src/react/page-number.tsx`**
- Create a `PageNumber` component accepting props: `pageIndex`, `totalPages`,
`config: PageNumberConfig | undefined`
- Return null if `config` is undefined
- Return null if `config.hideOnFirst` is true and `pageIndex === 0`
- Render a formatted string based on `config.format`:
  - `'1'` → `pageIndex + startAt`
  - `'1/N'` → `${pageIndex + startAt}/${totalPages}`
  - `'Page 1 of N'` → `Page ${pageIndex + startAt} of ${totalPages}`
- Apply `textAlign` styling based on `config.align`

**File: `packages/pagination/src/react/page-frame.tsx`**
- Import and use the new `PageNumber` component
- Remove the hardcoded `<span style={{ float: 'right' }}>{page.pageIndex +
1}</span>` at line 119
- Pass `pageNumber` config (derived from plugin options) and render `PageNumber`
in the header or footer band based on `config.side`
- Add `firstPageHeader`, `firstPageFooter`, and `firstPageDifferent` props
- When `firstPageDifferent` is true and `page.pageIndex === 0`, render
first-page chrome nodes instead of regular header/footer; fall back to regular
header/footer if first-page nodes don't exist

Phase 5: Build Chrome Shell Component

This phase creates the interactive chrome shell that provides UX affordances when editing header/footer content.

Task 1: Create ChromeShell Component

Build a wrapper component that shows editing affordances when selection is inside chrome nodes.

• Create packages/pagination/src/react/chrome-shell.tsx
• Accept props: type: 'header' | 'footer' | 'firstPageHeader' | 'firstPageFooter', children, isSelected: boolean
• When isSelected is false, render children without decoration (reading mode)
• When isSelected is true, render: label badge (e.g., "Header", "First Page Header"), dotted focus border around the chrome region, "Exit" button/affordance that moves selection out of chrome
• Use useSelected hook or similar to determine if selection is within the chrome node

Task 2: Integrate ChromeShell with Header/Footer Plugins

Wire the ChromeShell into the existing header and footer plugin renderers.

• Update packages/pagination/src/react/header-plugin.ts to wrap node rendering with ChromeShell
• Update packages/pagination/src/react/footer-plugin.ts to wrap node rendering with ChromeShell
• Create packages/pagination/src/react/first-page-header-plugin.ts and first-page-footer-plugin.ts following existing plugin patterns, using ChromeShell
• Register new plugins in packages/pagination/src/react/pagination-plugin.ts

🤖 Prompt for AI agents

Create the `ChromeShell` component that provides interactive editing affordances
for header/footer chrome regions, and wire it into existing and new plugins.

**New file: `packages/pagination/src/react/chrome-shell.tsx`**
- Create a `ChromeShell` component with props: `type: 'header' | 'footer' |
'firstPageHeader' | 'firstPageFooter'`, `children`, `isSelected: boolean`
- When `isSelected` is false: render children without any decoration (reading
mode)
- When `isSelected` is true: render a label badge (e.g., "Header", "First Page
Header"), a dotted focus border around the chrome region, and an "Exit"
button/affordance that moves selection out of the chrome node
- Use `useSelected` hook or similar to determine if selection is within the
chrome node

**Files: `packages/pagination/src/react/header-plugin.ts` and
`footer-plugin.ts`**
- Wrap node rendering with the `ChromeShell` component

**New files: `packages/pagination/src/react/first-page-header-plugin.ts` and
`first-page-footer-plugin.ts`**
- Follow the patterns of the existing header/footer plugins
- Use `ChromeShell` for node rendering

**File: `packages/pagination/src/react/pagination-plugin.ts`**
- Register the two new plugins (`first-page-header-plugin` and
`first-page-footer-plugin`)

Phase 6: Create Page Setup Dialog

This phase builds the comprehensive Page Setup dialog for configuring all layout options.

Task 1: Create Page Setup Dialog Component

Build the main dialog component with all configuration sections.

• Create packages/pagination/src/react/page-setup-dialog.tsx
• Include sections: Margins (top/bottom/left/right with numeric inputs), Unit selector (cm/in/mm/px with conversion), Page size presets (A4/Letter/Legal + custom), Header/Footer heights, First page different toggle, Page number configuration (side, align, format, startAt, hideOnFirst), Footnote placement toggle (per-page vs document-end)
• Use native <dialog> element for consistency with existing patterns
• Accept editor prop to access current options and call transforms

Task 2: Wire Dialog to Transforms

Connect all dialog inputs to the appropriate editor transforms.

• Margins inputs call editor.tf.pagination.setMargins()
• Page size selector calls editor.tf.pagination.setPageSize()
• First page toggle calls editor.tf.pagination.setFirstPageDifferent() and conditionally calls toggleFirstPageHeader/toggleFirstPageFooter
• Page number config calls editor.tf.pagination.setPageNumber()
• Footnote placement calls editor.tf.pagination.setFootnotePlacement()
• Add unit conversion utility functions (cm/in/mm to px and back)

Task 3: Add Dialog Trigger to Page Overlay

Provide a way for users to open the Page Setup dialog from the paged view.

• Update packages/pagination/src/react/page-overlay.tsx to include a "Page Setup" button in the preview panel header
• Render PageSetupDialog with open/close state management
• Pass editor instance to dialog

🤖 Prompt for AI agents

Build the comprehensive Page Setup dialog from scratch and integrate it with the
paged view.

**New file: `packages/pagination/src/react/page-setup-dialog.tsx`**
- Create a `PageSetupDialog` component accepting an `editor` prop
- Use a native `<dialog>` element for consistency with existing patterns
- Include the following sections:
  - **Margins**: top/bottom/left/right numeric inputs
  - **Unit selector**: cm/in/mm/px options with conversion
  - **Page size presets**: A4/Letter/Legal + custom
  - **Header/Footer heights**: numeric inputs
  - **First page different toggle**: checkbox/toggle
- **Page number configuration**: side, align, format, startAt, hideOnFirst
controls
  - **Footnote placement toggle**: per-page vs document-end
- Wire each input to the appropriate transform:
  - Margins → `editor.tf.pagination.setMargins()`
  - Page size → `editor.tf.pagination.setPageSize()`
- First page toggle → `editor.tf.pagination.setFirstPageDifferent()`,
conditionally calling `toggleFirstPageHeader`/`toggleFirstPageFooter`
  - Page number config → `editor.tf.pagination.setPageNumber()`
  - Footnote placement → `editor.tf.pagination.setFootnotePlacement()`
- Add unit conversion utility functions for converting cm/in/mm to px and back

**File: `packages/pagination/src/react/page-overlay.tsx`**
- Add a "Page Setup" button to the preview panel header
- Manage open/close state for the `PageSetupDialog`
- Pass the editor instance to the dialog

Phase 7: Static Rendering Elements

This phase adds static renderers for the new first-page chrome elements.

Create Static First-Page Chrome Renderers

Add SSR-compatible renderers for first-page header and footer elements.

• Create packages/pagination/src/static/first-page-header-element-static.tsx following the pattern of header-element-static.tsx
• Create packages/pagination/src/static/first-page-footer-element-static.tsx following the pattern of footer-element-static.tsx
• Export from packages/pagination/src/static/index.ts

🤖 Prompt for AI agents

Add SSR-compatible static renderers for the new first-page chrome node types.

**New file:
`packages/pagination/src/static/first-page-header-element-static.tsx`**
- Follow the pattern of the existing `header-element-static.tsx`

**New file:
`packages/pagination/src/static/first-page-footer-element-static.tsx`**
- Follow the pattern of the existing `footer-element-static.tsx`

**File: `packages/pagination/src/static/index.ts`**
- Export both new static renderers

Phase 8: End-of-Document Footnote Rendering

This phase implements the document-end footnote placement mode where all footnotes render on the final page.

Task 1: Update Allocate Footnotes for Document-End Mode

Modify the footnote allocation algorithm to support document-end placement.

• Update packages/pagination/src/lib/allocate-footnotes.ts to accept a placement: FootnotePlacement parameter
• When placement === 'perPage', use existing greedy first-reference assignment
• When placement === 'documentEnd', assign all footnote definitions to the last page's footnotes array instead of distributing them
• Ensure the returned Page[] reflects the chosen placement mode

Task 2: Wire Footnote Placement Through Page Layout

Pass the footnote placement option through the rendering pipeline.

• Update packages/pagination/src/react/internal/use-page-layout.ts to read footnotePlacement from options and pass to allocateFootnotes
• Ensure PageFrame renders footnotes correctly in both modes (footnotes appear in the footnote well of their assigned page)

Task 3: Ensure Document-End Footnotes Render in Content Box

Verify that document-end footnotes render inside the last page's content area, not below the page sheet.

• Review PageFrame footnote-well positioning to confirm it respects page bounds
• If footnotes overflow the footnote-well height, they should expand the content area or trigger page overflow handling rather than rendering below the page boundary
• Add defensive styling to clip or scroll overflow if necessary

🤖 Prompt for AI agents

Implement the document-end footnote placement mode by updating the footnote
allocation algorithm and wiring the option through the rendering pipeline.

**File: `packages/pagination/src/lib/allocate-footnotes.ts`**
- Add a `placement: FootnotePlacement` parameter to the allocation function
- When `placement === 'perPage'`: use the existing greedy first-reference
assignment (no change)
- When `placement === 'documentEnd'`: assign all footnote definitions to the
last page's `footnotes` array instead of distributing them across pages
- Ensure the returned `Page[]` correctly reflects the chosen placement mode

**File: `packages/pagination/src/react/internal/use-page-layout.ts`**
- Read `footnotePlacement` from plugin options
- Pass `footnotePlacement` to `allocateFootnotes`
- Ensure `PageFrame` renders footnotes correctly in both modes (footnotes appear
in the footnote well of their assigned page)

**File: `packages/pagination/src/react/page-frame.tsx`**
- Review footnote-well positioning to confirm it respects page bounds
- If footnotes overflow the footnote-well height, they should expand the content
area or trigger page overflow handling rather than rendering below the page
boundary
- Add defensive styling to clip or scroll overflow if necessary

Phase 9: Preview Rendering with Plugin Support

This phase addresses the gap where page thumbnails use simplified BlockPreview rendering instead of full plugin content.

Task 1: Create Scaled PlateStatic Preview Component

Build a component that renders page content using PlateStatic at thumbnail scale.

• Create packages/pagination/src/react/page-content-preview.tsx that wraps PlateStatic
• Accept nodes: TElement[] (page content) and scale: number
• Use CSS transform: scale() with transformOrigin: 'top left' for thumbnail sizing
• Ensure the component uses the same plugins as the main editor for consistent rendering

Task 2: Replace BlockPreview with PlateStatic Rendering

Update PageFrame to use full static rendering instead of plain-text extraction.

• Update packages/pagination/src/react/page-frame.tsx to replace BlockPreview usage with PageContentPreview
• Pass the editor's resolved plugins to the static renderer
• Maintain the existing thumbnail scaling and overflow clipping behavior

Task 3: Ensure Plugin Components Have Static Fallbacks

Verify that plugins rendering in previews have appropriate static-safe components.

• Confirm CommentLeafStatic and SuggestionLeafStatic (already exist in apps/www) are wired for static rendering
• For plugins without static variants (e.g., AI streaming indicators), ensure graceful degradation (render nothing or render base content without interactive state)
• Document in the pagination package README which plugins require static fallbacks for preview rendering

🤖 Prompt for AI agents

Replace the simplified `BlockPreview` thumbnail renderer with scaled PlateStatic
rendering to support full plugin content in page previews.

**New file: `packages/pagination/src/react/page-content-preview.tsx`**
- Create a `PageContentPreview` component wrapping PlateStatic
- Accept props: `nodes: TElement[]` (page content) and `scale: number`
- Apply CSS `transform: scale()` with `transformOrigin: 'top left'` for
thumbnail sizing
- Use the same plugins as the main editor for consistent rendering

**File: `packages/pagination/src/react/page-frame.tsx`**
- Replace `BlockPreview` usage with the new `PageContentPreview` component
- Pass the editor's resolved plugins to the static renderer
- Maintain existing thumbnail scaling and overflow clipping behavior

**Plugin static fallback verification:**
- Confirm `CommentLeafStatic` and `SuggestionLeafStatic` (already in `apps/www`)
are wired for static rendering
- For plugins without static variants (e.g., AI streaming indicators), ensure
graceful degradation: render nothing or render base content without interactive
state
- Document in the pagination package README which plugins require static
fallbacks for preview rendering

Research

The pagination package is structured into three main areas: lib/ (framework-agnostic logic with types, transforms, and the core pagination algorithm), react/ (React components including PageFrame, PageOverlay, and plugin wiring), and static/ (SSR-compatible element renderers). The current implementation has BasePaginationOptions in types.ts with margins, pageSize, headerHeight, footerHeight, footnoteWell, and previewVisible. Page numbers are hardcoded inline in PageFrame (line 119). Header/footer invariants are enforced by enforceHeaderFooterInvariants.ts which maintains a single header at index 0 and single footer at last position. The page preview uses a simplified BlockPreview component that extracts plain text rather than rendering full plugin content.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Establish foundational types and constants for the new page number, first-page
chrome, and footnote placement features. All subsequent phases depend on these
definitions.

**File: `packages/pagination/src/lib/types.ts`**
- Add a new `PageNumberConfig` type with the following fields:
  - `side: 'header' | 'footer'`
  - `align: 'left' | 'center' | 'right'`
  - `format: '1' | '1/N' | 'Page 1 of N'`
  - `startAt: number`
  - `hideOnFirst: boolean`
- Add `pageNumber?: PageNumberConfig` to the `BasePaginationOptions` interface
- Add `firstPageDifferent?: boolean` to the `BasePaginationOptions` interface
- Add `FootnotePlacement = 'perPage' | 'documentEnd'` type
- Add `footnotePlacement?: FootnotePlacement` to `BasePaginationOptions`
(default: `'perPage'`)
- Add `setPageNumber`, `setFirstPageDifferent`, and `setFootnotePlacement`
method signatures to the `BasePaginationTransforms` interface

**File: `packages/pagination/src/lib/internal/keys.ts`**
- Add `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` constants
- Export the new keys from the internal barrel file
===============================================================================

Task: 2

Implement the editor transforms for the new options and update the invariant
enforcer to handle first-page chrome nodes.

**New file: `packages/pagination/src/lib/transforms/setPageNumber.ts`**
- Implement a transform that calls `setOption('pageNumber', config)` with a
`PageNumberConfig` argument

**New file: `packages/pagination/src/lib/transforms/setFirstPageDifferent.ts`**
- Implement a transform that calls `setOption('firstPageDifferent', value)` with
a boolean argument

**New file: `packages/pagination/src/lib/transforms/setFootnotePlacement.ts`**
- Implement a transform that calls `setOption('footnotePlacement', value)` with
a `FootnotePlacement` argument

**File: `packages/pagination/src/lib/transforms/index.ts`**
- Export all three new transforms

**File: `packages/pagination/src/lib/base-pagination-plugin.ts`**
- Add `setPageNumber`, `setFirstPageDifferent`, and `setFootnotePlacement` to
`editor.tf.pagination`
- Set default option values: `pageNumber: undefined` (disabled by default),
`firstPageDifferent: false`, `footnotePlacement: 'perPage'`

**File:
`packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts`**
- Recognize `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` nodes
- Enforce at most one `firstPageHeader` node: positioned at index 1 if a header
exists, else at index 0
- Enforce at most one `firstPageFooter` node: positioned second-to-last if a
footer exists, else last
- Phase 1 (deduplication) should handle all four node types; Phase 2
(repositioning) should maintain correct ordering

**New files: `ensureFirstPageHeader.ts`, `ensureFirstPageFooter.ts`,
`toggleFirstPageHeader.ts`, `toggleFirstPageFooter.ts`**
- Follow the existing patterns of `ensureHeader.ts`, `ensureFooter.ts`, and the
existing toggle transforms
- Export all new transforms from the transforms barrel
===============================================================================

Task: 3

Update the core pagination algorithm and layout hook to handle first-page chrome
nodes.

**File: `packages/pagination/src/lib/paginate.ts`**
- Add `FIRST_PAGE_HEADER_KEY` and `FIRST_PAGE_FOOTER_KEY` to the set of node
types skipped from content binning, applying the same treatment already used for
`HEADER_KEY` and `FOOTER_KEY`
- Do not implement chrome selection logic here; that will be handled at render
time in `PageFrame`

**File: `packages/pagination/src/react/internal/use-page-layout.ts`**
- Extract the `firstPageDifferent` option from the plugin options
- Pass `firstPageDifferent` through to consumers (e.g., `PageOverlay`) so it can
be used for conditional chrome rendering
===============================================================================

Task: 4

Replace the hardcoded page number rendering with a configurable component and
add first-page chrome selection logic to `PageFrame`.

**New file: `packages/pagination/src/react/page-number.tsx`**
- Create a `PageNumber` component accepting props: `pageIndex`, `totalPages`,
`config: PageNumberConfig | undefined`
- Return null if `config` is undefined
- Return null if `config.hideOnFirst` is true and `pageIndex === 0`
- Render a formatted string based on `config.format`:
  - `'1'` → `pageIndex + startAt`
  - `'1/N'` → `${pageIndex + startAt}/${totalPages}`
  - `'Page 1 of N'` → `Page ${pageIndex + startAt} of ${totalPages}`
- Apply `textAlign` styling based on `config.align`

**File: `packages/pagination/src/react/page-frame.tsx`**
- Import and use the new `PageNumber` component
- Remove the hardcoded `<span style={{ float: 'right' }}>{page.pageIndex +
1}</span>` at line 119
- Pass `pageNumber` config (derived from plugin options) and render `PageNumber`
in the header or footer band based on `config.side`
- Add `firstPageHeader`, `firstPageFooter`, and `firstPageDifferent` props
- When `firstPageDifferent` is true and `page.pageIndex === 0`, render
first-page chrome nodes instead of regular header/footer; fall back to regular
header/footer if first-page nodes don't exist
===============================================================================

Task: 5

Create the `ChromeShell` component that provides interactive editing affordances
for header/footer chrome regions, and wire it into existing and new plugins.

**New file: `packages/pagination/src/react/chrome-shell.tsx`**
- Create a `ChromeShell` component with props: `type: 'header' | 'footer' |
'firstPageHeader' | 'firstPageFooter'`, `children`, `isSelected: boolean`
- When `isSelected` is false: render children without any decoration (reading
mode)
- When `isSelected` is true: render a label badge (e.g., "Header", "First Page
Header"), a dotted focus border around the chrome region, and an "Exit"
button/affordance that moves selection out of the chrome node
- Use `useSelected` hook or similar to determine if selection is within the
chrome node

**Files: `packages/pagination/src/react/header-plugin.ts` and
`footer-plugin.ts`**
- Wrap node rendering with the `ChromeShell` component

**New files: `packages/pagination/src/react/first-page-header-plugin.ts` and
`first-page-footer-plugin.ts`**
- Follow the patterns of the existing header/footer plugins
- Use `ChromeShell` for node rendering

**File: `packages/pagination/src/react/pagination-plugin.ts`**
- Register the two new plugins (`first-page-header-plugin` and
`first-page-footer-plugin`)
===============================================================================

Task: 6

Build the comprehensive Page Setup dialog from scratch and integrate it with the
paged view.

**New file: `packages/pagination/src/react/page-setup-dialog.tsx`**
- Create a `PageSetupDialog` component accepting an `editor` prop
- Use a native `<dialog>` element for consistency with existing patterns
- Include the following sections:
  - **Margins**: top/bottom/left/right numeric inputs
  - **Unit selector**: cm/in/mm/px options with conversion
  - **Page size presets**: A4/Letter/Legal + custom
  - **Header/Footer heights**: numeric inputs
  - **First page different toggle**: checkbox/toggle
- **Page number configuration**: side, align, format, startAt, hideOnFirst
controls
  - **Footnote placement toggle**: per-page vs document-end
- Wire each input to the appropriate transform:
  - Margins → `editor.tf.pagination.setMargins()`
  - Page size → `editor.tf.pagination.setPageSize()`
- First page toggle → `editor.tf.pagination.setFirstPageDifferent()`,
conditionally calling `toggleFirstPageHeader`/`toggleFirstPageFooter`
  - Page number config → `editor.tf.pagination.setPageNumber()`
  - Footnote placement → `editor.tf.pagination.setFootnotePlacement()`
- Add unit conversion utility functions for converting cm/in/mm to px and back

**File: `packages/pagination/src/react/page-overlay.tsx`**
- Add a "Page Setup" button to the preview panel header
- Manage open/close state for the `PageSetupDialog`
- Pass the editor instance to the dialog
===============================================================================

Task: 7

Add SSR-compatible static renderers for the new first-page chrome node types.

**New file:
`packages/pagination/src/static/first-page-header-element-static.tsx`**
- Follow the pattern of the existing `header-element-static.tsx`

**New file:
`packages/pagination/src/static/first-page-footer-element-static.tsx`**
- Follow the pattern of the existing `footer-element-static.tsx`

**File: `packages/pagination/src/static/index.ts`**
- Export both new static renderers
===============================================================================

Task: 8

Implement the document-end footnote placement mode by updating the footnote
allocation algorithm and wiring the option through the rendering pipeline.

**File: `packages/pagination/src/lib/allocate-footnotes.ts`**
- Add a `placement: FootnotePlacement` parameter to the allocation function
- When `placement === 'perPage'`: use the existing greedy first-reference
assignment (no change)
- When `placement === 'documentEnd'`: assign all footnote definitions to the
last page's `footnotes` array instead of distributing them across pages
- Ensure the returned `Page[]` correctly reflects the chosen placement mode

**File: `packages/pagination/src/react/internal/use-page-layout.ts`**
- Read `footnotePlacement` from plugin options
- Pass `footnotePlacement` to `allocateFootnotes`
- Ensure `PageFrame` renders footnotes correctly in both modes (footnotes appear
in the footnote well of their assigned page)

**File: `packages/pagination/src/react/page-frame.tsx`**
- Review footnote-well positioning to confirm it respects page bounds
- If footnotes overflow the footnote-well height, they should expand the content
area or trigger page overflow handling rather than rendering below the page
boundary
- Add defensive styling to clip or scroll overflow if necessary
===============================================================================

Task: 9

Replace the simplified `BlockPreview` thumbnail renderer with scaled PlateStatic
rendering to support full plugin content in page previews.

**New file: `packages/pagination/src/react/page-content-preview.tsx`**
- Create a `PageContentPreview` component wrapping PlateStatic
- Accept props: `nodes: TElement[]` (page content) and `scale: number`
- Apply CSS `transform: scale()` with `transformOrigin: 'top left'` for
thumbnail sizing
- Use the same plugins as the main editor for consistent rendering

**File: `packages/pagination/src/react/page-frame.tsx`**
- Replace `BlockPreview` usage with the new `PageContentPreview` component
- Pass the editor's resolved plugins to the static renderer
- Maintain existing thumbnail scaling and overflow clipping behavior

**Plugin static fallback verification:**
- Confirm `CommentLeafStatic` and `SuggestionLeafStatic` (already in `apps/www`)
are wired for static rendering
- For plugins without static variants (e.g., AI streaming indicators), ensure
graceful degradation: render nothing or render base content without interactive
state
- Document in the pagination package README which plugins require static
fallbacks for preview rendering

💡 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]
#84 - Feat/docx import export suggestions comments [merged]
#126 - feat: DOCX tracked changes and comments export [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!

[arthrod]

@coderabbitai of these 3 framings (#384 schema-first, #385 overlay store + sub-editors, #386 OOXML section model), which single assumption is load-bearing?

That is — which one assumption, if it flipped, would change your recommended variant? Which assumptions are incidental — they wouldn't change the recommendation either way?

Name the load-bearing assumption as a single sentence in the form
"If matters more than , variant <A|B|C> wins; otherwise the other."

Compare the plans you just produced across all three issues. Don't pick a winner yet — name the axis. 🥕

[coderabbitai]

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