refactor: centralizing anchored graphic placement

Author: VladaHarbour

packages/layout-engine/contracts/src/graphic-placement.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveAnchoredGraphicY,
+  computeParagraphContentStartY,
+  computeParagraphLayoutStartY,
+} from './graphic-placement.js';
+
+const base = {
+  objectHeight: 100,
+  contentTop: 72,
+  contentBottom: 720,
+  pageBottomMargin: 72,
+};
+
+describe('resolveAnchoredGraphicY', () => {
+  it('positions margin-relative top with offset', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...base,
+        anchor: { vRelativeFrom: 'margin', alignV: 'top', offsetV: 10 },
+      }),
+    ).toBe(82);
+  });
+
+  it('positions page-relative bottom with page margin', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...base,
+        anchor: { vRelativeFrom: 'page', alignV: 'bottom', offsetV: 5 },
+      }),
+    ).toBe(720 + 72 - 100 + 5);
+  });
+
+  it('positions paragraph-relative center on first line', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...base,
+        anchor: { vRelativeFrom: 'paragraph', alignV: 'center', offsetV: 0 },
+        anchorParagraphY: 200,
+        firstLineHeight: 24,
+      }),
+    ).toBe(200 + (24 - 100) / 2);
+  });
+
+  it('uses pre-registered fallback when vRelativeFrom is paragraph without paragraph context', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...base,
+        anchor: { vRelativeFrom: 'paragraph', offsetV: 20 },
+        preRegisteredFallbackToContentTop: true,
+      }),
+    ).toBe(92);
+  });
+
+  it('legacy undefined vRelativeFrom uses anchor paragraph Y', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...base,
+        anchor: { offsetV: 15 },
+        anchorParagraphY: 300,
+      }),
+    ).toBe(315);
+  });
+});
+
+describe('computeParagraphLayoutStartY', () => {
+  it('rewinds trailing then applies full spacing-before without double collapse', () => {
+    expect(
+      computeParagraphLayoutStartY({
+        cursorY: 120,
+        spacingBefore: 24,
+        trailingSpacing: 12,
+        rewindTrailingFromPrevious: true,
+      }),
+    ).toBe(132);
+  });
+
+  it('collapses spacing-before against trailing when previous after-spacing is kept', () => {
+    expect(
+      computeParagraphLayoutStartY({
+        cursorY: 100,
+        spacingBefore: 24,
+        trailingSpacing: 8,
+        rewindTrailingFromPrevious: false,
+      }),
+    ).toBe(116);
+  });
+});
+
+describe('computeParagraphContentStartY', () => {
+  it('adds spacing-before minus trailing collapse', () => {
+    expect(computeParagraphContentStartY(100, 24, false, 8)).toBe(116);
+  });
+
+  it('returns cursorY when spacing already applied', () => {
+    expect(computeParagraphContentStartY(100, 24, true, 0)).toBe(100);
+  });
+});

packages/layout-engine/contracts/src/graphic-placement.ts

@@ -0,0 +1,192 @@
+type AnchorVRelative = 'paragraph' | 'page' | 'margin';
+type AnchorHRelative = 'column' | 'page' | 'margin';
+type AnchorAlignH = 'left' | 'center' | 'right';
+type AnchorAlignV = 'top' | 'center' | 'bottom';
+
+export type ColumnLayoutForAnchor = {
+  width: number;
+  gap: number;
+  count: number;
+};
+
+/**
+ * Inputs for resolving the paint Y of an anchored image, drawing, or floating table.
+ * `offsetV` is applied inside this function; callers must pass the resolved value to
+ * text-wrap registration without adding `offsetV` again.
+ */
+export type ResolveAnchoredGraphicYInput = {
+  anchor?: {
+    vRelativeFrom?: AnchorVRelative;
+    alignV?: AnchorAlignV;
+    offsetV?: number;
+  };
+  objectHeight: number;
+  contentTop: number;
+  contentBottom: number;
+  /** Bottom page margin in px (used when vRelativeFrom is `page`). */
+  pageBottomMargin?: number;
+  /**
+   * Anchor paragraph top Y (body cursor when laying out the anchor paragraph).
+   * Used for `paragraph` and legacy (undefined vRelativeFrom) positioning.
+   */
+  anchorParagraphY?: number;
+  /** First line height of the anchor paragraph (paragraph-relative alignV). */
+  firstLineHeight?: number;
+  /**
+   * When true and vRelativeFrom is not margin/page, fall back to contentTop + offsetV
+   * (page/margin pre-registered anchors that lack paragraph context).
+   */
+  preRegisteredFallbackToContentTop?: boolean;
+};
+
+/**
+ * Resolve the vertical paint position for an anchored graphic (image, drawing, or table).
+ */
+export function resolveAnchoredGraphicY(input: ResolveAnchoredGraphicYInput): number {
+  const {
+    anchor,
+    objectHeight,
+    contentTop,
+    contentBottom,
+    pageBottomMargin = 0,
+    anchorParagraphY = contentTop,
+    firstLineHeight = 0,
+    preRegisteredFallbackToContentTop = false,
+  } = input;
+
+  const offsetV = anchor?.offsetV ?? 0;
+  const vRelativeFrom = anchor?.vRelativeFrom;
+  const alignV = anchor?.alignV;
+  const contentHeight = Math.max(0, contentBottom - contentTop);
+
+  if (vRelativeFrom === 'margin') {
+    if (alignV === 'bottom') {
+      return contentBottom - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return contentTop + (contentHeight - objectHeight) / 2 + offsetV;
+    }
+    return contentTop + offsetV;
+  }
+
+  if (vRelativeFrom === 'page') {
+    const pageHeight = contentBottom + pageBottomMargin;
+    if (alignV === 'bottom') {
+      return pageHeight - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return (pageHeight - objectHeight) / 2 + offsetV;
+    }
+    return offsetV;
+  }
+
+  if (vRelativeFrom === 'paragraph') {
+    const baseAnchorY = anchorParagraphY;
+    if (alignV === 'bottom') {
+      return baseAnchorY + firstLineHeight - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return baseAnchorY + (firstLineHeight - objectHeight) / 2 + offsetV;
+    }
+    return baseAnchorY + offsetV;
+  }
+
+  if (preRegisteredFallbackToContentTop) {
+    return contentTop + offsetV;
+  }
+
+  return anchorParagraphY + offsetV;
+}
+
+/**
+ * Y coordinate where paragraph text begins (after spacing-before collapse).
+ */
+export function computeParagraphContentStartY(
+  cursorY: number,
+  spacingBefore: number,
+  appliedSpacingBefore: boolean,
+  trailingSpacing: number | undefined,
+): number {
+  if (appliedSpacingBefore || spacingBefore <= 0) {
+    return cursorY;
+  }
+  const prevTrailing = trailingSpacing ?? 0;
+  return cursorY + Math.max(spacingBefore - prevTrailing, 0);
+}
+
+/**
+ * Paragraph text start Y including contextual-spacing rewind from the previous paragraph.
+ */
+export function computeParagraphLayoutStartY(input: {
+  cursorY: number;
+  spacingBefore: number;
+  trailingSpacing?: number;
+  suppressSpacingBefore?: boolean;
+  rewindTrailingFromPrevious?: boolean;
+}): number {
+  let y = input.cursorY;
+  let trailingForCollapse = input.trailingSpacing;
+  if (input.rewindTrailingFromPrevious) {
+    const prevTrailing = input.trailingSpacing ?? 0;
+    if (prevTrailing > 0) {
+      y -= prevTrailing;
+      // Match layout-paragraph.ts: after rewind, trailingSpacing is cleared before
+      // spacing-before is applied — do not collapse against the rewound gap again.
+      trailingForCollapse = 0;
+    }
+  }
+  const effectiveSpacingBefore = input.suppressSpacingBefore ? 0 : input.spacingBefore;
+  return computeParagraphContentStartY(y, effectiveSpacingBefore, effectiveSpacingBefore === 0, trailingForCollapse);
+}
+
+/**
+ * Resolve horizontal paint position for an anchored graphic.
+ */
+export function resolveAnchoredGraphicX(
+  anchor: {
+    hRelativeFrom?: AnchorHRelative;
+    alignH?: AnchorAlignH;
+    offsetH?: number;
+  },
+  columnIndex: number,
+  columns: ColumnLayoutForAnchor,
+  objectWidth: number,
+  margins?: { left?: number; right?: number },
+  pageWidth?: number,
+): number {
+  const alignH = anchor.alignH ?? 'left';
+  const offsetH = anchor.offsetH ?? 0;
+
+  const marginLeft = Math.max(0, margins?.left ?? 0);
+  const marginRight = Math.max(0, margins?.right ?? 0);
+  const contentWidth = pageWidth != null ? Math.max(1, pageWidth - (marginLeft + marginRight)) : columns.width;
+
+  const contentLeft = marginLeft;
+  const columnLeft = contentLeft + columnIndex * (columns.width + columns.gap);
+
+  const relativeFrom = anchor.hRelativeFrom ?? 'column';
+
+  let baseX: number;
+  let availableWidth: number;
+  if (relativeFrom === 'page') {
+    baseX = 0;
+    availableWidth = pageWidth != null ? pageWidth : contentWidth + marginLeft + marginRight;
+  } else if (relativeFrom === 'margin') {
+    baseX = contentLeft;
+    availableWidth = contentWidth;
+  } else {
+    baseX = columnLeft;
+    availableWidth = columns.width;
+  }
+
+  if (alignH === 'left') {
+    return baseX + offsetH;
+  }
+  if (alignH === 'right') {
+    return baseX + availableWidth - objectWidth - offsetH;
+  }
+  if (alignH === 'center') {
+    return baseX + (availableWidth - objectWidth) / 2 + offsetH;
+  }
+  return baseX;
+}

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

@@ -79,6 +79,15 @@ export {
 
 export { computeFragmentPmRange, computeLinePmRange, type LinePmRange } from './pm-range.js';
 
+export {
+  resolveAnchoredGraphicY,
+  resolveAnchoredGraphicX,
+  computeParagraphContentStartY,
+  computeParagraphLayoutStartY,
+  type ColumnLayoutForAnchor,
+  type ResolveAnchoredGraphicYInput,
+} from './graphic-placement.js';
+
 // Editor-neutral layout identity primitives (prep-001).
 // Additive only — `pmStart`/`pmEnd` and PM-shaped fields remain available
 // alongside these on every fragment/run.

packages/layout-engine/layout-engine/src/floating-objects.test.ts

@@ -132,7 +132,7 @@ describe('FloatingObjectManager', () => {
       expect(zones[0].bounds.x).toBe((600 - 200) / 2 + 10); // (columnWidth - imageWidth) / 2 + offsetH
     });
 
-    it('applies vertical offset to image Y position', () => {
+    it('uses fully resolved anchor Y for exclusion bounds (offset applied upstream)', () => {
       const manager = createFloatingObjectManager(mockColumns, { left: 0, right: 0 }, 600);
       const imageBlock = createMockImageBlock({
         anchor: {
@@ -141,10 +141,11 @@ describe('FloatingObjectManager', () => {
         },
       });
 
-      manager.registerDrawing(imageBlock, createMockMeasure(), 100, 0, 1);
+      // resolvedAnchorY already includes offsetV from resolveAnchoredGraphicY
+      manager.registerDrawing(imageBlock, createMockMeasure(), 150, 0, 1);
 
       const zones = manager.getAllFloatsForPage(1);
-      expect(zones[0].bounds.y).toBe(150); // anchorY(100) + offsetV(50)
+      expect(zones[0].bounds.y).toBe(150);
     });
   });
 
@@ -236,8 +237,8 @@ describe('FloatingObjectManager', () => {
       manager.registerDrawing(imageBlock, createMockMeasure(), 100, 0, 1);
 
       const result = manager.computeAvailableWidth(120, 20, 600, 0, 1);
-      expect(result.width).toBe(600 - 200 - 5 - 10); // baseWidth - imageWidth - distLeft - distRight
-      expect(result.offsetX).toBe(200 + 5 + 10); // Image width + distances
+      expect(result.width).toBe(600 - 200 - 10); // baseWidth - imageWidth - distRight
+      expect(result.offsetX).toBe(200 + 10); // Image width + right-side text gap
     });
 
     it('reduces width for right-side image (wrapText=left)', () => {
@@ -258,7 +259,7 @@ describe('FloatingObjectManager', () => {
       manager.registerDrawing(imageBlock, createMockMeasure(), 100, 0, 1);
 
       const result = manager.computeAvailableWidth(120, 20, 600, 0, 1);
-      expect(result.width).toBe(600 - 200 - 5 - 10);
+      expect(result.width).toBe(600 - 200 - 5); // baseWidth - imageWidth - distLeft
       expect(result.offsetX).toBe(0); // No offset for right-side image
     });
 
@@ -554,9 +555,9 @@ describe('FloatingObjectManager', () => {
       const result = manager.computeAvailableWidth(120, 20, 600, 0, 1);
 
       // Float center is at 50, which is < 300 (baseWidth/2), so it's a left float
-      // Boundary: 0 + 100 + 5 + 10 = 115 (full exclusion width)
-      expect(result.width).toBe(600 - 115);
-      expect(result.offsetX).toBe(115);
+      // Boundary: 0 + 100 + 10 = 110 (image width + distRight)
+      expect(result.width).toBe(600 - 110);
+      expect(result.offsetX).toBe(110);
     });
 
     it('handles bothSides wrapText for float on right', () => {
@@ -583,8 +584,8 @@ describe('FloatingObjectManager', () => {
       const result = manager.computeAvailableWidth(120, 20, 600, 0, 1);
 
       // Float is at X = 600 - 100 = 500, center at 550 > 300, so it's a right float
-      // Boundary: 500 - 10 - 5 = 485 (subtract both distances for symmetry)
-      expect(result.width).toBe(485);
+      // Boundary: 500 - 10 = 490 (image left edge - distLeft)
+      expect(result.width).toBe(490);
       expect(result.offsetX).toBe(0);
     });
 
@@ -612,9 +613,9 @@ describe('FloatingObjectManager', () => {
       const result = manager.computeAvailableWidth(120, 20, 600, 0, 1);
 
       // Float on left side (center < baseWidth/2)
-      // Exclusion width: 0 + 100 + 5 + 10 = 115
-      expect(result.width).toBe(600 - 115);
-      expect(result.offsetX).toBe(115);
+      // Exclusion width: 0 + 100 + 10 = 110
+      expect(result.width).toBe(600 - 110);
+      expect(result.offsetX).toBe(110);
     });
 
     it('returns full width when all exclusions are non-wrapping', () => {