@json-to-office/core-docx 1.3.0 → 1.5.0

package/dist/index.js

@@ -428,8 +428,7 @@ var init_minimal_docx_theme = __esm({
         },
         list: {
           format: "bullet",
-          bullet: "\u2022",
-          indent: 3
+          bullet: "\u2022"
         },
         image: {
           alignment: "left"
@@ -553,8 +552,7 @@ var init_corporate_docx_theme = __esm({
         },
         list: {
           format: "bullet",
-          bullet: "\u2022",
-          indent: 3
+          bullet: "\u2022"
         },
         statistic: {
           alignment: "center"
@@ -667,8 +665,7 @@ var init_modern_docx_theme = __esm({
         },
         list: {
           format: "bullet",
-          bullet: "\u2013",
-          indent: 3
+          bullet: "\u2013"
         },
         image: {
           alignment: "center"
@@ -792,8 +789,7 @@ var init_apex_docx_theme = __esm({
         },
         list: {
           format: "bullet",
-          bullet: "\u2022",
-          indent: 3
+          bullet: "\u2022"
         },
         image: {
           alignment: "center"
@@ -925,8 +921,7 @@ var init_devportal_docx_theme = __esm({
         },
         list: {
           format: "bullet",
-          bullet: "\u2013",
-          indent: 3
+          bullet: "\u2013"
         },
         image: {
           alignment: "center"
@@ -2779,99 +2774,6 @@ var init_styles2 = __esm({
   }
 });
 
-// src/ir/features.ts
-var DOCX_FEATURES, ALL_DOCX_FEATURES;
-var init_features = __esm({
-  "src/ir/features.ts"() {
-    "use strict";
-    DOCX_FEATURES = [
-      /** Paragraphs and text runs — the floor of the format. */
-      "paragraphs",
-      /** Named paragraph and character styles in `styles.xml`. */
-      "styles",
-      /** Numbering definitions and numbered paragraphs. */
-      "numbering",
-      /** Multiple sections with their own page setup. */
-      "sections",
-      /** Multi-column section layout. */
-      "columns",
-      /** Header and footer parts, including first/even variants. */
-      "headers-footers",
-      "tables",
-      /** Merged table cells — column span or vertical merge. */
-      "table-merged-cells",
-      /** A table positioned out of the text flow. */
-      "floating-tables",
-      /** Inline images. */
-      "images",
-      /** Anchored images with text wrapping. */
-      "floating-images",
-      /** SVG images with a raster fallback. */
-      "svg-images",
-      /** A paragraph positioned as a floating frame. */
-      "text-frames",
-      /** Native shape text boxes. */
-      "text-boxes",
-      /**
-       * A DrawingML group: shapes, text boxes and pictures sharing one child
-       * coordinate space, drawn as a single anchored or inline object.
-       *
-       * Separate from `text-boxes` because a lone `wps:wsp` run is a far smaller
-       * ask than `wpg:wgp` with child transforms, preset geometry and grouped
-       * pictures — a backend can plausibly have the first and not the second.
-       */
-      "drawing-groups",
-      /**
-       * A native chart part: a `c:chartSpace` with its own embedded workbook.
-       *
-       * Separate from `images` because a chart is not a picture with extra data —
-       * it is its own part, its own relationship and its own workbook, and a
-       * backend either writes all three or writes none. docx.js has no chart
-       * primitive at all, which is what turns a `chart` component sent to that
-       * backend into a named capability error rather than a document missing a
-       * figure.
-       */
-      "charts",
-      /** A table-of-contents field. */
-      "toc",
-      /** TOC entries baked in so an unrefreshed reader still shows them. */
-      "cached-toc",
-      /** Arbitrary Word fields, e.g. PAGE, NUMPAGES, REF. */
-      "fields",
-      /** Field results cached for readers that never refresh. */
-      "cached-fields",
-      "hyperlinks",
-      "bookmarks",
-      /** Links and REF fields that target a bookmark. */
-      "cross-references",
-      "comments",
-      /** Threaded and resolvable comments. */
-      "comment-threads",
-      "footnotes",
-      "endnotes",
-      /** Inserted and deleted content. */
-      "revisions",
-      /** Page, column and line breaks. */
-      "breaks",
-      /** Paragraph and table shading. */
-      "shading",
-      /** Paragraph, table and page borders. */
-      "borders",
-      /** Tab stops. */
-      "tab-stops",
-      /** Per-run proofing language and no-proof. */
-      "proofing-language",
-      /** Custom document properties. */
-      "custom-properties",
-      /** Right-to-left paragraph direction. */
-      "rtl"
-    ];
-    ALL_DOCX_FEATURES = new Set(
-      DOCX_FEATURES
-    );
-  }
-});
-
 // src/utils/packageDocument.ts
 import AdmZip from "adm-zip";
 function resolveGenerationDate(options) {
@@ -3279,37 +3181,47 @@ function coreProperties(ir) {
     ...metadata.custom?.length ? { customProperties: metadata.custom } : {}
   };
 }
-var DOCXJS_RENDERER_ID, NOT_YET_EMITTED, DOCXJS_CAPABILITIES;
+var DOCXJS_RENDERER_ID, DOCXJS_CAPABILITIES;
 var init_docxjs = __esm({
   "src/renderers/docxjs/index.ts"() {
     "use strict";
     init_styles2();
     init_imageUtils();
-    init_features();
     init_packageDocument();
     init_fixFloatingImageIds();
     init_emit();
     init_units();
     DOCXJS_RENDERER_ID = "docxjs";
-    NOT_YET_EMITTED = /* @__PURE__ */ new Set([
-      "table-merged-cells",
-      "cached-fields",
-      "shading",
-      "borders",
-      "rtl",
-      // `drawing-groups` is the one exclusion that is a real backend gap rather
-      // than a slice boundary: docx.js has no `wpg:wgp`. Leaving it out is what
-      // turns a native `visual` sent to this backend into a named capability
-      // error instead of a document with the graphic missing.
-      "drawing-groups",
-      // `charts` is the second real backend gap: docx.js has no chart primitive at
-      // all, so a `chart` component sent here becomes a named capability error
-      // rather than a document missing a figure.
-      "charts"
+    DOCXJS_CAPABILITIES = /* @__PURE__ */ new Set([
+      "paragraphs",
+      "styles",
+      "numbering",
+      "sections",
+      "columns",
+      "headers-footers",
+      "tables",
+      "floating-tables",
+      "images",
+      "floating-images",
+      "svg-images",
+      "text-frames",
+      "text-boxes",
+      "toc",
+      "cached-toc",
+      "fields",
+      "hyperlinks",
+      "bookmarks",
+      "cross-references",
+      "comments",
+      "comment-threads",
+      "footnotes",
+      "endnotes",
+      "revisions",
+      "breaks",
+      "tab-stops",
+      "proofing-language",
+      "custom-properties"
     ]);
-    DOCXJS_CAPABILITIES = new Set(
-      [...ALL_DOCX_FEATURES].filter((feature) => !NOT_YET_EMITTED.has(feature))
-    );
   }
 });
 
@@ -4567,11 +4479,10 @@ function coreProperties2(ir) {
     ...metadata.custom?.length ? { customProperties: metadata.custom } : {}
   };
 }
-var OFFICE_OPEN_DOCX_RENDERER_ID, OFFICE_OPEN_DOCX, UNSUPPORTED, OFFICE_OPEN_CAPABILITIES;
+var OFFICE_OPEN_DOCX_RENDERER_ID, OFFICE_OPEN_DOCX, OFFICE_OPEN_CAPABILITIES;
 var init_office_open = __esm({
   "src/renderers/office-open/index.ts"() {
     "use strict";
-    init_features();
     init_chartParts();
     init_imageUtils();
     init_packageDocument();
@@ -4579,17 +4490,37 @@ var init_office_open = __esm({
     init_styles3();
     OFFICE_OPEN_DOCX_RENDERER_ID = "office-open";
     OFFICE_OPEN_DOCX = "@office-open/docx";
-    UNSUPPORTED = /* @__PURE__ */ new Set([
-      "cached-fields",
-      "comment-threads",
-      "table-merged-cells",
-      "shading",
-      "borders",
-      "rtl"
+    OFFICE_OPEN_CAPABILITIES = /* @__PURE__ */ new Set([
+      "paragraphs",
+      "styles",
+      "numbering",
+      "sections",
+      "columns",
+      "headers-footers",
+      "tables",
+      "floating-tables",
+      "images",
+      "floating-images",
+      "svg-images",
+      "text-frames",
+      "text-boxes",
+      "drawing-groups",
+      "charts",
+      "toc",
+      "cached-toc",
+      "fields",
+      "hyperlinks",
+      "bookmarks",
+      "cross-references",
+      "comments",
+      "footnotes",
+      "endnotes",
+      "revisions",
+      "breaks",
+      "tab-stops",
+      "proofing-language",
+      "custom-properties"
     ]);
-    OFFICE_OPEN_CAPABILITIES = new Set(
-      [...ALL_DOCX_FEATURES].filter((feature) => !UNSUPPORTED.has(feature))
-    );
   }
 });
 
@@ -5106,88 +5037,6 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
   return map;
 }
 
-// src/json/normalizer.ts
-function normalizeComponent(component) {
-  if (component.name === "columns") {
-    return normalizeColumnsComponent(component);
-  }
-  if ("children" in component && component.children) {
-    return {
-      ...component,
-      // Preserve ALL properties from validated component
-      children: component.children.map(normalizeComponent)
-    };
-  }
-  if (component.name === "section") {
-    return normalizeSectionComponent(component);
-  }
-  return component;
-}
-function normalizeColumnsComponent(component) {
-  const cfg = component.props || {};
-  const applyTopLevelGap = (cols, topGap) => cols.map((c, i) => {
-    const isLast = i === cols.length - 1;
-    if (!isLast && c.gap === void 0 && topGap !== void 0) {
-      return { ...c, gap: topGap };
-    }
-    return c;
-  });
-  const normalizeAutoWidth = (cols) => cols.map((c) => ({
-    ...c,
-    width: c.width === "auto" ? void 0 : c.width
-  }));
-  let columnsArray;
-  if (typeof cfg.columns === "number" && cfg.columns > 0) {
-    const n = cfg.columns;
-    const base = Array.from(
-      { length: n },
-      () => ({})
-    );
-    const topLevelGap = cfg.gap !== void 0 ? cfg.gap : "5%";
-    columnsArray = applyTopLevelGap(base, topLevelGap);
-  } else if (Array.isArray(cfg.columns)) {
-    columnsArray = cfg.columns;
-    const topLevelGap = cfg.gap !== void 0 ? cfg.gap : "5%";
-    columnsArray = applyTopLevelGap(columnsArray, topLevelGap);
-    columnsArray = normalizeAutoWidth(columnsArray);
-  } else {
-    columnsArray = [{}];
-  }
-  const normalizedProps = {
-    columns: columnsArray
-  };
-  return {
-    ...component,
-    // Preserve any additional properties
-    name: "columns",
-    props: normalizedProps,
-    children: component.children ? component.children.map(normalizeComponent) : void 0
-  };
-}
-function normalizeSectionComponent(component) {
-  const props = component.props || {};
-  return {
-    ...component,
-    // Preserve ALL properties
-    props: {
-      ...props,
-      // Preserve ALL props properties
-      header: props.header ? props.header === "linkToPrevious" ? "linkToPrevious" : props.header.map((m) => normalizeComponent(m)) : void 0,
-      footer: props.footer ? props.footer === "linkToPrevious" ? "linkToPrevious" : props.footer.map((m) => normalizeComponent(m)) : void 0
-    },
-    children: component.children ? component.children.map(normalizeComponent) : void 0
-  };
-}
-function normalizeDocument(document) {
-  if (document.name !== "docx") {
-    throw new Error(
-      'Top-level document must be a docx component with name="docx"'
-    );
-  }
-  const normalized = normalizeComponent(document);
-  return [normalized];
-}
-
 // src/core/desugarExternals.ts
 import {
   clampVisualDpi as clampVisualDpi2,
@@ -6023,6 +5872,13 @@ init_themes();
 init_colorUtils();
 init_styleHelpers();
 var RIGHT_MARGIN_TAB_TWIPS = 9026 * 2;
+var STATISTIC_NUMBER_STYLE_ID = "StatisticNumber";
+var STATISTIC_DESCRIPTION_STYLE_ID = "StatisticDescription";
+var STATISTIC_SIZE_POINTS = {
+  small: 20,
+  medium: 28,
+  large: 40
+};
 function isValidStyleName(name) {
   return [
     "normal",
@@ -6661,6 +6517,67 @@ function createDocumentStyles(themeNameOrObject = "minimal", language) {
     }
   };
 }
+function createStatisticStyles(theme) {
+  const definitions = [
+    {
+      id: STATISTIC_NUMBER_STYLE_ID,
+      name: "Statistic Number",
+      font: "heading",
+      sizePoints: STATISTIC_SIZE_POINTS.medium,
+      color: theme.colors.primary,
+      bold: true,
+      // Space above separates the figure from whatever preceded it; none below,
+      // because the description is the other half of the same block.
+      spacing: { before: 12, after: 0 },
+      next: STATISTIC_DESCRIPTION_STYLE_ID,
+      // The figure and its caption are one unit; a page break between them
+      // reads as a number with no label.
+      keepNext: true
+    },
+    {
+      id: STATISTIC_DESCRIPTION_STYLE_ID,
+      name: "Statistic Description",
+      font: "body",
+      sizePoints: 10,
+      color: theme.colors.textMuted,
+      bold: false,
+      spacing: { before: 0, after: 12 },
+      next: "Normal",
+      keepNext: false
+    }
+  ];
+  return definitions.filter(
+    (definition) => !(theme.styles && Object.prototype.hasOwnProperty.call(theme.styles, definition.id))
+  ).map((definition) => {
+    const fontProps = resolveFontProperties(theme, definition.font);
+    return {
+      id: definition.id,
+      name: definition.name,
+      basedOn: "Normal",
+      next: definition.next,
+      quickFormat: true,
+      run: {
+        fontFamily: fontProps.family || "Arial",
+        // Pinned, not inherited: the whole point of the style is that the
+        // figure is not body text, so a theme's body size must not decide it.
+        sizeHalfPoints: definition.sizePoints * 2,
+        color: { hex: resolveColor(definition.color, theme) },
+        bold: definition.bold
+      },
+      paragraph: {
+        spacing: {
+          ...resolveSpacing(definition.spacing),
+          ...irLineSpacing(fontProps.lineSpacing)
+        },
+        // Centred, matching the compiler's own alignment default — a KPI
+        // reads as a block, and an author who wants otherwise says so on the
+        // component, which overrides this on the paragraph.
+        alignment: convertAlignment("center"),
+        keepNext: definition.keepNext
+      }
+    };
+  });
+}
 
 // src/ir/compiler.ts
 init_styleHelpers();
@@ -7971,6 +7888,7 @@ function compileDocument(structure, layout, warnings = [], images = /* @__PURE__
     resourcesByHash: /* @__PURE__ */ new Map(),
     nextBookmarkId: CONTENT_BOOKMARK_ID_BASE + 1,
     bookmarkNames: /* @__PURE__ */ new Set(),
+    usesStatistic: false,
     styleIds: /* @__PURE__ */ new Set([
       ...styles.paragraph.map((s) => s.id),
       ...styles.character.map((s) => s.id)
@@ -8019,7 +7937,17 @@ function compileDocument(structure, layout, warnings = [], images = /* @__PURE__
       trackRevisions: structure.trackRevisions === true,
       ...noProofWords(structure.theme) ? { noProofWords: noProofWords(structure.theme) } : {}
     },
-    styles,
+    // The statistic styles are appended rather than built with the rest: a
+    // document that uses no statistic must keep the exact style set it had
+    // before the component had styles, or every recorded golden moves for a
+    // component the document does not contain.
+    styles: ctx.usesStatistic ? {
+      ...styles,
+      paragraph: [
+        ...styles.paragraph,
+        ...createStatisticStyles(structure.theme)
+      ]
+    } : styles,
     numbering: ctx.numbering,
     resources: ctx.resources,
     sections,
@@ -8034,6 +7962,21 @@ function compileDocument(structure, layout, warnings = [], images = /* @__PURE__
     unsupported: ctx.unsupported
   };
 }
+var AFTER_TABLE_TWIPS = 120;
+var BODY_STYLE_IDS = /* @__PURE__ */ new Set([void 0, "Normal"]);
+function separateFromTables(blocks) {
+  for (let i = 1; i < blocks.length; i += 1) {
+    const block2 = blocks[i];
+    if (blocks[i - 1].kind !== "table") continue;
+    if (block2.kind !== "paragraph") continue;
+    if (!BODY_STYLE_IDS.has(block2.styleId)) continue;
+    if (block2.formatting?.spacing?.beforeTwips !== void 0) continue;
+    block2.formatting = {
+      ...block2.formatting,
+      spacing: { ...block2.formatting?.spacing, beforeTwips: AFTER_TABLE_TWIPS }
+    };
+  }
+}
 function collectOutline(layout, warnings) {
   try {
     return collectDocumentOutline(layout.sections);
@@ -8110,6 +8053,7 @@ function compileSection(section2, index, ordinal, chrome, ctx) {
       })
     );
   });
+  separateFromTables(children);
   const compiled = {
     id: `s${index}`,
     path: path4,
@@ -8880,35 +8824,83 @@ function compileToc(component, scope) {
   });
   return blocks;
 }
+var TREND_GLYPHS = {
+  up: "\u25B2",
+  down: "\u25BC",
+  neutral: "\u2013"
+};
 function compileStatistic(component, scope) {
-  const { path: path4 } = scope;
+  const { ctx, path: path4 } = scope;
   const props = component.props ?? {};
   const alignment2 = compileAlignment(props.alignment) ?? "center";
+  ctx.usesStatistic = true;
   const spacing = props.spacing ? {
     ...props.spacing.before !== void 0 ? { beforeTwips: props.spacing.before } : {},
     ...props.spacing.after !== void 0 ? { afterTwips: props.spacing.after } : {}
   } : void 0;
-  const line = (text, styleId, suffix, formatting) => {
-    const value = normalizeUnicodeText(String(text ?? ""));
-    return {
-      kind: "paragraph",
-      id: `${scope.id}:${suffix}`,
-      path: `${path4}.${suffix}`,
-      styleId,
-      formatting,
-      // Nothing to say is not the same as saying nothing: an empty statistic
-      // line is a styled blank paragraph, with no run inside it at all.
-      children: value ? [{ kind: "text", text: value }] : []
-    };
-  };
+  if (props.format !== void 0) {
+    warnOnce(
+      ctx,
+      "statistic",
+      'statistic "format" is not implemented and was ignored \u2014 format the value yourself and pass the result as "number".',
+      "W_STATISTIC_FORMAT_IGNORED"
+    );
+  }
+  const text = (value) => normalizeUnicodeText(String(value ?? ""));
+  const numberPoints = STATISTIC_SIZE_POINTS[String(props.size)] ?? STATISTIC_SIZE_POINTS.medium;
+  const resized = numberPoints !== STATISTIC_SIZE_POINTS.medium;
+  const suffixHalfPoints = Math.max(12, Math.round(numberPoints));
+  const numberRuns = [];
+  const numberText = text(props.number);
+  if (numberText) {
+    numberRuns.push({
+      kind: "text",
+      text: numberText,
+      ...resized ? { formatting: { sizeHalfPoints: numberPoints * 2 } } : {}
+    });
+  }
+  const unitText = text(props.unit);
+  if (unitText) {
+    numberRuns.push({
+      kind: "text",
+      text: unitText,
+      formatting: { sizeHalfPoints: suffixHalfPoints }
+    });
+  }
+  const glyph = typeof props.trend === "string" ? TREND_GLYPHS[props.trend] : void 0;
+  const trendValue = text(props.trendValue);
+  if (glyph || trendValue) {
+    numberRuns.push({
+      kind: "text",
+      text: `${numberRuns.length > 0 ? " " : ""}${[glyph, trendValue].filter(Boolean).join(" ")}`,
+      formatting: {
+        sizeHalfPoints: suffixHalfPoints,
+        color: irColor(resolveColor(ctx.theme.colors.textMuted, ctx.theme))
+      }
+    });
+  }
+  const line = (children, styleId, suffix, formatting) => ({
+    kind: "paragraph",
+    id: `${scope.id}:${suffix}`,
+    path: `${path4}.${suffix}`,
+    styleId,
+    formatting,
+    // Nothing to say is not the same as saying nothing: an empty statistic
+    // line is a styled blank paragraph, with no run inside it at all.
+    children
+  });
+  const descriptionText = text(props.description);
   return [
-    line(props.number, "StatisticNumber", "number", {
+    line(numberRuns, STATISTIC_NUMBER_STYLE_ID, "number", {
       alignment: alignment2,
       ...spacing ? { spacing } : {}
     }),
-    line(props.description, "StatisticDescription", "description", {
-      alignment: alignment2
-    })
+    line(
+      descriptionText ? [{ kind: "text", text: descriptionText }] : [],
+      STATISTIC_DESCRIPTION_STYLE_ID,
+      "description",
+      { alignment: alignment2 }
+    )
   ];
 }
 function compileList(component, scope, referencePrefix = "list", explicitLevels) {
@@ -8981,12 +8973,12 @@ function compileList(component, scope, referencePrefix = "list", explicitLevels)
 }
 function itemSpacing(spacing, index, count) {
   const out = {};
-  if (index === 0 && spacing?.before) {
+  if (index === 0 && spacing?.before !== void 0) {
     out.beforeTwips = pointsToTwips2(spacing.before);
   }
-  if (index === count - 1 && spacing?.after) {
+  if (index === count - 1 && spacing?.after !== void 0) {
     out.afterTwips = pointsToTwips2(spacing.after);
-  } else if (spacing?.item) {
+  } else if (spacing?.item !== void 0) {
     out.afterTwips = pointsToTwips2(spacing.item);
   }
   return out;
@@ -10457,7 +10449,9 @@ function warnOnce(ctx, component, message, code) {
 }
 
 // src/renderers/registry.ts
-import { RendererRegistry } from "@json-to-office/shared/rendering";
+import {
+  RendererRegistry
+} from "@json-to-office/shared/rendering";
 
 // src/renderers/types.ts
 import {
@@ -10483,108 +10477,16 @@ function resolveDocxRenderer(id) {
 function docxRendererIds() {
   return registry.ids();
 }
+function docxRendererStatuses() {
+  return registry.statuses();
+}
 function isDocxRendererId(value) {
   return registry.has(value);
 }
 
 // src/core/generateFromIr.ts
 init_packageDocument();
-
-// src/core/generationContext.ts
-import { applyExportMode } from "@json-to-office/shared";
-
-// src/styles/theme-resolver.ts
-init_themes();
-function resolveBuiltInTheme(themeName, options = {}) {
-  if (!hasTheme(themeName)) {
-    const available = [
-      ...getThemeNames(),
-      ...Object.keys(options.customThemes ?? {})
-    ].sort();
-    options.warnings?.push({
-      component: "theme",
-      message: `Theme "${themeName}" not found; falling back to "minimal". Available themes: ${available.join(", ")}.`,
-      severity: "warning",
-      context: { code: "theme_not_found", requested: themeName, available }
-    });
-  }
-  return getThemeWithFallback(themeName);
-}
-
-// src/themes/overrides.ts
-function applyThemeOverrides(theme, overrides) {
-  if (!overrides) return theme;
-  const fonts = { ...theme.fonts };
-  for (const [role, def] of Object.entries(overrides.fonts ?? {})) {
-    const key = role;
-    fonts[key] = { ...theme.fonts[key], ...def };
-  }
-  const styles = { ...theme.styles ?? {} };
-  for (const [name, def] of Object.entries(overrides.styles ?? {})) {
-    styles[name] = { ...styles[name], ...def };
-  }
-  return {
-    ...theme,
-    colors: { ...theme.colors, ...overrides.colors ?? {} },
-    fonts,
-    ...Object.keys(styles).length > 0 && { styles }
-  };
-}
-
-// src/core/generationContext.ts
-function defaultNamedThemeLookup(themeName, customThemes, warnings) {
-  if (customThemes) {
-    if (customThemes[themeName]) return customThemes[themeName];
-    const themeNameLower = themeName.toLowerCase();
-    const matchingThemeKey = Object.keys(customThemes).find(
-      (key) => key.toLowerCase() === themeNameLower
-    );
-    if (matchingThemeKey) return customThemes[matchingThemeKey];
-    return resolveBuiltInTheme(themeName, { customThemes, warnings });
-  }
-  return resolveBuiltInTheme(themeName, { warnings });
-}
-function resolveThemeContext(documentIn, options = {}) {
-  const { customThemes, fonts, warnings, resolveNamedTheme } = options;
-  if (documentIn.props === null) {
-    throw new Error(
-      "Document `props` is null. Omit it, or provide an object \u2014 a null props cannot carry a theme."
-    );
-  }
-  const document = documentIn.props === void 0 ? { ...documentIn, props: {} } : documentIn;
-  const authoredThemeName = document.props.theme || void 0;
-  const baseThemeName = authoredThemeName ?? "minimal";
-  let theme = resolveNamedTheme ? resolveNamedTheme(
-    baseThemeName,
-    warnings,
-    authoredThemeName !== void 0
-  ) : defaultNamedThemeLookup(baseThemeName, customThemes, warnings);
-  const themeOverrides = document.props.themeOverrides;
-  if (themeOverrides) {
-    theme = applyThemeOverrides(theme, themeOverrides);
-  }
-  const mode = applyExportMode({ doc: document, theme, fonts });
-  for (const w of mode.warnings) {
-    if (warnings) {
-      warnings.push({
-        component: "fontRegistry",
-        message: w.message,
-        severity: "warning",
-        context: { code: w.code }
-      });
-    } else {
-      console.warn(`[json-to-docx] [${w.code}] ${w.message}`);
-    }
-  }
-  return {
-    document: mode.doc,
-    theme: mode.theme,
-    themeName: baseThemeName
-  };
-}
-
-// src/core/generateFromIr.ts
-init_generationContext();
+init_generationContext();
 
 // src/core/layout.ts
 init_styles();
@@ -11037,8 +10939,7 @@ function resolveComponentTree(components, theme) {
 }
 
 // src/core/structure.ts
-async function processDocument(document, theme, themeName, generationDate) {
-  const metadata = createDocumentMetadata(document.props, generationDate);
+function resolveDocumentTree(document, theme) {
   const docDefaults = document.props.componentDefaults;
   const mergedComponentDefaults = docDefaults ? mergeWithDefaults2(docDefaults, theme.componentDefaults || {}) : void 0;
   const docNoProofWords = document.props.noProofWords;
@@ -11052,6 +10953,14 @@ async function processDocument(document, theme, themeName, generationDate) {
     },
     ...mergedNoProofWords && { noProofWords: mergedNoProofWords }
   } : theme;
+  return {
+    theme: effectiveTheme,
+    children: resolveComponentTree(document.children || [], effectiveTheme)
+  };
+}
+async function processResolvedDocument(document, resolved, themeName, generationDate) {
+  const metadata = createDocumentMetadata(document.props, generationDate);
+  const effectiveTheme = resolved.theme;
   const context = createRenderContext(
     {
       metadata,
@@ -11062,11 +10971,7 @@ async function processDocument(document, theme, themeName, generationDate) {
     effectiveTheme,
     themeName
   );
-  const resolvedChildren = resolveComponentTree(
-    document.children || [],
-    effectiveTheme
-  );
-  const sections = await extractSections(resolvedChildren, context);
+  const sections = await extractSections(resolved.children, context);
   return {
     metadata,
     sections,
@@ -11166,6 +11071,419 @@ function createRenderContext(document, theme, themeName) {
   };
 }
 
+// src/quality/facts.ts
+import { DEFAULT_DOCX_RENDERER_ID as DEFAULT_DOCX_RENDERER_ID2 } from "@json-to-office/shared-docx";
+
+// src/core/generationContext.ts
+import { applyExportMode } from "@json-to-office/shared";
+
+// src/styles/theme-resolver.ts
+init_themes();
+function resolveBuiltInTheme(themeName, options = {}) {
+  if (!hasTheme(themeName)) {
+    const available = [
+      ...getThemeNames(),
+      ...Object.keys(options.customThemes ?? {})
+    ].sort();
+    options.warnings?.push({
+      component: "theme",
+      message: `Theme "${themeName}" not found; falling back to "minimal". Available themes: ${available.join(", ")}.`,
+      severity: "warning",
+      context: { code: "theme_not_found", requested: themeName, available }
+    });
+  }
+  return getThemeWithFallback(themeName);
+}
+
+// src/themes/overrides.ts
+function applyThemeOverrides(theme, overrides) {
+  if (!overrides) return theme;
+  const fonts = { ...theme.fonts };
+  for (const [role, def] of Object.entries(overrides.fonts ?? {})) {
+    const key = role;
+    fonts[key] = { ...theme.fonts[key], ...def };
+  }
+  const styles = { ...theme.styles ?? {} };
+  for (const [name, def] of Object.entries(overrides.styles ?? {})) {
+    styles[name] = { ...styles[name], ...def };
+  }
+  return {
+    ...theme,
+    colors: { ...theme.colors, ...overrides.colors ?? {} },
+    fonts,
+    ...Object.keys(styles).length > 0 && { styles }
+  };
+}
+
+// src/core/generationContext.ts
+function defaultNamedThemeLookup(themeName, customThemes, warnings) {
+  if (customThemes) {
+    if (customThemes[themeName]) return customThemes[themeName];
+    const themeNameLower = themeName.toLowerCase();
+    const matchingThemeKey = Object.keys(customThemes).find(
+      (key) => key.toLowerCase() === themeNameLower
+    );
+    if (matchingThemeKey) return customThemes[matchingThemeKey];
+    return resolveBuiltInTheme(themeName, { customThemes, warnings });
+  }
+  return resolveBuiltInTheme(themeName, { warnings });
+}
+function resolveThemeContext(documentIn, options = {}) {
+  const { customThemes, fonts, warnings, resolveNamedTheme } = options;
+  if (documentIn.props === null) {
+    throw new Error(
+      "Document `props` is null. Omit it, or provide an object \u2014 a null props cannot carry a theme."
+    );
+  }
+  const document = documentIn.props === void 0 ? { ...documentIn, props: {} } : documentIn;
+  const authoredThemeName = document.props.theme || void 0;
+  const baseThemeName = authoredThemeName ?? "minimal";
+  let theme = resolveNamedTheme ? resolveNamedTheme(
+    baseThemeName,
+    warnings,
+    authoredThemeName !== void 0
+  ) : defaultNamedThemeLookup(baseThemeName, customThemes, warnings);
+  const themeOverrides = document.props.themeOverrides;
+  if (themeOverrides) {
+    theme = applyThemeOverrides(theme, themeOverrides);
+  }
+  const mode = applyExportMode({ doc: document, theme, fonts });
+  for (const w of mode.warnings) {
+    if (warnings) {
+      warnings.push({
+        component: "fontRegistry",
+        message: w.message,
+        severity: "warning",
+        context: { code: w.code }
+      });
+    } else {
+      console.warn(`[json-to-docx] [${w.code}] ${w.message}`);
+    }
+  }
+  return {
+    document: mode.doc,
+    theme: mode.theme,
+    themeName: baseThemeName
+  };
+}
+
+// src/json/normalizer.ts
+function normalizeComponent(component) {
+  if (component.name === "columns") {
+    return normalizeColumnsComponent(component);
+  }
+  if ("children" in component && component.children) {
+    return {
+      ...component,
+      // Preserve ALL properties from validated component
+      children: component.children.map(normalizeComponent)
+    };
+  }
+  if (component.name === "section") {
+    return normalizeSectionComponent(component);
+  }
+  return component;
+}
+function normalizeColumnsComponent(component) {
+  const cfg = component.props || {};
+  const applyTopLevelGap = (cols, topGap) => cols.map((c, i) => {
+    const isLast = i === cols.length - 1;
+    if (!isLast && c.gap === void 0 && topGap !== void 0) {
+      return { ...c, gap: topGap };
+    }
+    return c;
+  });
+  const normalizeAutoWidth = (cols) => cols.map((c) => ({
+    ...c,
+    width: c.width === "auto" ? void 0 : c.width
+  }));
+  let columnsArray;
+  if (typeof cfg.columns === "number" && cfg.columns > 0) {
+    const n = cfg.columns;
+    const base = Array.from(
+      { length: n },
+      () => ({})
+    );
+    const topLevelGap = cfg.gap !== void 0 ? cfg.gap : "5%";
+    columnsArray = applyTopLevelGap(base, topLevelGap);
+  } else if (Array.isArray(cfg.columns)) {
+    columnsArray = cfg.columns;
+    const topLevelGap = cfg.gap !== void 0 ? cfg.gap : "5%";
+    columnsArray = applyTopLevelGap(columnsArray, topLevelGap);
+    columnsArray = normalizeAutoWidth(columnsArray);
+  } else {
+    columnsArray = [{}];
+  }
+  const normalizedProps = {
+    columns: columnsArray
+  };
+  return {
+    ...component,
+    // Preserve any additional properties
+    name: "columns",
+    props: normalizedProps,
+    children: component.children ? component.children.map(normalizeComponent) : void 0
+  };
+}
+function normalizeSectionComponent(component) {
+  const props = component.props || {};
+  return {
+    ...component,
+    // Preserve ALL properties
+    props: {
+      ...props,
+      // Preserve ALL props properties
+      header: props.header ? props.header === "linkToPrevious" ? "linkToPrevious" : props.header.map((m) => normalizeComponent(m)) : void 0,
+      footer: props.footer ? props.footer === "linkToPrevious" ? "linkToPrevious" : props.footer.map((m) => normalizeComponent(m)) : void 0
+    },
+    children: component.children ? component.children.map(normalizeComponent) : void 0
+  };
+}
+function normalizeDocument(document) {
+  if (document.name !== "docx") {
+    throw new Error(
+      'Top-level document must be a docx component with name="docx"'
+    );
+  }
+  const normalized = normalizeComponent(document);
+  return [normalized];
+}
+
+// src/quality/facts.ts
+init_widthUtils();
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function pageBox(theme, themeName, pageOverride) {
+  const page = createSectionProperties(
+    getColumnSettings("single"),
+    theme,
+    themeName,
+    "nextPage",
+    pageOverride
+  ).page;
+  return {
+    availableWidthTwips: Math.max(
+      0,
+      page.size.width - page.margin.left - page.margin.right
+    ),
+    pageBottomTwips: page.size.height
+  };
+}
+function tableFact(props, path4, availableWidthTwips) {
+  const columns = Array.isArray(props.columns) ? props.columns : void 0;
+  if (!columns) return void 0;
+  let totalWidthTwips = 0;
+  let hasExplicitWidth = false;
+  let pointSum = 0;
+  let percentSum = 0;
+  const explicitWidths = [];
+  columns.forEach((column, index) => {
+    const width = asRecord(column)?.width;
+    if (typeof width === "number" && Number.isFinite(width)) {
+      hasExplicitWidth = true;
+      explicitWidths.push({ index, width });
+      totalWidthTwips += relativeLengthToTwips(width, availableWidthTwips);
+      pointSum += width;
+    } else if (typeof width === "string") {
+      hasExplicitWidth = true;
+      const percent = width.trim().endsWith("%") ? Number(width.trim().slice(0, -1)) : Number.NaN;
+      if (Number.isFinite(percent)) {
+        explicitWidths.push({ index, width });
+        percentSum += percent;
+        totalWidthTwips += Math.max(
+          0,
+          Math.round(availableWidthTwips * percent / 100)
+        );
+      }
+    }
+  });
+  return {
+    id: `docx:table-width:${path4}`,
+    kind: "docx/table-width",
+    path: `${path4}/props/columns`,
+    totalWidthTwips,
+    availableWidthTwips,
+    hasExplicitWidth,
+    allColumnsExplicit: explicitWidths.length === columns.length,
+    pointSum,
+    percentSum,
+    explicitWidths
+  };
+}
+var TWIPS_PER_POINT3 = 20;
+var SINGLE_LINE_RATIO = 1.2;
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function lineHeightPt(fontSizePt, spacing) {
+  const rule = asRecord(spacing);
+  const value = finiteNumber(rule?.value);
+  switch (rule?.type) {
+    // `exactly` is an absolute line box, and display type routinely sets it
+    // below the font size — reading it as a multiplier would inflate every
+    // estimate on exactly the headings that matter most.
+    case "exactly":
+      return value ?? fontSizePt * SINGLE_LINE_RATIO;
+    case "atLeast":
+      return Math.max(value ?? 0, fontSizePt * SINGLE_LINE_RATIO);
+    case "multiple":
+      return fontSizePt * SINGLE_LINE_RATIO * (value ?? 1);
+    default:
+      return fontSizePt * SINGLE_LINE_RATIO;
+  }
+}
+function characterSpacingPt(spacing) {
+  const rule = asRecord(spacing);
+  const value = finiteNumber(rule?.value);
+  if (rule === void 0 || value === void 0) return 0;
+  return rule.type === "condensed" ? -value / TWIPS_PER_POINT3 : value / TWIPS_PER_POINT3;
+}
+function frameTextFact(props, path4, page) {
+  const floating = asRecord(props.floating);
+  const frameWidthTwips = finiteNumber(floating?.width);
+  if (frameWidthTwips === void 0) return void 0;
+  const text = typeof props.text === "string" ? props.text : "";
+  if (text.trim() === "") return void 0;
+  const font = asRecord(props.font);
+  const fontSizePt = finiteNumber(font?.size);
+  if (fontSizePt === void 0) return void 0;
+  const longestWord = text.split(/\s+/).reduce(
+    (longest, word) => word.length > longest.length ? word : longest,
+    ""
+  );
+  const offsetY = finiteNumber(asRecord(floating?.verticalPosition)?.offset);
+  return {
+    id: `docx:frame-text:${path4}`,
+    kind: "docx/frame-text",
+    path: path4,
+    text,
+    fontSizePt,
+    lineHeightPt: lineHeightPt(fontSizePt, font?.lineSpacing),
+    characterSpacingPt: characterSpacingPt(font?.characterSpacing),
+    frameWidthTwips,
+    ...finiteNumber(floating?.height) !== void 0 && {
+      frameHeightTwips: finiteNumber(floating?.height)
+    },
+    ...offsetY !== void 0 && { offsetYTwips: offsetY },
+    pageBottomTwips: page.pageBottomTwips,
+    longestWord
+  };
+}
+var SVG_VIEWBOX = /viewBox\s*=\s*"\s*(-?[\d.]+)[\s,]+(-?[\d.]+)[\s,]+(-?[\d.]+)[\s,]+(-?[\d.]+)\s*"/;
+var SVG_TEXT = /<text\b([^>]*)>([^<]*)<\/text>/g;
+var SVG_ATTR = (name) => new RegExp(`\\b${name}\\s*=\\s*"(-?[\\d.]+)"`);
+function svgTextFacts(props, path4) {
+  const svg = typeof props.svg === "string" ? props.svg : void 0;
+  if (!svg) return [];
+  const box = SVG_VIEWBOX.exec(svg);
+  if (!box) return [];
+  const viewBoxMinY = Number(box[2]);
+  const viewBoxHeight = Number(box[4]);
+  if (!Number.isFinite(viewBoxMinY) || !Number.isFinite(viewBoxHeight)) {
+    return [];
+  }
+  const facts = [];
+  let match;
+  SVG_TEXT.lastIndex = 0;
+  let index = 0;
+  while ((match = SVG_TEXT.exec(svg)) !== null) {
+    const [, attributes, content] = match;
+    const baselineY = Number(SVG_ATTR("y").exec(attributes)?.[1]);
+    if (!Number.isFinite(baselineY)) {
+      index += 1;
+      continue;
+    }
+    const fontSizeUnits = Number(
+      SVG_ATTR("font-size").exec(attributes)?.[1] ?? 0
+    );
+    facts.push({
+      id: `docx:svg-text:${path4}:${index}`,
+      kind: "docx/svg-text",
+      path: `${path4}/props/svg`,
+      content: content.trim(),
+      baselineY,
+      fontSizeUnits: Number.isFinite(fontSizeUnits) ? fontSizeUnits : 0,
+      viewBoxMinY,
+      viewBoxHeight
+    });
+    index += 1;
+  }
+  return facts;
+}
+function walkActive(node, path4, page, visit) {
+  const rec = asRecord(node);
+  if (!rec || rec.enabled === false) return;
+  visit(rec, path4, page);
+  const children = Array.isArray(rec.children) ? rec.children : [];
+  children.forEach(
+    (child, index) => walkActive(child, `${path4}/children/${index}`, page, visit)
+  );
+}
+function prepareDocxQualityDocument(document, options = {}) {
+  const context = options.context ?? resolveThemeContext(normalizeDocument(document)[0], {
+    customThemes: options.customThemes,
+    fonts: options.fonts,
+    warnings: options.warnings
+  });
+  const resolved = resolveDocumentTree(context.document, context.theme);
+  const basePage = pageBox(resolved.theme, context.themeName);
+  const facts = [];
+  const provenance = {};
+  let previousHeadingLevel;
+  const addFact = (fact) => {
+    facts.push(fact);
+    provenance[fact.id] = {
+      path: fact.path,
+      ...fact.relatedPaths && { relatedPaths: fact.relatedPaths }
+    };
+  };
+  const visit = (node, path4, page) => {
+    const props = asRecord(node.props) ?? {};
+    if (node.name === "table") {
+      const fact = tableFact(props, path4, page.availableWidthTwips);
+      if (fact) addFact(fact);
+    }
+    if (node.name === "paragraph" || node.name === "text-box") {
+      const fact = frameTextFact(props, path4, page);
+      if (fact) addFact(fact);
+    }
+    if (node.name === "image" || node.name === "visual") {
+      for (const fact of svgTextFacts(props, path4)) addFact(fact);
+    }
+    if (node.name === "heading") {
+      const level = typeof props.level === "number" && Number.isFinite(props.level) ? props.level : 1;
+      addFact({
+        id: `docx:heading:${path4}`,
+        kind: "docx/heading",
+        path: `${path4}/props/level`,
+        level,
+        ...previousHeadingLevel !== void 0 && {
+          previousLevel: previousHeadingLevel
+        }
+      });
+      previousHeadingLevel = level;
+    }
+  };
+  resolved.children.forEach((component, index) => {
+    const rec = component;
+    const page = rec.name === "section" ? pageBox(resolved.theme, context.themeName, rec.props?.page) : basePage;
+    walkActive(component, `/children/${index}`, page, visit);
+  });
+  return {
+    format: "docx",
+    model: {
+      authored: document,
+      context,
+      document: resolved,
+      themeName: context.themeName
+    },
+    facts,
+    provenance,
+    renderer: options.renderer ?? DEFAULT_DOCX_RENDERER_ID2
+  };
+}
+
 // src/core/generateFromIr.ts
 var UncompiledComponentError = class extends Error {
   code = "UNCOMPILED_COMPONENT";
@@ -11193,11 +11511,14 @@ async function compileDocumentToIr(document, options = {}, collector) {
   );
 }
 async function compileDocumentScoped(document, options, warnings) {
-  const context = options.context ?? resolveThemeContext(normalizeDocument(document)[0], {
+  const prepared = options.prepared ?? prepareDocxQualityDocument(document, {
     customThemes: options.customThemes,
     fonts: options.fonts,
-    warnings
+    warnings,
+    context: options.context,
+    renderer: options.renderer
   });
+  const { context } = prepared.model;
   const hasVisual = collectVisualProps(context.document).length > 0;
   const resolvedFonts = await resolveDocumentFonts(
     context.document,
@@ -11213,9 +11534,10 @@ async function compileDocumentScoped(document, options, warnings) {
     ...options.baseDir !== void 0 ? { baseDir: options.baseDir } : {},
     ...visualFonts.length > 0 ? { visualFonts } : {}
   });
-  const structure = await processDocument(
+  const resolved = desugared === context.document ? prepared.model.document : resolveDocumentTree(desugared, context.theme);
+  const structure = await processResolvedDocument(
     desugared,
-    context.theme,
+    resolved,
     context.themeName,
     resolveGenerationDate(options)
   );
@@ -11380,7 +11702,8 @@ async function generateBufferWithWarnings(jsonConfig, options) {
     ...options?.baseDir !== void 0 ? { baseDir: options.baseDir } : {},
     ...options?.deterministic !== void 0 ? { deterministic: options.deterministic } : {},
     ...options?.generatedAt !== void 0 ? { generatedAt: options.generatedAt } : {},
-    ...renderer ? { renderer } : {}
+    ...renderer ? { renderer } : {},
+    ...options?.prepared ? { prepared: options.prepared } : {}
   });
 }
 function parseDocument(jsonConfig) {
@@ -11521,6 +11844,411 @@ async function rasterizeVisual(obj, ctx) {
   });
 }
 
+// src/quality/preflight.ts
+import {
+  assertValidQualityPolicy,
+  assertValidQualityProfile
+} from "@json-to-office/quality";
+
+// src/quality/rules.ts
+import {
+  mergeQualityProfiles,
+  QUALITY_CODES,
+  QualityEngine
+} from "@json-to-office/quality";
+
+// src/quality/text-metrics.ts
+var DEFAULT_ADVANCE = 556;
+var ADVANCE = {
+  " ": 278,
+  A: 667,
+  B: 667,
+  C: 722,
+  D: 722,
+  E: 667,
+  F: 611,
+  G: 778,
+  H: 722,
+  I: 278,
+  J: 500,
+  K: 667,
+  L: 556,
+  M: 833,
+  N: 722,
+  O: 778,
+  P: 667,
+  Q: 778,
+  R: 722,
+  S: 667,
+  T: 611,
+  U: 722,
+  V: 667,
+  W: 944,
+  X: 667,
+  Y: 667,
+  Z: 611,
+  a: 556,
+  b: 556,
+  c: 500,
+  d: 556,
+  e: 556,
+  f: 278,
+  g: 556,
+  h: 556,
+  i: 222,
+  j: 222,
+  k: 500,
+  l: 222,
+  m: 833,
+  n: 556,
+  o: 556,
+  p: 556,
+  q: 556,
+  r: 333,
+  s: 500,
+  t: 278,
+  u: 556,
+  v: 500,
+  w: 722,
+  x: 500,
+  y: 500,
+  z: 500,
+  ".": 278,
+  ",": 278,
+  ":": 278,
+  ";": 278,
+  "!": 278,
+  "?": 556,
+  "'": 191,
+  '"': 355,
+  "-": 333,
+  "\u2013": 556,
+  "\u2014": 1e3,
+  "&": 667,
+  "%": 889,
+  "(": 333,
+  ")": 333,
+  "/": 278,
+  "@": 1015,
+  "#": 556,
+  "+": 584,
+  "=": 584
+};
+function estimateTextWidthPt(text, fontSizePt, trackingPt = 0) {
+  let units = 0;
+  for (const character of text) {
+    units += ADVANCE[character] ?? DEFAULT_ADVANCE;
+  }
+  const width = units / 1e3 * fontSizePt + text.length * trackingPt;
+  return Math.max(0, width);
+}
+function estimateWrappedLines(text, widthPt, fontSizePt, trackingPt = 0) {
+  if (widthPt <= 0) return 1;
+  let lines = 0;
+  for (const paragraph2 of text.split("\n")) {
+    const words = paragraph2.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+      lines += 1;
+      continue;
+    }
+    let current = "";
+    let used = 0;
+    for (const word of words) {
+      const candidate = current === "" ? word : `${current} ${word}`;
+      if (estimateTextWidthPt(candidate, fontSizePt, trackingPt) <= widthPt) {
+        current = candidate;
+      } else {
+        if (current !== "") used += 1;
+        current = word;
+      }
+    }
+    lines += used + (current === "" ? 0 : 1);
+  }
+  return Math.max(1, lines);
+}
+
+// src/quality/rules.ts
+var WIDTH_TOLERANCE_TWIPS = 10;
+function numberParameter(parameters, name, fallback) {
+  const value = parameters[name];
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+var docxTableWidthRule = {
+  id: "docx/table-width",
+  code: QUALITY_CODES.TABLE_WIDTH_OVERFLOW,
+  category: "integrity",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: { toleranceTwips: WIDTH_TOLERANCE_TWIPS },
+  evaluate: ({ facts, configuration }) => {
+    const toleranceTwips = numberParameter(
+      configuration.parameters,
+      "toleranceTwips",
+      WIDTH_TOLERANCE_TWIPS
+    );
+    return facts.filter(
+      (fact) => fact.kind === "docx/table-width"
+    ).filter(
+      (fact) => fact.hasExplicitWidth && fact.totalWidthTwips > fact.availableWidthTwips + toleranceTwips
+    ).map((fact) => {
+      const totalPt = Math.round(fact.totalWidthTwips / 20 * 10) / 10;
+      const availablePt = Math.round(fact.availableWidthTwips / 20 * 10) / 10;
+      const scale = fact.availableWidthTwips / fact.totalWidthTwips;
+      const fixes = fact.allColumnsExplicit ? fact.explicitWidths.map(({ index, width }) => ({
+        op: "replace",
+        path: `${fact.path}/${index}/width`,
+        value: typeof width === "number" ? Math.floor(width * scale * 10) / 10 : `${Math.floor(Number(width.trim().slice(0, -1)) * scale * 10) / 10}%`
+      })) : [];
+      return {
+        message: `Column widths use ${totalPt}pt, but this section has ${availablePt}pt available \u2014 the table will spill off the right edge.`,
+        path: fact.path,
+        suggestion: "Reduce fixed/percentage widths, widen the page, or leave columns unsized so they share the remainder.",
+        context: {
+          totalWidthPt: totalPt,
+          availableWidthPt: availablePt,
+          pointSum: fact.pointSum,
+          percentSum: fact.percentSum
+        },
+        evidence: {
+          actual: totalPt,
+          expected: availablePt,
+          unit: "pt"
+        },
+        ...fixes.length > 0 && { fixes }
+      };
+    });
+  }
+};
+var docxHeadingHierarchyRule = {
+  id: "docx/heading-hierarchy",
+  code: QUALITY_CODES.HEADING_SKIP,
+  category: "hierarchy",
+  defaultSeverity: "info",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  evaluate: ({ facts }) => facts.filter((fact) => fact.kind === "docx/heading").flatMap((fact) => {
+    const previousLevel = fact.previousLevel;
+    if (previousLevel === void 0 || fact.level <= previousLevel + 1) {
+      return [];
+    }
+    return [
+      {
+        message: `Heading level ${fact.level} follows level ${previousLevel} \u2014 the skipped level breaks the document outline.`,
+        path: fact.path,
+        suggestion: `Use level ${previousLevel + 1}, or promote this heading's section.`,
+        context: { level: fact.level, previousLevel },
+        evidence: {
+          actual: fact.level,
+          expected: previousLevel + 1
+        },
+        // The fact path already addresses `.../props/level`; RFC 6902
+        // `add` replaces an existing member, so this works whether the
+        // level was explicit or defaulted.
+        fixes: [
+          {
+            op: "add",
+            path: fact.path,
+            value: previousLevel + 1
+          }
+        ]
+      }
+    ];
+  })
+};
+var WIDTH_MODEL_TOLERANCE = 1.08;
+var TWIPS_PER_POINT4 = 20;
+function frameTextFacts(facts) {
+  return facts.filter(
+    (fact) => fact.kind === "docx/frame-text"
+  );
+}
+var docxTextFitRule = {
+  id: "docx/text-fit",
+  code: QUALITY_CODES.TEXT_OVERFLOW,
+  category: "integrity",
+  defaultSeverity: "warning",
+  defaultCertainty: "estimated",
+  formats: ["docx"],
+  defaultParameters: { widthTolerance: WIDTH_MODEL_TOLERANCE },
+  evaluate: ({ facts, configuration }) => {
+    const tolerance = numberParameter(
+      configuration.parameters,
+      "widthTolerance",
+      WIDTH_MODEL_TOLERANCE
+    );
+    const findings = [];
+    for (const fact of frameTextFacts(facts)) {
+      const frameWidthPt = fact.frameWidthTwips / TWIPS_PER_POINT4;
+      const longestWordPt = estimateTextWidthPt(
+        fact.longestWord,
+        fact.fontSizePt,
+        fact.characterSpacingPt
+      );
+      if (longestWordPt > frameWidthPt * tolerance) {
+        findings.push({
+          message: `"${fact.longestWord}" is estimated at ${Math.round(longestWordPt)}pt in a ${Math.round(frameWidthPt)}pt frame \u2014 with no wrap point it will break mid-word.`,
+          path: `${fact.path}/props/floating/width`,
+          suggestion: "Widen the frame, reduce fontSize, or condense the run further.",
+          context: {
+            longestWord: fact.longestWord,
+            estimatedWidthPt: Math.round(longestWordPt),
+            frameWidthPt: Math.round(frameWidthPt),
+            fontSizePt: fact.fontSizePt
+          },
+          evidence: {
+            actual: Math.round(longestWordPt),
+            expected: Math.round(frameWidthPt),
+            unit: "pt"
+          }
+        });
+        continue;
+      }
+      if (fact.offsetYTwips === void 0) continue;
+      const lines = estimateWrappedLines(
+        fact.text,
+        frameWidthPt,
+        fact.fontSizePt,
+        fact.characterSpacingPt
+      );
+      const heightTwips = lines * fact.lineHeightPt * TWIPS_PER_POINT4;
+      const bottomTwips = fact.offsetYTwips + heightTwips;
+      const overrunTwips = bottomTwips - fact.pageBottomTwips;
+      if (overrunTwips <= fact.lineHeightPt * TWIPS_PER_POINT4) continue;
+      findings.push({
+        message: `Frame starts at ${fact.offsetYTwips} twips and needs ${Math.round(heightTwips)} more for ${lines} line${lines === 1 ? "" : "s"} of ${fact.fontSizePt}pt \u2014 it runs ${Math.round(overrunTwips)} twips past the page, so the text breaks onto the next one.`,
+        path: `${fact.path}/props/floating/verticalPosition/offset`,
+        suggestion: "Raise the frame, shorten the text, or reduce fontSize so the block finishes on the page.",
+        context: {
+          offsetYTwips: fact.offsetYTwips,
+          estimatedHeightTwips: Math.round(heightTwips),
+          pageBottomTwips: fact.pageBottomTwips,
+          lines
+        },
+        evidence: {
+          actual: Math.round(bottomTwips),
+          expected: fact.pageBottomTwips,
+          unit: "twips"
+        }
+      });
+    }
+    return findings;
+  }
+};
+var docxSvgTextBoundsRule = {
+  id: "docx/svg-text-bounds",
+  code: QUALITY_CODES.SVG_TEXT_CLIPPED,
+  category: "integrity",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  evaluate: ({ facts }) => facts.filter((fact) => fact.kind === "docx/svg-text").flatMap((fact) => {
+    const canvasBottom = fact.viewBoxMinY + fact.viewBoxHeight;
+    if (fact.baselineY <= canvasBottom) return [];
+    const overflow = Math.round((fact.baselineY - canvasBottom) * 10) / 10;
+    return [
+      {
+        message: `SVG text "${fact.content}" sits ${overflow} units below the viewBox \u2014 it is clipped away and never reaches the document's text layer.`,
+        path: fact.path,
+        suggestion: `Move the baseline above ${Math.round(canvasBottom)}, or grow the viewBox height.`,
+        context: {
+          content: fact.content,
+          baselineY: fact.baselineY,
+          canvasBottom,
+          overflowUnits: overflow
+        },
+        evidence: {
+          actual: fact.baselineY,
+          expected: canvasBottom,
+          unit: "viewBox units"
+        }
+      }
+    ];
+  })
+};
+var DOCX_QUALITY_RULES = {
+  id: "docx/default",
+  rules: [
+    docxTableWidthRule,
+    docxHeadingHierarchyRule,
+    docxTextFitRule,
+    docxSvgTextBoundsRule
+  ]
+};
+var DOCX_QUALITY_PROFILES = {
+  "executive-report": {
+    id: "executive-report",
+    formats: ["docx"],
+    description: "Short decision document with strict outline continuity.",
+    rules: {
+      "docx/heading-hierarchy": { severity: "warning" }
+    }
+  },
+  "technical-report": {
+    id: "technical-report",
+    formats: ["docx"],
+    description: "Portable professional report defaults."
+  },
+  "legal-appendix": {
+    id: "legal-appendix",
+    formats: ["docx"],
+    description: "Dense appendix: preserve integrity without editorial taste."
+  }
+};
+var DOCX_DEFAULT_QUALITY_PROFILE = DOCX_QUALITY_PROFILES["technical-report"];
+var DOCX_PROFILES_BY_ID = DOCX_QUALITY_PROFILES;
+function resolveDocxQualityProfile(requested) {
+  if (!requested) return void 0;
+  const registered = DOCX_PROFILES_BY_ID[requested.id];
+  if (!registered) return requested;
+  return mergeQualityProfiles(registered, requested);
+}
+var docxQualityEngine = new QualityEngine(DOCX_QUALITY_RULES.rules);
+
+// src/quality/preflight.ts
+var PREPARE_RULE_ID = "quality/prepare";
+function emptyAnalysis(ruleErrors = [], blocked = false) {
+  return {
+    diagnostics: [],
+    counts: { error: 0, warning: 0, info: 0 },
+    blocked,
+    truncated: false,
+    suppressedCount: 0,
+    evaluatedRuleIds: [],
+    ruleErrors
+  };
+}
+function analyzeDocxQuality(doc, options = {}) {
+  assertValidQualityPolicy(options.policy);
+  assertValidQualityProfile(options.profile);
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc) || doc.name !== "docx") {
+    return emptyAnalysis();
+  }
+  let prepared = options.prepared;
+  try {
+    prepared ??= prepareDocxQualityDocument(
+      doc,
+      options
+    );
+  } catch (error) {
+    if (options.policy?.onRuleError === "throw") throw error;
+    const gate = options.policy?.gate;
+    return emptyAnalysis(
+      [
+        {
+          ruleId: PREPARE_RULE_ID,
+          message: error instanceof Error ? error.message : String(error)
+        }
+      ],
+      gate !== void 0 && gate !== "none"
+    );
+  }
+  return docxQualityEngine.analyzeSync(prepared, {
+    profile: resolveDocxQualityProfile(options.profile) ?? DOCX_DEFAULT_QUALITY_PROFILE,
+    policy: options.policy
+  });
+}
+
 // src/utils/warningsDocument.ts
 function generateWarningsDocument(warnings) {
   if (!warnings || warnings.length === 0) {
@@ -12447,18 +13175,24 @@ export {
   ComponentValidationError2 as ComponentValidationError,
   DocumentGenerator as CoreDocumentGenerator,
   DEFAULT_DOCX_RENDERER_ID,
+  DOCX_DEFAULT_QUALITY_PROFILE,
+  DOCX_QUALITY_PROFILES,
+  DOCX_QUALITY_RULES,
   ThemeFileError,
   ThemeParseError,
   ThemeValidationError,
   UncompiledComponentError,
   UnknownPreservedComponentError,
+  analyzeDocxQuality,
   cleanComponentProps,
   corporateTheme,
   createComponent,
   createDocumentGenerator,
   createMinimalTheme,
   createVersion,
+  docxQualityEngine,
   docxRendererIds,
+  docxRendererStatuses,
   examples,
   exportPluginSchema,
   exportThemeToJson,
@@ -12499,7 +13233,9 @@ export {
   mergeSchemas,
   minimalTheme,
   modernTheme,
+  prepareDocxQualityDocument,
   resetVisualPrepassStats,
+  resolveDocxQualityProfile,
   runExample,
   themes,
   validateComponentProps,