feat: import and render document-level background

Author: VladaHarbour

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

@@ -800,6 +800,11 @@ export type PageMargins = {
   gutter?: number;
 };
 
+export type DocumentBackground = {
+  /** Solid page background color as a CSS hex value. */
+  color: string;
+};
+
 export type ImageBlockAttrs = {
   sdt?: SdtMetadata;
   containerSdt?: SdtMetadata;
@@ -2257,6 +2262,8 @@ export type HeaderFooterLayout = {
 export type Layout = {
   pageSize: { w: number; h: number };
   pages: Page[];
+  /** Optional document-level page background from OOXML w:background. */
+  documentBackground?: DocumentBackground;
   columns?: ColumnLayout;
   headerFooter?: Partial<Record<HeaderFooterType, HeaderFooterLayout>>;
   /**

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

@@ -1,6 +1,7 @@
 import type {
   ColumnLayout,
   ColumnRegion,
+  DocumentBackground,
   DrawingBlock,
   FlowMode,
   Fragment,
@@ -32,6 +33,8 @@ export type ResolvedLayout = {
   blockVersions?: Record<string, string>;
   /** Resolved pages with normalized dimensions. */
   pages: ResolvedPage[];
+  /** Optional document-level page background from OOXML w:background. */
+  documentBackground?: DocumentBackground;
   /** Document epoch identifier from the source layout. Used for change tracking in the painter. */
   layoutEpoch?: number;
 };

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

@@ -28,6 +28,7 @@ import type {
   SectionNumbering,
   FlowMode,
   NormalizedColumnLayout,
+  DocumentBackground,
 } from '@superdoc/contracts';
 import { buildLayoutSourceIdentityForFragment, normalizeColumnLayout, getFragmentZIndex } from '@superdoc/contracts';
 import { createFloatingObjectManager, computeAnchorX } from './floating-objects.js';
@@ -456,6 +457,7 @@ function calculateChainHeight(
 export type LayoutOptions = {
   pageSize?: PageSize;
   margins?: Margins;
+  documentBackground?: DocumentBackground;
   columns?: ColumnLayout;
   flowMode?: FlowMode;
   semantic?: {
@@ -3219,6 +3221,7 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
   return {
     pageSize,
     pages,
+    ...(options.documentBackground ? { documentBackground: options.documentBackground } : {}),
     // Note: columns here reflects the effective default for subsequent pages
     // after processing sections. Page/region-specific column changes are encoded
     // implicitly via fragment positions. Consumers should not assume this is

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

@@ -343,6 +343,7 @@ export function resolveLayout(input: ResolveLayoutInput): ResolvedLayout {
     flowMode,
     pageGap: layout.pageGap ?? 0,
     pages,
+    ...(layout.documentBackground ? { documentBackground: layout.documentBackground } : {}),
   };
 
   if (blocks.length > 0) {

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

@@ -431,6 +431,26 @@ describe('DomPainter', () => {
     expect(fragment.textContent).toContain('world');
   });
 
+  it('paints document-level page background from resolved layout', () => {
+    const painter = createTestPainter({ blocks: [block], measures: [measure] });
+    painter.paint({ ...layout, documentBackground: { color: '#EEEEEE' } }, mount);
+
+    const page = mount.querySelector('.superdoc-page') as HTMLElement;
+    expectCssColor(page.style.background, '#EEEEEE');
+  });
+
+  it('keeps the configured page background when no document background is present', () => {
+    const painter = createTestPainter({
+      blocks: [block],
+      measures: [measure],
+      pageStyles: { background: '#FFFFFF' },
+    });
+    painter.paint(layout, mount);
+
+    const page = mount.querySelector('.superdoc-page') as HTMLElement;
+    expectCssColor(page.style.background, '#FFFFFF');
+  });
+
   it('applies paragraph alignment to line elements', () => {
     const alignedBlock: FlowBlock = {
       kind: 'paragraph',

packages/layout-engine/painters/dom/src/renderer.ts

@@ -1201,18 +1201,19 @@ export class DomPainter {
     this.beginPaintSnapshot(resolvedLayout);
 
     this.totalPages = resolvedLayout.pages.length;
+    const previousLayout = this.currentLayout;
+    this.currentLayout = resolvedLayout;
     if (this.isSemanticFlow) {
       // Semantic mode always renders as a single continuous surface.
       applyStyles(mount, containerStyles);
       mount.style.gap = '0px';
       mount.style.alignItems = 'stretch';
-      if (!this.currentLayout || this.pageStates.length === 0) {
+      if (!previousLayout || this.pageStates.length === 0) {
         this.fullRender(resolvedLayout);
       } else {
         this.patchLayout(resolvedLayout);
       }
       this.setMountedPageIndices(this.createAllPageIndices(resolvedLayout.pages.length));
-      this.currentLayout = resolvedLayout;
       this.changedBlocks.clear();
       this.currentMapping = null;
       return;
@@ -1259,7 +1260,7 @@ export class DomPainter {
     } else {
       // Use configured page gap for normal vertical rendering
       mount.style.gap = `${this.pageGap}px`;
-      if (!this.currentLayout || this.pageStates.length === 0) {
+      if (!previousLayout || this.pageStates.length === 0) {
         this.fullRender(resolvedLayout);
       } else {
         this.patchLayout(resolvedLayout);
@@ -2475,22 +2476,26 @@ export class DomPainter {
   }
 
   private getEffectivePageStyles(): PageStyles | undefined {
+    const documentBackgroundColor = this.currentLayout?.documentBackground?.color;
+    const base = this.options.pageStyles ?? {};
+    const baseWithDocumentBackground = documentBackgroundColor
+      ? { ...base, background: documentBackgroundColor }
+      : base;
+
     if (this.isSemanticFlow) {
-      const base = this.options.pageStyles ?? {};
       return {
-        ...base,
-        background: base.background ?? 'var(--sd-layout-page-bg, #fff)',
+        ...baseWithDocumentBackground,
+        background: baseWithDocumentBackground.background ?? 'var(--sd-layout-page-bg, #fff)',
         boxShadow: 'none',
         border: 'none',
         margin: '0',
       };
     }
     if (this.virtualEnabled && this.layoutMode === 'vertical') {
       // Remove top/bottom margins to avoid double-counting with container gap during virtualization
-      const base = this.options.pageStyles ?? {};
-      return { ...base, margin: '0 auto' };
+      return { ...baseWithDocumentBackground, margin: '0 auto' };
     }
-    return this.options.pageStyles;
+    return documentBackgroundColor ? baseWithDocumentBackground : this.options.pageStyles;
   }
 
   private renderFragment(

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -191,6 +191,7 @@ import type {
   SectionMetadata,
   TrackedChangesMode,
   Fragment,
+  DocumentBackground,
 } from '@superdoc/contracts';
 import { extractHeaderFooterSpace as _extractHeaderFooterSpace } from '@superdoc/contracts';
 // TrackChangesBasePluginKey is used by #syncTrackedChangesPreferences and getTrackChangesPluginState.
@@ -7833,6 +7834,7 @@ export class PresentationEditor extends EventEmitter {
     this.#layoutOptions.pageSize = pageSize;
     this.#layoutOptions.margins = margins;
     const flowMode = this.#layoutOptions.flowMode ?? 'paginated';
+    const documentBackground = this.#resolveDocumentBackground();
 
     const resolvedMargins = {
       top: margins.top!,
@@ -7872,23 +7874,31 @@ export class PresentationEditor extends EventEmitter {
           marginBottom: semanticMargins.bottom,
         },
         sectionMetadata,
+        ...(documentBackground ? { documentBackground } : {}),
       };
     }
 
     this.#hiddenHost.style.width = `${pageSize.w}px`;
 
     const alternateHeaders = this.#resolveAlternateHeadersFlag();
-
     return {
       flowMode: 'paginated',
       pageSize,
       margins: resolvedMargins,
+      ...(documentBackground ? { documentBackground } : {}),
       ...(columns ? { columns } : {}),
       sectionMetadata,
       alternateHeaders,
     };
   }
 
+  #resolveDocumentBackground(): DocumentBackground | undefined {
+    const background = this.#editor?.state?.doc?.attrs?.documentBackground;
+    if (!background || typeof background !== 'object') return undefined;
+    const color = (background as { color?: unknown }).color;
+    return typeof color === 'string' && color.length > 0 ? { color } : undefined;
+  }
+
   #buildHeaderFooterInput() {
     if (this.#isSemanticFlowMode()) {
       return null;

packages/super-editor/src/editors/v1/core/presentation-editor/types.ts

@@ -15,6 +15,7 @@ import type {
   FlowMode,
   SectionMetadata,
   TrackChangeAuthor,
+  DocumentBackground,
 } from '@superdoc/contracts';
 import type { LayoutMode, RulerOptions } from '@superdoc/painter-dom';
 import type { ProofingConfig } from './proofing/types.js';
@@ -130,6 +131,7 @@ export type ResolvedLayoutOptions =
       pageSize: PageSize;
       margins: ResolvedMarginsBase;
       columns?: { count: number; gap: number };
+      documentBackground?: DocumentBackground;
       sectionMetadata: SectionMetadata[];
       alternateHeaders?: boolean;
     }
@@ -138,6 +140,7 @@ export type ResolvedLayoutOptions =
       pageSize: PageSize;
       margins: ResolvedMarginsBase;
       columns: { count: 1; gap: 0 };
+      documentBackground?: DocumentBackground;
       semantic: {
         contentWidth: number;
         marginLeft: number;
@@ -151,6 +154,7 @@ export type ResolvedLayoutOptions =
 export type LayoutEngineOptions = {
   pageSize?: PageSize;
   margins?: PageMargins;
+  documentBackground?: DocumentBackground;
   zoom?: number;
   virtualization?: VirtualizationOptions;
   pageStyles?: Record<string, unknown>;

packages/super-editor/src/editors/v1/core/super-converter/v2/importer/docxImporter.js

@@ -179,6 +179,23 @@ const parseTrackedChangeSourceIdMap = (raw) => {
 const readTrackedChangeSourceIdMap = (docx) =>
   parseTrackedChangeSourceIdMap(readCustomProperty(docx, TRACKED_CHANGE_SOURCE_ID_MAP_PROPERTY));
 
+const normalizeDocumentBackgroundColor = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!/^[0-9a-fA-F]{6}$/.test(trimmed)) return null;
+  return `#${trimmed.toUpperCase()}`;
+};
+
+const getDocumentBackground = (documentNode) => {
+  const background = documentNode?.elements?.find((el) => el?.name === 'w:background');
+  const color = normalizeDocumentBackgroundColor(background?.attributes?.['w:color'] ?? background?.attributes?.color);
+  if (!background || !color) return null;
+  return {
+    color,
+    originalXml: carbonCopy(background),
+  };
+};
+
 /**
  * Detect the document-level threading profile for comments based on file structure.
  * @param {ParsedDocx} docx The parsed docx object
@@ -203,6 +220,7 @@ const detectCommentThreadingProfile = (docx) => {
 export const createDocumentJson = (docx, converter, editor) => {
   const json = carbonCopy(getInitialJSON(docx));
   if (!json) return null;
+  const documentBackground = getDocumentBackground(json.elements?.[0]);
 
   if (converter) {
     importFootnotePropertiesFromSettings(docx, converter);
@@ -290,21 +308,26 @@ export const createDocumentJson = (docx, converter, editor) => {
         attributes: json.elements[0].attributes,
         // Attach body-level sectPr if it exists
         ...(bodySectPr ? { bodySectPr } : {}),
+        ...(documentBackground ? { documentBackground } : {}),
       },
     };
+    const pageStyles = getDocumentStyles(
+      node,
+      docx,
+      converter,
+      editor,
+      numbering,
+      translatedNumbering,
+      translatedLinkedStyles,
+    );
+    if (documentBackground) {
+      pageStyles.documentBackground = { color: documentBackground.color };
+    }
 
     return {
       pmDoc: result,
       savedTagsToRestore: node,
-      pageStyles: getDocumentStyles(
-        node,
-        docx,
-        converter,
-        editor,
-        numbering,
-        translatedNumbering,
-        translatedLinkedStyles,
-      ),
+      pageStyles,
       comments,
       footnotes,
       endnotes,

packages/super-editor/src/editors/v1/extensions/document/document.js

@@ -58,6 +58,15 @@ export const Document = Node.create({
          * ensuring that the last section’s page size/orientation/margins are applied correctly.
          */
       },
+      documentBackground: {
+        rendered: false,
+        default: null,
+        /**
+         * Document-level background metadata extracted from w:document > w:background.
+         * Stored separately from paragraph/table shading so page paint can apply it
+         * without changing content-level background semantics.
+         */
+      },
     };
   },