eigenpal
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 0 deletions b/‎.gitignore‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 32 additions & 27 deletions b/‎CLAUDE.md‎
Lines changed: 32 additions & 27 deletions
diff --git a/‎docs/api/docx-editor-react/index.api.md‎
Lines changed: 1 addition & 0 deletions b/‎docs/api/docx-editor-react/index.api.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/api/docx-editor-vue/composables.api.md‎
Lines changed: 5 additions & 0 deletions b/‎docs/api/docx-editor-vue/composables.api.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎e2e/tests/hf-click-and-type.spec.ts‎
Lines changed: 40 additions & 0 deletions b/‎e2e/tests/hf-click-and-type.spec.ts‎
Lines changed: 40 additions & 0 deletions
diff --git a/‎e2e/tests/hf-field-insert.spec.ts‎
Lines changed: 117 additions & 0 deletions b/‎e2e/tests/hf-field-insert.spec.ts‎
Lines changed: 117 additions & 0 deletions
@@ -78,3 +78,5 @@ packages/*/temp/
 # Not committed — consumer (e.g. docs-editor-page) clones the repo and
 # runs the script itself. See CLAUDE.md → Docs JSON.
 docs/json/
+examples/vite/public/DC_Template_Descricao_Cargo_Controlado_Enterprise.docx
+examples/vue/public/DC_Template_Descricao_Cargo_Controlado_Enterprise.docx
@@ -43,14 +43,16 @@ Empty-doc specs (`formatting`, `text-editing`) use `editor.gotoEmpty()`. Demo-as
 
 **Two renderers. Know which one owns your bug.**
 
-- **HIDDEN ProseMirror** (`left: -9999px`) — editing state, undo/redo, keyboard. `components/DocxEditor/OffscreenEditorHost.tsx`.
+- **HIDDEN ProseMirror** (`left: -9999px`) — editing state, undo/redo, keyboard. `components/DocxEditor/OffscreenEditorHost.tsx` (body) + `HiddenHeaderFooterPMs.tsx` (one EditorView per HF `rId`).
 - **VISIBLE pages** — what user sees. Static DOM rebuilt from PM state. **NOT `toDOM`** — `src/layout-painter/paintPage.ts`. Fixing `toDOM` for a visual bug → user sees nothing.
 
 Data flow: DOCX → `unzip` → `parser` → `Document` → `toProseDoc` → PM → painter → pages. Save: PM → `fromProseDoc` → `Document` → `serializer` → `rezip`.
 
-Click flow: `usePagesPointer.handlePagesMouseDown` → `getPositionFromMouse` → PM setSelection → `PagedEditor.handleTransaction` → painter re-render.
+Click flow: `usePagesPointer.handlePagesMouseDown` → `getPositionFromMouse` (body) or `resolveDomPosition` scoped to `.layout-page-header`/`.layout-page-footer` (HF) → PM setSelection → `PagedEditor.handleTransaction` → painter re-render.
 
-Vue host: `useDocxEditor()` in `packages/vue/src/composables/useDocxEditor.ts`. Dual-rendering rule applies to Vue too.
+Header/footer editing follows the same model as the body: the persistent hidden HF PM is the sole editor; the painter is the sole visible renderer in both edit and non-edit modes. The `InlineHeaderFooterEditor` overlay is UI chrome only (separator bar, options menu, save-on-close) — it does NOT mount its own EditorView. There is no `.hf-editor-pm` CSS — those workarounds existed to make PM's `toDOM` tables match the painter's flex layout and are gone now that the painter is the sole renderer. See `openspec/changes/unify-hf-editing/` for the design.
+
+Vue host: `useDocxEditor()` in `packages/vue/src/composables/useDocxEditor.ts`. Dual-rendering rule applies to Vue too — the composable mounts the same per-`rId` persistent HF EditorView pattern (via `syncHfPMs` / `getHfPmView` / `setHfTransactionListener`) and routes HF rendering through `convertHeaderFooterPmDocToContent` in lockstep with React.
 
 ### React/Vue parity
 
@@ -78,37 +80,40 @@ Stable dataset attrs on painted DOM (CSS, queries, selection map depend on these
 
 - `data-block-id` — block index
 - `data-from-line`/`data-to-line` — measured line range
-- `data-doc-from`/`data-doc-to` — PM positions for selection mapping
+- `data-doc-from`/`data-doc-to` — PM positions for selection mapping (body AND HF — different PM docs, scope queries with `.layout-page-content` for body / `.layout-page-header|footer` for HF; see `collectBodySpans.ts` for the pattern)
 - `data-comment-id` — comment-range spans
 - `data-change-author`/`data-change-date`/`data-revision-id` — tracked changes
 - `data-continues-from-prev`/`data-continues-on-next` — split paragraphs
 - `data-flex-line` — flex-promoted lines (image-aligned, right-tab); `paintParagraphFragment` suppresses `text-indent` on these (would apply per-flex-item)
 
 ### Key file map
 
-| Debugging                   | File                                                        |
-| --------------------------- | ----------------------------------------------------------- |
-| Text/paragraph rendering    | `layout-painter/renderParagraph.ts`                         |
-| Image rendering             | `layout-painter/renderImage.ts`                             |
-| Table rendering             | `layout-painter/renderTable.ts`                             |
-| Page composition            | `layout-painter/paintPage.ts`                              |
-| Formatting commands         | `prosemirror/extensions/marks/`, `nodes/`                   |
-| Keyboard shortcuts          | `prosemirror/extensions/features/BaseKeymapExtension.ts`    |
-| Toolbar ↔ selection         | `prosemirror/plugins/selectionTracker.ts`                   |
-| DOCX XML parsers            | `docx/paragraphParser.ts`, `docx/tableParser.ts`            |
-| Document → PM               | `prosemirror/conversion/toProseDoc.ts`                      |
-| Click → PM position         | `components/DocxEditor/hooks/usePagesPointer.ts`            |
-| Selection rects / caret     | `components/DocxEditor/hooks/useSelectionOverlay.ts`        |
-| Layout pipeline             | `components/DocxEditor/hooks/useLayoutPipeline.ts`          |
-| Scroll API                  | `components/DocxEditor/hooks/usePagedScrollApi.ts`          |
-| Image resize/drag           | `components/DocxEditor/hooks/useImageInteractions.ts`       |
-| Font/HF reflow triggers     | `components/DocxEditor/hooks/useLayoutTriggers.ts`          |
-| Table resize                | `components/DocxEditor/hooks/useTableResizeState.ts`        |
-| Measure-block cache         | `components/DocxEditor/internals/measureBlock.ts`           |
-| Sidebar comment Y positions | `components/DocxEditor/internals/sidebarAnchorPositions.ts` |
-| PM position → DOM           | `components/DocxEditor/internals/pmAnchors.ts`              |
-| Main toolbar                | `components/Toolbar.tsx`                                    |
-| Editor CSS                  | `prosemirror/editor.css`                                    |
+| Debugging                   | File                                                            |
+| --------------------------- | --------------------------------------------------------------- |
+| Text/paragraph rendering    | `layout-painter/renderParagraph.ts`                             |
+| Image rendering             | `layout-painter/renderImage.ts`                                 |
+| Table rendering             | `layout-painter/renderTable.ts`                                 |
+| Page composition            | `layout-painter/paintPage.ts`                                  |
+| Formatting commands         | `prosemirror/extensions/marks/`, `nodes/`                       |
+| Keyboard shortcuts          | `prosemirror/extensions/features/BaseKeymapExtension.ts`        |
+| Toolbar ↔ selection         | `prosemirror/plugins/selectionTracker.ts`                       |
+| DOCX XML parsers            | `docx/paragraphParser.ts`, `docx/tableParser.ts`                |
+| Document → PM               | `prosemirror/conversion/toProseDoc.ts`                          |
+| Click → PM position         | `components/DocxEditor/hooks/usePagesPointer.ts`                |
+| Selection rects / caret     | `components/DocxEditor/hooks/useSelectionOverlay.ts`            |
+| HF persistent PMs           | `components/DocxEditor/HiddenHeaderFooterPMs.tsx`               |
+| HF caret in painter         | `components/DocxEditor/DocxEditorPagedArea.tsx` (`hfCaretRect`) |
+| HF inline chrome            | `components/InlineHeaderFooterEditor.tsx`                       |
+| Layout pipeline             | `components/DocxEditor/hooks/useLayoutPipeline.ts`              |
+| Scroll API                  | `components/DocxEditor/hooks/usePagedScrollApi.ts`              |
+| Image resize/drag           | `components/DocxEditor/hooks/useImageInteractions.ts`           |
+| Font/HF reflow triggers     | `components/DocxEditor/hooks/useLayoutTriggers.ts`              |
+| Table resize                | `components/DocxEditor/hooks/useTableResizeState.ts`            |
+| Measure-block cache         | `components/DocxEditor/internals/measureBlock.ts`               |
+| Sidebar comment Y positions | `components/DocxEditor/internals/sidebarAnchorPositions.ts`     |
+| PM position → DOM           | `components/DocxEditor/internals/pmAnchors.ts`                  |
+| Main toolbar                | `components/Toolbar.tsx`                                        |
+| Editor CSS                  | `prosemirror/editor.css`                                        |
 
 ### Extensions
 
 
@@ -16,6 +16,7 @@ import { EditorHandle } from '@eigenpal/docx-editor-core';
 import { EditorState } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 import { FontOption } from '@eigenpal/docx-editor-core/utils/fontOptions';
+import { HeaderFooter } from '@eigenpal/docx-editor-core/types/document';
 import { Layout } from '@eigenpal/docx-editor-core/layout-engine';
 import * as prosemirror_state from 'prosemirror-state';
 import * as prosemirror_view from 'prosemirror-view';
 
@@ -24,6 +24,7 @@ import { formatStorageSize } from '@eigenpal/docx-editor-core';
 import { getAutoSaveStatusLabel } from '@eigenpal/docx-editor-core';
 import { getAutoSaveStorageSize } from '@eigenpal/docx-editor-core';
 import { getSelectionRuns } from '@eigenpal/docx-editor-core';
+import { HeaderFooter } from '@eigenpal/docx-editor-core/types/document';
 import { HighlightRect } from '@eigenpal/docx-editor-core/utils';
 import { isAutoSaveSupported } from '@eigenpal/docx-editor-core';
 import { Layout } from '@eigenpal/docx-editor-core/layout-engine/types';
@@ -251,13 +252,17 @@ export interface UseDocxEditorReturn {
     focus: () => void;
     getCommands: () => CommandMap;
     getDocument: () => Document_2 | null;
+    getHfPmView: (hf: HeaderFooter) => EditorView | null;
     isReady: Ref<boolean>;
     layout: ShallowRef<Layout | null>;
     loadBuffer: (buffer: ArrayBuffer | Uint8Array | Blob | File) => Promise<void>;
     loadDocument: (doc: Document_2) => void;
     parseError: Ref<string | null>;
     reLayout: () => void;
     save: () => Promise<Blob | null>;
+    setDocument: (doc: Document_2) => void;
+    setHfTransactionListener: (cb: ((rId: string, view: EditorView, docChanged: boolean) => void) | null) => void;
+    syncHfPMs: () => void;
 }
 
 // @public (undocumented)
 
@@ -0,0 +1,40 @@
+import { test, expect } from '@playwright/test';
+import { EditorPage } from '../helpers/editor-page';
+
+// Smoke test for the user-reported #468 regression: double-click the header,
+// then a single click inside a cell should place the cursor there, and
+// keystrokes should land in the header (not the body).
+test('HF click → place cursor → type lands in header', async ({ page }) => {
+  const editor = new EditorPage(page);
+  await editor.goto();
+  await editor.waitForReady();
+
+  await page
+    .locator('input[type="file"][accept=".docx"]')
+    .setInputFiles('e2e/fixtures/header-with-table.docx');
+  await page.waitForSelector('.paged-editor__pages');
+  await page.waitForSelector('[data-page-number]');
+  await expect(page.locator('.layout-page-header [data-from-row]')).toHaveCount(1, {
+    timeout: 15000,
+  });
+
+  // Double-click the header to engage edit mode.
+  const header = page.locator('.layout-page-header').first();
+  await header.dblclick();
+  await expect(page.locator('.hf-inline-editor')).toHaveCount(1);
+
+  // Find a painted span inside a table cell so we're not clicking on
+  // the separator chrome bar at the top of the overlay.
+  const span = page.locator('.layout-page-header .layout-table-cell span[data-doc-from]').first();
+  await span.click();
+
+  // Now type a marker string. It must land in the header.
+  await page.keyboard.type('ZZZMARK');
+
+  const headerText = await page.locator('.layout-page-header').first().textContent();
+  expect(headerText).toContain('ZZZMARK');
+
+  // And the body must NOT contain the marker.
+  const bodyText = await page.locator('.layout-page-content').first().textContent();
+  expect(bodyText).not.toContain('ZZZMARK');
+});
@@ -0,0 +1,117 @@
+import { test, expect } from '@playwright/test';
+import { EditorPage } from '../helpers/editor-page';
+
+test('HF: inserting PAGE field updates header immediately (no space keystroke needed)', async ({
+  page,
+}) => {
+  const editor = new EditorPage(page);
+  await editor.goto();
+  await editor.waitForReady();
+
+  await page
+    .locator('input[type="file"][accept=".docx"]')
+    .setInputFiles('e2e/fixtures/header-with-table.docx');
+  await page.waitForSelector('.paged-editor__pages');
+  await page.waitForSelector('[data-page-number]');
+  await expect(page.locator('.layout-page-header [data-from-row]')).toHaveCount(1, {
+    timeout: 15000,
+  });
+
+  // Engage HF edit mode and place the cursor in a span so the insert lands
+  // inside the header rather than at position 0.
+  await page.locator('.layout-page-header').first().dblclick();
+  await expect(page.locator('.hf-inline-editor')).toHaveCount(1);
+  await page.locator('.layout-page-header .layout-table-cell span[data-doc-from]').first().click();
+
+  const headerBefore = await page.locator('.layout-page-header').first().textContent();
+
+  // Click Options → "Insert current page number"
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /options/i })
+    .click();
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /current page number/i })
+    .click();
+
+  // Immediately read the painted header — should reflect the inserted field
+  // without any extra keystroke.
+  const headerImmediate = await page.locator('.layout-page-header').first().textContent();
+  // And after a beat for any deferred repaint.
+  await page.waitForTimeout(200);
+  const headerAfter = await page.locator('.layout-page-header').first().textContent();
+
+  console.log('BEFORE:', JSON.stringify(headerBefore));
+  console.log('IMMEDIATE:', JSON.stringify(headerImmediate));
+  console.log('AFTER:', JSON.stringify(headerAfter));
+
+  // Both immediate and delayed reads should differ from the pre-insert text.
+  expect(headerImmediate).not.toEqual(headerBefore);
+  expect(headerAfter).not.toEqual(headerBefore);
+});
+
+test('HF: PAGE field inserted without clicking inside cell first', async ({ page }) => {
+  // User's reported flow: double-click header → immediately open Options →
+  // Insert page number. No intervening click to place the cursor. The field
+  // should still appear in the painted header right away.
+  const editor = new EditorPage(page);
+  await editor.goto();
+  await editor.waitForReady();
+
+  await page
+    .locator('input[type="file"][accept=".docx"]')
+    .setInputFiles('e2e/fixtures/header-with-table.docx');
+  await page.waitForSelector('.layout-page-header [data-from-row]', { timeout: 15000 });
+
+  await page.locator('.layout-page-header').first().dblclick();
+  await expect(page.locator('.hf-inline-editor')).toHaveCount(1);
+
+  const headerBefore = await page.locator('.layout-page-header').first().textContent();
+
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /options/i })
+    .click();
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /current page number/i })
+    .click();
+
+  // No keystroke, no extra click. Read the painted header.
+  const headerAfter = await page.locator('.layout-page-header').first().textContent();
+  console.log('NO-CELL-CLICK BEFORE:', JSON.stringify(headerBefore));
+  console.log('NO-CELL-CLICK AFTER :', JSON.stringify(headerAfter));
+  expect(headerAfter).not.toEqual(headerBefore);
+});
+
+test('HF: NUMPAGES field renders total page count immediately', async ({ page }) => {
+  const editor = new EditorPage(page);
+  await editor.goto();
+  await editor.waitForReady();
+
+  await page
+    .locator('input[type="file"][accept=".docx"]')
+    .setInputFiles('e2e/fixtures/header-with-table.docx');
+  await page.waitForSelector('.layout-page-header [data-from-row]', { timeout: 15000 });
+
+  const totalPages = await page.locator('[data-page-number]').count();
+
+  await page.locator('.layout-page-header').first().dblclick();
+  await expect(page.locator('.hf-inline-editor')).toHaveCount(1);
+  await page.locator('.layout-page-header .layout-table-cell span[data-doc-from]').first().click();
+
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /options/i })
+    .click();
+  await page
+    .locator('.hf-inline-editor')
+    .getByRole('button', { name: /total page count/i })
+    .click();
+
+  const headerAfter = await page.locator('.layout-page-header').first().textContent();
+  console.log('NUMPAGES AFTER:', JSON.stringify(headerAfter), 'totalPages=', totalPages);
+  // The resolved value should appear somewhere in the painted header.
+  expect(headerAfter).toContain(String(totalPages));
+});