I built a Chrome extension that downloads every image on a page — here's what I learned about Shadow DOM, CSS backgrounds, and Manifest V3

kyriewen — Thu, 07 May 2026 11:47:14 +0000

For three years I've kept a folder called _inspiration on my desktop, full of images I "saved as" while researching designs, products, or just browsing. About 60% of the time, "save image as" failed silently — the file would be a 1×1 transparent placeholder, or a low-res thumbnail, or just nothing because the image was a CSS background.

I tried the popular image downloader extensions. They missed about half of what I wanted to save. They also bundled analytics. So I built my own, called Image Harvest.

This post is the technical write-up I wished existed when I started. Three things tripped me up the most:

Extracting images from Shadow DOM and CSS backgrounds
Perceptual hashing in the browser without freezing the UI
Surviving the Manifest V3 service worker lifecycle

Code excerpts below are simplified for clarity. The shipping version handles a lot more edge cases.

1. The five places images actually hide on modern webpages

document.querySelectorAll('img') catches maybe 50% of images on a typical 2026 webpage. The rest live in:

<picture> and srcset — multiple resolutions; the browser picks one but you might want all
CSS background-image — used heavily on hero sections, gallery sites, e-commerce product pages
Lazy-loaded sources — loading="lazy", IntersectionObserver-driven, or framework-specific
<iframe> content — same-origin only, but more common than you'd think
Shadow DOM — especially on sites built with web components or React + shadow boundaries (some design systems)

A complete extraction pass needs to handle all five. Here's the core walker:

function extractImagesFromDocument(doc) {
  const images = new Set();

  // 1. Plain <img> and <picture>
  doc.querySelectorAll('img').forEach(img => {
    if (img.currentSrc) images.add(img.currentSrc);
    if (img.src) images.add(img.src);
    if (img.srcset) {
      parseSrcset(img.srcset).forEach(url => images.add(url));
    }
  });

  // 2. CSS background-image on every element
  doc.querySelectorAll('*').forEach(el => {
    const bg = getComputedStyle(el).backgroundImage;
    if (bg && bg !== 'none') {
      const matches = bg.match(/url\(["']?(.*?)["']?\)/g) || [];
      matches.forEach(m => {
        const url = m.replace(/^url\(["']?/, '').replace(/["']?\)$/, '');
        if (url && !url.startsWith('data:')) images.add(url);
      });
    }
  });

  // 3. Recurse into open Shadow DOM
  doc.querySelectorAll('*').forEach(el => {
    if (el.shadowRoot) {
      extractImagesFromDocument(el.shadowRoot).forEach(url => images.add(url));
    }
  });

  // 4. Same-origin iframes
  doc.querySelectorAll('iframe').forEach(iframe => {
    try {
      if (iframe.contentDocument) {
        extractImagesFromDocument(iframe.contentDocument).forEach(url => images.add(url));
      }
    } catch (e) {
      // Cross-origin — silently skip
    }
  });

  return images;
}

A few non-obvious things:

getComputedStyle is expensive when called on every element. On a 5000-node Pinterest page it can take 200ms. I batch it with requestIdleCallback and stream results to the side panel as they arrive.
document.querySelectorAll('*') is fine — even on huge pages it's a single pass. The expensive part is what you do with each element.
Closed Shadow DOM is unreachable by design. There's no workaround. You just accept the partial result and move on.

2. Perceptual hashing without freezing the UI

After extraction, you often have 200+ images and many are duplicates at different resolutions. The user wants a deduped list. Comparing pixel-by-pixel doesn't work because resized versions differ. Perceptual hashing is the answer.

I use dHash (difference hash) — it's simpler than pHash and good enough for "is this the same image at a different size":

async function dHash(imageUrl) {
  const img = await loadImage(imageUrl);
  const canvas = new OffscreenCanvas(9, 8); // 9x8 because we compare adjacent pixels
  const ctx = canvas.getContext('2d');
  ctx.drawImage(img, 0, 0, 9, 8);
  const { data } = ctx.getImageData(0, 0, 9, 8);

  let hash = 0n;
  for (let row = 0; row < 8; row++) {
    for (let col = 0; col < 8; col++) {
      const left = grayscale(data, row * 9 + col);
      const right = grayscale(data, row * 9 + col + 1);
      hash = (hash << 1n) | (left > right ? 1n : 0n);
    }
  }
  return hash;
}

function grayscale(data, pixelIndex) {
  const i = pixelIndex * 4;
  return (data[i] + data[i + 1] + data[i + 2]) / 3;
}

function hammingDistance(a, b) {
  let xor = a ^ b;
  let dist = 0;
  while (xor) {
    dist += Number(xor & 1n);
    xor >>= 1n;
  }
  return dist;
}

Two images with hamming distance < 8 are "similar enough" for my use case. ~50ms per image on average hardware.

The critical part: run this in a Web Worker. Doing 200 hashes on the main thread freezes the side panel. The worker pipeline:

// In the panel UI:
const worker = new Worker('hash-worker.js');
worker.postMessage({ urls: extractedImages });
worker.onmessage = (e) => {
  // Stream similarity results back as they're computed
  updateUIWithCluster(e.data);
};

OffscreenCanvas works inside workers, which is the magic that makes this possible without a UI thread roundtrip.

3. Manifest V3 service worker — the cold-start trap

MV3 killed background pages. You get a service worker that dies after ~30 seconds of inactivity. Re-opening your extension panel triggers a cold start, and that cold start can be ~150ms of "loading…" on slow machines.

The fix is chrome.storage.session:

// In the service worker:
async function getCachedExtraction(tabId) {
  const cache = await chrome.storage.session.get(`extraction_${tabId}`);
  return cache[`extraction_${tabId}`];
}

async function setCachedExtraction(tabId, results) {
  await chrome.storage.session.set({
    [`extraction_${tabId}`]: {
      timestamp: Date.now(),
      results
    }
  });
}

// In the panel:
async function loadPanel(tabId) {
  const cached = await getCachedExtraction(tabId);
  if (cached && Date.now() - cached.timestamp < 5 * 60 * 1000) {
    renderResults(cached.results); // Instant
    return;
  }
  showLoading();
  const fresh = await runExtraction(tabId);
  renderResults(fresh);
}

chrome.storage.session survives service-worker death (it's gone when the browser closes) so the second open is instant. This single change made the panel feel "native" instead of "extension-y."

A second MV3 gotcha: chrome.scripting.executeScript with world: 'MAIN' is required when you need to access page-level globals. Default is 'ISOLATED', which can't see things like window.MY_FRAMEWORK that some sites expose for image config.

await chrome.scripting.executeScript({
  target: { tabId, allFrames: true },
  world: 'MAIN', // ← critical for some sites
  func: extractImagesFromDocument,
});

4. The Side Panel API at narrow widths

The Chrome Side Panel API is genuinely good but underdocumented. The hard part isn't the API — it's making your UI actually usable at the side panel's minimum width (~280px).

Three things that helped:

Three density presets (compact, comfortable, spacious) instead of trying to make one layout work for all widths
Container queries (not media queries) so the same component reflows correctly in panel and popup
Single render layer — the panel and the popup are the same view tree, hydrated with different config. No code duplication, and behavior parity is automatic.

.image-card {
  container-type: inline-size;
}

@container (max-width: 200px) {
  .image-card .meta { display: none; }
}

@container (max-width: 280px) {
  .image-card { aspect-ratio: 1; }
}

What I'd do differently

Ship the MVP earlier. I sat on a working version for a month polishing edge cases nobody asked about.
Add telemetry from day one — opt-in, anonymous, but I have no idea which features users actually use. Adding it now feels invasive.
Write the test suite earlier. I have ~30% coverage. It's not a disaster, but every refactor is slower than it needs to be.

Try it

If you want to see all this in action:

Install: https://chromewebstore.google.com/detail/iecgnjidmogebokcfnejncgnelcepffo
Site: https://image-harvest.kyriewen.cn (full feature comparison + GIFs)
Github: https://github.com/zbw-zbw/image-harvest
Reviews (if it helps you): https://chromewebstore.google.com/detail/iecgnjidmogebokcfnejncgnelcepffo/reviews

Free tier handles most use. Pro adds multi-tab extract, similar-image detection, 4-engine reverse search, color extraction, and tagged collections. One-time payment option because I personally hate subscriptions for utilities.

If you've shipped a Chrome extension and have war stories about MV3, Shadow DOM, or the Side Panel API — drop them in the comments. Solo devs unite. 🙌