@json-to-office/core-docx 1.0.0 → 1.1.0

package/dist/index.js

@@ -2005,6 +2005,12 @@ function pointsToEighthPoints(points) {
 function inchesToTwips(inches) {
   return Math.round(inches * TWIPS_PER_INCH);
 }
+function inchesToEmu(inches) {
+  return Math.round(inches * EMU_PER_INCH);
+}
+function pointsToEmu(points) {
+  return Math.round(points * EMU_PER_INCH / 72);
+}
 function twipsToEmu(twips) {
   return Math.round(twips * EMU_PER_TWIP);
 }
@@ -2207,6 +2213,10 @@ function inlineChildren(children, resources = /* @__PURE__ */ new Map()) {
       case "shape":
         out.push(emitShape(child, resources));
         break;
+      case "drawingGroup":
+        throw new Error(
+          "the docxjs renderer has no emitter for a drawing group; this document should have been refused by the capability check"
+        );
       case "noteReference":
         out.push(
           child.noteKind === "endnote" ? new EndnoteReferenceRun(child.id) : new FootnoteReferenceRun(child.id)
@@ -2308,7 +2318,7 @@ function paragraphOptions(formatting) {
   const options = {};
   if (!formatting) return options;
   if (formatting.alignment) {
-    options.alignment = ALIGNMENT[formatting.alignment];
+    options.alignment = ALIGNMENT2[formatting.alignment];
   }
   if (formatting.spacing) {
     const spacing = {};
@@ -2542,11 +2552,11 @@ function emitBorder(border3) {
     color: border3.color?.hex ?? "000000"
   };
 }
-var ALIGNMENT, PAGE_FIELD, WRAP_TYPE, VERTICAL_ALIGN, TABLE_ANCHOR, HORIZONTAL_POSITION, VERTICAL_POSITION, BORDER_STYLE;
+var ALIGNMENT2, PAGE_FIELD, WRAP_TYPE, VERTICAL_ALIGN, TABLE_ANCHOR, HORIZONTAL_POSITION, VERTICAL_POSITION, BORDER_STYLE;
 var init_emit = __esm({
   "src/renderers/docxjs/emit.ts"() {
     "use strict";
-    ALIGNMENT = {
+    ALIGNMENT2 = {
       left: AlignmentType.LEFT,
       center: AlignmentType.CENTER,
       right: AlignmentType.RIGHT,
@@ -2669,7 +2679,7 @@ function paragraphProperties(formatting) {
     out.spacing = spacing;
   }
   if (formatting.alignment !== void 0) {
-    out.alignment = ALIGNMENT[formatting.alignment] ?? formatting.alignment;
+    out.alignment = ALIGNMENT2[formatting.alignment] ?? formatting.alignment;
   }
   if (formatting.keepNext !== void 0) out.keepNext = formatting.keepNext;
   if (formatting.keepLines !== void 0) out.keepLines = formatting.keepLines;
@@ -2798,6 +2808,15 @@ var init_features = __esm({
       "text-frames",
       /** Native shape text boxes. */
       "text-boxes",
+      /**
+       * A DrawingML group: shapes, text boxes and pictures sharing one child
+       * coordinate space, drawn as a single anchored or inline object.
+       *
+       * Separate from `text-boxes` because a lone `wps:wsp` run is a far smaller
+       * ask than `wpg:wgp` with child transforms, preset geometry and grouped
+       * pictures — a backend can plausibly have the first and not the second.
+       */
+      "drawing-groups",
       /** A table-of-contents field. */
       "toc",
       /** TOC entries baked in so an unrefreshed reader still shows them. */
@@ -3044,7 +3063,7 @@ function numberingConfig(numbering) {
       level: level.level,
       format: level.format,
       text: level.text,
-      alignment: level.alignment ? ALIGNMENT[level.alignment] : void 0,
+      alignment: level.alignment ? ALIGNMENT2[level.alignment] : void 0,
       ...level.suffix ? { suffix: level.suffix } : {},
       style: {
         ...level.indent ? {
@@ -3262,7 +3281,12 @@ var init_docxjs = __esm({
       "cached-fields",
       "shading",
       "borders",
-      "rtl"
+      "rtl",
+      // `drawing-groups` is the one exclusion that is a real backend gap rather
+      // than a slice boundary: docx.js has no `wpg:wgp`. Leaving it out is what
+      // turns a native `visual` sent to this backend into a named capability
+      // error instead of a document with the graphic missing.
+      "drawing-groups"
     ]);
     DOCXJS_CAPABILITIES = new Set(
       [...ALL_DOCX_FEATURES].filter((feature) => !NOT_YET_EMITTED.has(feature))
@@ -3373,15 +3397,15 @@ function inlineChildren2(children, ctx = emptyContext()) {
         out.push({ bookmarkEnd: { id: child.id } });
         break;
       case "image": {
-        const build = ctx.pictures.get(child.resourceId);
-        if (!build) {
-          throw new Error(
-            `no image was prepared for resource "${child.resourceId}"`
-          );
-        }
         const pending = breakOption();
         if (pending.break) out.push(pending);
-        out.push({ picture: build(child, ctx.nextDrawingId()) });
+        out.push({ picture: pictureOptions(child, ctx) });
+        break;
+      }
+      case "drawingGroup": {
+        const pending = breakOption();
+        if (pending.break) out.push(pending);
+        out.push({ wpgGroup: drawingGroupOptions(child, ctx) });
         break;
       }
       case "hyperlink":
@@ -3476,6 +3500,166 @@ function floatingOptions2(floating) {
     zIndex: floating.zIndex
   };
 }
+function imageMedia(ctx, resourceId, placement) {
+  const build = ctx.pictures.get(resourceId);
+  if (!build) {
+    throw new Error(`no image was prepared for resource "${resourceId}"`);
+  }
+  return build(placement);
+}
+function pictureOptions(image, ctx) {
+  const media = imageMedia(ctx, image.resourceId, image);
+  return {
+    type: media.type,
+    data: media.data,
+    // No `fileName`: at run level the backend allocates one, and stating our
+    // own would only fight it.
+    ...media.fallback ? { fallback: media.fallback } : {},
+    // Raw numbers are EMUs in @office-open/docx. Passing pixels here makes a
+    // normal image only a few hundred EMUs wide, effectively a dot.
+    transformation: { width: image.widthEmu, height: image.heightEmu },
+    // The id is stated rather than left to the backend's process-global
+    // counter. `name` stays empty, which is what it was before and what the
+    // backend falls back to.
+    altText: { id: String(ctx.nextDrawingId()) },
+    ...image.floating ? { floating: floatingOptions2(image.floating) } : {}
+    // No `description` or `title`: no DOCX this pipeline has produced carries
+    // `wp:docPr` alt text, and the compiler warns so the gap is visible rather
+    // than silent.
+  };
+}
+function drawingGroupOptions(group, ctx) {
+  const id = ctx.nextDrawingId();
+  return {
+    altText: {
+      id: String(id),
+      ...group.altText ? { description: group.altText } : {}
+    },
+    transformation: { width: group.widthEmu, height: group.heightEmu },
+    childOffset: { x: 0, y: 0 },
+    childExtent: { cx: group.canvasWidthEmu, cy: group.canvasHeightEmu },
+    children: group.children.map((child) => groupChild(child, ctx)),
+    ...group.floating ? { floating: floatingOptions2(group.floating) } : {}
+  };
+}
+function groupChild(child, ctx) {
+  return child.kind === "shape" ? groupShape(child, ctx) : groupPicture(child, ctx);
+}
+function groupShape(shape, ctx) {
+  const id = ctx.nextDrawingId();
+  return {
+    type: "wps",
+    transformation: childTransformation(shape.frame),
+    data: {
+      nonVisualProperties: {
+        id,
+        ...shape.name ? { name: shape.name } : {},
+        // `txBox="1"` is how Word tells a text box from a shape that happens
+        // to hold text, and it changes how the object behaves on selection.
+        ...shape.isTextBox ? { textBox: "1" } : {}
+      },
+      presetGeometry: { preset: shape.geometry },
+      ...shape.fill ? { fill: drawingFill(shape.fill) } : {},
+      ...shape.outline ? { outline: drawingOutline(shape.outline) } : {},
+      children: (shape.text?.paragraphs ?? []).map(
+        (child) => paragraph(child, ctx)
+      ),
+      ...shape.text ? { bodyProperties: bodyProperties(shape.text) } : {}
+    }
+  };
+}
+function groupPicture(picture2, ctx) {
+  const id = ctx.nextDrawingId();
+  const media = imageMedia(ctx, picture2.resourceId, {
+    widthEmu: picture2.frame.widthEmu,
+    heightEmu: picture2.frame.heightEmu
+  });
+  return {
+    type: media.type,
+    data: media.data,
+    fileName: media.fileName,
+    ...media.fallback ? {
+      fallback: {
+        ...media.fallback,
+        fileName: media.fallbackFileName
+      }
+    } : {},
+    transformation: childTransformation(picture2.frame),
+    nonVisualProperties: {
+      id,
+      ...picture2.name ? { name: picture2.name } : {},
+      ...picture2.altText ? { description: picture2.altText } : {}
+    },
+    ...picture2.crop ? { sourceRectangle: sourceRectangle(picture2.crop) } : {}
+  };
+}
+function childTransformation(frame) {
+  const flip = {
+    ...frame.flipHorizontal ? { horizontal: true } : {},
+    ...frame.flipVertical ? { vertical: true } : {}
+  };
+  return {
+    offset: {
+      emus: { x: frame.xEmu, y: frame.yEmu },
+      pixels: {
+        x: Math.round(emuToPixels(frame.xEmu)),
+        y: Math.round(emuToPixels(frame.yEmu))
+      }
+    },
+    emus: { x: frame.widthEmu, y: frame.heightEmu },
+    pixels: {
+      x: Math.round(emuToPixels(frame.widthEmu)),
+      y: Math.round(emuToPixels(frame.heightEmu))
+    },
+    // Degrees: the backend multiplies by 60000 on the way into `@rot`.
+    ...frame.rotationDegrees !== void 0 ? { rotation: frame.rotationDegrees } : {},
+    ...Object.keys(flip).length > 0 ? { flip } : {}
+  };
+}
+function drawingFill(fill) {
+  if (fill.kind === "none") return { type: "none" };
+  return {
+    type: "solid",
+    color: {
+      type: "rgb",
+      value: fill.color.hex,
+      // Transparency becomes an alpha transform on the colour. DrawingML
+      // states *opacity*, so the value is the complement of what the author
+      // wrote; the backend scales the percentage into `a:alpha`'s thousandths
+      // itself, so it must be handed a plain percentage here.
+      ...fill.transparencyPercent !== void 0 ? { transforms: { alpha: 100 - fill.transparencyPercent } } : {}
+    }
+  };
+}
+function drawingOutline(outline) {
+  return {
+    ...outline.widthEmu !== void 0 ? { width: outline.widthEmu } : {},
+    ...outline.dash ? { dash: outline.dash } : {},
+    ...outline.color ? { type: "solidFill", color: { value: outline.color.hex } } : {}
+  };
+}
+function bodyProperties(text) {
+  const insets = text.insetsEmu;
+  return {
+    ...text.anchor ? { anchor: BODY_ANCHOR[text.anchor] } : {},
+    // `lIns`/`tIns`/`rIns`/`bIns` is the vocabulary `a:bodyPr` actually has;
+    // the backend also accepts a `margins` object and folds it into the same
+    // attributes.
+    ...insets?.left !== void 0 ? { lIns: insets.left } : {},
+    ...insets?.top !== void 0 ? { tIns: insets.top } : {},
+    ...insets?.right !== void 0 ? { rIns: insets.right } : {},
+    ...insets?.bottom !== void 0 ? { bIns: insets.bottom } : {}
+  };
+}
+function sourceRectangle(crop) {
+  const thousandths = (fraction) => Math.round(fraction * 1e5);
+  return {
+    ...crop.left !== void 0 ? { left: thousandths(crop.left) } : {},
+    ...crop.top !== void 0 ? { top: thousandths(crop.top) } : {},
+    ...crop.right !== void 0 ? { right: thousandths(crop.right) } : {},
+    ...crop.bottom !== void 0 ? { bottom: thousandths(crop.bottom) } : {}
+  };
+}
 function shapeOptions(shape, ctx) {
   const id = String(ctx.nextDrawingId());
   return {
@@ -3493,23 +3677,8 @@ function shapeOptions(shape, ctx) {
         color: { type: "rgb", value: shape.fill.hex }
       }
     } : {},
-    ...shape.outline ? {
-      outline: {
-        ...shape.outline.widthEmu !== void 0 ? { width: shape.outline.widthEmu } : {},
-        fill: {
-          type: "solid",
-          color: { type: "rgb", value: shape.outline.color.hex }
-        }
-      }
-    } : {},
-    ...shape.insetsEmu ? {
-      bodyProperties: {
-        ...shape.insetsEmu.top !== void 0 ? { topInset: shape.insetsEmu.top } : {},
-        ...shape.insetsEmu.bottom !== void 0 ? { bottomInset: shape.insetsEmu.bottom } : {},
-        ...shape.insetsEmu.left !== void 0 ? { leftInset: shape.insetsEmu.left } : {},
-        ...shape.insetsEmu.right !== void 0 ? { rightInset: shape.insetsEmu.right } : {}
-      }
-    } : {},
+    ...shape.outline ? { outline: drawingOutline(shape.outline) } : {},
+    ...shape.insetsEmu ? { bodyProperties: bodyProperties({ insetsEmu: shape.insetsEmu }) } : {},
     ...shape.floating ? { floating: floatingOptions2(shape.floating) } : {}
   };
 }
@@ -3866,7 +4035,7 @@ function numberingConfig2(numbering) {
     }))
   };
 }
-var WRAP_TYPE2, TOC_PAGE_TAB_TWIPS;
+var WRAP_TYPE2, BODY_ANCHOR, TOC_PAGE_TAB_TWIPS;
 var init_emit2 = __esm({
   "src/renderers/office-open/emit.ts"() {
     "use strict";
@@ -3877,6 +4046,11 @@ var init_emit2 = __esm({
       tight: 2,
       topAndBottom: 3
     };
+    BODY_ANCHOR = {
+      top: "t",
+      middle: "ctr",
+      bottom: "b"
+    };
     TOC_PAGE_TAB_TWIPS = 9025;
   }
 });
@@ -4054,18 +4228,9 @@ async function prepareImages2(ir) {
         index === 0 ? data : distinguishImageBytes(data, type, size)
       );
     });
-    resources.set(resource.id, (image, drawingId) => {
-      const rasterSize = {
-        width: emuToPixels(image.widthEmu),
-        height: emuToPixels(image.heightEmu)
-      };
-      const sizeKey = `${rasterSize.width}x${rasterSize.height}`;
-      const transformation = {
-        // Raw numbers are EMUs in @office-open/docx. Passing pixels here makes
-        // a normal image only a few hundred EMUs wide, effectively a dot.
-        width: image.widthEmu,
-        height: image.heightEmu
-      };
+    resources.set(resource.id, (placement) => {
+      const sizeKey = placementKey(placement);
+      const stem = `${resource.id}-${sizeKey}`;
       return {
         type,
         // @office-open/docx stores a drawing transformation on its deduplicated
@@ -4073,29 +4238,28 @@ async function prepareImages2(ir) {
         // reuse the first size, so each distinct placement size gets equivalent
         // image bytes carrying a harmless format-native marker.
         data: placementData.get(sizeKey) ?? data,
-        transformation,
-        // The id is stated rather than left to the backend's process-global
-        // counter. `name` stays empty, which is what it was before and what
-        // the backend falls back to.
-        altText: { id: String(drawingId) },
+        // Named after the resource and the size it is drawn at, so two
+        // placements of one image at one size share a single part and a third
+        // at another size gets its own.
+        fileName: `${stem}.${type}`,
         ...type === "svg" ? {
           // Word before 2016 draws the fallback rather than the vector. A
           // raster that could not be produced falls back to the SVG bytes,
           // which is what this pipeline has always shipped.
           fallback: {
             type: "png",
-            data: rasters.get(`${image.resourceId}:${sizeKey}`) ?? data
-          }
-        } : {},
-        ...image.floating ? { floating: floatingOptions2(image.floating) } : {}
-        // No `description` or `title`: no DOCX this pipeline has produced
-        // carries `wp:docPr` alt text, and the compiler warns so the gap is
-        // visible rather than silent.
+            data: rasters.get(`${resource.id}:${sizeKey}`) ?? data
+          },
+          fallbackFileName: `${stem}-fallback.png`
+        } : {}
       };
     });
   }
   return resources;
 }
+function placementKey(placement) {
+  return `${emuToPixels(placement.widthEmu)}x${emuToPixels(placement.heightEmu)}`;
+}
 function distinguishImageBytes(data, mediaType, placement) {
   const marker = Buffer.from(`json-to-office:${placement}`, "utf8");
   switch (mediaType) {
@@ -4194,12 +4358,27 @@ function crc32(data) {
 }
 function collectImagePlacements2(ir) {
   const placements = /* @__PURE__ */ new Map();
+  const record = (resourceId, placement) => {
+    const sizes = placements.get(resourceId) ?? /* @__PURE__ */ new Set();
+    sizes.add(placementKey(placement));
+    placements.set(resourceId, sizes);
+  };
   const visitInline = (inline) => {
     if (inline.kind === "image") {
-      const key = `${emuToPixels(inline.widthEmu)}x${emuToPixels(inline.heightEmu)}`;
-      const sizes = placements.get(inline.resourceId) ?? /* @__PURE__ */ new Set();
-      sizes.add(key);
-      placements.set(inline.resourceId, sizes);
+      record(inline.resourceId, inline);
+      return;
+    }
+    if (inline.kind === "drawingGroup") {
+      for (const child of inline.children) {
+        if (child.kind === "picture") {
+          record(child.resourceId, {
+            widthEmu: child.frame.widthEmu,
+            heightEmu: child.frame.heightEmu
+          });
+          continue;
+        }
+        child.text?.paragraphs.forEach(visitBlock);
+      }
       return;
     }
     if (inline.kind === "hyperlink" || inline.kind === "revision") {
@@ -4372,6 +4551,9 @@ import {
   DEFAULT_VISUAL_DPI,
   MAX_RASTERIZE_BATCH_SLIDES
 } from "@json-to-office/shared";
+import {
+  isNativeVisualProps
+} from "@json-to-office/shared-docx";
 
 // src/components/visual.ts
 import { createHash } from "crypto";
@@ -4584,7 +4766,9 @@ function collectVisualProps(root) {
     const obj = node;
     if (typeof obj.name === "string" && obj.enabled === false) return;
     if (obj.name === "visual" && obj.props && typeof obj.props === "object") {
-      found.push(obj.props);
+      if (!isNativeVisualProps(obj.props)) {
+        found.push(obj.props);
+      }
       return;
     }
     for (const value of Object.values(obj)) visit(value);
@@ -4864,6 +5048,9 @@ import {
   clampVisualDpi as clampVisualDpi2,
   DEFAULT_VISUAL_DPI as DEFAULT_VISUAL_DPI2
 } from "@json-to-office/shared";
+import {
+  isNativeVisualProps as isNativeVisualProps2
+} from "@json-to-office/shared-docx";
 
 // src/components/highcharts.ts
 init_colorUtils();
@@ -5025,6 +5212,7 @@ async function desugarExternals(document, options) {
   return transformComponents(document, async (node) => {
     if (node.enabled === false) return void 0;
     if (node.name === "visual") {
+      if (isNativeVisualProps2(node.props)) return void 0;
       return withNodeIdentity(node, {
         name: "image",
         props: await visualImageProps(
@@ -5077,6 +5265,9 @@ async function visualImageProps(props, prerastered, options) {
 
 // src/core/imageResources.ts
 init_imageUtils();
+import {
+  isNativeVisualProps as isNativeVisualProps3
+} from "@json-to-office/shared-docx";
 async function loadImageResources(components) {
   const sources = /* @__PURE__ */ new Set();
   for (const component of components) collectSources(component, sources);
@@ -5115,6 +5306,9 @@ function collectSources(component, out) {
   const children = component.children;
   for (const child of children ?? []) collectSources(child, out);
   const props = component.props ?? {};
+  if (component.name === "visual" && isNativeVisualProps3(props)) {
+    collectNativeVisualSources(props, out);
+  }
   for (const key of ["header", "footer"]) {
     const part = props[key];
     if (Array.isArray(part)) {
@@ -5136,6 +5330,23 @@ function collectSources(component, out) {
     }
   }
 }
+function collectNativeVisualSources(props, out) {
+  const canvas = props.canvas;
+  const background = canvas?.background?.image;
+  if (background) {
+    const source = resolveImageSource(background);
+    if (source) out.add(source);
+  }
+  const elements = props.elements;
+  if (!Array.isArray(elements)) return;
+  for (const element of elements) {
+    if (!element || element.name !== "image") continue;
+    const source = resolveImageSource(
+      element.props ?? {}
+    );
+    if (source) out.add(source);
+  }
+}
 function collectCellSource(content, out) {
   if (content && typeof content === "object") {
     collectSources(content, out);
@@ -5148,6 +5359,516 @@ import {
   FeatureRequirementCollector
 } from "@json-to-office/shared/rendering";
 import { synthesizeFamilyName } from "@json-to-office/shared";
+import {
+  isNativeVisualProps as isNativeVisualProps4
+} from "@json-to-office/shared-docx";
+
+// src/ir/nativeVisual.ts
+init_units();
+init_imageUtils();
+var PIXELS_PER_INCH2 = 96;
+var DEFAULT_WIDTH_FRACTION = 0.75;
+var ASSUMED_FONT_SIZE_POINTS = 18;
+var MIN_DERIVED_TEXT_HEIGHT_INCHES = 0.5;
+var DERIVED_LINE_HEIGHT_RATIO = 1.6;
+var GEOMETRY_ALIASES = {
+  arrow: "rightArrow",
+  lightning: "lightningBolt"
+};
+var DASH_VALUES = /* @__PURE__ */ new Set([
+  "solid",
+  "dash",
+  "dot",
+  "dashDot"
+]);
+var ANCHOR = {
+  top: "top",
+  middle: "middle",
+  bottom: "bottom"
+};
+var ALIGNMENT = {
+  left: "left",
+  center: "center",
+  right: "right",
+  justify: "justified"
+};
+function compileNativeVisualGroup(props, outer) {
+  const canvas = {
+    widthEmu: inchesToEmu(props.canvas.width),
+    heightEmu: inchesToEmu(props.canvas.height)
+  };
+  const children = [];
+  let refused = false;
+  const deps = {
+    ...outer,
+    reject: (detail) => {
+      refused = true;
+      outer.reject(detail);
+    }
+  };
+  const background = props.canvas.background;
+  if (background?.color) {
+    const color = deps.color(background.color);
+    if (!color) {
+      deps.reject(`canvas.background.color "${background.color}"`);
+    } else {
+      children.push({
+        kind: "shape",
+        frame: fullBleed(canvas),
+        geometry: "rect",
+        fill: { kind: "solid", color },
+        name: "Canvas background"
+      });
+    }
+  }
+  if (background?.image) {
+    const source = resolveImageSource(background.image);
+    const resource = source ? deps.picture(source) : void 0;
+    if (!resource) {
+      deps.reject("canvas.background.image could not be loaded");
+    } else {
+      children.push({
+        kind: "picture",
+        frame: fullBleed(canvas),
+        resourceId: resource.resourceId,
+        name: "Canvas background"
+      });
+    }
+  }
+  for (const [index, element] of (props.elements ?? []).entries()) {
+    if (element.enabled === false) continue;
+    const child = compileElement(element, index, canvas, deps);
+    if (child) children.push(child);
+  }
+  return refused ? void 0 : { canvas, children };
+}
+function compileElement(element, index, canvas, deps) {
+  const at = `elements[${index}]`;
+  switch (element.name) {
+    case "text":
+      return compileText(element.props, at, canvas, deps);
+    case "shape":
+      return compileShape(element.props, at, canvas, deps);
+    case "image":
+      return compileImage(element.props, at, canvas, deps);
+    default:
+      deps.reject(`${at} is a "${element.name}"`);
+      return void 0;
+  }
+}
+function compileText(props, at, canvas, deps) {
+  const runs = textRuns(props);
+  if (!runs) {
+    deps.warn(
+      `[core-docx] native visual ${at} has neither "text" nor "runs"; nothing was drawn for it.`
+    );
+    return void 0;
+  }
+  const colors = resolveColors(
+    [
+      ["color", props.color],
+      ["fill.color", props.fill?.color],
+      ...runs.map((run, i) => [`runs[${i}].color`, run.color]),
+      ...runs.map(
+        (run, i) => [
+          `runs[${i}].underline.color`,
+          underlineColor(run.underline)
+        ]
+      ),
+      ["underline.color", underlineColor(props.underline)]
+    ],
+    at,
+    deps
+  );
+  if (!colors) return void 0;
+  const frame = resolveFrame(props, canvas, {
+    defaultHeightInches: derivedTextHeightInches(props, runs)
+  });
+  const paragraphs = textParagraphs(runs, props, colors, at);
+  return {
+    kind: "shape",
+    frame,
+    geometry: "rect",
+    isTextBox: true,
+    // A text box with no fill is transparent, which is what the rasterized
+    // path draws; saying so explicitly stops Word applying its own default.
+    fill: props.fill?.color ? solidFill(colors.get("fill.color"), props.fill.transparency) : { kind: "none" },
+    text: {
+      paragraphs,
+      // pptx anchors a text box at the top unless told otherwise, and a
+      // drawing that changes anchor between render modes moves its text.
+      anchor: ANCHOR[props.valign ?? "top"] ?? "top",
+      // A text box's insets default to nothing, again matching pptx. A shape
+      // deliberately leaves them unstated so OOXML's own defaults apply.
+      insetsEmu: marginInsets(props.margin) ?? ZERO_INSETS
+    },
+    name: `Text ${at}`
+  };
+}
+var ZERO_INSETS = { top: 0, bottom: 0, left: 0, right: 0 };
+function textRuns(props) {
+  if (props.runs?.length) return props.runs;
+  if (props.text === void 0) return void 0;
+  return [{ text: props.text }];
+}
+function textParagraphs(runs, props, colors, at) {
+  const paragraphs = [];
+  let current = [];
+  const flush = () => {
+    paragraphs.push({
+      kind: "paragraph",
+      id: `${at}.p${paragraphs.length}`,
+      path: `${at}.paragraphs[${paragraphs.length}]`,
+      children: current,
+      formatting: {
+        ...props.align ? { alignment: ALIGNMENT[props.align] } : {},
+        // A drawing's text is set flush against the shape; the document's
+        // paragraph spacing would push it away from the top edge, which is not
+        // what an absolutely-placed box means.
+        spacing: { beforeTwips: 0, afterTwips: 0 }
+      }
+    });
+    current = [];
+  };
+  runs.forEach((run, index) => {
+    const formatting = runFormatting(run, props, colors, index);
+    const lines = run.text.split("\n");
+    lines.forEach((line, lineIndex) => {
+      if (lineIndex > 0) current.push({ kind: "lineBreak" });
+      if (line) {
+        current.push({ kind: "text", text: line, ...formatting });
+      }
+    });
+    if (run.breakLine && index < runs.length - 1) flush();
+  });
+  flush();
+  return paragraphs;
+}
+function runFormatting(run, props, colors, index) {
+  const fontFamily = run.fontFace ?? props.fontFace;
+  const sizePoints = run.fontSize ?? props.fontSize;
+  const color = colors.get(`runs[${index}].color`) ?? (run.color === void 0 ? colors.get("color") : void 0);
+  const bold = run.bold ?? props.bold;
+  const italic = run.italic ?? props.italic;
+  const strike = run.strike ?? props.strike;
+  const underline = compileUnderline(
+    run.underline ?? props.underline,
+    colors.get(
+      run.underline !== void 0 ? `runs[${index}].underline.color` : "underline.color"
+    )
+  );
+  const formatting = {
+    ...fontFamily ? { fontFamily } : {},
+    ...sizePoints !== void 0 ? { sizeHalfPoints: pointsToHalfPoints(sizePoints) } : {},
+    ...color ? { color } : {},
+    ...bold !== void 0 ? { bold } : {},
+    ...italic !== void 0 ? { italic } : {},
+    ...strike !== void 0 ? { strike } : {},
+    ...underline ? { underline } : {}
+  };
+  return Object.keys(formatting).length > 0 ? { formatting } : {};
+}
+var UNDERLINE_TYPES = {
+  sng: "single",
+  dbl: "double",
+  dash: "dash",
+  dotted: "dotted"
+};
+function compileUnderline(value, color) {
+  if (value === void 0 || value === false) return void 0;
+  const style = value === true ? "sng" : value.style ?? "sng";
+  return {
+    type: UNDERLINE_TYPES[style] ?? "single",
+    ...color ? { color } : {}
+  };
+}
+function underlineColor(value) {
+  return typeof value === "object" ? value.color : void 0;
+}
+function derivedTextHeightInches(props, runs) {
+  const fontSize = props.fontSize ?? ASSUMED_FONT_SIZE_POINTS;
+  const lineCount = runs.reduce(
+    (total, run) => total + (run.breakLine ? 1 : 0) + (run.text.match(/\n/g)?.length ?? 0),
+    1
+  );
+  return Math.max(
+    MIN_DERIVED_TEXT_HEIGHT_INCHES,
+    fontSize / 72 * DERIVED_LINE_HEIGHT_RATIO * lineCount
+  );
+}
+function compileShape(props, at, canvas, deps) {
+  const segments = shapeSegments(props);
+  const colors = resolveColors(
+    [
+      ["fill.color", props.fill?.color],
+      ["line.color", props.line?.color],
+      ["fontColor", props.fontColor],
+      ...segments.map(
+        (segment, i) => [`text[${i}].color`, segment.color]
+      )
+    ],
+    at,
+    deps
+  );
+  if (!colors) return void 0;
+  const frame = resolveFrame(props, canvas, { defaultHeightInches: 0 });
+  if (props.flipH) frame.flipHorizontal = true;
+  if (props.flipV) frame.flipVertical = true;
+  const dash = props.line?.dashType;
+  if (dash !== void 0 && !DASH_VALUES.has(dash)) {
+    deps.reject(`${at}.line.dashType "${dash}"`);
+    return void 0;
+  }
+  const outline = props.line ? {
+    ...colors.get("line.color") ? { color: colors.get("line.color") } : {},
+    ...props.line.width !== void 0 ? { widthEmu: pointsToEmu(props.line.width) } : {},
+    ...dash && dash !== "solid" ? { dash } : {}
+  } : void 0;
+  const text = segments.length ? {
+    paragraphs: shapeParagraphs(segments, props, colors, at),
+    anchor: ANCHOR[props.valign ?? "middle"] ?? "middle",
+    // Unstated insets are left unstated so OOXML's own shape defaults
+    // apply, which is what the raster path draws.
+    ...marginInsets(props.margin) ? { insetsEmu: marginInsets(props.margin) } : {}
+  } : void 0;
+  return {
+    kind: "shape",
+    frame,
+    geometry: GEOMETRY_ALIASES[props.type] ?? props.type,
+    ...props.fill ? {
+      fill: props.fill.color ? solidFill(colors.get("fill.color"), props.fill.transparency) : { kind: "none" }
+    } : {},
+    ...outline && Object.keys(outline).length > 0 ? { outline } : {},
+    ...text ? { text } : {},
+    name: `Shape ${at}`
+  };
+}
+function shapeSegments(props) {
+  if (props.text === void 0) return [];
+  if (typeof props.text === "string") {
+    return props.text ? [{ text: props.text }] : [];
+  }
+  return props.text;
+}
+function shapeParagraphs(segments, props, colors, at) {
+  const paragraphs = [];
+  let current = [];
+  const flush = () => {
+    paragraphs.push({
+      kind: "paragraph",
+      id: `${at}.p${paragraphs.length}`,
+      path: `${at}.paragraphs[${paragraphs.length}]`,
+      children: current,
+      formatting: {
+        // A shape centres its text unless told otherwise, which is what the
+        // rasterized shape draws.
+        alignment: props.align ? ALIGNMENT[props.align] : "center",
+        spacing: { beforeTwips: 0, afterTwips: 0 }
+      }
+    });
+    current = [];
+  };
+  segments.forEach((segment, index) => {
+    const fontFamily = segment.fontFace ?? props.fontFace;
+    const sizePoints = segment.fontSize ?? props.fontSize;
+    const color = colors.get(`text[${index}].color`) ?? (segment.color === void 0 ? colors.get("fontColor") : void 0);
+    const bold = segment.bold ?? props.bold;
+    const italic = segment.italic ?? props.italic;
+    const formatting = {
+      ...fontFamily ? { fontFamily } : {},
+      ...sizePoints !== void 0 ? { sizeHalfPoints: pointsToHalfPoints(sizePoints) } : {},
+      ...color ? { color } : {},
+      ...bold !== void 0 ? { bold } : {},
+      ...italic !== void 0 ? { italic } : {}
+    };
+    const wrapped = Object.keys(formatting).length > 0 ? { formatting } : void 0;
+    segment.text.split("\n").forEach((line, lineIndex) => {
+      if (lineIndex > 0) current.push({ kind: "lineBreak" });
+      if (line) current.push({ kind: "text", text: line, ...wrapped });
+    });
+    if (segment.breakLine && index < segments.length - 1) flush();
+  });
+  flush();
+  return paragraphs;
+}
+function compileImage(props, at, canvas, deps) {
+  const source = resolveImageSource(props);
+  if (!source) {
+    deps.reject(`${at} has none of "path", "base64" or "svg"`);
+    return void 0;
+  }
+  const resource = deps.picture(source);
+  if (!resource) {
+    deps.reject(`${at} image could not be loaded`);
+    return void 0;
+  }
+  const aspect = resource.intrinsic ? resource.intrinsic.width / resource.intrinsic.height : void 0;
+  const intrinsicInches = resource.intrinsic ? {
+    width: resource.intrinsic.width / PIXELS_PER_INCH2,
+    height: resource.intrinsic.height / PIXELS_PER_INCH2
+  } : void 0;
+  const box = resolveImageBox(props, canvas, aspect, intrinsicInches);
+  const sizing = props.sizing;
+  if (!sizing || !aspect) {
+    if (sizing && !aspect) {
+      deps.warn(
+        `[core-docx] native visual ${at} asks for "${sizing.type}" sizing, but the image's stored size could not be read; it was stretched to its box instead.`
+      );
+    }
+    return picture(box, props, resource, at);
+  }
+  const boxAspect = box.widthEmu / box.heightEmu;
+  if (sizing.type === "contain") {
+    const fitted = boxAspect > aspect ? {
+      widthEmu: Math.round(box.heightEmu * aspect),
+      heightEmu: box.heightEmu
+    } : {
+      widthEmu: box.widthEmu,
+      heightEmu: Math.round(box.widthEmu / aspect)
+    };
+    return picture(
+      {
+        ...box,
+        xEmu: box.xEmu + Math.round((box.widthEmu - fitted.widthEmu) / 2),
+        yEmu: box.yEmu + Math.round((box.heightEmu - fitted.heightEmu) / 2),
+        ...fitted
+      },
+      props,
+      resource,
+      at
+    );
+  }
+  const visible = boxAspect > aspect ? { widthFraction: 1, heightFraction: aspect / boxAspect } : { widthFraction: boxAspect / aspect, heightFraction: 1 };
+  const crop = sizing.type === "cover" ? {
+    ...visible.widthFraction < 1 ? {
+      left: (1 - visible.widthFraction) / 2,
+      right: (1 - visible.widthFraction) / 2
+    } : {},
+    ...visible.heightFraction < 1 ? {
+      top: (1 - visible.heightFraction) / 2,
+      bottom: (1 - visible.heightFraction) / 2
+    } : {}
+  } : {
+    ...visible.widthFraction < 1 ? { right: 1 - visible.widthFraction } : {},
+    ...visible.heightFraction < 1 ? { bottom: 1 - visible.heightFraction } : {}
+  };
+  return picture(box, props, resource, at, crop);
+}
+function picture(frame, props, resource, at, crop) {
+  return {
+    kind: "picture",
+    frame,
+    resourceId: resource.resourceId,
+    ...props.alt ? { altText: props.alt } : {},
+    ...crop && Object.keys(crop).length > 0 ? { crop } : {},
+    name: `Image ${at}`
+  };
+}
+function resolveImageBox(props, canvas, aspect, intrinsicInches) {
+  const width = props.sizing?.w ?? props.w;
+  const height = props.sizing?.h ?? props.h;
+  const widthEmu = width !== void 0 ? resolveExtent(width, canvas.widthEmu) : void 0;
+  const heightEmu = height !== void 0 ? resolveExtent(height, canvas.heightEmu) : void 0;
+  const resolved = (() => {
+    if (widthEmu !== void 0 && heightEmu !== void 0) {
+      return { widthEmu, heightEmu };
+    }
+    if (widthEmu !== void 0) {
+      return {
+        widthEmu,
+        heightEmu: aspect ? Math.round(widthEmu / aspect) : Math.round(widthEmu * (3 / 4))
+      };
+    }
+    if (heightEmu !== void 0) {
+      return {
+        widthEmu: aspect ? Math.round(heightEmu * aspect) : Math.round(heightEmu * (4 / 3)),
+        heightEmu
+      };
+    }
+    if (intrinsicInches) {
+      return {
+        widthEmu: inchesToEmu(intrinsicInches.width),
+        heightEmu: inchesToEmu(intrinsicInches.height)
+      };
+    }
+    const fallbackWidth = Math.round(canvas.widthEmu * DEFAULT_WIDTH_FRACTION);
+    return {
+      widthEmu: fallbackWidth,
+      heightEmu: Math.round(fallbackWidth * (3 / 4))
+    };
+  })();
+  return {
+    xEmu: props.x !== void 0 ? resolveOffset(props.x, canvas.widthEmu) : 0,
+    yEmu: props.y !== void 0 ? resolveOffset(props.y, canvas.heightEmu) : 0,
+    ...resolved,
+    ...rotation(props.rotate)
+  };
+}
+function fullBleed(canvas) {
+  return {
+    xEmu: 0,
+    yEmu: 0,
+    widthEmu: canvas.widthEmu,
+    heightEmu: canvas.heightEmu
+  };
+}
+function resolveFrame(props, canvas, options) {
+  return {
+    xEmu: props.x !== void 0 ? resolveOffset(props.x, canvas.widthEmu) : 0,
+    yEmu: props.y !== void 0 ? resolveOffset(props.y, canvas.heightEmu) : 0,
+    widthEmu: props.w !== void 0 ? resolveExtent(props.w, canvas.widthEmu) : Math.round(canvas.widthEmu * DEFAULT_WIDTH_FRACTION),
+    heightEmu: props.h !== void 0 ? resolveExtent(props.h, canvas.heightEmu) : inchesToEmu(options.defaultHeightInches),
+    ...rotation(props.rotate)
+  };
+}
+function rotation(degrees) {
+  if (degrees === void 0 || degrees % 360 === 0) return {};
+  return { rotationDegrees: degrees };
+}
+function resolveOffset(value, axisEmu) {
+  return resolveLength(value, axisEmu);
+}
+function resolveExtent(value, axisEmu) {
+  return Math.max(0, resolveLength(value, axisEmu));
+}
+function resolveLength(value, axisEmu) {
+  if (typeof value === "number") return inchesToEmu(value);
+  const percent = Number.parseFloat(value);
+  if (!Number.isFinite(percent)) return 0;
+  return Math.round(percent / 100 * axisEmu);
+}
+function marginInsets(margin) {
+  if (margin === void 0) return void 0;
+  const [top, right, bottom, left] = Array.isArray(margin) ? margin : [margin, margin, margin, margin];
+  return {
+    top: pointsToEmu(top ?? 0),
+    right: pointsToEmu(right ?? 0),
+    bottom: pointsToEmu(bottom ?? 0),
+    left: pointsToEmu(left ?? 0)
+  };
+}
+function solidFill(color, transparency) {
+  return {
+    kind: "solid",
+    color,
+    ...transparency !== void 0 && transparency > 0 ? { transparencyPercent: transparency } : {}
+  };
+}
+function resolveColors(entries, at, deps) {
+  const resolved = /* @__PURE__ */ new Map();
+  let failed = false;
+  for (const [key, value] of entries) {
+    if (value === void 0) continue;
+    const color = deps.color(value);
+    if (!color) {
+      deps.reject(`${at}.${key} "${value}"`);
+      failed = true;
+      continue;
+    }
+    resolved.set(key, color);
+  }
+  return failed ? void 0 : resolved;
+}
 
 // src/styles/themeToStyles.ts
 init_themes();
@@ -6990,7 +7711,7 @@ function decoratedStyle(match, base) {
 function pushSegment(out, text, options, override = {}) {
   const bold = override.bold ?? options.base.bold;
   const italic = override.italic ?? options.base.italic;
-  const formatting = runFormatting(options, { bold, italic });
+  const formatting = runFormatting2(options, { bold, italic });
   const lines = text.split("\n");
   for (const [lineIndex, line] of lines.entries()) {
     if (!line && lineIndex === 0) continue;
@@ -7068,7 +7789,7 @@ function pushNoProofWords(out, text, formatting, options) {
     out.push({ kind: "text", text: text.slice(lastIndex), formatting });
   }
 }
-function runFormatting(options, state) {
+function runFormatting2(options, state) {
   const formatting = { ...options.base };
   if (state.bold !== void 0) formatting.bold = state.bold;
   if (state.italic !== void 0) formatting.italic = state.italic;
@@ -7440,7 +8161,9 @@ function compileComponent(component, scope) {
     case "columns":
       return compileColumns(component, scope);
     case "image":
-      return compileImage(component, scope);
+      return compileImage2(component, scope);
+    case "visual":
+      return compileVisual(component, scope);
     case "table":
       return compileTable(component, scope);
     default:
@@ -7684,7 +8407,7 @@ function compileTextBox(component, scope) {
   const style = props.style;
   const padding = style?.padding;
   if (props.renderAs === "shape") {
-    const shape = compileShape(props, children, scope);
+    const shape = compileShape2(props, children, scope);
     if (shape) return shape;
   }
   ctx.features.require("tables", path4);
@@ -7738,7 +8461,7 @@ function compileTextBox(component, scope) {
   ];
 }
 var EMU_PER_PIXEL = 9525;
-function compileShape(props, children, scope) {
+function compileShape2(props, children, scope) {
   const { ctx, path: path4 } = scope;
   const width = shapeSize(props.width, "width", ctx);
   const height = shapeSize(props.height, "height", ctx);
@@ -8232,7 +8955,7 @@ function reportUnlowered(component, props, text, scope) {
 }
 function compileRuns(props, text, ctx, path4, mode = "inline") {
   const font = props.font ?? {};
-  const base = runFormatting2(font, props, ctx);
+  const base = runFormatting3(font, props, ctx);
   if (base.language) ctx.features.require("proofing-language", path4);
   if (base.noProof) ctx.features.require("proofing-language", path4);
   const words = mergeNoProofWords(noProofWords(ctx.theme), props.noProofWords);
@@ -8502,7 +9225,7 @@ function isoDate(date) {
 function isoDateTime(date) {
   return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "Z");
 }
-function runFormatting2(font, props, ctx) {
+function runFormatting3(font, props, ctx) {
   const hasWeightRequest = font.fontWeight != null || font.bold === true;
   const effectiveFamily = font.family ?? (hasWeightRequest ? resolveBodyFamily(ctx.theme) : void 0);
   const weighted = applyFontWeightAlias({
@@ -8665,8 +9388,107 @@ function headingLevel(level) {
   const value = typeof level === "number" ? level : 1;
   return value >= 1 && value <= 6 ? value : 1;
 }
+function compileVisual(component, scope) {
+  const { ctx, path: path4 } = scope;
+  const props = component.props ?? {};
+  if (!isNativeVisualProps4(props)) {
+    ctx.unsupported.push({
+      name: "visual",
+      path: path4,
+      detail: "a raster visual reached the compiler; it should have been rasterized during desugaring"
+    });
+    return [];
+  }
+  const group = compileNativeVisualGroup(
+    props,
+    nativeVisualDeps(ctx, path4)
+  );
+  if (!group) return [];
+  const size = visualPlacementPixels(props, group.canvas, {
+    widthPx: Math.round(twipsToPixels(getAvailableWidthTwips(ctx.theme))),
+    heightPx: Math.round(twipsToPixels(getAvailableHeightTwips(ctx.theme)))
+  });
+  const drawing = {
+    kind: "drawingGroup",
+    widthEmu: pixelsToEmu(size.width),
+    heightEmu: pixelsToEmu(size.height),
+    canvasWidthEmu: group.canvas.widthEmu,
+    canvasHeightEmu: group.canvas.heightEmu,
+    children: group.children,
+    ...typeof props.alt === "string" && props.alt ? { altText: props.alt } : {},
+    ...props.floating ? { floating: compileFloating(props.floating, ctx, path4) } : {}
+  };
+  ctx.features.require("drawing-groups", path4);
+  if (props.floating) ctx.features.require("floating-images", path4);
+  const spacing = {};
+  if (props.spacing?.before !== void 0) {
+    spacing.beforeTwips = pointsToTwips2(props.spacing.before);
+  }
+  if (props.spacing?.after !== void 0) {
+    spacing.afterTwips = pointsToTwips2(props.spacing.after);
+  }
+  const blocks = [
+    {
+      kind: "paragraph",
+      id: scope.id,
+      path: path4,
+      children: [drawing],
+      formatting: {
+        // A floating drawing is anchored, so aligning its paragraph would move
+        // the anchor rather than the graphic — the same rule an image follows.
+        ...props.floating ? {} : { alignment: compileAlignment(props.alignment) ?? "center" },
+        ...Object.keys(spacing).length > 0 ? { spacing } : {},
+        ...props.keepNext !== void 0 ? { keepNext: props.keepNext } : {},
+        ...props.keepLines !== void 0 ? { keepLines: props.keepLines } : {}
+      }
+    }
+  ];
+  const caption = captionBlock(props.caption, scope, "visual");
+  if (caption === void 0) return [];
+  if (caption) blocks.push(caption);
+  return blocks;
+}
+function nativeVisualDeps(ctx, path4) {
+  return {
+    color: (value) => {
+      try {
+        return irColor(resolveColor(value, ctx.theme));
+      } catch {
+        return void 0;
+      }
+    },
+    picture: (source) => {
+      const loaded = ctx.images.get(source);
+      if (!loaded) return void 0;
+      const mediaType = detectImageType(source, loaded.contentType);
+      if (mediaType === "svg") ctx.features.require("svg-images", path4);
+      return {
+        resourceId: declareResource(loaded, mediaType, ctx),
+        mediaType,
+        ...loaded.intrinsic ? { intrinsic: loaded.intrinsic } : {}
+      };
+    },
+    reject: (detail) => ctx.unsupported.push({ name: "visual", path: path4, detail }),
+    warn: (message) => warnOnce(ctx, `visual:${message}`, message)
+  };
+}
+function visualPlacementPixels(props, canvas, reference) {
+  const canvasWidthPx = Math.round(emuToPixels(canvas.widthEmu));
+  const canvasHeightPx = Math.round(emuToPixels(canvas.heightEmu));
+  const targetWidth = props.width !== void 0 ? parseWidthValue(props.width, reference.widthPx) : void 0;
+  const targetHeight = props.height !== void 0 ? parseDimensionValue(props.height, reference.heightPx) : void 0;
+  if (targetWidth === void 0 && targetHeight === void 0) {
+    return { width: canvasWidthPx, height: canvasHeightPx };
+  }
+  return calculateMissingDimension(
+    canvasWidthPx,
+    canvasHeightPx,
+    targetWidth,
+    targetHeight
+  );
+}
 var UNLOWERED_IMAGE_PROPS = ["comment"];
-function compileImage(component, scope) {
+function compileImage2(component, scope) {
   const { ctx, path: path4 } = scope;
   const props = component.props ?? {};
   for (const prop of UNLOWERED_IMAGE_PROPS) {
@@ -8727,32 +9549,37 @@ function compileImage(component, scope) {
       }
     }
   ];
-  if (props.caption) {
-    const caption = String(props.caption);
-    const syntax = containsUnsupportedSyntax(caption);
-    if (syntax) {
-      ctx.unsupported.push({ name: "image", path: path4, detail: syntax });
-      return [];
-    }
-    blocks.push({
-      kind: "paragraph",
-      id: `${scope.id}:caption`,
-      path: `${path4}.caption`,
-      styleId: "Normal",
-      // Captions default to left alignment, whatever the figure did.
-      formatting: { alignment: "left" },
-      // A caption reaches the parser only when it carries a decorator, which
-      // is why a link in an otherwise plain caption stays literal.
-      children: DECORATED.test(caption) ? parseInline(caption, {
-        base: {},
-        hyperlinks: true,
-        resolvePlaceholder: placeholderResolver(ctx),
-        resolveCrossReference: crossReferenceResolver(ctx, path4)
-      }) : parseLiteral(caption, { base: {} })
-    });
-  }
+  const caption = captionBlock(props.caption, scope, "image");
+  if (caption === void 0) return [];
+  if (caption) blocks.push(caption);
   return blocks;
 }
+function captionBlock(value, scope, componentName) {
+  if (!value) return null;
+  const { ctx, path: path4 } = scope;
+  const caption = String(value);
+  const syntax = containsUnsupportedSyntax(caption);
+  if (syntax) {
+    ctx.unsupported.push({ name: componentName, path: path4, detail: syntax });
+    return void 0;
+  }
+  return {
+    kind: "paragraph",
+    id: `${scope.id}:caption`,
+    path: `${path4}.caption`,
+    styleId: "Normal",
+    // Captions default to left alignment, whatever the figure did.
+    formatting: { alignment: "left" },
+    // A caption reaches the parser only when it carries a decorator, which
+    // is why a link in an otherwise plain caption stays literal.
+    children: DECORATED.test(caption) ? parseInline(caption, {
+      base: {},
+      hyperlinks: true,
+      resolvePlaceholder: placeholderResolver(ctx),
+      resolveCrossReference: crossReferenceResolver(ctx, path4)
+    }) : parseLiteral(caption, { base: {} })
+  };
+}
 function relativeFrom(value, axis) {
   const allowed = axis === "horizontal" ? ["character", "column", "margin", "page"] : ["margin", "page", "paragraph", "line"];
   return typeof value === "string" && allowed.includes(value) ? value : void 0;
@@ -9176,6 +10003,9 @@ function cellChildren(cell, baseStyle, scope, rowRevision) {
     if (content.name === "image") {
       return wrap(cellImage(content, base, ctx));
     }
+    if (content.name === "visual") {
+      return wrap(cellVisual(content, scope));
+    }
     if (content.name !== "paragraph") {
       return wrap([
         {
@@ -9215,6 +10045,40 @@ function cellChildren(cell, baseStyle, scope, rowRevision) {
     })
   );
 }
+function cellVisual(component, scope) {
+  const { ctx, path: path4 } = scope;
+  const props = component.props ?? {};
+  if (!isNativeVisualProps4(props)) {
+    ctx.unsupported.push({
+      name: "visual",
+      path: path4,
+      detail: "a raster visual reached the compiler; it should have been rasterized during desugaring"
+    });
+    return [];
+  }
+  const group = compileNativeVisualGroup(
+    props,
+    nativeVisualDeps(ctx, path4)
+  );
+  if (!group) return [];
+  const size = visualPlacementPixels(props, group.canvas, {
+    widthPx: CELL_DRAWING_REFERENCE.width,
+    heightPx: CELL_DRAWING_REFERENCE.height
+  });
+  ctx.features.require("drawing-groups", path4);
+  return [
+    {
+      kind: "drawingGroup",
+      widthEmu: pixelsToEmu(size.width),
+      heightEmu: pixelsToEmu(size.height),
+      canvasWidthEmu: group.canvas.widthEmu,
+      canvasHeightEmu: group.canvas.heightEmu,
+      children: group.children,
+      ...typeof props.alt === "string" && props.alt ? { altText: props.alt } : {}
+    }
+  ];
+}
+var CELL_DRAWING_REFERENCE = { width: 300, height: 200 };
 function cellImage(component, base, ctx) {
   const props = component.props ?? {};
   const source = resolveImageSource(props);
@@ -10330,6 +11194,9 @@ import {
   clampVisualDpi as clampVisualDpi3,
   DEFAULT_VISUAL_DPI as DEFAULT_VISUAL_DPI3
 } from "@json-to-office/shared";
+import {
+  isNativeVisualProps as isNativeVisualProps5
+} from "@json-to-office/shared-docx";
 var DEFAULT_CONCURRENCY = 4;
 async function flattenVisuals(doc, options) {
   let rasterize = options.rasterize;
@@ -10375,8 +11242,10 @@ async function flattenVisuals(doc, options) {
     doc,
     async (node) => (
       // A disabled visual is left as-is: it is filtered out at render anyway, so
-      // rasterizing it would be wasted work.
-      node.name === "visual" && node.enabled !== false ? rasterizeVisual(node, ctx) : void 0
+      // rasterizing it would be wasted work. A native one is left as-is for a
+      // stronger reason — it is already service-free, and flattening exists to
+      // remove the service dependency, not to trade editable objects for pixels.
+      node.name === "visual" && node.enabled !== false && !isNativeVisualProps5(node.props) ? rasterizeVisual(node, ctx) : void 0
     )
   );
 }