Paged-view production parity: hybrid synthesis + body-opacity-dim on chrome focus (variant D)

[arthrod]

@coderabbitai plan

🥕 multi-assumptions: variant D (hybrid synthesis) of 4 parallel framings of the same goal.
Sibling variant(s): #384, #385, #386. This variant cherry-picks across A/B/C and adds one new piece — body-opacity dim on chrome focus — that none of the prior framings covered.

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 D — hybrid synthesis with body-opacity-dim UX)

This variant is B's spine (overlay store + sub-editors) with grafts from A (transform proxies, comprehensive Page Setup dialog) and C (titlePg flag instead of dedicated node types, HeaderFooterReference[]-shaped chrome IDs, four-mode footnote placement, page-number fmt), plus one novel piece:

The opacity-dim UX (new in D): when any chrome editor (header / footer / first-page-header / first-page-footer) has focus, the body editor visually dims to ~50% opacity with a 200ms transition. This is how Word and Pages signal "you are editing chrome, not body" — and it is the actual user fix for "header and footer when selected creates an ugly text". The chrome shell label and focus ring (B/A) are not enough on their own; the body must visually recede.

1. State (B + C grafted): introduce pageLayoutStore (Zustand or context) with B's shape — margins, pageSize, headerHeight, footerHeight, footnoteWell, pageNumber, chrome editor IDs — but model the chrome IDs as C's HeaderFooterReference[] with type: 'default' | 'first' | 'even' (only 'default' and 'first' used in v1). Persist to a top-level pageLayout field in document metadata.
2. First-page-different (C grafted): titlePg: boolean flag in the store. When pageIndex === 0 and titlePg === true, PageFrame resolves chrome via headerReferences.find(r => r.type === 'first') instead of 'default', falling back to default. No new node types — A's firstPageHeader/firstPageFooter types are discarded.
3. Footnote placement (C grafted): widen FootnotePlacement to 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd' (current 'footer' aliases to 'pageBottom', current 'documentEnd' aliases to 'docEnd'). v1 implements pageBottom and docEnd; beneathText and sectEnd are accepted by the type but warn-and-fall-back-to-pageBottom until phase 2.
4. Page-number config (C grafted): PageNumberConfig carries region, align, format: 'decimal' | 'roman' | 'letter' | '1/N' | 'page-of-n', startAt, hideOnFirst. <PageNumber> is a non-editable React element rendered inside chrome regions, positioned via store config — never a Slate void, so body selection cannot delete or move it.
5. Chrome sub-editors (B): header / footer / first-page-header / first-page-footer become separate Plate editor instances mounted by PageOverlay, sharing the body editor's plugin list. Single-line content constraint via schema. Cross-editor focus tracked by useChromeFocusContext (new).
6. Body-opacity-dim (D — new): ChromeFocusContext exposes activeChromeId: string | null. PageOverlay wraps body editor in a div whose data-chrome-active attribute toggles when activeChromeId is set; CSS uses that attribute selector to apply opacity: 0.5 + transition: opacity 200ms ease-out to the body. Optional chromeFocusDimsBody flag in store (default true) for users who want to disable.
7. PlateStatic gap fix (B): chrome regions in paged preview render through live sub-editors, not PlateStatic. The static-safe filter in getElementOnlyStaticPlugins (page-frame.tsx:322-362) only matters for the print/PDF path, not on-screen paged preview. AI / comments / suggestions / drag-handle "just work" inside chrome (since they are real editors).
8. Page Setup dialog (A grafted): promote MarginsDialog to a full PageSetupDialog covering margins (per-axis numeric + cm/in/mm/px), page-size presets, chrome heights, page-number config, first-page-different toggle, footnote placement (4-mode dropdown), and chromeFocusDimsBody toggle. Wire to store via existing editor.tf.pagination.* transforms — keep them as proxies for back-compat (A's pattern).
9. Auto-migration (C grafted): when an existing document with body-level header/footer nodes loads, a normalizer extracts them into the chrome registry on first edit; body header/footer nodes are removed. Single-shot, idempotent. Existing single-doc-header documents become single-section-no-titlePg documents.
10. DOCX round-trip (B + C path): importer maps DOCX sectPr.titlePg → store.titlePg, headerReference[type=first] → first-page chrome ID, pgNumType → store.pageNumber, footnotePr.pos → store.footnotePlacement. Single-section assumption baked in for v1; multi-section is a follow-up that does not require a re-architecture (because the chrome reference shape is already C-shaped).

Acceptance: in dev-browser, paged mode shows live, fully-functional header/footer editors (typing in header works without "ugly text"); clicking a chrome region focuses it AND dims the body editor to 50% opacity with a smooth 200ms transition; first page can have a different header via titlePg; page-number position/format is store-driven (decimal vs roman vs Page 1 of N); Page Setup dialog edits margins/heights/footnote placement (with 4 modes selectable in UI even if beneathText/sectEnd warn-fallback); on-screen paged preview renders ALL live editor plugins (AI, comments, suggestions, drag-handle) inside body since it is a real editor, not PlateStatic.

Because the code is

• packages/pagination/src/lib/types.ts — BasePaginationOptions already has margins, mode, footnotePlacement (only 2 modes), headerHeight, footerHeight, footnoteWell. Variant D widens FootnotePlacement, adds pageNumber, firstPageDifferent/titlePg, chromeFocusDimsBody, and a chromeReferences shape. All additive.
• packages/pagination/src/react/page-frame.tsx:107-158 — chrome regions today render via StaticPageValue (PlateStatic). Replacing with live sub-editors removes the static-filter surface for paged preview entirely (variant B's fix).
• 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 is the source of "PlateStatic page viewer doesn't render several plugins". Variant D matches B's framing: only the print/PDF path needs this filter.
• packages/pagination/src/react/margins-dialog.tsx — minimal v1 native <dialog>; only edits the four margin sides. Variant D promotes it to comprehensive PageSetupDialog.
• packages/pagination/src/lib/transforms/ensureHeader.ts / ensureFooter.ts — body-coupled chrome nodes; variant D's auto-migration turns them into chromeRegistry entries on first load.
• packages/pagination/src/lib/allocate-footnotes.ts — currently switches on 'footer' | 'documentEnd'; variant D widens to 4 modes (with backward-compat aliases for the two existing strings).
• packages/pagination/src/lib/base-pagination-plugin.ts — defines transforms; variant D adds setPageNumber, setFirstPageDifferent, setChromeFocusDimsBody, and proxies them through to the store.
• Sibling issues Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant A — schema-first) #384 (variant A), Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant B — overlay store + sub-editors) #385 (variant B), Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant C — OOXML section model) #386 (variant C) — each plan was generated by @coderabbitai plan. Variant D explicitly synthesizes across them per the Mix-and-match analysis below.

Mix-and-match analysis (what came from where)

Concern	A says	B says	C says	D picks
Where layout state lives	editor.options + editor.children chrome nodes	external pageLayoutStore + chrome sub-editors	chromeRegistry + Section.sectPr	B (store + sub-editors) — but with C's reference shape
First-page rule	dedicated firstPageHeader/firstPageFooter node types	store flag swaps editors	titlePg + titlePgHdrRef/titlePgFtrRef	C (titlePg flag) — cleaner, opens door to multi-section later
Page-number formats	'1' | '1/N' | 'Page 1 of N'	not specified beyond config shape	'decimal' | 'roman' | 'letter' from pgNumType	C (decimal/roman/letter) + A's vocabulary kept as aliases
Footnote placement modes	'perPage' | 'documentEnd'	placement flag, modes not specified	4 modes: pageBottom | beneathText | sectEnd | docEnd	C (4 modes); v1 implements 2, others warn-fallback
PlateStatic plugin coverage	per-plugin staticSafe opt-in	sub-editors render natively in paged mode	per-section chrome editors mount with full plugin set	B — A's staticSafe was rejected as unworkable since chrome-only plugins need live state
Page Setup dialog	"create comprehensive from start"	not specified	not specified	A (one comprehensive dialog) — avoids partial iterations
Persistence	options + chrome nodes in editor.children	document metadata field	separate top-level property	B's pageLayout metadata field — same shape as C's separate property, simpler name
Migration	schema-additive	not specified explicitly	auto-migration in normalizer	C (auto-migration) — applied to B's store, not C's section model
Body dim on chrome focus	not covered	not covered	not covered	D's novel piece — none of A/B/C addressed the visual recession that the user explicitly called out

Assumptions deliberately shuffled vs variant B

Axis	Variant D	Variant B
Chrome reference shape	C-style HeaderFooterReference[] with type: 'default' | 'first' | 'even'	flat headerEditorId / footerEditorId strings + separate firstPageHeaderEditorId / firstPageFooterEditorId
First-page rule	titlePg flag (single source of truth, OOXML-aligned)	firstPageDifferent flag + 4 separate ID fields
Page-number formats	'decimal' | 'roman' | 'letter' | '1/N' | 'page-of-n'	not specified beyond format: 'decimal' | 'roman' | 'letter' (similar but D adds 1/N and page-of-n aliases for back-compat)
Body recede UX	explicit opacity-dim with 200ms transition + opt-out flag	not addressed
Footnote modes	4 (pageBottom/beneathText/sectEnd/docEnd) with v1 partial implementation	'page' | 'documentEnd' (2)
Auto-migration	yes — extract body chrome nodes into store on first load	not specified
Future multi-section path	reference-based shape can extend to multi-section without API break	flat IDs need restructuring to support sections

Assumptions deliberately shuffled vs variant C

Axis	Variant D	Variant C
Section abstraction	none (single-section)	first-class Section nodes carrying sectPr
Granularity	document-level	per-section
Implementation cost	medium (B's spine + selective C grafts)	high (full OOXML alignment + per-section pagination)
DOCX round-trip	adapter maps store ↔ sectPr (single section)	near-direct
Page-number pgNumType	borrowed format/start fields	full pgNumType per section
Reversibility	medium (store + chrome editors)	medium (sections persist)
Future-proofing	reference-shape extensible to per-section later	already there

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/page-overlay.tsx, packages/pagination/src/react/margins-dialog.tsx, packages/pagination/src/lib/paginate.ts, packages/pagination/src/lib/allocate-footnotes.ts, packages/pagination/src/lib/transforms/.
• Review of our own code in packages/pagination/src/, packages/core/src/static/components/PlateStatic.tsx, apps/www/src/registry/components/editor/plugins/pagination-kit.tsx.
• Comparative analysis vs siblings Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant A — schema-first) #384, Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant B — overlay store + sub-editors) #385, 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 for variant D vs each: e.g. "If the body must remain a real editor in paged preview (sub-editor cost is tolerable), variant D wins over A; otherwise A wins." "If we don't need multi-section in the next 12 months, variant D wins over C; if we do, C wins." Don't pick a winner yet — name the axis per pair.
• Body-dim correctness questions — does dimming the body editor to 50% interfere with focus rings of decoration plugins (cursor, comments, AI suggestions) that render inside it? Should the dim use opacity (affects child visibility) or a CSS filter: brightness(0.6) (cheaper for some browsers)? Is there an a11y concern (low-contrast text during chrome editing) we should opt-out of for users who set prefers-reduced-motion or have contrast preferences?
• Auto-migration safety — for existing documents with body-level header/footer nodes, when does the normalizer fire (mount? first edit?) and is it idempotent across multiple loads on the same client? What happens if two collaborators load an unmigrated doc simultaneously and migrate independently?
• Page-number numbering with titlePg — when first-page-different is on AND pageNumber.hideOnFirst === false, does the first page show "1" or skip to "2"? Word's behavior: shows 1 on title page if hideOnFirst is false. Confirm we match.
• beneathText vs sectEnd warn-fallback semantics — exactly what should we do when a user picks these in v1? Silent fallback to pageBottom? Loud console warning? UI toast?
• Single-line constraint on chrome editors — soft (visual clipping) or hard (schema rejects multi-block paste)? DOCX headers can have multi-line content; hard rejection breaks DOCX round-trip.

Full plan

1. Type extensions in types.ts: widen FootnotePlacement to 4 modes (with backward-compat aliases), add PageNumberConfig, HeaderFooterReference, titlePg, chromeFocusDimsBody, pageNumber on BasePaginationOptions.
2. Define pageLayoutStore (Zustand) shape + PageLayoutProvider + persistence to pageLayout document metadata field.
3. Build chrome sub-editor infrastructure: createChromeEditor, ChromeEditorMount, schema constraint for single-line.
4. useChromeFocusContext + body-opacity-dim wiring (CSS attribute selector, 200ms transition, respects prefers-reduced-motion).
5. ChromeShell component (label + focus ring + exit affordance + dim trigger).
6. PageNumber non-editable component reading store config; render in chrome regions.
7. Refactor PageFrame chrome regions to mount sub-editors instead of StaticPageValue; consume store for chrome heights / margins / pageNumber.
8. titlePg swap logic in PageFrame for pageIndex === 0 based on store + reference array.
9. Promote MarginsDialog → PageSetupDialog covering all options, wired through editor.tf.pagination.* transforms (kept as proxies into the store).
10. Widen allocate-footnotes.ts to 4 modes: pageBottom and docEnd work; beneathText/sectEnd warn-fallback to pageBottom with TODO.
11. Auto-migration normalizer: extract body header/footer nodes → chromeRegistry → remove from editor.children.
12. Update DOCX I/O adapter (if packages/docx-io* exists) to map titlePg, headerReference[type=first], pgNumType, footnotePr.pos.
13. dev-browser verification of all 7 user-reported issues + the body-dim transition.

References

• Sibling issues Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant A — schema-first) #384, Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant B — overlay store + sub-editors) #385, Paged-view production parity: margins, chrome UX, page numbers, first-page, footnotes, PlateStatic plugin coverage (variant C — OOXML section model) #386
• packages/pagination/src/
• branch codex/pagination-variant-a
• ECMA-376 §17.6 (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), #385 (overlay store + sub-editors), #386 (OOXML section model). Variant D is a hybrid synthesis that picks B's spine (sub-editors), C's titlePg/reference shape and 4-mode footnotes, A's comprehensive Page Setup dialog and transform proxies, plus a novel body-opacity-dim UX none of A/B/C addressed.

[coderabbitai]

Coding Plan

Summary

• Introduce a Zustand-based pageLayoutStore as the single source of truth for page layout state, following the ImagePreviewStore pattern established in the codebase
• Replace static text rendering in chrome regions with live Plate sub-editors, solving the "chrome-only plugins don't render" problem by making chrome regions fully functional editors
• Implement body-opacity-dim using a CSS pseudo-element overlay approach to avoid affecting cursor/selection rendering inside the body editor
• Model chrome references as an array with type: 'default' | 'first' | 'even' discriminator, enabling future multi-section support without API breaks

Design Choices

Design Choice 1: Chrome editor single-line constraint approach

Options Considered:

1. Soft constraint: Visual clipping with overflow hidden, allowing multi-line content to exist in the model for DOCX round-trip compatibility
2. Hard constraint: Schema rejection that prevents multi-block paste, breaking DOCX import of multi-line headers

Chosen Option: 1

Rationale: Soft visual constraint with optional height clamping—DOCX headers can legitimately contain multiple paragraphs, and hard rejection would break import fidelity.

Design Choice 2: Body dim implementation technique

Options Considered:

1. opacity: 0.5 on the body wrapper—simple, well-supported, but affects all descendants including cursor/selection overlays
2. filter: brightness(0.6) on body wrapper—may have better performance on some browsers, still affects descendants
3. Pseudo-element overlay with pointer-events: none and semi-transparent background—preserves child rendering fidelity

Chosen Option: 3

Rationale: Pseudo-element overlay—this avoids inadvertently dimming cursor/comment/AI overlays that render inside the body editor and provides the cleanest visual separation.

Design Choice 3: Warn-fallback semantics for unimplemented footnote modes

Options Considered:

1. Silent fallback to pageBottom without user notification
2. Console warning during pagination cycle
3. UI toast notification when mode is selected in Page Setup dialog

Chosen Option: 3

Rationale: UI toast at selection time—user should know immediately that their chosen mode is not yet implemented, not discover it silently later.

Design Choice 4: Auto-migration trigger timing

Options Considered:

1. On editor mount (before first render)
2. On first user edit (lazy migration)
3. During DOCX import only

Chosen Option: 1

Rationale: On editor mount via normalizeInitialValue—ensures consistent state before any rendering occurs and avoids race conditions in collaborative scenarios where two clients might migrate simultaneously.

💡 User Tips

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

Implementation Steps

Phase 1: Type System Extensions

Extend the pagination type definitions to support all new features. This phase establishes the data contracts that all subsequent phases depend on.

Task 1: Define Chrome Reference and Page Number Types

Add new types for chrome editor references and page number configuration.

• Add HeaderFooterReference type to packages/pagination/src/lib/types.ts with shape { id: string; type: 'default' | 'first' | 'even'; content: Descendant[] }
• Add PageNumberConfig type with region: 'header' | 'footer', align: 'left' | 'center' | 'right', format: 'decimal' | 'roman' | 'letter' | '1/N' | 'page-of-n', startAt: number, hideOnFirst: boolean
• Add FootnotePlacement union type: 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd'

Task 2: Extend BasePaginationOptions

Widen the existing options type to include new configuration fields.

• Add titlePg: boolean (default false) to BasePaginationOptions in packages/pagination/src/lib/types.ts
• Add chromeFocusDimsBody: boolean (default true)
• Add footnotePlacement: FootnotePlacement (default 'pageBottom')
• Add pageNumber: PageNumberConfig | null (default null)
• Add headerReferences: HeaderFooterReference[] and footerReferences: HeaderFooterReference[]

Task 3: Define Store State Shape

Create the Zustand store state interface.

• Define PageLayoutState interface in new file packages/pagination/src/lib/page-layout-state.ts covering all layout options plus activeChromeId: string | null for focus tracking
• Export PageLayoutActions interface for store actions: setMargins, setPageSize, setTitlePg, setPageNumber, setFootnotePlacement, setActiveChromeId, etc.

🤖 Prompt for AI agents

Extend the pagination type system in `packages/pagination/src/lib/types.ts` and
create a new state interface file. This phase establishes all data contracts
needed by subsequent phases.

**In `packages/pagination/src/lib/types.ts`:**
- Add `FootnotePlacement` union type: `'pageBottom' | 'beneathText' | 'sectEnd'
| 'docEnd'`
- Add `HeaderFooterReference` type with shape `{ id: string; type: 'default' |
'first' | 'even'; content: Descendant[] }`
- Add `PageNumberConfig` type with fields:
  - `region: 'header' | 'footer'`
  - `align: 'left' | 'center' | 'right'`
  - `format: 'decimal' | 'roman' | 'letter' | '1/N' | 'page-of-n'`
  - `startAt: number`
  - `hideOnFirst: boolean`
- Extend `BasePaginationOptions` with:
  - `titlePg: boolean` (default false)
  - `chromeFocusDimsBody: boolean` (default true)
  - `footnotePlacement: FootnotePlacement` (default `'pageBottom'`)
  - `pageNumber: PageNumberConfig | null` (default null)
  - `headerReferences: HeaderFooterReference[]`
  - `footerReferences: HeaderFooterReference[]`

**Create `packages/pagination/src/lib/page-layout-state.ts`:**
- Define `PageLayoutState` interface covering all layout options (margins,
pageSize, headerHeight, footerHeight, footnoteWell, titlePg,
chromeFocusDimsBody, footnotePlacement, pageNumber, headerReferences,
footerReferences) plus `activeChromeId: string | null`
- Export `PageLayoutActions` interface for store actions: `setMargins`,
`setPageSize`, `setTitlePg`, `setPageNumber`, `setFootnotePlacement`,
`setActiveChromeId`, and any other relevant setters

Phase 2: Page Layout Store Infrastructure

Implement the Zustand-based state management layer following existing store patterns in the codebase.

Task 1: Create pageLayoutStore

Implement the store using zustand-x patterns.

• Create packages/pagination/src/react/stores/page-layout-store.ts using createZustandStore pattern from ImagePreviewStore
• Initialize with default values matching current BasePaginationOptions defaults
• Add .extendActions() for all mutations (setMargins, setPageSize, setTitlePg, etc.)
• Add .extendSelectors() for computed values (resolved chrome for page index, etc.)

Task 2: Chrome Focus Context

Create React context for tracking active chrome editor.

• Create packages/pagination/src/react/contexts/chrome-focus-context.tsx
• Export ChromeFocusProvider that wraps children and provides activeChromeId + setActiveChromeId
• Export useChromeFocusContext hook for consuming components
• Wire onFocus/onBlur callbacks to update activeChromeId in store

Task 3: Store Persistence Layer

Wire store state to document metadata for persistence.

• Create packages/pagination/src/react/hooks/use-page-layout-persistence.ts
• Read initial state from editor.meta.pageLayout on mount
• Subscribe to store changes and write back to editor metadata
• Handle hydration of legacy documents (no pageLayout field → use defaults)

🤖 Prompt for AI agents

Implement the Zustand-based page layout store and associated React
context/persistence infrastructure. Follow the `ImagePreviewStore` pattern using
`createZustandStore` from `zustand-x`.

**Create `packages/pagination/src/react/stores/page-layout-store.ts`:**
- Use `createZustandStore` following the `ImagePreviewStore` pattern
- Initialize state with default values that match current
`BasePaginationOptions` defaults
- Use `.extendActions()` to add all mutation methods: `setMargins`,
`setPageSize`, `setTitlePg`, `setPageNumber`, `setFootnotePlacement`,
`setActiveChromeId`, `setChromeFocusDimsBody`, etc.
- Use `.extendSelectors()` for computed values such as resolved chrome reference
for a given page index

**Create `packages/pagination/src/react/contexts/chrome-focus-context.tsx`:**
- Export `ChromeFocusProvider` component providing `activeChromeId` and
`setActiveChromeId` via React context
- Export `useChromeFocusContext` hook
- Wire focus/blur events to update `activeChromeId` in the pageLayoutStore

**Create `packages/pagination/src/react/hooks/use-page-layout-persistence.ts`:**
- On mount, read initial state from `editor.meta.pageLayout` to hydrate the
store
- Subscribe to store changes and write back to `editor.meta.pageLayout`
- For legacy documents without a `pageLayout` field, fall back to default values

Phase 3: Chrome Sub-Editor Infrastructure

Build the multi-editor architecture for header/footer regions, enabling full plugin support in chrome areas.

Task 1: Create Chrome Editor Factory

Factory function to instantiate chrome editors with shared plugin configuration.

• Create packages/pagination/src/react/chrome-editor/create-chrome-editor.ts
• Accept parent editor's plugin list (minus pagination itself to avoid recursion)
• Apply single-line soft constraint via custom overrideByKey that visually clips overflow
• Return a configured PlateEditor instance with unique ID

Task 2: Chrome Editor Mount Component

React component that renders a chrome editor instance.

• Create packages/pagination/src/react/chrome-editor/chrome-editor-mount.tsx
• Mount <Plate> with the chrome editor instance
• Wire focus/blur to ChromeFocusContext to update activeChromeId
• Pass through relevant props (placeholder, className, etc.)

Task 3: Chrome Editor Registry

Manage lifecycle of chrome editor instances.

• Create packages/pagination/src/react/chrome-editor/chrome-editor-registry.ts
• Store Map<string, PlateEditor> keyed by reference ID
• Provide getOrCreateEditor(referenceId, config) for lazy instantiation
• Provide disposeEditor(referenceId) for cleanup

🤖 Prompt for AI agents

Build the multi-editor architecture for chrome (header/footer) regions. This
enables full Plate plugin support within chrome areas.

**Create
`packages/pagination/src/react/chrome-editor/create-chrome-editor.ts`:**
- Export a factory function that accepts the parent editor's plugin list
(excluding the pagination plugin to prevent recursion)
- Apply single-line soft constraint using `overrideByKey` to visually clip
overflow (do not hard-reject multi-block content)
- Return a configured `PlateEditor` instance with a unique ID

**Create
`packages/pagination/src/react/chrome-editor/chrome-editor-mount.tsx`:**
- Render a `<Plate>` component using the chrome editor instance
- On focus, call `setActiveChromeId` from `ChromeFocusContext` with the editor's
ID
- On blur, call `setActiveChromeId(null)` from `ChromeFocusContext`
- Accept and pass through relevant props: `placeholder`, `className`, etc.

**Create
`packages/pagination/src/react/chrome-editor/chrome-editor-registry.ts`:**
- Maintain a `Map<string, PlateEditor>` keyed by reference ID
- Export `getOrCreateEditor(referenceId, config)` for lazy instantiation of
editors
- Export `disposeEditor(referenceId)` for cleanup when an editor is no longer
needed

Phase 4: Body Opacity Dim UX

Implement the visual recession effect when chrome editors have focus—the novel piece unique to variant D.

Task 1: Dim Overlay Styling

CSS-based dim effect using pseudo-element approach.

• Create packages/pagination/src/react/styles/body-dim.css with [data-chrome-active="true"]::after pseudo-element rules
• Apply position: absolute; inset: 0; background: rgba(255,255,255,0.5); pointer-events: none; transition: opacity 200ms ease-out
• Add @media (prefers-reduced-motion: reduce) query to skip transition
• Add [data-chrome-dims-disabled="true"] selector to opt out

Task 2: Body Wrapper Integration

Wire the data attributes into the page overlay structure.

• Modify packages/pagination/src/react/page-overlay.tsx to wrap the body editor section in a div with data-chrome-active attribute bound to activeChromeId !== null
• Bind data-chrome-dims-disabled to store's chromeFocusDimsBody === false
• Import the CSS file for styles to take effect

🤖 Prompt for AI agents

Implement the visual body-dim effect using a CSS pseudo-element overlay
approach. This is the novel UX piece of variant D, ensuring cursor/selection
overlays inside the body editor are not inadvertently dimmed.

**Create `packages/pagination/src/react/styles/body-dim.css`:**
- Add `[data-chrome-active="true"]::after` pseudo-element rule with: `position:
absolute; inset: 0; background: rgba(255,255,255,0.5); pointer-events: none;
transition: opacity 200ms ease-out`
- Add `@media (prefers-reduced-motion: reduce)` to skip the transition
- Add `[data-chrome-dims-disabled="true"]` selector to opt out of the dim effect

**Modify `packages/pagination/src/react/page-overlay.tsx`:**
- Wrap the body editor section in a `div` with a `data-chrome-active` attribute
bound to `activeChromeId !== null` from the store
- Set `data-chrome-dims-disabled` to `true` when `store.chromeFocusDimsBody ===
false`
- Import `body-dim.css` so styles are applied

Phase 5: Chrome Shell and Page Number Components

Build the visible UI components for chrome regions and page numbers.

Task 1: Chrome Shell Component

Container component providing label, focus ring, and visual affordances for chrome regions.

• Create packages/pagination/src/react/components/chrome-shell.tsx
• Accept label prop ('Header', 'Footer', 'First Page Header', etc.)
• Render focus ring on :focus-within of contained editor
• Show label above region when focused
• Provide "exit" click target (clicking outside chrome region returns focus to body)

Task 2: Page Number Component

Non-editable React component for dynamic page number rendering.

• Create packages/pagination/src/react/components/page-number.tsx
• Read pageNumber config from store
• Accept pageIndex prop and compute display value based on format and startAt
• Render as contentEditable={false} span
• Handle hideOnFirst by returning null when pageIndex === 0 && hideOnFirst
• Implement format renderers: decimal (1,2,3), roman (i,ii,iii), letter (a,b,c), '1/N' (1/10), 'page-of-n' (Page 1 of 10)

🤖 Prompt for AI agents

Build the visible UI components for chrome regions and page number display.

**Create `packages/pagination/src/react/components/chrome-shell.tsx`:**
- Accept a `label` prop (e.g., `'Header'`, `'Footer'`, `'First Page Header'`)
- Render a focus ring on `:focus-within` of the contained editor
- Display the label above the region when the editor is focused
- Include an "exit" click target: clicking outside the chrome region returns
focus to the body editor

**Create `packages/pagination/src/react/components/page-number.tsx`:**
- Read `pageNumber` config from `pageLayoutStore`
- Accept a `pageIndex` prop; compute the display value using `format` and
`startAt` from config
- Render as a `contentEditable={false}` span
- Return `null` when `pageIndex === 0 && hideOnFirst === true`
- Implement all format renderers:
  - `decimal`: 1, 2, 3
  - `roman`: i, ii, iii
  - `letter`: a, b, c
  - `'1/N'`: e.g., 1/10
  - `'page-of-n'`: e.g., Page 1 of 10

Phase 6: PageFrame and PageOverlay Refactoring

Replace static text rendering with live sub-editors and integrate store-driven configuration.

Task 1: Refactor Chrome Region Rendering in PageFrame

Replace collectInlineText approach with chrome sub-editor mounts.

• Modify packages/pagination/src/react/page-frame.tsx header/footer band rendering
• Replace static text spans with <ChromeShell> containing <ChromeEditorMount>
• Resolve correct reference via headerReferences.find(r => r.type === ...) based on pageIndex and titlePg
• Render <PageNumber> component in configured region/position

Task 2: Title Page Chrome Resolution

Implement first-page-different logic using titlePg flag.

• Add resolveChrome(references, pageIndex, titlePg) utility function in packages/pagination/src/react/page-frame.tsx
• When pageIndex === 0 && titlePg === true, look for type: 'first' reference first, fall back to type: 'default'
• For all other pages, use type: 'default'
• Apply to both header and footer resolution

Task 3: Store-Driven Geometry in PageOverlay

Replace plugin options with store values for chrome heights and margins.

• Modify packages/pagination/src/react/page-overlay.tsx to read margins, headerHeight, footerHeight, footnoteWell from pageLayoutStore
• Update usePageLayout hook to consume store values instead of plugin options
• Ensure re-render when store values change

🤖 Prompt for AI agents

Refactor `PageFrame` and `PageOverlay` to use live chrome sub-editors and
store-driven geometry, replacing the old static text rendering approach.

**Modify `packages/pagination/src/react/page-frame.tsx`:**
- Replace `collectInlineText`-based static text spans in header/footer bands
with `<ChromeShell>` containing `<ChromeEditorMount>`
- Add a `resolveChrome(references, pageIndex, titlePg)` utility function:
- When `pageIndex === 0 && titlePg === true`: find `type: 'first'` reference,
fall back to `type: 'default'`
  - For all other pages: use `type: 'default'`
  - Apply to both header and footer resolution
- Use `headerReferences.find(r => r.type === ...)` based on resolved type for
each page
- Render `<PageNumber>` component in the configured region and position

**Modify `packages/pagination/src/react/page-overlay.tsx`:**
- Read `margins`, `headerHeight`, `footerHeight`, and `footnoteWell` from
`pageLayoutStore` instead of plugin options
- Update the `usePageLayout` hook to consume store values
- Ensure the component re-renders reactively when store values change

Phase 7: Page Setup Dialog

Create comprehensive dialog for all page layout settings, exposing full configuration surface to users.

Task 1: Create Page Setup Dialog Component

Build the main dialog component with all configuration sections.

• Create packages/pagination/src/react/components/page-setup-dialog.tsx
• Include sections: Margins (4 inputs + unit selector), Page Size (preset dropdown + custom dimensions), Chrome Heights (header/footer numeric inputs)
• Include Page Number section: region selector, alignment, format dropdown, startAt input, hideOnFirst checkbox
• Include First Page Different toggle (titlePg)
• Include Footnote Placement dropdown (4 modes, with toast on unimplemented selection)
• Include "Dim body when editing chrome" toggle (chromeFocusDimsBody)

Task 2: Wire Dialog to Transforms

Connect dialog controls to existing transform API for backward compatibility.

• Use editor.tf.pagination.setMargins(), setPageSize(), etc. as the mutation layer
• Add new transforms to packages/pagination/src/lib/base-pagination-plugin.ts: setPageNumber, setTitlePg, setFootnotePlacement, setChromeFocusDimsBody
• These transforms proxy through to the pageLayoutStore

Task 3: Add Dialog Trigger to Toolbar/Menu

Integrate dialog into the editor UI surface.

• Create packages/pagination/src/react/components/page-setup-toolbar-button.tsx
• Opens PageSetupDialog on click
• Add to registry exports for downstream consumption

🤖 Prompt for AI agents

Build the Page Setup dialog component and wire it to the transform API and
toolbar.

**Create `packages/pagination/src/react/components/page-setup-dialog.tsx`:**
- Build a dialog with the following sections:
  - **Margins**: 4 numeric inputs (top, right, bottom, left) + unit selector
  - **Page Size**: preset dropdown + custom width/height dimension inputs
  - **Chrome Heights**: header and footer numeric inputs
- **Page Number**: region selector (`header`/`footer`), alignment, format
dropdown, `startAt` input, `hideOnFirst` checkbox
  - **First Page Different**: toggle for `titlePg`
- **Footnote Placement**: dropdown for 4 modes; show a UI toast when an
unimplemented mode (`beneathText` or `sectEnd`) is selected
  - **Dim body when editing chrome**: toggle for `chromeFocusDimsBody`

**Modify `packages/pagination/src/lib/base-pagination-plugin.ts`:**
- Add new transforms: `setPageNumber`, `setTitlePg`, `setFootnotePlacement`,
`setChromeFocusDimsBody`
- These transforms proxy through to the `pageLayoutStore`
- Dialog controls must use `editor.tf.pagination.*` methods (e.g.,
`setMargins()`, `setPageSize()`) as the mutation layer

**Create
`packages/pagination/src/react/components/page-setup-toolbar-button.tsx`:**
- Render a toolbar button that opens `PageSetupDialog` on click
- Export for downstream registry consumption

Phase 8: Footnote Allocation Enhancement

Widen the footnote placement system to support four modes with graceful degradation for unimplemented modes.

Task 1: Extend Allocation Algorithm

Modify allocate-footnotes to support multiple placement modes.

• Update packages/pagination/src/lib/allocate-footnotes.ts to accept placement: FootnotePlacement parameter
• Implement pageBottom mode (current behavior, footnotes on citing page)
• Implement docEnd mode (collect all footnotes, append to final page)
• For beneathText and sectEnd: log warning, fall back to pageBottom

Task 2: Wire Placement to Pagination Pipeline

Pass placement setting through the pagination flow.

• Update packages/pagination/src/react/internal/use-page-layout.ts to read footnotePlacement from store
• Pass placement to allocateFootnotes call
• Ensure proper re-pagination when placement changes

🤖 Prompt for AI agents

Extend the footnote allocation algorithm to support four placement modes and
wire the setting through the pagination pipeline.

**Modify `packages/pagination/src/lib/allocate-footnotes.ts`:**
- Add a `placement: FootnotePlacement` parameter to the allocation function
- Implement `'pageBottom'` mode: current behavior—place footnotes on the citing
page
- Implement `'docEnd'` mode: collect all footnotes and append to the final page
- For `'beneathText'` and `'sectEnd'`: log a console warning and fall back to
`'pageBottom'`

**Modify `packages/pagination/src/react/internal/use-page-layout.ts`:**
- Read `footnotePlacement` from `pageLayoutStore`
- Pass the resolved `placement` value to the `allocateFootnotes` call
- Ensure the pagination pipeline re-runs when `footnotePlacement` changes in the
store

Phase 9: Auto-Migration

Implement automatic extraction of legacy body-level header/footer nodes into the chrome reference registry.

Task 1: Migration Normalizer

Create normalizer that runs on initial value to migrate legacy documents.

• Add migration logic to packages/pagination/src/lib/base-pagination-plugin.ts in normalizeInitialValue
• Scan editor.children for nodes with type === HEADER_KEY or type === FOOTER_KEY
• Extract content into new HeaderFooterReference entries with type: 'default'
• Remove original nodes from editor.children
• Write references to pageLayoutStore/metadata
• Make idempotent: skip if headerReferences already populated

Task 2: Migration Safety

Ensure migration is safe for collaborative editing scenarios.

• Migration runs in normalizeInitialValue (before first render, synchronous)
• Each client migrates independently but deterministically (same input → same output)
• Add _migrated: true marker to document metadata after migration
• Skip migration if marker present

🤖 Prompt for AI agents

Implement auto-migration of legacy body-level header/footer nodes into the
chrome reference registry, with safety guards for collaborative editing.

**Modify `packages/pagination/src/lib/base-pagination-plugin.ts` —
`normalizeInitialValue`:**
- **Skip** migration if `_migrated: true` is present in document metadata or if
`headerReferences` is already populated (idempotency)
- Scan `editor.children` for nodes with `type === HEADER_KEY` or `type ===
FOOTER_KEY`
- Extract their content into new `HeaderFooterReference` entries with `type:
'default'`
- Remove the original nodes from `editor.children`
- Write the extracted references to `pageLayoutStore` and/or editor metadata
- After migration, set `_migrated: true` in document metadata

**Collaborative safety notes:**
- Migration runs synchronously in `normalizeInitialValue` (before first render)
- Each client migrates independently but deterministically: same input always
produces same output
- The `_migrated` marker prevents re-running migration on subsequent mounts

Phase 10: DOCX Import/Export Integration

Map DOCX header/footer/page-number semantics to the new store structure.

Task 1: Import Mapping

Extend DOCX import to populate pageLayoutStore fields.

• Modify packages/docx-io/src/lib/importDocx.ts to extract sectPr fields
• Map sectPr.titlePg → store titlePg
• Map headerReference[type="first"] → headerReferences entry with type: 'first'
• Map pgNumType@fmt → pageNumber.format
• Map pgNumType@start → pageNumber.startAt
• Map footnotePr/pos@val → footnotePlacement

Task 2: Export Mapping

Extend DOCX export to serialize store state to OOXML structures.

• Modify packages/docx-io/src/lib/internal/document.template.ts to emit sectPr from store
• Generate titlePg element when store.titlePg === true
• Generate headerReference elements from headerReferences array with correct type attribute
• Generate pgNumType element from pageNumber config
• Generate footnotePr/pos from footnotePlacement

🤖 Prompt for AI agents

Integrate the new store fields with DOCX import and export pipelines for full
round-trip fidelity.

**Modify `packages/docx-io/src/lib/importDocx.ts`:**
- Extract `sectPr` from the parsed DOCX
- Map the following to store fields:
  - `sectPr.titlePg` → store `titlePg`
- `headerReference[type="first"]` → `headerReferences` entry with `type:
'first'`
  - `pgNumType@fmt` → `pageNumber.format`
  - `pgNumType@start` → `pageNumber.startAt`
  - `footnotePr/pos@val` → `footnotePlacement`

**Modify `packages/docx-io/src/lib/internal/document.template.ts`:**
- Read store state and emit `sectPr` with the following:
  - `titlePg` element when `store.titlePg === true`
- `headerReference` elements from `headerReferences` array, each with the
correct `type` attribute
  - `pgNumType` element from `pageNumber` config
  - `footnotePr/pos` element from `footnotePlacement`

Phase 11: Registry Integration and Dev Verification

Wire everything into the apps/www registry and verify in dev environment.

Task 1: Create Pagination Kit for Registry

Add pagination-kit.tsx to the www registry.

• Create apps/www/src/registry/components/editor/plugins/pagination-kit.tsx
• Configure PaginationPlugin with PageOverlay render
• Export PaginationKit array for consumption by EditorKit
• Register Page Setup dialog components

Task 2: Update Registry Manifests

Register new components in registry system.

• Add pagination entries to apps/www/src/registry/registry-kits.ts
• Add UI components (PageSetupDialog, ChromeShell, PageNumber) to apps/www/src/registry/registry-ui.ts
• Ensure proper dependencies declared

Task 3: Dev Browser Verification

Create dev page for testing all features.

• Add pagination demo to apps/www/src/app/dev/
• Verify: typing in header works without visual artifacts
• Verify: clicking chrome region focuses it AND dims body with 200ms transition
• Verify: first page uses different header when titlePg enabled
• Verify: page number respects format/position/startAt/hideOnFirst
• Verify: AI/comments/suggestions render in chrome regions (live sub-editors)
• Verify: Page Setup dialog edits all settings correctly

🤖 Prompt for AI agents

Wire all new pagination components into the apps/www registry and set up a dev
verification page.

**Create `apps/www/src/registry/components/editor/plugins/pagination-kit.tsx`:**
- Configure `PaginationPlugin` with the `PageOverlay` render
- Export `PaginationKit` array for consumption by `EditorKit`
- Register `PageSetupDialog` and related components

**Update registry manifests:**
- Add pagination entries to `apps/www/src/registry/registry-kits.ts`
- Add `PageSetupDialog`, `ChromeShell`, and `PageNumber` UI components to
`apps/www/src/registry/registry-ui.ts`
- Declare proper dependencies for each entry

**Create dev verification page at `apps/www/src/app/dev/`:**
- Add a pagination demo page that enables manual verification of:
  - Typing in header without visual artifacts
  - Clicking chrome region focuses it and dims body with 200ms transition
  - First page uses different header when `titlePg` is enabled
  - Page number respects format, position, `startAt`, and `hideOnFirst`
  - AI/comments/suggestions render in chrome regions as live sub-editors
  - Page Setup dialog correctly edits all settings

Research

The pagination package (packages/pagination/src/) implements a render-time overlay approach where pages are derived at render time without mutating the Slate document. Core types live in lib/types.ts with BasePaginationOptions defining margins, pageSize, headerHeight, footerHeight, and footnoteWell. The PageOverlay component (in react/page-overlay.tsx) renders scaled PageFrame thumbnails in a side panel. Chrome regions (header/footer/footnote-well) currently render as simple divs with extracted text via collectInlineText. The paginate.ts algorithm does bin-packing layout, and allocate-footnotes.ts assigns footnotes per-page. No margins-dialog, no multi-editor chrome, no pageLayoutStore, and no footnote placement modes currently exist—these must be built from scratch. Zustand stores in the codebase follow the createZustandStore pattern from zustand-x (see ImagePreviewStore as reference).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend the pagination type system in `packages/pagination/src/lib/types.ts` and
create a new state interface file. This phase establishes all data contracts
needed by subsequent phases.

**In `packages/pagination/src/lib/types.ts`:**
- Add `FootnotePlacement` union type: `'pageBottom' | 'beneathText' | 'sectEnd'
| 'docEnd'`
- Add `HeaderFooterReference` type with shape `{ id: string; type: 'default' |
'first' | 'even'; content: Descendant[] }`
- Add `PageNumberConfig` type with fields:
  - `region: 'header' | 'footer'`
  - `align: 'left' | 'center' | 'right'`
  - `format: 'decimal' | 'roman' | 'letter' | '1/N' | 'page-of-n'`
  - `startAt: number`
  - `hideOnFirst: boolean`
- Extend `BasePaginationOptions` with:
  - `titlePg: boolean` (default false)
  - `chromeFocusDimsBody: boolean` (default true)
  - `footnotePlacement: FootnotePlacement` (default `'pageBottom'`)
  - `pageNumber: PageNumberConfig | null` (default null)
  - `headerReferences: HeaderFooterReference[]`
  - `footerReferences: HeaderFooterReference[]`

**Create `packages/pagination/src/lib/page-layout-state.ts`:**
- Define `PageLayoutState` interface covering all layout options (margins,
pageSize, headerHeight, footerHeight, footnoteWell, titlePg,
chromeFocusDimsBody, footnotePlacement, pageNumber, headerReferences,
footerReferences) plus `activeChromeId: string | null`
- Export `PageLayoutActions` interface for store actions: `setMargins`,
`setPageSize`, `setTitlePg`, `setPageNumber`, `setFootnotePlacement`,
`setActiveChromeId`, and any other relevant setters
===============================================================================

Task: 2

Implement the Zustand-based page layout store and associated React
context/persistence infrastructure. Follow the `ImagePreviewStore` pattern using
`createZustandStore` from `zustand-x`.

**Create `packages/pagination/src/react/stores/page-layout-store.ts`:**
- Use `createZustandStore` following the `ImagePreviewStore` pattern
- Initialize state with default values that match current
`BasePaginationOptions` defaults
- Use `.extendActions()` to add all mutation methods: `setMargins`,
`setPageSize`, `setTitlePg`, `setPageNumber`, `setFootnotePlacement`,
`setActiveChromeId`, `setChromeFocusDimsBody`, etc.
- Use `.extendSelectors()` for computed values such as resolved chrome reference
for a given page index

**Create `packages/pagination/src/react/contexts/chrome-focus-context.tsx`:**
- Export `ChromeFocusProvider` component providing `activeChromeId` and
`setActiveChromeId` via React context
- Export `useChromeFocusContext` hook
- Wire focus/blur events to update `activeChromeId` in the pageLayoutStore

**Create `packages/pagination/src/react/hooks/use-page-layout-persistence.ts`:**
- On mount, read initial state from `editor.meta.pageLayout` to hydrate the
store
- Subscribe to store changes and write back to `editor.meta.pageLayout`
- For legacy documents without a `pageLayout` field, fall back to default values
===============================================================================

Task: 3

Build the multi-editor architecture for chrome (header/footer) regions. This
enables full Plate plugin support within chrome areas.

**Create
`packages/pagination/src/react/chrome-editor/create-chrome-editor.ts`:**
- Export a factory function that accepts the parent editor's plugin list
(excluding the pagination plugin to prevent recursion)
- Apply single-line soft constraint using `overrideByKey` to visually clip
overflow (do not hard-reject multi-block content)
- Return a configured `PlateEditor` instance with a unique ID

**Create
`packages/pagination/src/react/chrome-editor/chrome-editor-mount.tsx`:**
- Render a `<Plate>` component using the chrome editor instance
- On focus, call `setActiveChromeId` from `ChromeFocusContext` with the editor's
ID
- On blur, call `setActiveChromeId(null)` from `ChromeFocusContext`
- Accept and pass through relevant props: `placeholder`, `className`, etc.

**Create
`packages/pagination/src/react/chrome-editor/chrome-editor-registry.ts`:**
- Maintain a `Map<string, PlateEditor>` keyed by reference ID
- Export `getOrCreateEditor(referenceId, config)` for lazy instantiation of
editors
- Export `disposeEditor(referenceId)` for cleanup when an editor is no longer
needed
===============================================================================

Task: 4

Implement the visual body-dim effect using a CSS pseudo-element overlay
approach. This is the novel UX piece of variant D, ensuring cursor/selection
overlays inside the body editor are not inadvertently dimmed.

**Create `packages/pagination/src/react/styles/body-dim.css`:**
- Add `[data-chrome-active="true"]::after` pseudo-element rule with: `position:
absolute; inset: 0; background: rgba(255,255,255,0.5); pointer-events: none;
transition: opacity 200ms ease-out`
- Add `@media (prefers-reduced-motion: reduce)` to skip the transition
- Add `[data-chrome-dims-disabled="true"]` selector to opt out of the dim effect

**Modify `packages/pagination/src/react/page-overlay.tsx`:**
- Wrap the body editor section in a `div` with a `data-chrome-active` attribute
bound to `activeChromeId !== null` from the store
- Set `data-chrome-dims-disabled` to `true` when `store.chromeFocusDimsBody ===
false`
- Import `body-dim.css` so styles are applied
===============================================================================

Task: 5

Build the visible UI components for chrome regions and page number display.

**Create `packages/pagination/src/react/components/chrome-shell.tsx`:**
- Accept a `label` prop (e.g., `'Header'`, `'Footer'`, `'First Page Header'`)
- Render a focus ring on `:focus-within` of the contained editor
- Display the label above the region when the editor is focused
- Include an "exit" click target: clicking outside the chrome region returns
focus to the body editor

**Create `packages/pagination/src/react/components/page-number.tsx`:**
- Read `pageNumber` config from `pageLayoutStore`
- Accept a `pageIndex` prop; compute the display value using `format` and
`startAt` from config
- Render as a `contentEditable={false}` span
- Return `null` when `pageIndex === 0 && hideOnFirst === true`
- Implement all format renderers:
  - `decimal`: 1, 2, 3
  - `roman`: i, ii, iii
  - `letter`: a, b, c
  - `'1/N'`: e.g., 1/10
  - `'page-of-n'`: e.g., Page 1 of 10
===============================================================================

Task: 6

Refactor `PageFrame` and `PageOverlay` to use live chrome sub-editors and
store-driven geometry, replacing the old static text rendering approach.

**Modify `packages/pagination/src/react/page-frame.tsx`:**
- Replace `collectInlineText`-based static text spans in header/footer bands
with `<ChromeShell>` containing `<ChromeEditorMount>`
- Add a `resolveChrome(references, pageIndex, titlePg)` utility function:
- When `pageIndex === 0 && titlePg === true`: find `type: 'first'` reference,
fall back to `type: 'default'`
  - For all other pages: use `type: 'default'`
  - Apply to both header and footer resolution
- Use `headerReferences.find(r => r.type === ...)` based on resolved type for
each page
- Render `<PageNumber>` component in the configured region and position

**Modify `packages/pagination/src/react/page-overlay.tsx`:**
- Read `margins`, `headerHeight`, `footerHeight`, and `footnoteWell` from
`pageLayoutStore` instead of plugin options
- Update the `usePageLayout` hook to consume store values
- Ensure the component re-renders reactively when store values change
===============================================================================

Task: 7

Build the Page Setup dialog component and wire it to the transform API and
toolbar.

**Create `packages/pagination/src/react/components/page-setup-dialog.tsx`:**
- Build a dialog with the following sections:
  - **Margins**: 4 numeric inputs (top, right, bottom, left) + unit selector
  - **Page Size**: preset dropdown + custom width/height dimension inputs
  - **Chrome Heights**: header and footer numeric inputs
- **Page Number**: region selector (`header`/`footer`), alignment, format
dropdown, `startAt` input, `hideOnFirst` checkbox
  - **First Page Different**: toggle for `titlePg`
- **Footnote Placement**: dropdown for 4 modes; show a UI toast when an
unimplemented mode (`beneathText` or `sectEnd`) is selected
  - **Dim body when editing chrome**: toggle for `chromeFocusDimsBody`

**Modify `packages/pagination/src/lib/base-pagination-plugin.ts`:**
- Add new transforms: `setPageNumber`, `setTitlePg`, `setFootnotePlacement`,
`setChromeFocusDimsBody`
- These transforms proxy through to the `pageLayoutStore`
- Dialog controls must use `editor.tf.pagination.*` methods (e.g.,
`setMargins()`, `setPageSize()`) as the mutation layer

**Create
`packages/pagination/src/react/components/page-setup-toolbar-button.tsx`:**
- Render a toolbar button that opens `PageSetupDialog` on click
- Export for downstream registry consumption
===============================================================================

Task: 8

Extend the footnote allocation algorithm to support four placement modes and
wire the setting through the pagination pipeline.

**Modify `packages/pagination/src/lib/allocate-footnotes.ts`:**
- Add a `placement: FootnotePlacement` parameter to the allocation function
- Implement `'pageBottom'` mode: current behavior—place footnotes on the citing
page
- Implement `'docEnd'` mode: collect all footnotes and append to the final page
- For `'beneathText'` and `'sectEnd'`: log a console warning and fall back to
`'pageBottom'`

**Modify `packages/pagination/src/react/internal/use-page-layout.ts`:**
- Read `footnotePlacement` from `pageLayoutStore`
- Pass the resolved `placement` value to the `allocateFootnotes` call
- Ensure the pagination pipeline re-runs when `footnotePlacement` changes in the
store
===============================================================================

Task: 9

Implement auto-migration of legacy body-level header/footer nodes into the
chrome reference registry, with safety guards for collaborative editing.

**Modify `packages/pagination/src/lib/base-pagination-plugin.ts` —
`normalizeInitialValue`:**
- **Skip** migration if `_migrated: true` is present in document metadata or if
`headerReferences` is already populated (idempotency)
- Scan `editor.children` for nodes with `type === HEADER_KEY` or `type ===
FOOTER_KEY`
- Extract their content into new `HeaderFooterReference` entries with `type:
'default'`
- Remove the original nodes from `editor.children`
- Write the extracted references to `pageLayoutStore` and/or editor metadata
- After migration, set `_migrated: true` in document metadata

**Collaborative safety notes:**
- Migration runs synchronously in `normalizeInitialValue` (before first render)
- Each client migrates independently but deterministically: same input always
produces same output
- The `_migrated` marker prevents re-running migration on subsequent mounts
===============================================================================

Task: 10

Integrate the new store fields with DOCX import and export pipelines for full
round-trip fidelity.

**Modify `packages/docx-io/src/lib/importDocx.ts`:**
- Extract `sectPr` from the parsed DOCX
- Map the following to store fields:
  - `sectPr.titlePg` → store `titlePg`
- `headerReference[type="first"]` → `headerReferences` entry with `type:
'first'`
  - `pgNumType@fmt` → `pageNumber.format`
  - `pgNumType@start` → `pageNumber.startAt`
  - `footnotePr/pos@val` → `footnotePlacement`

**Modify `packages/docx-io/src/lib/internal/document.template.ts`:**
- Read store state and emit `sectPr` with the following:
  - `titlePg` element when `store.titlePg === true`
- `headerReference` elements from `headerReferences` array, each with the
correct `type` attribute
  - `pgNumType` element from `pageNumber` config
  - `footnotePr/pos` element from `footnotePlacement`
===============================================================================

Task: 11

Wire all new pagination components into the apps/www registry and set up a dev
verification page.

**Create `apps/www/src/registry/components/editor/plugins/pagination-kit.tsx`:**
- Configure `PaginationPlugin` with the `PageOverlay` render
- Export `PaginationKit` array for consumption by `EditorKit`
- Register `PageSetupDialog` and related components

**Update registry manifests:**
- Add pagination entries to `apps/www/src/registry/registry-kits.ts`
- Add `PageSetupDialog`, `ChromeShell`, and `PageNumber` UI components to
`apps/www/src/registry/registry-ui.ts`
- Declare proper dependencies for each entry

**Create dev verification page at `apps/www/src/app/dev/`:**
- Add a pagination demo page that enables manual verification of:
  - Typing in header without visual artifacts
  - Clicking chrome region focuses it and dims body with 200ms transition
  - First page uses different header when `titlePg` is enabled
  - Page number respects format, position, `startAt`, and `hideOnFirst`
  - AI/comments/suggestions render in chrome regions as live sub-editors
  - Page Setup dialog correctly edits all settings

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