@json-to-office/core-docx 3.3.0 → 4.1.0

package/dist/index.js

@@ -246,6 +246,7 @@ var init_minimal_docx_theme = __esm({
       name: "minimal",
       displayName: "Minimal Clean",
       description: "A quiet, warm minimal theme \u2014 Calibri throughout, sage-green ink on ivory neutrals, a large tracked-tight bold title, wide margins and hairline rules",
+      whenToUse: "Quiet documents where the type carries the tone: notes, briefs, drafts and internal papers that want warmth without decoration.",
       version: "4.0.0",
       colors: {
         primary: "#2B302B",
@@ -435,6 +436,7 @@ var init_devportal_docx_theme = __esm({
       name: "devportal",
       displayName: "Field Editorial",
       description: "A compact editorial theme \u2014 Helvetica in near-black ink with a burnt-orange accent, tight condensed titles, letterspaced labels, warm tinted fills and hairline rules",
+      whenToUse: "Developer and product documentation, API guides and technical handbooks: dense text, code and tables that need compact, letterspaced structure.",
       version: "4.0.0",
       colors: {
         primary: "#12191F",
@@ -633,6 +635,7 @@ var init_vermilion_docx_theme = __esm({
       name: "vermilion",
       displayName: "Vermilion Editorial",
       description: "Poster-red editorial system \u2014 vermilion display headings, ink text, warm creams and hairline rules",
+      whenToUse: "Editorial and annual-report work that wants a strong red display voice: covers, feature-style sections, reports built around a few large headings.",
       version: "1.0.0",
       colors: {
         primary: "#282829",
@@ -851,6 +854,7 @@ var init_consulting_docx_theme = __esm({
       name: "consulting",
       displayName: "Consulting House",
       description: "The house style for client and technical reports \u2014 near-black ink, three greys and one deep-blue accent, Calibri body under Arial headings, hairline rules, no fills behind body text, safe fonts only",
+      whenToUse: "Client and technical reports, memos and anything a client will read as the house's own work; the default choice for a report unless the brief names a brand.",
       version: "1.0.0",
       colors: {
         primary: "#1A1F26",
@@ -11876,8 +11880,10 @@ import {
 } from "@json-to-office/quality";
 import { DEFAULT_DOCX_RENDERER_ID as DEFAULT_DOCX_RENDERER_ID2 } from "@json-to-office/shared-docx";
 import {
+  designCanvas as designCanvas2,
   designColors as designColors2,
-  resolveDesignColor as resolveDesignColor2
+  resolveDesignColor as resolveDesignColor2,
+  typeScaleSizes
 } from "@json-to-office/shared";
 
 // src/core/generationContext.ts
@@ -12390,9 +12396,176 @@ async function expandBlocksWithPlugins(document, theme, plugins, render, preserv
 init_styleHelpers();
 init_defaults();
 init_widthUtils();
+
+// src/quality/text-inventory.ts
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
+function twipsToPt(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value / 20 : void 0;
+}
+function frameOf(props) {
+  const widthPt = twipsToPt(asRecord(props.floating)?.width);
+  return widthPt === void 0 ? void 0 : { widthPt };
+}
+function collectDocxTextInventory(children, basePath = "/children") {
+  const entries = [];
+  const add = (path4, text, role, extra = {}) => {
+    if (typeof text !== "string" || text.trim() === "") return;
+    entries.push({
+      id: `docx:text:${path4}`,
+      kind: "docx/text",
+      path: path4,
+      text,
+      role,
+      order: entries.length,
+      ...extra
+    });
+  };
+  const visitCell = (cell, path4, role, inherited) => {
+    const cellRole = inherited.repeats ? "chrome" : role;
+    const extra = inherited.repeats ? { repeats: true } : {};
+    if (typeof cell === "string") {
+      add(path4, cell, cellRole, extra);
+      return;
+    }
+    const rec = asRecord(cell);
+    if (!rec) return;
+    if ("content" in rec) {
+      if (typeof rec.content === "string")
+        add(`${path4}/content`, rec.content, cellRole, extra);
+      else {
+        const inner = asRecord(rec.content);
+        if (inner) visitNode(inner, `${path4}/content`, inherited);
+      }
+      return;
+    }
+    if (typeof rec.name === "string") visitNode(rec, path4, inherited);
+  };
+  const visitNode = (node, path4, inherited) => {
+    if (node.enabled === false) return;
+    const props = asRecord(node.props) ?? {};
+    const name = typeof node.name === "string" ? node.name : "";
+    const extra = {
+      ...inherited.repeats && { repeats: true }
+    };
+    switch (name) {
+      case "heading": {
+        if (inherited.repeats) {
+          add(`${path4}/props/text`, props.text, "chrome", extra);
+          break;
+        }
+        const level = typeof props.level === "number" && Number.isFinite(props.level) ? props.level : 1;
+        add(`${path4}/props/text`, props.text, "heading", { ...extra, level });
+        break;
+      }
+      case "paragraph": {
+        const frame = frameOf(props);
+        add(
+          `${path4}/props/text`,
+          props.text,
+          inherited.repeats ? "chrome" : "body",
+          {
+            ...extra,
+            ...frame && { frame }
+          }
+        );
+        break;
+      }
+      case "list": {
+        if (Array.isArray(props.items)) {
+          props.items.forEach((item, index) => {
+            const itemPath = `${path4}/props/items/${index}`;
+            if (typeof item === "string")
+              add(itemPath, item, "list-item", extra);
+            else {
+              const rec = asRecord(item);
+              if (rec) add(`${itemPath}/text`, rec.text, "list-item", extra);
+            }
+          });
+        }
+        break;
+      }
+      case "table": {
+        const columns = Array.isArray(props.columns) ? props.columns.map(asRecord) : [];
+        columns.forEach((column, columnIndex) => {
+          if (!column) return;
+          visitCell(
+            column.header,
+            `${path4}/props/columns/${columnIndex}/header`,
+            "table-header",
+            inherited
+          );
+        });
+        const rows = Math.max(
+          0,
+          ...columns.map(
+            (column) => Array.isArray(column?.cells) ? column.cells.length : 0
+          )
+        );
+        for (let row = 0; row < rows; row++) {
+          columns.forEach((column, columnIndex) => {
+            if (!column || !Array.isArray(column.cells)) return;
+            if (row >= column.cells.length) return;
+            visitCell(
+              column.cells[row],
+              `${path4}/props/columns/${columnIndex}/cells/${row}`,
+              "table-cell",
+              inherited
+            );
+          });
+        }
+        break;
+      }
+      case "statistic": {
+        add(`${path4}/props/number`, props.number, "statistic", extra);
+        add(`${path4}/props/description`, props.description, "statistic", extra);
+        break;
+      }
+      case "image":
+      case "chart":
+      case "highcharts":
+      case "visual":
+      case "visual-native": {
+        add(`${path4}/props/caption`, props.caption, "caption", extra);
+        break;
+      }
+      case "section": {
+        for (const part of ["header", "footer"]) {
+          const components = props[part];
+          if (!Array.isArray(components)) continue;
+          components.forEach((component, index) => {
+            const rec = asRecord(component);
+            if (rec) {
+              visitNode(rec, `${path4}/props/${part}/${index}`, {
+                repeats: true
+              });
+            }
+          });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+    if (Array.isArray(node.children)) {
+      node.children.forEach((child, index) => {
+        const rec = asRecord(child);
+        if (rec) visitNode(rec, `${path4}/children/${index}`, inherited);
+      });
+    }
+  };
+  children.forEach((child, index) => {
+    const rec = asRecord(child);
+    if (rec) visitNode(rec, `${basePath}/${index}`, {});
+  });
+  return entries;
+}
+
+// src/quality/facts.ts
+function asRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
 function pageBox(theme, themeName, pageOverride) {
   const page = createSectionProperties(
     getColumnSettings("single"),
@@ -12418,7 +12591,7 @@ function tableFact(props, path4, availableWidthTwips) {
   let percentSum = 0;
   const explicitWidths = [];
   columns.forEach((column, index) => {
-    const width = asRecord(column)?.width;
+    const width = asRecord2(column)?.width;
     if (typeof width === "number" && Number.isFinite(width)) {
       hasExplicitWidth = true;
       explicitWidths.push({ index, width });
@@ -12499,7 +12672,7 @@ function chartFact(node, props, path4, paletteTokens) {
   const categoryCount = Math.max(
     0,
     ...series.map((entry) => {
-      const record = asRecord(entry);
+      const record = asRecord2(entry);
       const labels = Array.isArray(record?.labels) ? record.labels.length : 0;
       const values = Array.isArray(record?.values) ? record.values.length : 0;
       return Math.max(labels, values);
@@ -12541,8 +12714,8 @@ function statesOwnBorders(authored) {
     return true;
   }
   const layers = [
-    asRecord(authored.cellDefaults),
-    asRecord(authored.headerCellDefaults)
+    asRecord2(authored.cellDefaults),
+    asRecord2(authored.headerCellDefaults)
   ];
   if (layers.some(
     (layer) => layer?.borderSize !== void 0 || layer?.borderColor !== void 0
@@ -12551,8 +12724,8 @@ function statesOwnBorders(authored) {
   }
   const columns = Array.isArray(authored.columns) ? authored.columns : [];
   return columns.some((column) => {
-    const record = asRecord(column);
-    const defaults = asRecord(record?.cellDefaults);
+    const record = asRecord2(column);
+    const defaults = asRecord2(record?.cellDefaults);
     return defaults?.borderSize !== void 0 || defaults?.borderColor !== void 0;
   });
 }
@@ -12576,7 +12749,7 @@ function tableDesignFact(props, path4, theme, themeName, authored) {
   );
   const columns = authoredColumns.map(
     (column, index) => {
-      const authoredColumn = asRecord(column) ?? {};
+      const authoredColumn = asRecord2(column) ?? {};
       const cells = Array.isArray(authoredColumn.cells) ? authoredColumn.cells : [];
       const alignments = /* @__PURE__ */ new Set();
       const values = [];
@@ -12595,11 +12768,11 @@ function tableDesignFact(props, path4, theme, themeName, authored) {
         },
         values,
         alignment: alignments.size === 1 ? [...alignments][0] : alignments.size === 0 ? "left" : "mixed",
-        hasCellDefaults: asRecord(authoredColumn.cellDefaults) !== void 0,
-        hasHeader: asRecord(authoredColumn.header) !== void 0,
+        hasCellDefaults: asRecord2(authoredColumn.cellDefaults) !== void 0,
+        hasHeader: asRecord2(authoredColumn.header) !== void 0,
         generated: false,
         cellsWithOwnAlignment: cells.flatMap((cell, cellIndex) => {
-          const alignment2 = asRecord(cell)?.horizontalAlignment;
+          const alignment2 = asRecord2(cell)?.horizontalAlignment;
           return typeof alignment2 === "string" && DOCX_ALIGNMENTS.has(alignment2) && alignment2 !== "right" ? [cellIndex] : [];
         })
       };
@@ -12620,7 +12793,7 @@ function finiteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function lineHeightPt(fontSizePt, spacing) {
-  const rule = asRecord(spacing);
+  const rule = asRecord2(spacing);
   const value = finiteNumber(rule?.value);
   switch (rule?.type) {
     // `exactly` is an absolute line box, and display type routinely sets it
@@ -12637,7 +12810,7 @@ function lineHeightPt(fontSizePt, spacing) {
   }
 }
 function characterSpacingPt(spacing) {
-  const rule = asRecord(spacing);
+  const rule = asRecord2(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;
@@ -12651,7 +12824,7 @@ function nodeAtPointer(root, pointer) {
       current = current[index];
       continue;
     }
-    const record = asRecord(current);
+    const record = asRecord2(current);
     if (!record) return void 0;
     current = record[token];
   }
@@ -12667,10 +12840,10 @@ function styleKey(node, props) {
   return typeof props.themeStyle === "string" && props.themeStyle !== "" ? props.themeStyle : "normal";
 }
 function effectiveFontSize(node, props, typography) {
-  const authored = finiteNumber(asRecord(props.font)?.size);
+  const authored = finiteNumber(asRecord2(props.font)?.size);
   if (authored !== void 0) return { fontSizePt: authored, authored: true };
   const { styles, theme } = typography;
-  const style = asRecord(styles[styleKey(node, props)]) ?? asRecord(styles.normal);
+  const style = asRecord2(styles[styleKey(node, props)]) ?? asRecord2(styles.normal);
   const stated = finiteNumber(style?.size);
   if (stated !== void 0) return { fontSizePt: stated, authored: false };
   const reference = style?.font === "heading" || style?.font === "body" || style?.font === "mono" || style?.font === "light" ? style.font : void 0;
@@ -12680,11 +12853,11 @@ function effectiveFontSize(node, props, typography) {
 function pinnedLineBox(props, path4) {
   const candidates = [
     [props.lineSpacing, `${path4}/props/lineSpacing`],
-    [asRecord(props.font)?.lineSpacing, `${path4}/props/font/lineSpacing`]
+    [asRecord2(props.font)?.lineSpacing, `${path4}/props/font/lineSpacing`]
   ];
   for (const [spacing, pointer] of candidates) {
     if (spacing === void 0) continue;
-    const rule = asRecord(spacing);
+    const rule = asRecord2(spacing);
     if (rule?.type !== "exactly") return void 0;
     const lineBoxPt = finiteNumber(rule.value);
     return lineBoxPt === void 0 ? void 0 : { lineBoxPt, pointer };
@@ -12710,8 +12883,8 @@ function lineBoxFact(node, props, path4, typography, authored) {
   };
 }
 function frameSignature(floating) {
-  const horizontal = asRecord(floating.horizontalPosition);
-  const vertical = asRecord(floating.verticalPosition);
+  const horizontal = asRecord2(floating.horizontalPosition);
+  const vertical = asRecord2(floating.verticalPosition);
   return JSON.stringify([
     floating.width ?? null,
     floating.height ?? null,
@@ -12721,24 +12894,24 @@ function frameSignature(floating) {
     vertical?.offset ?? null,
     vertical?.relative ?? null,
     vertical?.align ?? null,
-    asRecord(floating.wrap)?.type ?? null
+    asRecord2(floating.wrap)?.type ?? null
   ]);
 }
 function frameTextFact(props, path4, page, frameChainId, flowIndex) {
-  const floating = asRecord(props.floating);
+  const floating = asRecord2(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 font = asRecord2(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 horizontal = asRecord(floating?.horizontalPosition);
-  const vertical = asRecord(floating?.verticalPosition);
+  const horizontal = asRecord2(floating?.horizontalPosition);
+  const vertical = asRecord2(floating?.verticalPosition);
   const offsetX = finiteNumber(horizontal?.offset);
   const offsetY = finiteNumber(vertical?.offset);
   const absolutelyPinned = horizontal?.offset !== void 0 || vertical?.offset !== void 0;
@@ -12809,7 +12982,7 @@ function svgTextFacts(props, path4) {
   return facts;
 }
 function walkActive(node, path4, page, visit) {
-  const rec = asRecord(node);
+  const rec = asRecord2(node);
   if (!rec || rec.enabled === false) return;
   visit(rec, path4, page);
   const children = Array.isArray(rec.children) ? rec.children : [];
@@ -12817,6 +12990,93 @@ function walkActive(node, path4, page, visit) {
     (child, index) => walkActive(child, `${path4}/children/${index}`, page, visit)
   );
 }
+function textSizeFact(node, props, path4, typography, role) {
+  const size = effectiveFontSize(node, props, typography);
+  if (size === void 0) return void 0;
+  return {
+    id: `docx:text-size:${path4}`,
+    kind: "docx/text-size",
+    path: path4,
+    role: role ?? styleKey(node, props),
+    fontSizePt: size.fontSizePt,
+    authored: size.authored,
+    ...size.authored && { sizePath: `${path4}/props/font/size` }
+  };
+}
+function tableTextSizeFacts(props, authored, path4, typography, page) {
+  const facts = [];
+  const sizeOf = (holder) => finiteNumber(asRecord2(asRecord2(holder)?.font)?.size);
+  const authoredSize = (holder, pointer, role) => {
+    const size = sizeOf(holder);
+    if (size === void 0) return;
+    facts.push({
+      id: `docx:text-size:${pointer}`,
+      kind: "docx/text-size",
+      path: pointer,
+      role,
+      fontSizePt: size,
+      authored: true,
+      sizePath: `${pointer}/font/size`
+    });
+  };
+  const cellContent = (holder, pointer, role) => {
+    const content = asRecord2(holder)?.content;
+    if (asRecord2(content) === void 0) return;
+    walkActive(content, `${pointer}/content`, page, (node, nodePath) => {
+      if (node.name !== "paragraph" && node.name !== "heading") return;
+      const nodeProps = asRecord2(node.props) ?? {};
+      if (typeof nodeProps.text !== "string" || nodeProps.text.trim() === "")
+        return;
+      const fact = textSizeFact(node, nodeProps, nodePath, typography, role);
+      if (fact) facts.push(fact);
+    });
+  };
+  if (authored) {
+    authoredSize(
+      authored.cellDefaults,
+      `${path4}/props/cellDefaults`,
+      "tableCell"
+    );
+    authoredSize(
+      authored.headerCellDefaults,
+      `${path4}/props/headerCellDefaults`,
+      "tableHeader"
+    );
+    const columns = Array.isArray(authored.columns) ? authored.columns : [];
+    columns.forEach((column, index) => {
+      const record = asRecord2(column) ?? {};
+      const columnPath = `${path4}/props/columns/${index}`;
+      authoredSize(
+        record.cellDefaults,
+        `${columnPath}/cellDefaults`,
+        "tableCell"
+      );
+      authoredSize(record.header, `${columnPath}/header`, "tableHeader");
+      cellContent(record.header, `${columnPath}/header`, "tableHeader");
+      const cells = Array.isArray(record.cells) ? record.cells : [];
+      cells.forEach((cell, cellIndex) => {
+        authoredSize(cell, `${columnPath}/cells/${cellIndex}`, "tableCell");
+        cellContent(cell, `${columnPath}/cells/${cellIndex}`, "tableCell");
+      });
+    });
+  }
+  for (const [key, role] of [
+    ["cellDefaults", "tableCell"],
+    ["headerCellDefaults", "tableHeader"]
+  ]) {
+    const size = sizeOf(props[key]);
+    if (size === void 0) continue;
+    facts.push({
+      id: `docx:text-size:${path4}:${role}`,
+      kind: "docx/text-size",
+      path: path4,
+      role,
+      fontSizePt: size,
+      authored: false
+    });
+  }
+  return facts;
+}
 function prepareDocxQualityDocument(document, options = {}) {
   const themed = options.context ?? resolveThemeContext(normalizeDocument(document)[0], {
     customThemes: options.customThemes,
@@ -12881,11 +13141,48 @@ function prepareDocxQualityDocument(document, options = {}) {
   let inherited = {};
   topLevel.forEach((node, index) => {
     if (node?.name !== "section") return;
-    const props = asRecord(node.props) ?? {};
+    const props = asRecord2(node.props) ?? {};
     const part = (kind) => props[kind] === "linkToPrevious" ? inherited[kind] : props[kind];
     const header = part("header");
     const footer = part("footer");
     inherited = { header, footer };
+    for (const kind of ["header", "footer"]) {
+      if (!Array.isArray(props[kind])) continue;
+      const drawnByBlock = !Array.isArray(
+        asRecord2(
+          asRecord2(
+            (Array.isArray(themed.document.children) ? themed.document.children : [])[index]
+          )?.props
+        )?.[kind]
+      );
+      const part2 = props[kind];
+      const visitChrome = (child, childPath) => {
+        if (child.name !== "paragraph" && child.name !== "heading") return;
+        const childProps = asRecord2(child.props) ?? {};
+        if (typeof childProps.text !== "string" || childProps.text.trim() === "")
+          return;
+        const fact = textSizeFact(
+          child,
+          childProps,
+          childPath,
+          typography,
+          kind
+        );
+        if (fact)
+          addFact({
+            ...fact,
+            generated: drawnByBlock || authoredPath(childPath) !== childPath
+          });
+      };
+      part2.forEach(
+        (child, childIndex) => walkActive(
+          child,
+          `/children/${index}/props/${kind}/${childIndex}`,
+          basePage,
+          visitChrome
+        )
+      );
+    }
     addFact({
       id: `docx:section-chrome:${index}`,
       kind: "docx/section-chrome",
@@ -12918,13 +13215,35 @@ function prepareDocxQualityDocument(document, options = {}) {
   const paletteTokens = resolved.theme.palette?.chart?.map(
     (value) => `#${resolveDesignColor2(value, visualColors)}`
   ) ?? SERIES_COLOR_TOKENS.filter((token) => paletteHexes[token] !== void 0);
-  const authoredPropsAt = (pointer) => asRecord(asRecord(nodeAtPointer(context.document, pointer))?.props);
+  const authoredPropsAt = (pointer) => asRecord2(asRecord2(nodeAtPointer(context.document, pointer))?.props);
+  const roleSizesPt = {};
+  for (const key of Object.keys(typography.styles)) {
+    const size = effectiveFontSize(
+      { name: "paragraph" },
+      { themeStyle: key },
+      typography
+    );
+    if (size) roleSizesPt[key] = size.fontSizePt;
+  }
+  const scale = resolved.theme.typography?.scale?.[designCanvas2("docx", resolved.theme.page?.size)];
+  const typeScalePt = [
+    .../* @__PURE__ */ new Set([
+      ...Object.values(roleSizesPt),
+      ...["heading", "body", "mono", "light"].flatMap((role) => {
+        const size = resolveFontSize(resolved.theme, role);
+        return size === void 0 ? [] : [size];
+      }),
+      ...scale ? typeScaleSizes(scale) : []
+    ])
+  ].sort((a, b) => a - b);
   addFact({
     id: "docx:theme",
     kind: "docx/theme",
     path: "/props",
     themeName: context.themeName,
     paletteHexes,
+    typeScalePt,
+    roleSizesPt,
     // `heading` and `body` only. A theme also names `mono` and `light`, but
     // those paint nothing until a component asks for them — counting an
     // unused `Courier New` against a document's family budget would flag a
@@ -12932,7 +13251,7 @@ function prepareDocxQualityDocument(document, options = {}) {
     fontFamilies: [
       ...new Set(
         ["heading", "body"].flatMap((role) => {
-          const family = asRecord(
+          const family = asRecord2(
             resolved.theme.fonts?.[role]
           )?.family;
           return typeof family === "string" && family.trim() !== "" ? [family] : [];
@@ -12968,15 +13287,27 @@ function prepareDocxQualityDocument(document, options = {}) {
       excerpt: occurrence.match.excerpt
     });
   });
+  for (const entry of collectDocxTextInventory(resolved.children)) {
+    addFact({ ...entry, generated: authoredPath(entry.path) !== entry.path });
+  }
   let previousVisitPath;
   let lastFrame;
   let flowIndex = 0;
   const parentOf = (path4) => path4.slice(0, path4.lastIndexOf("/"));
   const visit = (node, path4, page) => {
-    const props = asRecord(node.props) ?? {};
+    const props = asRecord2(node.props) ?? {};
     if (node.name === "table") {
       const fact = tableFact(props, path4, page.availableWidthTwips);
       if (fact) addFact(fact);
+      for (const size of tableTextSizeFacts(
+        props,
+        authoredPropsAt(path4),
+        path4,
+        typography,
+        page
+      )) {
+        addFact({ ...size, generated: authoredPath(size.path) !== size.path });
+      }
       const design = tableDesignFact(
         props,
         path4,
@@ -12993,7 +13324,7 @@ function prepareDocxQualityDocument(document, options = {}) {
             return {
               ...column,
               path: authored,
-              generated: table2 === void 0 || asRecord(nodeAtPointer(themed.document, table2))?.name !== "table"
+              generated: table2 === void 0 || asRecord2(nodeAtPointer(themed.document, table2))?.name !== "table"
             };
           })
         });
@@ -13009,7 +13340,7 @@ function prepareDocxQualityDocument(document, options = {}) {
         addFact({
           ...fact,
           generated: !["chart", "highcharts"].includes(
-            String(asRecord(nodeAtPointer(themed.document, authored))?.name)
+            String(asRecord2(nodeAtPointer(themed.document, authored))?.name)
           ),
           seriesColorsPath: authoredPath(fact.seriesColorsPath),
           ...fact.annotation && {
@@ -13023,7 +13354,7 @@ function prepareDocxQualityDocument(document, options = {}) {
       }
     }
     if (node.name === "paragraph" || node.name === "text-box") {
-      const floating = asRecord(props.floating);
+      const floating = asRecord2(props.floating);
       if (floating) {
         const signature = frameSignature(floating);
         const chainId = lastFrame !== void 0 && previousVisitPath === lastFrame.path && parentOf(lastFrame.path) === parentOf(path4) && lastFrame.signature === signature ? lastFrame.chainId : `docx:frame-chain:${path4}`;
@@ -13035,6 +13366,10 @@ function prepareDocxQualityDocument(document, options = {}) {
     if (node.name === "paragraph" || node.name === "heading") {
       const fact = lineBoxFact(node, props, path4, typography, context.document);
       if (fact) addFact(fact);
+      if (typeof props.text === "string" && props.text.trim() !== "") {
+        const fact2 = textSizeFact(node, props, path4, typography);
+        if (fact2) addFact({ ...fact2, generated: authoredPath(path4) !== path4 });
+      }
     }
     if (node.name === "image" || node.name === "visual") {
       for (const fact of svgTextFacts(props, path4)) addFact(fact);
@@ -13607,6 +13942,7 @@ function numberParameter(parameters, name, fallback) {
 }
 var docxTableWidthRule = {
   id: "docx/table-width",
+  description: "Explicit column widths that sum past the usable width of their section.",
   code: QUALITY_CODES.TABLE_WIDTH_OVERFLOW,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13654,6 +13990,7 @@ var docxTableWidthRule = {
 };
 var docxHeadingHierarchyRule = {
   id: "docx/heading-hierarchy",
+  description: "A heading that skips a level and breaks the outline.",
   code: QUALITY_CODES.HEADING_SKIP,
   category: "hierarchy",
   defaultSeverity: "info",
@@ -13697,6 +14034,7 @@ function frameTextFacts(facts) {
 }
 var docxTextFitRule = {
   id: "docx/text-fit",
+  description: "A word too wide for its floating frame, or a frame whose wrapped text runs off the sheet.",
   code: QUALITY_CODES.TEXT_OVERFLOW,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13770,6 +14108,7 @@ var docxTextFitRule = {
 var FRAME_COLLISION_MIN_WIDTH_TWIPS = 240;
 var docxFrameCollisionRule = {
   id: "docx/frame-collision",
+  description: "Two page-anchored frames whose estimated text lands on the same region of a page.",
   code: QUALITY_CODES.FRAME_COLLISION,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13866,6 +14205,7 @@ var docxFrameCollisionRule = {
 };
 var docxSvgTextBoundsRule = {
   id: "docx/svg-text-bounds",
+  description: "A text baseline outside an inline SVG\u2019s viewBox, so the words are never painted.",
   code: QUALITY_CODES.SVG_TEXT_CLIPPED,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13901,6 +14241,7 @@ function tenths(value) {
 }
 var docxLineBoxRule = {
   id: "docx/line-box",
+  description: "An `exactly` line box shorter than the capitals it has to hold.",
   code: QUALITY_CODES.LINE_BOX_COLLAPSE,
   category: "legibility",
   defaultSeverity: "warning",
@@ -13954,6 +14295,7 @@ var docxLineBoxRule = {
 };
 var docxPlaceholderRule = {
   id: "docx/placeholder-text",
+  description: "An unfilled scaffold slot, or leftover filler copy.",
   code: QUALITY_CODES.PLACEHOLDER_TEXT,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13972,6 +14314,7 @@ var docxPlaceholderRule = {
 };
 var docxSlotBudgetRule = {
   id: "docx/slot-budget",
+  description: "A block slot holding more words than its budget allows \u2014 a takeaway past the word count the block sets.",
   code: QUALITY_CODES.SLOT_BUDGET,
   category: "composition",
   defaultSeverity: "warning",
@@ -13995,6 +14338,7 @@ var docxSlotBudgetRule = {
 var DEFAULT_MAX_FONT_FAMILIES = 3;
 var docxFontCountRule = {
   id: "docx/font-count",
+  description: "Distinct font families the document can paint.",
   code: QUALITY_CODES.FONT_COUNT,
   category: "brand",
   defaultSeverity: "warning",
@@ -14031,6 +14375,7 @@ var docxFontCountRule = {
 };
 var docxPaletteRule = {
   id: "docx/palette-adherence",
+  description: "A literal colour the resolved theme does not define.",
   code: QUALITY_CODES.OFF_PALETTE,
   category: "brand",
   defaultSeverity: "info",
@@ -14056,6 +14401,7 @@ var docxPaletteRule = {
 var DEFAULT_MAX_TABLE_ROWS_PER_PAGE = 25;
 var docxChartRule = {
   id: "docx/chart-design",
+  description: "What a chart claims about its numbers: the comparison, the palette, the unit and the caption.",
   code: QUALITY_CODES.CHART_OVERLOADED,
   category: "information-design",
   defaultSeverity: "warning",
@@ -14097,6 +14443,7 @@ function seriesColorFix(fact) {
 }
 var docxTableDesignRule = {
   id: "docx/table-design",
+  description: "How a table lays its numbers out: alignment, rounding, rules and length.",
   code: QUALITY_CODES.TABLE_NUMERIC_ALIGN,
   category: "information-design",
   defaultSeverity: "warning",
@@ -14154,6 +14501,7 @@ function stringListParameter(parameters, name) {
 }
 var docxRequiredChromeRule = {
   id: "docx/required-chrome",
+  description: "A block slot with a role a profile or policy requires \u2014 a takeaway, a source \u2014 left empty. Off until one names roles.",
   code: QUALITY_CODES.CHROME_MISSING,
   category: "consistency",
   defaultSeverity: "warning",
@@ -14177,6 +14525,7 @@ var docxRequiredChromeRule = {
 var SECTION_CHROME_PARTS = ["header", "footer", "pageNumber"];
 var docxRunningHeadRule = {
   id: "docx/running-head",
+  description: "A body section without the running head a profile or policy expects. Off until one names parts.",
   code: QUALITY_CODES.CHROME_MISSING,
   category: "consistency",
   defaultSeverity: "warning",
@@ -14209,6 +14558,170 @@ var docxRunningHeadRule = {
     });
   }
 };
+var SIZE_TOLERANCE_PT = 0.25;
+function themeFact(facts) {
+  return facts.find(
+    (fact) => fact.kind === "docx/theme"
+  );
+}
+function textSizeFacts(facts) {
+  return facts.filter(
+    (fact) => fact.kind === "docx/text-size"
+  );
+}
+function roleDriftFacts(facts, theme) {
+  const byRole = /* @__PURE__ */ new Map();
+  for (const fact of textSizeFacts(facts)) {
+    byRole.set(fact.role, [...byRole.get(fact.role) ?? [], fact]);
+  }
+  const drifting = /* @__PURE__ */ new Map();
+  for (const [role, members] of byRole) {
+    const sizes = [...new Set(members.map((fact) => fact.fontSizePt))].sort(
+      (a, b) => a - b
+    );
+    if (sizes.length < 2) continue;
+    const expected = theme?.roleSizesPt[role];
+    if (expected === void 0) continue;
+    for (const fact of members) {
+      if (fact.sizePath !== void 0 && !fact.generated && Math.abs(fact.fontSizePt - expected) > SIZE_TOLERANCE_PT)
+        drifting.set(fact, { expected, sizes });
+    }
+  }
+  return drifting;
+}
+function nearestSize(size, scale) {
+  let best;
+  for (const candidate of scale) {
+    if (best === void 0 || Math.abs(candidate - size) < Math.abs(best - size))
+      best = candidate;
+  }
+  return best;
+}
+var docxTypeScaleRule = {
+  id: "docx/type-scale",
+  description: "An authored size the theme never paints: not a style, not a font role, not a step of its scale. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_OFF_SCALE,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  evaluate: ({ facts }) => {
+    const theme = themeFact(facts);
+    const scale = theme?.typeScalePt ?? [];
+    if (scale.length === 0) return [];
+    const drifting = roleDriftFacts(facts, theme);
+    const offScale = textSizeFacts(facts).filter(
+      (fact) => fact.sizePath !== void 0 && !fact.generated && !drifting.has(fact) && !scale.some(
+        (size) => Math.abs(size - fact.fontSizePt) <= SIZE_TOLERANCE_PT
+      )
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const fact of offScale) {
+      const key = `${fact.role}@${fact.fontSizePt}`;
+      groups.set(key, [...groups.get(key) ?? [], fact]);
+    }
+    return [...groups.values()].map((members) => {
+      const [first] = members;
+      const nearest = nearestSize(first.fontSizePt, scale);
+      const sizePaths = members.map((fact) => fact.sizePath);
+      const count = members.length === 1 ? "" : ` (${members.length} places, patched together)`;
+      return {
+        path: sizePaths[0],
+        ...sizePaths.length > 1 && { relatedPaths: sizePaths.slice(1) },
+        message: `${first.fontSizePt}pt is not a size the ${theme.themeName} theme paints; the nearest on its scale is ${nearest}pt${count}.`,
+        suggestion: `Use ${nearest}pt, or drop the size and let the "${first.role}" style set it.`,
+        context: { role: first.role, scale, paths: sizePaths },
+        evidence: {
+          actual: first.fontSizePt,
+          expected: nearest,
+          unit: "pt",
+          values: { source: "theme" }
+        },
+        fixes: sizePaths.map((path4) => ({
+          op: "replace",
+          path: path4,
+          value: nearest
+        }))
+      };
+    });
+  }
+};
+var docxSizeCountRule = {
+  id: "docx/size-count",
+  description: "More distinct text sizes than maximumSizes allows, blocks included. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_SIZE_COUNT,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  defaultParameters: { maximumSizes: 8 },
+  evaluate: ({ facts, configuration, profile }) => {
+    const maximum = numberParameter(
+      configuration.parameters,
+      "maximumSizes",
+      8
+    );
+    const firstPathBySize = /* @__PURE__ */ new Map();
+    for (const fact of textSizeFacts(facts)) {
+      const size = Math.round(fact.fontSizePt * 4) / 4;
+      if (!firstPathBySize.has(size)) firstPathBySize.set(size, fact.path);
+    }
+    if (firstPathBySize.size <= maximum) return [];
+    const sizes = [...firstPathBySize.keys()].sort((a, b) => a - b);
+    return [
+      {
+        path: themeFact(facts)?.path ?? "/props",
+        relatedPaths: sizes.map((size) => firstPathBySize.get(size)),
+        message: `The document paints ${sizes.length} distinct text sizes (${sizes.join(", ")}pt); the ${profile?.id ?? "selected"} profile allows ${maximum}.`,
+        suggestion: "Keep to the theme styles \u2014 title, headings, body, label, source \u2014 and drop the ad-hoc sizes.",
+        context: { sizes, maximum },
+        evidence: {
+          actual: sizes.length,
+          expected: maximum,
+          values: { source: "profile" }
+        }
+      }
+    ];
+  }
+};
+var docxRoleDriftRule = {
+  id: "docx/role-drift",
+  description: "One heading level, table role or paragraph style painted at two sizes; the theme size is the fix. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_ROLE_DRIFT,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  evaluate: ({ facts }) => {
+    const theme = themeFact(facts);
+    const findings = [];
+    for (const [fact, { expected, sizes }] of roleDriftFacts(facts, theme)) {
+      const keeper = textSizeFacts(facts).find(
+        (member) => member.role === fact.role && Math.abs(member.fontSizePt - expected) <= SIZE_TOLERANCE_PT
+      );
+      const others = sizes.filter((size) => size !== fact.fontSizePt);
+      const sizePath = fact.sizePath;
+      findings.push({
+        path: sizePath,
+        ...keeper && { relatedPaths: [keeper.path] },
+        message: `"${fact.role}" is painted at ${fact.fontSizePt}pt here and at ${others.join("pt, ")}pt elsewhere; the theme sets it at ${expected}pt.`,
+        suggestion: `Drop the size so "${fact.role}" paints at the theme's ${expected}pt.`,
+        context: { role: fact.role, sizes },
+        evidence: {
+          actual: fact.fontSizePt,
+          expected,
+          unit: "pt",
+          values: { role: fact.role, source: "theme" }
+        },
+        fixes: [{ op: "replace", path: sizePath, value: expected }]
+      });
+    }
+    return findings;
+  }
+};
 var DOCX_QUALITY_RULES = {
   id: "docx/default",
   rules: [
@@ -14225,14 +14738,17 @@ var DOCX_QUALITY_RULES = {
     docxFontCountRule,
     docxPaletteRule,
     docxRequiredChromeRule,
-    docxRunningHeadRule
+    docxRunningHeadRule,
+    docxTypeScaleRule,
+    docxSizeCountRule,
+    docxRoleDriftRule
   ]
 };
 var DOCX_QUALITY_PROFILES = {
   "client-report": {
     id: "client-report",
     formats: ["docx"],
-    description: "Client or public-administration report: a running head with page numbers on every section after the cover, a takeaway and a source wherever a block declares them, no heading skipped.",
+    description: "Client or public-administration report: a running head with page numbers on every section after the cover, a takeaway and a source wherever a block declares them, no heading skipped, and every size on the theme scale with at most eight in play.",
     rules: {
       "docx/required-chrome": {
         parameters: { required: ["takeaway", "source"] }
@@ -14243,7 +14759,10 @@ var DOCX_QUALITY_PROFILES = {
           fromSection: 1
         }
       },
-      "docx/heading-hierarchy": { severity: "warning" }
+      "docx/heading-hierarchy": { severity: "warning" },
+      "docx/type-scale": { enabled: true },
+      "docx/size-count": { enabled: true, parameters: { maximumSizes: 8 } },
+      "docx/role-drift": { enabled: true }
     }
   },
   "executive-report": {
@@ -15975,6 +16494,7 @@ export {
   analyzeDocxQuality,
   blockSlotBudgets,
   cleanComponentProps,
+  collectDocxTextInventory,
   consultingTheme,
   createComponent,
   createDocumentGenerator,