@bendyline/squisq-formats 2.6.14 → 2.6.15

package/README.md

@@ -87,7 +87,34 @@ const imported = await pdfToMarkdownDoc(pdfBuffer);
 const container = await pdfToContainer(pdfBuffer);
 ```
 
-**Fidelity:** export uses pdf-lib's standard 14 fonts (`themeId` affects colors only). PDF has no semantic structure, so import is heuristic and best-effort: headings are detected by font size, and tables / code blocks / blockquotes / links via the `detectTables` / `detectCodeBlocks` / `detectBlockquotes` / `detectLinks` options (all default true). `pdfToMarkdownDoc` is text-only; `pdfToContainer` also extracts embedded XObject and inline raster images in browsers and Node, placed **by page** — each image is inserted after the last content block from its page (image-only pages fall back to the nearest preceding page with content, else the document end). Placement is page-level only; masks, vector artwork, and images that PDF.js cannot expose as decoded pixels are not emitted.
+**Fidelity:** export uses pdf-lib's standard 14 fonts (`themeId` affects colors only). Pass `images` (keyed by the markdown URL, as for DOCX) to draw PNG and JPEG images that stand alone in a paragraph; other images print as an `[Image: alt]` note. PDF has no semantic structure, so import is heuristic and best-effort: headings are detected by font size, and tables / code blocks / blockquotes / links via the `detectTables` / `detectCodeBlocks` / `detectBlockquotes` / `detectLinks` options (all default true). `pdfToMarkdownDoc` is text-only; `pdfToContainer` also extracts embedded XObject and inline raster images in browsers and Node, placed **by page** — each image is inserted after the last content block from its page (image-only pages fall back to the nearest preceding page with content, else the document end). Placement is page-level only; masks, vector artwork, and images that PDF.js cannot expose as decoded pixels are not emitted.
+
+### Diagrams as pictures
+
+DOCX, EPUB, PDF and PPTX cannot draw Mermaid or Squisq diagrams, so on their
+own they export diagram source as text. `rasterizeDiagrams` finds every
+diagram — Mermaid fences, ASCII `diagram`/`timeline`/`tree` fences, and
+`{[drawing]}`/`{[layout]}`/`{[diagram]}` heading blocks — asks a renderer for
+a PNG of each, and returns the document with each diagram replaced by an
+image plus the bytes for the exporters' `images` option. Drawing needs a
+browser; `@bendyline/squisq-react/diagram-pictures` provides the renderer.
+
+```ts
+import { rasterizeDiagrams } from '@bendyline/squisq-formats/diagrams';
+import { createDiagramPictureRenderer } from '@bendyline/squisq-react/diagram-pictures';
+
+const pictured = await rasterizeDiagrams(markdownDoc, createDiagramPictureRenderer());
+const docx = await markdownDocToDocx(pictured.markdownDoc, { images: pictured.images });
+const pdf = await markdownDocToPdf(pictured.markdownDoc, { images: pictured.images });
+
+// PPTX keeps drawings, timelines and ASCII diagrams as native shapes;
+// only Mermaid needs a picture.
+const pptx = await docToPptx(doc, { diagramImages: pictured.mermaid });
+```
+
+A diagram the renderer cannot draw stays as source; the export never fails on
+it. Image entries carry their display size (`width`/`height` in CSS pixels),
+so a picture rendered at 2× prints at 1×.
 
 ### HTML
 
@@ -289,18 +316,19 @@ Also exported: `createRegistry` / `defaultRegistry` / `defaultFormats`, `BUILTIN
 
 ## Subpath Exports
 
-| Subpath                               | Contents                                                                       |
-| ------------------------------------- | ------------------------------------------------------------------------------ |
-| `@bendyline/squisq-formats/docx`      | DOCX import/export (+ `docxToContainer`)                                       |
-| `@bendyline/squisq-formats/pdf`       | PDF import/export (+ `pdfToContainer`, `configurePdfWorker`)                   |
-| `@bendyline/squisq-formats/html`      | Player HTML export, static plain-HTML export + bundles, HTML import            |
-| `@bendyline/squisq-formats/epub`      | EPUB 3 e-book export (with optional Media Overlays)                            |
-| `@bendyline/squisq-formats/pptx`      | PPTX export + import (text/lists/tables + slide images)                        |
-| `@bendyline/squisq-formats/xlsx`      | XLSX import + tables-only export                                               |
-| `@bendyline/squisq-formats/csv`       | CSV import/export (RFC 4180)                                                   |
-| `@bendyline/squisq-formats/ooxml`     | Shared OOXML infrastructure (package reader/writer, XML utilities, namespaces) |
-| `@bendyline/squisq-formats/container` | `ContentContainer` ↔ ZIP serialization                                         |
-| `@bendyline/squisq-formats/registry`  | Format registry + programmatic `convert()` (also re-exported from the root)    |
+| Subpath                               | Contents                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------- |
+| `@bendyline/squisq-formats/docx`      | DOCX import/export (+ `docxToContainer`)                                        |
+| `@bendyline/squisq-formats/pdf`       | PDF import/export (+ `pdfToContainer`, `configurePdfWorker`)                    |
+| `@bendyline/squisq-formats/html`      | Player HTML export, static plain-HTML export + bundles, HTML import             |
+| `@bendyline/squisq-formats/epub`      | EPUB 3 e-book export (with optional Media Overlays)                             |
+| `@bendyline/squisq-formats/pptx`      | PPTX export + import (text/lists/tables + slide images)                         |
+| `@bendyline/squisq-formats/xlsx`      | XLSX import + tables-only export                                                |
+| `@bendyline/squisq-formats/csv`       | CSV import/export (RFC 4180)                                                    |
+| `@bendyline/squisq-formats/ooxml`     | Shared OOXML infrastructure (package reader/writer, XML utilities, namespaces)  |
+| `@bendyline/squisq-formats/diagrams`  | `rasterizeDiagrams` / `findDiagrams`: diagrams as pictures for document exports |
+| `@bendyline/squisq-formats/container` | `ContentContainer` ↔ ZIP serialization                                          |
+| `@bendyline/squisq-formats/registry`  | Format registry + programmatic `convert()` (also re-exported from the root)     |
 
 The package root re-exports the common converters; `./container`, the plain-HTML/bundle functions, `docxToContainer`, `pdfToContainer`, `PdfPageSize`, and the image utilities are subpath-only.
 

package/dist/{chunk-MIK4NMOP.js → chunk-EMAPNC32.js}

@@ -1,6 +1,6 @@
 import {
   inferMimeType
-} from "./chunk-VPWPEMZJ.js";
+} from "./chunk-YVCUNZB5.js";
 import {
   RelIdAllocator,
   inlineNodeToRuns,
@@ -8,9 +8,6 @@ import {
   sanitizeOfficeHyperlink,
   toOoxmlHex
 } from "./chunk-A6N6IN3I.js";
-import {
-  extToMime
-} from "./chunk-B7GEAZBI.js";
 import {
   extractPlainText,
   stripHtmlTags
@@ -59,6 +56,9 @@ import {
   fontAwesomeFaces,
   fontAwesomeGlyph
 } from "./chunk-USU6HTKB.js";
+import {
+  extToMime
+} from "./chunk-RSU3V5IQ.js";
 
 // src/pptx/export.ts
 import { resolveFontFamily, VIEWPORT_PRESETS } from "@bendyline/squisq/schemas";
@@ -162,12 +162,19 @@ async function docToPptx(doc, options = {}) {
     { persistentLayers: doc.persistentLayers },
     theme
   );
+  const mediaAspectRatios = {};
+  for (const [source, picture] of effectiveOptions.diagramImages ?? []) {
+    if (picture.width > 0 && picture.height > 0) {
+      mediaAspectRatios[source] = picture.width / picture.height;
+    }
+  }
   const expanded = expandDocBlocks(flatBlocks, {
     audioSegments,
     viewport: VIEWPORT_PRESETS.landscape,
     persistentLayers,
     theme,
     customTemplates: doc.customTemplates,
+    mediaAspectRatios,
     // A .pptx is a discrete deck: the >20s pacing split would emit N identical
     // copies of one authored slide (a long single block became 18 duplicates),
     // and the <5s pacing merge would delete authored slides outright. Keep one
@@ -206,6 +213,7 @@ async function docToPptx(doc, options = {}) {
       effectiveOptions.allowRelativeHyperlinks ?? false,
       effectiveOptions.signal
     );
+    ctx.diagramImages = effectiveOptions.diagramImages;
     slideXmls.push(buildLayerSlideXml(slideBlocks[index], ctx));
     slideContexts.push(ctx);
   }
@@ -545,15 +553,46 @@ function convertLayerToShapes(layer, ctx, textBottom) {
         )
       ];
     }
-    case "mermaid":
+    case "mermaid": {
+      const picture = ctx.diagramImages?.get(layer.content.source.trim());
+      if (picture && picture.width > 0 && picture.height > 0) {
+        const data = picture.data instanceof Uint8Array ? picture.data.buffer.slice(
+          picture.data.byteOffset,
+          picture.data.byteOffset + picture.data.byteLength
+        ) : picture.data;
+        const relId = ctx.addImage(
+          `diagram-${ctx.embeddedImages.length + 1}.png`,
+          data,
+          mermaidTitle(layer.content.source)
+        );
+        const embedded = ctx.embeddedImages.find((candidate) => candidate.relId === relId);
+        const area = toEmuRect(resolveLayerRect(layer.position, 1920, 1080));
+        const scale = Math.min(area.width / picture.width, area.height / picture.height);
+        const width = Math.round(picture.width * scale);
+        const height = Math.round(picture.height * scale);
+        return [
+          buildImageShape(
+            embedded,
+            ctx.allocShapeId(),
+            area.x + Math.round((area.width - width) / 2),
+            area.y + Math.round((area.height - height) / 2),
+            width,
+            height
+          )
+        ];
+      }
       return [
         buildLayerTextShape(
           textLayerForPlaceholder(layer.position, layer.content.source, ctx),
           ctx.allocShapeId()
         )
       ];
+    }
   }
 }
+function mermaidTitle(source) {
+  return /^\s*accTitle\s*:\s*(.+?)\s*$/mu.exec(source)?.[1] ?? "Diagram";
+}
 function resolvePositionValue(value, dimension) {
   if (typeof value === "number") return value;
   if (typeof value === "string") {
@@ -1075,7 +1114,7 @@ function buildBodyShapeCustom(bodyContent, top, height, style) {
   return `<p:sp><p:nvSpPr><p:cNvPr id="3" name="Content"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr><p:nvPr><p:ph idx="1"/></p:nvPr></p:nvSpPr><p:spPr><a:xfrm><a:off x="${BODY_LEFT}" y="${top}"/><a:ext cx="${BODY_WIDTH}" cy="${height}"/></a:xfrm></p:spPr><p:txBody><a:bodyPr/><a:lstStyle><a:lvl1pPr>${defRPr}</a:lvl1pPr></a:lstStyle>` + bodyContent + `</p:txBody></p:sp>`;
 }
 function buildImageShape(img, shapeId, left, top, maxWidth, maxHeight) {
-  return `<p:pic><p:nvPicPr><p:cNvPr id="${shapeId}" name="${escapeXml(img.alt || "Picture")}"/><p:cNvPicPr><a:picLocks noChangeAspect="1"/></p:cNvPicPr><p:nvPr/></p:nvPicPr><p:blipFill><a:blip r:embed="${img.relId}"/><a:stretch><a:fillRect/></a:stretch></p:blipFill><p:spPr><a:xfrm><a:off x="${left}" y="${top}"/><a:ext cx="${maxWidth}" cy="${maxHeight}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr></p:pic>`;
+  return `<p:pic><p:nvPicPr><p:cNvPr id="${shapeId}" name="${escapeXml(img.alt || "Picture")}"${img.alt ? ` descr="${escapeXml(img.alt)}"` : ""}/><p:cNvPicPr><a:picLocks noChangeAspect="1"/></p:cNvPicPr><p:nvPr/></p:nvPicPr><p:blipFill><a:blip r:embed="${img.relId}"/><a:stretch><a:fillRect/></a:stretch></p:blipFill><p:spPr><a:xfrm><a:off x="${left}" y="${top}"/><a:ext cx="${maxWidth}" cy="${maxHeight}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr></p:pic>`;
 }
 function convertBodyBlocks(nodes, ctx) {
   const parts = [];

package/dist/{chunk-XJNOZTAY.js → chunk-EQAHFGGX.js}

@@ -5,9 +5,6 @@ import {
   normalizeOoxmlHex,
   sanitizeOfficeHyperlink
 } from "./chunk-A6N6IN3I.js";
-import {
-  extToMime
-} from "./chunk-B7GEAZBI.js";
 import {
   stripHtmlTags
 } from "./chunk-AVOZAKGP.js";
@@ -62,6 +59,11 @@ import {
   fontAwesomeGlyph,
   obfuscateDocxFont
 } from "./chunk-USU6HTKB.js";
+import {
+  extToMime,
+  fitWithin,
+  readImageDimensions
+} from "./chunk-RSU3V5IQ.js";
 
 // src/docx/export.ts
 import { resolveFontFamily } from "@bendyline/squisq/schemas";
@@ -526,59 +528,30 @@ function convertImage(node, ctx) {
   const ext = contentType.split("/")[1]?.replace("jpeg", "jpg") || "png";
   const filename = `image${ctx.images.length + 1}.${ext}`;
   const { relId, docPrId } = ctx.addImage(data, contentType, filename);
-  const dims = readImageDimensions(data);
+  const dims = imageEntry.width && imageEntry.height ? { width: imageEntry.width, height: imageEntry.height } : readImageDimensions(data);
   const EMU_PER_INCH = 914400;
   const MAX_WIDTH_EMU = 6 * EMU_PER_INCH;
+  const MAX_HEIGHT_EMU = 8 * EMU_PER_INCH;
   let cx;
   let cy;
   if (dims) {
-    const widthEmu = dims.width / 96 * EMU_PER_INCH;
-    const heightEmu = dims.height / 96 * EMU_PER_INCH;
-    if (widthEmu > MAX_WIDTH_EMU) {
-      const scale = MAX_WIDTH_EMU / widthEmu;
-      cx = MAX_WIDTH_EMU;
-      cy = Math.round(heightEmu * scale);
-    } else {
-      cx = Math.round(widthEmu);
-      cy = Math.round(heightEmu);
-    }
+    const fitted = fitWithin(
+      dims.width / 96 * EMU_PER_INCH,
+      dims.height / 96 * EMU_PER_INCH,
+      MAX_WIDTH_EMU,
+      MAX_HEIGHT_EMU
+    );
+    cx = Math.round(fitted.width);
+    cy = Math.round(fitted.height);
   } else {
     cx = 5 * EMU_PER_INCH;
     cy = 3 * EMU_PER_INCH;
   }
   const name = escapeXml(node.alt || filename);
+  const description = node.alt ? ` descr="${escapeXml(node.alt)}"` : "";
   const NS_A = "http://schemas.openxmlformats.org/drawingml/2006/main";
   const NS_PIC = "http://schemas.openxmlformats.org/drawingml/2006/picture";
-  return `<w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0"><wp:extent cx="${cx}" cy="${cy}"/><wp:docPr id="${docPrId}" name="${name}"/><wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a="${NS_A}" noChangeAspect="1"/></wp:cNvGraphicFramePr><a:graphic xmlns:a="${NS_A}"><a:graphicData uri="${NS_PIC}"><pic:pic xmlns:pic="${NS_PIC}"><pic:nvPicPr><pic:cNvPr id="0" name="${name}"/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip r:embed="${relId}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`;
-}
-function readImageDimensions(data) {
-  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
-  if (bytes.length < 24) return null;
-  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
-    const width = bytes[16] << 24 | bytes[17] << 16 | bytes[18] << 8 | bytes[19];
-    const height = bytes[20] << 24 | bytes[21] << 16 | bytes[22] << 8 | bytes[23];
-    return { width, height };
-  }
-  if (bytes[0] === 255 && bytes[1] === 216) {
-    let offset = 2;
-    while (offset < bytes.length - 9) {
-      if (bytes[offset] !== 255) break;
-      const marker = bytes[offset + 1];
-      if (marker === 192 || marker === 194) {
-        const height = bytes[offset + 5] << 8 | bytes[offset + 6];
-        const width = bytes[offset + 7] << 8 | bytes[offset + 8];
-        return { width, height };
-      }
-      const segLen = bytes[offset + 2] << 8 | bytes[offset + 3];
-      offset += 2 + segLen;
-    }
-  }
-  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70) {
-    const width = bytes[6] | bytes[7] << 8;
-    const height = bytes[8] | bytes[9] << 8;
-    return { width, height };
-  }
-  return null;
+  return `<w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0"><wp:extent cx="${cx}" cy="${cy}"/><wp:docPr id="${docPrId}" name="${name}"${description}/><wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a="${NS_A}" noChangeAspect="1"/></wp:cNvGraphicFramePr><a:graphic xmlns:a="${NS_A}"><a:graphicData uri="${NS_PIC}"><pic:pic xmlns:pic="${NS_PIC}"><pic:nvPicPr><pic:cNvPr id="0" name="${name}"/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip r:embed="${relId}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`;
 }
 function convertFootnoteRef(node, ctx) {
   const fnId = ctx.getFootnoteId(node.identifier);

package/dist/{chunk-3ITGQRL5.js → chunk-NVMYRBOJ.js}

@@ -1,7 +1,7 @@
 import {
   extractFilename,
   inferMimeType
-} from "./chunk-VPWPEMZJ.js";
+} from "./chunk-YVCUNZB5.js";
 import {
   extractPlainText
 } from "./chunk-AVOZAKGP.js";

package/dist/chunk-RSU3V5IQ.js

@@ -0,0 +1,73 @@
+// src/shared/images.ts
+var EXT_TO_MIME = {
+  // Raster / vector images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  svg: "image/svg+xml",
+  tiff: "image/tiff",
+  tif: "image/tiff",
+  ico: "image/x-icon",
+  avif: "image/avif",
+  // Office vector formats (docx/pptx embedded metafiles)
+  emf: "image/emf",
+  wmf: "image/wmf",
+  // Audio / video (html export inlines these as data URIs)
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  // Sidecar data files (`{[dataTable src=…]}` references)
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  parquet: "application/vnd.apache.parquet"
+};
+function extToMime(ext) {
+  const key = ext.replace(/^\./, "").toLowerCase();
+  return EXT_TO_MIME[key] ?? "application/octet-stream";
+}
+function readImageDimensions(data) {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (bytes.length < 24) return null;
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
+    const width = bytes[16] << 24 | bytes[17] << 16 | bytes[18] << 8 | bytes[19];
+    const height = bytes[20] << 24 | bytes[21] << 16 | bytes[22] << 8 | bytes[23];
+    return { width, height };
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    let offset = 2;
+    while (offset < bytes.length - 9) {
+      if (bytes[offset] !== 255) break;
+      const marker = bytes[offset + 1];
+      if (marker === 192 || marker === 194) {
+        const height = bytes[offset + 5] << 8 | bytes[offset + 6];
+        const width = bytes[offset + 7] << 8 | bytes[offset + 8];
+        return { width, height };
+      }
+      const segLen = bytes[offset + 2] << 8 | bytes[offset + 3];
+      offset += 2 + segLen;
+    }
+  }
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70) {
+    const width = bytes[6] | bytes[7] << 8;
+    const height = bytes[8] | bytes[9] << 8;
+    return { width, height };
+  }
+  return null;
+}
+function fitWithin(width, height, maxWidth, maxHeight) {
+  if (width <= 0 || height <= 0) return { width: 0, height: 0 };
+  const scale = Math.min(1, maxWidth / width, maxHeight / height);
+  return { width: width * scale, height: height * scale };
+}
+
+export {
+  extToMime,
+  readImageDimensions,
+  fitWithin
+};

package/dist/{chunk-XG6KFCPM.js → chunk-SAMQZRJU.js}

@@ -1,7 +1,7 @@
 import {
   convert,
   defaultRegistry
-} from "./chunk-2SUIARE4.js";
+} from "./chunk-VE2ADQ5T.js";
 import {
   ConversionError
 } from "./chunk-KXOZMWBS.js";

package/dist/{chunk-C7SPLITE.js → chunk-TLDBJH7D.js}

@@ -2,7 +2,7 @@ import {
   arrayBufferToBase64DataUrl,
   extractFilename,
   inferMimeType
-} from "./chunk-VPWPEMZJ.js";
+} from "./chunk-YVCUNZB5.js";
 import {
   FootnoteIndex,
   footnoteIds

package/dist/{chunk-2SUIARE4.js → chunk-VE2ADQ5T.js}

@@ -262,7 +262,7 @@ function dataReferenceWarnings(doc, formatLabel) {
 }
 async function collectContainerDocxImages(container, signal) {
   const images = await collectContainerImages(container, signal);
-  const { extToMime } = await import("./images-JLBFCDD4.js");
+  const { extToMime } = await import("./images-CAWESWRF.js");
   return new Map(
     [...images].map(([path, data]) => [
       path,
@@ -382,11 +382,14 @@ function defaultFormats() {
       const raw = optionsFor(options, "pdf");
       const markdownDoc = await markdownOf(input);
       const pdfWarnings = [];
+      const containerImages = await collectContainerDocxImages(input.container, options.signal);
+      const images = new Map([...containerImages, ...raw.images ?? /* @__PURE__ */ new Map()]);
       const buf = await markdownDocToPdf(markdownDoc, {
         ...raw,
         ...options.title !== void 0 ? { title: options.title } : {},
         themeId: resolveThemeId(input, options),
         themeRegistry: options.themeRegistry ?? raw.themeRegistry,
+        images,
         onWarning: (message) => pdfWarnings.push(message)
       });
       return ok(await toBytes(buf), MIME.pdf, [

package/dist/{chunk-VPWPEMZJ.js → chunk-YVCUNZB5.js}

@@ -1,6 +1,6 @@
 import {
   extToMime
-} from "./chunk-B7GEAZBI.js";
+} from "./chunk-RSU3V5IQ.js";
 
 // src/html/imageUtils.ts
 function inferMimeType(filename) {

package/dist/{chunk-ROF7SSQP.js → chunk-ZDRSDYXN.js}

@@ -9,6 +9,10 @@ import {
   fontAwesomeFaces,
   fontAwesomeGlyph
 } from "./chunk-USU6HTKB.js";
+import {
+  fitWithin,
+  readImageDimensions
+} from "./chunk-RSU3V5IQ.js";
 
 // src/pdf/export.ts
 import { PDFDocument, StandardFonts, rgb, PDFString } from "pdf-lib";
@@ -391,6 +395,7 @@ async function markdownDocToPdf(doc, options = {}) {
   pdfDoc.setCreationDate(/* @__PURE__ */ new Date());
   pdfDoc.setModificationDate(/* @__PURE__ */ new Date());
   const ctx = await createExportContext(pdfDoc, options, doc);
+  ctx.images = await embedDocumentImages(pdfDoc, doc, options.images);
   renderBlocks(doc.children, ctx, 0);
   const warning = ctx.text.warning();
   if (warning) {
@@ -404,6 +409,39 @@ async function docToPdf(doc, options = {}) {
   const markdownDoc = docToMarkdown(doc);
   return markdownDocToPdf(markdownDoc, options);
 }
+var POINTS_PER_CSS_PIXEL = 0.75;
+function collectImageUrls(nodes, into) {
+  for (const node of nodes) {
+    if (node.type === "image") into.add(node.url);
+    const children = node.children;
+    if (Array.isArray(children)) collectImageUrls(children, into);
+  }
+  return into;
+}
+async function embedDocumentImages(pdfDoc, doc, images) {
+  const embedded = /* @__PURE__ */ new Map();
+  if (!images || images.size === 0) return embedded;
+  for (const url of collectImageUrls(doc.children, /* @__PURE__ */ new Set())) {
+    const entry = images.get(url);
+    if (!entry) continue;
+    const bytes = entry.data instanceof Uint8Array ? entry.data : new Uint8Array(entry.data);
+    const isPng = bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71;
+    const isJpeg = bytes[0] === 255 && bytes[1] === 216;
+    if (!isPng && !isJpeg) continue;
+    try {
+      const image = isPng ? await pdfDoc.embedPng(bytes) : await pdfDoc.embedJpg(bytes);
+      const pixels = readImageDimensions(bytes) ?? { width: image.width, height: image.height };
+      const sized = Boolean(entry.width && entry.height);
+      embedded.set(url, {
+        image,
+        width: sized ? entry.width : pixels.width,
+        height: sized ? entry.height : pixels.height
+      });
+    } catch {
+    }
+  }
+  return embedded;
+}
 async function createExportContext(pdfDoc, options, doc) {
   const [regular, bold, italic, boldItalic, mono, monoBold] = await Promise.all([
     pdfDoc.embedFont(StandardFonts.Helvetica),
@@ -455,7 +493,8 @@ async function createExportContext(pdfDoc, options, doc) {
     colors: { text: colorText, heading: colorHeading, link: colorLink },
     footnotes: new FootnoteIndex(doc),
     text: new WinAnsiTracker(),
-    signal: options.signal
+    signal: options.signal,
+    images: /* @__PURE__ */ new Map()
   };
 }
 function ensureSpace(ctx, needed) {
@@ -812,6 +851,7 @@ function renderHeading(node, ctx, extraIndent) {
 function renderParagraph(node, ctx, extraIndent, colorOverride) {
   const x0 = ctx.margin + extraIndent;
   const w = ctx.contentWidth - extraIndent;
+  if (renderImageParagraph(node, ctx, x0, w)) return;
   const spans = flattenInlines(node.children, ctx, {
     bold: false,
     italic: false,
@@ -821,6 +861,38 @@ function renderParagraph(node, ctx, extraIndent, colorOverride) {
   drawSpans(spans, ctx, w, x0);
   ctx.y -= PARAGRAPH_SPACING;
 }
+function renderImageParagraph(node, ctx, x0, width) {
+  const images = node.children.filter((child) => child.type === "image");
+  const onlyImages = node.children.every(
+    (child) => child.type === "image" || child.type === "break" || child.type === "text" && !child.value.trim()
+  );
+  if (!onlyImages || images.length === 0) return false;
+  if (!images.some((image) => ctx.images.has(image.url))) return false;
+  const maxHeight = ctx.pageHeight - 2 * ctx.margin;
+  for (const imageNode of images) {
+    const embedded = ctx.images.get(imageNode.url);
+    if (!embedded) {
+      const note = flattenInlines([imageNode], ctx, { bold: false, italic: false, code: false });
+      drawSpans(note, ctx, width, x0);
+      continue;
+    }
+    const size = fitWithin(
+      embedded.width * POINTS_PER_CSS_PIXEL,
+      embedded.height * POINTS_PER_CSS_PIXEL,
+      width,
+      maxHeight
+    );
+    ensureSpace(ctx, size.height);
+    ctx.page.drawImage(embedded.image, {
+      x: x0 + (width - size.width) / 2,
+      y: ctx.y - size.height,
+      width: size.width,
+      height: size.height
+    });
+    ctx.y -= size.height + PARAGRAPH_SPACING;
+  }
+  return true;
+}
 function renderBlockquote(node, ctx, extraIndent) {
   const barX = ctx.margin + extraIndent + 4;
   const indent = extraIndent + BLOCKQUOTE_INDENT;

package/dist/diagrams/index.d.ts

@@ -0,0 +1,86 @@
+import { MarkdownDocument, MarkdownCodeBlock } from '@bendyline/squisq/markdown';
+
+/**
+ * Diagrams as pictures for document exports.
+ *
+ * DOCX, EPUB and PDF have no Mermaid or Squisq renderer, so a diagram would
+ * export as its source text. `rasterizeDiagrams` finds every diagram in a
+ * MarkdownDocument, asks a host-supplied renderer for a picture of it, and
+ * returns the document with each pictured diagram swapped for an image plus
+ * the picture bytes, ready for the exporters' `images` option. The renderer
+ * is supplied by the host because drawing needs a browser (Mermaid lays out
+ * text with the DOM); this module is environment-neutral.
+ *
+ * Diagrams are recognized the way the player recognizes them:
+ * - ```mermaid fences;
+ * - ASCII-art ```diagram, ```tree, and ```timeline fences (also unlabeled or
+ *   `text` fences whose content the detectors accept);
+ * - heading blocks with a container template — `{[drawing]}`, `{[layout]}`,
+ *   `{[diagram]}` — together with every child heading they own.
+ *
+ * `docToPptx` keeps drawings, timelines and ASCII diagrams as native shapes;
+ * for it, use the returned `mermaid` map as its `diagramImages` option.
+ */
+
+/** What kind of diagram a picture is wanted for. */
+type ExportDiagramKind = 'mermaid' | 'diagram' | 'timeline' | 'tree' | 'container';
+interface ExportDiagram {
+    readonly kind: ExportDiagramKind;
+    /**
+     * The diagram's own markdown: its fence, or for a container its heading
+     * and every child heading and body it owns.
+     */
+    readonly markdown: string;
+    /** The fence content for fence kinds; '' for containers. */
+    readonly source: string;
+    /** The container's template (`drawing`, `layout`, `diagram`); '' for fences. */
+    readonly template: string;
+    /** A text alternative for the picture. */
+    readonly alt: string;
+}
+/** A PNG picture of a diagram, with the size it should display at. */
+interface DiagramPicture {
+    readonly data: ArrayBuffer | Uint8Array;
+    /** Display size in CSS pixels (96 per inch); the PNG may be denser. */
+    readonly width: number;
+    readonly height: number;
+}
+/** Draws one diagram; resolves to null to leave that diagram as source. */
+type DiagramRasterizer = (diagram: ExportDiagram) => Promise<DiagramPicture | null>;
+interface RasterizeDiagramsOptions {
+    signal?: AbortSignal;
+    /** Limit the kinds pictured. Default: all of them. */
+    kinds?: readonly ExportDiagramKind[];
+    /** Prefix for the image URLs written into the document. Default: `diagram`. */
+    urlPrefix?: string;
+    /** Receives a note for each diagram the renderer could not draw. */
+    onWarning?: (message: string) => void;
+}
+interface RasterizedDiagrams {
+    /** The document with each pictured diagram replaced by an image of it. */
+    readonly markdownDoc: MarkdownDocument;
+    /**
+     * Picture bytes keyed by the image URL written into `markdownDoc`, in the
+     * shape the DOCX and PDF exporters take; EPUB takes `data` alone.
+     */
+    readonly images: Map<string, {
+        data: Uint8Array;
+        contentType: 'image/png';
+        width: number;
+        height: number;
+    }>;
+    /** Pictures of Mermaid diagrams keyed by trimmed source, for `docToPptx`'s `diagramImages`. */
+    readonly mermaid: Map<string, DiagramPicture>;
+}
+/** The diagram kind of a fence, or null for ordinary code. */
+declare function fenceDiagramKind(node: MarkdownCodeBlock): ExportDiagramKind | null;
+/** Every diagram in `doc`, in document order. */
+declare function findDiagrams(doc: MarkdownDocument): ExportDiagram[];
+/**
+ * Picture every diagram in `doc` with `render`, one at a time, and return
+ * the document with each pictured diagram replaced by an image of it. A
+ * diagram the renderer declines or fails on stays as it was.
+ */
+declare function rasterizeDiagrams(doc: MarkdownDocument, render: DiagramRasterizer, options?: RasterizeDiagramsOptions): Promise<RasterizedDiagrams>;
+
+export { type DiagramPicture, type DiagramRasterizer, type ExportDiagram, type ExportDiagramKind, type RasterizeDiagramsOptions, type RasterizedDiagrams, fenceDiagramKind, findDiagrams, rasterizeDiagrams };