@boxpdf/html-writer 0.1.18 → 0.1.21

package/dist/index.cjs

@@ -22,45 +22,157 @@ var index_exports = {};
 __export(index_exports, {
   pageToHtml: () => pageToHtml,
   writeHtmlDocument: () => writeHtmlDocument,
+  writeMarkdownDocument: () => writeMarkdownDocument,
   writePage: () => writePage
 });
 module.exports = __toCommonJS(index_exports);
 var import_structure2 = require("@boxpdf/reader/structure");
 
 // src/semantic-caption.ts
-function isClearMediaCaption(media, block, pageWidth, pageHeight, pageLines) {
-  if (block.type !== "paragraph" || block.lines.length === 0) return false;
-  const bounds2 = unionLines(block.lines);
-  const lineHeight = median(block.lines.map((line) => line.bounds.height));
-  if (media.bounds.width < pageWidth * 0.2 || media.bounds.height < lineHeight * 10) return false;
-  if (media.bounds.x < -2 || media.bounds.y < -2 || media.bounds.x + media.bounds.width > pageWidth + 2 || media.bounds.y + media.bounds.height > pageHeight + 2)
-    return false;
-  const gap = media.bounds.y - (bounds2.y + bounds2.height);
-  if (gap < -lineHeight * 0.15 || gap > lineHeight * 1.25) return false;
-  const mediaCenter = media.bounds.x + media.bounds.width / 2;
-  const captionCenter = bounds2.x + bounds2.width / 2;
-  if (Math.abs(mediaCenter - captionCenter) > Math.max(3, media.bounds.width * 0.03)) return false;
-  if (bounds2.width < media.bounds.width * 0.45 || bounds2.width > media.bounds.width * 1.06) {
-    return false;
-  }
-  const first = block.lines.flatMap((line) => line.spans).find((span) => /\S/u.test(span.text));
-  if (!first) return false;
-  const otherLines = pageLines.filter((line) => !block.lines.includes(line));
-  return fontSignature(first) !== dominantFontSignature(otherLines);
-}
+var minimumCaptionScore = 0.72;
 function clearMediaCaptionAssociations(media, blocks, pageWidth, pageHeight, pageLines) {
+  const candidates = blocks.flatMap((block) => {
+    const candidate = captionCandidate(block);
+    return candidate ? [candidate] : [];
+  });
+  const preliminary = media.flatMap(
+    (item) => candidates.flatMap((candidate) => {
+      const evidence = scoreCaption(item, candidate, pageWidth, pageHeight, pageLines, 0);
+      return evidence ? [{ media: item, candidate, evidence }] : [];
+    })
+  );
+  const patterns = repeatedPatterns(preliminary);
+  const edges = preliminary.map((edge) => {
+    const evidence = scoreCaption(
+      edge.media,
+      edge.candidate,
+      pageWidth,
+      pageHeight,
+      pageLines,
+      patterns.get(patternKey(edge)) ?? 0
+    );
+    return evidence ? { ...edge, evidence } : void 0;
+  }).filter((edge) => Boolean(edge)).filter((edge) => edge.evidence.score >= minimumCaptionScore);
+  const bestForMedia = bestEdges(edges, (edge) => edge.media);
+  const bestForCaption = bestEdges(edges, (edge) => edge.candidate.block);
   const associations = /* @__PURE__ */ new Map();
-  for (const item of media) {
-    const candidates = blocks.filter((block) => isClearMediaCaption(item, block, pageWidth, pageHeight, pageLines)).filter((block) => !associations.has(block)).sort((left, right) => captionGap(item, left) - captionGap(item, right));
-    const caption = candidates[0];
-    if (caption) associations.set(caption, item);
+  for (const edge of edges) {
+    if (bestForMedia.get(edge.media) === edge && bestForCaption.get(edge.candidate.block) === edge) {
+      associations.set(edge.candidate.block, edge.media);
+    }
   }
   return associations;
 }
-function captionGap(media, block) {
-  if (block.type !== "paragraph") return Number.POSITIVE_INFINITY;
-  const bounds2 = unionLines(block.lines);
-  return Math.abs(media.bounds.y - bounds2.y - bounds2.height);
+function scoreCaption(media, candidate, pageWidth, pageHeight, pageLines, repeatedAlignment) {
+  if (!insidePage(media.bounds, pageWidth, pageHeight)) return void 0;
+  if (media.bounds.width < pageWidth * 0.06 || media.bounds.height < candidate.lineHeight * 1.5)
+    return void 0;
+  const relation = verticalRelation(media.bounds, candidate.bounds);
+  if (!relation) return void 0;
+  const maximumGap = Math.max(candidate.lineHeight * 3, pageHeight * 0.035);
+  if (relation.gap > maximumGap) return void 0;
+  const overlapWidth = overlap(
+    media.bounds.x,
+    media.bounds.width,
+    candidate.bounds.x,
+    candidate.bounds.width
+  );
+  const horizontalOverlap = overlapWidth / Math.max(1, Math.min(media.bounds.width, candidate.bounds.width));
+  const centerDistance = Math.abs(center(media.bounds) - center(candidate.bounds));
+  const centerAlignment = clamp01(
+    1 - centerDistance / Math.max(media.bounds.width, candidate.bounds.width)
+  );
+  if (horizontalOverlap < 0.45 && centerAlignment < 0.82) return void 0;
+  const relativeWidth = Math.min(media.bounds.width, candidate.bounds.width) / Math.max(media.bounds.width, candidate.bounds.width);
+  const gapRatio = clamp01(1 - relation.gap / maximumGap);
+  const interveningContent = interveningScore(media.bounds, candidate, relation.side, pageLines);
+  if (interveningContent === 0) return void 0;
+  if (relation.side === "above" && (gapRatio < 0.6 || interveningContent < 1)) return void 0;
+  const fontContrast = captionFontContrast(candidate, pageLines);
+  const surroundingWhitespace = whitespaceScore(candidate, relation.side, relation.gap, pageLines);
+  const score = gapRatio * 0.22 + horizontalOverlap * 0.17 + centerAlignment * 0.13 + relativeWidth * 0.09 + fontContrast * 0.13 + surroundingWhitespace * 0.09 + interveningContent * 0.09 + repeatedAlignment * 0.08;
+  return {
+    score,
+    side: relation.side,
+    gapRatio,
+    horizontalOverlap,
+    centerAlignment,
+    relativeWidth,
+    fontContrast,
+    surroundingWhitespace,
+    interveningContent,
+    repeatedAlignment
+  };
+}
+function captionCandidate(block) {
+  if (block.type !== "paragraph" || block.lines.length === 0) return void 0;
+  const first = block.lines.flatMap((line) => line.spans).find((span) => /\S/u.test(span.text));
+  if (!first) return void 0;
+  return {
+    block,
+    bounds: unionLines(block.lines),
+    lineHeight: median(block.lines.map((line) => line.bounds.height)),
+    font: fontSignature(first)
+  };
+}
+function verticalRelation(media, caption) {
+  const belowGap = media.y - (caption.y + caption.height);
+  if (belowGap >= -caption.height * 0.15) return { side: "below", gap: Math.max(0, belowGap) };
+  const aboveGap = caption.y - (media.y + media.height);
+  if (aboveGap >= -caption.height * 0.15) return { side: "above", gap: Math.max(0, aboveGap) };
+  return void 0;
+}
+function interveningScore(media, candidate, side, pageLines) {
+  const lower = side === "below" ? candidate.bounds.y + candidate.bounds.height : media.y + media.height;
+  const upper = side === "below" ? media.y : candidate.bounds.y;
+  const blockers = pageLines.filter(
+    (line) => !candidate.block.lines.includes(line) && line.bounds.y < upper && line.bounds.y + line.bounds.height > lower && overlap(line.bounds.x, line.bounds.width, media.x, media.width) / Math.max(1, Math.min(line.bounds.width, media.width)) >= 0.25
+  );
+  return blockers.length === 0 ? 1 : blockers.length === 1 ? 0.35 : 0;
+}
+function captionFontContrast(candidate, pageLines) {
+  const otherLines = pageLines.filter((line) => !candidate.block.lines.includes(line));
+  if (candidate.font !== dominantFontSignature(otherLines)) return 1;
+  const candidateSize = median(
+    candidate.block.lines.flatMap((line) => line.spans.map((span) => span.fontSize))
+  );
+  const bodySize = median(otherLines.flatMap((line) => line.spans.map((span) => span.fontSize)));
+  return Math.abs(candidateSize - bodySize) >= 0.75 ? 0.65 : 0.15;
+}
+function whitespaceScore(candidate, side, mediaGap, pageLines) {
+  const awayGaps = pageLines.filter((line) => !candidate.block.lines.includes(line)).filter(
+    (line) => overlap(line.bounds.x, line.bounds.width, candidate.bounds.x, candidate.bounds.width) > 0
+  ).flatMap((line) => {
+    if (side === "below" && line.bounds.y + line.bounds.height <= candidate.bounds.y)
+      return [candidate.bounds.y - line.bounds.y - line.bounds.height];
+    if (side === "above" && line.bounds.y >= candidate.bounds.y + candidate.bounds.height)
+      return [line.bounds.y - candidate.bounds.y - candidate.bounds.height];
+    return [];
+  });
+  const awayGap = Math.min(...awayGaps, Number.POSITIVE_INFINITY);
+  return Number.isFinite(awayGap) ? clamp01((awayGap + candidate.lineHeight * 0.25) / (mediaGap + candidate.lineHeight)) : 1;
+}
+function repeatedPatterns(edges) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const edge of edges.filter((item) => item.evidence.score >= minimumCaptionScore - 0.08)) {
+    counts.set(patternKey(edge), (counts.get(patternKey(edge)) ?? 0) + 1);
+  }
+  return new Map([...counts].map(([key, count]) => [key, count >= 2 ? 1 : 0]));
+}
+function patternKey(edge) {
+  const widthRatio = edge.candidate.bounds.width / Math.max(1, edge.media.bounds.width);
+  return `${edge.candidate.font}|${edge.evidence.side}|${Math.round(widthRatio * 4) / 4}`;
+}
+function bestEdges(edges, key) {
+  const output = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    const existing = output.get(key(edge));
+    if (!existing || edge.evidence.score > existing.evidence.score) output.set(key(edge), edge);
+  }
+  return output;
+}
+function insidePage(bounds2, pageWidth, pageHeight) {
+  return bounds2.x >= -2 && bounds2.y >= -2 && bounds2.x + bounds2.width <= pageWidth + 2 && bounds2.y + bounds2.height <= pageHeight + 2;
 }
 function unionLines(lines) {
   const x = Math.min(...lines.map((line) => line.bounds.x));
@@ -80,6 +192,15 @@ function dominantFontSignature(lines) {
 function fontSignature(span) {
   return `${(span.fontFamily ?? span.fontName ?? "").toLocaleLowerCase("en")}|${Math.round(span.fontSize * 2) / 2}|${span.color ?? ""}`;
 }
+function center(bounds2) {
+  return bounds2.x + bounds2.width / 2;
+}
+function overlap(left, leftSize, right, rightSize) {
+  return Math.max(0, Math.min(left + leftSize, right + rightSize) - Math.max(left, right));
+}
+function clamp01(value) {
+  return Math.max(0, Math.min(1, value));
+}
 function median(values) {
   const ordered = [...values].sort((left, right) => left - right);
   return ordered[Math.floor(ordered.length / 2)] ?? 1;
@@ -98,6 +219,12 @@ function dominantTextColor(lines) {
   return [...counts].sort((left, right) => right[1] - left[1])[0]?.[0] ?? "#000000";
 }
 function semanticTextHtml(text, lines, defaultColor, preserveWeight = true) {
+  return semanticText(text, lines, defaultColor, preserveWeight, "html");
+}
+function semanticTextMarkdown(text, lines, defaultColor, preserveWeight = true) {
+  return semanticText(text, lines, defaultColor, preserveWeight, "markdown");
+}
+function semanticText(text, lines, defaultColor, preserveWeight, format) {
   const ranges = [];
   let cursor = 0;
   for (const span of lines.flatMap((line) => line.spans)) {
@@ -123,11 +250,11 @@ function semanticTextHtml(text, lines, defaultColor, preserveWeight = true) {
   let html = "";
   let offset = 0;
   for (const range of merged) {
-    html += escapeHtml(text.slice(offset, range.start));
-    html += styledHtml(text.slice(range.start, range.end), range);
+    html += escapeText(text.slice(offset, range.start), format);
+    html += styledText(text.slice(range.start, range.end), range, format);
     offset = range.end;
   }
-  return html + escapeHtml(text.slice(offset));
+  return html + escapeText(text.slice(offset), format);
 }
 function mergeRanges(ranges, text) {
   const merged = [];
@@ -141,13 +268,19 @@ function mergeRanges(ranges, text) {
   }
   return merged;
 }
-function styledHtml(value, range) {
-  let html = escapeHtml(value);
+function styledText(value, range, format) {
+  let html = escapeText(value, format);
   if (range.color) html = `<span style="color:${range.color}">${html}</span>`;
-  if (range.italic) html = `<em>${html}</em>`;
-  if (range.bold) html = `<strong>${html}</strong>`;
+  if (range.italic) html = format === "html" ? `<em>${html}</em>` : `_${html}_`;
+  if (range.bold) html = format === "html" ? `<strong>${html}</strong>` : `**${html}**`;
   return html;
 }
+function escapeText(value, format) {
+  return format === "html" ? escapeHtml(value) : escapeMarkdown(value);
+}
+function escapeMarkdown(value) {
+  return value.replace(/([\\`*_[\]<>])/g, "\\$1");
+}
 function normalizedColor(value) {
   if (!value || !/^#[\da-f]{6}$/i.test(value)) return void 0;
   const color = value.toLowerCase();
@@ -283,22 +416,39 @@ function base64(bytes) {
 }
 
 // src/semantic-media.ts
-function semanticMedia(page) {
-  const output = (page.images ?? []).map((image) => rasterMedia(image));
-  output.push(...vectorMedia(page));
-  return output.sort((left, right) => right.bounds.y - left.bounds.y);
+function semanticMedia(page, imageOptions = "embedded") {
+  if (imageOptions === "excluded") return [];
+  const output = (page.images ?? []).map(
+    (image, index) => rasterMedia(image, page.number, index, imageOptions)
+  );
+  output.push(...vectorMedia(page, imageOptions));
+  return mediaComponents(output, page).sort((left, right) => right.bounds.y - left.bounds.y);
+}
+async function prepareSemanticMedia(page, imageOptions, onImage) {
+  const media = semanticMedia(page, imageOptions);
+  for (const item of media) {
+    for (const asset of item.assets ?? []) await onImage?.(asset);
+    delete item.assets;
+  }
+  return media;
 }
-function rasterMedia(image) {
+function rasterMedia(image, pageNumber, index, imageOptions) {
   const bounds2 = transformedUnitBounds(image.transform);
   const mime = image.format === "jpeg" ? "image/jpeg" : "image/bmp";
   const data = image.format === "jpeg" ? image.data : rgbBmp(image);
+  const extension = image.format === "jpeg" ? "jpg" : "bmp";
+  const name = `page-${pageNumber}-image-${index + 1}.${extension}`;
+  const source = imageOptions === "references" ? name : `data:${mime};base64,${base64(data)}`;
   const opacity = unitInterval(image.opacity) ? `;opacity:${number2(image.opacity)}` : "";
   return {
     bounds: bounds2,
-    html: `<img class="pdf-semantic-media" src="data:${mime};base64,${base64(data)}" width="${number2(bounds2.width)}" height="${number2(bounds2.height)}" alt="" style="max-width:100%;height:auto${opacity}">`
+    kind: "raster",
+    html: `<img class="pdf-semantic-media" src="${source}" width="${number2(bounds2.width)}" height="${number2(bounds2.height)}" alt="" style="max-width:100%;height:auto${opacity}">`,
+    markdown: `![](${source})`,
+    ...imageOptions === "references" ? { assets: [{ name, mimeType: mime, data }] } : {}
   };
 }
-function vectorMedia(page) {
+function vectorMedia(page, imageOptions) {
   const primitives = [
     ...(page.paths ?? []).flatMap((path, index) => {
       const bounds2 = vectorPathBounds(path);
@@ -316,7 +466,7 @@ function vectorMedia(page) {
   const visualCodeFonts = new Set(
     (page.fonts ?? []).filter((font) => font.format === "truetype" && font.visualCodeMapping).map((font) => font.id)
   );
-  return components.map((component) => {
+  return components.map((component, componentIndex) => {
     const bounds2 = component.bounds;
     const paths = component.primitives.flatMap(
       (primitive) => primitive.type === "path" ? [{ path: primitive.value, index: primitive.index }] : []
@@ -333,13 +483,82 @@ function vectorMedia(page) {
     );
     const fontIds = new Set(overlay.map((span) => span.fontAssetId));
     const fontFaces = (page.fonts ?? []).filter((font) => fontIds.has(font.id)).map((font) => visualFontFace(font, aliases)).join("");
+    const svg = `<svg class="pdf-semantic-media" xmlns="http://www.w3.org/2000/svg" viewBox="${number2(bounds2.x)} ${number2(page.height - bounds2.y - bounds2.height)} ${number2(bounds2.width)} ${number2(bounds2.height)}" style="display:block;max-width:100%;height:auto" aria-hidden="true">${fontFaces ? `<style>${fontFaces}</style>` : ""}${paths.length ? `<defs>${vectorPathClipDefinitions(paths, page.number)}</defs>` : ""}<g transform="translate(0 ${number2(page.height)}) scale(1 -1)">${fills.map(vectorFillSvg).join("") + paths.map(({ path, index }) => vectorPathSvg(path, page.number, index)).join("")}</g>${overlay.map((span) => vectorText(span, page.height, aliases)).join("")}</svg>`;
+    const name = `page-${page.number}-vector-${componentIndex + 1}.svg`;
     return {
       bounds: bounds2,
-      html: `<svg class="pdf-semantic-media" xmlns="http://www.w3.org/2000/svg" viewBox="${number2(bounds2.x)} ${number2(page.height - bounds2.y - bounds2.height)} ${number2(bounds2.width)} ${number2(bounds2.height)}" style="display:block;max-width:100%;height:auto" aria-hidden="true">${fontFaces ? `<style>${fontFaces}</style>` : ""}${paths.length ? `<defs>${vectorPathClipDefinitions(paths, page.number)}</defs>` : ""}<g transform="translate(0 ${number2(page.height)}) scale(1 -1)">${fills.map(vectorFillSvg).join("") + paths.map(({ path, index }) => vectorPathSvg(path, page.number, index)).join("")}</g>${overlay.map((span) => vectorText(span, page.height, aliases)).join("")}</svg>`,
+      kind: "vector",
+      html: imageOptions === "references" ? `<img class="pdf-semantic-media" src="${name}" width="${number2(bounds2.width)}" height="${number2(bounds2.height)}" alt="">` : svg,
+      markdown: imageOptions === "references" ? `![](${name})` : svg,
+      ...imageOptions === "references" ? {
+        assets: [
+          { name, mimeType: "image/svg+xml", data: new TextEncoder().encode(svg) }
+        ]
+      } : {},
       ...consumedSpans.length > 0 ? { consumedSpans } : {}
     };
   });
 }
+function mediaComponents(media, page) {
+  const components = [];
+  for (const item of media) {
+    if (isPageBackdrop(item.bounds, page)) {
+      components.push([item]);
+      continue;
+    }
+    const matches = components.filter(
+      (component) => !component.some((member) => isPageBackdrop(member.bounds, page)) && component.some((member) => mediaPiecesTouch(member.bounds, item.bounds))
+    );
+    if (matches.length === 0) {
+      components.push([item]);
+      continue;
+    }
+    const target = matches[0];
+    target.push(item);
+    for (const component of matches.slice(1)) {
+      target.push(...component);
+      components.splice(components.indexOf(component), 1);
+    }
+  }
+  return components.map((component) => compositeMedia(component));
+}
+function compositeMedia(items) {
+  if (items.length === 1) return items[0];
+  const bounds2 = unionBounds(items.map((item) => item.bounds));
+  const layers = items.map((item) => {
+    const left = (item.bounds.x - bounds2.x) / bounds2.width * 100;
+    const top = (bounds2.y + bounds2.height - item.bounds.y - item.bounds.height) / bounds2.height * 100;
+    const width = item.bounds.width / bounds2.width * 100;
+    const height = item.bounds.height / bounds2.height * 100;
+    return `<div style="position:absolute;left:${number2(left)}%;top:${number2(top)}%;width:${number2(width)}%;height:${number2(height)}%;overflow:hidden">${item.html}</div>`;
+  }).join("");
+  return {
+    bounds: bounds2,
+    kind: "composite",
+    html: `<div class="pdf-semantic-media pdf-semantic-media-composite" style="position:relative;max-width:100%;width:${number2(bounds2.width)}px;aspect-ratio:${number2(bounds2.width)}/${number2(bounds2.height)}">${layers}</div>`,
+    markdown: items.map((item) => item.markdown).join("\n\n"),
+    consumedSpans: items.flatMap((item) => item.consumedSpans ?? []),
+    assets: items.flatMap((item) => item.assets ?? [])
+  };
+}
+function mediaPiecesTouch(left, right) {
+  const xOverlap = overlap2(left.x, left.width, right.x, right.width);
+  const yOverlap = overlap2(left.y, left.height, right.y, right.height);
+  if (xOverlap > 0 && yOverlap > 0) return true;
+  const horizontalGap = axisGap(left.x, left.width, right.x, right.width);
+  const verticalGap = axisGap(left.y, left.height, right.y, right.height);
+  if (horizontalGap <= 2 && yOverlap / Math.min(left.height, right.height) >= 0.65) return true;
+  return verticalGap <= 2 && xOverlap / Math.min(left.width, right.width) >= 0.65;
+}
+function isPageBackdrop(bounds2, page) {
+  return bounds2.width * bounds2.height >= page.width * page.height * 0.7;
+}
+function overlap2(left, leftSize, right, rightSize) {
+  return Math.max(0, Math.min(left + leftSize, right + rightSize) - Math.max(left, right));
+}
+function axisGap(left, leftSize, right, rightSize) {
+  return Math.max(0, right - left - leftSize, left - right - rightSize);
+}
 function vectorComponents(primitives, padding) {
   const components = [];
   for (const primitive of primitives) {
@@ -458,7 +677,7 @@ function escapeHtml2(value) {
 }
 
 // src/semantic-document.ts
-async function writeSemanticDocument(pages, write, lookaheadPages) {
+async function writeSemanticDocument(pages, write, lookaheadPages, imageOptions, onImage, format = "html") {
   const stats = {
     pagesProcessed: 0,
     peakBufferedPages: 0,
@@ -476,27 +695,30 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
   let contentStarted = false;
   let employmentOpen = false;
   let pendingParagraph;
-  await write('<article class="pdf-semantic-document">');
+  const markdown = format === "markdown";
+  const output = (html, markdownValue = "") => write(markdown ? markdownValue : html);
+  const inlineText = (text, lines, defaultColor, preserveWeight = true) => markdown ? semanticTextMarkdown(text, lines, defaultColor, preserveWeight) : semanticTextHtml(text, lines, defaultColor, preserveWeight);
+  await output('<article class="pdf-semantic-document">');
   const closeTable = async () => {
     if (!activeTable) return;
-    await write("</table>");
+    await output("</table>", "\n");
     activeTable = void 0;
     while (pendingMedia.length > 0) await write(pendingMedia.shift() ?? "");
   };
   const closeSections = async (minimumLevel = 0) => {
     while ((sectionLevels.at(-1) ?? -1) >= minimumLevel && sectionLevels.length > 0) {
-      await write("</section>");
+      await output("</section>");
       sectionLevels.pop();
     }
   };
   const flushPendingParagraph = async () => {
     if (!pendingParagraph) return;
-    await write(semanticBlockHtml(pendingParagraph.block, pendingParagraph.defaultColor));
+    await write(semanticBlockOutput(pendingParagraph.block, pendingParagraph.defaultColor, format));
     pendingParagraph = void 0;
   };
   const closeEmployment = async () => {
     if (!employmentOpen) return;
-    await write("</section>");
+    await output("</section>");
     employmentOpen = false;
   };
   const emitPage = async (page, future) => {
@@ -510,29 +732,53 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
       page.structured.lines
     );
     const captionedMedia = new Set(captions.values());
+    const emittedMedia = /* @__PURE__ */ new Set();
     const futureFurniture = new Set(future.flatMap((candidate) => marginSignatures(candidate)));
     const repeatedFurniture = /* @__PURE__ */ new Set([...seenFurniture, ...futureFurniture]);
     for (const [blockIndex, block] of page.structured.blocks.entries()) {
       const nextBlock = page.structured.blocks[blockIndex + 1];
       const blockY = semanticBlockY(block);
       let emittedAsCaption = false;
+      while (page.media[mediaIndex] && emittedMedia.has(page.media[mediaIndex])) {
+        mediaIndex += 1;
+      }
       while ((page.media[mediaIndex]?.bounds.y ?? -Infinity) >= blockY) {
         await flushPendingParagraph();
         const item = page.media[mediaIndex];
         if (item && captions.get(block) === item && block.type === "paragraph") {
-          const html2 = `<figure class="pdf-semantic-figure">${item.html}<figcaption>${semanticTextHtml(block.text, block.lines, defaultColor)}</figcaption></figure>`;
+          const html2 = markdown ? `${item.markdown}
+
+*${inlineText(block.text, block.lines, defaultColor)}*
+
+` : `<figure class="pdf-semantic-figure">${item.html}<figcaption>${inlineText(block.text, block.lines, defaultColor)}</figcaption></figure>`;
           if (activeTable) pendingMedia.push(html2);
           else await write(html2);
+          emittedMedia.add(item);
           mediaIndex += 1;
           emittedAsCaption = true;
           break;
         }
         if (item && captionedMedia.has(item)) break;
-        const html = `<div class="pdf-semantic-visual">${item?.html}</div>`;
+        const html = markdown ? `${item?.markdown ?? ""}
+
+` : `<div class="pdf-semantic-visual">${item?.html}</div>`;
         if (activeTable) pendingMedia.push(html);
         else await write(html);
         mediaIndex += 1;
       }
+      const associatedMedia = captions.get(block);
+      if (!emittedAsCaption && associatedMedia && block.type === "paragraph") {
+        await flushPendingParagraph();
+        const html = markdown ? `${associatedMedia.markdown}
+
+*${inlineText(block.text, block.lines, defaultColor)}*
+
+` : `<figure class="pdf-semantic-figure">${associatedMedia.html}<figcaption>${inlineText(block.text, block.lines, defaultColor)}</figcaption></figure>`;
+        if (activeTable) pendingMedia.push(html);
+        else await write(html);
+        emittedMedia.add(associatedMedia);
+        emittedAsCaption = true;
+      }
       if (emittedAsCaption) continue;
       if (isRepeatedFurniture(block, page, repeatedFurniture)) {
         stats.suppressedFurniture += 1;
@@ -541,8 +787,11 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
       await flushPendingParagraph();
       if (employmentOpen && block.type !== "list") await closeEmployment();
       if (!contentStarted && !headerOpen && block.type === "heading" && block.level === 1) {
-        await write(
-          `<header><h1>${semanticTextHtml(block.text, block.lines, defaultColor, false)}</h1>`
+        await output(
+          `<header><h1>${inlineText(block.text, block.lines, defaultColor, false)}</h1>`,
+          `# ${inlineText(block.text, block.lines, defaultColor, false)}
+
+`
         );
         headerOpen = true;
         continue;
@@ -550,19 +799,25 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
       if (headerOpen) {
         if (block.type === "paragraph") {
           const tag = isContactBlock(block) ? "address" : "p";
-          await write(
-            `<${tag}>${semanticTextHtml(block.text, block.lines, defaultColor)}</${tag}>`
+          await output(
+            `<${tag}>${inlineText(block.text, block.lines, defaultColor)}</${tag}>`,
+            `${inlineText(block.text, block.lines, defaultColor)}
+
+`
           );
           headerHasParagraph = true;
           continue;
         }
         if (block.type === "heading" && !headerHasParagraph && (block.level === 1 || block.text.trimStart().startsWith("#") || block.level === 4 && nextBlock?.type === "paragraph" && isContactBlock(nextBlock))) {
-          await write(
-            `<h${block.level}>${semanticTextHtml(block.text, block.lines, defaultColor, false)}</h${block.level}>`
+          await output(
+            `<h${block.level}>${inlineText(block.text, block.lines, defaultColor, false)}</h${block.level}>`,
+            `${"#".repeat(block.level)} ${inlineText(block.text, block.lines, defaultColor, false)}
+
+`
           );
           continue;
         }
-        await write("</header>");
+        await output("</header>");
         headerOpen = false;
         contentStarted = true;
       }
@@ -570,23 +825,34 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
         const rows = (0, import_structure.tableToRows)(block.table);
         if (activeTable && tablesContinue(activeTable.table, block.table, page.width)) {
           const continuationRows = sameRow(activeTable.header, rows[0]) ? rows.slice(1) : rows;
-          for (const row of continuationRows) await write(tableRow(row, false));
+          for (const row of continuationRows)
+            await write(markdown ? markdownTableRow(row) : tableRow(row, false));
           activeTable.table = block.table;
           stats.mergedTables += 1;
           continue;
         }
         await closeTable();
         const header = tableHeader(rows);
-        await write("<table>");
-        for (const [index, row] of rows.entries())
-          await write(tableRow(row, Boolean(header && index === 0)));
+        await output("<table>", markdownTableStart(rows, header));
+        const markdownRows = markdown ? header ? rows.slice(1) : rows : rows;
+        for (const [index, row] of markdownRows.entries())
+          await write(
+            markdown ? markdownTableRow(row) : tableRow(row, Boolean(header && index === 0))
+          );
         activeTable = { table: block.table, header };
         continue;
       }
       if (activeTable && block.type === "definitionList" && isFinancialSummary(block)) {
         const columns = activeTable.table.columns.length;
-        await write(
-          `<tfoot>${block.entries.map((entry) => financialSummaryRow(entry, columns)).join("")}</tfoot>`
+        await output(
+          `<tfoot>${block.entries.map((entry) => financialSummaryRow(entry, columns)).join("")}</tfoot>`,
+          block.entries.map(
+            (entry) => markdownTableRow([
+              entry.term,
+              ...Array(Math.max(0, columns - 2)).fill(""),
+              entry.description
+            ])
+          ).join("")
         );
         await closeTable();
         continue;
@@ -595,8 +861,11 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
       if (block.type === "heading") {
         const level = contentStarted && block.level === 1 ? 2 : block.level;
         await closeSections(level);
-        await write(
-          `<section data-level="${level}"><h${level}>${semanticTextHtml(block.text, block.lines, defaultColor, false)}</h${level}>`
+        await output(
+          `<section data-level="${level}"><h${level}>${inlineText(block.text, block.lines, defaultColor, false)}</h${level}>`,
+          `${"#".repeat(level)} ${inlineText(block.text, block.lines, defaultColor, false)}
+
+`
         );
         sectionLevels.push(level);
         continue;
@@ -604,13 +873,25 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
       if (block.type === "paragraph") {
         if (isTitledRecord(block)) {
           const [institution, ...details] = block.lines;
-          if (institution) await write(`<h3>${escapeHtml3(institution.text)}</h3>`);
-          for (const detail of details) await write(`<p>${escapeHtml3(detail.text)}</p>`);
+          if (institution)
+            await output(
+              `<h3>${escapeHtml3(institution.text)}</h3>`,
+              `### ${escapeMarkdown2(institution.text)}
+
+`
+            );
+          for (const detail of details)
+            await output(`<p>${escapeHtml3(detail.text)}</p>`, `${escapeMarkdown2(detail.text)}
+
+`);
           continue;
         }
         if (isUnmarkedList(block)) {
-          await write(
-            `<ul>${block.lines.map((line) => `<li>${escapeHtml3(line.text)}</li>`).join("")}</ul>`
+          await output(
+            `<ul>${block.lines.map((line) => `<li>${escapeHtml3(line.text)}</li>`).join("")}</ul>`,
+            `${block.lines.map((line) => `- ${escapeMarkdown2(line.text)}`).join("\n")}
+
+`
           );
           continue;
         }
@@ -618,27 +899,40 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
         continue;
       }
       if (block.type === "employment") {
-        await write(
-          `<section><h3>${escapeHtml3(block.role)}</h3><p>${escapeHtml3(block.organization)}</p><p>${escapeHtml3(block.date)}</p>`
+        await output(
+          `<section><h3>${escapeHtml3(block.role)}</h3><p>${escapeHtml3(block.organization)}</p><p>${escapeHtml3(block.date)}</p>`,
+          `### ${escapeMarkdown2(block.role)}
+
+${escapeMarkdown2(block.organization)}
+
+${escapeMarkdown2(block.date)}
+
+`
         );
         employmentOpen = true;
         continue;
       }
-      await write(semanticBlockHtml(block, defaultColor));
+      await write(semanticBlockOutput(block, defaultColor, format));
     }
     while (mediaIndex < page.media.length) {
-      await flushPendingParagraph();
-      const html = `<div class="pdf-semantic-visual">${page.media[mediaIndex]?.html}</div>`;
-      if (activeTable) pendingMedia.push(html);
-      else await write(html);
+      const item = page.media[mediaIndex];
+      if (item && !emittedMedia.has(item)) {
+        await flushPendingParagraph();
+        const html = markdown ? `${item.markdown}
+
+` : `<div class="pdf-semantic-visual">${item.html}</div>`;
+        if (activeTable) pendingMedia.push(html);
+        else await write(html);
+      }
       mediaIndex += 1;
     }
     for (const signature of marginSignatures(page)) seenFurniture.add(signature);
   };
   for await (const page of pages) {
-    const media = semanticMedia(page);
+    const media = await prepareSemanticMedia(page, imageOptions, onImage);
     const structured = (0, import_structure.structurePage)(withoutSemanticMediaSpans(page, media));
     buffer.push({ width: page.width, height: page.height, structured, media });
+    restoreObservedHyphens(buffer);
     stats.pagesProcessed += 1;
     stats.peakBufferedPages = Math.max(stats.peakBufferedPages, buffer.length);
     stats.peakBufferedLines = Math.max(
@@ -654,22 +948,82 @@ async function writeSemanticDocument(pages, write, lookaheadPages) {
     const ready = buffer.shift();
     if (ready) await emitPage(ready, buffer);
   }
-  if (headerOpen) await write("</header>");
+  if (headerOpen) await output("</header>");
   await closeTable();
   await closeEmployment();
   if (pendingParagraph && isFooterParagraph(pendingParagraph.block, pendingParagraph.height)) {
     await closeSections();
-    await write(
-      `<footer>${semanticBlockHtml(pendingParagraph.block, pendingParagraph.defaultColor)}</footer>`
+    await output(
+      `<footer>${semanticBlockHtml(pendingParagraph.block, pendingParagraph.defaultColor)}</footer>`,
+      `---
+
+${semanticBlockMarkdown(pendingParagraph.block, pendingParagraph.defaultColor)}`
     );
     pendingParagraph = void 0;
   } else {
     await flushPendingParagraph();
     await closeSections();
   }
-  await write("</article>");
+  await output("</article>");
   return stats;
 }
+function restoreObservedHyphens(buffer) {
+  const terms = new Set(
+    buffer.flatMap(
+      (page) => page.structured.lines.flatMap(
+        (line) => line.text.match(/[\p{L}\p{N}]+(?:[-‐‑][\p{L}\p{N}]+)+/gu) ?? []
+      )
+    )
+  );
+  for (const page of buffer) {
+    for (const block of page.structured.blocks) restoreBlockHyphens(block, terms);
+  }
+}
+function restoreBlockHyphens(block, terms) {
+  const restore = (value) => restoreTextHyphens(value, terms);
+  if (block.type === "insetGroup") {
+    for (const nested of block.blocks) restoreBlockHyphens(nested, terms);
+  } else if (block.type === "heading" || block.type === "paragraph" || block.type === "preformatted") {
+    block.text = restore(block.text);
+  } else if (block.type === "list") {
+    for (const item of block.items) item.text = restore(item.text);
+  } else if (block.type === "definitionList") {
+    for (const entry of block.entries) {
+      entry.term = restore(entry.term);
+      entry.description = restore(entry.description);
+    }
+  } else if (block.type === "cardList") {
+    for (const item of block.items) {
+      item.title = restore(item.title);
+      item.details = item.details.map(restore);
+    }
+  } else if (block.type === "sectionGroup") {
+    for (const item of block.items) {
+      item.label = restore(item.label);
+      item.content = item.content.map(restore);
+    }
+  } else if (block.type === "employment") {
+    block.role = restore(block.role);
+    block.organization = restore(block.organization);
+    block.date = restore(block.date);
+  }
+}
+function restoreTextHyphens(value, terms) {
+  let output = value;
+  for (const term of terms) {
+    const collapsed = term.replace(/[-‐‑]/gu, "");
+    if (collapsed === term || !output.includes(collapsed)) continue;
+    const pattern = new RegExp(
+      `(?<![\\p{L}\\p{N}])${escapeRegularExpression(collapsed)}(?![\\p{L}\\p{N}])`,
+      "gu"
+    );
+    output = output.replace(pattern, term);
+  }
+  return output;
+}
+function escapeRegularExpression(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function isContactBlock(block) {
   const text = block.text;
   const signals = [
@@ -753,6 +1107,20 @@ function tableRow(row, header) {
   const cell = header ? "th" : "td";
   return `<tr>${row.map((value) => `<${cell}>${escapeHtml3(value)}</${cell}>`).join("")}</tr>`;
 }
+function markdownTableStart(rows, header) {
+  const columns = rows[0]?.length ?? 0;
+  if (columns === 0) return "";
+  const heading = header ?? Array(columns).fill("");
+  return `${markdownTableRow(heading)}${markdownTableRow(Array(columns).fill("---"), false)}`;
+}
+function markdownTableRow(row, shouldEscape = true) {
+  const cells = row.map((value) => shouldEscape ? escapeMarkdownTableCell(value) : value);
+  return `| ${cells.join(" | ")} |
+`;
+}
+function escapeMarkdownTableCell(value) {
+  return escapeMarkdown2(value).replaceAll("|", "\\|").replace(/\s*\n\s*/g, "<br>");
+}
 function isFinancialSummary(block) {
   return block.entries.length > 0 && block.entries.every((entry) => isNumericValue(entry.description)) && block.entries.some((entry) => /\p{Sc}|%/u.test(entry.description));
 }
@@ -800,6 +1168,90 @@ function semanticBlockHtml(block, defaultColor = "#000000") {
   const tag = block.ordered ? "ol" : "ul";
   return `<${tag}>${block.items.map((item) => `<li>${semanticTextHtml(item.text, item.lines, defaultColor)}</li>`).join("")}</${tag}>`;
 }
+function semanticBlockOutput(block, defaultColor, format) {
+  return format === "markdown" ? semanticBlockMarkdown(block, defaultColor) : semanticBlockHtml(block, defaultColor);
+}
+function semanticBlockMarkdown(block, defaultColor = "#000000") {
+  if (block.type === "insetGroup") {
+    const content = block.blocks.map((item) => semanticBlockMarkdown(item, defaultColor)).join("");
+    return `${content.trimEnd().split("\n").map((line) => line ? `> ${line}` : ">").join("\n")}
+
+`;
+  }
+  if (block.type === "table") {
+    const rows = (0, import_structure.tableToRows)(block.table);
+    const header = tableHeader(rows);
+    return `${markdownTableStart(rows, header)}${(header ? rows.slice(1) : rows).map((row) => markdownTableRow(row)).join("")}
+`;
+  }
+  if (block.type === "heading") {
+    return `${"#".repeat(block.level)} ${semanticTextMarkdown(block.text, block.lines, defaultColor, false)}
+
+`;
+  }
+  if (block.type === "paragraph") {
+    return `${semanticTextMarkdown(block.text, block.lines, defaultColor)}
+
+`;
+  }
+  if (block.type === "preformatted") {
+    const fence = block.text.includes("```") ? "````" : "```";
+    return `${fence}
+${block.text}
+${fence}
+
+`;
+  }
+  if (block.type === "definitionList") {
+    return `${block.entries.map((entry) => `**${escapeMarkdown2(entry.term)}:** ${escapeMarkdown2(entry.description)}`).join("\n\n")}
+
+`;
+  }
+  if (block.type === "cardList") {
+    const rows = [
+      ["Item", "Quantity", "Amount"],
+      ...block.items.map((item) => {
+        const trailing = item.details.at(-1) ?? "";
+        const match = /^\s*[×x]\s*(\d+)\s+(.+)$/u.exec(trailing);
+        const detail = item.details.slice(0, -1).join(" ");
+        return [
+          `${item.title}${detail ? ` \u2014 ${detail}` : ""}`,
+          match?.[1] ?? "",
+          match?.[2] ?? trailing
+        ];
+      })
+    ];
+    return `## Items ordered
+
+${markdownTableStart(rows, rows[0])}${rows.slice(1).map((row) => markdownTableRow(row)).join("")}
+`;
+  }
+  if (block.type === "sectionGroup") {
+    return block.items.map(
+      (item) => `## ${escapeMarkdown2(titleCase(item.label))}
+
+${item.content.map(
+        (content, index) => index === 0 ? `**${escapeMarkdown2(content)}**` : escapeMarkdown2(content)
+      ).join("\n\n")}
+
+`
+    ).join("");
+  }
+  if (block.type === "employment") {
+    return `### ${escapeMarkdown2(block.role)}
+
+${escapeMarkdown2(block.organization)}
+
+${escapeMarkdown2(block.date)}
+
+`;
+  }
+  return `${block.items.map(
+    (item, index) => `${block.ordered ? `${index + 1}.` : "-"} ${semanticTextMarkdown(item.text, item.lines, defaultColor)}`
+  ).join("\n")}
+
+`;
+}
 function semanticBlockY(block) {
   const lines = block.type === "list" ? block.items.flatMap((item) => item.lines) : block.lines;
   return Math.max(...lines.map((line) => line.bounds.y + line.bounds.height));
@@ -832,6 +1284,9 @@ function titleCase(value) {
 function escapeHtml3(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+function escapeMarkdown2(value) {
+  return value.replace(/([\\`*_[\]<>])/g, "\\$1");
+}
 
 // src/index.ts
 var styles = `.pdf-document{margin:0 auto}.pdf-page{box-sizing:border-box;margin:1rem auto;background:#fff;color:#000}.pdf-page--visual,.pdf-page--positioned{position:relative;overflow:hidden}.pdf-page-content{position:absolute;transform-origin:0 0}.pdf-span{position:absolute;white-space:pre;transform-origin:left bottom;unicode-bidi:isolate}.pdf-span[data-direction=ttb]{writing-mode:vertical-rl}.pdf-page--semantic,.pdf-page--flow{max-width:60rem;padding:1rem}.pdf-page--semantic p,.pdf-page--flow p{white-space:pre-wrap;unicode-bidi:plaintext}.pdf-semantic-document h1,.pdf-page--semantic h1{font-size:1.7em}.pdf-semantic-document h2,.pdf-page--semantic h2{font-size:1.5em}.pdf-semantic-document h3,.pdf-page--semantic h3{font-size:1.35em}.pdf-semantic-document h4,.pdf-page--semantic h4{font-size:1.1em}.pdf-page table{border-collapse:collapse}.pdf-page td{padding:.15rem .4rem;vertical-align:top}`;
@@ -848,9 +1303,18 @@ async function writeHtmlDocument(pages, write, options = {}) {
     await write("</head><body>");
   }
   await write('<main class="pdf-document">');
-  if (resolveProfile(options) === "semantic") {
+  const profile = resolveProfile(options);
+  const imageOptions = resolveImageOptions(profile, options);
+  validateImageOptions(imageOptions, options);
+  if (profile === "semantic") {
     const lookahead = semanticLookahead(options.semanticLookaheadPages);
-    const stats = await writeSemanticDocument(pages, write, lookahead);
+    const stats = await writeSemanticDocument(
+      pages,
+      write,
+      lookahead,
+      imageOptions,
+      options.onImage
+    );
     options.onSemanticStats?.(stats);
   } else {
     for await (const page of pages) await writePage(page, write, options);
@@ -858,6 +1322,20 @@ async function writeHtmlDocument(pages, write, options = {}) {
   await write("</main>");
   if (includeDocument) await write("</body></html>");
 }
+async function writeMarkdownDocument(pages, write, options = {}) {
+  const imageOptions = options.imageOptions ?? "excluded";
+  validateImageOptions(imageOptions, options);
+  const lookahead = semanticLookahead(options.semanticLookaheadPages);
+  const stats = await writeSemanticDocument(
+    pages,
+    write,
+    lookahead,
+    imageOptions,
+    options.onImage,
+    "markdown"
+  );
+  options.onSemanticStats?.(stats);
+}
 function semanticLookahead(value) {
   const lookahead = value ?? 4;
   if (!Number.isSafeInteger(lookahead) || lookahead < 1 || lookahead > 16) {
@@ -866,7 +1344,9 @@ function semanticLookahead(value) {
   return lookahead;
 }
 async function writePage(page, write, options = {}) {
-  if (resolveProfile(options) === "semantic") await writeFlowPage(page, write);
+  const profile = resolveProfile(options);
+  validateImageOptions(resolveImageOptions(profile, options), options);
+  if (profile === "semantic") await writeFlowPage(page, write, options);
   else await writePositionedPage(page, write, options);
 }
 async function pageToHtml(page, options = {}) {
@@ -881,7 +1361,9 @@ async function pageToHtml(page, options = {}) {
   return output;
 }
 async function writePositionedPage(page, write, options) {
-  const visualSpans = page.visualSpans ?? page.spans;
+  const imageOptions = resolveImageOptions("visual", options);
+  const visualImages = await prepareVisualImages(page, imageOptions, options.onImage);
+  const visualSpans = coalesceVisualSpans(page.visualSpans ?? page.spans);
   const reflectedOverlay = usesReflectedVisualOverlay(page, visualSpans);
   const quarterTurn = page.rotate === 90 || page.rotate === 270;
   const displayWidth = quarterTurn ? page.height : page.width;
@@ -893,25 +1375,32 @@ async function writePositionedPage(page, write, options) {
   const type3Fonts = new Map(
     (page.fonts ?? []).filter((font) => font.format === "type3").map((font) => [font.id, font])
   );
+  const textClasses = options.includeStyles ?? true ? visualTextClasses(page.number, visualSpans, fontAliases) : void 0;
   if ((options.includeStyles ?? true) && page.fonts?.length) {
     await write(
       `<style>${page.fonts.map((font) => visualFontFace(font, fontAliases)).join("")}</style>`
     );
   }
+  if (textClasses?.css) await write(`<style>${textClasses.css}</style>`);
   await write(
     `<div class="pdf-page-content pdf-page-content--${page.rotate}" style="width:${number3(page.width)}pt;height:${number3(page.height)}pt${rotationTransform(page)}">`
   );
   await write(
     `<svg class="pdf-visual-text" xmlns="http://www.w3.org/2000/svg" width="${number3(page.width)}pt" height="${number3(page.height)}pt" viewBox="0 0 ${number3(page.width)} ${number3(page.height)}">`
   );
-  const clipDefinitions = imageClipDefinitions(page.images ?? [], page.number, page.height) + vectorPathClipDefinitions(
+  const clipDefinitions = imageClipDefinitions(
+    imageOptions === "excluded" ? [] : page.images ?? [],
+    page.number,
+    page.height
+  ) + vectorPathClipDefinitions(
     (page.paths ?? []).map((path, index) => ({ path, index })),
     page.number
   );
   if (clipDefinitions) await write(`<defs>${clipDefinitions}</defs>`);
   if (reflectedOverlay) {
     for (const [index, image] of (page.images ?? []).entries()) {
-      await write(visualImage(image, page.height, page.number, index));
+      const source = visualImages[index];
+      if (source) await write(visualImage(image, page.height, page.number, index, source));
     }
   }
   if (page.fills?.length || page.paths?.length) {
@@ -924,14 +1413,29 @@ async function writePositionedPage(page, write, options) {
   }
   if (!reflectedOverlay) {
     for (const [index, image] of (page.images ?? []).entries()) {
-      await write(visualImage(image, page.height, page.number, index));
+      const source = visualImages[index];
+      if (source) await write(visualImage(image, page.height, page.number, index, source));
     }
   }
-  for (const span of visualSpans) {
+  for (let spanIndex = 0; spanIndex < visualSpans.length; spanIndex += 1) {
+    const span = visualSpans[spanIndex];
+    if (!span) continue;
     if (!usesPositionedSpan(span)) {
       const type3 = span.fontAssetId ? type3Fonts.get(span.fontAssetId) : void 0;
+      const line = !type3 && textClasses ? visualTextLine(visualSpans, spanIndex, textClasses.names, page.height, fontAliases) : void 0;
+      if (line) {
+        await write(line.html);
+        spanIndex = line.endIndex;
+        continue;
+      }
       await write(
-        type3 ? visualType3Text(span, type3, page.height) : visualText(span, page.height, fontAliases, reflectedOverlay && page.rotate === 180)
+        type3 ? visualType3Text(span, type3, page.height) : visualText(
+          span,
+          page.height,
+          fontAliases,
+          reflectedOverlay && page.rotate === 180,
+          textClasses?.names
+        )
       );
     }
   }
@@ -941,23 +1445,131 @@ async function writePositionedPage(page, write, options) {
   }
   await write("</div></section>");
 }
+function coalesceVisualSpans(spans) {
+  const output = [];
+  for (const span of spans) {
+    const previous = output.at(-1);
+    if (!previous || !canCoalesceVisualSpans(previous, span)) {
+      output.push(span);
+      continue;
+    }
+    output[output.length - 1] = {
+      ...previous,
+      text: previous.text + span.text,
+      bounds: {
+        ...previous.bounds,
+        width: span.bounds.x + span.bounds.width - previous.bounds.x,
+        height: Math.max(previous.bounds.height, span.bounds.height)
+      }
+    };
+  }
+  return output;
+}
+function canCoalesceVisualSpans(left, right) {
+  if (usesPositionedSpan(left) || usesPositionedSpan(right)) return false;
+  if (left.direction !== "ltr" || right.direction !== "ltr") return false;
+  if (/guardian/i.test(left.fontFamily ?? "")) return false;
+  if (left.glyphCodes || right.glyphCodes) return false;
+  if (!sameVisualTextState(left, right)) return false;
+  const tolerance = Math.max(0.02, left.fontSize * 0.015);
+  if (Math.abs(left.bounds.y - right.bounds.y) > tolerance) return false;
+  const gap = right.bounds.x - (left.bounds.x + left.bounds.width);
+  return !right.hasLeadingSpace && gap >= -tolerance && gap <= tolerance;
+}
+function sameVisualTextState(left, right) {
+  return Math.abs(left.fontSize - right.fontSize) <= 1e-3 && left.fontName === right.fontName && left.fontFamily === right.fontFamily && left.fontAssetId === right.fontAssetId && left.color === right.color && left.fillOpacity === right.fillOpacity && left.strokeColor === right.strokeColor && left.strokeWidth === right.strokeWidth && left.strokeOpacity === right.strokeOpacity && left.renderingMode === right.renderingMode && sameTransform(left.transform, right.transform);
+}
+function sameTransform(left, right) {
+  if (!left || !right) return left === right;
+  return left.every((value, index) => Math.abs(value - (right[index] ?? 0)) <= 1e-6);
+}
+function visualTextClasses(pageNumber, spans, fontAliases) {
+  const names = /* @__PURE__ */ new Map();
+  let css = "";
+  for (const span of spans) {
+    if (usesPositionedSpan(span) || span.glyphCodes) {
+      continue;
+    }
+    const style = visualTextClassStyle(span, fontAliases);
+    if (!style || names.has(style)) continue;
+    const name = `boxpdf-p${number3(pageNumber)}-t${names.size + 1}`;
+    names.set(style, name);
+    css += `.${name}{${style}}`;
+  }
+  return { css, names };
+}
+function visualTextLine(spans, startIndex, styleClasses, pageHeight, fontAliases) {
+  const first = spans[startIndex];
+  if (!first || !canGroupVisualTextLine(first)) return void 0;
+  const style = visualTextClassStyle(first, fontAliases);
+  const className = styleClasses.get(style);
+  if (!className) return void 0;
+  let endIndex = startIndex;
+  while (endIndex + 1 < spans.length) {
+    const next = spans[endIndex + 1];
+    if (!next || !canGroupVisualTextLine(next) || Math.abs(next.bounds.y - first.bounds.y) > 1e-3 || visualTextClassStyle(next, fontAliases) !== style) {
+      break;
+    }
+    endIndex += 1;
+  }
+  if (endIndex === startIndex) return void 0;
+  const baseline = pageHeight - first.bounds.y;
+  const lineSpans = spans.slice(startIndex, endIndex + 1);
+  const content = lineSpans.map(
+    (span, index) => visualTextTspan(span, index > 0 ? textSpanGap(lineSpans[index - 1], span) : void 0)
+  ).join("");
+  return {
+    html: `<text class="${className}" x="${number3(first.bounds.x)}" y="${number3(baseline)}">${content}</text>`,
+    endIndex
+  };
+}
+function visualTextTspan(span, dx) {
+  const extent = span.bounds.width;
+  const offset = dx === void 0 || number3(dx) === "0" ? "" : ` dx="${number3(dx)}"`;
+  const length = extent > 0 ? ` textLength="${number3(extent)}" lengthAdjust="${usesSpacingAdjustment(span) ? "spacing" : "spacingAndGlyphs"}"` : "";
+  return `<tspan${offset}${length}>${escapeHtml4(span.text)}</tspan>`;
+}
+function textSpanGap(previous, current) {
+  if (!previous) return 0;
+  const gap = current.bounds.x - (previous.bounds.x + previous.bounds.width);
+  const adjustment = current.textAdjustmentBefore;
+  return adjustment !== void 0 && Math.abs(adjustment - gap) <= 1e-3 ? adjustment : gap;
+}
+function canGroupVisualTextLine(span) {
+  return !usesPositionedSpan(span) && !span.glyphCodes && span.direction === "ltr" && !isHebrewPaintOrder(span) && !hasNonIdentityTransform(span.transform) && span.renderingMode !== 3 && span.renderingMode !== 7 && (span.fontAssetId !== void 0 || !isAdobeCjkFont(span.fontFamily));
+}
 function usesReflectedVisualOverlay(page, spans) {
   return Boolean(page.images?.length) && Boolean(page.paths?.length || page.fills?.length) && spans.length > 0 && spans.every(
     (span) => span.transform !== void 0 && Math.abs(span.transform[0] + 1) < 1e-6 && Math.abs(span.transform[1]) < 1e-6 && Math.abs(span.transform[2]) < 1e-6 && Math.abs(span.transform[3] - 1) < 1e-6
   );
 }
-function visualImage(image, pageHeight, pageNumber, imageIndex) {
+function visualImage(image, pageHeight, pageNumber, imageIndex, source) {
   const [a, b, c, d, e, f] = image.transform;
   const transform = [a, -b, -c, d, c + e, pageHeight - d - f].map(number3).join(" ");
   const opacity = isUnitInterval2(image.opacity) ? ` opacity="${number3(image.opacity)}"` : "";
-  const mime = image.format === "jpeg" ? "image/jpeg" : "image/bmp";
-  const data = image.format === "jpeg" ? image.data : rgbBmp2(image);
-  let output = `<image width="1" height="1" preserveAspectRatio="none" transform="matrix(${transform})" href="data:${mime};base64,${base64(data)}"${opacity}/>`;
+  let output = `<image width="1" height="1" preserveAspectRatio="none" transform="matrix(${transform})" href="${source}"${opacity}/>`;
   for (let index = (image.clips?.length ?? 0) - 1; index >= 0; index -= 1) {
     output = `<g clip-path="url(#${imageClipId(pageNumber, imageIndex, index)})">${output}</g>`;
   }
   return output;
 }
+async function prepareVisualImages(page, imageOptions, onImage) {
+  if (imageOptions === "excluded") return [];
+  const sources = [];
+  for (const [index, image] of (page.images ?? []).entries()) {
+    const mimeType = image.format === "jpeg" ? "image/jpeg" : "image/bmp";
+    const data = image.format === "jpeg" ? image.data : rgbBmp2(image);
+    if (imageOptions === "embedded") {
+      sources.push(`data:${mimeType};base64,${base64(data)}`);
+      continue;
+    }
+    const extension = image.format === "jpeg" ? "jpg" : "bmp";
+    const name = `page-${page.number}-image-${index + 1}.${extension}`;
+    await onImage?.({ name, mimeType, data });
+    sources.push(name);
+  }
+  return sources;
+}
 function imageClipDefinitions(images, pageNumber, pageHeight) {
   return images.flatMap(
     (image, imageIndex) => (image.clips ?? []).map((clip, clipIndex) => {
@@ -1024,8 +1636,9 @@ function positionedSpan(span, fontAliases) {
   ].join(";");
   return `<span class="pdf-span"${direction} style="${style}">${escapeHtml4(span.text)}</span>`;
 }
-async function writeFlowPage(page, write) {
-  const media = semanticMedia(page);
+async function writeFlowPage(page, write, options) {
+  const imageOptions = resolveImageOptions("semantic", options);
+  const media = await prepareSemanticMedia(page, imageOptions, options.onImage);
   const structured = (0, import_structure2.structurePage)(withoutSemanticMediaSpans(page, media));
   const defaultColor = dominantTextColor(structured.lines);
   let mediaIndex = 0;
@@ -1037,18 +1650,22 @@ async function writeFlowPage(page, write) {
     structured.lines
   );
   const captionedMedia = new Set(captions.values());
+  const emittedMedia = /* @__PURE__ */ new Set();
   await write(
     `<section class="pdf-page pdf-page--semantic pdf-page--flow" data-page="${page.number}">`
   );
   for (const block of structured.blocks) {
     const blockY = semanticBlockY2(block);
     let emittedAsCaption = false;
+    while (media[mediaIndex] && emittedMedia.has(media[mediaIndex]))
+      mediaIndex += 1;
     while ((media[mediaIndex]?.bounds.y ?? -Infinity) >= blockY) {
       const item = media[mediaIndex];
       if (item && captions.get(block) === item && block.type === "paragraph") {
         await write(
           `<figure class="pdf-semantic-figure">${item.html}<figcaption>${semanticTextHtml(block.text, block.lines, defaultColor)}</figcaption></figure>`
         );
+        emittedMedia.add(item);
         mediaIndex += 1;
         emittedAsCaption = true;
         break;
@@ -1057,6 +1674,14 @@ async function writeFlowPage(page, write) {
       await write(`<div class="pdf-semantic-visual">${item?.html}</div>`);
       mediaIndex += 1;
     }
+    const associatedMedia = captions.get(block);
+    if (!emittedAsCaption && associatedMedia && block.type === "paragraph") {
+      await write(
+        `<figure class="pdf-semantic-figure">${associatedMedia.html}<figcaption>${semanticTextHtml(block.text, block.lines, defaultColor)}</figcaption></figure>`
+      );
+      emittedMedia.add(associatedMedia);
+      emittedAsCaption = true;
+    }
     if (emittedAsCaption) continue;
     if (block.type === "table") await write((0, import_structure2.tableToHtml)(block.table));
     else if (block.type === "heading") {
@@ -1111,7 +1736,10 @@ async function writeFlowPage(page, write) {
     }
   }
   while (mediaIndex < media.length) {
-    await write(`<div class="pdf-semantic-visual">${media[mediaIndex]?.html}</div>`);
+    const item = media[mediaIndex];
+    if (item && !emittedMedia.has(item)) {
+      await write(`<div class="pdf-semantic-visual">${item.html}</div>`);
+    }
     mediaIndex += 1;
   }
   await write("</section>");
@@ -1147,10 +1775,37 @@ function semanticBlockY2(block) {
   const lines = block.type === "list" ? block.items.flatMap((item) => item.lines) : block.lines;
   return Math.max(...lines.map((line) => line.bounds.y + line.bounds.height));
 }
-function visualText(span, pageHeight, fontAliases, counterRotateReflectedText = false) {
+function visualText(span, pageHeight, fontAliases, counterRotateReflectedText = false, styleClasses) {
   if (span.renderingMode === 3 || span.renderingMode === 7) return "";
   if (!span.fontAssetId && isAdobeCjkFont(span.fontFamily)) return "";
   const direction = directionAttribute([span]);
+  const style = visualTextStyle(span, fontAliases);
+  const styleClass = styleClasses?.get(visualTextClassStyle(span, fontAliases));
+  const presentation = styleClass ? ` class="${styleClass}"` : style ? ` style="${style}"` : "";
+  const fontSize = styleClass ? "" : ` font-size="${number3(span.fontSize)}"`;
+  const textExtent = span.direction === "ttb" ? span.bounds.height : span.bounds.width;
+  const textLength = textExtent > 0 && !isHebrewPaintOrder(span) ? ` textLength="${number3(textExtent)}" lengthAdjust="${span.direction === "ttb" || usesSpacingAdjustment(span) ? "spacing" : "spacingAndGlyphs"}"` : "";
+  const transform = counterRotateReflectedText && span.transform ? [
+    span.transform[0],
+    span.transform[1],
+    span.transform[2],
+    -span.transform[3]
+  ] : span.transform;
+  const transformed = hasNonIdentityTransform(transform);
+  const rtlOffset = span.direction === "rtl" ? span.bounds.width : 0;
+  const basisX = transform?.[0] ?? 1;
+  const basisY = transform?.[1] ?? 0;
+  const anchorX = span.bounds.x + basisX * rtlOffset;
+  const anchorY = pageHeight - span.bounds.y + basisY * rtlOffset;
+  const position = transformed ? ` x="0" y="0" transform="matrix(${transform?.map(number3).join(" ")} ${number3(anchorX)} ${number3(anchorY)})"` : ` x="${number3(anchorX)}" y="${number3(anchorY)}"`;
+  return `<text${direction}${position}${fontSize}${textLength}${presentation}>${escapeHtml4(span.text)}</text>`;
+}
+function visualTextClassStyle(span, fontAliases) {
+  const style = visualTextStyle(span, fontAliases);
+  const fontSize = `font-size:${number3(span.fontSize)}px`;
+  return style ? `${style};${fontSize}` : fontSize;
+}
+function visualTextStyle(span, fontAliases) {
   const font = visualFontStyles(
     span.fontFamily,
     span.fontAssetId ? fontAliases.get(span.fontAssetId) : void 0
@@ -1160,7 +1815,7 @@ function visualText(span, pageHeight, fontAliases, counterRotateReflectedText =
   const strokeOnly = span.renderingMode === 1 || span.renderingMode === 5;
   const fillOpacity = isUnitInterval2(span.fillOpacity) ? `fill-opacity:${number3(span.fillOpacity)}` : "";
   const strokeOpacity = isUnitInterval2(span.strokeOpacity) ? `stroke-opacity:${number3(span.strokeOpacity)}` : "";
-  const style = [
+  return [
     isHebrewPaintOrder(span) ? "unicode-bidi:bidi-override;direction:ltr" : "",
     span.direction === "ttb" ? "writing-mode:vertical-rl" : "",
     strokeOnly ? "fill:none" : isCssHexColor2(span.color) ? `fill:${span.color}` : "",
@@ -1170,22 +1825,6 @@ function visualText(span, pageHeight, fontAliases, counterRotateReflectedText =
     strokeOpacity,
     font
   ].filter(Boolean).join(";");
-  const textExtent = span.direction === "ttb" ? span.bounds.height : span.bounds.width;
-  const textLength = textExtent > 0 && !isHebrewPaintOrder(span) ? ` textLength="${number3(textExtent)}" lengthAdjust="${span.direction === "ttb" || usesSpacingAdjustment(span) ? "spacing" : "spacingAndGlyphs"}"` : "";
-  const transform = counterRotateReflectedText && span.transform ? [
-    span.transform[0],
-    span.transform[1],
-    span.transform[2],
-    -span.transform[3]
-  ] : span.transform;
-  const transformed = hasNonIdentityTransform(transform);
-  const rtlOffset = span.direction === "rtl" ? span.bounds.width : 0;
-  const basisX = transform?.[0] ?? 1;
-  const basisY = transform?.[1] ?? 0;
-  const anchorX = span.bounds.x + basisX * rtlOffset;
-  const anchorY = pageHeight - span.bounds.y + basisY * rtlOffset;
-  const position = transformed ? ` x="0" y="0" transform="matrix(${transform?.map(number3).join(" ")} ${number3(anchorX)} ${number3(anchorY)})"` : ` x="${number3(anchorX)}" y="${number3(anchorY)}"`;
-  return `<text${direction}${position} font-size="${number3(span.fontSize)}"${textLength}${style ? ` style="${style}"` : ""}>${escapeHtml4(span.text)}</text>`;
 }
 function isAdobeCjkFont(fontFamily) {
   return /^Adobe(?:Heiti|Song|Kaiti|Ming|Gothic|Mincho)Std-/i.test(fontFamily ?? "");
@@ -1280,10 +1919,19 @@ function resolveProfile(options) {
   }
   return options.profile ?? legacyProfile;
 }
+function resolveImageOptions(profile, options) {
+  return options.imageOptions ?? (profile === "semantic" ? "excluded" : "embedded");
+}
+function validateImageOptions(imageOptions, options) {
+  if (imageOptions === "references" && !options.onImage) {
+    throw new Error('imageOptions "references" requires an onImage callback');
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   pageToHtml,
   writeHtmlDocument,
+  writeMarkdownDocument,
   writePage
 });
 //# sourceMappingURL=index.cjs.map