@helping-ai-workflow/md2doc 2.4.0 → 2.4.2

package/README.md

@@ -75,6 +75,29 @@ also pass `--open`.
 | `--version`, `-v` | Print version. |
 | `--help`, `-h` | Print help. |
 
+### Images
+
+Local images referenced from the markdown are resolved against the **markdown file's own
+directory** and inlined into the output as base64 `data:` URIs, so the rendered HTML / PDF
+stays self-contained wherever it is written (the OS temp dir by default) and however it is
+later copied or mailed.
+
+```markdown
+![block diagram](assets/block.png)        <!-- inlined -->
+<img src="assets/block.png" width="400">  <!-- inlined, attributes preserved -->
+![remote](https://example.com/x.png)      <!-- left as a remote URL -->
+```
+
+`srcset` and `<source>` inside `<picture>` are inlined too. Only known image
+extensions are inlined, so `![x](../../id_rsa)` is left alone rather than
+base64'd into a document you may be about to share.
+
+A reference with no file on disk keeps its original `src` and prints
+`[WARN] image not found, left as-is: ...` on stderr; the render still succeeds.
+
+Each reference carries its own copy of the payload, so re-using one large diagram
+in several places grows the HTML accordingly. PDF output is unaffected.
+
 ### Migration from md2html / md2pdf (v1.x → v2.0.0)
 
 | Old | New |

package/lib/md2doc.js

@@ -129,6 +129,169 @@ function buildKatexStyleTag() {
   return `<style data-md2doc-math>${css}</style>`;
 }
 
+// ── Local image assets ───────────────────────────────────────────────────────
+// Image srcs in the markdown are relative to the SOURCE markdown, but the HTML
+// is normally written somewhere else entirely (the OS temp dir by default), so
+// a relative src resolves against the wrong directory and the image silently
+// never loads. Resolve every local reference against the markdown's own
+// directory and inline it as a data: URI — the same self-contained principle
+// the embedded CSS / KaTeX fonts already follow, and the only form that also
+// survives the puppeteer PDF path (which renders from its own temp HTML).
+const SRC_DIR = path.dirname(path.resolve(src));
+const LARGE_ASSET_WARN_BYTES = 4 * 1024 * 1024;
+
+// Doubles as the allowlist: a reference whose extension is not an image is left
+// alone. Without that gate, `![x](../../../.ssh/id_rsa)` would happily base64
+// the file into a document meant to be shared.
+const IMAGE_MIME_BY_EXT = {
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.jfif': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.bmp':  'image/bmp',
+  '.ico':  'image/x-icon',
+  '.apng': 'image/apng',
+  '.tif':  'image/tiff',
+  '.tiff': 'image/tiff',
+};
+
+const inlinedAssetCache = new Map();
+const skippedAssetWarned = new Set();
+
+// Only a scheme we actually know is treated as remote — a bare `letter+colon`
+// test would misread both a Windows drive (`C:/img.png`) and a filename that
+// merely contains a colon. `//host/x.png` is protocol-relative.
+const EXTERNAL_REF_RE = /^(?:(?:https?|data|file|blob|ftps?|mailto|tel|about|chrome|chrome-extension|moz-extension):|\/\/)/i;
+
+function isExternalRef(href) {
+  return EXTERNAL_REF_RE.test(String(href).trim());
+}
+
+function warnOnce(href, message) {
+  if (skippedAssetWarned.has(href)) return;
+  skippedAssetWarned.add(href);
+  console.error(message);
+}
+
+// Splits `assets/pic.svg?v=2#gear` into its path and its fragment. The query is
+// dropped (it is cache-busting for a fetch that no longer happens); the
+// fragment is kept and re-attached to the data URI, since it selects a view /
+// symbol inside an SVG rather than addressing the file.
+function splitAssetRef(href) {
+  const raw = String(href).trim();
+  const hash = raw.indexOf('#');
+  const withoutHash = hash === -1 ? raw : raw.slice(0, hash);
+  const fragment = hash === -1 ? '' : raw.slice(hash);
+  return { filePart: withoutHash.replace(/\?.*$/, ''), fragment };
+}
+
+function resolveAssetPath(filePart) {
+  if (!filePart) return null;
+  let decoded = filePart;
+  try {
+    decoded = decodeURIComponent(filePart);
+  } catch (_) {
+    // Malformed percent-escapes: probe the raw form only.
+  }
+  const candidates = [];
+  for (const c of [decoded, filePart]) {
+    candidates.push(path.isAbsolute(c) ? c : path.resolve(SRC_DIR, c));
+  }
+  return firstExistingPath(candidates);
+}
+
+// Returns a data: URI, or null when the reference must be left untouched
+// (remote URL, already a data: URI, non-image extension, or no such file).
+function inlineImageSrc(href) {
+  if (!href || isExternalRef(href)) return null;
+  const { filePart, fragment } = splitAssetRef(href);
+  if (!filePart) return null;
+
+  const mime = IMAGE_MIME_BY_EXT[path.extname(filePart).toLowerCase()];
+  if (!mime) {
+    warnOnce(href, `[WARN] not a known image extension, left as-is: ${href}`);
+    return null;
+  }
+
+  const abs = resolveAssetPath(filePart);
+  if (!abs) {
+    warnOnce(href, `[WARN] image not found, left as-is: ${href} (resolved against ${SRC_DIR})`);
+    return null;
+  }
+
+  let uri = inlinedAssetCache.get(abs);
+  if (uri === undefined) {
+    uri = null;
+    try {
+      const stat = fs.statSync(abs);
+      if (!stat.isFile()) throw new Error('not a regular file');
+      if (stat.size > LARGE_ASSET_WARN_BYTES) {
+        console.error(`[WARN] inlining large image (${(stat.size / 1048576).toFixed(1)} MB): ${href}`);
+      }
+      uri = `data:${mime};base64,${fs.readFileSync(abs).toString('base64')}`;
+    } catch (e) {
+      console.error(`[WARN] could not inline image ${href}: ${e.message}`);
+      uri = null;
+    }
+    inlinedAssetCache.set(abs, uri);
+  }
+  return uri ? uri + fragment : null;
+}
+
+// A srcset value is a comma-separated list of `<url> <descriptor>` candidates.
+function inlineSrcsetValue(value) {
+  const parts = String(value).split(',');
+  let changed = false;
+  const rebuilt = parts.map((part) => {
+    const m = part.match(/^(\s*)(\S+)(\s*.*)$/);
+    if (!m) return part;
+    const uri = inlineImageSrc(m[2]);
+    if (!uri) return part;
+    changed = true;
+    return m[1] + uri + m[3];
+  });
+  return changed ? rebuilt.join(',') : null;
+}
+
+// Author-written <img> / <source> tags (specs use them for width= and for
+// <picture>) need the same rewrite. Scoped to markdown-authored HTML chunks
+// only — never run over the whole page, whose bundled mermaid / katex JS also
+// contains '<img' literals.
+// The tag matcher is attribute-aware: a quoted value may legally contain '>',
+// and a plain [^>]* would truncate the tag and miss a src that sits after it.
+const ASSET_TAG_RE = /<(?:img|source)\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const SRC_ATTR_RE   = /(\s(?:src|srcset)\s*=\s*)(?:(["'])([^"']*)\2|([^\s"'=<>`]+))/gi;
+
+function inlineImagesInTag(tag) {
+  return tag.replace(SRC_ATTR_RE, (match, lead, quote, quoted, bare) => {
+    const raw = (quoted !== undefined ? quoted : bare) || '';
+    const decoded = raw.replace(/&amp;/g, '&');
+    const isSrcset = /srcset\s*=\s*$/i.test(lead);
+    const value = isSrcset ? inlineSrcsetValue(decoded) : inlineImageSrc(decoded);
+    return value ? `${lead}"${value}"` : match;
+  });
+}
+
+function inlineImagesInHtmlChunk(chunk) {
+  if (!chunk || !/<(?:img|source)\b/i.test(chunk)) return chunk;
+  // Step over comments untouched — a commented-out <img> is not displayed, so
+  // inlining it would only bloat the output (or smuggle a file into it).
+  let out = '';
+  let last = 0;
+  HTML_COMMENT_RE.lastIndex = 0;
+  let m;
+  while ((m = HTML_COMMENT_RE.exec(chunk)) !== null) {
+    out += chunk.slice(last, m.index).replace(ASSET_TAG_RE, inlineImagesInTag) + m[0];
+    last = m.index + m[0].length;
+  }
+  return out + chunk.slice(last).replace(ASSET_TAG_RE, inlineImagesInTag);
+}
+
 let bodyHtml;
 let tocHtml = '';
 let serializedSections = '[]';
@@ -325,6 +488,29 @@ ${itemsHtml}
       .replace(/'/g, '&#39;');
   }
 
+  // marked's tokenizer already escapes alt / title (its default image renderer
+  // interpolates both raw), so this must NOT escape them again. Only the src is
+  // ours; everything else — including cleanUrl() on a src we leave alone — stays
+  // marked's job, so non-inlined images render exactly as before.
+  const baseImage = renderer.image.bind(renderer);
+  renderer.image = function(token) {
+    const isObj = (token !== null && typeof token === 'object');
+    const href  = isObj ? (token.href  || '') : (token || '');
+    const title = isObj ? (token.title || '') : (arguments[1] || '');
+    const text  = isObj ? (token.text  || '') : (arguments[2] || '');
+    const uri = inlineImageSrc(href);
+    if (!uri) return baseImage.apply(this, arguments);
+    // A data: URI is base64 (or an already-encoded payload): no quote, no '<'.
+    let out = `<img src="${uri}" alt="${text}"`;
+    if (title) out += ` title="${title}"`;
+    return out + '>';
+  };
+
+  const baseHtml = renderer.html.bind(renderer);
+  renderer.html = function(token) {
+    return inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
+  };
+
   renderer.code = function(token) {
     // token is either a string (old API) or {text, lang} object (new API)
     const lang = (typeof token === 'object') ? (token.lang || '') : (arguments[1] || '');
@@ -1682,6 +1868,83 @@ ${mermaidInitTag}` : ''}
       setSidebarOpen(false);
     }
   });
+
+  // ── Zoom / resize scroll anchoring ────────────────────────────────────────
+  // Browser zoom (and any window resize) reflows the column but leaves the
+  // pixel scroll offset untouched, so the passage being read slides out of
+  // view. Remember what sat at the top of the reading column and put it back.
+  var ANCHOR_LINE = 80;
+  var contentEl = document.querySelector('main.content');
+  var anchorNode = null;
+  var anchorTop = 0;
+  var anchorFrame = 0;
+  var suppressAnchorCapture = false;
+  var lastLayoutWidth = document.documentElement.clientWidth;
+  var lastPixelRatio = window.devicePixelRatio;
+
+  function captureScrollAnchor() {
+    if (suppressAnchorCapture || !contentEl) return;
+    var rect = contentEl.getBoundingClientRect();
+    var hit = document.elementFromPoint(rect.left + rect.width / 2, ANCHOR_LINE);
+    var node = (hit && hit.closest) ? hit.closest('main.content > *') : null;
+    if (!node) {
+      // Between blocks, or over a gap: fall back to the last heading above the
+      // anchor line. Heading offsets are monotonic in document order, so this
+      // is a binary search rather than a scan of every heading each frame.
+      var lo = 0;
+      var hi = headingNodes.length - 1;
+      while (lo <= hi) {
+        var mid = (lo + hi) >> 1;
+        if (headingNodes[mid].getBoundingClientRect().top <= ANCHOR_LINE) {
+          node = headingNodes[mid];
+          lo = mid + 1;
+        } else {
+          hi = mid - 1;
+        }
+      }
+    }
+    if (!node) return;
+    anchorNode = node;
+    anchorTop = node.getBoundingClientRect().top;
+  }
+
+  function restoreScrollAnchor() {
+    if (!anchorNode || !anchorNode.isConnected) return;
+    var delta = anchorNode.getBoundingClientRect().top - anchorTop;
+    if (!delta) return;
+    window.scrollTo(window.scrollX, window.scrollY + delta);
+  }
+
+  window.addEventListener('scroll', function () {
+    if (anchorFrame) return;
+    anchorFrame = window.requestAnimationFrame(function () {
+      anchorFrame = 0;
+      captureScrollAnchor();
+    });
+  }, { passive: true });
+
+  window.addEventListener('resize', function () {
+    var width = document.documentElement.clientWidth;
+    var ratio = window.devicePixelRatio;
+    // A height-only change (a mobile browser hiding its toolbar, a devtools
+    // dock) reflows nothing, so correcting the scroll would only jerk the page.
+    if (width === lastLayoutWidth && ratio === lastPixelRatio) return;
+    lastLayoutWidth = width;
+    lastPixelRatio = ratio;
+    // Hold the anchor across the whole reflow: the scrollTo below fires scroll
+    // events that would otherwise re-capture a mid-reflow position.
+    suppressAnchorCapture = true;
+    restoreScrollAnchor();
+    window.requestAnimationFrame(function () {
+      restoreScrollAnchor();
+      window.requestAnimationFrame(function () {
+        suppressAnchorCapture = false;
+        captureScrollAnchor();
+      });
+    });
+  });
+
+  captureScrollAnchor();
 })();
 </script>
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/cli.test.js && node test/code-operator.test.js"
+    "test": "node test/md2doc.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/cli.test.js && node test/code-operator.test.js"
   },
   "repository": {
     "type": "git",