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

package/dist/index.js

@@ -2376,7 +2376,7 @@ import {
   WpsShapeRun
 } from "docx";
 import { assertNever } from "@json-to-office/shared/rendering";
-function complexField(instruction, formatting, leading) {
+function complexField(instruction, formatting, leading, cachedText) {
   const options = runOptions(formatting);
   const fieldChar = (type, extra = {}) => new TextRun({
     children: [
@@ -2395,6 +2395,9 @@ function complexField(instruction, formatting, leading) {
     fieldChar("begin", leading),
     new TextRun({ children: [instrText], ...options }),
     fieldChar("separate"),
+    // A sequence number is the one field this pipeline can compute, so its
+    // result is written: a reader that never updates fields shows the count.
+    ...cachedText !== void 0 ? [new TextRun({ text: cachedText, ...options })] : [],
     fieldChar("end")
   ];
 }
@@ -2505,13 +2508,18 @@ function inlineChildren(children, resources = /* @__PURE__ */ new Map()) {
           out.push(new SimpleField(child.instruction, child.cachedText));
           break;
         }
-        if (!PAGE_FIELDS.has(child.instruction)) {
+        if (!PAGE_FIELDS.has(child.instruction) && !isSequenceField(child.instruction)) {
           throw new Error(
             `the docxjs renderer has no emitter for the field "${child.instruction}"`
           );
         }
         out.push(
-          ...complexField(child.instruction, child.formatting, breakOption())
+          ...complexField(
+            child.instruction,
+            child.formatting,
+            breakOption(),
+            child.cachedText
+          )
         );
         break;
       }
@@ -2885,7 +2893,7 @@ function emitBorder(border3) {
     ...border3.spacePoints !== void 0 ? { space: border3.spacePoints } : {}
   };
 }
-var ALIGNMENT2, PAGE_FIELDS, WRAP_TYPE, VERTICAL_ALIGN, TABLE_ANCHOR, HORIZONTAL_POSITION, VERTICAL_POSITION, BORDER_STYLE;
+var ALIGNMENT2, PAGE_FIELDS, isSequenceField, WRAP_TYPE, VERTICAL_ALIGN, TABLE_ANCHOR, HORIZONTAL_POSITION, VERTICAL_POSITION, BORDER_STYLE;
 var init_emit = __esm({
   "src/renderers/docxjs/emit.ts"() {
     "use strict";
@@ -2898,6 +2906,7 @@ var init_emit = __esm({
       end: AlignmentType.END
     };
     PAGE_FIELDS = /* @__PURE__ */ new Set(["PAGE", "NUMPAGES"]);
+    isSequenceField = (instruction) => /^SEQ [A-Za-z][\w-]* \\\* ARABIC$/.test(instruction);
     WRAP_TYPE = {
       none: TextWrappingType.NONE,
       square: TextWrappingType.SQUARE,
@@ -5042,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 = {
@@ -5061,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);
   }
@@ -5521,13 +5534,25 @@ init_colorUtils();
 init_layoutUtils();
 import {
   chartFamilyResolver,
+  remoteExportNotice,
+  REMOTE_EXPORT_WARNING,
   chartPointsPerPixel,
   POINTS_PER_PIXEL_96DPI,
   withChartFontFaceCss,
   withChartTypography
 } from "@json-to-office/shared";
 var DEFAULT_EXPORT_SERVER_URL = "http://localhost:7801";
-async function generateChart(config, servicesConfig) {
+function assertExportServerAllowed(serverUrl, servicesConfig, warnings) {
+  const notice = remoteExportNotice(serverUrl, servicesConfig?.allowRemote);
+  if (notice)
+    warnings?.push({
+      component: "highcharts",
+      severity: "warning",
+      message: notice,
+      context: { code: REMOTE_EXPORT_WARNING, serverUrl }
+    });
+}
+async function generateChart(config, servicesConfig, warnings) {
   if (!isNodeEnvironment()) {
     throw new Error(
       "Highcharts export server requires a Node.js environment. Chart generation is not available in browser environments."
@@ -5538,6 +5563,7 @@ async function generateChart(config, servicesConfig) {
     servicesConfig?.serverUrl,
     DEFAULT_EXPORT_SERVER_URL
   );
+  assertExportServerAllowed(serverUrl, servicesConfig, warnings);
   const requestBody = {
     infile: config.options,
     type: "png",
@@ -5650,13 +5676,13 @@ function withChartFontFaces(config, theme, faces) {
     theme.fonts.heading.family
   ]);
 }
-async function renderChartToImageProps(props, theme, servicesConfig, chartFonts) {
+async function renderChartToImageProps(props, theme, servicesConfig, chartFonts, warnings) {
   const config = withChartFontFaces(
     withThemeTypography(withThemeColors(props, theme), theme),
     theme,
     chartFonts
   );
-  const chart = await generateChart(config, servicesConfig);
+  const chart = await generateChart(config, servicesConfig, warnings);
   const hasConfigDimensions = config.width !== void 0 || config.height !== void 0;
   return {
     base64: chart.base64DataUri,
@@ -5696,7 +5722,8 @@ async function desugarExternals(document, options) {
           node.props,
           options.theme,
           options.services?.highcharts,
-          options.chartFonts
+          options.chartFonts,
+          options.warnings
         )
       });
     }
@@ -8247,6 +8274,9 @@ function parsePlaceholders(normalized, parseOptions) {
         out.push({
           kind: "field",
           instruction: resolved.instruction,
+          ...resolved.cachedText !== void 0 && {
+            cachedText: resolved.cachedText
+          },
           ...formatting ? { formatting } : {}
         });
       }
@@ -8473,6 +8503,7 @@ function compileDocument(structure, layout, warnings = [], images = /* @__PURE__
     nextBookmarkId: CONTENT_BOOKMARK_ID_BASE + 1,
     bookmarkNames: /* @__PURE__ */ new Set(),
     usesStatistic: false,
+    sequences: /* @__PURE__ */ new Map(),
     styleIds: /* @__PURE__ */ new Set([
       ...styles.paragraph.map((s) => s.id),
       ...styles.character.map((s) => s.id)
@@ -9868,7 +9899,20 @@ function compileRuns(props, text, ctx, path4, mode = "inline") {
   return children;
 }
 function placeholderResolver(ctx) {
-  return (name) => resolvePlaceholder(name, ctx.generatedAt);
+  return (name) => {
+    const sequence = /^SEQ:([A-Za-z][\w-]*)$/i.exec(name);
+    if (sequence) {
+      const key = sequence[1];
+      const count = (ctx.sequences.get(key) ?? 0) + 1;
+      ctx.sequences.set(key, count);
+      return {
+        kind: "field",
+        instruction: `SEQ ${key} \\* ARABIC`,
+        cachedText: String(count)
+      };
+    }
+    return resolvePlaceholder(name, ctx.generatedAt);
+  };
 }
 function crossReferenceResolver(ctx, path4) {
   return (id, format2, token) => resolveCrossReference(id, format2, token, ctx, path4);
@@ -11730,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,
@@ -11738,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) {
@@ -11830,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";
@@ -12094,12 +12142,41 @@ import {
   readBlockDefinitions,
   blockValueAt,
   isBlockRecord,
-  toAuthoredBlockPointer
+  toAuthoredBlockPointer,
+  blockPointerKey,
+  blockSlotRoles
 } from "@json-to-office/shared";
-import { blockSlotBudgets } from "@json-to-office/shared";
+import { blockSlotBudgets, blockSlotRoles as blockSlotRoles2 } from "@json-to-office/shared";
 import { validateDocument } from "@json-to-office/shared-docx";
 var toAuthoredPointer = toAuthoredBlockPointer;
-function docxBlockContext(document, theme, path4 = "") {
+function documentSourceLines(document) {
+  if (!isBlockRecord(document)) return [];
+  const invocations = [];
+  const walk2 = (value, path4) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk2(item, `${path4}/${index}`));
+      return;
+    }
+    if (!isBlockRecord(value) || value.enabled === false) return;
+    if (value.name === "block") invocations.push(path4);
+    for (const [key, item] of Object.entries(value)) {
+      if (path4 === "/props" && key === "blocks") continue;
+      walk2(item, `${path4}/${blockPointerKey(key)}`);
+    }
+  };
+  walk2(document, "");
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const slot of blockSlotRoles(document, invocations)) {
+    if (slot.role !== "source" || typeof slot.value !== "string") continue;
+    const text = slot.value.trim();
+    if (text === "" || seen.has(text)) continue;
+    seen.add(text);
+    lines.push({ text, path: slot.path });
+  }
+  return lines;
+}
+function docxBlockContext(document, theme, path4, sources) {
   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 : {};
@@ -12119,26 +12196,46 @@ function docxBlockContext(document, theme, path4 = "") {
   return {
     document: blockValueAt(document, "/props/metadata") ?? {},
     page: { width, height },
-    section: {}
+    section: {},
+    sources: sources.map((line) => line.text)
   };
 }
-function createDocxBlockEvaluator(document, theme, extra = {}) {
+function docxBlockContextSources(sources) {
+  return {
+    "/document": "/props/metadata",
+    ...Object.fromEntries(
+      sources.map((line, index) => [`/sources/${index}`, line.path])
+    )
+  };
+}
+function createDocxBlockEvaluator(document, theme, extra = {}, sources = documentSourceLines(document)) {
   return new JsonBlockEvaluator(readBlockDefinitions(document), {
     format: "docx",
     theme,
-    contextAt: (path4) => docxBlockContext(document, theme, path4),
-    contextSources: { "/document": "/props/metadata" },
+    contextAt: (path4) => docxBlockContext(document, theme, path4, sources),
+    contextSources: docxBlockContextSources(sources),
     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 sources = documentSourceLines(document);
+  const evaluator = createDocxBlockEvaluator(
+    document,
+    theme,
+    { onSection: (effect) => effects.push(effect) },
+    sources
+  );
   const expanded = evaluator.expand(document);
-  return finishDocxBlocks(expanded, document, theme, evaluator, effects);
+  return finishDocxBlocks(
+    expanded,
+    document,
+    theme,
+    evaluator,
+    effects,
+    sources
+  );
 }
 function validateEffects(document, effects) {
   for (const effect of effects) {
@@ -12159,7 +12256,7 @@ function validateEffects(document, effects) {
       ]);
   }
 }
-function finishDocxBlocks(expanded, document, theme, evaluator, effects, validate = true) {
+function finishDocxBlocks(expanded, document, theme, evaluator, effects, sources, validate = true) {
   if (isBlockRecord(expanded) && Array.isArray(expanded.children)) {
     let inherited;
     expanded.children.forEach((section2, index) => {
@@ -12197,11 +12294,11 @@ function finishDocxBlocks(expanded, document, theme, evaluator, effects, validat
         const environment = {
           ...chrome.environment,
           context: {
-            ...docxBlockContext(document, theme, path4),
+            ...docxBlockContext(document, theme, path4, sources),
             section: { tracker }
           },
           contextSources: {
-            "/document": "/props/metadata",
+            ...docxBlockContextSources(sources),
             "/section/tracker": trackerSource
           }
         };
@@ -12245,10 +12342,16 @@ function finishDocxBlocks(expanded, document, theme, evaluator, effects, validat
 }
 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 sources = documentSourceLines(document);
+  const evaluator = createDocxBlockEvaluator(
+    document,
+    theme,
+    {
+      reservedNames: [...plugins],
+      onSection: (effect) => effects.push(effect)
+    },
+    sources
+  );
   const walk2 = (value) => composeBlocksWithPlugins(evaluator, value, {
     plugins,
     render,
@@ -12261,6 +12364,7 @@ async function expandBlocksWithPlugins(document, theme, plugins, render, preserv
     theme,
     evaluator,
     effects,
+    sources,
     false
   );
   const second = await walk2(finished.document);
@@ -12360,7 +12464,8 @@ function chartFact(node, props, path4, paletteTokens) {
     kind: "docx/chart",
     path: path4,
     componentName: typeof node.name === "string" ? node.name : "",
-    paletteTokens
+    paletteTokens,
+    generated: false
   };
   if (node.name === "highcharts") {
     const shape = normalizeHighchartsChart(props.options);
@@ -12371,7 +12476,11 @@ function chartFact(node, props, path4, paletteTokens) {
       threeD: shape.threeD,
       seriesCount: shape.seriesCount,
       categoryCount: shape.categoryCount,
-      seriesColorsStated: shape.seriesColorsStated,
+      // A config that names no `colors` is painted in the theme's chart
+      // palette at render, so the series are the document's whenever the
+      // theme has a palette to give; only a theme with none leaves them to
+      // the export server's default.
+      seriesColorsStated: shape.seriesColorsStated || paletteTokens.length > 0,
       seriesColorsPath: `${path4}/props/options`,
       ...shape.valueAxisMin !== void 0 && {
         valueAxisMin: shape.valueAxisMin
@@ -12743,6 +12852,11 @@ function prepareDocxQualityDocument(document, options = {}) {
       ...fact.relatedPaths && { relatedPaths: fact.relatedPaths }
     };
   };
+  const annotatedInvocations = new Set(
+    blockSlotRoles2(themed.document, expanded.blocks).filter(
+      (slot) => (slot.role === "takeaway" || slot.role === "source") && typeof slot.value === "string" && slot.value.trim() !== ""
+    ).map((slot) => slot.invocation)
+  );
   for (const budget of blockSlotBudgets(themed.document, expanded.blocks)) {
     addFact({
       id: `docx:block-slot:${budget.path}`,
@@ -12750,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,
@@ -12854,7 +13000,27 @@ function prepareDocxQualityDocument(document, options = {}) {
     }
     if (node.name === "chart" || node.name === "highcharts") {
       const fact = chartFact(node, props, path4, paletteTokens);
-      if (fact) addFact(fact);
+      if (fact) {
+        const authored = authoredPath(path4);
+        const invocation = expanded.blocks.filter(
+          (pointer) => authored === pointer || authored.startsWith(`${pointer}/`)
+        ).sort((a, b) => b.length - a.length)[0];
+        const annotated = invocation !== void 0 && annotatedInvocations.has(invocation);
+        addFact({
+          ...fact,
+          generated: !["chart", "highcharts"].includes(
+            String(asRecord(nodeAtPointer(themed.document, authored))?.name)
+          ),
+          seriesColorsPath: authoredPath(fact.seriesColorsPath),
+          ...fact.annotation && {
+            annotation: {
+              ...fact.annotation,
+              path: authoredPath(fact.annotation.path),
+              stated: fact.annotation.stated || annotated
+            }
+          }
+        });
+      }
     }
     if (node.name === "paragraph" || node.name === "text-box") {
       const floating = asRecord(props.floating);
@@ -12924,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 {
@@ -12976,7 +13153,8 @@ async function compileDocumentScoped(document, options, warnings) {
     ...options.services ? { services: options.services } : {},
     ...options.baseDir !== void 0 ? { baseDir: options.baseDir } : {},
     ...visualFonts.length > 0 ? { visualFonts } : {},
-    ...chartFonts.length > 0 ? { chartFonts } : {}
+    ...chartFonts.length > 0 ? { chartFonts } : {},
+    warnings
   });
   const resolved = desugared === context.document ? prepared.model.document : resolveDocumentTree(desugared, context.theme);
   const structure = await processResolvedDocument(
@@ -13909,7 +14087,7 @@ var docxChartRule = {
   }
 };
 function seriesColorFix(fact) {
-  if (fact.componentName !== "chart") return void 0;
+  if (fact.componentName !== "chart" || fact.generated) return void 0;
   if (fact.seriesCount < 1 || fact.paletteTokens.length === 0) return void 0;
   const tokens = Array.from(
     { length: fact.seriesCount },
@@ -13970,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: [
@@ -13984,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"],
@@ -14009,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];
@@ -14056,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
   });
 }
@@ -14166,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."
@@ -15062,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,
@@ -15078,7 +15980,9 @@ export {
   createDocumentGenerator,
   createMinimalTheme,
   createVersion,
+  declaredDocxQualityProfile,
   devportalTheme,
+  docxBlueprint,
   docxQualityEngine,
   docxRendererIds,
   docxRendererStatuses,
@@ -15103,6 +16007,7 @@ export {
   getExampleNames,
   getVisualPrepassStats,
   hasNodeBuiltins,
+  instantiateDocxBlueprint,
   isColumnsComponent,
   isDocxRendererId,
   isHeadingComponent,