Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant C — OOXML section model)

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant C of 3 parallel framings of the same goal.
Sibling variant(s): #384 and #385. 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 C — OOXML section model, DOCX-native shape)

1. Adopt OOXML's section-properties (sectPr) model as the source of truth. Introduce a new top-level Section node type carrying sectPr:
   • pgMar — margins (top/right/bottom/left/header/footer/gutter)
   • pgSz — page size + orientation
   • headerReference[] / footerReference[] — IDs of chrome editors (per default/first/even)
   • pgNumType — { start, fmt, position } (format and position of page number)
   • footnotePr — { pos: 'pageBottom'|'beneathText'|'sectEnd'|'docEnd', numFmt, ... }
   • titlePg — first-page-different flag
2. Headers and footers stored as separate ID-keyed Plate values in a chromeRegistry: Record<HeaderFooterId, TElement[]> (mirroring DOCX's header1.xml / footer1.xml). Persisted alongside the document — not inside the body editor's editor.children.
3. Body wrapped in one or more Section nodes; each section's sectPr references chrome by ID. Single-section docs are the trivial case; multi-section emerges naturally.
4. PageFrame (packages/pagination/src/react/page-frame.tsx) reads sectPr for the section that owns the current page; renders chrome by mounting the referenced chrome editor(s) with the same plugin set as the body.
5. Chrome shell UX: clicking a chrome region focuses the dedicated chrome editor for that ID, with a label like Section 1 — header (default) / Section 1 — header (first page). Body editor defocuses.
6. First-page-different → sectPr.titlePg = true; PageFrame uses titlePgHdrRef / titlePgFtrRef for page index 0 of the section. Symmetric for first-page footer.
7. Page number → consume sectPr.pgNumType.position and pgNumType.fmt; render as a non-editable structured slot inside the chrome region. pgNumType.start per section enables the Word-style "restart numbering at chapter".
8. Footnote placement → consume sectPr.footnotePr.pos; allocator (packages/pagination/src/lib/allocate-footnotes.ts) routes definitions per section: pageBottom → per-page footer well; sectEnd → end of the section's last page; docEnd → end of the entire document.
9. Page Setup dialog operates on the active section's sectPr directly (per-section, not document-level). Multi-section docs get a section selector.
10. PlateStatic gap: each chrome region mounts its own chrome editor (real editor) for paged preview, so the static filter is not in the paged paint path. Print/PDF wraps the body editor + each chrome editor in PlateStatic instances, applying the existing static-safe filter only there.
11. DOCX import/export becomes a near-direct mapping (sectPr ↔ sectPr, chromeRegistry ↔ headerN.xml/footerN.xml).

Acceptance: in dev-browser, a multi-section document shows independent margins / chrome / page-number formats per section; first-page-different works per section; footnote placement can be set to footer / section-end / document-end; chrome shells are labeled per section; round-tripping a Word DOCX with two sections, a title-page header, and bottom-of-page footnotes preserves all of it (loaded → exported → diff is clean).

Because the code is

• packages/pagination/src/lib/types.ts — current BasePaginationOptions is document-level only (one margins, one mode, one pageSize). Cannot represent per-section variation. Variant C replaces this with sectPr per section.
• packages/pagination/src/lib/transforms/ensureHeader.ts / ensureFooter.ts — assume single doc-level chrome nodes inside editor.children. Replaced by chromeRegistry lookup.
• packages/pagination/src/lib/paginate.ts — currently allocates pages over the whole body uniformly. Needs to walk section-by-section with per-section margins / page-size / chrome.
• packages/pagination/src/lib/allocate-footnotes.ts — currently knows 'footer' | 'documentEnd'; OOXML extends to pageBottom | beneathText | sectEnd | docEnd. Variant C aligns the type to OOXML.
• packages/pagination/src/react/page-frame.tsx:107-158, 156, 322-362 — chrome rendered through StaticPageValue (the source of the dropped-plugins issue) and page-number is hardcoded. Variant C replaces both with per-section sectPr consumption + live chrome editors.
• packages/docx-io (DOCX I/O package, if present in the workspace) — variant C lets the importer/exporter map sectPr / headerN.xml / footerN.xml directly without re-flattening into a single doc-level header/footer.

Assumptions deliberately shuffled vs variant A

Axis	Variant C	Variant A
Granularity	per-section	document-level
Data shape	OOXML-shaped (sectPr, pgNumType, titlePg, footnotePr)	flat options + chrome nodes in body
First-page rule	titlePg flag + titlePgHdrRef/titlePgFtrRef	dedicated firstPageHeader/firstPageFooter node types
Page number	structured pgNumType inside sectPr	flat pageNumber option in BasePaginationOptions
DOCX round-trip	near-direct (matches OOXML)	adapter mapping per option
Implementation cost	high (new section abstraction across import/export, paginate, paint)	low (extend existing types)
Future-proofing	multi-section, per-section margins/headers, restart numbering	locked to single-section docs
Reversibility	medium (sections persist; can hide multi-section behind a flag)	hard (schema migration if first-page node types ship)

Assumptions deliberately shuffled vs variant B

Axis	Variant C	Variant B
Where chrome lives	ID-keyed chrome registry referenced from Section.sectPr nodes	external pageLayoutStore + scoped chrome sub-editors
Granularity	per-section	document-level
Data model	OOXML-shaped	bespoke store shape
First-page rule	titlePg + titlePgHdrRef	store flag
DOCX round-trip	near-direct	adapter on store
Section model	first-class multi-section	none — single section assumed
Cost upfront	high	medium

Validate this approach — especially but not limited to

• Static analysis of packages/pagination/src/lib/types.ts, packages/pagination/src/lib/paginate.ts, packages/pagination/src/lib/allocate-footnotes.ts, packages/pagination/src/react/page-frame.tsx, packages/pagination/src/lib/transforms/.
• Review of our own code in packages/pagination/src/, any packages/docx-io* if present, 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 B — overlay store + sub-editors) #385 — 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 to support multi-section documents and lossless DOCX round-trip" (→ C) vs "is single-section + clean round-trip via adapter enough" (→ A or B), and within single-section, "is body-editor cleanliness more important than schema-additive simplicity" (→ B vs A)?
• Migration cost: existing single-header / single-footer documents must auto-wrap into a single-section Section node. What's the migration story for already-saved Plate values?
• Does the current pagination plugin contract (BasePaginationApi.pagination.getPages() etc.) survive a per-section model, or do consumers need to migrate to getSections().flatMap(s => s.getPages())?
• Multi-section perf: paginating each section independently — is the measurer cache key still adequate, or do we need to namespace it per section?
• Is the OOXML shape too OOXML-coupled? Will a future PDF / Markdown / HTML importer struggle to fit non-Word documents into sectPr?
• Are there Plate registry consumers (landing-page docs, README-style content) for whom Section is overkill?

Full plan

1. Define Section node type + sectPr shape in packages/pagination/src/lib/types.ts (OOXML-aligned).
2. Define chromeRegistry persistence shape (keyed by header/footer ID).
3. Migration: auto-wrap body in a single Section node; auto-move existing header/footer body nodes into chromeRegistry.
4. Refactor paginate.ts to walk per-section.
5. Refactor allocate-footnotes.ts to handle pageBottom | beneathText | sectEnd | docEnd.
6. Refactor PageFrame to look up per-section sectPr, mount referenced chrome editor(s), consume pgNumType for page-number paint.
7. Implement titlePg swap on page index 0 of each section.
8. Build Page Setup dialog operating on active section's sectPr; add section selector for multi-section docs.
9. Wire chrome shell (label includes section number + role).
10. DOCX adapter: map sectPr ↔ sectPr, chromeRegistry ↔ headerN.xml/footerN.xml.
11. Print/PDF path: wraps body editor + each chrome editor in PlateStatic with existing static-safe filter; on-screen paged preview uses live chrome editors.
12. dev-browser verification of all seven user-reported issues + a multi-section round-trip test.

References

• packages/pagination/src/lib/types.ts
• packages/pagination/src/lib/paginate.ts
• packages/pagination/src/lib/allocate-footnotes.ts
• packages/pagination/src/react/page-frame.tsx
• branch codex/pagination-variant-a
• ECMA-376 §17.6 (OOXML sectPr), §17.10 (footnotes), §17.11 (numbering)

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

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

Similarity score: 97%

This comment was generated by Kilo Auto-Triage.

[arthrod]

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

• Introduce an OOXML-aligned Section node type with sectPr properties (margins, page size, chrome references, page numbering, footnote placement) to enable per-section layout control
• Store header/footer content in a separate chromeRegistry keyed by ID, mirroring DOCX's headerN.xml/footerN.xml architecture for clean round-trip mapping
• Refactor the pagination engine to process sections independently, with each section defining its own page geometry and chrome configuration
• Maintain backward compatibility through auto-migration of legacy documents and a getPages() API that flattens section pages

Design Choices

Design Choice 1: Multi-section requirement is load-bearing

Options Considered:

1. Implement full multi-section model (Variant C) - high cost, full DOCX fidelity
2. Single-section with sectPr-shaped options (hybrid) - medium cost, good DOCX mapping but no multi-section
3. Keep existing document-level options (Variant A) - low cost, adapter-based DOCX mapping

Chosen Option: 1

Rationale: The ticket explicitly requires multi-section support with per-section chrome, and the acceptance criteria includes "multi-section document shows independent margins / chrome / page-number formats per section."

Design Choice 2: Chrome registry storage location

Options Considered:

1. Store in plugin options alongside document value
2. Store as a separate top-level property in the serialized document shape
3. Store inline within Section nodes as nested children

Chosen Option: 2

Rationale: Separate top-level property mirrors DOCX's headerN.xml/footerN.xml architecture, keeps body editor clean, and simplifies DOCX round-trip mapping.

Design Choice 3: API compatibility approach

Options Considered:

1. Breaking change: Replace with getSections() returning sections with pages
2. Backward-compatible: Keep getPages() as flatMap over sections, add getSections() for advanced use
3. Deprecation path: Add getSections(), mark getPages() as deprecated

Chosen Option: 2

Rationale: Maintain backward compatibility by having getPages() internally flatten section pages, while exposing getSections() for consumers needing per-section access.

Design Choice 4: Migration strategy for existing documents

Options Considered:

1. Auto-migration in normalizer: wrap body in Section, move chrome to registry on first edit
2. Explicit migration utility: require consumer to call editor.tf.pagination.migrateToSections()
3. Dual-mode: support both legacy and new format indefinitely

Chosen Option: 1

Rationale: Auto-migration in normalizer ensures seamless upgrade path for existing documents without consumer code changes.

💡 User Tips

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

Implementation Steps

Phase 1: Type System & Data Model

Define the OOXML-aligned type system for sections, section properties, and chrome registry. This phase establishes the data contracts that all subsequent phases depend on.

Task 1: Define OOXML-Aligned Types

Add new types representing the section properties model, ensuring alignment with OOXML while remaining practical for the Plate context.

• Add to packages/pagination/src/lib/types.ts: SectPr type containing pgMar, pgSz, headerReference[], footerReference[], pgNumType, footnotePr, titlePg
• Define PgMar type with top, right, bottom, left, header, footer, gutter (all numbers in CSS px)
• Define PgSz type extending current PageSize with orient: 'portrait' | 'landscape'
• Define HeaderFooterReference type with id: string and type: 'default' | 'first' | 'even'
• Define PgNumType with start: number, fmt: 'decimal' | 'roman' | 'letter' | ..., position: 'bottom' | 'top' | 'none'
• Define FootnotePr with pos: 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd', numFmt, numStart

Task 2: Define Section Node Type

Create the Section element type that wraps body content and carries sectPr.

• Add SECTION_KEY = 'section' to packages/pagination/src/lib/internal/keys.ts
• Define TSection element type in types.ts with type: 'section', sectPr: SectPr, children: TElement[]
• Add BaseSectionPlugin in new file packages/pagination/src/lib/base-section-plugin.ts with void-like schema behavior

Task 3: Define Chrome Registry Types

Establish the separate storage structure for header/footer content.

• Define ChromeRegistryEntry type with id: string, content: TElement[]
• Define ChromeRegistry as Record<string, TElement[]>
• Define PaginationDocumentShape containing body: TElement[], chromeRegistry: ChromeRegistry
• Update BasePaginationOptions to include optional chromeRegistry for external persistence scenarios

🤖 Prompt for AI agents

Implement the OOXML-aligned type system and data model for the
section-properties pagination feature. All types should be added to or alongside
`packages/pagination/src/lib/types.ts` and
`packages/pagination/src/lib/internal/keys.ts`.

**Task 1.1 — OOXML-Aligned Types** (`packages/pagination/src/lib/types.ts`):
- Add `PgMar` type: fields `top`, `right`, `bottom`, `left`, `header`, `footer`,
`gutter` — all `number` (CSS px)
- Add `PgSz` type: extend current `PageSize` with `orient: 'portrait' |
'landscape'`
- Add `HeaderFooterReference` type: `id: string`, `type: 'default' | 'first' |
'even'`
- Add `PgNumType` type: `start: number`, `fmt: 'decimal' | 'roman' | 'letter' |
...`, `position: 'bottom' | 'top' | 'none'`
- Add `FootnotePr` type: `pos: 'pageBottom' | 'beneathText' | 'sectEnd' |
'docEnd'`, `numFmt`, `numStart`
- Add `SectPr` type: composes `pgMar: PgMar`, `pgSz: PgSz`, `headerReference:
HeaderFooterReference[]`, `footerReference: HeaderFooterReference[]`,
`pgNumType: PgNumType`, `footnotePr: FootnotePr`, `titlePg: boolean`

**Task 1.2 — Section Node Type**:
- Add `SECTION_KEY = 'section'` constant to
`packages/pagination/src/lib/internal/keys.ts`
- Add `TSection` element type in `types.ts`: `type: 'section'`, `sectPr:
SectPr`, `children: TElement[]`
- Create `packages/pagination/src/lib/base-section-plugin.ts` with
`BaseSectionPlugin` using void-like schema behavior

**Task 1.3 — Chrome Registry Types** (`packages/pagination/src/lib/types.ts`):
- Add `ChromeRegistryEntry` type: `id: string`, `content: TElement[]`
- Add `ChromeRegistry` type: `Record<string, TElement[]>`
- Add `PaginationDocumentShape` type: `body: TElement[]`, `chromeRegistry:
ChromeRegistry`
- Update `BasePaginationOptions` to include optional `chromeRegistry:
ChromeRegistry`

Phase 2: Plugin Infrastructure & Migration

Extend the plugin system to support sections and implement automatic migration from legacy format.

Task 1: Create Section Plugin

Build the Slate plugin for Section nodes with schema and basic normalization.

• Create packages/pagination/src/lib/base-section-plugin.ts extending createSlatePlugin
• Define schema: Section is block-level, contains block children, not void
• Register in BasePaginationPlugin.plugins array alongside existing header/footer/pageBreak plugins

Task 2: Implement Legacy Document Migration

Add normalizer logic to auto-wrap legacy documents into the new section structure.

• Create packages/pagination/src/lib/transforms/migrateToSectionModel.ts
• Detection: Check if editor.children contains any Section nodes; if not, treat as legacy
• Migration steps: (1) Extract header/footer nodes, (2) Generate IDs and populate chromeRegistry, (3) Wrap remaining body nodes in a single Section with default sectPr referencing the chrome IDs
• Call migration in BasePaginationPlugin.normalizeNode at path length 0, before enforceHeaderFooterInvariants

Task 3: Update Header/Footer Invariant Enforcement

Refactor the existing invariant normalizer to work with the new section model.

• Update packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts to operate within Section nodes rather than at document root
• Ensure each Section has valid sectPr.headerReference and sectPr.footerReference arrays
• Remove direct header/footer node enforcement from document root (now handled by chromeRegistry)

🤖 Prompt for AI agents

Extend the plugin system to support Section nodes and implement automatic
migration from the legacy format. This phase wires up the new
`BaseSectionPlugin`, adds a migration transform, and refactors the invariant
enforcer.

**Task 2.1 — Create Section Plugin**
(`packages/pagination/src/lib/base-section-plugin.ts`):
- Extend `createSlatePlugin` to define the Section plugin
- Schema: block-level node, contains block children, not void
- Register the plugin in `BasePaginationPlugin.plugins` array alongside existing
header/footer/pageBreak plugins

**Task 2.2 — Legacy Document Migration**
(`packages/pagination/src/lib/transforms/migrateToSectionModel.ts`):
- Detection: check `editor.children` for any `Section` nodes; if none found,
treat document as legacy
- Migration steps:
  1. Extract header/footer nodes from `editor.children`
  2. Generate IDs and populate `chromeRegistry` with extracted content
3. Wrap remaining body nodes in a single Section with default `sectPr`
referencing the generated chrome IDs
- Invoke this migration in `BasePaginationPlugin.normalizeNode` at path length
0, **before** `enforceHeaderFooterInvariants`

**Task 2.3 — Update Invariant Enforcement**
(`packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts`):
- Refactor to operate within Section nodes rather than at document root
- Ensure each Section has valid `sectPr.headerReference` and
`sectPr.footerReference` arrays
- Remove direct header/footer node enforcement from the document root (now
handled via `chromeRegistry`)

Phase 3: Per-Section Pagination Engine

Refactor the core pagination algorithm to process sections independently with their own geometry.

Task 1: Refactor paginate.ts for Section-Aware Pagination

Modify the bin-packing algorithm to walk section-by-section with varying page geometry.

• Update packages/pagination/src/lib/paginate.ts to accept Section[] instead of flat TElement[]
• For each Section: resolve PageRect from section.sectPr.pgSz and sectPr.pgMar
• Track section boundaries in output Page[] by adding sectionIndex: number to Page type
• Maintain pageIndexInSection: number alongside global pageIndex for first-page-different logic
• Handle inter-section page breaks (new section always starts new page)

Task 2: Extend Footnote Allocation for OOXML Modes

Implement all four footnote placement modes from sectPr.footnotePr.

• Update packages/pagination/src/lib/allocate-footnotes.ts to read section.sectPr.footnotePr.pos
• pageBottom: current behavior (footnote on same page as reference)
• beneathText: allocate to page but render below content, not in footer well
• sectEnd: accumulate all section footnotes, place on section's last page
• docEnd: accumulate all footnotes, place on document's final page(s)
• Return enriched Page[] with footnotes populated per the mode

Task 3: Add Section to Page Type

Extend the Page type to carry section context for rendering.

• Update Page type in types.ts to include sectionIndex: number, pageIndexInSection: number, sectPr: SectPr
• Update usePageLayout in packages/pagination/src/react/internal/use-page-layout.ts to pass sections through paginate and preserve sectPr on each page

🤖 Prompt for AI agents

Refactor the core pagination engine to process sections independently, each with
its own page geometry, footnote placement mode, and section-context metadata on
pages.

**Task 3.1 — Section-Aware paginate.ts**
(`packages/pagination/src/lib/paginate.ts`):
- Change input to accept `Section[]` instead of a flat `TElement[]`
- For each Section, resolve `PageRect` from `section.sectPr.pgSz` and
`sectPr.pgMar`
- Add `sectionIndex: number` to the `Page` type output
- Track `pageIndexInSection: number` alongside the global `pageIndex` counter
(used for first-page-different logic)
- Enforce that a new section always starts a new page (inter-section page break)

**Task 3.2 — Footnote Allocation Modes**
(`packages/pagination/src/lib/allocate-footnotes.ts`):
- Read `section.sectPr.footnotePr.pos` to determine placement mode
- Implement all four modes:
  - `pageBottom`: existing behavior — footnote on same page as reference
  - `beneathText`: allocate to page, render below content (not in footer well)
  - `sectEnd`: accumulate all section footnotes, place on section's last page
  - `docEnd`: accumulate all footnotes, place on document's final page(s)
- Return enriched `Page[]` with `footnotes` populated according to the active
mode

**Task 3.3 — Extend Page Type** (`packages/pagination/src/lib/types.ts` and
`packages/pagination/src/react/internal/use-page-layout.ts`):
- Update `Page` type to include `sectionIndex: number`, `pageIndexInSection:
number`, `sectPr: SectPr`
- Update `usePageLayout` to pass sections through `paginate` and ensure each
returned `Page` carries its `sectPr`

Phase 4: Rendering & Chrome Shell

Update PageFrame to consume per-section sectPr and mount chrome editors instead of static text.

Task 1: Refactor PageFrame for sectPr Consumption

Update the page renderer to read geometry and chrome from the page's sectPr.

• Update packages/pagination/src/react/page-frame.tsx to receive page.sectPr instead of global chrome heights
• Derive header/footer heights from sectPr.pgMar.header and sectPr.pgMar.footer
• Derive page geometry from sectPr.pgSz and sectPr.pgMar
• Resolve chrome content from chromeRegistry using sectPr.headerReference / sectPr.footerReference

Task 2: Implement First-Page-Different Logic

Handle titlePg flag for varying chrome on section's first page.

• In PageFrame, check page.sectPr.titlePg and page.pageIndexInSection === 0
• When true, resolve chrome using headerReference.find(r => r.type === 'first') instead of 'default'
• Fall back to 'default' if no 'first' reference exists

Task 3: Implement Page Number Rendering from pgNumType

Replace hardcoded page number with sectPr-driven formatting.

• Read page.sectPr.pgNumType for fmt, start, position
• Calculate display number: sectPr.pgNumType.start + pageIndexInSection (or global depending on restart behavior)
• Format according to fmt: decimal, roman (I, II, III), letter (A, B, C)
• Position in header or footer based on position field
• Render as non-editable span within the chrome region

Task 4: Chrome Shell UX Foundation

Implement basic chrome region interaction with section-aware labeling.

• Add data-chrome-id and data-section-index attributes to chrome regions in PageFrame
• Display label overlay when chrome region is hovered/focused: "Section {n} — header ({type})"
• Wire click handler to emit event for focusing the corresponding chrome editor (actual focus handling is consumer-level)

🤖 Prompt for AI agents

Update `packages/pagination/src/react/page-frame.tsx` to consume per-section
`sectPr` from each `Page` object, implementing first-page-different chrome,
pgNumType-driven page number formatting, and basic chrome shell UX.

**Task 4.1 — PageFrame sectPr Consumption** (`page-frame.tsx`):
- Receive `page.sectPr` instead of global chrome heights
- Derive header/footer heights from `sectPr.pgMar.header` /
`sectPr.pgMar.footer`
- Derive page geometry from `sectPr.pgSz` and `sectPr.pgMar`
- Resolve chrome content from `chromeRegistry` using `sectPr.headerReference` /
`sectPr.footerReference`

**Task 4.2 — First-Page-Different Logic** (`page-frame.tsx`):
- Check `page.sectPr.titlePg && page.pageIndexInSection === 0`
- When true, resolve chrome using `headerReference.find(r => r.type ===
'first')` instead of `'default'`
- Fall back to `'default'` if no `'first'` reference exists

**Task 4.3 — Page Number Rendering** (`page-frame.tsx`):
- Read `page.sectPr.pgNumType` for `fmt`, `start`, and `position`
- Calculate display number as `sectPr.pgNumType.start + pageIndexInSection` (or
global depending on restart behavior)
- Format by `fmt`: decimal, roman (I, II, III), letter (A, B, C)
- Position in header or footer based on the `position` field
- Render as a non-editable `<span>` within the chrome region

**Task 4.4 — Chrome Shell UX** (`page-frame.tsx`):
- Add `data-chrome-id` and `data-section-index` attributes to chrome region
elements
- Show a label overlay on hover/focus: `"Section {n} — header ({type})"`
- Wire a click handler to emit an event for focusing the corresponding chrome
editor (consumer-level focus handling is out of scope)

Phase 5: API Surface Updates

Extend the editor API to support section-aware queries and transforms.

Task 1: Add Section-Aware API Methods

Extend BasePaginationApi with section-level queries.

• Add getSections(): Section[] returning all sections from editor.children
• Add getSectionOf(path: number[]): number mapping a path to its section index
• Add getPageOf(path: number[]): { sectionIndex: number, pageIndex: number, pageIndexInSection: number }
• Keep existing getPages() as getSections().flatMap(s => s.pages) for backward compatibility

Task 2: Add Section-Aware Transforms

Extend BasePaginationTransforms for per-section operations.

• Add setSectPr(sectionIndex: number, sectPr: Partial<SectPr>) to update a section's properties
• Add insertSection(at: number, sectPr?: SectPr) to add a new section
• Add setHeaderContent(chromeId: string, content: Descendant[]) operating on chromeRegistry
• Add setFooterContent(chromeId: string, content: Descendant[]) operating on chromeRegistry
• Deprecate document-level setMargins, setPageSize in favor of setSectPr

Task 3: Update Chrome Registry Management

Add API methods for chrome registry CRUD operations.

• Add getChromeContent(id: string): TElement[] | undefined to read from registry
• Add setChromeContent(id: string, content: TElement[]): void to write to registry
• Add createChromeEntry(type: 'header' | 'footer'): string returning new ID with default content
• Wire these through plugin options or a dedicated store mechanism

🤖 Prompt for AI agents

Extend `BasePaginationApi` and `BasePaginationTransforms` with section-aware
query and mutation methods, and add chrome registry CRUD to the API surface.

**Task 5.1 — Section-Aware API Methods** (`BasePaginationApi`):
- Add `getSections(): Section[]` — returns all Section nodes from
`editor.children`
- Add `getSectionOf(path: number[]): number` — maps a node path to its
containing section index
- Add `getPageOf(path: number[]): { sectionIndex: number, pageIndex: number,
pageIndexInSection: number }`
- Update existing `getPages()` to be implemented as `getSections().flatMap(s =>
s.pages)` for backward compatibility

**Task 5.2 — Section-Aware Transforms** (`BasePaginationTransforms`):
- Add `setSectPr(sectionIndex: number, sectPr: Partial<SectPr>)` — update a
section's properties
- Add `insertSection(at: number, sectPr?: SectPr)` — insert a new section at the
given index
- Add `setHeaderContent(chromeId: string, content: Descendant[])` — write to
chromeRegistry
- Add `setFooterContent(chromeId: string, content: Descendant[])` — write to
chromeRegistry
- Mark document-level `setMargins` and `setPageSize` as deprecated in favor of
`setSectPr`

**Task 5.3 — Chrome Registry Management** (API layer):
- Add `getChromeContent(id: string): TElement[] | undefined` — read from
chromeRegistry
- Add `setChromeContent(id: string, content: TElement[]): void` — write to
chromeRegistry
- Add `createChromeEntry(type: 'header' | 'footer'): string` — create a new
entry with default content, return its ID
- Wire these through plugin options or a dedicated store mechanism

Phase 6: DOCX Integration

Wire the section model to docx-io for near-direct import/export mapping.

Task 1: Update DOCX Export for sectPr

Extend docx-io to consume Section nodes and chromeRegistry for export.

• Update packages/docx-io/src/lib/docx-export-plugin.tsx to extract Sections from editor.children
• For each Section, call generateSectionXML with sectPr-derived parameters
• Resolve chromeRegistry entries and pass as headerHTMLString/footerHTMLString to addFilesToContainer
• Map sectPr.pgNumType to <w:pgNumType> in the generated <w:sectPr>

Task 2: Update DOCX Import for sectPr

Extend import to read section properties and populate chromeRegistry.

• Update packages/docx-io/src/lib/importDocx.ts to use a custom mammoth transformer or post-processor
• Extract headerN.xml and footerN.xml content from the DOCX ZIP directly (mammoth discards these)
• Parse <w:sectPr> from document.xml to build SectPr objects
• Populate chromeRegistry with converted header/footer content
• Wrap body content in Section nodes with appropriate sectPr.headerReference/footerReference

Task 3: Expose Chrome Registry in Document Serialization

Ensure chromeRegistry persists alongside the document body.

• Define serialization shape: { body: TElement[], chromeRegistry: ChromeRegistry }
• Update any editor.api.pagination methods that return document value to include chromeRegistry
• Document the shape for consumers implementing custom persistence

🤖 Prompt for AI agents

Wire the new section model to `packages/docx-io` for near-direct DOCX import and
export, and define the document serialization shape that persists
`chromeRegistry` alongside the body.

**Task 6.1 — DOCX Export** (`packages/docx-io/src/lib/docx-export-plugin.tsx`):
- Extract Section nodes from `editor.children`
- For each Section, call `generateSectionXML` with parameters derived from
`sectPr`
- Resolve `chromeRegistry` entries and pass as
`headerHTMLString`/`footerHTMLString` to `addFilesToContainer`
- Map `sectPr.pgNumType` to `<w:pgNumType>` inside the generated `<w:sectPr>`
XML

**Task 6.2 — DOCX Import** (`packages/docx-io/src/lib/importDocx.ts`):
- Use a custom mammoth transformer or post-processor to handle section data
- Extract `headerN.xml` and `footerN.xml` directly from the DOCX ZIP (mammoth
discards these)
- Parse `<w:sectPr>` from `document.xml` to construct `SectPr` objects
- Populate `chromeRegistry` with the converted header/footer content
- Wrap imported body content in Section nodes with appropriate
`sectPr.headerReference`/`footerReference`

**Task 6.3 — Document Serialization Shape**:
- Define and enforce the serialization shape: `{ body: TElement[],
chromeRegistry: ChromeRegistry }`
- Update any `editor.api.pagination` methods that return the document value to
include `chromeRegistry`
- Document the shape for consumers implementing custom persistence

Research

The pagination package (packages/pagination) currently implements a render-time overlay approach (Variant A) where pages are derived at render time rather than persisted. The system uses document-level options (BasePaginationOptions) for a single set of margins, page size, and chrome heights. Headers and footers are stored as top-level nodes in editor.children with normalizer enforcement. The paginate.ts function performs greedy bin-packing over all blocks uniformly, while allocate-footnotes.ts assigns footnotes to the first page containing a reference. The page-frame.tsx component renders chrome via simple text extraction (collectInlineText). The packages/docx-io package has internal machinery for headers/footers (generateHeaderXML, generateFooterXML) but doesn't expose it in the public API.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the OOXML-aligned type system and data model for the
section-properties pagination feature. All types should be added to or alongside
`packages/pagination/src/lib/types.ts` and
`packages/pagination/src/lib/internal/keys.ts`.

**Task 1.1 — OOXML-Aligned Types** (`packages/pagination/src/lib/types.ts`):
- Add `PgMar` type: fields `top`, `right`, `bottom`, `left`, `header`, `footer`,
`gutter` — all `number` (CSS px)
- Add `PgSz` type: extend current `PageSize` with `orient: 'portrait' |
'landscape'`
- Add `HeaderFooterReference` type: `id: string`, `type: 'default' | 'first' |
'even'`
- Add `PgNumType` type: `start: number`, `fmt: 'decimal' | 'roman' | 'letter' |
...`, `position: 'bottom' | 'top' | 'none'`
- Add `FootnotePr` type: `pos: 'pageBottom' | 'beneathText' | 'sectEnd' |
'docEnd'`, `numFmt`, `numStart`
- Add `SectPr` type: composes `pgMar: PgMar`, `pgSz: PgSz`, `headerReference:
HeaderFooterReference[]`, `footerReference: HeaderFooterReference[]`,
`pgNumType: PgNumType`, `footnotePr: FootnotePr`, `titlePg: boolean`

**Task 1.2 — Section Node Type**:
- Add `SECTION_KEY = 'section'` constant to
`packages/pagination/src/lib/internal/keys.ts`
- Add `TSection` element type in `types.ts`: `type: 'section'`, `sectPr:
SectPr`, `children: TElement[]`
- Create `packages/pagination/src/lib/base-section-plugin.ts` with
`BaseSectionPlugin` using void-like schema behavior

**Task 1.3 — Chrome Registry Types** (`packages/pagination/src/lib/types.ts`):
- Add `ChromeRegistryEntry` type: `id: string`, `content: TElement[]`
- Add `ChromeRegistry` type: `Record<string, TElement[]>`
- Add `PaginationDocumentShape` type: `body: TElement[]`, `chromeRegistry:
ChromeRegistry`
- Update `BasePaginationOptions` to include optional `chromeRegistry:
ChromeRegistry`
===============================================================================

Task: 2

Extend the plugin system to support Section nodes and implement automatic
migration from the legacy format. This phase wires up the new
`BaseSectionPlugin`, adds a migration transform, and refactors the invariant
enforcer.

**Task 2.1 — Create Section Plugin**
(`packages/pagination/src/lib/base-section-plugin.ts`):
- Extend `createSlatePlugin` to define the Section plugin
- Schema: block-level node, contains block children, not void
- Register the plugin in `BasePaginationPlugin.plugins` array alongside existing
header/footer/pageBreak plugins

**Task 2.2 — Legacy Document Migration**
(`packages/pagination/src/lib/transforms/migrateToSectionModel.ts`):
- Detection: check `editor.children` for any `Section` nodes; if none found,
treat document as legacy
- Migration steps:
  1. Extract header/footer nodes from `editor.children`
  2. Generate IDs and populate `chromeRegistry` with extracted content
3. Wrap remaining body nodes in a single Section with default `sectPr`
referencing the generated chrome IDs
- Invoke this migration in `BasePaginationPlugin.normalizeNode` at path length
0, **before** `enforceHeaderFooterInvariants`

**Task 2.3 — Update Invariant Enforcement**
(`packages/pagination/src/lib/transforms/enforceHeaderFooterInvariants.ts`):
- Refactor to operate within Section nodes rather than at document root
- Ensure each Section has valid `sectPr.headerReference` and
`sectPr.footerReference` arrays
- Remove direct header/footer node enforcement from the document root (now
handled via `chromeRegistry`)
===============================================================================

Task: 3

Refactor the core pagination engine to process sections independently, each with
its own page geometry, footnote placement mode, and section-context metadata on
pages.

**Task 3.1 — Section-Aware paginate.ts**
(`packages/pagination/src/lib/paginate.ts`):
- Change input to accept `Section[]` instead of a flat `TElement[]`
- For each Section, resolve `PageRect` from `section.sectPr.pgSz` and
`sectPr.pgMar`
- Add `sectionIndex: number` to the `Page` type output
- Track `pageIndexInSection: number` alongside the global `pageIndex` counter
(used for first-page-different logic)
- Enforce that a new section always starts a new page (inter-section page break)

**Task 3.2 — Footnote Allocation Modes**
(`packages/pagination/src/lib/allocate-footnotes.ts`):
- Read `section.sectPr.footnotePr.pos` to determine placement mode
- Implement all four modes:
  - `pageBottom`: existing behavior — footnote on same page as reference
  - `beneathText`: allocate to page, render below content (not in footer well)
  - `sectEnd`: accumulate all section footnotes, place on section's last page
  - `docEnd`: accumulate all footnotes, place on document's final page(s)
- Return enriched `Page[]` with `footnotes` populated according to the active
mode

**Task 3.3 — Extend Page Type** (`packages/pagination/src/lib/types.ts` and
`packages/pagination/src/react/internal/use-page-layout.ts`):
- Update `Page` type to include `sectionIndex: number`, `pageIndexInSection:
number`, `sectPr: SectPr`
- Update `usePageLayout` to pass sections through `paginate` and ensure each
returned `Page` carries its `sectPr`
===============================================================================

Task: 4

Update `packages/pagination/src/react/page-frame.tsx` to consume per-section
`sectPr` from each `Page` object, implementing first-page-different chrome,
pgNumType-driven page number formatting, and basic chrome shell UX.

**Task 4.1 — PageFrame sectPr Consumption** (`page-frame.tsx`):
- Receive `page.sectPr` instead of global chrome heights
- Derive header/footer heights from `sectPr.pgMar.header` /
`sectPr.pgMar.footer`
- Derive page geometry from `sectPr.pgSz` and `sectPr.pgMar`
- Resolve chrome content from `chromeRegistry` using `sectPr.headerReference` /
`sectPr.footerReference`

**Task 4.2 — First-Page-Different Logic** (`page-frame.tsx`):
- Check `page.sectPr.titlePg && page.pageIndexInSection === 0`
- When true, resolve chrome using `headerReference.find(r => r.type ===
'first')` instead of `'default'`
- Fall back to `'default'` if no `'first'` reference exists

**Task 4.3 — Page Number Rendering** (`page-frame.tsx`):
- Read `page.sectPr.pgNumType` for `fmt`, `start`, and `position`
- Calculate display number as `sectPr.pgNumType.start + pageIndexInSection` (or
global depending on restart behavior)
- Format by `fmt`: decimal, roman (I, II, III), letter (A, B, C)
- Position in header or footer based on the `position` field
- Render as a non-editable `<span>` within the chrome region

**Task 4.4 — Chrome Shell UX** (`page-frame.tsx`):
- Add `data-chrome-id` and `data-section-index` attributes to chrome region
elements
- Show a label overlay on hover/focus: `"Section {n} — header ({type})"`
- Wire a click handler to emit an event for focusing the corresponding chrome
editor (consumer-level focus handling is out of scope)
===============================================================================

Task: 5

Extend `BasePaginationApi` and `BasePaginationTransforms` with section-aware
query and mutation methods, and add chrome registry CRUD to the API surface.

**Task 5.1 — Section-Aware API Methods** (`BasePaginationApi`):
- Add `getSections(): Section[]` — returns all Section nodes from
`editor.children`
- Add `getSectionOf(path: number[]): number` — maps a node path to its
containing section index
- Add `getPageOf(path: number[]): { sectionIndex: number, pageIndex: number,
pageIndexInSection: number }`
- Update existing `getPages()` to be implemented as `getSections().flatMap(s =>
s.pages)` for backward compatibility

**Task 5.2 — Section-Aware Transforms** (`BasePaginationTransforms`):
- Add `setSectPr(sectionIndex: number, sectPr: Partial<SectPr>)` — update a
section's properties
- Add `insertSection(at: number, sectPr?: SectPr)` — insert a new section at the
given index
- Add `setHeaderContent(chromeId: string, content: Descendant[])` — write to
chromeRegistry
- Add `setFooterContent(chromeId: string, content: Descendant[])` — write to
chromeRegistry
- Mark document-level `setMargins` and `setPageSize` as deprecated in favor of
`setSectPr`

**Task 5.3 — Chrome Registry Management** (API layer):
- Add `getChromeContent(id: string): TElement[] | undefined` — read from
chromeRegistry
- Add `setChromeContent(id: string, content: TElement[]): void` — write to
chromeRegistry
- Add `createChromeEntry(type: 'header' | 'footer'): string` — create a new
entry with default content, return its ID
- Wire these through plugin options or a dedicated store mechanism
===============================================================================

Task: 6

Wire the new section model to `packages/docx-io` for near-direct DOCX import and
export, and define the document serialization shape that persists
`chromeRegistry` alongside the body.

**Task 6.1 — DOCX Export** (`packages/docx-io/src/lib/docx-export-plugin.tsx`):
- Extract Section nodes from `editor.children`
- For each Section, call `generateSectionXML` with parameters derived from
`sectPr`
- Resolve `chromeRegistry` entries and pass as
`headerHTMLString`/`footerHTMLString` to `addFilesToContainer`
- Map `sectPr.pgNumType` to `<w:pgNumType>` inside the generated `<w:sectPr>`
XML

**Task 6.2 — DOCX Import** (`packages/docx-io/src/lib/importDocx.ts`):
- Use a custom mammoth transformer or post-processor to handle section data
- Extract `headerN.xml` and `footerN.xml` directly from the DOCX ZIP (mammoth
discards these)
- Parse `<w:sectPr>` from `document.xml` to construct `SectPr` objects
- Populate `chromeRegistry` with the converted header/footer content
- Wrap imported body content in Section nodes with appropriate
`sectPr.headerReference`/`footerReference`

**Task 6.3 — Document Serialization Shape**:
- Define and enforce the serialization shape: `{ body: TElement[],
chromeRegistry: ChromeRegistry }`
- Update any `editor.api.pagination` methods that return the document value to
include `chromeRegistry`
- Document the shape for consumers implementing custom persistence

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

⚠️ Possible Duplicate Issue(s)

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

🔗 Related PRs

#16 - Add DOCX export feature with Slate plugin and UI components [merged]
#84 - Feat/docx import export suggestions comments [merged]
#97 - Revert staging to ebf750c [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!