feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006) (#3599)

* feat(super-converter): match field dispatch keywords case-insensitively

OOXML field type names are case-insensitive, but the field-reference
preprocessors dispatched on the raw first token (e.g. only "PAGE",
not "page"). A lowercase PAGE/NUMPAGES field in a repeated footer fell
through to the cached static text and showed the same number on every
page.

Add a shared extractFieldKeyword helper that normalizes the dispatch
token to upper case while leaving the original instruction text intact
for downstream processors, and route fldSimple/fldChar dispatch and the
header/footer page-field scan through it. Make the HYPERLINK target
regex case-insensitive and anchored. Cover the new behavior with unit
tests and a behavior spec asserting a lowercase PAGE footer resolves
per page.

* test(super-converter): cover field keyword dispatch

* fix(super-converter): trust header footer field keyword

* feat(page-number): support PAGE field value-format switches

Parse the `\*` value-format switches on PAGE field instructions (Arabic,
Roman/roman, ALPHABETIC/alphabetic, ArabicDash) into a run-local
pageNumberFormat override, and apply it independently of section numbering
when resolving page-number tokens.

- add parsePageInstruction / pageNumberFormatToInstructionSwitch in a new
  page-instruction.js; page-preprocessor stores the original instruction and
  parsed format on sd:autoPageNumber
- round-trip instruction + pageNumberFormat through the autoPageNumber
  translator and the page-number extension node (preserve imported
  instruction text, synthesize a switch for new formatted nodes)
- add pageNumberFormat to TextRun and thread it through layout-bridge,
  layout-resolved, painters (resolveRunText), and stamp section-aware
  displayNumber on pages so formatting uses the pre-format numeric value
- move formatPageNumber + PageNumberFormat into @superdoc/contracts as the
  single source of truth; re-export from pageNumbering
- include pageNumberFormat in block-version, merge, and hash signatures so
  format changes invalidate cached layouts

upperLetter/lowerLetter now render as repeated letters (AA, BB, CC) to match
Word instead of the previous Excel-style sequence (AA, AB).

* fix(page-number): render ArabicDash spacing

* fix(layout-bridge): hash page number formats

* fix(page-number): fall back for unknown formats

* test(behavior): cover formatted footer page fields

* fix(page-number): address PAGE field review feedback

* fix(sequence-field): preserve cached numbering for lowercase seq fields

Only dispatch the SEQ pre-processor for uppercase SEQ instructions so
lowercase `seq` fields keep their cached visible result runs instead of
being re-resolved. Also recurse into run-wrapped content when extracting
resolved text so cached numbers nested inside runs are captured.

* fix(painter): rebuild drawing page fields on context changes

* fix: footnote formatter parity test

* fix(layout): remove duplicate displayNumber fields and fix page signature ref

Drop the redundant displayNumber declarations from HeaderFooterPage,
ResolvedHeaderFooterPage, and the layout-bridge page builder, keeping the
section-aware variant. Correct the renderer page context signature to read
displayPageNumber instead of the nonexistent pageNumberDisplayNumber.

* test(layout): update page-number field expectations

Adjust header/footer token and footer rendering expectations to the
spaced "- N -" format, and migrate the renderer page-context test to the
pageNumberFieldFormat shape.

Author: luccas-harbour

packages/layout-engine/contracts/src/index.ts

@@ -2260,8 +2260,9 @@ export type HeaderFooterType = 'default' | 'first' | 'even' | 'odd';
 export type HeaderFooterPage = {
   number: number;
   fragments: Fragment[];
-  displayNumber?: number;
   numberText?: string;
+  /** Section-aware numeric page value before formatting. */
+  displayNumber?: number;
   /**
    * Optional page-local block clones backing this page's resolved fragments.
    * Present when header/footer tokens were laid out per page or per bucket.

packages/layout-engine/contracts/src/page-number-formatting.test.ts

@@ -7,8 +7,9 @@ describe('page number formatting', () => {
     expect(formatPageNumber(5, 'upperRoman')).toBe('V');
     expect(formatPageNumber(5, 'lowerRoman')).toBe('v');
     expect(formatPageNumber(27, 'upperLetter')).toBe('AA');
-    expect(formatPageNumber(703, 'lowerLetter')).toBe('aaa');
-    expect(formatPageNumber(12, 'numberInDash')).toBe('-12-');
+    expect(formatPageNumber(28, 'upperLetter')).toBe('BB');
+    expect(formatPageNumber(703, 'lowerLetter')).toBe('a'.repeat(28));
+    expect(formatPageNumber(12, 'numberInDash')).toBe('- 12 -');
   });
 
   it('normalizes page numbers before formatting', () => {
@@ -17,6 +18,10 @@ describe('page number formatting', () => {
     expect(formatPageNumber(Number.NaN, 'decimal')).toBe('1');
   });
 
+  it('falls back to decimal for unsupported runtime formats', () => {
+    expect(formatPageNumber(5, 'chicago' as never)).toBe('5');
+  });
+
   it('falls back to decimal for roman numerals beyond 3999', () => {
     expect(formatPageNumber(4000, 'upperRoman')).toBe('4000');
   });

packages/layout-engine/contracts/src/page-number-formatting.ts

@@ -24,16 +24,10 @@ function toUpperRoman(value: number): string {
 }
 
 function toUpperLetter(value: number): string {
-  let n = Math.max(1, value);
-  let result = '';
-
-  while (n > 0) {
-    const remainder = (n - 1) % 26;
-    result = String.fromCharCode(65 + remainder) + result;
-    n = Math.floor((n - 1) / 26);
-  }
-
-  return result;
+  const normalized = Math.max(1, value);
+  const index = (normalized - 1) % 26;
+  const repeatCount = Math.floor((normalized - 1) / 26) + 1;
+  return String.fromCharCode(65 + index).repeat(repeatCount);
 }
 
 export function formatPageNumber(pageNumber: number, format: PageNumberFormat): string {
@@ -49,7 +43,7 @@ export function formatPageNumber(pageNumber: number, format: PageNumberFormat):
     case 'lowerLetter':
       return toUpperLetter(value).toLowerCase();
     case 'numberInDash':
-      return `-${value}-`;
+      return `- ${value} -`;
     case 'decimal':
     default:
       return String(value);

packages/layout-engine/contracts/src/resolved-layout.ts

@@ -452,9 +452,9 @@ export function isResolvedDrawingItem(item: ResolvedPaintItem): item is Resolved
 /** A resolved header/footer page — mirrors HeaderFooterPage but with resolved items. */
 export type ResolvedHeaderFooterPage = {
   number: number;
-  /** Numeric page number after section numbering restart/offset. Used for OOXML odd/even parity. */
-  displayNumber?: number;
   numberText?: string;
+  /** Section-aware numeric page value before formatting. */
+  displayNumber?: number;
   items: ResolvedPaintItem[];
 };
 

packages/layout-engine/layout-bridge/src/cacheInvalidation.ts

@@ -51,6 +51,7 @@ export function computeHeaderFooterContentHash(blocks: FlowBlock[]): string {
         if ('bold' in run && run.bold) parts.push('b');
         if ('italic' in run && run.italic) parts.push('i');
         if ('token' in run && run.token) parts.push(`token:${run.token}`);
+        if ('pageNumberFormat' in run && run.pageNumberFormat) parts.push(`pnf:${run.pageNumberFormat}`);
       }
     }
   }

packages/layout-engine/layout-bridge/src/layoutHeaderFooter.ts

@@ -1,4 +1,11 @@
-import type { FlowBlock, HeaderFooterLayout, Measure, ParagraphBlock, TableBlock } from '@superdoc/contracts';
+import type {
+  FlowBlock,
+  HeaderFooterLayout,
+  ListBlock,
+  Measure,
+  ParagraphBlock,
+  TableBlock,
+} from '@superdoc/contracts';
 import { layoutHeaderFooter, type HeaderFooterConstraints } from '@superdoc/layout-engine';
 import { MeasureCache } from './cache';
 import { resolveHeaderFooterTokens, cloneHeaderFooterBlocks } from './resolveHeaderFooterTokens';
@@ -143,6 +150,11 @@ function hasPageTokens(blocks: FlowBlock[]): boolean {
   for (const block of blocks) {
     if (block.kind === 'paragraph') {
       if (paragraphHasPageToken(block as ParagraphBlock)) return true;
+    } else if (block.kind === 'list') {
+      const list = block as ListBlock;
+      for (const item of list.items ?? []) {
+        if (paragraphHasPageToken(item.paragraph)) return true;
+      }
     } else if (block.kind === 'table') {
       // SD-1332: PAGE fields can live inside table cells in headers/footers
       // (Word's typical layout). Skipping tables here would take the
@@ -168,6 +180,11 @@ function hasPageNumberTokensRequiringPerPageLayout(blocks: FlowBlock[]): boolean
   for (const block of blocks) {
     if (block.kind === 'paragraph') {
       if (paragraphRequiresPerPageLayout(block as ParagraphBlock)) return true;
+    } else if (block.kind === 'list') {
+      const list = block as ListBlock;
+      for (const item of list.items ?? []) {
+        if (paragraphRequiresPerPageLayout(item.paragraph)) return true;
+      }
     } else if (block.kind === 'table') {
       const table = block as TableBlock;
       for (const row of table.rows ?? []) {
@@ -332,6 +349,7 @@ export async function layoutHeaderFooterWithCache(
       blocks: FlowBlock[];
       measures: Measure[];
       fragments: HeaderFooterLayout['pages'][0]['fragments'];
+      numberText?: string;
     }> = [];
 
     for (const pageNum of pagesToLayout) {
@@ -372,6 +390,7 @@ export async function layoutHeaderFooterWithCache(
         blocks: clonedBlocks,
         measures,
         fragments: fragmentsWithLines,
+        numberText: displayText,
       });
     }
 
@@ -390,6 +409,7 @@ export async function layoutHeaderFooterWithCache(
         number: p.number,
         displayNumber: p.displayNumber,
         fragments: p.fragments,
+        numberText: p.numberText,
         blocks: p.blocks,
         measures: p.measures,
       })),

packages/layout-engine/layout-bridge/test/cacheInvalidation.test.ts

@@ -52,6 +52,25 @@ describe('Cache Invalidation', () => {
         expect(hash).toContain('token:pageNumber');
       });
 
+      it('should include page number token format in hash', () => {
+        const decimalBlocks: FlowBlock[] = [
+          {
+            kind: 'paragraph',
+            id: 'p1',
+            runs: [{ text: '0', token: 'pageNumber', pageNumberFormat: 'decimal' }],
+          } as ParagraphBlock,
+        ];
+        const romanBlocks: FlowBlock[] = [
+          {
+            kind: 'paragraph',
+            id: 'p1',
+            runs: [{ text: '0', token: 'pageNumber', pageNumberFormat: 'upperRoman' }],
+          } as ParagraphBlock,
+        ];
+
+        expect(computeHeaderFooterContentHash(decimalBlocks)).not.toBe(computeHeaderFooterContentHash(romanBlocks));
+      });
+
       it('should produce different hashes for different content', () => {
         const blocks1: FlowBlock[] = [
           {

packages/layout-engine/layout-bridge/test/layoutHeaderFooterBucketing.test.ts

@@ -89,6 +89,23 @@ const makePageTokenBlock = (id: string): FlowBlock => ({
   ],
 });
 
+const makeFormattedPageTokenBlock = (
+  id: string,
+  pageNumberFieldFormat: NonNullable<TextRun['pageNumberFieldFormat']>,
+): FlowBlock => ({
+  kind: 'paragraph',
+  id,
+  runs: [
+    {
+      text: '0',
+      token: 'pageNumber',
+      pageNumberFieldFormat,
+      fontFamily: 'Arial',
+      fontSize: 12,
+    } as TextRun,
+  ],
+});
+
 describe('getBucketForPageNumber', () => {
   it('should return d1 for single-digit page numbers (1-9)', () => {
     expect(getBucketForPageNumber(1)).toBe('d1');
@@ -440,6 +457,34 @@ describe('layoutHeaderFooterWithCache - Digit Bucketing (Large Docs)', () => {
     expect(measureBlock).toHaveBeenCalledTimes(3);
     expect((result.default?.layout.pages[0].blocks?.[0] as ParagraphBlock).runs[1].text).toBe('005');
   });
+
+  it.each([
+    ['decimal', { format: 'decimal' }],
+    ['numberInDash', { format: 'numberInDash' }],
+  ] as const)('should keep bucketing for %s run-local page number format', async (_name, pageNumberFieldFormat) => {
+    const sections = {
+      default: [makeFormattedPageTokenBlock(`header-${pageNumberFieldFormat.format}`, pageNumberFieldFormat)],
+    };
+
+    const pageResolver: PageResolver = (pageNum) => ({
+      displayText: String(pageNum),
+      displayNumber: pageNum,
+      totalPages: 150,
+    });
+
+    const measureBlock = vi.fn(async () => makeMeasure(20));
+    const result = await layoutHeaderFooterWithCache(
+      sections,
+      { width: 400, height: 80 },
+      measureBlock,
+      undefined,
+      undefined,
+      pageResolver,
+    );
+
+    expect(result.default?.layout.pages).toHaveLength(3);
+    expect(measureBlock).toHaveBeenCalledTimes(3);
+  });
 });
 
 describe('layoutHeaderFooterWithCache - Section-Aware Token Resolution', () => {

packages/layout-engine/layout-bridge/test/resolveHeaderFooterTokens.test.ts

@@ -81,7 +81,7 @@ describe('resolveHeaderFooterTokens', () => {
     resolveHeaderFooterTokens(blocks, 3, 10, 'iii', 7);
 
     const block = blocks[0] as ParagraphBlock;
-    expect(block.runs[0].text).toBe('-7-');
+    expect(block.runs[0].text).toBe('- 7 -');
     expect((block.runs[0] as TextRun).token).toBe('pageNumber');
   });
 

packages/layout-engine/layout-engine/src/pageNumbering.test.ts

@@ -31,16 +31,20 @@ describe('formatPageNumber', () => {
     it('should truncate fractional numbers before formatting', () => {
       expect(formatPageNumber(4.9, 'decimal')).toBe('4');
     });
+
+    it('should fall back to decimal for unsupported runtime formats', () => {
+      expect(formatPageNumber(5, 'chicago' as never)).toBe('5');
+    });
   });
 
   describe('numberInDash format', () => {
     it('should wrap numbers in dashes', () => {
-      expect(formatPageNumber(1, 'numberInDash')).toBe('-1-');
-      expect(formatPageNumber(12, 'numberInDash')).toBe('-12-');
+      expect(formatPageNumber(1, 'numberInDash')).toBe('- 1 -');
+      expect(formatPageNumber(12, 'numberInDash')).toBe('- 12 -');
     });
 
     it('should clamp zero to 1', () => {
-      expect(formatPageNumber(0, 'numberInDash')).toBe('-1-');
+      expect(formatPageNumber(0, 'numberInDash')).toBe('- 1 -');
     });
   });
 
@@ -128,19 +132,19 @@ describe('formatPageNumber', () => {
       expect(formatPageNumber(26, 'upperLetter')).toBe('Z');
     });
 
-    it('should format numbers > 26 as AA, AB, etc.', () => {
+    it('should format numbers > 26 as repeated letters', () => {
       expect(formatPageNumber(27, 'upperLetter')).toBe('AA');
-      expect(formatPageNumber(28, 'upperLetter')).toBe('AB');
-      expect(formatPageNumber(52, 'upperLetter')).toBe('AZ');
-      expect(formatPageNumber(53, 'upperLetter')).toBe('BA');
-      expect(formatPageNumber(78, 'upperLetter')).toBe('BZ');
-      expect(formatPageNumber(79, 'upperLetter')).toBe('CA');
+      expect(formatPageNumber(28, 'upperLetter')).toBe('BB');
+      expect(formatPageNumber(52, 'upperLetter')).toBe('ZZ');
+      expect(formatPageNumber(53, 'upperLetter')).toBe('AAA');
+      expect(formatPageNumber(78, 'upperLetter')).toBe('ZZZ');
+      expect(formatPageNumber(79, 'upperLetter')).toBe('AAAA');
     });
 
     it('should format large numbers correctly', () => {
-      expect(formatPageNumber(702, 'upperLetter')).toBe('ZZ');
-      expect(formatPageNumber(703, 'upperLetter')).toBe('AAA');
-      expect(formatPageNumber(704, 'upperLetter')).toBe('AAB');
+      expect(formatPageNumber(702, 'upperLetter')).toBe('Z'.repeat(27));
+      expect(formatPageNumber(703, 'upperLetter')).toBe('A'.repeat(28));
+      expect(formatPageNumber(704, 'upperLetter')).toBe('B'.repeat(28));
     });
 
     it('should clamp zero and negative to A', () => {
@@ -158,16 +162,16 @@ describe('formatPageNumber', () => {
       expect(formatPageNumber(26, 'lowerLetter')).toBe('z');
     });
 
-    it('should format numbers > 26 as aa, ab, etc.', () => {
+    it('should format numbers > 26 as repeated letters', () => {
       expect(formatPageNumber(27, 'lowerLetter')).toBe('aa');
-      expect(formatPageNumber(28, 'lowerLetter')).toBe('ab');
-      expect(formatPageNumber(52, 'lowerLetter')).toBe('az');
-      expect(formatPageNumber(53, 'lowerLetter')).toBe('ba');
+      expect(formatPageNumber(28, 'lowerLetter')).toBe('bb');
+      expect(formatPageNumber(52, 'lowerLetter')).toBe('zz');
+      expect(formatPageNumber(53, 'lowerLetter')).toBe('aaa');
     });
 
     it('should format large numbers correctly', () => {
-      expect(formatPageNumber(702, 'lowerLetter')).toBe('zz');
-      expect(formatPageNumber(703, 'lowerLetter')).toBe('aaa');
+      expect(formatPageNumber(702, 'lowerLetter')).toBe('z'.repeat(27));
+      expect(formatPageNumber(703, 'lowerLetter')).toBe('a'.repeat(28));
     });
 
     it('should clamp zero and negative to a', () => {
@@ -434,7 +438,7 @@ describe('computeDisplayPageNumber', () => {
       expect(result[24].displayText).toBe('Y');
       expect(result[25].displayText).toBe('Z');
       expect(result[26].displayText).toBe('AA');
-      expect(result[27].displayText).toBe('AB');
+      expect(result[27].displayText).toBe('BB');
     });
 
     it('should handle large page numbers in roman numerals', () => {