@link-assistant/web-capture 1.4.2 → 1.7.1

package/src/extract-images.js

@@ -0,0 +1,120 @@
+import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+const BASE64_IMAGE_REGEX =
+  /!\[([^\]]*)\]\(data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,([^)]+)\)/gi;
+
+/**
+ * @param {string} markdown - Markdown content with data URI images
+ * @param {string} outputDir - Directory where the markdown file is being written
+ * @param {Object} [options]
+ * @param {string} [options.imagesDir='images'] - Subdirectory name for images
+ * @returns {{markdown: string, extracted: number}}
+ */
+export function extractAndSaveImages(markdown, outputDir, options = {}) {
+  const { imagesDir = 'images' } = options;
+  const imagesPath = path.resolve(outputDir, imagesDir);
+
+  const images = [];
+
+  const updatedMarkdown = markdown.replace(
+    BASE64_IMAGE_REGEX,
+    (match, altText, mimeExt, base64Data) => {
+      const ext =
+        mimeExt === 'jpeg' ? 'jpg' : mimeExt === 'svg+xml' ? 'svg' : mimeExt;
+
+      let buffer;
+      try {
+        buffer = Buffer.from(base64Data, 'base64');
+      } catch {
+        return match;
+      }
+
+      const hash = createHash('sha256')
+        .update(buffer)
+        .digest('hex')
+        .slice(0, 8);
+      const filename = `image-${hash}.${ext}`;
+      const relativePath = `${imagesDir}/${filename}`;
+
+      images.push({ filename, buffer });
+
+      return `![${altText}](${relativePath})`;
+    }
+  );
+
+  if (images.length > 0) {
+    fs.mkdirSync(imagesPath, { recursive: true });
+    for (const img of images) {
+      fs.writeFileSync(path.join(imagesPath, img.filename), img.buffer);
+    }
+  }
+
+  return { markdown: updatedMarkdown, extracted: images.length };
+}
+
+/**
+ * Extract base64 images from markdown into memory buffers and rewrite paths.
+ * Does NOT write to disk — intended for streaming into archives.
+ *
+ * @param {string} markdown - Markdown content with data URI images
+ * @param {string} [imagesDir='images'] - Directory prefix for image paths
+ * @returns {{markdown: string, images: Array<{filename: string, buffer: Buffer}>}}
+ */
+export function extractBase64ToBuffers(markdown, imagesDir = 'images') {
+  const images = [];
+  const updatedMarkdown = markdown.replace(
+    BASE64_IMAGE_REGEX,
+    (match, altText, mimeExt, base64Data) => {
+      const ext =
+        mimeExt === 'jpeg' ? 'jpg' : mimeExt === 'svg+xml' ? 'svg' : mimeExt;
+
+      let buffer;
+      try {
+        buffer = Buffer.from(base64Data, 'base64');
+      } catch {
+        return match;
+      }
+
+      const hash = createHash('sha256')
+        .update(buffer)
+        .digest('hex')
+        .slice(0, 8);
+      const filename = `image-${hash}.${ext}`;
+      const relativePath = `${imagesDir}/${filename}`;
+
+      images.push({ filename, buffer });
+      return `![${altText}](${relativePath})`;
+    }
+  );
+  return { markdown: updatedMarkdown, images };
+}
+
+/**
+ * Strip base64 data URI images from markdown, leaving only the alt text
+ * as a placeholder. Used when keepOriginalLinks is enabled — base64 images
+ * have no original URL to restore, so we remove the heavy data URI.
+ *
+ * @param {string} markdown - Markdown content with data URI images
+ * @returns {{markdown: string, stripped: number}}
+ */
+export function stripBase64Images(markdown) {
+  let stripped = 0;
+  const updatedMarkdown = markdown.replace(
+    BASE64_IMAGE_REGEX,
+    (_match, altText) => {
+      stripped++;
+      return altText ? `*[image: ${altText}]*` : '';
+    }
+  );
+  return { markdown: updatedMarkdown, stripped };
+}
+
+/**
+ * @param {string} markdown - Markdown content
+ * @returns {boolean}
+ */
+export function hasBase64Images(markdown) {
+  return BASE64_IMAGE_REGEX.test(markdown);
+}

package/src/gdocs.js

@@ -7,7 +7,7 @@
 import fetch from 'node-fetch';
 import he from 'he';
 import archiver from 'archiver';
-import { convertHtmlToMarkdown } from './lib.js';
+import { convertHtmlToMarkdown, prettyPrintHtml } from './lib.js';
 
 const GDOCS_URL_PATTERN = /docs\.google\.com\/document\/d\/([a-zA-Z0-9_-]+)/;
 
@@ -194,8 +194,8 @@ export function extractBase64Images(html) {
  *
  * Fetches the document as HTML, extracts embedded base64 images,
  * and bundles everything into a ZIP archive containing:
- * - article.md (Markdown version)
- * - article.html (HTML version with local image paths)
+ * - document.md (Markdown version)
+ * - document.html (HTML version with local image paths)
  * - images/ (extracted images)
  *
  * @param {string} url - Google Docs URL
@@ -213,7 +213,7 @@ export async function fetchGoogleDocAsArchive(url, options = {}) {
   const { html: localHtml, images } = extractBase64Images(result.content);
 
   // Convert the localized HTML to Markdown
-  const markdown = convertHtmlToMarkdown(localHtml, result.exportUrl);
+  const markdown = convertHtmlToMarkdown(localHtml);
 
   return {
     documentId: result.documentId,
@@ -286,8 +286,10 @@ async function sendGDocsArchive(res, url, apiToken) {
 
   const archive = archiver('zip', { zlib: { level: 9 } });
   archive.pipe(res);
-  archive.append(archiveResult.markdown, { name: 'article.md' });
-  archive.append(archiveResult.html, { name: 'article.html' });
+  archive.append(archiveResult.markdown, { name: 'document.md' });
+  archive.append(prettyPrintHtml(archiveResult.html), {
+    name: 'document.html',
+  });
   for (const img of archiveResult.images) {
     archive.append(img.data, { name: `images/${img.filename}` });
   }

package/src/lib.js

@@ -167,7 +167,8 @@ export function convertHtmlToMarkdown(html, baseUrl) {
   });
   turndown.use(turndownPluginGfm.gfm);
   // Decode HTML entities to unicode after markdown conversion
-  return he.decode(turndown.turndown($.html()));
+  // Preserve non-breaking spaces as   entities for clear marking
+  return he.decode(turndown.turndown($.html())).replace(/\u00A0/g, ' ');
 }
 
 // Convert relative URLs to absolute URLs in HTML content
@@ -502,7 +503,8 @@ export function convertHtmlToMarkdownEnhanced(html, baseUrl, options = {}) {
   turndown.use(turndownPluginGfm.gfm);
 
   // Decode HTML entities to unicode after markdown conversion
-  let markdown = he.decode(turndown.turndown($.html()));
+  // Normalize non-breaking spaces to regular spaces in Markdown text
+  let markdown = he.decode(turndown.turndown($.html())).replace(/\u00A0/g, ' ');
 
   // Apply post-processing
   if (postProcess) {
@@ -553,3 +555,56 @@ export function ensureUtf8(html) {
   }
   return html;
 }
+
+const VOID_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+export function prettyPrintHtml(html) {
+  const tagRe = /(<\/?[a-zA-Z][^>]*?>)/g;
+  const parts = html.split(tagRe).filter(Boolean);
+  let indent = 0;
+  const indentStr = '  ';
+  const lines = [];
+
+  for (const part of parts) {
+    const isTag = part.startsWith('<');
+    if (!isTag) {
+      const text = part.trim();
+      if (text) {
+        lines.push(indentStr.repeat(indent) + text);
+      }
+      continue;
+    }
+    const isClosing = part.startsWith('</');
+    const tagMatch = part.match(/^<\/?([a-zA-Z][a-zA-Z0-9]*)/);
+    const tagName = tagMatch ? tagMatch[1].toLowerCase() : '';
+    const isVoid = VOID_TAGS.has(tagName);
+    const isSelfClosing = part.endsWith('/>');
+
+    if (isClosing) {
+      indent = Math.max(0, indent - 1);
+      lines.push(indentStr.repeat(indent) + part);
+    } else if (isVoid || isSelfClosing) {
+      lines.push(indentStr.repeat(indent) + part);
+    } else {
+      lines.push(indentStr.repeat(indent) + part);
+      indent++;
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/markdown.js

@@ -1,14 +1,19 @@
 import { fetchHtml, convertHtmlToMarkdown } from './lib.js';
+import { stripBase64Images } from './extract-images.js';
 
 export async function markdownHandler(req, res) {
   const url = req.query.url;
   if (!url) {
     return res.status(400).send('Missing `url` parameter');
   }
+  const embedImages = req.query.embedImages === 'true';
   try {
     const html = await fetchHtml(url);
-    // Pass baseUrl to convertHtmlToMarkdown so all URLs are absolute
-    const markdown = convertHtmlToMarkdown(html, url);
+    let markdown = convertHtmlToMarkdown(html, url);
+    if (!embedImages) {
+      const strip = stripBase64Images(markdown);
+      markdown = strip.markdown;
+    }
     res.type('text/markdown').send(markdown);
   } catch (err) {
     console.error(err);

package/src/postprocess.js

@@ -71,10 +71,8 @@ export function postProcessMarkdown(markdown, options = {}) {
 export function applyUnicodeNormalization(text) {
   let result = text;
 
-  // Replace non-breaking spaces (U+00A0) with regular spaces.
-  // GitHub's math renderer doesn't recognize \xa0 as a word boundary
-  // for inline math $...$ delimiters.
-  result = result.replace(/\u00A0/g, ' ');
+  // Preserve non-breaking spaces as   entities for clear marking
+  result = result.replace(/\u00A0/g, ' ');
 
   // Normalize curly quotes to straight quotes
   result = result.replace(/[\u2018\u2019]/g, "'");

package/tests/unit/batch.test.js

@@ -22,7 +22,7 @@ describe('batch module', () => {
     },
     defaults: {
       archivePath: 'archive',
-      markdownFile: 'article.md',
+      markdownFile: 'document.md',
       imagesDir: 'images',
       hasLocalImages: true,
     },
@@ -37,7 +37,7 @@ describe('batch module', () => {
 
     it('merges defaults into article config', () => {
       const article = getArticle(sampleConfig, '0.0.0');
-      expect(article.markdownFile).toBe('article.md');
+      expect(article.markdownFile).toBe('document.md');
       expect(article.hasLocalImages).toBe(true);
     });
 
@@ -59,7 +59,7 @@ describe('batch module', () => {
     it('returns all articles with defaults merged', () => {
       const articles = getAllArticles(sampleConfig);
       expect(articles).toHaveLength(2);
-      expect(articles[0].markdownFile).toBe('article.md');
+      expect(articles[0].markdownFile).toBe('document.md');
       expect(articles[1].language).toBe('ru');
     });
   });
@@ -78,7 +78,7 @@ describe('batch module', () => {
     it('sets default archive paths', () => {
       const config = createConfigFromUrls(['https://habr.com/article/123']);
       expect(config.articles['1'].archivePath).toContain('habr-com');
-      expect(config.articles['1'].markdownFile).toBe('article.md');
+      expect(config.articles['1'].markdownFile).toBe('document.md');
     });
   });
 

package/tests/unit/extract-images.test.js

@@ -0,0 +1,233 @@
+import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  extractAndSaveImages,
+  extractBase64ToBuffers,
+  stripBase64Images,
+  hasBase64Images,
+} from '../../src/extract-images.js';
+
+describe('extract-images module', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'extract-images-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // 1x1 red PNG pixel as base64
+  const TINY_PNG =
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+  // 1x1 white JPEG as base64
+  const TINY_JPEG =
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAP///wAAAf/bAEMA/9sAQwD/2wBDAf///wAAAf/bAEMA/9sAQwD/2Q==';
+
+  function contentHash(base64Data) {
+    const buf = Buffer.from(base64Data, 'base64');
+    return createHash('sha256').update(buf).digest('hex').slice(0, 8);
+  }
+
+  const PNG_HASH = contentHash(TINY_PNG);
+  const JPEG_HASH = contentHash(TINY_JPEG);
+
+  describe('extractAndSaveImages', () => {
+    it('extracts a single PNG image from markdown', () => {
+      const md = `# Hello\n\n![test](data:image/png;base64,${TINY_PNG})\n\nEnd.`;
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.extracted).toBe(1);
+      expect(result.markdown).toContain(
+        `![test](images/image-${PNG_HASH}.png)`
+      );
+      expect(result.markdown).not.toContain('data:image');
+
+      const imgPath = path.join(tmpDir, 'images', `image-${PNG_HASH}.png`);
+      expect(fs.existsSync(imgPath)).toBe(true);
+      const buf = fs.readFileSync(imgPath);
+      expect(buf.length).toBeGreaterThan(0);
+      // Verify PNG magic bytes
+      expect(buf[0]).toBe(0x89);
+      expect(buf[1]).toBe(0x50); // P
+    });
+
+    it('extracts multiple images with content-hash filenames', () => {
+      const md = [
+        `![a](data:image/png;base64,${TINY_PNG})`,
+        `![b](data:image/jpeg;base64,${TINY_JPEG})`,
+      ].join('\n');
+
+      const result = extractAndSaveImages(md, tmpDir);
+      expect(result.extracted).toBe(2);
+      expect(result.markdown).toContain(`images/image-${PNG_HASH}.png`);
+      expect(result.markdown).toContain(`images/image-${JPEG_HASH}.jpg`);
+    });
+
+    it('produces stable filenames for duplicate images', () => {
+      const md = [
+        `![a](data:image/png;base64,${TINY_PNG})`,
+        `![b](data:image/png;base64,${TINY_PNG})`,
+      ].join('\n');
+
+      const result = extractAndSaveImages(md, tmpDir);
+      expect(result.extracted).toBe(2);
+      // Both should produce the same hash-based filename
+      const matches = result.markdown.match(
+        new RegExp(`image-${PNG_HASH}\\.png`, 'g')
+      );
+      expect(matches).toHaveLength(2);
+    });
+
+    it('handles JPEG mime type correctly', () => {
+      const md = `![photo](data:image/jpeg;base64,${TINY_JPEG})`;
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.extracted).toBe(1);
+      expect(result.markdown).toContain(`images/image-${JPEG_HASH}.jpg`);
+    });
+
+    it('uses custom imagesDir', () => {
+      const md = `![img](data:image/png;base64,${TINY_PNG})`;
+      const result = extractAndSaveImages(md, tmpDir, {
+        imagesDir: 'my-images',
+      });
+
+      expect(result.extracted).toBe(1);
+      expect(result.markdown).toContain(`my-images/image-${PNG_HASH}.png`);
+      expect(
+        fs.existsSync(path.join(tmpDir, 'my-images', `image-${PNG_HASH}.png`))
+      ).toBe(true);
+    });
+
+    it('returns markdown unchanged when no base64 images', () => {
+      const md = '# No images\n\nJust text.';
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.extracted).toBe(0);
+      expect(result.markdown).toBe(md);
+      expect(fs.existsSync(path.join(tmpDir, 'images'))).toBe(false);
+    });
+
+    it('preserves non-base64 image references', () => {
+      const md =
+        '![remote](https://example.com/img.png)\n![local](images/existing.png)';
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.extracted).toBe(0);
+      expect(result.markdown).toBe(md);
+    });
+
+    it('preserves alt text during extraction', () => {
+      const md = `![A descriptive alt text](data:image/png;base64,${TINY_PNG})`;
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.markdown).toContain(
+        `![A descriptive alt text](images/image-${PNG_HASH}.png)`
+      );
+    });
+
+    it('handles SVG data URIs', () => {
+      const svgContent =
+        '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><rect fill="red" width="1" height="1"/></svg>';
+      const svgBase64 = Buffer.from(svgContent).toString('base64');
+      const svgHash = contentHash(svgBase64);
+      const md = `![icon](data:image/svg+xml;base64,${svgBase64})`;
+      const result = extractAndSaveImages(md, tmpDir);
+
+      expect(result.extracted).toBe(1);
+      expect(result.markdown).toContain(`images/image-${svgHash}.svg`);
+
+      const imgPath = path.join(tmpDir, 'images', `image-${svgHash}.svg`);
+      expect(fs.existsSync(imgPath)).toBe(true);
+      const content = fs.readFileSync(imgPath, 'utf-8');
+      expect(content).toContain('<svg');
+    });
+  });
+
+  describe('extractBase64ToBuffers', () => {
+    it('extracts base64 images to in-memory buffers', () => {
+      const md = `# Hello\n\n![test](data:image/png;base64,${TINY_PNG})\n\nEnd.`;
+      const result = extractBase64ToBuffers(md);
+
+      expect(result.images).toHaveLength(1);
+      expect(result.images[0].filename).toMatch(/^image-[0-9a-f]{8}\.png$/);
+      expect(result.images[0].buffer.length).toBeGreaterThan(0);
+      expect(result.markdown).toContain(`images/${result.images[0].filename}`);
+      expect(result.markdown).not.toContain('data:image');
+    });
+
+    it('uses custom imagesDir prefix', () => {
+      const md = `![img](data:image/png;base64,${TINY_PNG})`;
+      const result = extractBase64ToBuffers(md, 'assets');
+
+      expect(result.markdown).toContain('assets/image-');
+    });
+
+    it('does not write files to disk', () => {
+      const md = `![img](data:image/png;base64,${TINY_PNG})`;
+      extractBase64ToBuffers(md);
+      expect(fs.existsSync(path.join(tmpDir, 'images'))).toBe(false);
+    });
+  });
+
+  describe('stripBase64Images', () => {
+    it('strips base64 images and leaves alt text placeholder', () => {
+      const md = `![my image](data:image/png;base64,${TINY_PNG})`;
+      const result = stripBase64Images(md);
+
+      expect(result.stripped).toBe(1);
+      expect(result.markdown).toBe('*[image: my image]*');
+      expect(result.markdown).not.toContain('data:image');
+    });
+
+    it('strips base64 images with empty alt text', () => {
+      const md = `![](data:image/png;base64,${TINY_PNG})`;
+      const result = stripBase64Images(md);
+
+      expect(result.stripped).toBe(1);
+      expect(result.markdown).toBe('');
+    });
+
+    it('preserves remote image URLs', () => {
+      const md = '![remote](https://example.com/img.png)';
+      const result = stripBase64Images(md);
+
+      expect(result.stripped).toBe(0);
+      expect(result.markdown).toBe(md);
+    });
+
+    it('strips multiple base64 images', () => {
+      const md = [
+        `![a](data:image/png;base64,${TINY_PNG})`,
+        `![b](data:image/jpeg;base64,${TINY_JPEG})`,
+        '![c](https://example.com/img.png)',
+      ].join('\n');
+      const result = stripBase64Images(md);
+
+      expect(result.stripped).toBe(2);
+      expect(result.markdown).toContain('*[image: a]*');
+      expect(result.markdown).toContain('*[image: b]*');
+      expect(result.markdown).toContain('https://example.com/img.png');
+    });
+  });
+
+  describe('hasBase64Images', () => {
+    it('returns true when markdown has base64 images', () => {
+      expect(hasBase64Images(`![x](data:image/png;base64,${TINY_PNG})`)).toBe(
+        true
+      );
+    });
+
+    it('returns false when no base64 images', () => {
+      expect(hasBase64Images('![x](https://example.com/img.png)')).toBe(false);
+    });
+
+    it('returns false for empty string', () => {
+      expect(hasBase64Images('')).toBe(false);
+    });
+  });
+});

package/tests/unit/gdocs.test.js

@@ -6,6 +6,14 @@ import {
   extractBase64Images,
   GDOCS_EXPORT_FORMATS,
 } from '../../src/gdocs.js';
+import {
+  extractAndSaveImages,
+  extractBase64ToBuffers,
+  stripBase64Images,
+} from '../../src/extract-images.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 
 jest.setTimeout(30000);
 
@@ -200,4 +208,71 @@ describe('gdocs', () => {
       expect(updated).toContain('images/image-01.gif');
     });
   });
+
+  describe('image extraction pipeline (issue #53)', () => {
+    const TINY_PNG =
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gdocs-issue53-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('extractBase64Images from HTML produces images with data buffers', () => {
+      const html = `<html><body><img src="data:image/png;base64,${TINY_PNG}" alt="photo"><p>Hello</p></body></html>`;
+      const { html: localHtml, images } = extractBase64Images(html);
+
+      expect(images).toHaveLength(1);
+      expect(images[0].filename).toBe('image-01.png');
+      expect(images[0].data.length).toBeGreaterThan(0);
+      // Verify PNG magic bytes in extracted data
+      expect(images[0].data[0]).toBe(0x89);
+      expect(images[0].data[1]).toBe(0x50); // P
+      expect(localHtml).toContain('images/image-01.png');
+      expect(localHtml).not.toContain('data:image');
+    });
+
+    it('default markdown mode extracts base64 images to disk (not strip)', () => {
+      const markdown = `# Hello\n\n![photo](data:image/png;base64,${TINY_PNG})\n\nEnd.`;
+      const result = extractAndSaveImages(markdown, tmpDir);
+
+      expect(result.extracted).toBe(1);
+      expect(result.markdown).not.toContain('data:image');
+      expect(result.markdown).toContain('images/image-');
+      expect(result.markdown).toContain('.png');
+
+      const imagesDir = path.join(tmpDir, 'images');
+      expect(fs.existsSync(imagesDir)).toBe(true);
+      const files = fs.readdirSync(imagesDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/^image-.*\.png$/);
+
+      const imgBuf = fs.readFileSync(path.join(imagesDir, files[0]));
+      expect(imgBuf[0]).toBe(0x89); // PNG magic
+    });
+
+    it('keepOriginalLinks strips base64 images', () => {
+      const markdown = `![photo](data:image/png;base64,${TINY_PNG})`;
+      const result = stripBase64Images(markdown);
+
+      expect(result.stripped).toBe(1);
+      expect(result.markdown).toBe('*[image: photo]*');
+      expect(result.markdown).not.toContain('data:image');
+    });
+
+    it('extractBase64ToBuffers produces in-memory buffers for archive', () => {
+      const markdown = `![test](data:image/png;base64,${TINY_PNG})`;
+      const result = extractBase64ToBuffers(markdown);
+
+      expect(result.images).toHaveLength(1);
+      expect(result.images[0].buffer.length).toBeGreaterThan(0);
+      expect(result.images[0].buffer[0]).toBe(0x89); // PNG magic
+      expect(result.markdown).toContain('images/');
+      expect(result.markdown).not.toContain('data:image');
+    });
+  });
 });

package/tests/unit/heading-image.test.js

@@ -0,0 +1,49 @@
+import { convertHtmlToMarkdown } from '../../src/lib.js';
+import { extractBase64Images } from '../../src/gdocs.js';
+
+const PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNgYAAAAAMAASsJTYQAAAAASUVORK5CYII=';
+
+const IMG_REF_PATTERN = /!\[[^\]]*\]\([^)]*images\/[^)]+\)/g;
+
+describe('heading image parity', () => {
+  it('<img> inside <h1> survives Turndown and stays in sync with extraction', () => {
+    const html = `<html><body><h1>Title <img src="data:image/png;base64,${PNG_B64}" alt="x"></h1><p>Body</p></body></html>`;
+
+    const { html: localHtml, images } = extractBase64Images(html);
+    const md = convertHtmlToMarkdown(localHtml);
+    const mdImgCount = (md.match(IMG_REF_PATTERN) || []).length;
+
+    expect(images).toHaveLength(1);
+    expect(mdImgCount).toBe(images.length);
+  });
+
+  it('<img> inside all heading levels is preserved', () => {
+    for (let level = 1; level <= 6; level++) {
+      const tag = `h${level}`;
+      const html = `<html><body><${tag}><img src="data:image/png;base64,${PNG_B64}" alt="icon"> Heading</${tag}></body></html>`;
+
+      const { html: localHtml, images } = extractBase64Images(html);
+      const md = convertHtmlToMarkdown(localHtml);
+      const refs = (md.match(IMG_REF_PATTERN) || []).length;
+
+      expect(refs).toBe(images.length);
+    }
+  });
+
+  it('image count parity across full pipeline', () => {
+    const html = `<html><body>
+<h1><img src="data:image/png;base64,${PNG_B64}" alt="h1"> Chapter</h1>
+<p>Text <img src="data:image/png;base64,${PNG_B64}" alt="p1"> here.</p>
+<h2><img src="data:image/png;base64,${PNG_B64}" alt="h2"> Section</h2>
+<p><img src="data:image/png;base64,${PNG_B64}" alt="p2"></p>
+</body></html>`;
+
+    const { html: localHtml, images } = extractBase64Images(html);
+    const md = convertHtmlToMarkdown(localHtml);
+    const mdRefCount = (md.match(IMG_REF_PATTERN) || []).length;
+
+    expect(images).toHaveLength(4);
+    expect(mdRefCount).toBe(images.length);
+  });
+});