DEV Community: Muhaymin Bin Mehmood

Your Image CDN Picks the Format. Here's How to See What It Actually Sends

Muhaymin Bin Mehmood — Mon, 12 Oct 2026 10:52:27 +0000

Here is one image URL from a real Shopify store, requested three times. Same URL, same second, three different files:

https://jellinator.com/cdn/shop/files/ShotCups_100Pack.png?width=1200

  Chrome (AVIF+WebP)   image/webp     87 KB   Vary: Accept
  WebP only            image/webp     87 KB   Vary: Accept
  Old browser          image/png    1223 KB   Vary: Accept

The only thing that changed between the three requests is the Accept header. A browser that says it understands WebP gets an 87 KB file. A client that doesn't gets the original 1.2 MB PNG.

That is content negotiation, and most image CDNs do it now. It's great for visitors. It also means that "what format is this image?" has no single answer, and some tools will give you the wrong one.

The header that decides it

Every browser sends an Accept header with image requests. Current Chrome sends:

Accept: image/avif,image/webp,image/apng,image/*,*/*;q=0.8

A negotiating CDN reads that list and picks the best format it can produce. It then adds Vary: Accept to the response, which tells every cache in between: "this URL has more than one version, keyed by the Accept header".

If you see Vary: Accept on an image response, the server is negotiating. If you don't, you're getting the same file whatever you ask for.

Check it with curl

curl -I sends a HEAD request and prints the headers. Add the header a browser would send:

curl -sI -H "Accept: image/avif,image/webp,image/*,*/*;q=0.8" \
  "https://jellinator.com/cdn/shop/files/ShotCups_100Pack.png?width=1200" \
  | grep -iE "content-type|content-length|vary"

Then run it again without -H. curl's default is Accept: */*, which is exactly the "old browser" case above. If the two answers differ, your CDN negotiates.

A small script for a list of URLs

When you want to check a batch of images, this does the three requests for each URL and prints one line per client:

// check-formats.mjs: what format does each image URL send to different browsers?
// Usage: node check-formats.mjs <image-url> [more urls...]
const ACCEPTS = {
  "Chrome (AVIF+WebP)": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
  "WebP only": "image/webp,image/*,*/*;q=0.8",
  "Old browser": "image/*,*/*;q=0.8",
}

for (const url of process.argv.slice(2)) {
  console.log(`\n${url}`)
  for (const [label, accept] of Object.entries(ACCEPTS)) {
    const res = await fetch(url, { method: "HEAD", headers: { accept } })
    const type = res.headers.get("content-type")
    const size = res.headers.get("content-length")
    const vary = res.headers.get("vary") ?? "-"
    console.log(`  ${label.padEnd(20)} ${type?.padEnd(12)} ${size ? Math.round(size / 1024) + " KB" : "?"}  Vary: ${vary}`)
  }
}

It needs Node 18 or newer (for the built-in fetch). Some servers answer HEAD differently from GET; if a line looks odd, try the same URL with GET.

The size can change the format too

Run the same image at a smaller width and something else happens:

https://jellinator.com/cdn/shop/files/ShotCups_100Pack.png?width=300

  Chrome (AVIF+WebP)   image/avif     14 KB   Vary: Accept
  WebP only            image/webp     16 KB   Vary: Accept
  Old browser          image/png      98 KB   Vary: Accept

At 300px this CDN sent AVIF to Chrome. At 1200px it sent WebP, even though Chrome said it accepts AVIF.

We saw the same pattern across a larger sample. In a study of 199 Shopify product pages, 94% of image files came back as WebP or AVIF, and 97% of those responses carried Vary: Accept. But when we spot-checked the main product photo of 24 stores at 600px, 22 came back as WebP and none as AVIF. AVIF showed up on some small variants, and not consistently.

So "my CDN supports AVIF" and "my product photos are served as AVIF" are two different claims. Check the second one directly.

Why some audits get this wrong

Any tool that fetches your images without a browser-like Accept header sees the "old browser" version. For the image above, that's a 1.2 MB PNG instead of an 87 KB WebP, so the tool reports a problem your visitors never have.

When you read an image audit, check one thing: does it say which Accept header it used? If it doesn't, compare a couple of its numbers with the script above before you start re-exporting files.

The reverse mistake happens too. If you test only with Chrome DevTools, you see the best case. Visitors on old browsers, some email clients and some social link previews may get the original file.

Caching: don't break Vary

Negotiation only works if every cache between the CDN and the visitor respects Vary: Accept. If you put your own proxy or a second CDN in front of your images and it ignores Vary, the first visitor's format gets cached for everyone. An old client's PNG can then be served to every visitor, or an AVIF can reach a client that can't decode it.

If you add a layer in front of an image CDN, either pass Vary: Accept through and key the cache on it, or let the original CDN handle images directly.

A quick checklist

Request your main product or hero image with a browser Accept header. Note the Content-Type and size.
Request it again without one. If both match, the server doesn't negotiate, and the format you uploaded is the format everyone gets.
Look for Vary: Accept on negotiated responses.
Try more than one width. The format can change with size.
When an audit flags a heavy image, check which Accept header it sent before trusting the number.

If you'd rather scan a whole page than individual URLs, our website image auditor requests the page's images with a current browser's Accept header and shows the type and size it actually got.

This post was drafted with an AI assistant. Every command and output above was run against the live URLs shown, on 2026-10-12.

Shopify Product Images in 2026: Formats Are Mostly Solved. Layout and Alt Text Are Not.

Muhaymin Bin Mehmood — Mon, 12 Oct 2026 09:56:27 +0000

We checked one product page on each of 199 Shopify stores and 43 WooCommerce stores, sampled from the HTTP Archive crawl of September 2026. Here is what their images look like to a modern browser.

Key findings

On Shopify, 94% of product image files came back as WebP or AVIF. We asked for images the way a current browser does. AVIF showed up on 60% of pages (95% CI 53 to 66%).
WooCommerce is the opposite. 82% of image files on WooCommerce product pages came back as JPEG or PNG, and on 78% of pages the first-loaded image was JPEG or PNG (CI 63 to 88%, smaller sample of 43).
43% of Shopify product pages have at least one first-loaded image with no width or height attribute (CI 36 to 50%). That is a layout-shift risk unless the theme reserves the space in CSS.
1 in 5 Shopify product pages has a first-loaded image with no alt attribute at all (19.5%, CI 15 to 26%).
Heavy files are rare. The median image file on a Shopify product page is 42 KB. Only 3% of pages had a first-loaded image over 1 MB.

What we measured

For each store we picked one real product page and read its HTML the way a crawler sees it, without running JavaScript. For every image the HTML references, we asked the server for the file with the same Accept header a current Chrome sends (image/avif,image/webp,...), and recorded what came back: the format (from the Content-Type header) and the size (from Content-Length).

Two kinds of numbers appear below:

Per file: every image file the page references, including each size variant listed in srcset. Useful for "what format do servers send".
Per page: whether a page has at least one problem image. For layout, alt text and heavy files we only count first-loaded images: <img> elements with a src and no loading="lazy". These are the images a browser requests first, usually the main product photo.

What we did not measure: total page weight, which image a browser actually picks from a srcset, rendered image sizes, Largest Contentful Paint, images injected by JavaScript, and CSS background images. More on that in Limitations.

1. Image formats: Shopify has mostly solved this

Shopify, all image files (n = 2,764)	Share
WebP	79.0%
AVIF	15.2%
JPEG	4.5%
PNG	1.2%

That is 94% modern formats, and it does not look like 199 store owners each converted their images. 97% of those WebP and AVIF responses carried a Vary: Accept header, which means the server picked the format based on what the browser said it accepts. In other words, the platform's image CDN does this for every store, whether the owner uploaded a JPEG or not.

AVIF needs a caveat. In a follow-up spot check on 12 October 2026, we requested the main product image of 24 stores from the sample at 600px wide, telling the server we accept AVIF. 22 came back as WebP and 2 as JPEG; none as AVIF. AVIF only showed up on some small size variants, and not consistently. So read "AVIF on 60% of pages" as "at least one AVIF file somewhere on the page", not as stores choosing AVIF for their product photos.

The gap that is left is small but real: on 10.8% of Shopify pages (CI 7 to 16%) the first-loaded image still came back as JPEG or PNG. We stored only hashes of image URLs, so we cannot say where those files are hosted.

2. WooCommerce: still mostly JPEG and PNG

WooCommerce, all image files (n = 1,124)	Share
JPEG	52.8%
PNG	29.2%
WebP	16.5%
AVIF	1.2%

On 77.5% of WooCommerce pages (CI 63 to 88%) the first-loaded image was JPEG or PNG, and only 1 page in 43 served any AVIF. WordPress can serve WebP, but unless a plugin or CDN negotiates the format, the browser gets whatever file was uploaded.

This is a smaller sample (43 stores), so treat the exact percentages as rough. The direction is not in doubt.

3. Missing width and height

First-loaded `<img>` with no `width` or `height` attribute	Pages	95% CI
Shopify (195 pages with a first-loaded image)	42.6%	36 to 50%
WooCommerce (40 pages)	37.5%	24 to 53%

Without width and height, the browser does not know an image's shape until it loads, so text below it can jump. Some themes prevent that with CSS (aspect-ratio or a fixed-ratio wrapper), so a missing attribute is a risk, not proof of layout shift. We read HTML only, so we cannot tell which themes cover it in CSS.

If lazy-loaded images are included, the Shopify figure rises to 55%. We keep the narrower first-loaded number as the headline, because lazy-loading markup can include <source> elements that never carry these attributes.

4. Missing alt attributes

First-loaded `<img>` with no `alt` attribute	Pages	95% CI
Shopify	19.5%	15 to 26%
WooCommerce	12.5%	6 to 26%

We only counted images where the alt attribute is missing entirely. alt="" is the correct markup for a decorative image, so we counted it as present. Whether the existing alt text is any good is a separate question we did not try to answer.

5. File sizes

	Shopify	WooCommerce
Median image file	42 KB	22 KB
75th percentile	117 KB	59 KB
90th percentile	271 KB	134 KB
Files over 1 MB	1.2%	0.8%
Pages with a first-loaded image over 1 MB	3.1%	2.5%

These are sizes of individual files, including every size variant a page lists in srcset. A browser on a phone will not download the biggest variants, so do not add these up into a "page weight".

What to do with this

On Shopify, format is not your problem. Check your theme's main product image for width and height attributes, and make sure product photos have alt text. Both are template fixes, done once. Shopify's own theme guidance recommends the image_tag Liquid filter, which adds both size attributes for you.
On WooCommerce, serving WebP or AVIF is still the biggest easy win. A CDN or plugin that negotiates the format by Accept header fixes it for every image at once. Converting files before upload works too.
Anywhere, check what your own pages actually serve before you trust a score. You can scan a page with our Website Image Auditor, or look at the Content-Type of your main image in DevTools.

How the sample was built

Source: the HTTP Archive crawl of 1 September 2026 (mobile, root pages), filtered to e-commerce sites using the Wappalyzer "Ecommerce" category.
Draw: a deterministic, seeded draw per platform, with fixed quotas (200 Shopify, 100 WooCommerce, 100 other). Domains we had used while building the tool were excluded before the draw. Failed stores were replaced only from a pre-ordered reserve list.
Collected: 22 September 2026. One representative product page per store, chosen by a fixed ranking and confirmed to be a real product page (not a category or listing).
Not completed: the WooCommerce stratum stopped at 50 of 100 and the "other platforms" stratum was not collected. We report Shopify and WooCommerce separately and never combine them. Shopify is about 19% of e-commerce sites in the source crawl, so none of this describes "all online stores".
robots.txt: after the crawl we found that our collector's robots.txt parser was not fully standards-compliant. We re-checked every recoverable request against each site's robots.txt with a compliant parser and removed every store where the check failed or could not be completed, plus one site that turned out not to be a store. Details and counts are on the full study page.
Final sample: 199 Shopify and 43 WooCommerce product pages.

Limitations

Static HTML only. Images added by JavaScript and CSS background images are missing.
Referenced, not downloaded. We fetched every candidate in srcset; a real browser picks one. That is why we publish per-file and per-page-presence facts, not page totals.
First 40 image references per page. Long galleries are cut off, and later images are not measured.
One product page per store. Other templates on the same store can differ.
Sizes from headers. 2,790 of 2,863 Shopify sizes came from Content-Length on a HEAD request, the rest from a one-byte range request. Files with no size from either were left out, never counted as zero.
Confidence intervals are 95% Wilson intervals on page-level shares. File-level shares have no interval, because files from the same page are not independent.
robots.txt checks mostly used each site's file as of 12 October 2026, about three weeks after the crawl, because few archived copies existed for the crawl date.

Data

This is a cross-post. The original, with the full sample description, FAQ and how to cite it, is on batchset.com.

This report was drafted with an AI assistant. Every number was computed by scripts from the collected data, and each one is traceable to them.

Find Oversized Images on Any Page With One Console Snippet

Muhaymin Bin Mehmood — Mon, 12 Oct 2026 08:34:24 +0000

Lighthouse will tell you to "properly size images". It won't always tell you which image, by how much, or why it matters on a phone but not on your laptop.

You can get that answer yourself in about 40 lines of JavaScript, pasted into the DevTools console. No extension, no build step.

The idea is simple. For every image on the page, compare:

how many pixels the file has (naturalWidth)
how many pixels the screen can actually use for it (the rendered box, times devicePixelRatio)

If the file is three times wider than what the screen can use, the visitor downloaded and decoded roughly nine times the pixels they needed.

The snippet

(() => {
  const dpr = window.devicePixelRatio || 1;

  // Transfer sizes from Resource Timing, keyed by URL
  const bytesByUrl = new Map(
    performance.getEntriesByType("resource").map((e) => [e.name, e.encodedBodySize])
  );

  const rows = [];

  for (const img of document.images) {
    const src = img.currentSrc || img.src;
    if (!src || src.startsWith("data:") || /\.svg(\?|#|$)/i.test(src)) continue;

    const box = img.getBoundingClientRect();
    if (box.width === 0 || box.height === 0) continue; // hidden or display:none

    if (!img.complete || img.naturalWidth === 0) {
      rows.push({ image: src.split("/").pop().slice(0, 40), status: "not loaded yet (lazy?)" });
      continue;
    }

    // How much the browser scales the file to fill the box.
    // object-fit: cover fills the box and crops, so the larger scale wins.
    // Everything else we treat as contain-like (the smaller scale wins).
    const sx = box.width / img.naturalWidth;
    const sy = box.height / img.naturalHeight;
    const fit = getComputedStyle(img).objectFit;
    const scale = fit === "cover" ? Math.max(sx, sy) : Math.min(sx, sy);

    // Pixels the screen can actually use, at this device pixel ratio
    const neededW = Math.ceil(img.naturalWidth * scale * dpr);
    const extra = img.naturalWidth / neededW; // 1 = right-sized, 2 = twice as wide as needed

    const bytes = bytesByUrl.get(src);
    rows.push({
      image: src.split("/").pop().slice(0, 40),
      file: `${img.naturalWidth}x${img.naturalHeight}`,
      shown: `${Math.round(box.width)}x${Math.round(box.height)}`,
      needed: `${neededW}px wide @${dpr}x`,
      extra: +extra.toFixed(1),
      kb: bytes ? Math.round(bytes / 1024) : bytes === 0 ? "hidden" : "unknown",
    });
  }

  rows.sort((a, b) => (b.extra ?? 0) - (a.extra ?? 0));
  console.table(rows);
})();

Paste it into the console on any page and you get a table sorted by the worst offenders. extra is the column to read. Anything around 1 is fine. Anything above 2 is worth a look.

Three details that make the numbers honest

1. `currentSrc`, not `src`

If the image uses srcset, the browser picks one candidate and img.src still points at the fallback. currentSrc is the file that was actually downloaded, so that is the one to measure and the one to look up in Resource Timing.

2. `object-fit: cover` changes the math

I wrote about cover vs contain before, and it matters here too. A wide hero image inside a short, wide box with object-fit: cover gets scaled until it fills the box on both axes, and the overflow is cropped. So the scale is the larger of the two ratios, not the smaller one.

If you get this wrong, a cropped hero image looks massively oversized when it isn't, or the other way round.

3. Device pixel ratio

On a laptop at DPR 1, a 400px box needs a 400px file. On a phone at DPR 3, the same 400px box can use 1200px. An image that looks oversized on your desktop might be exactly right on a phone.

So run it at the sizes your visitors actually use. In DevTools, switch on device mode, pick a phone preset (that sets the DPR too), reload, then run the snippet again.

What `kb` can and can't tell you

The kb column comes from encodedBodySize in the Resource Timing API. Two catches:

Cross-origin images report 0 unless the image server sends a Timing-Allow-Origin header. The snippet shows those as hidden, not as 0 KB, because "the browser won't tell me" is not the same as "it's free". Many image CDNs do send the header, so you will often get real numbers.
The timing buffer has a limit. Browsers keep 250 resource entries by default. On a very heavy page, older entries may be missing and show up as unknown. Calling performance.setResourceTimingBufferSize(1000) early in the page load raises the limit, but that's for your own site, not for one you're inspecting.

Is the LCP image one of them?

An oversized thumbnail in the footer costs bandwidth. An oversized LCP image costs you the metric Google actually looks at. This one-liner tells you which element was the Largest Contentful Paint:

new PerformanceObserver((list) => {
  const lcp = list.getEntries().at(-1);
  console.log("LCP:", lcp.element, lcp.url, Math.round(lcp.startTime) + "ms");
}).observe({ type: "largest-contentful-paint", buffered: true });

buffered: true matters, because LCP has usually already happened by the time you open the console. Without it you get nothing.

If the URL it prints is near the top of the extra table, that is the first image to fix.

What I found when I tested it

I ran both snippets on the homepage of a large, well-known e-commerce brand, at a 765px-wide viewport and DPR 1:

42 images on the page.
The LCP element was the hero image: a 2560x1442 JPEG, about 559 KB, shown in a 765x235 box with object-fit: cover. That's 3.3x wider than the viewport could use, which works out to around 11 times the pixels.
Eight category tiles were 696x920 files shown at 184x239, so 3.8x wider than needed. Each was only 30 to 42 KB, so they hurt far less than the hero did.

That last point is why the kb column is there. extra tells you an image is too big. kb tells you whether it's worth your afternoon.

To be fair to that site, it was a narrow viewport at DPR 1, which is the worst case for this test. At full desktop width some of these would come out much closer to right-sized. That's exactly why you should test at more than one size.

Fixing what it finds

Serve smaller files where the box is small. srcset with width descriptors plus an honest sizes attribute lets the browser pick. If sizes is missing, the browser assumes 100vw and will happily pick the largest candidate for a thumbnail.
Don't fix the hero with lazy loading. The LCP image should load early: no loading="lazy", and consider fetchpriority="high".
Resize at the source when the CMS only stores one huge original. If you have a folder of product photos to bring down to a sane width, I built a free bulk image resizer that does it in the browser without uploading the files.

Limits of a console snippet

This only sees <img> elements. CSS background-image, images inside shadow DOM and canvas drawings aren't covered. It also only sees images that have loaded, so scroll the page first if it uses lazy loading. And carousels often clone slides, so the same file can appear several times in the table.

If you want this as a report instead of a console table, with transfer sizes measured from the server side and a list of fixes, I also built a website image auditor that scans a public page. The snippet above is the quick version you can run anywhere, including on staging and behind a login.

Either way, start with the LCP image. It's usually one file, and it's usually the one that matters.

This post was drafted with an AI assistant. Both snippets were run in a real browser before publishing.

A Watermark That Fits One Photo Can Fail a Whole Batch: Design Placement as a Workflow

Muhaymin Bin Mehmood — Sat, 10 Oct 2026 14:00:00 +0000

A watermark looks balanced on a landscape photo. Apply the same settings to a portrait photo and it covers the product. Apply them to a small thumbnail and the text becomes unreadable.

The problem is often the placement policy, not the logo.

A batch watermark feature needs more than a text field and an opacity slider. It needs a clear purpose, a coordinate system that survives different dimensions, and a review step that catches cases a shared setting cannot handle.

This article develops a reference workflow for visible watermarks. It is not a description of BatchSet's internal implementation, and it does not cover invisible watermarking or forensic identification.

1. Decide what the visible mark should do

“Add a watermark” can mean several different things:

Purpose	Likely design priority
Brand attribution	Readable identity without hiding the subject
A draft or proof label	An unmistakable status that survives a casual glance
A product-photo preview	A useful view of the item with a visible mark
Internal review identification	A clear reference label or version

Choose the purpose before tuning opacity.

A subtle corner logo and a repeated “DRAFT” pattern solve different communication problems. Neither should be described as making a file impossible to copy or alter.

For an attribution workflow, my acceptance criteria would include the logo remaining readable at the expected viewing size, important product details remaining visible, and the final crop retaining the mark.

That last condition is easy to miss. The un-cropped export may look correct even though the receiving interface crops the corner away.

2. Keep clean sources and labeled derivatives

A visible raster watermark becomes part of the exported pixels. Keep an untouched master so another destination can receive a clean image or a different mark.

A simple output naming scheme might distinguish:

product-042-master.png
product-042-preview-watermarked.jpg
product-042-approved-clean.jpg

These are workflow labels, not a recommendation to send all three files to every recipient.

Avoid reopening the watermarked JPEG, moving the mark, and encoding again as the normal editing path. Generate each derivative from the clean source and the approved watermark asset.

Keep the watermark asset version with your export settings. Otherwise, a repeated job can produce different branding even when the placement values are unchanged.

3. Choose coordinates relative to the output

Fixed pixels are easy to implement and easy to misuse.

A 200-pixel-wide logo occupies 20% of a 1000-pixel image and 5% of a 4000-pixel image. A 24-pixel inset similarly becomes much less visible on a larger export.

Relative coordinates make the policy easier to explain:

Mark width: a fraction of output width.
Edge inset: a fraction of the shorter output side.
Placement: a named anchor, such as bottom-right.
Shape: preserve the watermark asset's aspect ratio.

Relative placement is still a default, not an automatic understanding of the image's subject. A corner may contain a product label or a person's face. Include per-image review where that matters.

4. Calculate a bounded placement box

The following reference helper positions a logo at the bottom-right. It also limits height so a very tall watermark does not consume the entire image.

The numbers are illustrative defaults for a workflow, not universal design rules.

function watermarkBox({
  outputWidth,
  outputHeight,
  markWidth,
  markHeight,
  widthRatio = 0.18,
  insetRatio = 0.03,
  maxHeightRatio = 0.2,
}) {
  for (const value of [outputWidth, outputHeight, markWidth, markHeight]) {
    if (!Number.isFinite(value) || value <= 0) {
      throw new RangeError("Dimensions must be positive finite numbers");
    }
  }
  if (!Number.isFinite(widthRatio) || widthRatio <= 0 || widthRatio > 1 ||
      !Number.isFinite(maxHeightRatio) || maxHeightRatio <= 0 || maxHeightRatio > 1 ||
      !Number.isFinite(insetRatio) || insetRatio < 0 || insetRatio >= 0.5) {
    throw new RangeError("Invalid placement ratios");
  }

  const inset = Math.min(outputWidth, outputHeight) * insetRatio;
  const availableWidth = outputWidth - 2 * inset;
  const availableHeight = outputHeight - 2 * inset;
  const scale = Math.min(
    outputWidth * widthRatio / markWidth,
    outputHeight * maxHeightRatio / markHeight,
    availableWidth / markWidth,
    availableHeight / markHeight,
  );
  const width = markWidth * scale;
  const height = markHeight * scale;

  return {
    x: outputWidth - inset - width,
    y: outputHeight - inset - height,
    width,
    height,
  };
}

This function computes a box. It does not detect faces, evaluate contrast, enforce a minimum readable logo size, or predict a platform's crop.

It permits upscaling. For a raster logo, you may choose a separate policy that rejects excessive enlargement or uses a higher-resolution asset. A large blurry logo can satisfy the geometry and still fail the design.

5. Keep watermark opacity local to the watermark

Canvas drawing state can leak between operations if you change it and forget to restore it.

MDN documents globalAlpha, while save and restore provide a state stack.

For a context whose base image has already been drawn and whose transform is set to output-pixel coordinates, isolate temporary opacity like this:

function drawWatermark(ctx, decodedMark, box, opacity = 0.35) {
  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
    throw new RangeError("Opacity must be between 0 and 1");
  }

  ctx.save();
  try {
    ctx.globalCompositeOperation = "source-over";
    ctx.globalAlpha = opacity;
    ctx.drawImage(decodedMark, box.x, box.y, box.width, box.height);
  } finally {
    ctx.restore();
  }
}

The placement box should come from validated dimensions, such as the helper above. The drawing context must not have an unintended clip or transform; saving it does not clear an existing clip.

The mark's own alpha and the drawing opacity both affect the visible result. An asset whose pixels are already translucent can look fainter than an opaque asset at the same global opacity setting.

The finally block restores state even if drawing throws. It does not undo pixels already drawn or restore the original image. To retry with different settings, redraw the derivative from the clean source.

6. Place the mark after the intended crop and resize

For a typical destination-specific preview, I would use this order:

Decode the clean source and the watermark asset.
Calculate the intended crop, resize, and final canvas dimensions.
Fill the output canvas with the approved background if it must be opaque.
Draw the cropped and resized base image over that background.
Composite the watermark at the final output dimensions.
Encode and reopen the actual export for review.

The advantage of marking at final dimensions is that the selected relative size is visible in the export. Marking a very large source and then shrinking it can make the logo unnecessarily hard to evaluate.

If a receiving site crops after upload, your final dimensions are not the last transformation. Preview representative crops or choose an inset that accommodates the actual destination. There is no universal safe zone for every placement.

7. Test contrast on difficult images

One opacity value cannot make a white logo equally readable over every photograph.

Review light images, dark images, busy textures, and subjects that occupy the chosen corner. Include portrait, landscape, square, and unusually narrow exports.

Possible design responses include a darker mark variant, a light mark variant, a restrained backing plate, a different anchor, or an image-specific override. Each changes the appearance and should be deliberate.

Do not infer success from the full-size preview alone. A mark readable at 1600 pixels may vanish in a 160-pixel product thumbnail. Inspect both the intended display size and a larger detail view.

If the mark is a text label, use a font-loading policy that prevents export before the selected typeface is ready. Otherwise, a preview and download can disagree even when the text and coordinates match.

8. Make batch approval a visible step

For a proposed batch interface, I would separate applying a shared watermark from approving every result.

Show representative previews early, then let the user inspect individual outputs and move the mark where it obscures useful content. Record those overrides against stable item IDs rather than filenames alone.

An export summary should include output count, watermark asset or text version, shared placement settings, and which items used overrides. This makes a later rerun easier to reproduce.

Export failures still need explicit handling. A watermark preview is not evidence that the final encoder produced a downloadable file. Check the output format, bytes, and successful item count before offering the package.

Add the mark with a clear output policy

BatchSet's Bulk Image Converter provides browser-based image conversion and batch ZIP export. Its current advanced options list watermarking as a Pro feature; the ordinary free conversion workflow does not add a watermark.

When using a watermark workflow, keep your clean sources and inspect the final exported images at their destination size. Consistency means applying the same intention across a batch, with room for the images that need a different placement.

A ZIP Download Is Not Proof Your Batch Finished: Designing Reliable Browser Exports

Muhaymin Bin Mehmood — Fri, 09 Oct 2026 14:00:00 +0000

You select fifty product images, click Convert, and receive a ZIP.

The download looks successful. After extraction, there are only forty-eight images. Two inputs had the same basename, and the export code reused their output path.

Or perhaps two conversions failed and the interface quietly archived everything else.

These are different failures, but they create the same experience: a complete-looking delivery that does not account for the user's original request.

An archive is a container. It does not establish that every input produced a valid result, that filenames stayed distinct, or that the browser saved the download successfully.

Here is a reference design for a browser batch export whose result can be checked. The proposed manifest and code below are engineering examples, not claims about features currently implemented in BatchSet.

1. Separate conversion, packaging, and delivery

A single “Done” state often hides several stages:

Stage	Useful completion condition
Conversion	Every selected item has a settled success or failure status
Packaging	The expected successful outputs were added and archive generation resolved
Delivery	A download was initiated or an explicit file-writing operation completed
Recipient verification	The archive opens and its contents match expectations

For a conventional browser download, the application should not assume that triggering an anchor proves a file was saved. The user can cancel, a browser can block the action, or storage can become unavailable.

Use language that matches what the application knows. “Archive ready” and “Download started” are useful states even when the application cannot verify the final disk write.

For conversion progress, count settled items and show how many succeeded. If packaging then takes several seconds, label that stage instead of leaving the interface at a mysterious 100%.

2. Give each input a stable identity

Filenames are not unique identifiers.

These can all appear in one batch:

camera-a/product.jpg
camera-b/product.jpg
product.png

Converting each to product.webp creates a collision even if every conversion succeeds.

Assign an item ID and preserve the user's input order before starting asynchronous work. Store results against that identity, not whichever filename or completion index happens to be convenient.

A proposed result record might include:

{
  "id": "item-002",
  "inputIndex": 1,
  "inputName": "product.jpg",
  "status": "success",
  "outputName": "0002-product.webp",
  "outputBytes": 184230
}

The bytes are illustrative. In a real export, read them from the produced Blob.

Keeping identity separate from display naming also helps with retries. A replacement result can update the same item without accidentally counting it as another input.

3. Choose output names before generating the archive

Some archive APIs treat a name as a path. A slash can create directories; duplicate names can replace earlier entries. JSZip documents its entry behavior in the file API.

For a simple flat export, generate names yourself rather than accepting arbitrary paths from the input.

This example uses a unique input index, a conservative ASCII stem, and an extension selected from the known output MIME type:

function archiveImageName(inputName, inputIndex, outputType) {
  if (!Number.isSafeInteger(inputIndex) || inputIndex < 0) {
    throw new RangeError("Invalid input index");
  }
  const extensions = new Map([
    ["image/jpeg", "jpg"],
    ["image/png", "png"],
    ["image/webp", "webp"],
  ]);
  const extension = extensions.get(outputType);
  if (!extension) throw new Error("Unsupported output type");

  const leaf = String(inputName).split(/[\\/]/).pop();
  const stem = leaf.replace(/\.[^.]*$/, "")
    .normalize("NFKD")
    .replace(/[^a-zA-Z0-9_-]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 60) || "image";

  const prefix = String(inputIndex + 1).padStart(4, "0");
  return `${prefix}-${stem}.${extension}`;
}

This policy intentionally sacrifices some filename fidelity for predictability. The original name can remain in a separate manifest. Unique indices prevent collisions even when different names normalize to the same stem.

It is a naming policy for application-generated exports, not an archive-extraction security system. It does not prove compatibility with every filesystem or third-party uploader. Confirm your destination's naming rules.

Only use a verified output type. An extension derived from the requested format can mislabel an encoder fallback.

4. Decide whether partial export is allowed

There are two useful policies:

Complete batch required: block packaging until every item succeeds or the user resolves failures.
Partial export allowed: offer successful files with a clearly visible list of failures and a partial label.

Neither should be implicit.

For a product catalog, missing images may create broken listings. For an informal cleanup task, exporting the successful files and retrying the rest might save time.

If partial export is allowed, explain the count before download:

Partial export: 48 of 50 images succeeded. Two failed inputs are listed in the report.

Use actionable failure categories where possible: unsupported input, decoding failure, export failure, or cancellation. Avoid turning every exception into a generic “something went wrong.”

Do not mark a still-pending input as failed just to make the counts add up. Packaging should begin only after results have settled, or after cancellation has been handled according to an explicit policy.

5. Put accountability inside the package

A UI warning disappears when a ZIP is forwarded to another person. A small manifest can travel with the files.

For the proposed workflow, I would include:

Selected, successful, and failed item counts.
The output settings relevant to the transformation.
One record per selected input.
Each successful output's archive name and measured bytes.
A bounded, user-facing failure category for failed items.

Avoid raw stack traces, temporary object URLs, or source download URLs with tokens. The manifest is part of the deliverable and may be shared beyond the original user.

JSON is convenient for software that checks packages. A short human-readable summary can help recipients who do not use developer tools. Choose what the workflow needs rather than adding sensitive information merely because it is available.

Counts should reconcile: selected equals succeeded plus failed once all items are settled. The number of archived image entries should equal succeeded. Manifest and summary files are additional entries, so distinguish image count from total archive entry count.

6. Compression and packaging have separate costs

JPEG, PNG, and WebP already use compression. ZIP is useful for packaging them together, but another compression layer does not guarantee substantial savings.

For an image-heavy export, a sensible reference starting point is to store image entries without additional ZIP compression and then measure the trade-off on representative batches. Text manifests may compress well even when images do not.

JSZip's generation options describe archive output types and compression choices. Its limitations also explain that generateAsync retains the generated result in memory.

That means “the conversions finished” does not establish that packaging will fit within the browser's remaining memory. Completed output Blobs, decoded resources that were not released, and the archive result can overlap.

Treat large-batch packaging as its own resource decision. Release unnecessary previews, avoid base64 copies, consider smaller groups, and investigate a suitable streaming architecture where the expected workload justifies it.

An option named streamFiles is not, by itself, a promise that the final Blob is written directly to disk without accumulation. Read the complete library behavior and test the actual path you ship.

7. Freeze an export snapshot

If the user edits output settings while packaging runs, which settings should the archive use?

My proposed rule is to package an immutable snapshot of settled results. Changes after that snapshot start a new export rather than mutating the current one halfway through.

This prevents a package containing early files from one format and late files from another unless mixed output is an explicit feature.

Retain the snapshot identity for retries of packaging. A ZIP generation failure should not require recompressing every image if valid outputs are still available. Conversely, do not reuse stale outputs after settings change.

Allow a user to dismiss progress without implying that a running operation has stopped. Cancellation behavior must match the library and worker capabilities actually available.

8. Verify the artifact, not only the callback

For release testing, use batches that include duplicate basenames, mixed extensions, non-ASCII names, one corrupt input, and an intentionally oversized workload.

Then check:

The chosen complete-or-partial policy is visible.
Every selected item is accounted for.
Output names are distinct and use correct extensions.
The archive extracts in representative recipient software.
Extracted files decode and have expected dimensions.
Manifest byte counts match extracted file sizes.
Retrying packaging does not create missing or duplicated items.

A hash can additionally check that extracted bytes match the intended bytes. It does not establish that an image looks correct or that the image belongs to the right product. Those need other checks.

Use the ZIP as a delivery container

BatchSet's Bulk Image Converter offers browser-based conversion of mixed image inputs and a ZIP download.

When preparing a batch for handoff, check its successful count and inspect the extracted results before replacing your originals. A convenient container becomes a reliable delivery only when its contents match the work you intended to finish.

Your Transparent PNG Needs a Background Before It Becomes a JPEG

Muhaymin Bin Mehmood — Thu, 08 Oct 2026 14:00:00 +0000

A product cutout looks perfect over a checkerboard preview. After conversion to JPEG, the surrounding area becomes a solid rectangle. On a dark website, that rectangle is suddenly obvious.

The export may be technically valid. The workflow still failed to explain an important decision: which background replaces the transparent parts of the image?

Transparency is part of the image's composition, not a cosmetic detail that can be ignored when choosing a format. Converting to JPEG means committing to an opaque result.

Here is a practical way to make that commitment deliberate, whether you are building an image tool or preparing assets for a storefront.

1. A checkerboard is usually a preview background

A transparency preview often places the image over alternating gray squares. Those squares help you see where the image has no opaque content. They are not necessarily stored in the image itself.

That distinction matters when someone asks to “keep the checkerboard” or assumes the file already has a gray background.

In a raster image with an alpha channel, pixels can be opaque, transparent, or partly transparent. Partly transparent pixels are common around anti-aliased edges and soft shadows.

MDN's image-format guide documents transparency support in formats such as PNG and WebP. Ordinary JPEG does not preserve an alpha channel.

Changing a filename from .png to .jpg does not perform this conversion. An actual encoder must create JPEG bytes, and the resulting image must have an opaque appearance.

2. Select the destination before selecting the background

Different destinations can require different decisions:

Destination	Useful starting decision	What to inspect
A product card on a white page	Flatten onto the agreed white	Product edges and light shadows
A colored campaign banner	Flatten onto the banner's exact background	Seams around the image rectangle
A logo used across light and dark themes	Preserve transparency if supported	Contrast in both themes
A receiving system that only accepts JPEG	Choose and preview an opaque matte	Final uploaded appearance

White is a common background, but it is still a choice. If the page uses a warm off-white and the image is flattened onto pure white, the rectangular boundary may remain visible.

For assets intended for many backgrounds, retaining transparency is often more flexible. Confirm that the recipient accepts the format and that the rest of the workflow preserves alpha.

For a known opaque destination, flattening can be appropriate. The question is whether the chosen matte matches the intended use, rather than whether transparent pixels can somehow survive a JPEG export.

3. Flattening is a composition operation

For a partly transparent source pixel over an opaque background, a simplified channel calculation is:

result = alpha × foreground + (1 − alpha) × background

Suppose alpha is 0.5, the foreground channel is 40, and the background channel is 240. The simplified result is 140.

That example explains why changing the background also changes the appearance of edge pixels. It is not a specification of every color-managed rendering pipeline; color spaces and implementation details matter in precise work.

A soft shadow is similarly blended into the chosen background. After flattening, the exported pixels do not retain the original alpha values needed to recomposite that shadow over a different color.

The opaque result should therefore be treated as a destination-specific derivative. Keep the transparent original if you may need another version later.

4. Make the drawing order explicit

For a simple canvas export, the sequence is straightforward:

Create an output canvas at the desired dimensions.
Fill it with the chosen opaque background.
Draw the decoded source over that fill.
Encode as JPEG.
Check that encoding produced a nonempty JPEG Blob.

Here is a narrow reference implementation. It expects a valid decoded ImageBitmap, uses its current dimensions, and allows only an opaque six-digit hex background color.

async function flattenBitmapToJPEG(bitmap, {
  background = "#ffffff",
  quality = 0.85,
} = {}) {
  if (!/^#[0-9a-f]{6}$/i.test(background)) {
    throw new TypeError("Use an opaque #RRGGBB background");
  }
  if (!Number.isFinite(quality) || quality < 0 || quality > 1) {
    throw new RangeError("Quality must be between 0 and 1");
  }
  if (!Number.isInteger(bitmap.width) || bitmap.width <= 0 ||
      !Number.isInteger(bitmap.height) || bitmap.height <= 0) {
    throw new RangeError("Bitmap dimensions must be positive integers");
  }

  const canvas = document.createElement("canvas");
  canvas.width = bitmap.width;
  canvas.height = bitmap.height;
  const ctx = canvas.getContext("2d");
  if (!ctx) throw new Error("Canvas 2D is unavailable");

  ctx.fillStyle = background;
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.drawImage(bitmap, 0, 0);

  const blob = await new Promise((resolve, reject) => {
    try {
      canvas.toBlob(result => {
        if (!result || result.size === 0) {
          reject(new Error("JPEG export failed"));
        } else {
          resolve(result);
        }
      }, "image/jpeg", quality);
    } catch (error) {
      reject(error);
    }
  });

  if (blob.type !== "image/jpeg") {
    throw new Error(`Unexpected export type: ${blob.type}`);
  }
  return blob;
}

The relevant browser APIs are documented in fillRect, drawImage, and toBlob.

This example is not BatchSet's implementation. It does not handle decoding, resampling, animation, orientation policy, wide-gamut fidelity, or resource limits. The caller owns the bitmap and should close it when no longer needed.

Creating a new canvas also avoids inheriting an earlier drawing operation's transform or opacity. In a reused canvas pipeline, those states must be controlled deliberately.

5. Do not let global opacity affect the base image

A tool that draws several layers can accidentally carry state from one operation into the next.

Imagine applying opacity 0.3 to a watermark, then drawing the next product image without restoring the context. Its transparent edge and even its opaque center can blend differently than intended.

Treat each drawing stage as a defined operation with an expected state. Where a shared context is necessary, save the state before temporary changes and restore it afterward. The next layer should not depend on whether a previous image happened to use a watermark.

This is also why a preview must use the same composition policy as export. A preview that draws on white while export uses another matte creates an avoidable mismatch.

6. A halo can already exist in the source

Flattening does not guarantee perfect edges.

A cutout may contain partly transparent boundary pixels whose color was influenced by a previous background. It can look acceptable on white and show a light fringe on dark green.

If a fringe exists, distinguish its likely cause before changing settings:

Does it appear when the original transparent file is shown over the destination color?
Does it appear only after resizing?
Does it become visible only after lossy encoding?
Is the source itself a screenshot of a transparency preview?

Each points to a different stage. Increasing JPEG quality will not reliably repair an incorrectly matted source edge. Changing the background will not restore detail that was already removed from a poor cutout.

Review the original alpha-bearing file on several solid backgrounds. If the problem is present before export, return to the cutout or editing stage rather than repeatedly re-encoding the derivative.

7. Keep the preview and the downloadable file comparable

For an export interface, I would show an explicit background control and preview the opaque result before download.

The preview should explain whether it is showing original transparency or the proposed JPEG composite. A checkerboard can be useful for source inspection but misleading as the only preview of an opaque export.

After encoding, reopen the actual output for the final preview where practical. That catches differences introduced by the encoder rather than showing only the uncompressed canvas.

Inspect fine edges, semi-transparent shadows, small text, and the intended page background. For batch work, include representative images with both bright and dark subjects instead of checking only one easy example.

Keep source filenames and derivatives distinct. Naming a white-matted JPEG as though it were the reusable transparent master makes future editing unnecessarily confusing.

Export a deliberate background

BatchSet's PNG to JPG converter processes conversion in the browser and flattens transparent areas onto white. That is a concrete output policy to consider before choosing the tool for a destination with another background.

If you need transparency, retain an alpha-capable output such as PNG or an appropriate WebP workflow. If you need JPEG, treat the background as part of the exported image and verify the final composition where it will be used.

Quality 80 Is Not a File-Size Promise: Build Image Compression Around Measured Byte Budgets

Muhaymin Bin Mehmood — Wed, 07 Oct 2026 14:00:00 +0000

Two product photos go through the same export settings: WebP, the same dimensions, quality 80.

One fits comfortably inside an upload limit. The other does not.

That result is not necessarily a broken encoder. A quality setting is an input to compression, while file size is an output you measure afterward. Image content matters, too.

This becomes a product problem when an interface turns “quality 80” into a promise that every file will be under 200 KB. The user does not care which parameter the encoder received. They care whether the exported file works in the receiving system and still looks acceptable.

Here is a reference workflow for treating those as two separate requirements. The examples are proposed engineering patterns, not a description of BatchSet's internal compression algorithm.

1. Give every number a specific meaning

A compression interface can expose several numbers that look related but measure different things:

Number	What it describes	What it does not establish
Quality setting	A control passed to a particular encoder	A universal visual quality percentage
Output bytes	The encoded file's measured size	Whether fine text remains readable
Pixel dimensions	The output raster's width and height	A guaranteed byte count
Percentage saved	Change relative to one input file	Page-load time or upload acceptance

“80% quality” does not mean that 80% of the original information is preserved. Nor should you expect quality 0.8 in two formats or two different encoders to produce equivalent images.

MDN's canvas export reference describes a quality argument for formats that support lossy encoding. It is an encoder option, not a target-size argument.

For a byte-limited upload, the final decision must use the encoded output. A preview or an estimate cannot replace that measurement.

2. Write down the acceptance criteria first

Suppose a team agrees on this illustrative requirement:

The receiving system accepts WebP.
Every delivered file must be at most 200,000 bytes.
Product labels must remain readable at the intended display size.
The first pass keeps approved dimensions unchanged.
If quality adjustments cannot satisfy both conditions, request review.

These are project choices, not universal web standards.

Also settle whether “200 KB” means 200,000 bytes or 200 × 1024 bytes. The difference can determine whether a file just over the boundary is accepted. Internally, keep the limit as an integer byte count and make the displayed unit clear.

An uploader might have other requirements: allowed MIME types, minimum dimensions, or a server that recompresses files after upload. A local byte check addresses only the local file-size condition.

3. Measure a bounded set of candidates

I would begin with a small, explicit set of quality candidates rather than an unbounded loop that keeps reducing quality until something fits.

The following function accepts an injected encoder. It tries higher settings first and returns the first candidate inside the budget. If none fits, it returns the smallest tested candidate with an explicit failure status.

async function chooseWithinBudget({
  encode,
  expectedType,
  maxBytes,
  qualities = [0.9, 0.8, 0.7, 0.6, 0.5],
}) {
  if (typeof encode !== "function" || !expectedType) {
    throw new TypeError("An encoder and expected MIME type are required");
  }
  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
    throw new RangeError("maxBytes must be a positive safe integer");
  }
  if (!qualities.length || qualities.some(q =>
    !Number.isFinite(q) || q < 0 || q > 1
  )) {
    throw new RangeError("Invalid quality candidates");
  }

  const candidates = [...new Set(qualities)].sort((a, b) => b - a);
  let smallest;

  for (const quality of candidates) {
    const blob = await encode(quality);
    if (!(blob instanceof Blob) || blob.size === 0) {
      throw new Error("Encoder returned no usable output");
    }
    if (blob.type !== expectedType) {
      throw new Error(`Unexpected export type: ${blob.type}`);
    }
    const result = { blob, quality, bytes: blob.size };
    if (!smallest || result.bytes < smallest.bytes) smallest = result;
    if (result.bytes <= maxBytes) {
      return { ...result, metTarget: true };
    }
  }

  return { ...smallest, metTarget: false };
}

This is a bounded search over selected settings. It does not find the best possible image among all settings, and a higher encoder setting does not prove better perceptual quality for every use case.

It also does not assume that every successive output must be smaller. An unexpected increase is still a real measurement, so the smallest tested candidate is tracked separately.

The application must supply an encoder, handle its errors, and perform visual review. Cancellation, decoding, resizing, and memory management are outside this small function.

4. Verify the output format before assigning a filename

An application might request WebP and then name the result product.webp. That filename is only correct if the export actually produced WebP.

Canvas can fall back to PNG when a requested encoding is unsupported. Handle that before putting the result into an archive or sending it to a destination that only accepts certain formats.

For a canvas integration, wrap its callback-based export and reject a null result. Then verify the returned Blob's type against the requested format, as the reference function does.

Checking the type reported by your own browser encoder is a useful integration check. It is not a general-purpose file validator for arbitrary untrusted uploads. Those are different boundaries.

Similarly, treat an encoding error as an error. Replacing it with an empty Blob can make the byte budget look satisfied while delivering an unusable image.

5. Use a quality floor that matches the image's purpose

A file can meet its byte budget and still fail its job.

For a photograph, I might inspect fabric texture, hair, gradients, and edges. For a screenshot, I would inspect small text and thin interface lines. For a product label, the identifying text may be the most valuable part of the image.

That suggests a review sequence:

Compare the original and candidate at the intended display size.
Inspect important details at a larger zoom.
Check the output on representative destination backgrounds.
Reject candidates that lose information the recipient needs.

The “quality floor” is a decision about acceptable output, not merely a minimum slider value. A numerical floor can limit the search, but it still needs validation against representative images.

Automated similarity metrics can help flag changes in a controlled pipeline. They do not know that a tiny serial number matters more than a large blank background unless your evaluation makes that distinction.

6. Change dimensions deliberately when quality alone is insufficient

If no acceptable candidate fits, a second pass can consider smaller dimensions. Do not reduce dimensions silently and then show only a successful byte count.

For example, a proposed workflow might offer:

No tested quality setting met the limit at the current dimensions. Try a smaller export, choose another accepted format, or keep the original for manual review.

Reducing both width and height to 75% produces 56.25% as many pixels. That arithmetic does not predict the encoded file size: compression still depends on image content and representation.

Resize from the original working source for each candidate. Repeatedly decoding and recompressing an already lossy candidate makes it harder to compare alternatives fairly.

Keep any minimum dimensions required by the recipient. A 40 KB thumbnail is not a successful replacement for a full-size image someone needs to zoom into.

7. Make the report explain the result

A useful export report would show the selected format, dimensions, measured bytes, tested setting, and whether the target was met.

Use literal statuses such as:

Within byte limit — visual review required.
Above byte limit — smallest tested candidate retained.
Encoding failed — no output produced.

These distinguish a measurement from a judgment and a failed operation from an oversized but valid file.

For batch statistics, add input bytes and output bytes first, then compute the total change. Averaging each file's percentage saved gives every tiny icon the same weight as a large photograph and can tell a different story.

Also show increases honestly. If a particular file grew, do not clamp its “saved” percentage to zero or quietly drop it from the report.

Start with measured compression

BatchSet's Bulk Image Compressor offers browser-based batch compression, quality controls, before-and-after sizes, and ZIP export. The free workflow uses a quality slider; target file-size mode is a Pro option.

Use the exported bytes and a visual check to judge the result. A quality setting is a starting point. A usable file inside the receiving system's actual limit is the outcome to verify.

A Favicon Is a Tiny Deployment: Asset Design, HTML, Manifests, and Cache Debugging

Muhaymin Bin Mehmood — Tue, 06 Oct 2026 14:00:00 +0000

You replace the logo, deploy the site, and still see the old favicon in a browser tab.

You regenerate the file. The old icon remains. Then someone installs the site on their phone and gets a different icon again.

The problem may have nothing to do with the logo itself. A site can expose multiple icon files, multiple declarations, cached responses, and a manifest used by installation surfaces.

A favicon is a small asset with a surprisingly complete delivery path: design, encoding, HTML discovery, fetching, caching, and display.

Here is a framework-neutral workflow for treating it like a real deployment.

1. Design for the smallest use first

A wordmark that looks excellent at 800 pixels wide may become unreadable in a 16-pixel tab icon.

Do not start by generating every output size from the full logo and assume the design problem is solved.

Choose a recognizable mark: a symbol, a simplified initial, or another compact part of the identity. Look at it at actual small sizes. Thin strokes, tiny gaps, and decorative details can disappear.

My suggested acceptance questions are:

Is the mark recognizable at 16 and 32 pixels?
Does it have enough internal space after resizing?
Is it distinguishable on light and dark surrounding UI?
Is it clearly related to the product's identity?

A larger source improves the available input quality. It does not guarantee that every small derivative has a useful silhouette.

For a new product, review the tiny icon before committing to a final export package. It is easier to simplify the source once than to debug ten blurry outputs later.

2. Separate icon purposes

Different browser and platform surfaces can use different declarations.

Artifact	Intended role in this reference package
`favicon.ico`	Conventional browser icon fallback with multiple sizes
Small PNG icons	Explicit raster tab-icon options
`apple-touch-icon.png`	Apple touch-icon declaration
Larger manifest icons	App-installation surfaces that use the manifest
`site.webmanifest`	Metadata referencing the manifest icon files

An SVG tab icon can be another option when it fits the target browser support and your artwork. It does not eliminate the need to verify other surfaces.

The HTML link element supplies resource relationships. Its sizes and type metadata help describe icon candidates; listing a size does not resize an incorrectly generated file.

For app icons, the manifest icons reference describes the distinct metadata used there.

3. Use explicit paths and real dimensions

Here is a reference HTML declaration set. Adjust the paths to the files you actually ship:

<link rel="icon" href="/icons/favicon.ico" type="image/x-icon">
<link rel="icon" href="/icons/favicon-32x32.png"
      type="image/png" sizes="32x32">
<link rel="icon" href="/icons/favicon-16x16.png"
      type="image/png" sizes="16x16">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png"
      sizes="180x180">
<link rel="manifest" href="/site.webmanifest">

This is a template, not a universal platform checklist. Frameworks may generate their own declarations from filesystem conventions or metadata APIs.

Inspect the resulting HTML rather than adding duplicate tags blindly. An inherited layout, a CMS theme, and a plugin can each contribute icon declarations.

If the application is served below a path such as /portal/, a root-relative /icons/ URL points to the origin root. Decide whether that is where your assets live. Do not assume your application base path is automatically prefixed.

The MDN rel reference is useful when checking the relationships you declare.

4. Treat the manifest as another linked document

A minimal example might contain:

{
  "name": "Example Workspace",
  "short_name": "Workspace",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    {
      "src": "/icons/app-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/app-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    }
  ]
}

Those filenames are illustrative. Verify they exist and have the declared dimensions.

A manifest is not an installability guarantee. Requirements and behavior depend on the platform and the rest of the application.

Also check where relative paths resolve. A relative icon path is resolved from the manifest URL, not simply from whichever application screen you happened to be viewing.

For a subpath deployment, inspect start_url, scope, and icon locations together. A valid JSON file can still point users or fetches to the wrong place.

5. Do not label an ordinary icon maskable without checking it

Some app surfaces apply shape masks. An icon designed to reach the corners of its square may lose important content when cropped.

A purpose value of maskable is a promise about how the artwork should survive those treatments. It is not a request for the browser to repair the design.

If you need maskable support, create and test artwork for it, and declare that specific file appropriately. Keep critical content within the required safe region and check previews using the platform's tooling.

Do not claim a package provides maskable artwork merely because it includes a 512-pixel PNG. Size and maskability are different properties.

This is particularly relevant for logos whose essential letter or symbol sits near an edge. Test the silhouette after the mask, not only before it.

6. Debug the fetched asset before blaming the cache

A filename ending in .png can still return an HTML error page. A single-page application may answer an unknown asset route with its application shell.

For each declared icon, verify:

The requested URL is correct.
The response succeeds.
The response content type matches an actual image.
The decoded dimensions match the declaration.
The response body is the new artwork.

A 200 status alone is insufficient.

In a browser console, this helper checks a raster asset's actual decoded dimensions:

async function inspectRasterIcon(url) {
  const response = await fetch(url, { cache: "no-store" });
  if (!response.ok) {
    throw new Error(`Icon request failed: ${response.status}`);
  }

  const contentType = response.headers.get("content-type") || "";
  if (!contentType.toLowerCase().startsWith("image/")) {
    throw new Error(`Expected image response, got ${contentType}`);
  }

  const bitmap = await createImageBitmap(await response.blob());
  try {
    return { width: bitmap.width, height: bitmap.height, contentType };
  } finally {
    bitmap.close();
  }
}

Use it for a same-origin PNG or another supported raster input. It is not an ICO-frame inspector, an SVG renderer, or a guarantee that browser tab selection uses that particular candidate. Cross-origin requests also require appropriate CORS access.

7. Make updates observable

If the server delivers the new bytes but the tab still shows the old icon, separate the possible layers: HTTP cache, service-worker cache, browser icon storage, an already-installed app icon, and stale HTML declarations.

A versioned asset name such as favicon-32x32-v2.png can make an updated candidate easier to identify. Update the declaration and ship the new file together.

Versioning is not permission to delete every previous asset immediately. Cached HTML or an older app installation may still refer to it.

For a simple release, I would:

Deploy new versioned icon files.
Update HTML and manifest references.
Check the served page and manifest.
Inspect service-worker behavior if present.
Test a fresh browser context and a new installation separately.

Avoid treating one hard reload as proof that every installation surface has updated. An icon attached to a saved shortcut can have its own lifecycle.

8. Keep a small release checklist

Check	Evidence
Small-size readability	Actual-size 16 and 32 pixel previews
HTML declarations	Rendered document points to intended files
Asset delivery	Correct status, type, bytes, and dimensions
Manifest	Valid JSON with working icon URLs
Deployment paths	Correct under the production base path
Light and dark UI	Recognizable mark on target surfaces
Installation	Real device or supported platform test
Update	New references visible after deployment

This is a narrow icon-delivery checklist. It does not replace testing the rest of a PWA or auditing the security of SVG input in a generator.

The aim is to leave no mystery about which file was generated, which file was fetched, and which surface was inspected.

Generate the package, then verify the deployment

BatchSet's Favicon Generator generates an ICO, PNG sizes, an Apple touch icon, larger app icons, and a web manifest locally in your browser.

Use a simple square brand mark, download the package, and adapt the provided declarations to your actual deployment paths. Treat generated files as a starting package, not proof that every browser or installation surface is already configured.

A tiny icon deserves a small, deliberate deployment check. That is usually faster than repeatedly regenerating the logo while the wrong file keeps being served.

Combining Images into a PDF Does Not Make Them Searchable: A Practical Browser Export Workflow

Muhaymin Bin Mehmood — Mon, 05 Oct 2026 14:00:00 +0000

You photograph ten receipts, combine them into a PDF, and send the result to a colleague.

The file opens. Every receipt is visible. Then your colleague searches for a supplier name and finds nothing.

Nothing necessarily went wrong with the conversion. The PDF may simply contain images of text rather than actual text.

An image-to-PDF tool packages visual pages. Searchability, semantic structure, and accessibility are separate capabilities.

That distinction matters when you build exports for receipts, screenshots, catalogs, portfolios, and administrative documents. A successful download should not create expectations the file cannot meet.

1. Define the output before implementing the converter

Start by deciding what the recipient needs.

Requirement	Image-only PDF can provide it?	Additional work to consider
View several images in one file	Yes	Page order and readable layout
Print a visual packet	Yes	Page size, margins, and effective resolution
Search text photographed on the pages	Not by embedding images alone	OCR and verified text output
Copy text from a receipt photo	Not by embedding images alone	A usable text layer
Navigate a structured document	Not automatically	Structure, tags, reading order, and testing

W3C's PDF OCR technique addresses adding actual text to scanned documents. OCR can support search and reading, but recognized text still needs review, and OCR alone does not establish complete accessibility.

For an expense packet, images may be sufficient. For a document someone must read with assistive technology, a different authoring workflow may be necessary.

Make that distinction visible before export, not after the user has uploaded a finished document elsewhere.

2. Page order is part of the data

File-selection order, filename order, and the intended document order are not always the same.

Consider:

receipt-1.jpg
receipt-10.jpg
receipt-2.jpg

Plain lexical sorting places receipt-10 before receipt-2. Numeric-aware filename sorting can help, but it still cannot know the intended chronology when names are inconsistent.

For a proposed interface, I would show numbered previews before export and allow explicit reordering. Keep that order in a stable array instead of reconstructing it from whichever asynchronous conversion finishes first.

const documentPages = [
  { id: "receipt-a", file: firstFile },
  { id: "receipt-b", file: secondFile },
];

// Export this array in order; do not sort by completion time.

If one input fails, tell the user which page is missing. Do not quietly produce a nine-page document that looks like a complete ten-page packet.

3. Fit the image without changing its proportions

A landscape screenshot should not be stretched to fill a portrait page. A tall receipt should not be cropped just to avoid whitespace.

For a reference layout, fit the full image inside a page box while preserving its aspect ratio. PDF coordinates are commonly expressed in points; one point is 1/72 inch.

function fitImageToPage({
  imageWidth,
  imageHeight,
  pageWidth,
  pageHeight,
  margin = 24,
}) {
  for (const value of [imageWidth, imageHeight, pageWidth, pageHeight]) {
    if (!Number.isFinite(value) || value <= 0) {
      throw new RangeError("Dimensions must be positive finite numbers");
    }
  }
  if (!Number.isFinite(margin) || margin < 0) {
    throw new RangeError("Invalid margin");
  }

  const availableWidth = pageWidth - 2 * margin;
  const availableHeight = pageHeight - 2 * margin;
  if (availableWidth <= 0 || availableHeight <= 0) {
    throw new RangeError("Margins leave no drawing area");
  }

  const scale = Math.min(
    availableWidth / imageWidth,
    availableHeight / imageHeight,
  );
  const width = imageWidth * scale;
  const height = imageHeight * scale;

  return {
    width,
    height,
    x: (pageWidth - width) / 2,
    y: (pageHeight - height) / 2,
  };
}

This computes placement. It does not resample or improve the source image.

For unusually tall receipts, you might offer a custom-height page or a deliberate split across multiple pages. Explain the option. Cropping off a total is not a formatting improvement.

4. Embedding and re-encoding are different choices

Some PDF libraries can embed JPEG or PNG bytes directly. Others use a canvas-based path that decodes the source and creates a new encoded image first.

Re-encoding can change quality and file size. Direct embedding avoids that particular conversion step, but does not solve layout, orientation, or every compatibility issue.

The PDF-LIB API reference documents image embedding and document serialization. Here is a deliberately narrow reference example using that library as an injected dependency:

async function makeImagePDF(files, PDFDocument) {
  const document = await PDFDocument.create();

  for (const file of files) {
    const bytes = await file.arrayBuffer();
    let image;

    if (file.type === "image/jpeg") {
      image = await document.embedJpg(bytes);
    } else if (file.type === "image/png") {
      image = await document.embedPng(bytes);
    } else {
      throw new Error(`Unsupported input in this example: ${file.name}`);
    }

    const page = document.addPage([595.28, 841.89]);
    const placement = fitImageToPage({
      imageWidth: image.width,
      imageHeight: image.height,
      pageWidth: page.getWidth(),
      pageHeight: page.getHeight(),
    });
    page.drawImage(image, placement);
  }

  return document.save();
}

The calling application supplies PDFDocument from its installed pdf-lib dependency and uses the layout helper above. This is not BatchSet's implementation.

The example supports only JPEG and PNG, trusts file MIME labels as routing hints, and aborts on the first error. It does not normalize orientation, accept WebP, run OCR, add document tags, or apply production resource limits. Real decoding must validate bytes rather than treating a MIME label as proof of the file's format.

WebP input requires an appropriate conversion path before using these embedding methods. Do not assume every image format accepted by the browser is directly embeddable by your PDF library.

5. Judge resolution at the final placed size

A 1200-pixel-wide image printed six inches wide has an effective resolution of 200 pixels per inch:

1200 pixels / 6 inches = 200 pixels per inch

That is an illustrative calculation, not a guarantee of readable receipt text. Source sharpness, camera focus, contrast, compression, and the actual printer still matter.

Changing a DPI metadata field does not manufacture missing detail. Neither does placing a blurry photo into a higher-resolution canvas.

Inspect the smallest relevant text at the intended print size. For a screenshot packet, that may be an error message. For a receipt, it may be a tax identifier or total. If those details fail, a visually pleasant thumbnail is not enough.

6. A PDF wrapper is not a compression guarantee

The PDF must store image content and document structures. It can be larger than the source images, depending on representation and overhead.

My suggested export report includes:

Input image count and actual output page count.
Total input encoded bytes.
Final PDF bytes.
Any images resized or re-encoded.
A list of failures or omissions.

If size reduction is required, make it a separate option and compare the actual output. Some screenshots and small images become larger when re-encoded.

Avoid blanket “compress every page to JPEG” behavior. Text screenshots, line art, transparent graphics, and photographs can have different needs. Review representative pages before applying one quality setting to the whole packet.

7. Browser-based does not mean unlimited

Even processing one page at a time, the PDF document object may retain embedded resources until serialization. Generating the final byte array can introduce another memory peak.

For large packets, expose a realistic batch limit, provide progress, and support cancellation where the chosen library permits it. If an operation has no abort interface, explain that cancellation may stop the next page rather than instantly interrupt the current one.

Keep originals available until the user has inspected the final file. Do not call a packet “complete” before export and verification finish.

Local processing can keep source files away from a conversion server, but it does not prevent the user from later uploading the result to an email or document service. Privacy language should describe the actual conversion stage.

8. Verify what the recipient will receive

For a release or an important packet, my checklist is:

Open the exported PDF in more than one viewer.
Confirm page count and intended order.
Check orientation, margins, and uncropped edges.
Zoom into small text and review a print proof if printing matters.
Search a known word to determine whether a text layer exists.
Compare final bytes with any receiving system's size limit.
Use an appropriate accessibility workflow if that is a requirement.

Searchability testing should include checking OCR accuracy where OCR was applied. Finding one word is not evidence that every page's text is correct.

Combine the pages with clear expectations

BatchSet's Image to PDF tool combines JPG, PNG, and WebP images into a PDF in the browser, with page-size and ordering options.

Use it when you need a visual packet in one file. Do not assume image conversion adds OCR, semantic tags, or an accessibility guarantee. Verify the exported pages, and choose a text-aware document workflow when the recipient needs more than pictures of words.

An Alt Attribute Is Not an Accessibility Strategy: Write Image Alternatives That Match the Context

Muhaymin Bin Mehmood — Sun, 04 Oct 2026 14:00:00 +0000

An automated check finds an image without an alt attribute. You add alt="image", run the check again, and the warning disappears.

The HTML changed. The experience barely improved.

Presence is easy to check. Whether an alternative communicates the right information requires understanding why the image exists on that page.

The same photo can be informative in a product gallery, redundant inside a product link with a clear label, and decorative in a background composition. A useful alternative belongs to the image's use, not just to the image file.

This article is a practical review workflow for developers and content teams. It does not claim that an image scanner can determine accessibility compliance from an attribute count.

1. Missing, empty, and descriptive are different states

Consider three examples:

<img src="bag.jpg">
<img src="bag.jpg" alt="">
<img src="bag.jpg" alt="Forest-green handbag with a gold clasp">

They should not be treated as interchangeable.

An absent attribute leaves the text alternative unspecified. An empty value can intentionally omit a decorative image from the reading experience. A descriptive value can communicate information that matters in context.

For a decorative image, adding descriptive prose can create noise rather than remove a barrier. W3C's decorative-image guidance explains why an empty alternative is appropriate and why leaving the attribute out is a different decision.

An audit that tests only hasAttribute("alt") can identify missing attributes. It cannot infer that every empty value is correct or that every nonempty value is useful.

That limitation should shape the report language: “missing alternative” and “requires contextual review” are more defensible than “all images accessible.”

2. Ask what the reader would lose

Before writing anything, ask:

If this image were unavailable, what information or action would the reader lose?

Suppose a catalog page already says “Forest-green leather handbag” beside a photo. On that page, repeating those exact words may add little. In a detail gallery, another view might reveal the clasp, strap, or internal compartments.

The alternative for that second view could communicate its distinct purpose:

<img
  src="bag-interior.jpg"
  alt="Open handbag showing two compartments and a zipped inner pocket"
>

The wording should match what the image actually shows. Do not infer materials, dimensions, authenticity, or hidden features from a thumbnail.

W3C's informative-image tutorial focuses on conveying the relevant meaning, rather than mechanically describing every visible detail.

My editorial rule is to identify the one reason this image deserves to be on this page. Start there. Add detail only when it helps someone make the same decision that the visual is supporting.

3. Functional images need a destination or action

An image can supply the label for a link or control.

This link has an alternative, but the label is not very helpful:

<a href="/downloads/catalog.pdf">
  <img src="download-icon.png" alt="Downward arrow">
</a>

The important information is what activating it does:

<a href="/downloads/catalog.pdf">
  <img src="download-icon.png" alt="Download the product catalog PDF">
</a>

If the link already contains visible text, the icon can instead have an empty alternative:

<a href="/downloads/catalog.pdf">
  <img src="download-icon.png" alt="">
  Download the product catalog PDF
</a>

These are simple cases, not a complete treatment of accessible-name computation. Inspect the rendered control when labels are assembled through nested elements or ARIA attributes.

The W3C functional-image guidance is a good reference for deciding when the alternative should describe the action instead of the appearance.

For image-only controls, include an explicit label requirement in component review. Do not let an unlabeled control pass merely because its icon is attractive.

4. Do not force an entire chart into one sentence

A chart can contain a conclusion and the evidence behind it. A brief alternative may communicate the chart's identity or key message, but it often cannot carry every data point.

For example, a chart comparing monthly image bytes should have a nearby textual explanation and, where useful, a data table. The visual should not be the only place the numbers exist.

An illustrative structure is:

<figure>
  <img
    src="monthly-image-bytes.png"
    alt="Monthly image transfer totals; explanation and data table follow"
  >
  <figcaption>
    Image-transfer totals for the sampled pages, January to March.
  </figcaption>
</figure>

<p>The totals declined each month for this sample.</p>
<!-- Include the actual accessible data table here. -->

The table must contain the real data and clear headings. The comment above is only a placement marker, not a substitute for it.

W3C's complex-image guidance covers alternatives that provide both a short identification and more complete information.

For engineering teams, this becomes a publishing contract: whoever exports the chart also delivers its underlying data or a meaningful narrative. A designer should not have to reconstruct the numbers from pixels.

5. Build context into the asset workflow

A filename such as IMG_1042.jpg is a poor starting label. So is automatically turning a slug into a sentence.

My suggested content record contains separate fields:

Field	Purpose
Asset identifier	Locate the actual file
Page or placement	Explain where it is used
Role	Informative, decorative, functional, or complex
Text alternative	Communicate the necessary meaning
Extended explanation	Support charts or detailed instructional images
Review owner	Identify who can verify the content

A single reusable “default alt” can be a helpful draft. It should not prevent a different value at a different placement.

For product galleries, use placement records to distinguish a front view, back view, detail, and interior view. Do not invent different wording merely to make strings unique. The distinction should reflect information the images actually contribute.

This is a proposed content model, not a claim about BatchSet's current storage schema.

6. Treat generated descriptions as drafts

An image-description model may identify a bag and a clasp. It does not necessarily know that the image is functioning as a download button, that adjacent text already explains it, or that the page is teaching users how to identify a manufacturing defect.

The strongest review prompt starts with the intended use, not just the pixels:

Placement: Product detail gallery
Purpose: Show how the inner compartments are arranged
Already stated nearby: Product name and exterior color
Required review: Confirm visible details; do not infer measurements

That record helps a human reviewer as much as it helps a model.

For a small team, I would prioritize consequential images first: controls, diagrams that explain a process, product details needed to compare choices, and screenshots that contain essential instructions.

Then review repetitive decoration and redundant card images. The goal is understandable content, not the longest possible description for every asset.

7. Give automated checks a narrow, honest job

In a browser console, a small inventory can collect candidates:

const imageInventory = [...document.querySelectorAll("img")].map(img => ({
  source: img.currentSrc || img.src,
  hasAlt: img.hasAttribute("alt"),
  alt: img.getAttribute("alt"),
  inLinkOrButton: Boolean(img.closest("a, button")),
}));

console.table(imageInventory);

This code does not compute accessible names, examine CSS backgrounds, inspect every shadow root, or understand the image's purpose. It creates a review list from the current document.

I would use three queues:

Missing attributes to investigate.
Empty attributes to confirm against the intended role.
Existing descriptions to check for usefulness and accuracy.

Do not automatically classify the second and third queues as failures. They contain context-dependent decisions.

When a scan cannot inspect the required markup, mark the check unavailable. That is a measurement limitation, not evidence that the page passed.

8. Review the experience, not only the markup

A practical acceptance pass should include:

Inspecting labels on image links and buttons.
Reading product-card content in its actual order.
Checking whether charts still make sense without seeing them.
Verifying that decorative elements do not create repetitive announcements.
Testing important flows with a screen reader and keyboard.

Images are only one part of accessibility. Focus order, interaction behavior, form labels, structure, and many other details still matter.

A successful image review does not certify the whole site. It improves one specific part of the experience with evidence you can explain.

Start with discovery, then add judgment

If you need a starting inventory, BatchSet's Website Image Auditor can flag missing alt attributes among the images it analyzes when the necessary markup is available.

It is an image-focused audit, not an accessibility certification. Unmeasurable images and fallback scans have coverage limitations, so review the report's analyzed set and availability indicators.

Use the findings to locate work. Use the page's purpose to decide what the alternative should say.

Your QR Code Works on Screen. Will It Still Scan After Printing?

Muhaymin Bin Mehmood — Sat, 03 Oct 2026 14:00:00 +0000

A QR code scans from your laptop screen. You put it into a brochure, reduce it to fit the layout, export a PDF, and send it to a printer.

That first successful scan only verified the first artifact.

The printed code has different conditions: different physical dimensions, contrast, surface finish, surrounding artwork, camera distance, and possibly different pixel edges after export.

For developers who generate QR codes, “the encoder returned an image” is not the same acceptance condition as “the final customer can open the correct destination.”

Here is a practical preflight workflow for ordinary QR Code symbols. It is not guidance for Micro QR, which has different layout requirements.

1. Understand the three sizes involved

A QR code has at least three separate size concepts:

Symbol size: the number of modules in the encoded square.
Export size: the number of pixels or vector dimensions in the downloaded file.
Placement size: the physical size of the code on the final material.

A module is one cell in the symbol's grid.

DENSO WAVE documents versions from 1 to 40, starting at 21 × 21 modules and increasing by four modules per side with each version. See its version and capacity explanation.

For standard QR Code, that gives:

function modulesForVersion(version) {
  if (!Number.isInteger(version) || version < 1 || version > 40) {
    throw new RangeError("QR version must be an integer from 1 to 40");
  }
  return 21 + 4 * (version - 1);
}

Saving a larger PNG changes export resolution. It does not make a physically tiny code larger when the designer places it at the same width on a business card.

2. Reserve the quiet zone before decorating the layout

The quiet zone is clear space around the symbol. It helps separate the code from nearby text, borders, and artwork.

For ordinary QR Code, DENSO WAVE specifies a four-module margin on all four sides. See its code-area guidance.

That means a 29-module symbol needs a 37-module-wide area when the minimum margin is included:

29 symbol modules + 4 left + 4 right = 37 modules

The same calculation applies vertically.

Do not crop the white border away because it looks like wasted space. A decorative frame inside that clear area is also using the margin.

If a generator lets you choose a margin smaller than four modules, use four or more for this standard QR print workflow. A code occasionally scanning with less space is not evidence that the smaller margin is a reliable production setting.

3. Calculate module size at final placement

Here is a planning helper:

function qrPrintPlan({ version, outerWidthMm, dpi = 300, margin = 4 }) {
  if (!Number.isInteger(version) || version < 1 || version > 40) {
    throw new RangeError("Invalid standard QR version");
  }
  if (!Number.isFinite(outerWidthMm) || outerWidthMm <= 0 ||
      !Number.isFinite(dpi) || dpi <= 0 ||
      !Number.isInteger(margin) || margin < 4) {
    throw new RangeError("Invalid dimensions, DPI, or quiet zone");
  }

  const symbolModules = 21 + 4 * (version - 1);
  const totalModules = symbolModules + 2 * margin;
  const moduleMm = outerWidthMm / totalModules;

  return {
    symbolModules,
    totalModules,
    moduleMm,
    nominalPrinterDotsPerModule: moduleMm * dpi / 25.4,
    nominalOuterPixels: outerWidthMm * dpi / 25.4,
  };
}

console.log(qrPrintPlan({ version: 3, outerWidthMm: 25 }));

For this illustrative version-3 code placed in a 25 mm outer square, including the four-module margin:

Total width is 37 modules.
Each module is approximately 0.676 mm wide.
At 300 DPI, that corresponds to approximately 7.98 nominal printer dots per module.

These numbers describe geometry, not a certified scan threshold. Real output also depends on the printer, substrate, ink spread, scaling, and camera conditions.

There is no universal “make every QR code 2 cm wide” rule that solves every payload and viewing distance. At the same physical width, a denser symbol has smaller modules.

If you deliberately use an integer raster scale, a 37-module-wide artifact at eight pixels per module is 296 pixels wide. Preserve that grid when exporting. Do not assume a later arbitrary resize will preserve it.

4. Payload length is a design input

A long URL full of parameters can require a denser symbol than a short URL. The exact version depends on encoding mode, content, and error-correction level; character count alone is not a reliable version calculator.

For print campaigns, ask whether all that data needs to be encoded directly.

Approach	What the symbol stores	Main dependency
Direct static URL	The final address	That address remaining usable
Static QR containing a short link	A short redirect address	The redirect service and mapping
Editable dynamic QR	Usually a stable redirect address	The service resolving it to the current destination

A dynamic QR image does not rewrite its printed modules when the destination changes. The server-side mapping changes.

A shorter redirect address can reduce the payload, but introduces a dependency on that service. The benefits and the operational responsibility belong in the same decision.

If a printed item must remain useful for years, plan who owns the destination, who can update it, and what happens when the service or subscription changes. A technically valid symbol can still point to an unavailable page.

5. Error correction is not permission to cover anything

QR error correction helps recover data from damage. DENSO WAVE explains the trade-off: greater correction capability adds redundancy and can increase the required symbol size. Its percentages concern restoration of codewords, not an arbitrary percentage of the picture's area. See the error-correction explanation.

That distinction matters for logos.

“Maximum correction” does not mean you may cover any large central region, erase finder patterns, or ignore the quiet zone. The location and kind of damage matter.

My recommended baseline is a plain, high-contrast code with no overlay. Confirm that baseline first. Add branding only when it survives the same final-material tests.

If branding causes failures, remove it before reducing the margin or making the modules smaller. The symbol's primary job is to communicate its payload.

6. Export for the actual production path

Choose a format with the next step in mind:

SVG: useful when the layout tool and printer preserve the vector artwork correctly.
PNG: useful for a controlled raster workflow with sufficient resolution at final placement.
JPEG: a poor default for a sharp module grid because lossy artifacts can alter edges.

Vector export does not guarantee print success. A later tool may rasterize it, crop the margin, apply transparency, or scale it incorrectly.

For raster artwork, avoid repeated resampling and do not turn the code into a low-quality compressed photo asset. Keep dark modules distinct from a light, clear background.

A transparent background deserves particular attention: placing it over a photograph can destroy the clear quiet zone even when the original export looked fine on white.

Verify the delivered PDF or final design export, not only the generator's preview.

7. Test the landing experience as well as the symbol

There are several independent success conditions:

The camera recognizes the symbol.
The decoded payload is correct.
The address resolves and any redirects complete.
The landing page works on the customer's phone.
The page presents the action promised beside the code.

If a restaurant card says “View menu,” opening a desktop-only download page is not a successful customer experience even though decoding worked.

Use an ordinary camera app and, where relevant, a second scanner implementation. Test the final printed proof on more than one device. Check a fresh navigation rather than relying only on an already-open page.

Do not publish private test credentials inside a QR payload. For WiFi or contact-card codes, inspect the actual decoded content and make sure you intended to distribute it.

8. Build a small preflight matrix

Before committing to a print run, I would test:

Dimension	Cases to include
Material	Actual paper, label, packaging, or sign surface
Placement	Final size and final surrounding artwork
Lighting	Normal use, dimmer light, and realistic glare
Angle	Straight-on and a plausible tilted view
Device	More than one phone, including an older one
Distance	The distance a customer can comfortably use
Destination	Correct content, working redirects, mobile usability

Write down the result. “It scanned once” is weaker evidence than “these devices opened the correct page from the approved print proof under these conditions.”

When a failure appears, change one variable at a time: increase placement size, restore the margin, simplify the payload, remove an overlay, or improve contrast. That makes the cause easier to identify.

Generate the code, then approve the proof

You can create static QR codes and download PNG or SVG using BatchSet's QR Code Generator. Dynamic QR codes and scan tracking are available with a free account.

For standard QR printing, explicitly select a quiet zone of at least four modules, choose appropriate dimensions, and test the final proof. A generator prepares the artifact; the real-world scan test approves it.

A Short Link Is an HTTP Contract: Redirects, Caching, and Click Counts That Mean What They Say

Muhaymin Bin Mehmood — Fri, 02 Oct 2026 14:00:00 +0000

A URL shortener looks like a small feature: save a long URL, generate a code, and redirect anyone who visits it.

But a link can outlive the interface that created it. It may sit in an email, a saved message, or a printed brochure for months. The redirect becomes a public contract between that artifact and the destination.

Several decisions hide inside that contract: whether the destination can change, whether caches can bypass the redirect service, which query parameters reach the landing page, and what a “click” actually means.

This is a reference architecture for developers. It does not describe BatchSet's internal status codes, cache configuration, event pipeline, or bot filtering. Those require implementation evidence, not assumptions from a product page.

1. Choose the behavior before choosing the status code

Suppose a business prints this illustrative address:

https://go.example.com/summer-menu

The destination is a seasonal menu. The business expects to replace it later without reprinting the card.

That is different from permanently moving a documentation page to a new canonical location.

Status	Meaning relevant to this design	Method behavior
301	Permanent redirect	Clients may change POST to GET
302	Temporary redirect	Clients may change POST to GET
307	Temporary redirect	Preserves the request method and body
308	Permanent redirect	Preserves the request method and body

For an ordinary navigation-only short-link endpoint, I would explicitly support GET and HEAD and reject other methods. A temporary redirect can fit an editable destination. That is a design choice, not a universal requirement.

If an application really needs to forward non-GET requests, method preservation becomes a separate, deliberate decision. Sending a submitted body to a different destination can have consequences that do not exist for a simple link click.

See the HTTP semantics in RFC 9110, redirection, along with MDN's 302 and 307 references.

2. Cache policy is part of editability

A temporary status does not substitute for a cache strategy.

If a client or intermediary reuses a stored redirect, an updated destination may not be consulted on that visit. The same reuse can keep the request from reaching the application analytics handler.

For a small editable-link service, a straightforward reference policy is:

HTTP/1.1 302 Found
Location: https://shop.example.com/menu
Cache-Control: no-store

no-store tells compliant caches not to store that response. no-cache has a different meaning: storage is allowed, but reuse requires validation. MDN explains the distinction.

This does not erase older cached redirects or make browser history behavior identical across clients. Configure and test the CDN as well as the application. Some deployments have explicit platform rules that must be reconciled with response headers.

At higher volume, you may cache the destination lookup internally while keeping each public redirect observable. That creates a new obligation: invalidate the mapping promptly when someone edits or disables the link.

Caching a database lookup and caching an HTTP redirect are different operations. Name them separately in the design.

3. A redirect request is not proof of a human click

Imagine sharing a link in a messaging app. The app may retrieve it to build a preview. A security scanner may inspect it before the recipient opens the message. A user may also visit twice.

A request counter can be useful without claiming to count people.

Metric	What it can mean	What it does not prove
Redirect requests	Requests observed by the redirect service	Human intent
Filtered requests	Requests remaining after a stated filter	Perfect bot exclusion
Estimated unique visitors	Deduplicated observations under a stated rule	Exact distinct people
Landing-page sessions	Sessions recorded at the destination	Every short-link request arrived
Conversions	A defined destination-side event	Every visit caused a sale

User agents, request methods, timing, and known crawler signatures can inform filtering. None of them is a flawless human detector.

The product decision I recommend is to document the metric and retain the distinction between raw observations and derived estimates. Avoid replacing one ambiguous label with a more impressive ambiguous label.

If a dashboard says “clicks,” its help text should explain what is counted and what may be missing.

4. Make analytics failure a deliberate trade-off

There are two tempting extremes:

Wait for every analytics write before redirecting, so logging failures can delay navigation.
Start an unawaited promise and return immediately, assuming the hosting runtime will finish it.

Neither is automatically correct.

For a reference design, a bounded durable enqueue can keep the event path short. The service can choose to continue redirecting when event ingestion fails, record the failure, and accept that the analytics stream may have a gap.

An alternative is logging at an edge or request layer with a suitable durability contract. Platform-specific background execution should use the platform's supported mechanism, not a detached promise with no lifecycle guarantee.

Define the desired behavior during an outage:

Does navigation continue?
Can the failed event be recovered?
Can operators see the missing-data condition?
Does retrying an event create duplicates?

A unique event ID helps a consumer deduplicate retries. It does not make an event pipeline “exactly once” by itself.

These are engineering choices for a new implementation. They are not claims about how BatchSet currently records clicks.

5. Validate destinations without claiming they are trustworthy

For a link that should open a website, require an absolute HTTP or HTTPS URL and reject embedded credentials.

function parseDestination(input) {
  const destination = new URL(input);

  if (!["http:", "https:"].includes(destination.protocol)) {
    throw new Error("Use an absolute HTTP or HTTPS URL");
  }
  if (destination.username || destination.password) {
    throw new Error("Embedded credentials are not supported");
  }

  return destination.href;
}

This is syntax and scheme validation. It does not establish that a website is honest, safe, reachable, or owned by the creator.

Production abuse handling needs its own decisions: creation limits, reserved codes, reporting, review, disabling malicious links, and appropriate checks for private-network destinations if those should not be supported.

If you later add server-side destination previews, the threat model changes again. A browser redirect does not require your server to fetch the destination; generating a preview does. That new fetcher needs its own SSRF protections.

6. Do not accidentally create a public open-redirect parameter

This pattern makes the saved mapping irrelevant:

/r/summer-menu?destination=https://unexpected.example

If any visitor can override the target, the short-code owner no longer controls what the public artifact means.

Prefer a stored, authorized mapping. Editing that mapping should require permission. Anonymous visitors should only resolve it.

Also decide what happens to query parameters. If the saved destination already has campaign tags, blindly appending every incoming parameter can overwrite attribution or introduce parameters the landing application never expected.

My default for a reference service is do not forward incoming parameters. If forwarding is needed, use a small allowlist and define precedence:

function addAllowedCampaignParameters(savedURL, incomingURL) {
  const target = new URL(savedURL);
  const incoming = new URL(incomingURL);

  for (const key of ["utm_source", "utm_medium", "utm_campaign"]) {
    const value = incoming.searchParams.get(key);
    if (value !== null && !target.searchParams.has(key)) {
      target.searchParams.set(key, value);
    }
  }

  return target.href;
}

The saved value wins here. Other applications may choose differently, but the rule should be intentional and testable.

Campaign parameters should not carry passwords, personal email addresses, or other secrets. URLs can be retained in histories, logs, screenshots, and downstream systems.

7. Test the public contract, including negative cases

A useful acceptance matrix for a short-link implementation includes:

Scenario	Expected decision to verify
Existing code, GET	Correct destination and cache policy
Existing code, HEAD	Deliberate response and counting policy
POST to navigation endpoint	Rejected if unsupported
Unknown code	Clear not-found response
Disabled or expired code	No silent redirect to an unrelated page
Destination edited	Subsequent fresh requests use the new target
Analytics unavailable	Navigation follows the documented outage policy
Replayed event	Consumer deduplicates under its stated rule
Unexpected query parameter	Cannot override the destination
Non-web scheme or credentials	Rejected at creation and edit time

Use example domains when testing destination behavior. Do not test a forwarding policy by sending real form data to arbitrary external sites.

Also compare redirect counts with destination-side analytics, expecting disagreement. A discrepancy is a debugging starting point, not proof that either system measures the same event incorrectly.

Put the link workflow to use

BatchSet offers a URL Shortener with click analytics and optional custom codes, available with a free account.

If you want to organize links for a campaign, start there. Verify the final destination before sharing, keep campaign labels consistent, and interpret click reporting alongside landing-page outcomes.

A short link should be easy to share. The meaning of its destination and its metrics should be just as easy to explain.