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

package/dist/plugin/example/index.js

@@ -3,9 +3,9 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 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/themes/defaults.ts
@@ -4329,15 +4329,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);
@@ -5358,7 +5358,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" })]
       });
     }
   }
@@ -6594,15 +6594,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;
 }
@@ -7712,11 +7713,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,
@@ -7740,8 +7741,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));
         })
       )
     );
@@ -7750,9 +7751,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] } : {}
@@ -7767,8 +7768,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 });
           }
         }
       }
@@ -7791,9 +7792,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 } : {}
@@ -7836,6 +7837,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, path3) => {
+    if (Array.isArray(value)) {
+      return value.map((item, index) => visit(item, join(path3, index)));
+    }
+    if (!isPlainRecord(value)) return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = visit(item, join(path3, key));
+    }
+    if (path3 !== "" && isComponentNode(value)) {
+      out[NODE_ORIGIN] = {
+        standardPath: path3,
+        kind: value.name
+      };
+    }
+    return out;
+  };
+  return visit(root, "");
+}
+function join(path3, key) {
+  return path3 === "" ? String(key) : `${path3}.${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);
@@ -7901,7 +7945,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();
@@ -7975,15 +8019,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,
@@ -8101,15 +8137,29 @@ 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 } : {}
+  };
+}
+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 {
@@ -10826,12 +10876,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)
     });
   }
@@ -11087,6 +11137,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");
@@ -11140,9 +11191,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"]);
@@ -11470,6 +11531,7 @@ function compileChromeImage(component, scope) {
     heightEmu: pixelsToEmu(size.height),
     ...props.floating ? { floating: compileFloating(props.floating, ctx, path3) } : {}
   };
+  recordImageOrigin(ctx, component, [image]);
   return [
     {
       kind: "paragraph",
@@ -12969,6 +13031,7 @@ function compileVisual(component, scope) {
     nativeVisualDeps(ctx, path3)
   );
   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)))
@@ -13095,6 +13158,7 @@ function compileImage2(component, scope) {
     ...typeof props.alt === "string" && props.alt ? { altText: props.alt } : {},
     ...props.floating ? { floating: compileFloating(props.floating, ctx, path3) } : {}
   };
+  recordImageOrigin(ctx, component, [image]);
   ctx.features.require("images", path3);
   if (props.floating) ctx.features.require("floating-images", path3);
   const spacing = {};
@@ -13859,6 +13923,7 @@ function cellVisual(component, scope) {
     nativeVisualDeps(ctx, path3)
   );
   if (!group) return [];
+  recordImageOrigin(ctx, component, group.children);
   const size = visualPlacementPixels(props, group.canvas, {
     widthPx: CELL_DRAWING_REFERENCE.width,
     heightPx: CELL_DRAWING_REFERENCE.height
@@ -13904,14 +13969,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 {
@@ -16466,7 +16531,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 } : {},
@@ -16504,6 +16569,7 @@ async function compileDocumentScoped(document, options, warnings) {
     warnings: compiled.warnings,
     required: compiled.required,
     unsupported: compiled.unsupported,
+    imageOrigins: compiled.imageOrigins,
     embeddedFonts
   };
 }
@@ -16531,13 +16597,291 @@ 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);
 }
 
+// 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 = (path3) => {
+    let hash = media.get(path3);
+    if (hash === void 0) {
+      const entry = zip.getEntry(path3);
+      if (!entry) throw new Error(`the package has no ${path3}`);
+      hash = sha256Hex(new Uint8Array(entry.getData()));
+      media.set(path3, 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(path3, key) {
+  return path3 === null ? null : `${path3}.${key}`;
+}
+function blockSourceOrigins(standard, preserved, preserveSet) {
+  const origins = /* @__PURE__ */ new Map();
+  const visit = (std, kept, path3) => {
+    if (!std || !kept || typeof std !== "object" || typeof kept !== "object")
+      return;
+    const keptNode = kept;
+    const stdNode = std;
+    if (path3 !== "" && typeof keptNode.name === "string" && preserveSet.has(keptNode.name) && stdNode.name === "group") {
+      origins.set(path3, { sourcePath: path3, sourceKind: keptNode.name });
+      return;
+    }
+    for (const [key, value] of Object.entries(keptNode)) {
+      if (key in stdNode) {
+        visit(stdNode[key], value, path3 === "" ? key : `${path3}.${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) {
@@ -16566,7 +16910,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."
@@ -16574,6 +16918,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) {
@@ -16607,6 +16953,8 @@ function createBuilderImpl(state) {
               warningsCollector,
               resolvedTheme,
               validateEmitted,
+              DETACHED_POSITION,
+              origins,
               depth + 1
             );
             nestedChildren = nested.standard;
@@ -16630,16 +16978,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);
@@ -16660,12 +17026,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({
@@ -16829,6 +17204,7 @@ function createBuilderImpl(state) {
       );
       const [modedDoc2] = normalizeDocument(expanded.document);
       return {
+        sourceOrigins: preserveSet ? blockSourceOrigins(modedDoc2, expanded.preserved, preserveSet) : /* @__PURE__ */ new Map(),
         modedRoot,
         modedTheme,
         themeName,
@@ -16844,12 +17220,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,
@@ -16863,7 +17242,8 @@ function createBuilderImpl(state) {
       processed,
       modedDoc,
       warnings,
-      preserveSet
+      preserveSet,
+      sourceOrigins
     };
   }
   async function expandStandardDefinition(document, options) {
@@ -16920,22 +17300,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) {
@@ -16951,13 +17342,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: {
@@ -16979,11 +17371,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) {
@@ -16993,7 +17393,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 fs4 = await import("fs/promises");
     await fs4.writeFile(outputPath, new Uint8Array(buffer));
     let preservedOutputPath;
@@ -17014,7 +17420,8 @@ function createBuilderImpl(state) {
       warnings,
       standardDefinition,
       preservedDefinition,
-      preservedOutputPath
+      preservedOutputPath,
+      ...renderManifest && { renderManifest }
     };
   }
   function getComponentNames() {