@link-assistant/web-capture 1.7.25 → 1.7.27

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/web-capture
 
+## 1.7.27
+
+### Patch Changes
+
+- 9cbb4c7: Pin the default `--format archive` layout contract so the zip always contains exactly `document.md` + `document.html` + `images/` (issue #113). The markdown-format archive endpoint previously bundled only `document.md` and `images/`, omitting the reference `document.html`; it now includes it on every path. Adds a reusable `buildArchiveFromHtml(html, baseUrl)` helper and an integration test that pins the layout so a future refactor cannot regress it.
+
+## 1.7.26
+
+### Patch Changes
+
+- 112f2f9: Fix `stripBase64Images` (used by `--keep-original-links`) dropping every base64 image with empty alt text instead of leaving a visible placeholder. Google Docs HTML exports emit `<img alt="" src="data:image/png;base64,...">` for every image, so the previous behaviour silently deleted all images from the rendered markdown. Empty-alt now renders as `![]()` (a valid empty image reference); non-empty alt continues to render as `*[image: <alt>]*`.
+
 ## 1.7.25
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/web-capture",
-  "version": "1.7.25",
+  "version": "1.7.27",
   "description": "CLI and microservice to render web pages as HTML, Markdown, or PNG",
   "main": "src/index.js",
   "bin": {
@@ -65,7 +65,8 @@
     "markdown-it": "^14.1.1",
     "nock": "^13.5.4",
     "prettier": "^3.6.2",
-    "supertest": "^6.3.4"
+    "supertest": "^6.3.4",
+    "unzipper": "^0.12.3"
   },
   "type": "module",
   "keywords": [

package/src/archive.js

@@ -170,14 +170,17 @@ export async function archiveHandler(req, res) {
       }
 
       if (!embedImages && !keepOriginalLinks) {
-        const b64 = extractBase64ToBuffers(markdown, 'images');
-        markdown = b64.markdown;
-        for (const img of b64.images) {
-          archive.append(img.buffer, { name: `images/${img.filename}` });
-        }
+        appendMarkdownAndImages(archive, markdown);
+      } else {
+        archive.append(markdown, { name: 'document.md' });
       }
 
-      archive.append(markdown, { name: 'document.md' });
+      // document.html — the source the markdown was derived from, for
+      // reference only, so the default archive layout (document.md +
+      // document.html + images/) is identical across capture paths (issue #113).
+      archive.append(prettyPrintHtml(convertRelativeUrls(html, absoluteUrl)), {
+        name: 'document.html',
+      });
     }
 
     // Download and add images if local mode
@@ -207,6 +210,57 @@ export async function archiveHandler(req, res) {
   }
 }
 
+/**
+ * Extract base64 images from `markdown` into the archive's `images/` folder and
+ * append the rewritten markdown as `document.md`. Shared by the archive
+ * endpoint and {@link buildArchiveFromHtml} so the default layout stays
+ * identical across capture paths.
+ *
+ * @param {import('archiver').Archiver} archive - The archive being built
+ * @param {string} markdown - Markdown content (may contain base64 data URIs)
+ */
+function appendMarkdownAndImages(archive, markdown) {
+  const { markdown: rewritten, images } = extractBase64ToBuffers(
+    markdown,
+    'images'
+  );
+  for (const img of images) {
+    archive.append(img.buffer, { name: `images/${img.filename}` });
+  }
+  archive.append(rewritten, { name: 'document.md' });
+}
+
+/**
+ * Build a self-contained ZIP archive (as a Buffer) from raw HTML, matching the
+ * default `--format archive` layout contract (issue #113):
+ *
+ *   - `document.md`   — markdown referencing images by relative `images/` path
+ *   - `document.html` — the source HTML the markdown was derived from (reference)
+ *   - `images/`       — every inline base64 image as a separate file
+ *
+ * @param {string} html - Source HTML to convert
+ * @param {string} baseUrl - Base URL for resolving relative links
+ * @returns {Promise<Buffer>} the finalized ZIP archive bytes
+ */
+export async function buildArchiveFromHtml(html, baseUrl) {
+  const archive = archiver('zip', { zlib: { level: 9 } });
+  const chunks = [];
+  archive.on('data', (chunk) => chunks.push(chunk));
+  const finished = new Promise((resolve, reject) => {
+    archive.on('end', resolve);
+    archive.on('error', reject);
+  });
+
+  appendMarkdownAndImages(archive, convertHtmlToMarkdown(html, baseUrl));
+  archive.append(prettyPrintHtml(convertRelativeUrls(html, baseUrl)), {
+    name: 'document.html',
+  });
+
+  await archive.finalize();
+  await finished;
+  return Buffer.concat(chunks);
+}
+
 function guessImageExtension(url) {
   const pathname = new URL(url).pathname.toLowerCase();
   if (pathname.endsWith('.jpg') || pathname.endsWith('.jpeg')) {

package/src/extract-images.js

@@ -95,9 +95,16 @@ export function extractBase64ToBuffers(markdown, imagesDir = '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.
+ * Strip base64 data URI images from markdown, leaving a visible placeholder.
+ * Used when keepOriginalLinks is enabled — base64 images have no original URL
+ * to restore, so we remove the heavy data URI but still leave a marker so the
+ * reader can see that an image was here.
+ *
+ * Non-empty alt becomes `*[image: <alt>]*`. Empty alt — common for Google Docs
+ * HTML exports, which emit `<img alt="" src="data:...">` for every image —
+ * becomes `![]()`, an empty markdown image reference that renderers still
+ * surface as a slot. Emitting `''` for empty-alt would silently delete every
+ * image in the document (see issue #117).
  *
  * @param {string} markdown - Markdown content with data URI images
  * @returns {{markdown: string, stripped: number}}
@@ -108,7 +115,7 @@ export function stripBase64Images(markdown) {
     BASE64_IMAGE_REGEX,
     (_match, altText) => {
       stripped++;
-      return altText ? `*[image: ${altText}]*` : '';
+      return altText ? `*[image: ${altText}]*` : '![]()';
     }
   );
   return { markdown: updatedMarkdown, stripped };

package/tests/integration/api-endpoints.test.js

@@ -9,6 +9,7 @@
 import { jest } from '@jest/globals';
 import request from 'supertest';
 import nock from 'nock';
+import unzipper from 'unzipper';
 import { app } from '../../src/index.js';
 
 jest.setTimeout(60000);
@@ -95,6 +96,14 @@ describe('API Endpoint Tests', () => {
       // ZIP signature: PK (0x50 0x4B)
       expect(res.body[0]).toBe(0x50);
       expect(res.body[1]).toBe(0x4b);
+
+      // Default archive layout contract (issue #113): the markdown archive must
+      // bundle document.md AND document.html for reference.
+      const dir = await unzipper.Open.buffer(res.body);
+      const names = dir.files.map((f) => f.path);
+      expect(names).toEqual(
+        expect.arrayContaining(['document.md', 'document.html'])
+      );
     });
 
     it('returns a ZIP archive with HTML format', async () => {

package/tests/integration/archive-default-layout.test.js

@@ -0,0 +1,37 @@
+/**
+ * Pin the default `--format archive` layout contract (issue #113):
+ * the zip contains exactly `document.md` + `document.html` + `images/`.
+ */
+import unzipper from 'unzipper';
+import { buildArchiveFromHtml } from '../../src/archive.js';
+
+const TINY_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+const FIXTURE_HTML = `<!doctype html><html><body>
+  <h1>Hi</h1><p>Para 1.</p>
+  <p><img alt="" src="data:image/png;base64,${TINY_PNG}"></p>
+  <p>Para 2.</p>
+</body></html>`;
+
+it('default archive contains document.md, document.html, and images/ folder', async () => {
+  const buf = await buildArchiveFromHtml(
+    FIXTURE_HTML,
+    'https://example.invalid/'
+  );
+  const dir = await unzipper.Open.buffer(buf);
+  const names = dir.files.map((f) => f.path);
+
+  expect(names).toEqual(
+    expect.arrayContaining(['document.md', 'document.html'])
+  );
+  expect(names.some((n) => n.startsWith('images/'))).toBe(true);
+
+  const mdEntry = dir.files.find((f) => f.path === 'document.md');
+  const md = (await mdEntry.buffer()).toString();
+  expect(md).toMatch(/images\//);
+  expect(md).not.toMatch(/data:image/);
+
+  const htmlEntry = dir.files.find((f) => f.path === 'document.html');
+  const html = (await htmlEntry.buffer()).toString();
+  expect(html).toMatch(/<h1>/);
+});

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

@@ -204,12 +204,18 @@ describe('extract-images module', () => {
       expect(result.markdown).not.toContain('data:image');
     });
 
-    it('strips base64 images with empty alt text', () => {
-      const md = `![](data:image/png;base64,${TINY_PNG})`;
+    it('leaves a visible placeholder when stripping a base64 image with empty alt', () => {
+      // Google Docs HTML exports emit `<img alt="" src="data:image/png;base64,...">`,
+      // which renders as `![](data:...)`. If stripping drops the markdown image
+      // entirely, every image in the doc vanishes from the output with no
+      // indication that anything was lost. Leave a visible placeholder so the
+      // reader can see that an image was here.
+      const md = `Hi.\n\n![](data:image/png;base64,${TINY_PNG})\n\nBye.\n`;
       const result = stripBase64Images(md);
 
       expect(result.stripped).toBe(1);
-      expect(result.markdown).toBe('');
+      expect(result.markdown).not.toMatch(/data:image/);
+      expect(result.markdown).toMatch(/!\[|\[image/);
     });
 
     it('preserves remote image URLs', () => {