@json-to-office/core-docx 2.7.0 → 3.0.0

package/dist/index.js

@@ -8454,641 +8454,6 @@ function emptyToUndefined(formatting) {
   return entries.length === 0 ? void 0 : Object.fromEntries(entries);
 }
 
-// src/blocks/index.ts
-import {
-  COVER_BUDGET,
-  KEY_TAKEAWAYS_BUDGET,
-  RUNNING_HEAD_BUDGET,
-  SECTION_OPENER_BUDGET
-} from "@json-to-office/shared-docx";
-
-// src/blocks/cover.ts
-init_widthUtils();
-
-// src/blocks/recipe.ts
-var MIN_RULE_PT = 0.25;
-var MAX_RULE_PT = 12;
-function clampRule(weightPt) {
-  return Math.min(MAX_RULE_PT, Math.max(MIN_RULE_PT, weightPt));
-}
-var FALLBACK_EYEBROW_FONT = {
-  size: 9,
-  bold: true,
-  color: "accent",
-  case: "upper"
-};
-function hasStyle(theme, role) {
-  const styles = theme.styles;
-  return styles?.[role] !== void 0;
-}
-function roleProps(theme, role, fallbackFont, color) {
-  if (hasStyle(theme, role)) {
-    return {
-      themeStyle: role,
-      ...color !== void 0 && { font: { color } }
-    };
-  }
-  return { font: { ...fallbackFont, ...color !== void 0 && { color } } };
-}
-
-// src/blocks/cover.ts
-var DROP_SHARE = 0.3;
-var DROP_SHARE_WITH_LOGO = 0.22;
-var DEFAULT_LOGO_WIDTH = "25%";
-var FALLBACK = {
-  ruleWeightPt: 3,
-  ruleColor: "accent",
-  padPt: 12,
-  metaFont: { size: 9, color: "textSecondary" }
-};
-function compileCover(props, theme) {
-  const recipe = theme.chrome?.cover;
-  const ruleWeightPt = recipe?.rule?.weightPt ?? FALLBACK.ruleWeightPt;
-  const padPt = recipe?.padPt ?? FALLBACK.padPt;
-  const heightPt = getAvailableHeightTwips(theme) / 20;
-  const dropPt = Math.round(
-    heightPt * (props.logo ? DROP_SHARE_WITH_LOGO : DROP_SHARE)
-  );
-  const children = [];
-  const sourceMap = {};
-  const emit = (child, slots) => {
-    const index = children.push(child) - 1;
-    sourceMap[`/children/${index}`] = "";
-    for (const [emitted, authored] of Object.entries(slots)) {
-      sourceMap[`/children/${index}${emitted}`] = authored;
-    }
-  };
-  if (props.logo) {
-    const { width, height, ...source } = props.logo;
-    emit(
-      {
-        name: "image",
-        props: {
-          ...source,
-          width: width ?? DEFAULT_LOGO_WIDTH,
-          ...height !== void 0 && { height },
-          alignment: theme.chrome?.logoSlot?.alignment ?? "left",
-          spacing: { before: 0, after: 0 }
-        }
-      },
-      { "/props": "/props/logo" }
-    );
-  }
-  const drawsRule = ruleWeightPt > 0;
-  if (drawsRule) {
-    emit(
-      {
-        name: "divider",
-        props: {
-          thickness: clampRule(ruleWeightPt),
-          color: recipe?.rule?.color ?? FALLBACK.ruleColor,
-          spacing: { before: dropPt, after: padPt }
-        }
-      },
-      {}
-    );
-  }
-  let dropPending = !drawsRule;
-  const before = () => {
-    if (!dropPending) return {};
-    dropPending = false;
-    return { before: dropPt };
-  };
-  if (props.client) {
-    emit(
-      {
-        name: "paragraph",
-        props: {
-          text: props.client,
-          keepNext: true,
-          spacing: { ...before(), after: 4 },
-          ...roleProps(theme, "eyebrow", FALLBACK_EYEBROW_FONT)
-        }
-      },
-      { "/props/text": "/props/client" }
-    );
-  }
-  const titleRole = recipe?.type && hasStyle(theme, recipe.type) ? recipe.type : "title";
-  emit(
-    {
-      name: "paragraph",
-      props: {
-        text: props.title,
-        keepNext: true,
-        ...dropPending && { spacing: before() },
-        ...roleProps(theme, titleRole, { size: 26, bold: true }, recipe?.color)
-      }
-    },
-    { "/props/text": "/props/title" }
-  );
-  if (props.subtitle) {
-    emit(
-      {
-        name: "paragraph",
-        props: {
-          text: props.subtitle,
-          keepNext: true,
-          ...roleProps(theme, "subtitle", { size: 13, color: "textSecondary" })
-        }
-      },
-      { "/props/text": "/props/subtitle" }
-    );
-  }
-  const meta = [props.date, props.confidentiality].filter(
-    (part) => typeof part === "string" && part !== ""
-  );
-  if (meta.length > 0) {
-    emit(
-      {
-        name: "paragraph",
-        props: {
-          text: meta.join("  \xB7  "),
-          spacing: { before: padPt, after: 0 },
-          ...roleProps(theme, "label", FALLBACK.metaFont)
-        }
-      },
-      {
-        "/props/text": props.date ? "/props/date" : "/props/confidentiality"
-      }
-    );
-  }
-  return { children, sourceMap };
-}
-
-// src/blocks/keyTakeaways.ts
-var KEY_TAKEAWAYS_DEFAULT_LABEL = "Key takeaways";
-var FALLBACK_RECIPE = {
-  ruleWeightPt: 1.5,
-  ruleColor: "accent",
-  padPt: 6,
-  type: "label"
-};
-function compileKeyTakeaways(props, theme) {
-  const recipe = theme.chrome?.keyTakeaways;
-  const labelRole = recipe?.type ?? FALLBACK_RECIPE.type;
-  const labelStyle = hasStyle(theme, labelRole);
-  const ruleWeightPt = clampRule(
-    recipe?.rule?.weightPt ?? FALLBACK_RECIPE.ruleWeightPt
-  );
-  const ruleColor = recipe?.rule?.color ?? recipe?.color ?? FALLBACK_RECIPE.ruleColor;
-  const padPt = recipe?.padPt ?? FALLBACK_RECIPE.padPt;
-  const children = [
-    {
-      name: "divider",
-      props: {
-        thickness: ruleWeightPt,
-        color: ruleColor,
-        spacing: { before: 12, after: padPt }
-      }
-    },
-    {
-      name: "paragraph",
-      props: {
-        text: props.label ?? KEY_TAKEAWAYS_DEFAULT_LABEL,
-        keepNext: true,
-        spacing: { after: 4 },
-        // The label role when the theme resolves one; a bold run in the
-        // recipe's colour otherwise, so the label still reads as a label.
-        ...labelStyle ? { themeStyle: labelRole } : {
-          font: {
-            bold: true,
-            ...recipe?.color !== void 0 && { color: recipe.color }
-          }
-        }
-      }
-    },
-    {
-      name: "list",
-      props: { items: [...props.items] }
-    },
-    {
-      name: "divider",
-      props: {
-        thickness: 0.5,
-        color: "borderPrimary",
-        spacing: { before: padPt, after: 12 }
-      }
-    }
-  ];
-  return {
-    children,
-    sourceMap: {
-      "/children/0": "",
-      "/children/1": "",
-      "/children/1/props/text": "/props/label",
-      "/children/2": "",
-      "/children/2/props/items": "/props/items",
-      "/children/3": ""
-    }
-  };
-}
-
-// src/blocks/runningHead.ts
-init_styles();
-init_widthUtils();
-var FALLBACK2 = {
-  headFont: { size: 8, color: "textMuted", case: "upper" },
-  footFont: { size: 8, color: "textMuted" },
-  ruleWeightPt: 0.5,
-  ruleColor: "border"
-};
-var PAGE_OF_TOTAL = "{PAGE} / {TOTAL_PAGES}";
-function sectionMeasureTwips(theme, page) {
-  if (!page || page.size === void 0 && page.margins === void 0) {
-    return getAvailableWidthTwips(theme);
-  }
-  const width = page.size ? getPageDimensions(page.size).width : getPageDimensions(theme.page.size).width;
-  const margins = getDocumentMargins(theme);
-  const left = page.margins?.left ?? margins.left ?? 1440;
-  const right = page.margins?.right ?? margins.right ?? 1440;
-  return Math.max(0, width - left - right);
-}
-function compileRunningHead(props, theme, scope) {
-  const measure = sectionMeasureTwips(theme, scope.page);
-  const head = theme.chrome?.runningHead;
-  const foot = theme.chrome?.confidentialFooter;
-  const slot = (name) => props[name] !== void 0 ? `${scope.block}/props/${name}` : void 0;
-  const header = [];
-  const headerMap = {};
-  const title = props.title ?? scope.documentTitle ?? "";
-  const tracker = scope.opener?.text ?? props.tracker ?? "";
-  if (title !== "" || tracker !== "") {
-    const both = title !== "" && tracker !== "";
-    header.push({
-      name: "paragraph",
-      props: {
-        text: both ? `${title}	${tracker}` : title || tracker,
-        ...both ? { tabStops: [{ type: "right", position: measure }] } : { alignment: title !== "" ? "left" : head?.alignment ?? "right" },
-        spacing: { before: 0, after: 0 },
-        ...roleProps(
-          theme,
-          head?.type ?? "tracker",
-          FALLBACK2.headFont,
-          head?.color
-        )
-      }
-    });
-    headerMap["/0"] = scope.block;
-    headerMap["/0/props/text"] = (tracker !== "" ? scope.opener?.slot ?? slot("tracker") : slot("title")) ?? scope.block;
-  }
-  const headRule = head?.rule?.weightPt ?? FALLBACK2.ruleWeightPt;
-  if (headRule > 0) {
-    header.push({
-      name: "divider",
-      props: {
-        thickness: clampRule(headRule),
-        color: head?.rule?.color ?? FALLBACK2.ruleColor,
-        spacing: { before: 2, after: 0 }
-      }
-    });
-    headerMap[`/${header.length - 1}`] = scope.block;
-  }
-  const footer = [];
-  const footerMap = {};
-  const footRule = foot?.rule?.weightPt ?? FALLBACK2.ruleWeightPt;
-  if (footRule > 0) {
-    footer.push({
-      name: "divider",
-      props: {
-        thickness: clampRule(footRule),
-        color: foot?.rule?.color ?? FALLBACK2.ruleColor,
-        spacing: { before: 0, after: 4 }
-      }
-    });
-    footerMap["/0"] = scope.block;
-  }
-  const parts = [
-    props.confidentiality ?? "",
-    props.pageNumbers === false ? "" : PAGE_OF_TOTAL,
-    props.date ?? ""
-  ];
-  const present = parts.filter((part) => part !== "");
-  if (present.length > 0) {
-    const single = present.length === 1;
-    const alignment2 = present[0] === PAGE_OF_TOTAL ? "center" : foot?.alignment ?? "left";
-    footer.push({
-      name: "paragraph",
-      props: {
-        text: single ? present[0] : parts.join("	").replace(/\t+$/, ""),
-        ...single ? { alignment: alignment2 } : {
-          tabStops: [
-            { type: "center", position: Math.round(measure / 2) },
-            { type: "right", position: measure }
-          ]
-        },
-        spacing: { before: 0, after: 0 },
-        ...roleProps(
-          theme,
-          foot?.type ?? "footer",
-          FALLBACK2.footFont,
-          foot?.color
-        )
-      }
-    });
-    const index = footer.length - 1;
-    footerMap[`/${index}`] = scope.block;
-    footerMap[`/${index}/props/text`] = slot("confidentiality") ?? slot("date") ?? scope.block;
-  }
-  return {
-    header: { children: header, sourceMap: headerMap },
-    footer: { children: footer, sourceMap: footerMap }
-  };
-}
-
-// src/blocks/sectionOpener.ts
-function compileSectionOpener(props, theme) {
-  const children = [];
-  const sourceMap = {};
-  const pageBreak = props.pageBreak === true;
-  if (props.number !== void 0) {
-    children.push({
-      name: "paragraph",
-      props: {
-        text: String(props.number),
-        keepNext: true,
-        spacing: { after: 2 },
-        ...pageBreak && { pageBreak: true },
-        ...roleProps(theme, "eyebrow", FALLBACK_EYEBROW_FONT)
-      }
-    });
-    sourceMap["/children/0"] = "";
-    sourceMap["/children/0/props/text"] = "/props/number";
-  }
-  const index = children.length;
-  children.push({
-    name: "heading",
-    props: {
-      text: props.title,
-      level: 1,
-      ...pageBreak && index === 0 && { pageBreak: true }
-    }
-  });
-  sourceMap[`/children/${index}`] = "";
-  sourceMap[`/children/${index}/props/text`] = "/props/title";
-  return { children, sourceMap };
-}
-function sectionTracker(section2) {
-  if (!Array.isArray(section2.children)) return void 0;
-  for (const [index, child] of section2.children.entries()) {
-    if (typeof child !== "object" || child === null || child.name !== "section-opener" || child.enabled === false) {
-      continue;
-    }
-    const props = child.props;
-    if (!props) continue;
-    if (typeof props.tracker === "string" && props.tracker !== "") {
-      return { text: props.tracker, slot: `/children/${index}/props/tracker` };
-    }
-    if (typeof props.title === "string" && props.title !== "") {
-      return { text: props.title, slot: `/children/${index}/props/title` };
-    }
-  }
-  return void 0;
-}
-
-// src/blocks/index.ts
-var BLOCK_NAMES = [
-  "key-takeaways",
-  "cover",
-  "section-opener",
-  "running-head"
-];
-function slotBudget(block2, props, pointer, slot, maxWords) {
-  const value = props[slot];
-  return typeof value === "string" ? [
-    {
-      block: block2,
-      slot,
-      path: `${pointer}/props/${slot}`,
-      words: wordCount(value),
-      maxWords
-    }
-  ] : [];
-}
-function budgetsOf(block2, budget) {
-  return (props, pointer) => Object.entries(budget).flatMap(
-    ([slot, { maxWords }]) => slotBudget(block2, props, pointer, slot, maxWords)
-  );
-}
-var BLOCKS = {
-  "key-takeaways": {
-    kind: "flow",
-    compile: (props, theme) => compileKeyTakeaways(props, theme),
-    budgets: (props, pointer) => (Array.isArray(props.items) ? props.items : []).flatMap(
-      (item, index) => typeof item === "string" ? [
-        {
-          block: "key-takeaways",
-          slot: "items",
-          path: `${pointer}/props/items/${index}`,
-          words: wordCount(item),
-          maxWords: KEY_TAKEAWAYS_BUDGET.items.maxWords
-        }
-      ] : []
-    )
-  },
-  cover: {
-    kind: "flow",
-    compile: (props, theme) => compileCover(props, theme),
-    budgets: budgetsOf("cover", COVER_BUDGET)
-  },
-  "section-opener": {
-    kind: "flow",
-    compile: (props, theme) => compileSectionOpener(props, theme),
-    budgets: budgetsOf("section-opener", SECTION_OPENER_BUDGET)
-  },
-  "running-head": {
-    kind: "chrome",
-    budgets: budgetsOf("running-head", RUNNING_HEAD_BUDGET)
-  }
-};
-function isBlockName(name) {
-  return BLOCK_NAMES.includes(name);
-}
-function isChromeBlockName(name) {
-  return isBlockName(name) && BLOCKS[name].kind === "chrome";
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-var SECTION_CHILD = /^\/children\/\d+\/children\/\d+$/;
-var SECTION = /^\/children\/(\d+)$/;
-function planChrome(document, theme) {
-  const plans = /* @__PURE__ */ new Map();
-  if (!isRecord(document) || document.name !== "docx" || !Array.isArray(document.children)) {
-    return plans;
-  }
-  const metadata = isRecord(document.props) ? document.props.metadata : void 0;
-  const documentTitle = isRecord(metadata) && typeof metadata.title === "string" ? metadata.title : void 0;
-  let inForce;
-  document.children.forEach((section2, index) => {
-    if (!isRecord(section2) || section2.name !== "section" || section2.enabled === false) {
-      return;
-    }
-    const sectionPointer = `/children/${index}`;
-    const children = Array.isArray(section2.children) ? section2.children : [];
-    children.forEach((child, childIndex) => {
-      if (isRecord(child) && isChromeBlockName(child.name) && child.enabled !== false) {
-        inForce = {
-          block: `${sectionPointer}/children/${childIndex}`,
-          props: isRecord(child.props) ? child.props : {}
-        };
-      }
-    });
-    if (!inForce) return;
-    const opener = sectionTracker(section2);
-    const sectionProps = isRecord(section2.props) ? section2.props : {};
-    plans.set(
-      index,
-      compileRunningHead(inForce.props, theme, {
-        block: inForce.block,
-        documentTitle,
-        ...opener && {
-          opener: {
-            text: opener.text,
-            slot: `${sectionPointer}${opener.slot}`
-          }
-        },
-        ...isRecord(sectionProps.page) && {
-          page: sectionProps.page
-        }
-      })
-    );
-  });
-  return plans;
-}
-function expandBlocks(document, theme) {
-  const sourceMap = {};
-  const blocks = [];
-  const chrome = planChrome(document, theme);
-  const walk2 = (node, pointer) => {
-    if (Array.isArray(node)) {
-      return node.map((child, index) => walk2(child, `${pointer}/${index}`));
-    }
-    if (!isRecord(node)) return node;
-    if (typeof node.name === "string" && node.enabled !== false && isBlockName(node.name)) {
-      const definition = BLOCKS[node.name];
-      if (definition.kind === "chrome") {
-        if (!SECTION_CHILD.test(pointer)) return node;
-        blocks.push(pointer);
-        return { ...node, children: [] };
-      }
-      if (isRecord(node.props)) {
-        const compiled = definition.compile(node.props, theme);
-        blocks.push(pointer);
-        for (const [emitted, authored] of Object.entries(compiled.sourceMap)) {
-          sourceMap[`${pointer}${emitted}`] = `${pointer}${authored}`;
-        }
-        return { ...node, children: compiled.children };
-      }
-    }
-    const next = { ...node };
-    if (isRecord(node.props)) {
-      const props = { ...node.props };
-      let changed = false;
-      for (const key of ["header", "footer"]) {
-        if (Array.isArray(props[key])) {
-          props[key] = walk2(props[key], `${pointer}/props/${key}`);
-          changed = true;
-        }
-      }
-      if (Array.isArray(props.columns)) {
-        props.columns = props.columns.map((column, index) => {
-          if (!isRecord(column)) return column;
-          const base = `${pointer}/props/columns/${index}`;
-          const out = { ...column };
-          if (isRecord(column.header) && "content" in column.header) {
-            out.header = {
-              ...column.header,
-              content: walk2(column.header.content, `${base}/header/content`)
-            };
-          }
-          if (Array.isArray(column.cells)) {
-            out.cells = column.cells.map(
-              (cell, cellIndex) => isRecord(cell) && "content" in cell ? {
-                ...cell,
-                content: walk2(
-                  cell.content,
-                  `${base}/cells/${cellIndex}/content`
-                )
-              } : cell
-            );
-          }
-          return out;
-        });
-        changed = true;
-      }
-      if (changed) next.props = props;
-    }
-    if (Array.isArray(node.children)) {
-      next.children = walk2(node.children, `${pointer}/children`);
-    }
-    const section2 = SECTION.exec(pointer);
-    if (section2 && node.name === "section" && node.enabled !== false) {
-      const plan = chrome.get(Number(section2[1]));
-      if (plan) {
-        const props = isRecord(next.props) ? { ...next.props } : {};
-        let changed = false;
-        for (const part of ["header", "footer"]) {
-          const { children, sourceMap: partMap } = plan[part];
-          if (props[part] !== void 0 || children.length === 0) continue;
-          props[part] = children;
-          changed = true;
-          const base = `${pointer}/props/${part}`;
-          sourceMap[base] = partMap["/0"] ?? pointer;
-          for (const [emitted, authored] of Object.entries(partMap)) {
-            sourceMap[`${base}${emitted}`] = authored;
-          }
-        }
-        if (props.pageBreak === void 0) {
-          props.pageBreak = true;
-          changed = true;
-        }
-        if (changed) next.props = props;
-      }
-    }
-    return next;
-  };
-  const expanded = walk2(document, "");
-  return {
-    document: blocks.length > 0 ? expanded : document,
-    sourceMap,
-    blocks
-  };
-}
-function toAuthoredPointer(sourceMap, pointer) {
-  let best;
-  for (const emitted of Object.keys(sourceMap)) {
-    if ((pointer === emitted || pointer.startsWith(`${emitted}/`)) && (best === void 0 || emitted.length > best.length)) {
-      best = emitted;
-    }
-  }
-  if (best === void 0) return pointer;
-  return `${sourceMap[best]}${pointer.slice(best.length)}`;
-}
-function blockSlotBudgets(document, blocks) {
-  return blocks.flatMap((pointer) => {
-    const node = nodeAt(document, pointer);
-    if (!isRecord(node) || !isRecord(node.props) || !isBlockName(node.name)) {
-      return [];
-    }
-    return BLOCKS[node.name].budgets(node.props, pointer);
-  });
-}
-function wordCount(text) {
-  const trimmed = text.trim();
-  return trimmed === "" ? 0 : trimmed.split(/\s+/).length;
-}
-function nodeAt(root, pointer) {
-  if (pointer === "") return root;
-  let current = root;
-  for (const segment of pointer.slice(1).split("/")) {
-    const key = segment.replace(/~1/g, "/").replace(/~0/g, "~");
-    if (Array.isArray(current)) current = current[Number(key)];
-    else if (isRecord(current)) current = current[key];
-    else return void 0;
-  }
-  return current;
-}
-
 // src/ir/compiler.ts
 init_types();
 init_units();
@@ -9514,7 +8879,7 @@ function compileComponent(component, scope) {
     case "table":
       return compileTable(component, scope);
     default:
-      if (isBlockName(component.name)) {
+      if (component.name === "group") {
         if (component.enabled === false) return [];
         return compileBlock(component, scope);
       }
@@ -12719,6 +12084,204 @@ function normalizeDocument(document) {
   return [normalized];
 }
 
+// src/blocks/document.ts
+init_styles();
+init_widthUtils();
+import {
+  JsonBlockEvaluator,
+  BlockEvaluationError,
+  composeBlocksWithPlugins,
+  readBlockDefinitions,
+  blockValueAt,
+  isBlockRecord,
+  toAuthoredBlockPointer
+} from "@json-to-office/shared";
+import { blockSlotBudgets } from "@json-to-office/shared";
+import { validateDocument } from "@json-to-office/shared-docx";
+var toAuthoredPointer = toAuthoredBlockPointer;
+function docxBlockContext(document, theme, path4 = "") {
+  const index = /^\/children\/(\d+)/.exec(path4)?.[1];
+  const section2 = index === void 0 ? void 0 : blockValueAt(document, `/children/${index}`);
+  const page = isBlockRecord(section2) && isBlockRecord(section2.props) && isBlockRecord(section2.props.page) ? section2.props.page : {};
+  const margins = getDocumentMargins(theme);
+  const dimensions = getPageDimensions(
+    page.size ?? theme.page.size
+  );
+  const overrides = isBlockRecord(page.margins) ? page.margins : {};
+  const width = Object.keys(page).length ? Math.max(
+    0,
+    dimensions.width - Number(overrides.left ?? margins.left ?? 1440) - Number(overrides.right ?? margins.right ?? 1440)
+  ) : getAvailableWidthTwips(theme);
+  const height = Object.keys(page).length ? Math.max(
+    0,
+    dimensions.height - Number(overrides.top ?? margins.top ?? 1440) - Number(overrides.bottom ?? margins.bottom ?? 1440)
+  ) : getAvailableHeightTwips(theme);
+  return {
+    document: blockValueAt(document, "/props/metadata") ?? {},
+    page: { width, height },
+    section: {}
+  };
+}
+function createDocxBlockEvaluator(document, theme, extra = {}) {
+  return new JsonBlockEvaluator(readBlockDefinitions(document), {
+    format: "docx",
+    theme,
+    contextAt: (path4) => docxBlockContext(document, theme, path4),
+    contextSources: { "/document": "/props/metadata" },
+    measure: (axis, unit, context) => Number(blockValueAt(context, `/page/${axis}`)) / (unit === "twip" ? 1 : unit === "in" ? 1440 : 20),
+    ...extra
+  });
+}
+function expandBlocks(document, theme) {
+  const effects = [];
+  const evaluator = createDocxBlockEvaluator(document, theme, {
+    onSection: (effect) => effects.push(effect)
+  });
+  const expanded = evaluator.expand(document);
+  return finishDocxBlocks(expanded, document, theme, evaluator, effects);
+}
+function validateEffects(document, effects) {
+  for (const effect of effects) {
+    const parts = effect.path.split("/").slice(1);
+    const section2 = blockValueAt(document, "/" + parts.slice(0, 2).join("/"));
+    let valid = parts.length >= 4 && parts[0] === "children" && parts[2] === "children" && isBlockRecord(section2) && section2.name === "section";
+    for (let i = 4; i < parts.length; i += 2) {
+      const parent = blockValueAt(document, "/" + parts.slice(0, i).join("/"));
+      valid &&= parts[i] === "children" && isBlockRecord(parent) && parent.name === "group";
+    }
+    if (!valid)
+      throw new BlockEvaluationError([
+        {
+          path: effect.environment.source,
+          code: "invalid_placement",
+          message: "Section effects require a block in a top-level section body, optionally nested in transparent groups."
+        }
+      ]);
+  }
+}
+function finishDocxBlocks(expanded, document, theme, evaluator, effects, validate = true) {
+  if (isBlockRecord(expanded) && Array.isArray(expanded.children)) {
+    let inherited;
+    expanded.children.forEach((section2, index) => {
+      if (!isBlockRecord(section2) || section2.name !== "section" || section2.enabled === false)
+        return;
+      const path4 = `/children/${index}`;
+      const local = effects.filter(
+        (e) => e.path.startsWith(`${path4}/children/`)
+      );
+      let tracker;
+      let trackerSource = path4;
+      for (const effect of local) {
+        if (effect.settings.tracker !== void 0) {
+          tracker = evaluator.evaluate(
+            effect.settings.tracker,
+            effect.environment,
+            `${path4}/props/tracker`,
+            `${effect.environment.definition}/section/tracker`
+          );
+          trackerSource = toAuthoredPointer(
+            evaluator.sourceMap,
+            `${path4}/props/tracker`
+          );
+        }
+      }
+      let chrome = inherited;
+      for (const effect of local) {
+        if (effect.settings.header !== void 0 || effect.settings.footer !== void 0) {
+          chrome = effect;
+          if (effect.settings.scope === "following") inherited = effect;
+        }
+      }
+      const props = isBlockRecord(section2.props) ? { ...section2.props } : {};
+      if (chrome) {
+        const environment = {
+          ...chrome.environment,
+          context: {
+            ...docxBlockContext(document, theme, path4),
+            section: { tracker }
+          },
+          contextSources: {
+            "/document": "/props/metadata",
+            "/section/tracker": trackerSource
+          }
+        };
+        for (const part of ["header", "footer"]) {
+          if (props[part] !== void 0 || chrome.settings[part] === void 0)
+            continue;
+          const compiled = evaluator.evaluate(
+            chrome.settings[part],
+            environment,
+            `${path4}/props/${part}`,
+            `${environment.definition}/section/${part}`
+          );
+          props[part] = evaluator.expand(compiled, `${path4}/props/${part}`);
+        }
+        if (props.pageBreak === void 0)
+          props.pageBreak = chrome.settings.pageBreak ?? true;
+      }
+      for (const effect of local)
+        if (effect.settings.pageBreak !== void 0 && props.pageBreak === void 0)
+          props.pageBreak = effect.settings.pageBreak;
+      section2.props = props;
+    });
+  }
+  validateEffects(expanded, effects);
+  if (evaluator.blocks.length && validate) {
+    const result = validateDocument(expanded);
+    if (!result.valid)
+      throw new BlockEvaluationError(
+        result.errors.map((issue) => ({
+          path: toAuthoredPointer(evaluator.sourceMap, issue.path),
+          code: issue.code ?? "block_invalid_output",
+          message: issue.message
+        }))
+      );
+  }
+  return {
+    document: expanded,
+    sourceMap: evaluator.sourceMap,
+    blocks: evaluator.blocks
+  };
+}
+async function expandBlocksWithPlugins(document, theme, plugins, render, preserve = /* @__PURE__ */ new Set()) {
+  const effects = [];
+  const evaluator = createDocxBlockEvaluator(document, theme, {
+    reservedNames: [...plugins],
+    onSection: (effect) => effects.push(effect)
+  });
+  const walk2 = (value) => composeBlocksWithPlugins(evaluator, value, {
+    plugins,
+    render,
+    preserve
+  });
+  const first = await walk2(document);
+  const finished = finishDocxBlocks(
+    first.standard,
+    document,
+    theme,
+    evaluator,
+    effects,
+    false
+  );
+  const second = await walk2(finished.document);
+  validateEffects(second.standard, effects);
+  const result = validateDocument(second.standard);
+  if (!result.valid)
+    throw new BlockEvaluationError(
+      result.errors.map((issue) => ({
+        path: toAuthoredPointer(evaluator.sourceMap, issue.path),
+        code: issue.code ?? "block_invalid_output",
+        message: issue.message
+      }))
+    );
+  return {
+    document: second.standard,
+    preserved: first.preserved,
+    sourceMap: evaluator.sourceMap,
+    blocks: evaluator.blocks
+  };
+}
+
 // src/quality/facts.ts
 init_styleHelpers();
 init_defaults();
@@ -13161,7 +12724,10 @@ function prepareDocxQualityDocument(document, options = {}) {
   const facts = [];
   const provenance = {};
   let previousHeadingLevel;
-  const authoredPath = (path4) => toAuthoredPointer(expanded.sourceMap, path4);
+  const authoredPath = (path4) => toAuthoredPointer(
+    themed.sourceMap ?? {},
+    toAuthoredPointer(expanded.sourceMap, path4)
+  );
   const addFact = (raw) => {
     const fact = {
       ...raw,
@@ -13176,7 +12742,7 @@ function prepareDocxQualityDocument(document, options = {}) {
       ...fact.relatedPaths && { relatedPaths: fact.relatedPaths }
     };
   };
-  for (const budget of blockSlotBudgets(context.document, expanded.blocks)) {
+  for (const budget of blockSlotBudgets(themed.document, expanded.blocks)) {
     addFact({
       id: `docx:block-slot:${budget.path}`,
       kind: "docx/block-slot",
@@ -13326,11 +12892,19 @@ function prepareDocxQualityDocument(document, options = {}) {
     facts,
     provenance,
     renderer: options.renderer ?? DEFAULT_DOCX_RENDERER_ID2,
-    ...expanded.blocks.length > 0 && {
+    ...(expanded.blocks.length > 0 || (themed.blockPaths?.length ?? 0) > 0) && {
       metadata: {
         blocks: {
-          sourceMap: expanded.sourceMap,
-          blocks: expanded.blocks,
+          sourceMap: {
+            ...themed.sourceMap,
+            ...Object.fromEntries(
+              Object.entries(expanded.sourceMap).map(([key, value]) => [
+                key,
+                toAuthoredPointer(themed.sourceMap ?? {}, value)
+              ])
+            )
+          },
+          blocks: [...themed.blockPaths ?? [], ...expanded.blocks],
           document: context.document
         }
       }
@@ -14760,7 +14334,7 @@ function validateComponentProps(schema, props, componentName, opts) {
     componentName
   });
 }
-function validateDocument(document, customComponents, options) {
+function validateDocument2(document, customComponents, options) {
   const knownCustomNames = new Set(customComponents.map((c) => c.name));
   const documentResult = validateDocumentUnified(document, {
     knownCustomNames,
@@ -15164,7 +14738,7 @@ function createBuilderImpl(state) {
       ...options?.validation
     };
     if (vOpts.enabled !== false) {
-      const result = validateDocument(
+      const result = validateDocument2(
         validationDocument,
         state.components,
         { allowUnknownFields: vOpts.allowUnknownFields }
@@ -15179,12 +14753,12 @@ function createBuilderImpl(state) {
         );
       }
     }
-    const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel) => {
-      const result = validateDocument(
+    const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel, sourcePath) => {
+      const result = validateDocument2(
         {
           ...internalDocument,
           ...renderer !== void 0 ? { renderer } : {},
-          children: emitted
+          children: sourcePath === void 0 ? emitted : [{ name: "section", props: {}, children: emitted }]
         },
         state.components,
         { allowUnknownFields: vOpts.allowUnknownFields }
@@ -15192,7 +14766,10 @@ function createBuilderImpl(state) {
       if (!result.valid) {
         throw new ComponentValidationError2(
           (result.errors ?? []).map((e) => ({
-            path: e.path ?? "",
+            path: sourcePath === void 0 ? e.path ?? "" : (e.path ?? "").replace(
+              /^\/children\/0\/children\/\d+/,
+              sourcePath
+            ),
             message: `custom component '${componentLabel}' emitted invalid output \u2014 ${e.message}`
           })),
           emitted
@@ -15210,6 +14787,62 @@ function createBuilderImpl(state) {
       warnings,
       resolveNamedTheme: resolveDocumentTheme
     });
+    if (modedRoot.props.blocks !== void 0) {
+      const expanded = await expandBlocksWithPlugins(
+        modedRoot,
+        modedTheme,
+        new Set(componentMap.keys()),
+        async (component, path4) => {
+          const custom = componentMap.get(String(component.name));
+          const version = resolveComponentVersion(
+            custom.name,
+            custom.versions,
+            component.version
+          );
+          const checked = validateComponentProps(
+            version,
+            component.props ?? {},
+            custom.name,
+            { clean: vOpts.allowUnknownFields === true }
+          );
+          if (!checked.valid)
+            throw new ComponentValidationError2(
+              (checked.errors ?? []).map((e) => ({ path: path4, message: e.message })),
+              component
+            );
+          const output = await version.render({
+            props: cleanComponentProps(version, component.props ?? {}),
+            theme: modedTheme,
+            children: component.children,
+            addWarning: (message, context) => warnings.push({
+              component: custom.name,
+              message,
+              severity: "warning",
+              context
+            })
+          });
+          const emitted = Array.isArray(output) ? output : [output];
+          validateEmitted?.(emitted, custom.name, path4);
+          return emitted;
+        },
+        preserveSet
+      );
+      const [modedDoc2] = normalizeDocument(expanded.document);
+      return {
+        modedRoot,
+        modedTheme,
+        themeName,
+        modedDoc: modedDoc2,
+        sourceMap: expanded.sourceMap,
+        blockPaths: expanded.blocks,
+        warnings,
+        preserveSet,
+        processed: {
+          standard: modedDoc2.children ?? [],
+          preserved: expanded.preserved.children ?? []
+        }
+      };
+    }
     const processed = await processDocumentComponents(
       modedRoot.children || [],
       preserveSet,
@@ -15234,9 +14867,13 @@ function createBuilderImpl(state) {
   }
   async function expandStandardDefinition(document, options) {
     try {
-      const { modedDoc, warnings } = await expandDocument(document, options);
+      const { modedDoc, warnings, sourceMap } = await expandDocument(
+        document,
+        options
+      );
       return {
         standardDefinition: modedDoc,
+        ...sourceMap && { sourceMap },
         warnings: warnings.length > 0 ? warnings : null
       };
     } catch (error) {
@@ -15254,6 +14891,8 @@ function createBuilderImpl(state) {
         themeName,
         processed,
         modedDoc,
+        sourceMap,
+        blockPaths,
         warnings,
         preserveSet
       } = await expandDocument(document, options);
@@ -15264,7 +14903,13 @@ function createBuilderImpl(state) {
       const { buffer } = await generateBufferViaIr(modedDoc, {
         // The prologue already ran: the theme had to be resolved before custom
         // components expanded, because each one's `render` is handed it.
-        context: { document: modedDoc, theme: modedTheme, themeName },
+        context: {
+          document: modedDoc,
+          theme: modedTheme,
+          themeName,
+          ...sourceMap !== void 0 && { sourceMap },
+          ...blockPaths !== void 0 && { blockPaths }
+        },
         ...state.services ? { services: state.services } : {},
         ...state.fonts ? { fonts: state.fonts } : {},
         ...baseDir !== void 0 ? { baseDir } : {},
@@ -15321,7 +14966,7 @@ function createBuilderImpl(state) {
   function validate(document) {
     try {
       const internalDocument = document;
-      const result = validateDocument(
+      const result = validateDocument2(
         internalDocument,
         state.components
       );
@@ -15400,7 +15045,6 @@ function getCoreVersion() {
   return "Core v1.0.0";
 }
 export {
-  BLOCK_NAMES,
   ComponentValidationError2 as ComponentValidationError,
   DocumentGenerator as CoreDocumentGenerator,
   DEFAULT_DOCX_RENDERER_ID,
@@ -15415,10 +15059,6 @@ export {
   analyzeDocxQuality,
   blockSlotBudgets,
   cleanComponentProps,
-  compileCover,
-  compileKeyTakeaways,
-  compileRunningHead,
-  compileSectionOpener,
   consultingTheme,
   createComponent,
   createDocumentGenerator,
@@ -15449,7 +15089,6 @@ export {
   getExampleNames,
   getVisualPrepassStats,
   hasNodeBuiltins,
-  isChromeBlockName,
   isColumnsComponent,
   isDocxRendererId,
   isHeadingComponent,
@@ -15473,12 +15112,10 @@ export {
   resetVisualPrepassStats,
   resolveDocxQualityProfile,
   runExample,
-  sectionMeasureTwips,
-  sectionTracker,
   themes,
   toAuthoredPointer,
   validateComponentProps,
-  validateDocument,
+  validateDocument2 as validateDocument,
   validateJsonSchema,
   validateThemeJsonString,
   vermilionTheme