@json-to-office/core-docx 7.6.0 → 7.7.0

package/dist/index.js

@@ -9,11 +9,51 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var __export = (target, all) => {
+var __export = (target2, all) => {
   for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
+    __defProp(target2, name, { get: all[name], enumerable: true });
 };
 
+// src/utils/generationContext.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { isAbsolute, resolve } from "path";
+function runWithBaseDir(baseDir, callback) {
+  return baseDir === void 0 ? callback() : baseDirStorage.run(resolve(baseDir), callback);
+}
+function getBaseDir() {
+  return baseDirStorage.getStore();
+}
+function resolveFromBaseDir(filePath) {
+  const base = baseDirStorage.getStore();
+  if (!base || isAbsolute(filePath)) return filePath;
+  return resolve(base, filePath);
+}
+function runWithWarnings(warnings, callback) {
+  return warnings === void 0 ? callback() : warningsStorage.run(warnings, callback);
+}
+function reportWarning(component, code, message, context) {
+  const warnings = warningsStorage.getStore();
+  if (warnings) {
+    warnings.push({
+      component,
+      message,
+      severity: "warning",
+      context: { code, ...context }
+    });
+    return;
+  }
+  console.warn(`[json-to-docx] [${code}] ${message}`);
+}
+var generationDateStorage, baseDirStorage, warningsStorage;
+var init_generationContext = __esm({
+  "src/utils/generationContext.ts"() {
+    "use strict";
+    generationDateStorage = new AsyncLocalStorage();
+    baseDirStorage = new AsyncLocalStorage();
+    warningsStorage = new AsyncLocalStorage();
+  }
+});
+
 // src/themes/defaults.ts
 import { designColors } from "@json-to-office/shared";
 function ensureThemeDefaults(theme) {
@@ -2447,43 +2487,6 @@ var init_widthUtils = __esm({
   }
 });
 
-// src/utils/generationContext.ts
-import { AsyncLocalStorage } from "async_hooks";
-import { isAbsolute, resolve } from "path";
-function runWithBaseDir(baseDir, callback) {
-  return baseDir === void 0 ? callback() : baseDirStorage.run(resolve(baseDir), callback);
-}
-function resolveFromBaseDir(filePath) {
-  const base = baseDirStorage.getStore();
-  if (!base || isAbsolute(filePath)) return filePath;
-  return resolve(base, filePath);
-}
-function runWithWarnings(warnings, callback) {
-  return warnings === void 0 ? callback() : warningsStorage.run(warnings, callback);
-}
-function reportWarning(component, code, message, context) {
-  const warnings = warningsStorage.getStore();
-  if (warnings) {
-    warnings.push({
-      component,
-      message,
-      severity: "warning",
-      context: { code, ...context }
-    });
-    return;
-  }
-  console.warn(`[json-to-docx] [${code}] ${message}`);
-}
-var generationDateStorage, baseDirStorage, warningsStorage;
-var init_generationContext = __esm({
-  "src/utils/generationContext.ts"() {
-    "use strict";
-    generationDateStorage = new AsyncLocalStorage();
-    baseDirStorage = new AsyncLocalStorage();
-    warningsStorage = new AsyncLocalStorage();
-  }
-});
-
 // src/utils/imageUtils.ts
 import { readFileSync } from "fs";
 import { availableParallelism } from "os";
@@ -4354,15 +4357,15 @@ function canonicalizeEmbeddedFontKeys(zip) {
   const targets = /* @__PURE__ */ new Map();
   for (const [relationship] of rels.matchAll(/<Relationship\b[^>]*>/g)) {
     const id = /\bId="([^"]+)"/.exec(relationship)?.[1];
-    const target = /\bTarget="([^"]+)"/.exec(relationship)?.[1];
-    if (id && target) targets.set(id, target);
+    const target2 = /\bTarget="([^"]+)"/.exec(relationship)?.[1];
+    if (id && target2) targets.set(id, target2);
   }
   const rekey = /* @__PURE__ */ new Map();
   const parts = [];
   for (const { id, key } of embeds) {
-    const target = targets.get(id);
-    if (!target) continue;
-    const name = target.startsWith("/") ? target.slice(1) : posix.normalize(posix.join("word", target));
+    const target2 = targets.get(id);
+    if (!target2) continue;
+    const name = target2.startsWith("/") ? target2.slice(1) : posix.normalize(posix.join("word", target2));
     const part = zip.getEntry(name);
     if (!part) continue;
     const font = xorFontKey(part.getData(), key);
@@ -5383,7 +5386,7 @@ function chromeSlots(set, Part, resources) {
     const part = set[slot];
     if (part) {
       out[slot] = new Part({
-        children: emitOutsideBody(() => partChildren(part, resources))
+        children: part.children.length > 0 ? emitOutsideBody(() => partChildren(part, resources)) : [new Paragraph2({ style: Part === Header ? "Header" : "Footer" })]
       });
     }
   }
@@ -6619,15 +6622,16 @@ function section(value, ctx, closesDocument = false) {
       grid: { type: "default", linePitch: 360, charSpace: 0 }
     },
     children: sectionChildren2(value, ctx, closesDocument),
-    ...value.headers ? { headers: headerFooterSet(value.headers, ctx) } : {},
-    ...value.footers ? { footers: headerFooterSet(value.footers, ctx) } : {}
+    ...value.headers ? { headers: headerFooterSet(value.headers, "Header", ctx) } : {},
+    ...value.footers ? { footers: headerFooterSet(value.footers, "Footer", ctx) } : {}
   };
 }
-function headerFooterSet(set, ctx) {
+function headerFooterSet(set, style, ctx) {
   const out = {};
   for (const slot of ["default", "first", "even"]) {
     const part = set[slot];
-    if (part) out[slot] = part.children.map((child) => block(child, ctx));
+    if (!part) continue;
+    out[slot] = part.children.length > 0 ? part.children.map((child) => block(child, ctx)) : [{ paragraph: { style, children: [] } }];
   }
   return out;
 }
@@ -7068,6 +7072,7 @@ import {
 import { assertRendererSupports } from "@json-to-office/shared/rendering";
 
 // src/core/fontResolution.ts
+init_generationContext();
 import {
   collectFontNamesFromDocx,
   validateFontReferences,
@@ -7121,8 +7126,14 @@ async function resolveDocumentFonts(document, theme, fonts, warnings, forceMater
   if (!fonts?.onResolved && !forceMaterialize) return [];
   const registry2 = new FontRegistry({
     // Spread keeps baseDir/googleFonts/mode/substitution intact for
-    // materializeSource; extraEntries carries the merged registry.
-    opts: { ...fonts, extraEntries: registryEntries },
+    // materializeSource; extraEntries carries the merged registry. Without a
+    // `fonts.baseDir` of its own, kind:"file" sources resolve against the
+    // render's baseDir, as images do — not against process.cwd().
+    opts: {
+      ...fonts,
+      baseDir: fonts?.baseDir ?? getBaseDir(),
+      extraEntries: registryEntries
+    },
     fileLoader: loadFileFontSource,
     variableLoader: fetchVariableFontSource,
     diskCache: fonts?.googleFonts?.cacheDir ? new FontDiskCache(fonts.googleFonts.cacheDir) : void 0
@@ -7445,11 +7456,11 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
   );
   let fontsRejected = false;
   const requestFonts = () => fontsRejected || !options.fonts?.length ? void 0 : options.fonts;
-  const rasterizeOne = async (target) => {
+  const rasterizeOne = async (target2) => {
     const fonts = requestFonts();
     const call = (withFonts) => rasterizeVisualSlide(
-      target.presentation,
-      target.dpi,
+      target2.presentation,
+      target2.dpi,
       void 0,
       serviceConfig,
       options.baseDir,
@@ -7473,8 +7484,8 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
   const rasterizeIndividually = async (chunk) => {
     await Promise.all(
       chunk.map(
-        (target) => limit(async () => {
-          map.set(target.key, await rasterizeOne(target));
+        (target2) => limit(async () => {
+          map.set(target2.key, await rasterizeOne(target2));
         })
       )
     );
@@ -7483,9 +7494,9 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
     for (const chunk of chunksOf(unique, MAX_RASTERIZE_BATCH_SLIDES)) {
       try {
         const response = await serviceConfig.renderBatch({
-          slides: chunk.map((target) => ({
-            presentation: target.presentation,
-            dpi: target.dpi
+          slides: chunk.map((target2) => ({
+            presentation: target2.presentation,
+            dpi: target2.dpi
           })),
           ...options.baseDir !== void 0 && { baseDir: options.baseDir },
           ...options.fonts?.length ? { fonts: [...options.fonts] } : {}
@@ -7500,8 +7511,8 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
           await rasterizeIndividually(chunk);
         } else {
           const message = toErrorMessage(error);
-          for (const target of chunk) {
-            map.set(target.key, { ok: false, error: message });
+          for (const target2 of chunk) {
+            map.set(target2.key, { ok: false, error: message });
           }
         }
       }
@@ -7524,9 +7535,9 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
         url: serverUrl,
         path: "/rasterize/batch",
         body: {
-          slides: chunk.map((target) => ({
-            presentation: target.presentation,
-            dpi: target.dpi
+          slides: chunk.map((target2) => ({
+            presentation: target2.presentation,
+            dpi: target2.dpi
           })),
           ...options.baseDir !== void 0 && { baseDir: options.baseDir },
           ...fonts?.length ? { fonts } : {}
@@ -7569,6 +7580,49 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
   return map;
 }
 
+// src/core/nodeOrigin.ts
+var NODE_ORIGIN = Symbol("json-to-office.nodeOrigin");
+function isComponentNode(value) {
+  return typeof value.name === "string" && "props" in value;
+}
+function isPlainRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function tagNodeOrigins(root) {
+  const visit = (value, path4) => {
+    if (Array.isArray(value)) {
+      return value.map((item, index) => visit(item, join(path4, index)));
+    }
+    if (!isPlainRecord(value)) return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = visit(item, join(path4, key));
+    }
+    if (path4 !== "" && isComponentNode(value)) {
+      out[NODE_ORIGIN] = {
+        standardPath: path4,
+        kind: value.name
+      };
+    }
+    return out;
+  };
+  return visit(root, "");
+}
+function join(path4, key) {
+  return path4 === "" ? String(key) : `${path4}.${key}`;
+}
+function nodeOrigin(node) {
+  if (!node || typeof node !== "object") return void 0;
+  return node[NODE_ORIGIN];
+}
+function withNodeOrigin(original, next) {
+  const origin = nodeOrigin(original);
+  if (origin) next[NODE_ORIGIN] = origin;
+  return next;
+}
+
 // src/core/componentTransform.ts
 async function transformComponents(doc, replace) {
   return await walk(doc, replace);
@@ -7634,7 +7688,7 @@ function withNodeIdentity(original, replacement) {
   const out = { ...replacement };
   if (original.id !== void 0) out.id = original.id;
   if (original.enabled !== void 0) out.enabled = original.enabled;
-  return out;
+  return withNodeOrigin(original, out);
 }
 function containsComponent(root, name) {
   const seen = /* @__PURE__ */ new WeakSet();
@@ -7708,15 +7762,7 @@ async function generateChart(config, servicesConfig, warnings, cache) {
   }
   const serverUrl = effectiveChartServerUrl(config, servicesConfig);
   assertExportServerAllowed(serverUrl, servicesConfig, warnings);
-  const requestBody = {
-    infile: config.options,
-    type: "png",
-    b64: true,
-    scale: config.scale,
-    // Forward resources verbatim only when present so the payload stays
-    // byte-identical to before for callers that omit it.
-    ...config.resources ? { resources: config.resources } : {}
-  };
+  const requestBody = chartRequestBody(config);
   return sendChartRequest({
     cache,
     serverUrl,
@@ -7834,15 +7880,32 @@ function withChartFontFaces(config, theme, faces) {
     theme.fonts.heading.family
   ]);
 }
-async function renderChartToImageProps(props, theme, servicesConfig, chartFonts, warnings, cache) {
-  const config = withChartFontFaces(
+function resolveChartConfig(props, theme, fonts) {
+  return withChartFontFaces(
     withThemeTypography(
       withThemeColors(withThemePresets(props, theme), theme),
       theme
     ),
     theme,
-    chartFonts
+    fonts
   );
+}
+function chartRequestBody(config) {
+  return {
+    infile: config.options,
+    type: "png",
+    b64: true,
+    scale: config.scale,
+    // Forward resources verbatim only when present so the payload stays
+    // byte-identical to before for callers that omit it.
+    ...config.resources ? { resources: config.resources } : {}
+  };
+}
+function resolveChartRequest(props, renderTheme, fontFaces) {
+  return chartRequestBody(resolveChartConfig(props, renderTheme, fontFaces));
+}
+async function renderChartToImageProps(props, theme, servicesConfig, chartFonts, warnings, cache) {
+  const config = resolveChartConfig(props, theme, chartFonts);
   const chart = await generateChart(config, servicesConfig, warnings, cache);
   const hasConfigDimensions = config.width !== void 0 || config.height !== void 0;
   return {
@@ -10559,12 +10622,12 @@ function parseLinks(normalized, options) {
       continue;
     }
     const [, linkText] = match;
-    const target = decodeEscapes(match[2]);
+    const target2 = decodeEscapes(match[2]);
     out.push({
       kind: "hyperlink",
       // A `#anchor` target names a bookmark in this document and needs no
       // relationship; anything else leaves the document.
-      target: target.startsWith("#") ? { kind: "bookmark", anchor: target.slice(1) } : { kind: "external", url: target },
+      target: target2.startsWith("#") ? { kind: "bookmark", anchor: target2.slice(1) } : { kind: "external", url: target2 },
       children: parseDecorated(linkText, options)
     });
   }
@@ -10820,6 +10883,7 @@ function compileDocument(structure, layout2, warnings = [], images = /* @__PURE_
     numberedItems: outline.numberedItems,
     tocEntries: outline.entries,
     images,
+    imageOrigins: /* @__PURE__ */ new WeakMap(),
     generatedAt: structure.metadata.date
   };
   ctx.features.require("paragraphs", "sections");
@@ -10873,9 +10937,19 @@ function compileDocument(structure, layout2, warnings = [], images = /* @__PURE_
     ir,
     required: ctx.features.list(),
     warnings: ctx.warnings,
-    unsupported: ctx.unsupported
+    unsupported: ctx.unsupported,
+    imageOrigins: ctx.imageOrigins
   };
 }
+function recordImageOrigin(ctx, component, images) {
+  const origin = nodeOrigin(component);
+  if (!origin) return;
+  for (const image of images) {
+    if (image.kind === "image" || image.kind === "picture") {
+      ctx.imageOrigins.set(image, origin);
+    }
+  }
+}
 var AFTER_TABLE_TWIPS = 120;
 var BEFORE_TABLE_TWIPS = 240;
 var BODY_STYLE_IDS = /* @__PURE__ */ new Set([void 0, "Normal"]);
@@ -11203,6 +11277,7 @@ function compileChromeImage(component, scope) {
     heightEmu: pixelsToEmu(size.height),
     ...props.floating ? { floating: compileFloating(props.floating, ctx, path4) } : {}
   };
+  recordImageOrigin(ctx, component, [image]);
   return [
     {
       kind: "paragraph",
@@ -12702,6 +12777,7 @@ function compileVisual(component, scope) {
     nativeVisualDeps(ctx, path4)
   );
   if (!group) return [];
+  recordImageOrigin(ctx, component, group.children);
   const size = visualPlacementPixels(props, group.canvas, {
     widthPx: Math.round(twipsToPixels(scope.measureTwips)),
     heightPx: Math.round(twipsToPixels(getAvailableHeightTwips(ctx.theme)))
@@ -12828,6 +12904,7 @@ function compileImage2(component, scope) {
     ...typeof props.alt === "string" && props.alt ? { altText: props.alt } : {},
     ...props.floating ? { floating: compileFloating(props.floating, ctx, path4) } : {}
   };
+  recordImageOrigin(ctx, component, [image]);
   ctx.features.require("images", path4);
   if (props.floating) ctx.features.require("floating-images", path4);
   const spacing = {};
@@ -13592,6 +13669,7 @@ function cellVisual(component, scope) {
     nativeVisualDeps(ctx, path4)
   );
   if (!group) return [];
+  recordImageOrigin(ctx, component, group.children);
   const size = visualPlacementPixels(props, group.canvas, {
     widthPx: CELL_DRAWING_REFERENCE.width,
     heightPx: CELL_DRAWING_REFERENCE.height
@@ -13637,14 +13715,14 @@ function cellImage(component, base, ctx) {
   const mediaType = detectImageType(source, loaded.contentType);
   if (mediaType === "svg") ctx.features.require("svg-images", "table");
   ctx.features.require("images", "table");
-  return [
-    {
-      kind: "image",
-      resourceId: declareResource(loaded, mediaType, ctx),
-      widthEmu: pixelsToEmu(size.width),
-      heightEmu: pixelsToEmu(size.height)
-    }
-  ];
+  const image = {
+    kind: "image",
+    resourceId: declareResource(loaded, mediaType, ctx),
+    widthEmu: pixelsToEmu(size.width),
+    heightEmu: pixelsToEmu(size.height)
+  };
+  recordImageOrigin(ctx, component, [image]);
+  return [image];
 }
 function placeholderFormatting(base) {
   return {
@@ -16394,7 +16472,7 @@ async function compileDocumentScoped(document, options, warnings) {
   const embeddedFonts = embedding ? selectEmbeddedFonts(resolvedFonts, warnings) : [];
   const visualFonts = hasVisual ? toRasterizeFontFaces(resolvedFonts, warnings) : [];
   const chartFonts = hasHighcharts ? toChartFontFaces(resolvedFonts) : [];
-  const desugared = await desugarExternals(context.document, {
+  const desugared = await desugarExternals(tagNodeOrigins(context.document), {
     theme: prepared.model.document.theme,
     ...options.services ? { services: options.services } : {},
     ...options.baseDir !== void 0 ? { baseDir: options.baseDir } : {},
@@ -16432,6 +16510,7 @@ async function compileDocumentScoped(document, options, warnings) {
     warnings: compiled.warnings,
     required: compiled.required,
     unsupported: compiled.unsupported,
+    imageOrigins: compiled.imageOrigins,
     embeddedFonts
   };
 }
@@ -16459,7 +16538,12 @@ async function renderScoped(document, options, warnings) {
     ...compiled.embeddedFonts.length > 0 ? { embeddedFonts: compiled.embeddedFonts } : {},
     warnings: compiled.warnings
   });
-  return { buffer: Buffer.from(bytes), warnings: compiled.warnings };
+  return {
+    buffer: Buffer.from(bytes),
+    warnings: compiled.warnings,
+    ir: compiled.ir,
+    imageOrigins: compiled.imageOrigins
+  };
 }
 function toDate(value) {
   return value instanceof Date ? value : new Date(value);
@@ -16482,7 +16566,7 @@ import {
 
 // src/json/filesystem.ts
 import { promises as fs3 } from "fs";
-import { join, resolve as resolve2, isAbsolute as isAbsolute2 } from "path";
+import { join as join2, resolve as resolve2, isAbsolute as isAbsolute2 } from "path";
 async function loadJsonDefinition(filePath) {
   try {
     const absolutePath = isAbsolute2(filePath) ? filePath : resolve2(filePath);
@@ -18053,7 +18137,7 @@ import {
 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";
+import { dirname as dirname2, join as join3 } from "path";
 
 // src/templates/blueprints/client-report.docx.blueprint.json
 var client_report_docx_blueprint_default = {
@@ -19248,11 +19332,11 @@ function scanned(known) {
     return [];
   }
   const directory = [
-    join2(here, "../templates/blueprints"),
-    join2(here, "templates/blueprints")
+    join3(here, "../templates/blueprints"),
+    join3(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) => {
+  return readdirSync(directory).filter((file) => file.endsWith(".docx.blueprint.json")).map((file) => JSON.parse(readFileSync2(join3(directory, file), "utf8"))).filter((candidate) => {
     const id = candidate?.id;
     return !(typeof id === "string" && id in known);
   });
@@ -19432,6 +19516,36 @@ var textSpaceAfterComponent = createComponent({
   }
 });
 
+// src/components/highchartsOptions.ts
+init_layoutUtils();
+function chartRenderTheme(input) {
+  const document = {
+    name: "docx",
+    props: { ...input.documentProps },
+    children: []
+  };
+  const context = resolveThemeContext(document, {
+    ...input.fonts ? { fonts: input.fonts } : {},
+    warnings: [],
+    resolveNamedTheme: () => input.theme
+  });
+  const { theme } = resolveDocumentTree(context.document, context.theme);
+  return themeForSectionPage(theme, input.page);
+}
+function resolveHighchartsRequest(input) {
+  const props = {
+    options: input.options,
+    ...input.width !== void 0 && { width: input.width },
+    ...input.height !== void 0 && { height: input.height },
+    ...input.scale !== void 0 && { scale: input.scale },
+    ...input.resources !== void 0 && { resources: input.resources }
+  };
+  return resolveChartRequest(props, chartRenderTheme(input), input.fontFaces);
+}
+function resolveHighchartsOptions(input) {
+  return resolveHighchartsRequest(input).infile;
+}
+
 // src/plugin/createDocumentGenerator.ts
 init_themes();
 
@@ -19661,7 +19775,280 @@ function mergeSchemas(customComponents, standardSchemas) {
   };
 }
 
+// src/core/renderManifest.ts
+init_units();
+import AdmZip6 from "adm-zip";
+import { posix as posix2 } from "path";
+var HEADER_FOOTER_TYPES = ["default", "first", "even"];
+function buildRenderManifest(buffer, ir, imageOrigins, sourceOrigins = /* @__PURE__ */ new Map()) {
+  try {
+    return {
+      ok: true,
+      manifest: collect(buffer, ir, imageOrigins, sourceOrigins)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function collect(buffer, ir, imageOrigins, sourceOrigins) {
+  const zip = new AdmZip6(buffer);
+  const read = (entry) => zip.getEntry(entry)?.getData().toString("utf8");
+  const media = /* @__PURE__ */ new Map();
+  const mediaHash = (path4) => {
+    let hash = media.get(path4);
+    if (hash === void 0) {
+      const entry = zip.getEntry(path4);
+      if (!entry) throw new Error(`the package has no ${path4}`);
+      hash = sha256Hex(new Uint8Array(entry.getData()));
+      media.set(path4, hash);
+    }
+    return hash;
+  };
+  const resources = new Map(ir.resources.map((r) => [r.id, r]));
+  const manifest = [];
+  const pair = (part, partPath, xml, images) => {
+    const rels = relationships(read(relsPathOf(partPath)), partPath);
+    const blips = readBlips(xml);
+    if (blips.length !== images.length) {
+      throw new Error(
+        `${partPath} embeds ${blips.length} image(s) where the IR placed ${images.length}`
+      );
+    }
+    blips.forEach((blip, index) => {
+      const image = images[index];
+      const mediaPath = target(rels, blip.embed, partPath);
+      const sha256 = mediaHash(mediaPath);
+      const resource = resources.get(image.resourceId);
+      if (!resource || !matchesResource(resource, blip, sha256, rels, partPath, mediaHash)) {
+        throw new Error(
+          `image ${index + 1} of ${partPath} (${mediaPath}) does not hold the bytes of IR resource ${image.resourceId}`
+        );
+      }
+      const origin = imageOrigins.get(image);
+      if (!origin) {
+        throw new Error(
+          `image ${index + 1} of ${partPath} has no standard-definition origin`
+        );
+      }
+      const source = sourceOriginOf(origin.standardPath, sourceOrigins);
+      manifest.push({
+        part,
+        partPath,
+        mediaPath,
+        sha256,
+        standardPath: origin.standardPath,
+        kind: origin.kind,
+        ...source && {
+          sourcePath: source.sourcePath,
+          sourceKind: source.sourceKind
+        }
+      });
+    });
+  };
+  const documentPath = "word/document.xml";
+  const documentXml = read(documentPath);
+  if (documentXml === void 0)
+    throw new Error(`the package has no ${documentPath}`);
+  pair(
+    "body",
+    documentPath,
+    documentXml,
+    ir.sections.flatMap((section2) => blockImages(section2.children))
+  );
+  const sectPrs = sectionProperties(documentXml);
+  if (sectPrs.length !== ir.sections.length) {
+    throw new Error(
+      `${documentPath} has ${sectPrs.length} section(s) where the IR has ${ir.sections.length}`
+    );
+  }
+  const documentRels = relationships(
+    read(relsPathOf(documentPath)),
+    documentPath
+  );
+  const seen = /* @__PURE__ */ new Set();
+  ir.sections.forEach((section2, index) => {
+    const references = chromeReferences(sectPrs[index]);
+    for (const part of ["header", "footer"]) {
+      const set = part === "header" ? section2.headers : section2.footers;
+      for (const type of HEADER_FOOTER_TYPES) {
+        const id = references.get(`${part}:${type}`);
+        if (id === void 0) continue;
+        const partPath = target(documentRels, id, documentPath);
+        if (seen.has(partPath)) continue;
+        seen.add(partPath);
+        const xml = read(partPath);
+        if (xml === void 0)
+          throw new Error(`the package has no ${partPath}`);
+        pair(part, partPath, xml, blockImages(set?.[type]?.children ?? []));
+      }
+    }
+  });
+  return manifest;
+}
+function sourceOriginOf(standardPath, sourceOrigins) {
+  if (sourceOrigins.size === 0) return void 0;
+  const segments = standardPath.split(".");
+  for (let n = segments.length; n > 0; n--) {
+    const hit = sourceOrigins.get(segments.slice(0, n).join("."));
+    if (hit) return hit;
+  }
+  return void 0;
+}
+function matchesResource(resource, blip, sha256, rels, partPath, mediaHash) {
+  if (sha256 === resource.sha256) return true;
+  if (resource.mediaType !== "svg" || blip.svgEmbed === void 0) return false;
+  return mediaHash(target(rels, blip.svgEmbed, partPath)) === resource.sha256;
+}
+function blockImages(blocks) {
+  const out = [];
+  const visitBlocks = (items) => {
+    for (const block2 of items) {
+      if (block2.kind === "paragraph") visitParagraph(block2);
+      else if (block2.kind === "table") {
+        for (const row of block2.rows) {
+          for (const cell of row.cells) visitBlocks(cell.children);
+        }
+      }
+    }
+  };
+  const visitParagraph = (paragraph2) => visitInlines(paragraph2.children);
+  const visitInlines = (inlines) => {
+    for (const inline of inlines) {
+      switch (inline.kind) {
+        case "image":
+          out.push(inline);
+          break;
+        case "drawingGroup":
+          for (const child of inline.children) {
+            if (child.kind === "picture") out.push(child);
+          }
+          break;
+        case "shape":
+          inline.children.forEach(visitParagraph);
+          break;
+        case "hyperlink":
+        case "revision":
+          visitInlines(inline.children);
+          break;
+        default:
+          break;
+      }
+    }
+  };
+  visitBlocks(blocks);
+  return out;
+}
+function readBlips(xml) {
+  const body = xml.replace(/<mc:Fallback\b[\s\S]*?<\/mc:Fallback>/g, "");
+  const blips = [];
+  const pattern = /<a:blip\b([^>]*?)(?:\/>|>([\s\S]*?)<\/a:blip>)/g;
+  for (const match of body.matchAll(pattern)) {
+    const embed = /\br:embed="([^"]+)"/.exec(match[1])?.[1];
+    if (embed === void 0) continue;
+    const svgEmbed = match[2] ? /<asvg:svgBlip\b[^>]*\br:embed="([^"]+)"/.exec(match[2])?.[1] : void 0;
+    blips.push(svgEmbed === void 0 ? { embed } : { embed, svgEmbed });
+  }
+  return blips;
+}
+function sectionProperties(xml) {
+  return [...xml.matchAll(/<w:sectPr\b(?:[^>]*\/>|[\s\S]*?<\/w:sectPr>)/g)].map(
+    (m) => m[0]
+  );
+}
+function chromeReferences(sectPr) {
+  const out = /* @__PURE__ */ new Map();
+  for (const match of sectPr.matchAll(
+    /<w:(header|footer)Reference\b([^>]*)\/?>/g
+  )) {
+    const type = attribute(match[2], "w:type") ?? "default";
+    const id = attribute(match[2], "r:id");
+    if (id !== void 0) out.set(`${match[1]}:${type}`, id);
+  }
+  return out;
+}
+function relsPathOf(partPath) {
+  return posix2.join(
+    posix2.dirname(partPath),
+    "_rels",
+    `${posix2.basename(partPath)}.rels`
+  );
+}
+function relationships(xml, partPath) {
+  const out = /* @__PURE__ */ new Map();
+  if (xml === void 0) return out;
+  for (const match of xml.matchAll(/<Relationship\b([^>]*)\/?>/g)) {
+    const id = attribute(match[1], "Id");
+    const target2 = attribute(match[1], "Target");
+    if (id !== void 0 && target2 !== void 0) out.set(id, target2);
+  }
+  if (out.size === 0 && /<Relationship\b/.test(xml)) {
+    throw new Error(`the relationships of ${partPath} could not be read`);
+  }
+  return out;
+}
+function target(rels, id, partPath) {
+  const raw = rels.get(id);
+  if (raw === void 0) {
+    throw new Error(`${partPath} references an unknown relationship ${id}`);
+  }
+  return raw.startsWith("/") ? raw.slice(1) : posix2.normalize(posix2.join(posix2.dirname(partPath), raw));
+}
+function attribute(attributes, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|\\s)${escaped}="([^"]*)"`).exec(attributes)?.[1];
+}
+
 // src/plugin/createDocumentGenerator.ts
+var RENDER_MANIFEST_UNAVAILABLE = "W_DOCX_RENDER_MANIFEST_UNAVAILABLE";
+var ROOT_POSITION = {
+  standard: "children",
+  standardBase: 0,
+  preserved: "children",
+  preservedBase: 0
+};
+var DETACHED_POSITION = {
+  standard: null,
+  standardBase: 0,
+  preserved: null,
+  preservedBase: 0
+};
+function joinPath(path4, key) {
+  return path4 === null ? null : `${path4}.${key}`;
+}
+function blockSourceOrigins(standard, preserved, preserveSet) {
+  const origins = /* @__PURE__ */ new Map();
+  const visit = (std, kept, path4) => {
+    if (!std || !kept || typeof std !== "object" || typeof kept !== "object")
+      return;
+    const keptNode = kept;
+    const stdNode = std;
+    if (path4 !== "" && typeof keptNode.name === "string" && preserveSet.has(keptNode.name) && stdNode.name === "group") {
+      origins.set(path4, { sourcePath: path4, sourceKind: keptNode.name });
+      return;
+    }
+    for (const [key, value] of Object.entries(keptNode)) {
+      if (key in stdNode) {
+        visit(stdNode[key], value, path4 === "" ? key : `${path4}.${key}`);
+      }
+    }
+  };
+  visit(standard, preserved, "");
+  return origins;
+}
+function manifestOf(buffer, ir, imageOrigins, sourceOrigins, warnings) {
+  const built = buildRenderManifest(buffer, ir, imageOrigins, sourceOrigins);
+  if (built.ok) return built.manifest;
+  warnings.push({
+    component: "docx",
+    severity: "warning",
+    message: `No render manifest: ${built.reason}.`,
+    context: { code: RENDER_MANIFEST_UNAVAILABLE, reason: built.reason }
+  });
+  return void 0;
+}
 function createBuilderImpl(state) {
   const componentMap = new Map(state.components.map((c) => [c.name, c]));
   function resolveDocumentTheme(themeName, warnings, authored) {
@@ -19690,7 +20077,7 @@ function createBuilderImpl(state) {
       warnings
     });
   }
-  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, validateEmitted, depth = 0) {
+  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, validateEmitted, at, origins, depth = 0) {
     if (depth > 20) {
       throw new Error(
         "Maximum component nesting depth exceeded (20). Check for circular component references."
@@ -19698,6 +20085,8 @@ function createBuilderImpl(state) {
     }
     const standardOut = [];
     const preservedOut = [];
+    const nextStandardPath = () => joinPath(at.standard, at.standardBase + standardOut.length);
+    const nextPreservedPath = () => joinPath(at.preserved, at.preservedBase + preservedOut.length);
     for (const componentData of components) {
       const componentName = componentData?.name;
       if (!componentName) {
@@ -19731,6 +20120,8 @@ function createBuilderImpl(state) {
               warningsCollector,
               resolvedTheme,
               validateEmitted,
+              DETACHED_POSITION,
+              origins,
               depth + 1
             );
             nestedChildren = nested.standard;
@@ -19754,16 +20145,34 @@ function createBuilderImpl(state) {
           if (validateEmitted) {
             validateEmitted(resultComponents, versionLabel);
           }
+          const preservedHere = preserveSet?.has(componentName) === true;
+          const preservedPath = nextPreservedPath();
+          const firstIndex = at.standardBase + standardOut.length;
           const processedResult = await processDocumentComponents(
             resultComponents,
             preserveSet,
             warningsCollector,
             resolvedTheme,
             validateEmitted,
+            {
+              standard: at.standard,
+              standardBase: firstIndex,
+              preserved: preservedHere ? null : at.preserved,
+              preservedBase: at.preservedBase + preservedOut.length
+            },
+            origins,
             depth + 1
           );
+          if (preservedHere && at.standard !== null && preservedPath !== null) {
+            processedResult.standard.forEach((_, index) => {
+              origins.set(`${at.standard}.${firstIndex + index}`, {
+                sourcePath: preservedPath,
+                sourceKind: componentName
+              });
+            });
+          }
           standardOut.push(...processedResult.standard);
-          if (preserveSet && preserveSet.has(componentName)) {
+          if (preservedHere) {
             preservedOut.push(componentData);
           } else {
             preservedOut.push(...processedResult.preserved);
@@ -19784,12 +20193,21 @@ function createBuilderImpl(state) {
         }
       } else {
         if ("children" in componentData && Array.isArray(componentData.children)) {
+          const standardPath = nextStandardPath();
+          const preservedPath = nextPreservedPath();
           const processedNested = await processDocumentComponents(
             componentData.children,
             preserveSet,
             warningsCollector,
             resolvedTheme,
             validateEmitted,
+            {
+              standard: joinPath(standardPath, "children"),
+              standardBase: 0,
+              preserved: joinPath(preservedPath, "children"),
+              preservedBase: 0
+            },
+            origins,
             depth + 1
           );
           standardOut.push({
@@ -19953,6 +20371,7 @@ function createBuilderImpl(state) {
       );
       const [modedDoc2] = normalizeDocument(expanded.document);
       return {
+        sourceOrigins: preserveSet ? blockSourceOrigins(modedDoc2, expanded.preserved, preserveSet) : /* @__PURE__ */ new Map(),
         modedRoot,
         modedTheme,
         themeName,
@@ -19968,12 +20387,15 @@ function createBuilderImpl(state) {
         }
       };
     }
+    const sourceOrigins = /* @__PURE__ */ new Map();
     const processed = await processDocumentComponents(
       modedRoot.children || [],
       preserveSet,
       warnings,
       modedTheme,
-      validateEmitted
+      validateEmitted,
+      ROOT_POSITION,
+      sourceOrigins
     );
     const processedDocument = {
       ...modedRoot,
@@ -19987,7 +20409,8 @@ function createBuilderImpl(state) {
       processed,
       modedDoc,
       warnings,
-      preserveSet
+      preserveSet,
+      sourceOrigins
     };
   }
   async function expandStandardDefinition(document, options) {
@@ -20044,22 +20467,33 @@ function createBuilderImpl(state) {
     const deterministic = options?.deterministic ?? state.deterministic;
     const generatedAt = options?.generatedAt ?? state.generatedAt;
     const renderer = options?.renderer ?? state.renderer ?? prepared.renderer;
-    const { buffer } = await generateBufferViaIr(context.document, {
-      context,
-      prepared,
-      ...state.services ? { services: state.services } : {},
-      ...state.fonts ? { fonts: state.fonts } : {},
-      ...baseDir !== void 0 ? { baseDir } : {},
-      ...deterministic !== void 0 ? { deterministic } : {},
-      ...generatedAt !== void 0 ? { generatedAt } : {},
-      ...renderer !== void 0 ? { renderer } : {},
+    const { buffer, ir, imageOrigins } = await generateBufferViaIr(
+      context.document,
+      {
+        context,
+        prepared,
+        ...state.services ? { services: state.services } : {},
+        ...state.fonts ? { fonts: state.fonts } : {},
+        ...baseDir !== void 0 ? { baseDir } : {},
+        ...deterministic !== void 0 ? { deterministic } : {},
+        ...generatedAt !== void 0 ? { generatedAt } : {},
+        ...renderer !== void 0 ? { renderer } : {},
+        warnings
+      }
+    );
+    const renderManifest = manifestOf(
+      buffer,
+      ir,
+      imageOrigins,
+      /* @__PURE__ */ new Map(),
       warnings
-    });
+    );
     return {
       buffer,
       warnings: warnings.length > 0 ? warnings : null,
       standardDefinition: context.document,
-      preservedDefinition: void 0
+      preservedDefinition: void 0,
+      ...renderManifest && { renderManifest }
     };
   }
   async function generateBuffer(document, options) {
@@ -20075,13 +20509,14 @@ function createBuilderImpl(state) {
         sourceMap,
         blockPaths,
         warnings,
-        preserveSet
+        preserveSet,
+        sourceOrigins
       } = await expandDocument(document, options);
       const baseDir = options?.baseDir ?? state.baseDir;
       const deterministic = options?.deterministic ?? state.deterministic;
       const generatedAt = options?.generatedAt ?? state.generatedAt;
       const renderer = options?.renderer ?? state.renderer ?? modedRoot.renderer;
-      const { buffer } = await generateBufferViaIr(modedDoc, {
+      const { buffer, ir, imageOrigins } = 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: {
@@ -20103,11 +20538,19 @@ function createBuilderImpl(state) {
         ...modedRoot,
         children: processed.preserved
       } : void 0;
+      const renderManifest = manifestOf(
+        buffer,
+        ir,
+        imageOrigins,
+        sourceOrigins,
+        warnings
+      );
       return {
         buffer,
         warnings: warnings.length > 0 ? warnings : null,
         standardDefinition: modedDoc,
-        preservedDefinition
+        preservedDefinition,
+        ...renderManifest && { renderManifest }
       };
     } catch (error) {
       if (state.debug) {
@@ -20117,7 +20560,13 @@ function createBuilderImpl(state) {
     }
   }
   async function generateFile(document, outputPath, options) {
-    const { buffer, warnings, standardDefinition, preservedDefinition } = await generateBuffer(document, options);
+    const {
+      buffer,
+      warnings,
+      standardDefinition,
+      preservedDefinition,
+      renderManifest
+    } = await generateBuffer(document, options);
     const fs6 = await import("fs/promises");
     await fs6.writeFile(outputPath, new Uint8Array(buffer));
     let preservedOutputPath;
@@ -20138,7 +20587,8 @@ function createBuilderImpl(state) {
       warnings,
       standardDefinition,
       preservedDefinition,
-      preservedOutputPath
+      preservedOutputPath,
+      ...renderManifest && { renderManifest }
     };
   }
   function getComponentNames() {
@@ -20234,6 +20684,7 @@ export {
   DOCX_DEFAULT_QUALITY_PROFILE,
   DOCX_QUALITY_PROFILES,
   DOCX_QUALITY_RULES,
+  RENDER_MANIFEST_UNAVAILABLE,
   ThemeFileError,
   ThemeParseError,
   ThemeValidationError,
@@ -20300,6 +20751,8 @@ export {
   resetChartRequestStats,
   resetVisualPrepassStats,
   resolveDocxQualityProfile,
+  resolveHighchartsOptions,
+  resolveHighchartsRequest,
   runExample,
   themes,
   toAuthoredPointer,