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

package/dist/index.js

@@ -5051,6 +5051,10 @@ function resolveServiceUrl(propsUrl, servicesUrl, defaultUrl) {
   const withScheme = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
   return withScheme.replace(/\/+$/, "");
 }
+var SERVICE_UNAVAILABLE_CODE = "SERVICE_UNAVAILABLE";
+function serviceUnavailable(message) {
+  return Object.assign(new Error(message), { code: SERVICE_UNAVAILABLE_CODE });
+}
 async function postJsonToService(opts) {
   const resolvedHeaders = typeof opts.headers === "function" ? await opts.headers(opts.body) : opts.headers;
   const headers = {
@@ -5070,12 +5074,12 @@ async function postJsonToService(opts) {
     });
   } catch (error) {
     if (error?.name === "AbortError") {
-      throw new Error(
+      throw serviceUnavailable(
         `${opts.serviceLabel} timed out after ${timeoutMs}ms at ${opts.url}.`
       );
     }
     const cause = error instanceof Error ? error.message : String(error);
-    throw new Error(opts.onUnreachable(opts.url, cause));
+    throw serviceUnavailable(opts.onUnreachable(opts.url, cause));
   } finally {
     clearTimeout(timer);
   }
@@ -11770,6 +11774,7 @@ async function processResolvedDocument(document, resolved, themeName, generation
   };
 }
 function createDocumentMetadata(props, generationDate = /* @__PURE__ */ new Date()) {
+  const parsed = props.metadata?.date ? new Date(props.metadata.date) : void 0;
   return {
     title: props.metadata?.title,
     subtitle: props.metadata?.subtitle,
@@ -11778,7 +11783,7 @@ function createDocumentMetadata(props, generationDate = /* @__PURE__ */ new Date
     company: props.metadata?.company,
     version: props.metadata?.version,
     tags: props.metadata?.tags,
-    date: props.metadata?.date ? new Date(props.metadata.date) : generationDate
+    date: parsed && !Number.isNaN(parsed.getTime()) ? parsed : generationDate
   };
 }
 async function extractSections(components, context) {
@@ -11870,7 +11875,10 @@ import {
   normalizeHighchartsChart
 } from "@json-to-office/quality";
 import { DEFAULT_DOCX_RENDERER_ID as DEFAULT_DOCX_RENDERER_ID2 } from "@json-to-office/shared-docx";
-import { designColors as designColors2, resolveDesignColor as resolveDesignColor2 } from "@json-to-office/shared";
+import {
+  designColors as designColors2,
+  resolveDesignColor as resolveDesignColor2
+} from "@json-to-office/shared";
 
 // src/core/generationContext.ts
 import { applyExportMode } from "@json-to-office/shared";
@@ -12856,6 +12864,38 @@ function prepareDocxQualityDocument(document, options = {}) {
       ...budget
     });
   }
+  for (const role of blockSlotRoles2(themed.document, expanded.blocks)) {
+    addFact({
+      id: `docx:chrome-slot:${role.path}`,
+      kind: "docx/chrome-slot",
+      path: role.path,
+      relatedPaths: [role.invocation],
+      block: role.block,
+      slot: role.slot,
+      role: role.role,
+      present: slotIsFilled(role.value),
+      invocation: role.invocation
+    });
+  }
+  const topLevel = Array.isArray(context.document.children) ? context.document.children : [];
+  let inherited = {};
+  topLevel.forEach((node, index) => {
+    if (node?.name !== "section") return;
+    const props = asRecord(node.props) ?? {};
+    const part = (kind) => props[kind] === "linkToPrevious" ? inherited[kind] : props[kind];
+    const header = part("header");
+    const footer = part("footer");
+    inherited = { header, footer };
+    addFact({
+      id: `docx:section-chrome:${index}`,
+      kind: "docx/section-chrome",
+      path: `/children/${index}`,
+      index,
+      header: partPresent(header),
+      footer: partPresent(footer),
+      pageNumber: hasPageField(header) || hasPageField(footer)
+    });
+  });
   const paletteHexes = {};
   const visualColors = designColors2(
     resolved.theme.colors,
@@ -13050,6 +13090,17 @@ function prepareDocxQualityDocument(document, options = {}) {
     }
   };
 }
+function slotIsFilled(value) {
+  if (typeof value === "string") return value.trim() !== "";
+  return value !== void 0 && value !== null && value !== false && (!Array.isArray(value) || value.length > 0);
+}
+function partPresent(part) {
+  return Array.isArray(part) && part.length > 0;
+}
+var PAGE_FIELD = /\{(PAGE|PAGE_NUMBER|TOTAL_PAGES|NUMPAGES)\}/;
+function hasPageField(part) {
+  return Array.isArray(part) && PAGE_FIELD.test(JSON.stringify(part));
+}
 
 // src/core/generateFromIr.ts
 var UncompiledComponentError = class extends Error {
@@ -14097,6 +14148,67 @@ function alignColumnRight(column) {
   }
   return operations;
 }
+function stringListParameter(parameters, name) {
+  const value = parameters[name];
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+var docxRequiredChromeRule = {
+  id: "docx/required-chrome",
+  code: QUALITY_CODES.CHROME_MISSING,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: { required: [] },
+  evaluate: ({ facts, configuration, profile }) => {
+    const required = stringListParameter(configuration.parameters, "required");
+    if (required.length === 0) return [];
+    return facts.filter(
+      (fact) => fact.kind === "docx/chrome-slot"
+    ).filter((fact) => required.includes(fact.role) && !fact.present).map((fact) => ({
+      path: fact.path,
+      relatedPaths: [fact.invocation],
+      message: `${fact.block} states no ${fact.role} in its "${fact.slot}" slot; the ${profile?.id ?? "selected"} profile expects one on every ${fact.block}.`,
+      suggestion: `Fill the "${fact.slot}" slot. The theme already styles it.`,
+      context: { block: fact.block, slot: fact.slot, role: fact.role }
+    }));
+  }
+};
+var SECTION_CHROME_PARTS = ["header", "footer", "pageNumber"];
+var docxRunningHeadRule = {
+  id: "docx/running-head",
+  code: QUALITY_CODES.CHROME_MISSING,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: { required: [], fromSection: 1 },
+  evaluate: ({ facts, configuration, profile }) => {
+    const required = stringListParameter(
+      configuration.parameters,
+      "required"
+    ).filter(
+      (part) => SECTION_CHROME_PARTS.includes(part)
+    );
+    if (required.length === 0) return [];
+    const from = numberParameter(configuration.parameters, "fromSection", 1);
+    return facts.filter(
+      (fact) => fact.kind === "docx/section-chrome" && fact.index >= from
+    ).flatMap((fact) => {
+      const missing = required.filter((part) => !fact[part]);
+      if (missing.length === 0) return [];
+      const parts = missing.map((part) => part === "pageNumber" ? "page-number field" : part).join(", ");
+      return [
+        {
+          path: fact.path,
+          message: `Section ${fact.index + 1} carries no ${parts}; the ${profile?.id ?? "selected"} profile expects a running head on every section after the cover.`,
+          suggestion: "Invoke a running-head block at the top of the first body section: its section effect fills every later section with the tracker and n / N.",
+          context: { section: fact.index, missing }
+        }
+      ];
+    });
+  }
+};
 var DOCX_QUALITY_RULES = {
   id: "docx/default",
   rules: [
@@ -14111,10 +14223,29 @@ var DOCX_QUALITY_RULES = {
     docxChartRule,
     docxTableDesignRule,
     docxFontCountRule,
-    docxPaletteRule
+    docxPaletteRule,
+    docxRequiredChromeRule,
+    docxRunningHeadRule
   ]
 };
 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.",
+    rules: {
+      "docx/required-chrome": {
+        parameters: { required: ["takeaway", "source"] }
+      },
+      "docx/running-head": {
+        parameters: {
+          required: ["header", "footer", "pageNumber"],
+          fromSection: 1
+        }
+      },
+      "docx/heading-hierarchy": { severity: "warning" }
+    }
+  },
   "executive-report": {
     id: "executive-report",
     formats: ["docx"],
@@ -14136,6 +14267,11 @@ var DOCX_QUALITY_PROFILES = {
 };
 var DOCX_DEFAULT_QUALITY_PROFILE = DOCX_QUALITY_PROFILES["technical-report"];
 var DOCX_PROFILES_BY_ID = DOCX_QUALITY_PROFILES;
+function declaredDocxQualityProfile(document) {
+  const props = document?.props;
+  const id = props?.qualityProfile;
+  return typeof id === "string" && Object.prototype.hasOwnProperty.call(DOCX_PROFILES_BY_ID, id) ? DOCX_PROFILES_BY_ID[id] : void 0;
+}
 function resolveDocxQualityProfile(requested) {
   if (!requested) return void 0;
   const registered = DOCX_PROFILES_BY_ID[requested.id];
@@ -14183,7 +14319,7 @@ function analyzeDocxQuality(doc, options = {}) {
     );
   }
   return docxQualityEngine.analyzeSync(prepared, {
-    profile: resolveDocxQualityProfile(options.profile) ?? DOCX_DEFAULT_QUALITY_PROFILE,
+    profile: resolveDocxQualityProfile(options.profile) ?? declaredDocxQualityProfile(doc) ?? DOCX_DEFAULT_QUALITY_PROFILE,
     policy: options.policy
   });
 }
@@ -14293,17 +14429,655 @@ function formatWarningsText(warnings) {
 
 // src/index.ts
 init_styles();
+
+// src/blueprints/index.ts
+import {
+  blockDependencies,
+  validateBlueprint
+} from "@json-to-office/shared";
+import { collectPlaceholders as collectPlaceholders2 } from "@json-to-office/quality";
+import { existsSync, readdirSync, readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/templates/blueprints/client-report.docx.blueprint.json
+var client_report_docx_blueprint_default = {
+  id: "client-report",
+  format: "docx",
+  title: "Client report",
+  description: "A report for a client or a public administration: a cover, key takeaways, KPIs, chart-first sections with a takeaway and a source under every figure, data tables, notes and sources, under a running head that tracks the section and numbers the pages.",
+  whenToUse: "A periodic or one-off report to a client, a board or a public body that reads for the conclusion first and checks the evidence second. Not for a memo or a technical specification.",
+  theme: "consulting",
+  profile: "client-report",
+  definitions: "client-report-blocks.docx.json",
+  numbering: "sections",
+  toc: false,
+  variants: {
+    "data-heavy": {
+      description: "Evidence-led: a KPI row under the takeaways, a chart with its takeaway in the second section, a data table with a note in the third, next steps last.",
+      whenToUse: "The brief comes with numbers: performance, finance, operations, anything the reader will check against a figure.",
+      pages: {
+        min: 4,
+        max: 8
+      },
+      metadata: {
+        title: "{{Title: as on the cover}}",
+        author: "{{Author or team}}",
+        company: "{{Client name}}",
+        date: "{{Month YYYY}}"
+      },
+      children: [
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "cover",
+                slots: {
+                  title: "{{Title: the report's conclusion in one sentence}}",
+                  subtitle: "{{Subtitle: what the report answers, for whom}}",
+                  client: "{{Client name}}",
+                  date: "{{Month YYYY}}",
+                  confidentiality: "{{Confidentiality: Confidential, or For internal use}}"
+                }
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "running-head",
+                slots: {
+                  confidentiality: "{{Confidentiality: as on the cover}}",
+                  date: "{{Month YYYY}}"
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "01",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "key-takeaways",
+                slots: {
+                  items: [
+                    "{{Takeaway 1: one claim, one sentence, with its number}}",
+                    "{{Takeaway 2: one claim, one sentence, with its number}}",
+                    "{{Takeaway 3: the recommendation that follows}}"
+                  ]
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "kpi-row",
+                slots: {
+                  items: [
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    },
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    },
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    }
+                  ],
+                  source: "{{Source: system or document, date}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "02",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "chart-figure",
+                slots: {
+                  chart: {
+                    name: "highcharts",
+                    props: {
+                      width: "100%",
+                      options: {
+                        chart: {
+                          type: "column",
+                          width: 900,
+                          height: 460
+                        },
+                        title: {
+                          text: null
+                        },
+                        xAxis: {
+                          categories: [
+                            "{{Period 1}}",
+                            "{{Period 2}}",
+                            "{{Period 3}}"
+                          ]
+                        },
+                        yAxis: {
+                          title: {
+                            text: "{{Measure (unit)}}"
+                          }
+                        },
+                        series: [
+                          {
+                            name: "{{Series name}}",
+                            data: [0, 0, 0]
+                          }
+                        ]
+                      }
+                    }
+                  },
+                  caption: "{{Caption: what the chart shows, as a statement}}",
+                  takeaway: "{{Takeaway: the one sentence the reader should keep}}",
+                  source: "{{Source: system or document, date}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "03",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "data-table",
+                slots: {
+                  title: "{{Table title: what it compares, and the period}}",
+                  labelHeader: "{{Row label}}",
+                  labels: ["{{Row 1}}", "{{Row 2}}", "{{Row 3}}"],
+                  columns: [
+                    {
+                      header: "{{Measure (unit)}}",
+                      cells: ["{{0.0}}", "{{0.0}}", "{{0.0}}"]
+                    },
+                    {
+                      header: "{{Change}}",
+                      cells: ["{{0.0}}", "{{0.0}}", "{{0.0}}"]
+                    }
+                  ],
+                  source: "{{Source: system or document, date}}"
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "callout",
+                slots: {
+                  label: "{{Note label}}",
+                  text: "{{Note: a caveat about the numbers, a definition or the method}}"
+                }
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "04",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "footnotes"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    narrative: {
+      description: "Argument-led: takeaways, then three sections of prose with one KPI row and one note as evidence, next steps last.",
+      whenToUse: "The brief is a position, an assessment or a recommendation with few numbers; the reader follows an argument.",
+      pages: {
+        min: 3,
+        max: 6
+      },
+      metadata: {
+        title: "{{Title: as on the cover}}",
+        author: "{{Author or team}}",
+        company: "{{Client name}}",
+        date: "{{Month YYYY}}"
+      },
+      children: [
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "cover",
+                slots: {
+                  title: "{{Title: the report's conclusion in one sentence}}",
+                  subtitle: "{{Subtitle: what the report answers, for whom}}",
+                  client: "{{Client name}}",
+                  date: "{{Month YYYY}}",
+                  confidentiality: "{{Confidentiality: Confidential, or For internal use}}"
+                }
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "running-head",
+                slots: {
+                  confidentiality: "{{Confidentiality: as on the cover}}",
+                  date: "{{Month YYYY}}"
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "01",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "key-takeaways",
+                slots: {
+                  items: [
+                    "{{Takeaway 1: one claim, one sentence, with its number}}",
+                    "{{Takeaway 2: one claim, one sentence, with its number}}",
+                    "{{Takeaway 3: the recommendation that follows}}"
+                  ]
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "02",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "callout",
+                slots: {
+                  label: "{{Note label}}",
+                  text: "{{Note: a caveat about the numbers, a definition or the method}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "03",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "kpi-row",
+                slots: {
+                  items: [
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    },
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    },
+                    {
+                      value: "{{0.0}}",
+                      label: "{{What it measures}}"
+                    }
+                  ],
+                  source: "{{Source: system or document, date}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            }
+          ]
+        },
+        {
+          name: "section",
+          children: [
+            {
+              name: "block",
+              props: {
+                ref: "section-opener",
+                slots: {
+                  number: "04",
+                  title: "{{Section title: the finding, as a statement}}",
+                  tracker: "{{Tracker: one or two words}}"
+                }
+              }
+            },
+            {
+              name: "paragraph",
+              props: {
+                text: "{{Body: two or three short paragraphs of evidence for the section title, each opening with its claim}}"
+              }
+            },
+            {
+              name: "block",
+              props: {
+                ref: "footnotes"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+};
+
+// src/blueprints/index.ts
+function register(...candidates) {
+  const registry2 = {};
+  for (const candidate of candidates) {
+    const issues = validateBlueprint(candidate);
+    if (issues.length > 0)
+      throw new Error(
+        `Invalid bundled blueprint: ${issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`
+      );
+    const blueprint = candidate;
+    if (blueprint.format !== "docx")
+      throw new Error(`Blueprint ${blueprint.id} is not a DOCX blueprint.`);
+    if (registry2[blueprint.id])
+      throw new Error(
+        `Two bundled blueprints share the id "${blueprint.id}"; the later one would silently replace the earlier.`
+      );
+    registry2[blueprint.id] = blueprint;
+  }
+  return registry2;
+}
+function scanned(known) {
+  let here;
+  try {
+    here = dirname2(fileURLToPath2(import.meta.url));
+  } catch {
+    return [];
+  }
+  const directory = [
+    join2(here, "../templates/blueprints"),
+    join2(here, "templates/blueprints")
+  ].find((path4) => existsSync(path4));
+  if (!directory) return [];
+  return readdirSync(directory).filter((file) => file.endsWith(".docx.blueprint.json")).map((file) => JSON.parse(readFileSync2(join2(directory, file), "utf8"))).filter((candidate) => {
+    const id = candidate?.id;
+    return !(typeof id === "string" && id in known);
+  });
+}
+var bundled = register(client_report_docx_blueprint_default);
+var DOCX_BLUEPRINTS = {
+  ...bundled,
+  ...register(...scanned(bundled))
+};
+function docxBlueprint(id) {
+  return DOCX_BLUEPRINTS[id];
+}
+var MARKER = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
+function instantiateDocxBlueprint(blueprint, options) {
+  if (blueprint.format !== "docx")
+    throw new Error(
+      `Blueprint ${blueprint.id} is a ${blueprint.format} blueprint; this instantiates DOCX ones.`
+    );
+  const variantId = options.variant ?? Object.keys(blueprint.variants)[0];
+  const variant = blueprint.variants[variantId];
+  if (!variant)
+    throw new Error(
+      `Blueprint ${blueprint.id} has no variant "${variantId}"; it has ${Object.keys(
+        blueprint.variants
+      ).join(", ")}.`
+    );
+  const children = structuredClone(variant.children);
+  const blocks = definitionsFor(children, options.definitions, blueprint);
+  const document = {
+    name: "docx",
+    props: {
+      theme: options.theme ?? blueprint.theme,
+      qualityProfile: blueprint.profile,
+      ...Object.keys(blocks).length > 0 && { blocks },
+      metadata: { ...variant.metadata, ...options.metadata }
+    },
+    children
+  };
+  return { document, fillMap: fillMap(document, blocks), variant: variantId };
+}
+function definitionsFor(children, available, blueprint) {
+  const refs = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (Array.isArray(node)) return node.forEach(visit);
+    if (!node || typeof node !== "object") return;
+    const record = node;
+    const props = record.props;
+    if (record.name === "block" && typeof props?.ref === "string")
+      refs.add(props.ref);
+    Object.values(record).forEach(visit);
+  };
+  visit(children);
+  const result = {};
+  for (const ref of refs) {
+    if (!available[ref])
+      throw new Error(
+        `Blueprint ${blueprint.id} invokes "${ref}", which ${blueprint.definitions} does not define.`
+      );
+    for (const name of [...blockDependencies(available, ref), ref])
+      result[name] ??= structuredClone(available[name]);
+  }
+  return result;
+}
+function fillMap(document, blocks) {
+  return collectPlaceholders2(document).filter((occurrence) => occurrence.match.kind === "scaffold-marker").map((occurrence) => {
+    const guidance = occurrence.text.match(MARKER)?.[1] ?? occurrence.text;
+    const base = { path: occurrence.path, marker: occurrence.text, guidance };
+    if (occurrence.path.startsWith("/props/metadata/"))
+      return { ...base, kind: "metadata" };
+    const slot = slotAt(document, occurrence.path, blocks);
+    return slot ? { ...base, kind: "slot", ...slot } : { ...base, kind: "text" };
+  });
+}
+function slotAt(document, pointer, blocks) {
+  const at = pointer.lastIndexOf("/props/slots/");
+  if (at < 0) return void 0;
+  const invocation = valueAt(document, pointer.slice(0, at));
+  const ref = invocation?.props?.ref;
+  if (typeof ref !== "string" || !blocks[ref]) return void 0;
+  const segments = pointer.slice(at + "/props/slots/".length).split("/").map(unescape);
+  let slot = blocks[ref].slots[segments[0]];
+  const names = [segments[0]];
+  for (const segment of segments.slice(1)) {
+    if (!slot) break;
+    if (slot.type === "array" && /^\d+$/.test(segment)) slot = slot.items;
+    else if (slot.type === "object") {
+      slot = slot.properties?.[segment];
+      names.push(segment);
+    } else if (slot.type === "component")
+      break;
+    else slot = void 0;
+  }
+  if (!slot) return void 0;
+  return {
+    block: ref,
+    slot: names.join("."),
+    type: slot.type,
+    ...slot.maxWords !== void 0 && { maxWords: slot.maxWords },
+    ...slot.maxLength !== void 0 && { maxLength: slot.maxLength },
+    ...slot.oneLine !== void 0 && { oneLine: slot.oneLine },
+    ...slot.required !== void 0 && { required: slot.required }
+  };
+}
+function unescape(segment) {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function valueAt(root, pointer) {
+  if (pointer === "") return root;
+  let current = root;
+  for (const segment of pointer.split("/").slice(1).map(unescape)) {
+    if (Array.isArray(current)) current = current[Number(segment)];
+    else if (current && typeof current === "object")
+      current = current[segment];
+    else return void 0;
+  }
+  return current;
+}
+
+// src/index.ts
 init_json();
 
 // src/templates/documents/index.ts
 import fs4 from "fs";
 import path2 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 var _dirname = null;
 function getDirname() {
   if (_dirname === null) {
     try {
-      _dirname = path2.dirname(fileURLToPath2(import.meta.url));
+      _dirname = path2.dirname(fileURLToPath3(import.meta.url));
     } catch {
       throw new Error(
         "Cannot resolve file paths in a bundled environment. Example loading from disk is not available."
@@ -15189,6 +15963,7 @@ export {
   ComponentValidationError2 as ComponentValidationError,
   DocumentGenerator as CoreDocumentGenerator,
   DEFAULT_DOCX_RENDERER_ID,
+  DOCX_BLUEPRINTS,
   DOCX_DEFAULT_QUALITY_PROFILE,
   DOCX_QUALITY_PROFILES,
   DOCX_QUALITY_RULES,
@@ -15205,7 +15980,9 @@ export {
   createDocumentGenerator,
   createMinimalTheme,
   createVersion,
+  declaredDocxQualityProfile,
   devportalTheme,
+  docxBlueprint,
   docxQualityEngine,
   docxRendererIds,
   docxRendererStatuses,
@@ -15230,6 +16007,7 @@ export {
   getExampleNames,
   getVisualPrepassStats,
   hasNodeBuiltins,
+  instantiateDocxBlueprint,
   isColumnsComponent,
   isDocxRendererId,
   isHeadingComponent,