@zumer/snapdom-plugins 1.0.0

package/ascii-export.js

@@ -0,0 +1,60 @@
+/**
+ * asciiExport - Official SnapDOM Plugin
+ * Adds a toAscii() export method that converts captures to ASCII art.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.width=80] - Character width of output
+ * @param {string} [options.charset=' .:-=+*#%@'] - Characters from lightest to darkest
+ * @param {boolean} [options.invert=false] - Invert luminance mapping
+ * @returns {Object} SnapDOM plugin
+ */
+export function asciiExport(options = {}) {
+  const {
+    width: charWidth = 80,
+    charset = ' .:-=+*#%@',
+    invert = false,
+  } = options;
+
+  return {
+    name: 'ascii-export',
+
+    defineExports() {
+      return {
+        ascii: async (ctx, opts = {}) => {
+          const cols = opts.width || charWidth;
+          const chars = opts.charset || charset;
+          const inv = opts.invert ?? invert;
+
+          const img = new Image();
+          img.src = ctx.export.url;
+          await new Promise((res, rej) => {
+            img.onload = res;
+            img.onerror = rej;
+          });
+
+          const aspect = img.height / img.width;
+          const rows = Math.round(cols * aspect * 0.5);
+          const canvas = document.createElement('canvas');
+          canvas.width = cols;
+          canvas.height = rows;
+          const c = canvas.getContext('2d');
+          c.drawImage(img, 0, 0, cols, rows);
+          const data = c.getImageData(0, 0, cols, rows).data;
+
+          let ascii = '';
+          for (let y = 0; y < rows; y++) {
+            for (let x = 0; x < cols; x++) {
+              const i = (y * cols + x) * 4;
+              let lum = (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) / 255;
+              if (inv) lum = 1 - lum;
+              const ci = Math.min(Math.floor(lum * chars.length), chars.length - 1);
+              ascii += chars[ci];
+            }
+            ascii += '\n';
+          }
+          return ascii;
+        }
+      };
+    }
+  };
+}

package/color-tint.js

@@ -0,0 +1,36 @@
+/**
+ * colorTint - Official SnapDOM Plugin
+ * Tints the entire capture to a specified color using an overlay
+ * with mix-blend-mode, following the same pattern as the overlay plugin.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.color='red'] - CSS color value
+ * @param {number} [options.opacity=1] - Overlay opacity (0-1)
+ * @returns {Object} SnapDOM plugin
+ */
+export function colorTint(options = {}) {
+  const {
+    color = 'red',
+    opacity = 1,
+  } = options;
+
+  return {
+    name: 'color-tint',
+
+    async afterClone(context) {
+      const root = context.clone;
+      if (!root || !(root instanceof HTMLElement)) return;
+      root.style.position = 'relative';
+      root.style.overflow = 'hidden';
+      const overlay = document.createElement('div');
+      overlay.style.position = 'absolute';
+      overlay.style.inset = '0';
+      overlay.style.backgroundColor = color;
+      overlay.style.opacity = String(opacity);
+      overlay.style.mixBlendMode = 'color';
+      overlay.style.pointerEvents = 'none';
+      overlay.style.zIndex = '999999';
+      root.appendChild(overlay);
+    }
+  };
+}

package/filter.js

@@ -0,0 +1,35 @@
+/**
+ * filter - Official SnapDOM Plugin
+ * Applies CSS filter effects to the captured clone.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.filter=''] - CSS filter string, e.g. 'grayscale(1) blur(2px)'
+ * @param {string} [options.preset] - 'grayscale' | 'sepia' | 'blur' | 'invert' | 'vintage' | 'dramatic'
+ * @returns {Object} SnapDOM plugin
+ */
+export function filter(options = {}) {
+  const presets = {
+    grayscale:  'grayscale(1)',
+    sepia:      'sepia(1)',
+    blur:       'blur(2px)',
+    invert:     'invert(1)',
+    vintage:    'sepia(0.4) contrast(1.1) brightness(0.9) saturate(0.8)',
+    dramatic:   'contrast(1.4) brightness(0.85) saturate(1.3)',
+  };
+
+  const {
+    filter: filterValue = '',
+    preset,
+  } = options;
+
+  const cssFilter = preset ? (presets[preset] || '') : filterValue;
+
+  return {
+    name: 'filter',
+
+    afterClone(ctx) {
+      if (!cssFilter) return;
+      ctx.clone.style.filter = cssFilter;
+    }
+  };
+}

package/html-in-canvas.js

@@ -0,0 +1,123 @@
+/**
+ * Experimental plugin for WICG html-in-canvas (issue #172).
+ * Uses drawElementImage() to render the snapdom clone directly into canvas,
+ * bypassing SVG/foreignObject.
+ *
+ * Requires: Chrome with chrome://flags/#canvas-draw-element enabled.
+ * @see https://github.com/WICG/html-in-canvas
+ */
+
+const PLUGIN_NAME = 'html-in-canvas'
+
+function isDrawElementImageAvailable() {
+  try {
+    const c = document.createElement('canvas')
+    const ctx = c.getContext('2d')
+    return ctx && typeof ctx.drawElementImage === 'function'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @returns {import('../../src/core/plugins.js').Plugin}
+ */
+export function htmlInCanvasPlugin() {
+  const available = isDrawElementImageAvailable()
+  if (!available) {
+    console.warn('[snapdom] html-in-canvas plugin: drawElementImage not available. Enable chrome://flags/#canvas-draw-element')
+  }
+
+  return {
+    name: PLUGIN_NAME,
+
+    beforeRender(state) {
+      if (!available) return
+      if (!state.clone || !state.element) return
+      state.options.__htmlInCanvas = {
+        clone: state.clone,
+        baseCSS: state.baseCSS || '',
+        fontsCSS: state.fontsCSS || '',
+        classCSS: state.classCSS || '',
+        element: state.element,
+        w0: null,
+        h0: null
+      }
+    },
+
+    afterRender(state) {
+      if (!available) return
+      const meta = state.options?.meta
+      const stored = state.options?.__htmlInCanvas
+      if (meta && stored) {
+        stored.w0 = meta.w0
+        stored.h0 = meta.h0
+      }
+    },
+
+    async defineExports(ctx) {
+      if (!available) return {}
+      const stored = ctx.__htmlInCanvas
+      if (!stored) return {}
+
+      return {
+        htmlInCanvas: async (opts = {}) => {
+          const { clone, baseCSS, fontsCSS, classCSS, element } = stored
+          const w0 = stored.w0 ?? element?.offsetWidth
+          const h0 = stored.h0 ?? element?.offsetHeight
+          const scale = opts.scale ?? ctx.scale ?? 1
+          const dpr = opts.dpr ?? (typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1)
+
+          const rect = element?.getBoundingClientRect?.()
+          const width = w0 ?? rect?.width ?? 100
+          const height = h0 ?? rect?.height ?? 100
+          const outW = Math.round(width * scale * dpr)
+          const outH = Math.round(height * scale * dpr)
+
+          const canvas = document.createElement('canvas')
+          canvas.width = outW
+          canvas.height = outH
+          canvas.setAttribute('layoutsubtree', '')
+
+          const wrapper = document.createElement('div')
+          wrapper.style.cssText = `width:${width}px;height:${height}px;overflow:visible;box-sizing:border-box;`
+          wrapper.setAttribute('xmlns', 'http://www.w3.org/1999/xhtml')
+
+          const styleTag = document.createElement('style')
+          styleTag.textContent = `${baseCSS}${fontsCSS}svg{overflow:visible;}${classCSS}`
+          wrapper.appendChild(styleTag)
+
+          const cloneCopy = clone.cloneNode(true)
+          wrapper.appendChild(cloneCopy)
+
+          canvas.appendChild(wrapper)
+
+          const container = document.createElement('div')
+          container.id = 'snapdom-html-in-canvas-temp'
+          container.style.cssText = 'position:fixed;left:-9999px;top:0;visibility:hidden;'
+          container.appendChild(canvas)
+          document.body.appendChild(container)
+
+          try {
+            await new Promise(r => requestAnimationFrame(r))
+            const ctx2d = canvas.getContext('2d')
+            if (!ctx2d || typeof ctx2d.drawElementImage !== 'function') {
+              throw new Error('drawElementImage not available')
+            }
+            ctx2d.save()
+            ctx2d.scale(dpr * scale, dpr * scale)
+            ctx2d.drawElementImage(wrapper, 0, 0, width, height)
+            ctx2d.restore()
+            return canvas
+          } finally {
+            try {
+              document.body.removeChild(container)
+            } catch {}
+          }
+        }
+      }
+    }
+  }
+}
+
+export default htmlInCanvasPlugin

package/index.js

@@ -0,0 +1,16 @@
+/**
+ * @zumer/snapdom-plugins
+ * Official plugins for SnapDOM.
+ *
+ * Individual:  import { filter } from '@zumer/snapdom-plugins/filter';
+ * All:         import { filter, asciiExport } from '@zumer/snapdom-plugins';
+ */
+
+export { timestampOverlay } from './timestamp-overlay.js';
+export { asciiExport } from './ascii-export.js';
+export { replaceText } from './replace-text.js';
+export { filter } from './filter.js';
+export { colorTint } from './color-tint.js';
+export { pictureResolver } from './picture-resolver.js';
+export { pdfImage } from './pdf-image.js';
+// export { htmlInCanvas } from './html-in-canvas.js';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@zumer/snapdom-plugins",
+  "version": "1.0.0",
+  "description": "Official plugins for SnapDOM",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./timestamp-overlay": "./timestamp-overlay.js",
+    "./ascii-export": "./ascii-export.js",
+    "./replace-text": "./replace-text.js",
+    "./filter": "./filter.js",
+    "./color-tint": "./color-tint.js",
+    "./picture-resolver": "./picture-resolver.js",
+    "./html-in-canvas": "./html-in-canvas.js",
+    "./pdf-image": "./pdf-image.js"
+  },
+  "keywords": [
+    "snapdom",
+    "snapdom-plugin",
+    "dom-capture",
+    "plugins"
+  ],
+  "peerDependencies": {
+    "@zumer/snapdom": ">=0.9.0"
+  },
+  "license": "MIT"
+}

package/pdf-image.js

@@ -0,0 +1,114 @@
+/**
+ * pdfImage - Official SnapDOM Plugin
+ * Exports the capture as a PNG embedded in a downloadable PDF.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.orientation='portrait'] - 'portrait' | 'landscape'
+ * @param {number} [options.quality=0.92] - JPEG quality (0-1)
+ * @param {string} [options.filename='capture.pdf'] - Download filename
+ * @returns {Object} SnapDOM plugin
+ */
+export function pdfImage(options = {}) {
+  const {
+    orientation = 'portrait',
+    quality = 0.92,
+    filename = 'capture.pdf',
+  } = options;
+
+  return {
+    name: 'pdf-image',
+
+    defineExports() {
+      return {
+        pdfImage: async (ctx) => {
+          const img = new Image();
+          img.src = ctx.export.url;
+          await new Promise((res, rej) => { img.onload = res; img.onerror = rej; });
+
+          const isLandscape = orientation === 'landscape';
+          const pageW = isLandscape ? 841.89 : 595.28; // A4 in points
+          const pageH = isLandscape ? 595.28 : 841.89;
+          const margin = 40;
+          const maxW = pageW - margin * 2;
+          const maxH = pageH - margin * 2;
+          const scale = Math.min(maxW / img.width, maxH / img.height, 1);
+          const w = img.width * scale;
+          const h = img.height * scale;
+          const x = (pageW - w) / 2;
+          const y = (pageH - h) / 2;
+
+          // Get image as JPEG data
+          const canvas = document.createElement('canvas');
+          canvas.width = img.width;
+          canvas.height = img.height;
+          canvas.getContext('2d').drawImage(img, 0, 0);
+          const jpegDataUrl = canvas.toDataURL('image/jpeg', quality);
+          const jpegBase64 = jpegDataUrl.split(',')[1];
+          const jpegBytes = atob(jpegBase64);
+          const jpegLen = jpegBytes.length;
+
+          const enc = new TextEncoder();
+          const realOffsets = [];
+
+          // Obj 1-3
+          let textPart = '%PDF-1.4\n';
+          realOffsets.push(textPart.length);
+          textPart += '1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n';
+          realOffsets.push(textPart.length);
+          textPart += '2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n';
+          realOffsets.push(textPart.length);
+          textPart += `3 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${pageW} ${pageH}] /Contents 5 0 R /Resources << /XObject << /Img 4 0 R >> >> >>\nendobj\n`;
+
+          // Obj 4 — image with binary JPEG stream
+          realOffsets.push(textPart.length);
+          const imgHeader = `4 0 obj\n<< /Type /XObject /Subtype /Image /Width ${img.width} /Height ${img.height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length ${jpegLen} >>\nstream\n`;
+
+          const imgHeaderBytes = enc.encode(imgHeader);
+          const preImgBytes = enc.encode(textPart);
+
+          const jpegBuf = new Uint8Array(jpegLen);
+          for (let i = 0; i < jpegLen; i++) jpegBuf[i] = jpegBytes.charCodeAt(i);
+
+          const afterImg = '\nendstream\nendobj\n';
+          const afterImgBytes = enc.encode(afterImg);
+
+          // Obj 5 — content stream
+          const contentStr = `q ${w.toFixed(2)} 0 0 ${h.toFixed(2)} ${x.toFixed(2)} ${y.toFixed(2)} cm /Img Do Q`;
+          const obj5 = `5 0 obj\n<< /Length ${contentStr.length} >>\nstream\n${contentStr}\nendstream\nendobj\n`;
+          const obj5Bytes = enc.encode(obj5);
+
+          realOffsets.push(preImgBytes.length + imgHeaderBytes.length + jpegLen + afterImgBytes.length);
+
+          // xref table
+          const xrefOffset = preImgBytes.length + imgHeaderBytes.length + jpegLen + afterImgBytes.length + obj5Bytes.length;
+          let xref = 'xref\n0 6\n0000000000 65535 f \n';
+          for (let i = 0; i < 5; i++) {
+            xref += `${String(realOffsets[i]).padStart(10, '0')} 00000 n \n`;
+          }
+          xref += `trailer\n<< /Size 6 /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF`;
+          const xrefBytes = enc.encode(xref);
+
+          // Combine all parts
+          const totalLen = preImgBytes.length + imgHeaderBytes.length + jpegLen + afterImgBytes.length + obj5Bytes.length + xrefBytes.length;
+          const pdfBuf = new Uint8Array(totalLen);
+          let pos = 0;
+          pdfBuf.set(preImgBytes, pos); pos += preImgBytes.length;
+          pdfBuf.set(imgHeaderBytes, pos); pos += imgHeaderBytes.length;
+          pdfBuf.set(jpegBuf, pos); pos += jpegLen;
+          pdfBuf.set(afterImgBytes, pos); pos += afterImgBytes.length;
+          pdfBuf.set(obj5Bytes, pos); pos += obj5Bytes.length;
+          pdfBuf.set(xrefBytes, pos);
+
+          const blob = new Blob([pdfBuf], { type: 'application/pdf' });
+          const url = URL.createObjectURL(blob);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = filename;
+          a.click();
+          setTimeout(() => URL.revokeObjectURL(url), 5000);
+          return url;
+        }
+      };
+    }
+  };
+}

package/picture-resolver.js

@@ -0,0 +1,306 @@
+/**
+ * pictureResolver - Official SnapDOM Plugin
+ *
+ * Resolves lazy-loaded <picture> elements that use base64/low-quality placeholders
+ * in <img src> while the real image lives in <source srcset>.
+ *
+ * Common pattern in news sites (La Nación, Clarín, NYT, Medium, etc.):
+ *   <picture>
+ *     <source srcset="https://cdn.example.com/real-image.jpg" media="...">
+ *     <img src="data:image/jpeg;base64,/9j/4AAQ..." alt="...">  ← tiny placeholder
+ *   </picture>
+ *
+ * The browser renders the real image visually, but DOM cloning captures the
+ * placeholder because cloneNode copies the HTML attribute, not the rendered source.
+ *
+ * This plugin:
+ *   1. Detects <picture> elements with base64/blob placeholder <img src>
+ *   2. Resolves the real URL from <source srcset> or img.currentSrc
+ *   3. Fetches the real image using the browser's context (correct Referer/cookies)
+ *   4. Replaces img src with the fetched data URL (attribute + property)
+ *   5. Removes <source> elements to prevent re-resolution during clone
+ *   6. Restores original DOM after cloning (zero side effects)
+ *
+ * Also handles common lazy-loading patterns:
+ *   - data-src / data-srcset attributes (lazysizes, vanilla-lazyload, etc.)
+ *   - loading="lazy" images that haven't entered viewport yet
+ *
+ * @param {Object} [options]
+ * @param {number}  [options.timeout=5000]        Max ms per image fetch
+ * @param {number}  [options.concurrency=4]       Max parallel fetches
+ * @param {boolean} [options.resolveLazySrc=true]  Also resolve data-src/data-srcset patterns
+ * @param {boolean} [options.silent=false]         Suppress console warnings
+ * @param {string}  [options.useProxy='']          CORS proxy for cross-origin images
+ * @returns {import('../../src/core/plugins.js').Plugin}
+ *
+ * @example
+ * // Per-capture usage
+ * const result = await snapdom(element, {
+ *   plugins: [pictureResolver()]
+ * });
+ *
+ * @example
+ * // Global registration
+ * snapdom.plugins(pictureResolver({ timeout: 3000 }));
+ *
+ * @example
+ * // With proxy for cross-origin images
+ * const result = await snapdom(element, {
+ *   plugins: [pictureResolver({ useProxy: 'https://corsproxy.io/?' })]
+ * });
+ */
+export function pictureResolver(options = {}) {
+  const {
+    timeout = 5000,
+    concurrency = 4,
+    resolveLazySrc = true,
+    silent = false,
+    useProxy = '',
+  } = options
+
+  /** @type {Array<() => void>} */
+  let undoStack = []
+
+  /**
+   * Check if a src string is a placeholder (base64, blob, empty, tiny SVG placeholder, etc.)
+   * @param {string} src
+   * @returns {boolean}
+   */
+  function isPlaceholder(src) {
+    if (!src) return true
+    if (src.startsWith('data:')) return true
+    if (src.startsWith('blob:')) return true
+    // Common 1x1 transparent pixel patterns
+    if (/^data:image\/(gif|png|svg)/.test(src) && src.length < 200) return true
+    return false
+  }
+
+  /**
+   * Find the best real URL for an image inside a <picture>.
+   * Priority: img.currentSrc > <source srcset> matching viewport > first <source srcset>
+   * @param {HTMLImageElement} img
+   * @param {HTMLPictureElement} picture
+   * @returns {string|null}
+   */
+  function findRealUrl(img, picture) {
+    // 1) currentSrc is the browser's resolved choice (best match for viewport)
+    const current = img.currentSrc || ''
+    if (current && !isPlaceholder(current)) return current
+
+    // 2) Walk <source> elements; prefer one whose media query matches
+    const sources = picture.querySelectorAll('source[srcset]')
+    let fallback = null
+    for (const source of sources) {
+      const srcset = source.getAttribute('srcset')
+      if (!srcset || isPlaceholder(srcset)) continue
+
+      const media = source.getAttribute('media')
+      if (media) {
+        try {
+          if (window.matchMedia(media).matches) {
+            // Best candidate: matches current viewport
+            return srcset.split(',')[0].trim().split(/\s+/)[0]
+          }
+        } catch { /* invalid media query, skip */ }
+      }
+      // Keep first valid source as fallback
+      if (!fallback) fallback = srcset.split(',')[0].trim().split(/\s+/)[0]
+    }
+
+    return fallback
+  }
+
+  /**
+   * Find lazy-load URLs from data-* attributes.
+   * Supports: data-src, data-srcset, data-lazy-src, data-original
+   * @param {HTMLImageElement} img
+   * @returns {string|null}
+   */
+  function findLazySrc(img) {
+    const candidates = [
+      img.getAttribute('data-src'),
+      img.getAttribute('data-lazy-src'),
+      img.getAttribute('data-original'),
+      img.getAttribute('data-hi-res-src'),
+    ]
+    for (const c of candidates) {
+      if (c && !isPlaceholder(c)) return c
+    }
+    // data-srcset: take first candidate
+    const dataSrcset = img.getAttribute('data-srcset') || img.getAttribute('data-lazy-srcset')
+    if (dataSrcset) {
+      const first = dataSrcset.split(',')[0].trim().split(/\s+/)[0]
+      if (first && !isPlaceholder(first)) return first
+    }
+    return null
+  }
+
+  /**
+   * Fetch an image URL using the browser's context (sends correct Referer/cookies).
+   * Falls back to proxy if direct fetch fails.
+   * @param {string} url
+   * @returns {Promise<string|null>} data URL or null on failure
+   */
+  async function fetchAsDataUrl(url) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeout)
+
+    try {
+      // Try direct fetch first (browser sends Referer/cookies)
+      let resp = await fetch(url, {
+        credentials: 'include',
+        signal: controller.signal,
+      })
+
+      // If blocked, try proxy
+      if (!resp.ok && useProxy) {
+        const proxyUrl = useProxy.includes('{url}')
+          ? useProxy.replace('{url}', encodeURIComponent(url))
+          : useProxy.endsWith('?')
+            ? `${useProxy}${encodeURIComponent(url)}`
+            : `${useProxy}${useProxy.includes('?') ? '&' : '?'}url=${encodeURIComponent(url)}`
+        resp = await fetch(proxyUrl, { signal: controller.signal })
+      }
+
+      if (!resp.ok) return null
+
+      const blob = await resp.blob()
+      return await new Promise((resolve, reject) => {
+        const fr = new FileReader()
+        fr.onload = () => resolve(/** @type {string} */ (fr.result))
+        fr.onerror = reject
+        fr.readAsDataURL(blob)
+      })
+    } catch {
+      return null
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  /**
+   * Process a batch of tasks with limited concurrency.
+   * @param {Array<() => Promise<void>>} tasks
+   */
+  async function runBatched(tasks) {
+    for (let i = 0; i < tasks.length; i += concurrency) {
+      const batch = tasks.slice(i, i + concurrency)
+      await Promise.allSettled(batch.map(fn => fn()))
+    }
+  }
+
+  return {
+    name: 'picture-resolver',
+
+    /**
+     * Before cloning: resolve placeholders to real images in the live DOM.
+     * Stores undo functions to restore original state after clone.
+     */
+    async beforeClone(ctx) {
+      const root = ctx.element
+      if (!root || !(root instanceof Element)) return
+
+      undoStack = []
+      const tasks = []
+
+      // ── 1) <picture> with placeholder <img src> ──
+      const pictures = root.querySelectorAll('picture')
+      for (const picture of pictures) {
+        const img = picture.querySelector('img')
+        if (!img) continue
+
+        const originalSrc = img.getAttribute('src') || ''
+        if (!isPlaceholder(originalSrc)) continue
+
+        const realUrl = findRealUrl(img, picture)
+        if (!realUrl) continue
+
+        tasks.push(async () => {
+          const dataUrl = await fetchAsDataUrl(realUrl)
+          if (!dataUrl) {
+            if (!silent) console.warn(`[snapdom:picture-resolver] Failed to fetch: ${realUrl.slice(0, 60)}`)
+            return
+          }
+
+          // Save original state for undo
+          const origAttr = img.getAttribute('src')
+          const origSrcset = img.getAttribute('srcset')
+          const origSizes = img.getAttribute('sizes')
+          const removedSources = []
+
+          // Swap to real image
+          img.src = dataUrl
+          img.setAttribute('src', dataUrl)
+          img.removeAttribute('srcset')
+          img.removeAttribute('sizes')
+
+          // Remove <source> elements to prevent clone re-resolution
+          const sources = picture.querySelectorAll('source')
+          for (const s of sources) {
+            removedSources.push({ el: s, parent: s.parentElement, next: s.nextSibling })
+            s.remove()
+          }
+
+          // Register undo
+          undoStack.push(() => {
+            if (origAttr !== null) img.setAttribute('src', origAttr)
+            else img.removeAttribute('src')
+            if (origSrcset !== null) img.setAttribute('srcset', origSrcset)
+            if (origSizes !== null) img.setAttribute('sizes', origSizes)
+            for (const { el, parent, next } of removedSources) {
+              if (parent) parent.insertBefore(el, next)
+            }
+          })
+        })
+      }
+
+      // ── 2) Lazy-loaded <img> with data-src / data-srcset ──
+      if (resolveLazySrc) {
+        const imgs = root.querySelectorAll('img')
+        for (const img of imgs) {
+          // Skip images already handled by <picture> pass
+          if (img.closest('picture') && isPlaceholder(img.getAttribute('src') || '')) continue
+
+          const currentSrc = img.getAttribute('src') || ''
+          const lazySrc = findLazySrc(img)
+
+          // Case A: has data-src but current src is placeholder
+          if (lazySrc && isPlaceholder(currentSrc)) {
+            tasks.push(async () => {
+              const dataUrl = await fetchAsDataUrl(lazySrc)
+              if (!dataUrl) return
+
+              const origSrc = img.getAttribute('src')
+              img.src = dataUrl
+              img.setAttribute('src', dataUrl)
+              img.removeAttribute('srcset')
+              img.removeAttribute('sizes')
+
+              undoStack.push(() => {
+                if (origSrc !== null) img.setAttribute('src', origSrc)
+                else img.removeAttribute('src')
+              })
+            })
+          }
+        }
+      }
+
+      // Run all fetches with concurrency limit
+      if (tasks.length > 0) {
+        await runBatched(tasks)
+      }
+    },
+
+    /**
+     * After cloning: restore original DOM (undo all mutations).
+     */
+    async afterClone(ctx) {
+      for (const undo of undoStack) {
+        try { undo() } catch { /* non-blocking */ }
+      }
+      undoStack = []
+    },
+  }
+}
+
+export default pictureResolver

package/replace-text.js

@@ -0,0 +1,43 @@
+/**
+ * replaceText - Official SnapDOM Plugin
+ * Find-and-replace text in the captured clone.
+ *
+ * @param {Object} [options]
+ * @param {Array<{find: string|RegExp, replace: string}>} [options.replacements=[]]
+ * @returns {Object} SnapDOM plugin
+ */
+export function replaceText(options = {}) {
+  const {
+    replacements = [],
+  } = options;
+
+  function walkTextNodes(node, fn) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      fn(node);
+    } else {
+      for (const child of node.childNodes) {
+        walkTextNodes(child, fn);
+      }
+    }
+  }
+
+  return {
+    name: 'replace-text',
+
+    afterClone(ctx) {
+      if (!replacements.length) return;
+
+      walkTextNodes(ctx.clone, (textNode) => {
+        let text = textNode.textContent;
+        for (const { find, replace } of replacements) {
+          if (find instanceof RegExp) {
+            text = text.replace(find, replace);
+          } else {
+            text = text.split(find).join(replace);
+          }
+        }
+        textNode.textContent = text;
+      });
+    }
+  };
+}

package/timestamp-overlay.js

@@ -0,0 +1,64 @@
+/**
+ * timestampOverlay - Official SnapDOM Plugin
+ * Adds a translucent timestamp label to the captured clone.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.format='datetime'] - 'datetime' | 'date' | 'time' | 'iso' | custom function
+ * @param {string} [options.position='bottom-right'] - 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+ * @param {string} [options.background='rgba(0,0,0,0.6)']
+ * @param {string} [options.color='#fff']
+ * @param {number} [options.fontSize=11]
+ * @returns {Object} SnapDOM plugin
+ */
+export function timestampOverlay(options = {}) {
+  const {
+    format = 'datetime',
+    position = 'bottom-right',
+    background = 'rgba(0,0,0,0.6)',
+    color = '#fff',
+    fontSize = 11,
+  } = options;
+
+  function getTimestamp() {
+    const now = new Date();
+    if (typeof format === 'function') return format(now);
+    switch (format) {
+      case 'date':     return now.toLocaleDateString();
+      case 'time':     return now.toLocaleTimeString();
+      case 'iso':      return now.toISOString();
+      case 'datetime':
+      default:         return now.toLocaleString();
+    }
+  }
+
+  const posMap = {
+    'top-left':     'top:6px;left:6px',
+    'top-right':    'top:6px;right:6px',
+    'bottom-left':  'bottom:6px;left:6px',
+    'bottom-right': 'bottom:6px;right:6px',
+  };
+
+  return {
+    name: 'timestamp-overlay',
+
+    afterClone(ctx) {
+      const label = document.createElement('div');
+      label.textContent = getTimestamp();
+      label.style.cssText = `
+        position:absolute;
+        ${posMap[position] || posMap['bottom-right']};
+        background:${background};
+        color:${color};
+        font-size:${fontSize}px;
+        padding:2px 6px;
+        border-radius:3px;
+        font-family:monospace;
+        pointer-events:none;
+        z-index:999999;
+        line-height:1.4;
+      `;
+      ctx.clone.style.position = 'relative';
+      ctx.clone.appendChild(label);
+    }
+  };
+}