fix(layout): handle floating-only docs and ignore non-visual image ID churn (#2740)

* fix(layout): handle floating-only docs and ignore non-visual image ID churn

* fix(layout): keep paginator state in sync when pruning empty pages

Author: harbournick

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

@@ -221,6 +221,9 @@ export async function layoutHeaderFooterWithCache(
 
   // Page resolver path with digit bucketing
   const { totalPages: docTotalPages } = pageResolver(1);
+  if (!Number.isFinite(docTotalPages) || docTotalPages <= 0) {
+    return result;
+  }
   const useBucketing = FeatureFlags.HF_DIGIT_BUCKETING && docTotalPages >= MIN_PAGES_FOR_BUCKETING;
 
   for (const [type, blocks] of Object.entries(sections) as [keyof HeaderFooterBatch, FlowBlock[] | undefined][]) {

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

@@ -52,6 +52,35 @@ describe('layoutHeaderFooterWithCache', () => {
     expect(measureBlock).toHaveBeenCalledTimes(1);
   });
 
+  it('returns no layouts when the body layout has zero pages', async () => {
+    const sections = {
+      default: [
+        {
+          kind: 'paragraph',
+          id: 'page-token-footer',
+          runs: [
+            { text: 'Page ', fontFamily: 'Arial', fontSize: 16 },
+            { text: '0', token: 'pageNumber', fontFamily: 'Arial', fontSize: 16 },
+          ],
+        } satisfies FlowBlock,
+      ],
+    };
+    const measureBlock = vi.fn(async () => makeMeasure(12));
+
+    const result = await layoutHeaderFooterWithCache(
+      sections,
+      { width: 300, height: 40 },
+      measureBlock,
+      undefined,
+      undefined,
+      () => ({ displayText: '1', totalPages: 0 }),
+      'footer',
+    );
+
+    expect(result).toEqual({});
+    expect(measureBlock).not.toHaveBeenCalled();
+  });
+
   describe('integration test', () => {
     it('full pipeline: PM JSON with page tokens → FlowBlocks → Measures → Layout', async () => {
       // 1. Create PM JSON with page number tokens (simulates header/footer from SuperConverter)

packages/layout-engine/layout-engine/src/anchors.ts

@@ -25,6 +25,53 @@ export type AnchoredTable = {
 
 export type AnchoredObject = AnchoredDrawing | AnchoredTable;
 
+export type AnchoredTableCollection = {
+  byParagraph: Map<number, AnchoredTable[]>;
+  withoutParagraph: AnchoredTable[];
+};
+
+function buildParagraphIndexById(blocks: FlowBlock[], len: number): Map<string, number> {
+  const paragraphIndexById = new Map<string, number>();
+
+  for (let i = 0; i < len; i += 1) {
+    const block = blocks[i];
+    if (block.kind === 'paragraph') {
+      paragraphIndexById.set(block.id, i);
+    }
+  }
+
+  return paragraphIndexById;
+}
+
+function findNearestParagraphIndex(blocks: FlowBlock[], len: number, fromIndex: number): number | null {
+  for (let i = fromIndex - 1; i >= 0; i -= 1) {
+    if (blocks[i].kind === 'paragraph') return i;
+  }
+
+  for (let i = fromIndex + 1; i < len; i += 1) {
+    if (blocks[i].kind === 'paragraph') return i;
+  }
+
+  return null;
+}
+
+function resolveAnchorParagraphIndex(
+  blocks: FlowBlock[],
+  len: number,
+  paragraphIndexById: Map<string, number>,
+  fromIndex: number,
+  anchorParagraphId: unknown,
+): number | null {
+  if (typeof anchorParagraphId === 'string') {
+    const explicitIndex = paragraphIndexById.get(anchorParagraphId);
+    if (typeof explicitIndex === 'number') {
+      return explicitIndex;
+    }
+  }
+
+  return findNearestParagraphIndex(blocks, len, fromIndex);
+}
+
 /**
  * Check if an anchored image should be pre-registered (before any paragraphs are laid out).
  * Images with vRelativeFrom='margin' or 'page' position themselves relative to the page,
@@ -78,28 +125,7 @@ export function collectPreRegisteredAnchors(blocks: FlowBlock[], measures: Measu
 export function collectAnchoredDrawings(blocks: FlowBlock[], measures: Measure[]): Map<number, AnchoredDrawing[]> {
   const map = new Map<number, AnchoredDrawing[]>();
   const len = Math.min(blocks.length, measures.length);
-  const paragraphIndexById = new Map<string, number>();
-
-  for (let i = 0; i < len; i += 1) {
-    const block = blocks[i];
-    if (block.kind === 'paragraph') {
-      paragraphIndexById.set(block.id, i);
-    }
-  }
-
-  const nearestPrevParagraph = (fromIndex: number): number | null => {
-    for (let i = fromIndex - 1; i >= 0; i -= 1) {
-      if (blocks[i].kind === 'paragraph') return i;
-    }
-    return null;
-  };
-
-  const nearestNextParagraph = (fromIndex: number): number | null => {
-    for (let i = fromIndex + 1; i < len; i += 1) {
-      if (blocks[i].kind === 'paragraph') return i;
-    }
-    return null;
-  };
+  const paragraphIndexById = buildParagraphIndexById(blocks, len);
 
   for (let i = 0; i < len; i += 1) {
     const block = blocks[i];
@@ -125,12 +151,7 @@ export function collectAnchoredDrawings(blocks: FlowBlock[], measures: Measure[]
       typeof drawingBlock.attrs === 'object' && drawingBlock.attrs
         ? (drawingBlock.attrs as { anchorParagraphId?: unknown }).anchorParagraphId
         : undefined;
-    let anchorParaIndex =
-      typeof anchorParagraphId === 'string' ? (paragraphIndexById.get(anchorParagraphId) ?? null) : null;
-    if (anchorParaIndex == null) {
-      anchorParaIndex = nearestPrevParagraph(i);
-    }
-    if (anchorParaIndex == null) anchorParaIndex = nearestNextParagraph(i);
+    const anchorParaIndex = resolveAnchorParagraphIndex(blocks, len, paragraphIndexById, i, anchorParagraphId);
     if (anchorParaIndex == null) continue; // no paragraphs at all
 
     const list = map.get(anchorParaIndex) ?? [];
@@ -143,34 +164,15 @@ export function collectAnchoredDrawings(blocks: FlowBlock[], measures: Measure[]
 
 /**
  * Collect anchored/floating tables mapped to their anchor paragraph index.
- * Map of paragraph block index -> anchored tables associated with that paragraph.
+ * Also returns anchored tables that have no paragraph to attach to.
  */
-export function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]): Map<number, AnchoredTable[]> {
-  const map = new Map<number, AnchoredTable[]>();
-  const paragraphIndexById = new Map<string, number>();
-
-  for (let i = 0; i < blocks.length; i += 1) {
-    const block = blocks[i];
-    if (block.kind === 'paragraph') {
-      paragraphIndexById.set(block.id, i);
-    }
-  }
-
-  const nearestPrevParagraph = (fromIndex: number): number | null => {
-    for (let i = fromIndex - 1; i >= 0; i -= 1) {
-      if (blocks[i].kind === 'paragraph') return i;
-    }
-    return null;
-  };
-
-  const nearestNextParagraph = (fromIndex: number): number | null => {
-    for (let i = fromIndex + 1; i < blocks.length; i += 1) {
-      if (blocks[i].kind === 'paragraph') return i;
-    }
-    return null;
-  };
+export function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]): AnchoredTableCollection {
+  const len = Math.min(blocks.length, measures.length);
+  const byParagraph = new Map<number, AnchoredTable[]>();
+  const withoutParagraph: AnchoredTable[] = [];
+  const paragraphIndexById = buildParagraphIndexById(blocks, len);
 
-  for (let i = 0; i < blocks.length; i += 1) {
+  for (let i = 0; i < len; i += 1) {
     const block = blocks[i];
     const measure = measures[i];
 
@@ -187,18 +189,19 @@ export function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]):
       typeof tableBlock.attrs === 'object' && tableBlock.attrs
         ? (tableBlock.attrs as { anchorParagraphId?: unknown }).anchorParagraphId
         : undefined;
-    let anchorParaIndex =
-      typeof anchorParagraphId === 'string' ? (paragraphIndexById.get(anchorParagraphId) ?? null) : null;
+    const anchorParaIndex = resolveAnchorParagraphIndex(blocks, len, paragraphIndexById, i, anchorParagraphId);
     if (anchorParaIndex == null) {
-      anchorParaIndex = nearestPrevParagraph(i);
+      withoutParagraph.push({ block: tableBlock, measure: tableMeasure });
+      continue;
     }
-    if (anchorParaIndex == null) anchorParaIndex = nearestNextParagraph(i);
-    if (anchorParaIndex == null) continue; // no paragraphs at all
 
-    const list = map.get(anchorParaIndex) ?? [];
+    const list = byParagraph.get(anchorParaIndex) ?? [];
     list.push({ block: tableBlock, measure: tableMeasure });
-    map.set(anchorParaIndex, list);
+    byParagraph.set(anchorParaIndex, list);
   }
 
-  return map;
+  return {
+    byParagraph,
+    withoutParagraph,
+  };
 }

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

@@ -79,6 +79,21 @@ const makeTableMeasure = (columnWidths: number[], rowHeights: number[]): TableMe
   totalHeight: rowHeights.reduce((sum, height) => sum + height, 0),
 });
 
+const makeParagraphlessFloatingTable = (id: string): TableBlock =>
+  makeTableBlock(id, 1, {
+    anchor: {
+      isAnchored: true,
+      hRelativeFrom: 'page',
+      vRelativeFrom: 'paragraph',
+      offsetH: 120,
+      offsetV: 15,
+    },
+    wrap: {
+      type: 'Square',
+      wrapText: 'bothSides',
+    },
+  });
+
 const block: FlowBlock = {
   kind: 'paragraph',
   id: 'block-1',
@@ -716,6 +731,48 @@ describe('layoutDocument', () => {
     expect(anchoredTableFragment?.y).toBe(DEFAULT_OPTIONS.margins!.top + paragraphMeasure.totalHeight);
   });
 
+  it('renders a floating table when the document has no body paragraphs', () => {
+    const floatingOnlyTable = makeParagraphlessFloatingTable('table-floating-only');
+    const floatingOnlyMeasure = makeTableMeasure([220], [60]);
+
+    const layout = layoutDocument([floatingOnlyTable], [floatingOnlyMeasure], DEFAULT_OPTIONS);
+
+    expect(layout.pages).toHaveLength(1);
+
+    const fragment = layout.pages[0].fragments.find(
+      (candidate) => candidate.kind === 'table' && candidate.blockId === 'table-floating-only',
+    ) as TableFragment | undefined;
+
+    expect(fragment).toBeTruthy();
+    expect(fragment?.x).toBe(120);
+    expect(fragment?.y).toBe(DEFAULT_OPTIONS.margins!.top + 15);
+  });
+
+  it('renders a floating table after pruning a leading empty page', () => {
+    const leadingPageBreak: PageBreakBlock = {
+      kind: 'pageBreak',
+      id: 'page-break-before-floating-table',
+    };
+    const floatingOnlyTable = makeParagraphlessFloatingTable('table-floating-after-page-break');
+    const floatingOnlyMeasure = makeTableMeasure([220], [60]);
+
+    const layout = layoutDocument(
+      [leadingPageBreak, floatingOnlyTable],
+      [{ kind: 'pageBreak' }, floatingOnlyMeasure],
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.pages).toHaveLength(1);
+
+    const fragment = layout.pages[0].fragments.find(
+      (candidate) => candidate.kind === 'table' && candidate.blockId === 'table-floating-after-page-break',
+    ) as TableFragment | undefined;
+
+    expect(fragment).toBeTruthy();
+    expect(fragment?.x).toBe(120);
+    expect(fragment?.y).toBe(DEFAULT_OPTIONS.margins!.top + 15);
+  });
+
   it('propagates pm ranges onto fragments', () => {
     const blockWithRuns: FlowBlock = {
       kind: 'paragraph',