feat(drawing): improve drawing-object fidelity for picture fills, connectors, charts, and anchored media (SD-2998 and SD-2996)

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

@@ -1075,14 +1075,26 @@ export type SolidFillWithAlpha = {
   alpha: number;
 };
 
+/** Picture fill for DrawingML vector shapes. */
+export type PictureFill = {
+  type: 'picture';
+  /** Image source path or hydrated data URI. */
+  src: string;
+  /** Source relationship id from the owning document part. */
+  rId?: string;
+  /** Source image extension, used when resolving media fallbacks. */
+  extension?: string;
+};
+
 /**
  * Fill color for shapes. Can be:
  * - string: Simple hex color (e.g., "#FF0000") for backward compatibility
  * - GradientFill: Linear or radial gradient
  * - SolidFillWithAlpha: Solid color with transparency
+ * - PictureFill: Image fill clipped by the shape geometry
  * - null: No fill
  */
-export type FillColor = string | GradientFill | SolidFillWithAlpha | null;
+export type FillColor = string | GradientFill | SolidFillWithAlpha | PictureFill | null;
 
 /**
  * Stroke color for shapes. Can be:
@@ -1361,12 +1373,23 @@ export type ChartSeriesData = {
   xValues?: number[];
   /** Optional bubble radius/size values for bubble charts. */
   bubbleSizes?: number[];
+  /** Optional data-label settings from c:dLbls. */
+  dataLabels?: ChartDataLabelsConfig;
+};
+
+/** Data-label configuration extracted from c:dLbls. */
+export type ChartDataLabelsConfig = {
+  showValue?: boolean;
+  numberFormat?: string;
+  position?: string;
 };
 
 /** Axis configuration extracted from c:catAx / c:valAx. */
 export type ChartAxisConfig = {
   title?: string;
   orientation?: 'minMax' | 'maxMin';
+  deleted?: boolean;
+  majorGridlines?: boolean;
 };
 
 /** Normalized chart data model parsed from OOXML chart XML. */
@@ -1377,6 +1400,8 @@ export type ChartModel = {
   subType?: string;
   /** Bar direction — 'col' for vertical columns, 'bar' for horizontal bars. */
   barDirection?: 'col' | 'bar';
+  /** Gap width between bar groups as a percentage of bar width. */
+  gapWidth?: number;
   /** Data series in the chart. */
   series: ChartSeriesData[];
   /** Category axis config. */
@@ -1387,6 +1412,8 @@ export type ChartModel = {
   legendPosition?: string;
   /** OOXML chart style ID. */
   styleId?: number;
+  /** Whether the chart area outline should be painted. */
+  chartAreaBorder?: boolean;
 };
 
 /** Chart drawing block. */

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

@@ -5209,43 +5209,50 @@ describe('layoutHeaderFooter', () => {
     expect(imgFragWithout!.y).not.toBe(imgFragFooter!.y);
   });
 
-  it('does NOT post-normalize page-relative anchors in header layout', () => {
+  it('post-normalizes page-relative anchors in header layout', () => {
     const imageBlock: FlowBlock = {
       kind: 'image',
       id: 'img-page',
       src: 'data:image/png;base64,xxx',
       anchor: {
         isAnchored: true,
+        hRelativeFrom: 'page',
+        alignH: 'center',
         vRelativeFrom: 'page',
-        alignV: 'top',
-        offsetV: 10,
+        alignV: 'center',
+        offsetH: 0,
+        offsetV: 0,
       },
+      wrap: { type: 'None' },
     };
     const imageMeasure: Measure = {
       kind: 'image',
-      width: 50,
-      height: 30,
+      width: 762.24,
+      height: 1010.88,
     };
 
     const constraints = {
-      width: 200,
-      height: 800,
+      width: 624,
+      height: 864,
+      pageWidth: 816,
       pageHeight: 1056,
-      margins: { left: 72, right: 72, top: 72, bottom: 72, header: 36 },
+      margins: { left: 96, right: 96, top: 96, bottom: 96, header: 48 },
     };
 
-    // With kind='header': no normalization — Y stays as inner-layout computed it
     const withHeader = layoutHeaderFooter([imageBlock], [imageMeasure], constraints, 'header');
     const imgFrag = withHeader.pages[0]?.fragments.find((f) => f.kind === 'image');
 
-    // Without kind: same behavior (no normalization)
+    // Without kind: no header/footer normalization, so the inner synthetic canvas
+    // still resolves the anchor against the body-content-sized page.
     const withoutKind = layoutHeaderFooter([imageBlock], [imageMeasure], constraints);
     const imgFragNoKind = withoutKind.pages[0]?.fragments.find((f) => f.kind === 'image');
 
-    // Both should have the same Y — inner-layout raw position
     expect(imgFrag).toBeDefined();
     expect(imgFragNoKind).toBeDefined();
-    expect(imgFrag!.y).toBe(imgFragNoKind!.y);
+    expect(imgFrag!.x).toBeCloseTo((816 - 762.24) / 2);
+    expect(imgFrag!.y).toBeCloseTo((1056 - 1010.88) / 2);
+    expect(imgFragNoKind!.x).not.toBe(imgFrag!.x);
+    expect(imgFragNoKind!.y).not.toBe(imgFrag!.y);
   });
 
   it('keeps paragraph-relative tall non-page-covering header anchors in measurement height', () => {

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

@@ -3643,17 +3643,12 @@ export function layoutHeaderFooter(
     remeasureParagraph,
   });
 
-  // Post-normalize page-relative anchored fragment Y positions for footers.
+  // Post-normalize page-relative anchored fragment positions for headers/footers.
   //
-  // The inner layoutDocument() uses the body content height as its page height,
-  // but page-relative anchors need the REAL physical page height to resolve
-  // bottom/center alignment correctly. This post-correction rewrites their Y
-  // to footer-band-local coordinates using the real page geometry.
-  //
-  // Headers don't need this: the inner layout's page-relative Y is already
-  // correct relative to the header container, and the painter handles the
-  // container-to-page offset via effectiveOffset subtraction.
-  if (kind === 'footer' && constraints.pageHeight != null) {
+  // The inner layoutDocument() uses the body content box as its page canvas, but
+  // page-relative anchors need the real physical page dimensions. This
+  // post-correction rewrites their coordinates using the real page geometry.
+  if (kind && constraints.pageHeight != null) {
     normalizeFragmentsForRegion(layout.pages, blocks, measures, kind, constraints);
   }
 

packages/layout-engine/layout-engine/src/normalize-header-footer-fragments.test.ts

@@ -10,8 +10,8 @@ function makeParaFragment(blockId: string, y: number): Fragment {
   return { kind: 'para', blockId, x: 0, y, fromLine: 0, toLine: 1 } as Fragment;
 }
 
-function makeAnchoredImageFragment(blockId: string, y: number, height: number): Fragment {
-  return { kind: 'image', blockId, x: 0, y, height, isAnchored: true } as unknown as Fragment;
+function makeAnchoredImageFragment(blockId: string, y: number, height: number, width = 0): Fragment {
+  return { kind: 'image', blockId, x: 0, y, width, height, isAnchored: true } as unknown as Fragment;
 }
 
 function makeDummyMeasure(): Measure {
@@ -23,6 +23,7 @@ const MARGIN_BOTTOM = 72;
 const FOOTER_DISTANCE = 36;
 
 const fullConstraints = {
+  pageWidth: 816,
   pageHeight: PAGE_HEIGHT,
   margins: { left: 72, right: 72, top: 72, bottom: MARGIN_BOTTOM, header: 36, footer: FOOTER_DISTANCE },
 };
@@ -33,7 +34,158 @@ const FOOTER_BAND_ORIGIN = PAGE_HEIGHT - FOOTER_DISTANCE; // 1020
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('normalizeFragmentsForRegion (footer page-relative only)', () => {
+describe('normalizeFragmentsForRegion (header/footer page-relative anchors)', () => {
+  describe('page-relative anchors in header', () => {
+    it('normalizes centered page-relative anchors against the physical page', () => {
+      const imgWidth = 762.24;
+      const imgHeight = 1010.88;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-background',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'center',
+          vRelativeFrom: 'page',
+          alignV: 'center',
+          offsetH: 0,
+          offsetV: 0,
+        },
+        wrap: { type: 'None' },
+      };
+      const fragment = makeAnchoredImageFragment('header-background', 0, imgHeight, imgWidth);
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBeCloseTo((816 - imgWidth) / 2);
+      expect(fragment.y).toBeCloseTo((PAGE_HEIGHT - imgHeight) / 2);
+    });
+
+    it('normalizes right-aligned page-relative anchors against the physical page', () => {
+      const imgWidth = 120;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-logo',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'right',
+          vRelativeFrom: 'page',
+          alignV: 'top',
+          offsetH: 12,
+        },
+        wrap: { type: 'None' },
+      };
+      const fragment = makeAnchoredImageFragment('header-logo', 0, 40, imgWidth);
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBe(816 - imgWidth - 12);
+    });
+
+    it('normalizes left page-relative anchors with explicit offsets', () => {
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-left-offset',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'left',
+          vRelativeFrom: 'page',
+          alignV: 'top',
+          offsetH: 24,
+        },
+        wrap: { type: 'None' },
+      };
+      const fragment = makeAnchoredImageFragment('header-left-offset', 0, 40, 120);
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBe(24);
+    });
+
+    it('keeps normal page-relative anchors container-local on the horizontal axis', () => {
+      const imgWidth = 120;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-normal-centered',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'center',
+          vRelativeFrom: 'page',
+          alignV: 'top',
+          offsetV: 0,
+        },
+        wrap: { type: 'Square' },
+      };
+      const fragment = makeAnchoredImageFragment('header-normal-centered', 0, 40, imgWidth);
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBe((816 - imgWidth) / 2 - fullConstraints.margins.left);
+      expect(fragment.y).toBe(0);
+    });
+
+    it('keeps legacy zIndex zero page-relative anchors in physical page coordinates', () => {
+      const imgWidth = 120;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-legacy-behind',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'center',
+          vRelativeFrom: 'page',
+          alignV: 'top',
+          offsetV: 0,
+        },
+      };
+      const fragment = makeAnchoredImageFragment('header-legacy-behind', 0, 40, imgWidth);
+      (fragment as { behindDoc?: boolean }).behindDoc = undefined;
+      (fragment as { zIndex?: number }).zIndex = 0;
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBe((816 - imgWidth) / 2);
+    });
+
+    it('does not normalize column-relative X when Y is page-relative', () => {
+      const imgWidth = 830;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'header-column-background',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'column',
+          offsetH: -76,
+          vRelativeFrom: 'page',
+          alignV: 'top',
+          offsetV: 8,
+        },
+      };
+      const fragment = makeAnchoredImageFragment('header-column-background', 0, 40, imgWidth);
+      fragment.x = -76;
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'header', fullConstraints);
+
+      expect(fragment.x).toBe(-76);
+      expect(fragment.y).toBe(8);
+    });
+  });
+
   describe('page-relative anchors in footer', () => {
     it('normalizes a top-aligned anchor', () => {
       const block: FlowBlock = {
@@ -85,6 +237,55 @@ describe('normalizeFragmentsForRegion (footer page-relative only)', () => {
       expect(fragment.y).toBe((PAGE_HEIGHT - imgHeight) / 2 - FOOTER_BAND_ORIGIN);
     });
 
+    it('normalizes footer X when the vertical anchor uses page coordinates', () => {
+      const imgWidth = 120;
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'footer-centered',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'center',
+          vRelativeFrom: 'page',
+          alignV: 'bottom',
+          offsetV: 0,
+        },
+        wrap: { type: 'None' },
+      };
+      const fragment = makeAnchoredImageFragment('footer-centered', 0, 40, imgWidth);
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'footer', fullConstraints);
+
+      expect(fragment.x).toBe((816 - imgWidth) / 2);
+      expect(fragment.y).toBe(PAGE_HEIGHT - 40 - FOOTER_BAND_ORIGIN);
+    });
+
+    it('normalizes page-relative X when the vertical anchor is not page-relative', () => {
+      const block: FlowBlock = {
+        kind: 'image',
+        id: 'footer-cross-axis',
+        src: 'test.png',
+        anchor: {
+          isAnchored: true,
+          hRelativeFrom: 'page',
+          alignH: 'center',
+          vRelativeFrom: 'paragraph',
+          offsetV: 0,
+        },
+        wrap: { type: 'None' },
+      };
+      const fragment = makeAnchoredImageFragment('footer-cross-axis', 12, 40, 120);
+      fragment.x = 24;
+      const pages = [{ number: 1, fragments: [fragment] }];
+
+      normalizeFragmentsForRegion(pages, [block], [makeDummyMeasure()], 'footer', fullConstraints);
+
+      expect(fragment.x).toBe((816 - 120) / 2);
+      expect(fragment.y).toBe(12);
+    });
+
     it('applies offsetV correctly', () => {
       const block: FlowBlock = {
         kind: 'image',