DEV Community: hao jia

I replaced a docs-site GIF with animated WebP and it got bigger

hao jia — Mon, 21 Sep 2026 08:02:56 +0000

I had a one-line plan for our internal docs site: replace every GIF with animated WebP. Twenty-odd components, one screen recording each, and that layer was eating close to half of the first-load traffic. WebP is a decade and a half newer than GIF, so the win felt too obvious to measure.

I measured it anyway. On my sample, animated WebP came out 6.4% larger than simply re-encoding the GIF.

The sample

I drew a fake back-office animation frame by frame with a script — a made-up order management page: skeleton shimmer, rows filling in, a filter dropdown opening, a confirmation dialog, and a clock ticking in the header. 960×600, 75 frames, 60 ms each, 4.5 seconds. As a GIF it weighs 1,585,112 bytes.

It is a synthetic file, not the output of a real screen recorder, so treat every number below as describing this kind of picture — a mostly static UI recording — and nothing broader.

Four formats, one export run

I dropped it into the animation workshop on ImgIng (https://imging.ai/), a browser-local image tool, and exported all four formats with the page defaults untouched.

Format	Bytes	Share of the original
Re-encoded GIF	983,087	62.02%
Animated WebP	1,045,924	65.98%
APNG	1,392,726	87.86%
Animated AVIF	157,490	9.94%

My plan finished third out of four.

Why the GIF refuses to shrink

GIF saves bytes by redrawing only the part of the frame that changed, but it can only declare one rectangle per frame. In this animation the cursor moves on the left while the clock ticks in the top right, so that rectangle has to swallow both ends plus all the untouched pixels in between. 68 of the 75 frames do use partial refresh, and the dirty rectangle still averages 59% of the canvas.

Two more structural costs pile on: at most 256 colours per frame, with every frame after the first carrying its own local palette (74 palettes × 256 × 3 ≈ 57 KB of pure lookup tables), and LZW that only rewards horizontal repetition.

None of that explains why WebP lost, though. Judging from the output alone, I'd guess animated WebP also works in keyframes plus rectangular difference blocks — it inherits the same fat dirty rectangle and only saves on what happens inside it. With 59% of the canvas redrawn and small table text everywhere, there is no order-of-magnitude left to win. I haven't looked inside the encoder, so that's a guess from the artefacts.

APNG deserves its own sentence: its frames are pixel-identical to the source. It isn't a smaller format, it's a lossless one. On two other samples it came out 35% and 36% larger than the original GIF, and the tool says so on the result card.

Checking that nobody touched the timeline

Size was never the part that worried me. Dropped frames or rewritten frame delays quietly change the playback speed, and nobody notices until much later. So I ignored the summary in the UI and parsed the files myself. The APNG export was the easiest one to audit, because its per-frame delays sit in plain fcTL chunks:

from struct import unpack

def apng_frames(buf):                     # read the fcTL chunks of an APNG
    i, out = 8, []
    while i < len(buf) - 8:
        n, kind = unpack('>I', buf[i:i+4])[0], buf[i+4:i+8]
        if kind == b'fcTL':
            num, den = unpack('>HH', buf[i+28:i+32])
            out.append(1000 * num / (den or 100))
        i += 12 + n
    return out                            # 75 delays of 60.0 ms

It returns 75 delays of 60 ms, 4500 ms in total; the 1280×800 demo gives 40 delays of 100 ms. GIF hides the same numbers in its graphic control extensions and animated WebP in its ANMF chunks, so each format needs its own reader. Across four samples and sixteen exports, frame count, per-frame delay, total duration and the infinite-loop flag all matched the source.

One quirk worth remembering: GIF stores delays in hundredths of a second, so only multiples of 10 ms survive. I asked for 66 ms while generating the sample and got 60 ms on disk. That's the format's resolution, not a compression loss.

What stopped me from switching everything to AVIF

The size argument is loud — the 1280×800 demo animation went from 1,127,031 bytes to 208,937, or 18.5% of the original. But I only put the WebP, APNG and AVIF files on one local page and opened it in Chromium 149, WebKit 26.5 and Firefox 151, screenshotting the same <img> twice 900 ms apart and comparing pixels to confirm it was genuinely animating rather than merely not erroring. All three engines passed.

Three desktop engines is all I have. In-app WebViews, older machines, whatever renders animations inside messaging clients — I tested none of them, so I can't speak for them. ImgIng's result card also notes that its animated AVIF carries no transparency, which is fine for screen recordings and not fine for a diagram on a transparent background.

So the plan turned into something duller: pick per asset, and keep a GIF fallback behind a <picture> for anything I haven't verified. I've only wired that markup up on a local page — how various docs pipelines treat it is something I haven't checked, so I won't claim it works everywhere.

One last counterintuitive bit. Another sample had already been squeezed my usual way — scaled to 70%, every second frame dropped, down to 64 colours — 357,648 bytes. Re-encoding it as GIF saved 684 bytes, 99.81%, pixel-identical. The same file as animated AVIF saved another 62%. "This one can't be compressed any further" only holds inside a single format.

A PDF is its own reference when you verify the images you pulled out of it

hao jia — Sun, 20 Sep 2026 08:03:04 +0000

Most of what my team maintains sits somewhere on the product-image path of an e-commerce platform, and one input format keeps coming back that nobody likes: a catalogue PDF as the only copy of a set of product photos. Getting the pictures out is the easy half. The half I care about is being able to say, before those files enter our asset store, whether each one is what the PDF actually contains or something regenerated along the way, a re-encoded JPEG, a page render at display size, a PNG that lost its alpha. A folder of images that merely look fine doesn't answer that.

The trick that makes this checkable is that you don't need the supplier's originals. The PDF is its own reference. A JPEG inside a PDF is stored as a /DCTDecode stream, and that stream is a complete JPEG file, so a faithful extraction produces a file whose SHA-256 equals the SHA-256 of the raw stream. Flate-compressed images (what PNGs become) have no file to compare against, so for those I decode the stored object, fold in its soft mask if it has one, and compare pixels. Pixel size is enough to pair each recovered file with its object, and colour space comes straight from the PDF, which I want recorded because a CMYK product shot needs different handling downstream.

The check

I ran it on test PDFs I generated myself with reportlab: an 8-page brochure with JPEG and PNG product shots, a PDF holding one CMYK and one grayscale JPEG, and a single RGB JPEG at 1600×1067. The recovered files came from ImgIng's Extract PDF images. It runs in the browser, and the workspace states that the file is read only in the browser and never uploaded. For synthetic files I took that at face value; before feeding it anything under an NDA I would still watch the Network tab myself, because that's what the compliance people would ask me.

The check walks every page with PyMuPDF's get_images(full=True), which lists each image object the page paints along with its size, colour space, filter and soft-mask reference, and files them by pixel size. Each recovered file is then opened, paired with the objects of the same size, and tested. For a DCTDecode object the test is a straight hash comparison against the undecoded stream (excerpt; f is the recovered file, xref the candidate object):

if filt == "DCTDecode":
    same = hashlib.sha256(f.read_bytes()).digest() == \
           hashlib.sha256(pdf.xref_stream_raw(xref)).digest()

For everything else the stored object is decoded, and if it has a soft mask, the mask is folded into its alpha before comparing (excerpt):

pix = fitz.Pixmap(pdf, xref)
if smask:
    pix = fitz.Pixmap(pix, fitz.Pixmap(pdf, smask))  # fold the mask into alpha

Both sides are converted to RGBA and diffed with Pillow's ImageChops.difference. If you write this yourself, call getbbox(alpha_only=False) on the diff; on RGBA images Pillow's default looks only at the alpha channel, and two opaque images with completely different colours come out "identical". A JPEG whose object also carries a mask gets a warning appended to its verdict. Across the four test PDFs, every recovered file found its object:

Recovered file	Format / mode	Matched object	Verdict
Brochure, 5 files	3 PNG RGBA, 2 JPEG RGB	DeviceRGB	PNGs pixels identical, JPEGs sha256 == PDF stream
CMYK JPEG	JPEG CMYK	DeviceCMYK	sha256 == PDF stream
Grayscale JPEG	JPEG L	DeviceGray	sha256 == PDF stream
RGB JPEG 1600×1067	JPEG RGB	DeviceRGB	sha256 == PDF stream
Page render crop (control)	PNG RGBA	none	no image object is 1361x908
Masked JPEG	JPEG RGB	DeviceRGB	sha256 == PDF stream, but the PDF also has a mask for it

Because I made these PDFs, I also had the source files and hashed those too: all three recovered JPEGs, RGB, CMYK and grayscale, match them exactly. Nothing got converted either; the CMYK file is still a CMYK JPEG, which I prefer to a silent RGB conversion. The colour decision stays with whoever owns the print or web pipeline. The PNG shots matched pixel for pixel, the one with transparency included. One thing I'd put in a pipeline note: every PNG came back as RGBA, even the ones that were opaque RGB going in (alpha is 255 everywhere). If a downstream service rejects images with an alpha channel, that's where it'll trip.

A row that should fail, and one that passes when it shouldn't

The page render crop is the control. I rendered the same page with ImgIng's PDF to images at 216 DPI (1786×2526 for the whole A4 page) and cropped the photo out of it: 1361×908, against 1600×1067 stored. Its PSNR against the original scaled to that size was 47.19 dB, so by eye it passes, but no object in the PDF has that size, and the check rejects it before any hashing happens. That's exactly the file I don't want in an asset store with a "supplier original" tag on it.

The masked JPEG is the case a hash alone gets wrong. In that sample the JPEG has a soft mask that fades it to an oval on the page. The extracted file is byte-identical to the stored stream, so it is faithful in the narrow sense, but the transparency lived in a separate object and did not come along. I only have that one hand-built sample, which is why the script prints a warning next to the verdict for any masked JPEG.

Two UI details matter for automation. With one result, the button reads "Save this image" and writes a single .jpg; with several, you only get "Save extracted images (ZIP)" and there is no per-card save, so I unpack the ZIP into a folder and point the script at it. The ZIP is stored uncompressed and the file names are just -image-001, -002, so the page numbers shown on the cards don't travel with the files.

Everything above ran against files generated on my own machine, with the extractor at https://imging.ai/ reading them inside the browser.

Our PDF upload limit says 2 MB. I tested auto-compression before adding it

hao jia — Sat, 19 Sep 2026 08:02:59 +0000

Our upload form rejects PDFs over "2 MB". Every month a few support tickets land with the same complaint: "My file says it's under the limit." A product manager on my team suggested the obvious fix: when a PDF is too big, compress it in the browser and retry automatically. Before estimating that, I ran a small test. The auto-retry idea didn't survive it, but two smaller changes did.

First, decide which "2 MB" you mean

"2 MB" is either 2,000,000 bytes or 2,097,152 bytes. Our frontend formatted sizes in base 1024. macOS Finder shows base 1000. The backend compared raw bytes. Three parties, three numbers, no bug anywhere, and still tickets.

One of my test files makes the gap obvious: 19,458,294 bytes. The compression tool I used shows it as "18.56 MB" (base 1024). In base 1000 it's 19.46 MB. Near the limit, that difference decides pass or fail.

We now store the limit as a byte constant, pick the stricter 2,000,000, and show both readings in the error message:

const LIMIT_BYTES = 2_000_000;
const fmt = (b) => `${(b / 1048576).toFixed(2)} MiB / ${(b / 1e6).toFixed(2)} MB`;

function checkUpload(file) {
  if (file.size <= LIMIT_BYTES) return { ok: true };
  return { ok: false, message: `This file is ${fmt(file.size)}. The limit is ${fmt(LIMIT_BYTES)}.` };
}

A 2,905,274-byte file gets "This file is 2.77 MiB / 2.91 MB. The limit is 1.91 MiB / 2.00 MB." Nobody has to guess which unit we meant.

Then, check whether compression would even help

I didn't want to test with customer files (we went through a compliance review once and I'm not repeating it), so I built three fake samples:

an 8-page product brochure, 19,458,294 bytes, photos from a CC0 Wikimedia Commons image, cropped and upscaled
a 10-page text-only document, 137,782 bytes
a 4-page 300 dpi "scan": a made-up form rendered to full-page images, no text layer, 8,948,995 bytes

I compressed them with the PDF tool on ImgIng (https://imging.ai/), mainly because it runs in the browser. I kept DevTools' Network tab open during every run and saw no non-GET requests, which is the first thing our compliance people would ask about. I don't know how it works internally; everything below is inferred from the output files.

On the default E-book preset (150 dpi):

Sample	Before (bytes)	After (bytes)	Saved
Brochure	19,458,294	864,614	95.6%
Scan	8,948,995	1,927,707	78.5%
Text-only	137,782	131,156	4.8%

The scan ends at 1.84 MiB, or 1.93 MB. Under 2 MB in both readings.

The text-only file is the problem. All four presets produced the identical 131,156-byte file. Splitting the PDF by stream type explains it: 85.22% of its bytes are embedded fonts, and the tool's docs say it doesn't subset fonts. The brochure is 99.23% images. That's one sample with fonts that were already subset, so I'm not claiming every text PDF behaves like this. Still, it was enough to kill "compress and retry" as a silent fallback. For a file like that, the user waits through a compression pass and then gets rejected anyway.

Verify what comes back

A smaller file only helps if it's still the same document. I compared page count and extracted text before and after. The brochure (3,357 characters) and the text-only file (11,174 characters) matched exactly, and so did every page count. The scan has no text layer, so only the page count means anything there. For image quality I rendered the pages and looked. The lowest preset (Screen, 72 dpi) got the brochure down to 352,318 bytes, but the small table text in its screenshots became unreadable. That's why our message suggests "around 150 dpi" instead of "smallest".

What we shipped

No automatic compression. When a PDF is over the limit, we check it before showing the error. If it looks like a scan, we suggest compressing to about 150 dpi. If it mixes images and text, we suggest compressing the images. If there are no images at all, we suggest splitting the file. Encrypted PDFs get their own message, because the compressor I tested refuses them until protection is removed.

I only tested three self-made files, in Chromium on a Mac. Mobile browsers and Windows are untested, and scans that already have an OCR text layer will probably confuse our "looks like a scan" check. That's next on the list.

Same 150 KB, three formats: what you actually get

hao jia — Fri, 18 Sep 2026 08:02:45 +0000

Someone on my team opened a PR that moved our export quality from JPEG 80 to WebP 80, with a note saying "same quality, smaller files". I didn't merge it. Those two 80s are not the same ruler, and the benchmark behind the claim was measuring the wrong thing.

Our constraint is a page budget: hero images on the product detail page must stay under 150 KB each. The budget is written in bytes. So the question is not "which format is smaller at the same quality" — it's "at the same 150 KB, which one buys me the most image quality". Those are two different experiments with two different answers.

Why quality 80 is not quality 80

JPEG's quality scales a quantization table. WebP's quality drives a whole group of prediction-search and quantization parameters. AVIF's quality gets mapped into an AV1 qindex. No standard ties these three scales to the same distortion level. Setting all three to 80 and comparing file sizes tells you one thing only: what those three unrelated rulers read at their own 80 mark.

Think of each format as a rate-distortion curve. To compare curves you have to slice along an axis. Slice along quality and you learn "how many bytes to reach the same fidelity". Slice along size and you learn "how much fidelity you get for the same bytes". Comparing q80 to q80 picks one arbitrary point on each curve and leaves both variables moving.

Pinning the bytes

For each format, binary search quality 1..100 for the highest value that still fits the budget:

from bisect import bisect_right

class SizeAt(list):
    """len(self) == 101; self[q] encodes at that quality and returns the byte size"""
    def __init__(self, im, fmt): self.im, self.fmt = im, fmt; super().__init__(range(101))
    def __getitem__(self, q):
        buf = io.BytesIO(); self.im.save(buf, self.fmt, quality=q); return buf.tell()

def best_quality(im, fmt, budget):
    return bisect_right(SizeAt(im, fmt), budget) - 1

This assumes size grows monotonically with quality. It usually does, but that's an observation, not a theorem — I swept the whole range once to confirm there was no inversion before trusting the search.

The sample is a CC0 photo from Wikimedia Commons (shot on an iPhone 6, 2048×1536, 638.7 KB), not my own material. Lots of sky and metal reflections, so it is on the hard side to compress. Budget: 150 KB.

Format	Quality that fits	Size	PSNR	SSIM	Encode time
JPEG	q23	147.6 KB	33.7	0.938	4 ms
WebP	q65	149.8 KB	37.6	0.965	126 ms
AVIF	q59	145.8 KB	38.9	0.973	131 ms

The interesting column is the second one. To fit 150 KB, JPEG has to fall all the way to q23 — zoom into the sky and you can see blocking. WebP stops at q65, AVIF at q59. That leftover quality headroom is exactly where the 5.2 dB spread comes from. With a q80-vs-q80 table, that column never appears.

What I actually changed

Budget first, format second. We now derive a per-image byte ceiling from the page budget, then pick the format by measured fidelity at that ceiling. Quality is a means to hit the budget, not a number you compare across formats.

Encoding time is a real cost. 4 ms vs 126 ms vs 131 ms is a thirty-fold spread. That number only describes one Pillow call on my Mac, but the direction holds: the bytes you save on the wire get paid for on the encoder. Our upload pipeline fans one original out into five sizes, so switching the primary format means re-running load tests, not flipping a constant. I did not test AVIF decode support on older devices in this round, so the JPEG fallback in <picture> stays.

Budgets belong per content type. The same run included a 1280×800 UI screenshot: 94.0 KB in, 31.6 KB out as WebP q80, 18.5 KB as AVIF q60, both above 40 dB. Flat color and sharp text compress far better than photos, so one global target wastes headroom.

Soft-edged and semi-transparent assets get their own path. Badges and shadowed overlays lose their gradient alpha when you push them through palette reduction. The shadowed transparent badge in that run went from 35.2 KB to 20.2 KB as WebP and 2.4 KB as AVIF, with the alpha levels intact.

One last constraint that isn't technical. These were unreleased product assets, and anything leaving our network needs a compliance sign-off — we spent three months under legal review after a data remediation two years ago, and I've asked that question first ever since. So besides the local script I ran the same comparison in the browser with Imging, where compression and conversion for common formats happen locally without an upload. The numbers lined up with my script, and I didn't have to file a request to check a table.

If you want the version of this that applies to your images: take your largest hero image, pick a byte ceiling, binary search each format, then open the three outputs side by side at 200% and look at a gradient area.

https://imging.ai/

Your thumbnails look washed out: it's the ICC profile, not JPEG quality

hao jia — Thu, 17 Sep 2026 08:31:47 +0000

If someone on your team has bumped a thumbnail service from quality 80 to 95 because the images look faded, check one thing before touching quality again: does the output file still carry the source image's ICC profile? On the sample I tested, removing the profile made the photo visibly duller while every pixel value stayed exactly the same. Saving that file at quality 100 wouldn't bring the color back, because nothing was lost to compression in the first place.

The sample

A CC0 photo from Wikimedia Commons, shot on an iPhone 6 at Madrid airport, resized to 2048×1536. With Pillow 11.3's ImageCms and the ICC files that ship with macOS, I wrote three JPEGs at quality 92: one tagged sRGB, one converted to Display P3, one converted to Adobe RGB (1998). The photo's colors sit inside sRGB, so this isn't a wide-gamut stress test, and the numbers below describe this one image only.

Two different kinds of worse

Compression damage lives in the details: soft edges, banding across smooth sky, 8×8 blocks when you zoom in. A dropped profile does something else. The RGB numbers don't change, but without a profile the viewer assumes sRGB, and P3 or Adobe RGB values read as sRGB come out less saturated. I measured the difference in CIELAB (ΔE76) between each tagged file and the same pixels read as sRGB:

Profile dropped	mean ΔE	p95 ΔE	pixels with ΔE > 5	mean chroma loss
Display P3	1.83	3.9	1.7%	16.6%
Adobe RGB	2.91	5.27	7.4%	20.1%

A mean ΔE under 3 sounds harmless, and the chroma column is where the problem shows. Grays, whites and shadows barely move. The most saturated 5% of pixels shift by ΔE 5.4 with P3 and 7.2 with Adobe RGB, which in this photo is the red and green tail livery and the blue sky going pale. So blurry or blocky points at compression, while uniformly faded with intact detail points at the profile.

Where the profile gets dropped

Input: JPEG tagged Display P3. Sample: Wikimedia Commons CC0 photo (iPhone 6), profile converted locally.

I fed the P3 JPEG through default save paths. Pillow 11.3 drops the profile when saving JPEG or WebP, after resize() or thumbnail() too, and quality 100 changes nothing; saving PNG keeps it. ffmpeg 7.1 keeps it converting to JPEG or PNG and drops it converting to WebP. macOS sips kept it for PNG, -Z resizing and a quality 60 re-save. Pillow resize followed by WebP output, which is probably the most common thumbnail recipe, hits the problem twice. The fix is to pass the profile through explicitly:

from PIL import Image

thumb = Image.open(src_path)
icc = thumb.info.get("icc_profile")   # None when the source is untagged
thumb.thumbnail((800, 800))
thumb.save(dst_path, "WEBP", quality=80, icc_profile=icc)

Run against the P3 sample, both the JPEG and WebP outputs read back as Display P3. The other option is converting to sRGB with ImageCms.profileToProfile before saving, which protects you from any later step that strips profiles again. I haven't settled which one I want for thumbnails. On a sample that fits inside sRGB the two look identical, and I have no wide-gamut data to judge what the conversion clips.

One trap while checking: sips -g profile reports sRGB IEC61966-2.1 for a JPEG with no embedded profile, so it can't tell untagged from real sRGB. I trust Image.open(path).info.get("icc_profile") instead.

What about canvas compression in the browser?

Sample: Wikimedia Commons CC0 photo (iPhone 6), converted to Display P3 locally. Firefox is the build bundled with Playwright.

Using Playwright's bundled engines on macOS 26.5, Chromium 149 and WebKit 26.5 honor the profile in <img>, and pixels read back from a canvas are already converted to sRGB (mean difference from the sRGB source: 0.66 and 0.69, which is JPEG noise). toBlob('image/jpeg') output looks right in both. Chromium also embeds an sRGB profile; WebKit's JPEG has none, which is fine because the pixels are already sRGB. The Firefox 151 build bundled with Playwright rendered the tagged and stripped files the same (mean screenshot difference 0.03), read back unconverted P3 values, and exported an untagged JPEG that looks washed out. That's one build with default settings, not a statement about release Firefox. It also means a has-profile check alone can mislead on browser exports, since WebKit's untagged JPEG is correct.

The order I check things in now

Does the source have a profile, and which one? If it's sRGB or absent, a dropped profile can't explain the fade, so go look at compression.
Does the output still have it? If the source is P3 and the output has nothing, the pipeline dropped it.
Only when both are tagged and colors are still off do quality settings and client-side export become suspects.

Apple's developer documentation notes that iPhone 7 and later can capture in P3, so tagged uploads are ordinary input rather than an edge case.

Chrome fires onerror, WebKit shows it: feature-detect HEIC before you preview

hao jia — Wed, 16 Sep 2026 08:04:21 +0000

Short version: if your upload preview goes blank when someone picks an iPhone photo, the browser most likely can't decode HEIC at all, and your component is treating a decode failure as "nothing to show". Don't sniff the user agent and don't trust the .heic extension. Ask the browser to decode the actual file, and branch on the answer.

I tested this because the bug report pattern is so common: preview empty in Chrome, fine on the developer's Mac. Before touching the component I wanted to know which engines fail, how the failure surfaces in code, and whether anything about the file itself matters. Here's what three engines did with the same file.

The sample

I don't have an iPhone original I can publish, so I took a CC0 photo from Wikimedia Commons, shot on an iPhone 6 (3264×2448 JPEG, an apron at Madrid airport), and converted it to HEIC with the sips tool that ships with macOS 26.5. One copy has EXIF orientation 6, i.e. portrait. It is not straight off a phone, so nothing below covers HDR, Live Photos or depth data.

Parsing the ISOBMFF boxes of the portrait copy shows why decoding is not a small feature. The primary item is a grid built from 35 hvc1 tiles, each a 512×512 HEVC image laid out 7 × 5. The ispe property says 3264×2448, landscape; the portrait orientation lives in an irot property of 270°. Upscaled to 4032×3024, the same photo becomes 48 tiles. To display it, an engine needs an HEVC decoder, has to stitch the grid and has to apply the rotation.

Three engines, three APIs

I used Playwright's bundled engines on macOS 26.5 and pointed all three APIs at the same portrait file, passed in as the File object you'd get from an <input type=file>. The table is the raw outcome; sizes are naturalWidth×naturalHeight or the bitmap size:

Engine	`<img>`	`createImageBitmap`	`img.decode()`
Chromium 149	onerror	InvalidStateError	EncodingError
Firefox 151	onerror	InvalidStateError	EncodingError
WebKit 26.5	2448×3264	2448×3264	2448×3264

Sample: CC0 iPhone 6 JPEG from Wikimedia Commons, converted to HEIC with macOS sips. Not a phone original.

WebKit returns 2448×3264, so it stitched the grid and honoured irot. Two caveats I'd put in any ticket. WebKit is borrowing the macOS system decoder here. And this is Playwright's WebKit build, not Safari; I haven't tested real Safari, Windows or any phone. "Works on my Mac" tells you nothing about the Chrome user who filed the bug.

One more thing I checked: I wrapped the HEIC in a File named x.bin with an empty type. All three engines gave exactly the same results. Browsers sniff the bytes, so renaming doesn't help, and checking file.type doesn't tell you whether the preview will work.

Detect by decoding

So the check is to decode the file the user actually picked, in the browser they're actually using, before you build the preview. This is all of it, and I ran it in all three engines against the HEIC and a JPEG control:

async function supportsDecode(blob) {
  try {
    const bitmap = await createImageBitmap(blob);
    bitmap.close();
    return true;
  } catch {
    return false;
  }
}

HEIC: false in Chromium and Firefox, true in WebKit. JPEG: true everywhere, already rotated to 2448×3264 from its EXIF. I prefer this over listening to <img> errors because it rejects into a catch you control. Don't branch on e.name though; the two failing engines use different error names across APIs.

A false doesn't mean the file is broken. Bytes 4 to 12 of the sample read ftypheic, so a header check separates "HEIC this browser can't decode" from "corrupt file". Those deserve different messages.

The fallback

Once you know, the options are:

Decodes: preview as usual with an object URL.
HEIC, can't decode: replace the empty box with a sentence like "This browser can't preview HEIC. The file is still selected." That alone kills the re-select loop.
Want an actual preview or a JPG: load a WASM decoder on demand (libheif builds are the usual choice) and decode locally, or upload and convert on the server.

I lean local-first. I work under compliance rules where "did the original leave the user's machine" is a question I've had to answer for months, and local decoding is the one answer that's simply "no". A converter I used as a reference, imging, does exactly this: pick a HEIC and it says the browser can't decode it natively and offers a "Load decoder" button; after loading, the file reads locally, and I saw no upload request for the original. Converting the portrait sample to JPG gave 2448×3264 with EXIF orientation 1, so no double rotation. Its HEIC output is marked server-side, so reading and writing are different stories there.

If you pick the server route, test with a multi-tile, rotated file. ffmpeg 7.1 with a plain ffmpeg -i in.heic out.png wrote 512×512, the first tile; ffprobe does report the tile grid, the default command just doesn't stitch it. Pillow 11.3 without the pillow-heif plugin raised "cannot identify image file". Both can handle HEIC with the right setup; the defaults can't.

What I still can't tell you: how a real iPhone HDR photo comes out of a WASM decoder versus a server conversion. I don't have a sample, so I'm leaving that open. The converter I referenced: https://imging.ai/

canPlayType said ‘probably’ in three engines; only two kept my transparent WebM transparent

hao jia — Tue, 15 Sep 2026 08:04:17 +0000

A cut-out presenter floating over a product page, person only, no rectangle, the page showing through, is the kind of request that reaches a frontend team sooner or later. The obvious deliverable is a transparent WebM, and the obvious way to decide whether the browser can handle it is canPlayType. I ran both through three engines before I'd estimate it, and the feature check turned out to be the part that tells you nothing.

The file

I made the test file with a browser-side video matting tool, because the source footage wasn't supposed to leave my machine, and after a compliance cleanup I once sat through, that's the first filter I apply. Input was "Tarun speaking 01" from Wikimedia Commons (CC0), re-encoded to H.264 at 464×832. With the background set to Transparent, the tool greys out MP4 and switches the format to WebM on its own, with a note that transparent backgrounds need WebM VP9 alpha.

ffmpeg reports VP9 Profile 0, alpha_mode: 1 on the stream, Opus 48 kHz audio, same resolution and all 511 frames. One trap before you even get to a browser: the stream line says yuv420p. ffmpeg's built-in VP9 decoder ignores the alpha. Force -c:v libvpx-vp9 before the input and you get yuva420p. If your pipeline sanity-checks transparency by reading pix_fmt from a default probe, it will say the alpha isn't there when it is. The file came out at 5.47 MB, where the export panel had estimated about 2.86 MB (both in the 1024-based MB the page uses), so don't size a CDN budget from that number.

Three engines, one probe

I used Playwright's bundled browsers: Chromium 149, Firefox 151 and WebKit 26.5. That WebKit is Playwright's build, not Safari, and I haven't tested real Safari on macOS or iOS. The probe seeks to 1 s, draws the frame into a canvas and reads the alpha of two 40×40 corners that are ceiling in the source, so nothing there should be opaque:

async function cornerAlpha(v, t = 1.0) {
  v.currentTime = t;
  await new Promise(r => v.addEventListener('seeked', r, { once: true }));
  const c = document.createElement('canvas');
  c.width = v.videoWidth; c.height = v.videoHeight;
  const ctx = c.getContext('2d', { willReadFrequently: true });
  ctx.drawImage(v, 0, 0);
  const maxA = d => Math.max(...d.filter((_, i) => i % 4 === 3));
  return [ctx.getImageData(0, 0, 40, 40).data, ctx.getImageData(c.width - 40, 0, 40, 40).data].map(maxA);
}

Chromium and Firefox returned a maximum alpha of 1 and 0 for the two corners, so the transparency survived decoding. WebKit returned 255 and 255, and the pixels are black. It plays the file without complaint and throws the alpha away. All three answered "probably" to canPlayType('video/webm; codecs="vp9"'). There's no error event and no warning, just a black box where the page should be.

Clip: Wikimedia Commons "Tarun speaking 01" (CC0), tested 2026-09-14.

The black isn't WebKit inventing a colour. The YUV stored under transparent pixels in this file is black, so anything that drops the alpha channel shows black. Which leads to the second way this breaks.

Converting it breaks it the same way

The usual reflex when a format doesn't play somewhere is to convert to MP4. ffmpeg -i transparent.webm -c:v libx264 -pix_fmt yuv420p -c:a aac converted.mp4 gives a clean H.264 file with black corners, and my probe reads 255 in every engine, because yuv420p has nowhere to put alpha. A default ffmpeg -i transparent.webm out.gif is also black: 511 frames, no transparent palette entry. A GIF can keep transparency if you ask for it explicitly and decode with libvpx:

ffmpeg -c:v libvpx-vp9 -i transparent.webm \
  -vf "fps=15,split[a][b];[a]palettegen=reserve_transparent=1[p];[b][p]paletteuse=alpha_threshold=128" keep.gif

The corner pixel of that file is fully transparent. It's 1-bit transparency though, so every semi-transparent pixel at the hair and shoulders gets forced to either solid or gone. Those soft edge pixels are exactly the part of an overlay people's eyes go to.

What I'd ship

Since detection can't see the problem, the decision has to rest on which engines you serve. The WebM overlay is fine for Chromium and Firefox. For anything WebKit-based I'd ship a separate MP4 with the background already composited in the page colour. The same tool exports that directly as a solid-colour H.264/AAC file, so it's a second export and not a hand-built fallback. What I still don't have is a result from real Safari, and until I do, WebKit gets the MP4. The acceptance list I'd attach to that ticket:

Decode one frame with -c:v libvpx-vp9 and confirm yuva420p; don't trust the default pix_fmt line.
In each target engine, draw a frame at a known background spot into a canvas and read alpha. canPlayType doesn't count as a check.
Include a WebKit run, and write down that it isn't Safari.
Any conversion step (MP4, GIF, a transcoding upload) gets the same corner check afterwards.
Look at hair and shoulder edges on the real page background, not on a checkerboard.

The tool I used for the export is at https://imging.ai/.

Upright in the upload preview, sideways after the server saved it

hao jia — Mon, 14 Sep 2026 08:06:24 +0000

The bug report is always some version of this: a user uploads a portrait photo from a phone, the preview in the upload form looks right, and the thumbnail our backend generates is lying on its side. Frontend says the image is fine, backend says it saved exactly what it received, and both are telling the truth. The photo's pixels are stored sideways and a single EXIF tag says how to turn them. The browser reads that tag and Pillow's default save throws it away. Reproducing it on a test photo, I also found that the textbook fix rotates the image twice, and that once you start writing EXIF on purpose you have to decide what to do with GPS.

Why the preview is upright

CSS image-orientation has an initial value of from-image, and MDN's description is that the EXIF information in the image "is used to rotate the image appropriately". That became the default in Chrome 81 and, according to Mozilla's bug tracker, in Firefox 77, so any current <img> shows a phone photo the way the phone meant it. I checked in HeadlessChrome 149 with a synthetic test photo I generated (4032×3024 stored, Orientation 6): naturalWidth × naturalHeight came back 3024×4032, already turned, and createImageBitmap reported the same, since its imageOrientation also defaults to from-image. One caveat from MDN is worth knowing if you ever try to switch this off: image-orientation: none does not override the orientation of images from a non-secure origin. The preview isn't lying. It's applying metadata the server is about to delete.

Two ways to get it wrong on the server

The first is the plain save(). Pillow writes no EXIF unless you pass it, so Orientation disappears but the pixels stay 4032×3024. The second is the fix most people reach for next: call ImageOps.exif_transpose() to rotate the pixels, then pass the original EXIF back to keep camera data. The pixels are now upright, but the copied block still says Orientation 6, so every viewer that respects the tag rotates the already-rotated image another 90 degrees. Here are both, on the same synthetic upload, read back with Pillow for the stored size and the tag, and with piexif for the GPS block:

File	Stored pixels	Orientation	GPS
The upload	4032×3024	6	yes
Plain `save()`	4032×3024	none	no
`exif_transpose()` + original EXIF	3024×4032	6	yes

Look at the GPS column. The sideways version is the one without location, and the "fixed" version quietly kept it. So fixing the rotation bug the obvious way is also what brought the location back into storage. The test photo's GPS is a made-up point at sea, but a real upload would carry whatever coordinates the phone recorded.

GPS is a decision, not a side effect

I spent three months in a data-compliance cleanup a while ago, and the thing I took from it is that data we hold by accident is still data we hold. Whether coordinates in a user's photo count as personal data under the law that applies to you is for whoever owns compliance on your side to answer, and I'm not going to guess it for every jurisdiction. What I can control is that the answer lives in code as an explicit list, not in whichever Pillow call someone happened to write. For product and avatar images my default is to keep a handful of camera fields and drop everything else, GPS and the embedded thumbnail included, because nothing downstream uses them.

normalize() rotates the pixels with exif_transpose() so the tag is honoured exactly once, shrinks the image to 1600 px on the long side, and then builds a fresh EXIF block from an allowlist instead of editing the old one. The allowlist is Make and Model from the main IFD plus DateTimeOriginal, ExposureTime, FNumber and ISOSpeedRatings from the Exif IFD. The part that matters (excerpt; old is the source EXIF parsed with piexif):

new = {"0th": {k: v for k, v in old["0th"].items() if k in KEEP_0TH},
       "Exif": {k: v for k, v in old["Exif"].items() if k in KEEP_EXIF},
       "GPS": {}, "1st": {}, "thumbnail": None}
new["0th"][piexif.ImageIFD.Orientation] = 1

After that the two dimension fields are set to the new width and height, and the file is saved at quality 85 with the new block and the source's ICC profile passed through explicitly. The check next to it opens the source and the stored file and asserts on what it reads back (excerpt; s is the source, d the stored file, e its parsed EXIF):

upright = ImageOps.exif_transpose(s).size
assert (d.width > d.height) == (upright[0] > upright[1]), "aspect flipped"
assert e["0th"].get(piexif.ImageIFD.Orientation, 1) == 1, "orientation tag left"
assert not e["GPS"], "GPS survived"
assert not e["thumbnail"], "old thumbnail survived"
assert "icc_profile" in d.info, "ICC dropped"

I ran it on the synthetic upload (Python 3.9, Pillow 11.3, piexif 1.1.3): the 4032×3024 source with tag 6 came out as a 1200×1600 file with 9 tags kept, and the check passed. Then I pointed check() at the two broken files from the previous section, so I know the assertions actually fail when they should. The plain save() output failed on "aspect flipped", and the transpose-plus-old-EXIF output failed on "orientation tag left".

The 9 tags are Make, Model, Orientation, the four exposure fields and the two new dimensions. The ICC line is there because the plain save() drops the colour profile along with the EXIF, and a product shot tagged with a wide-gamut profile can look off without it. The check() is the part I care about more than normalize(). It belongs in CI next to fixture photos that include at least one with Orientation 6 and GPS, and it reads the output file back instead of trusting what the code intended to write.

The acceptance list I review against

A portrait upload with Orientation 6 is stored with upright pixels and Orientation 1 or no tag, and the stored aspect ratio matches what the browser showed.
No GPS IFD in anything we store, unless a written requirement says otherwise.
No IFD1 thumbnail carried over from the source.
Colour profile preserved when the source had one.
Every rule is checked by reading the saved file, in CI, with at least one fixture that has both rotation and location.

If you resize on the client with canvas instead, the picture changes again. In my Chromium test, drawing a JPEG to canvas and calling toBlob gave upright pixels with no EXIF, GPS or XMP at all, which is fine for privacy but loses the camera fields. The HTML spec doesn't say whether drawImage should honour EXIF orientation (the WHATWG issue is still open), and MDN notes that some older browsers ignore it, so I wouldn't lean on that behaviour for users on old devices. Server-side normalisation with a read-back check is the version I'm comfortable signing off on.

sort=True put both columns of a real arXiv paper on the same line

hao jia — Sat, 12 Sep 2026 08:02:23 +0000

Before PDFs go into our internal RAG index, they pass through a preprocessing step my team owns, and the files are not allowed to leave the network. I sat through three months of a data-compliance cleanup once, so "upload it to a hosted parser and see" is not an option I reach for. That leaves the local Python stack, and the tip that comes up most for two-column documents is PyMuPDF's page.get_text(sort=True), which re-orders text by position on the page. I tested it before adopting it. On a real paper it did the opposite of what I wanted.

What sort=True did to an arXiv paper

The paper is RAG-Safety-Bench: Reliable Evaluation of Retrieval-Augmented LLM Safety by Adithiyan Rajan Indira Saravanan and Kathleen C. Fraser (arXiv:2609.11758, CC BY 4.0), a standard two-column LaTeX layout. I took pages 1–2 and extracted them twice, once in default order and once with sort=True. On the non-empty lines I counted three things: lines with a run of six or more spaces between two words, lines ending in a lowercase letter followed by a hyphen, and lowercase words with a year, a month abbreviation or the arXiv ID stuck to their end.

Default order gives 199 lines, no wide gaps, 41 hyphenated line ends, nothing glued, and the right column order, because LaTeX writes the left column before the right one and stream order already matches reading order. With sort=True there are 122 lines, and 47 of them contain a run of six or more spaces, which is what a left-column line and a right-column line pasted side by side look like. The vertical arXiv stamp in the left margin got merged into body text as well, as four glued tokens: reduce2026, onSep, to[cs.CL] and arearXiv:2609.11758v1. One sorted line on page 1 reads "uments can increase reliability and reduce2026", another "tion (RAG) can have unintended side effects onSep". reduce2026 would be embedded as a token. The drop from 41 to 26 lines ending in a hyphen is not an improvement either; the hyphenated fragments are still there, now in the middle of merged lines.

And a file where default order is the wrong one

That doesn't make default order safe. I generated a two-column test report with made-up content whose content stream writes a left line, then the right line at the same height, then the next left line. Nothing on the rendered page tells you the stream is in that order. pypdf and PyMuPDF's default both follow the stream and alternate columns every line.

I also ran it through ImgIng's Extract PDF content, a browser tool whose workspace states the file is read only in the browser and never uploaded, which is the property I need. Its output doesn't depend on stream order at all: this file and a copy written column by column gave identical TXT. The first three lines of each column came out correctly as two columns. Lines 4 to 7 were fused, left then right, with nothing between them, which produced strings like "Finance4. Result" and "differs byto 2":

On the arXiv paper the same tool kept the column order, left the margin stamp out, and moved the second author's affiliation block to after the left column's text. So four extraction paths, two files, and not one path right on both. That changed what I was building. Instead of picking a better extractor, I wanted a check that runs after whichever one we use.

A check that uses the PDF's own geometry

For files with native text, the PDF already knows where every line sits. The check pulls each body line with its bounding box from PyMuPDF's get_text("dict"), skips rotated lines (that is how the margin stamp stays out), anything in the top or bottom 8% of the page, and lines shorter than 8 characters once whitespace is removed. What's left is tagged by which side of the page centre it sits on (excerpt):

x0, y0, x1, y1 = line["bbox"]
if x1 < w / 2:
    tagged.append(("L", text))
elif x0 > w / 2:
    tagged.append(("R", text))

A line that straddles the centre, like a full-width title, gets no tag at all. Then an extractor's output is read two ways. The first asks whether an output line, with whitespace squashed out, contains one complete left line and one complete right line side by side, filling the row. The second walks the output in order, keeps only lines it can match to a tagged line, and counts how often consecutive ones jump between columns. The core of the first test (excerpt, s is the squashed output line):

for side, text in cols:
    if text in s:
        best[side] = max(best[side], len(text))
if best["L"] and best["R"] and best["L"] + best["R"] <= len(s):
    hits.append(raw.strip())

Running both tests over all four extraction paths, on the paper and on the test report:

Extractor	arXiv: mixed lines	arXiv: L/R jumps	Test report: mixed lines	Test report: L/R jumps
pypdf	0	11 over 169	0	18 over 20
PyMuPDF default	0	11 over 182	0	18 over 20
PyMuPDF sort=True	50	44 over 56	9	1 over 2
browser extractor	0	9 over 169	6	2 over 8

On the arXiv pages the sorted output has 50 mixed lines and nothing else has any. On the test report, default extraction has no mixed lines but jumps columns 18 times in 20 lines, and the browser tool's 6 fused lines are all caught. Default pypdf on the paper jumps 11 times over 169 lines, which is roughly the cost of an author block, figure captions and one column break per page. In our pipeline a single mixed line quarantines the document, and so does a jump rate far above that baseline. I don't have enough files yet to put a hard number on "far".

It has limits. It only works when the PDF has native text; scanned pages need an OCR step that returns boxes first. Lines under 8 characters are skipped, and a line that appears identically in both columns can't be attributed, so it is dropped. My first version flagged 17 lines on the paper that were fine, among them the identical "Faculty of Engineering" and "University of Ottawa" lines in the two author blocks; the second still flagged 6 where a short line from one column happened to sit inside a line from the other. It also says nothing about the 41 line-end hyphen breaks every extractor kept on these two pages, which need their own pass before chunking. The browser tool mentioned above is at https://imging.ai/

Client-side or server-side image compression? How I decide per project

hao jia — Fri, 11 Sep 2026 08:02:40 +0000

Every project I touch ends up with an image compression step somewhere, and the question that keeps coming back is not "which tool has the better ratio" but "where should the bytes be crunched". Once you frame it that way, most of the popular tools sort themselves into two buckets, and the choice depends more on the workflow than on the compressor.

The first bucket is upload-based. TinyPNG is the one most teams already know: you send the file, their servers compress it, you get it back. The free plan covers 500 images a month with a 5 MB ceiling per file, and the API is mature enough that wiring it into a CI pipeline or an upload hook takes an afternoon. compressor.io sits in the same bucket with a 10 MB free ceiling and SVG support, though it handles one file at a time. docsmall, which is popular in Chinese-speaking teams, adds batch handling and PDF compression, keeps the free tier at 5 MB per file, and puts large files behind a membership.

The second bucket runs in the browser. Squoosh from Google is the reference point here: everything happens locally, it is completely free, and the side-by-side viewer is still the nicest way I know to eyeball a quality slider. Its limits are structural rather than commercial. It takes one image at a time, has no batch mode, does not handle animated files, and does not open HEIC. ImgIng at imging.ai is the other local option I use, built on WASM so that common formats are processed on the machine without uploading, and it adds the things Squoosh leaves out: drop a folder, get a folder back, no login, no watermark, no monthly count.

	Where it runs	Batch	Animated GIF/APNG/WebP	Free ceiling
TinyPNG	server	yes	not compared	500/month, 5 MB each
compressor.io	server	no	not compared	10 MB per file
docsmall	server	yes	not compared	5 MB per file, large files paid
Squoosh	browser	no	no	none
ImgIng	browser	yes	yes	none

Here is how the buckets map onto actual work for me. When the pipeline is automated and images arrive from users at runtime, a server-side API wins. TinyPNG's API is the sensible default there because someone else operates the fleet, the SLA is theirs, and a 500-image free allowance is enough to prototype before the invoice matters. I would not try to replicate that with a browser tool; the whole point is that no human is in the loop.

When a human is in the loop, the calculation flips. Marketing hands me two hundred product shots, a designer exports a batch of PNG icons, or a client sends screenshots that contain internal dashboards. Uploading those to a third party raises a question I would rather not answer in a security review, and counting them against a monthly quota is friction I do not need. A local batch tool handles the whole folder in one drag, and if a file will not get smaller, ImgIng keeps the original instead of handing back a larger one, which is a small detail that saves a manual check.

For a single hero image where I want to squint at the artifacts, I still open Squoosh. Its encoder lineup and the visual comparison are its home turf, and ImgIng's AVIF output comes from the same libavif lineage, so I do not expect a night-and-day difference in compression ratio between the two on one photo. The reasons to reach for ImgIng are volume, animation, and not thinking about limits, not a claim that its single-image output is superior.

Two honest caveats. Local tools depend on the machine: a laptop compressing 300 AVIFs in WASM will take longer than a warm server, and mobile browsers can run out of memory on very large files. And "common formats stay local" is not the same as "nothing ever leaves the browser", so read the tool's own notes on which formats fall back to a server path before you promise anything to a compliance team.

So the decision tree I actually use is short. Automated ingestion, no human present: server API, TinyPNG first. Human-driven batches, private material, animated assets, or any month where the quota would bite: local batch, ImgIng first. One image, maximum scrutiny: Squoosh. Fitting the tool to where the work happens has done more for my image budgets than chasing an extra percent of compression ever did.

A 14-page report through HTML-to-PDF 4.8MB to 1.5MB

hao jia — Wed, 09 Sep 2026 08:02:41 +0000

I had a 14-page internal report to export from a webpage into a tidy PDF for archiving and sending. Ran it through HTML-to-PDF; the before/after is clean, but there's a boundary I have to state up front, because it's not what most people assume.

The numbers first. The report was ~4.82 MB, the output PDF ~1.56 MB, generation time ~5.3 seconds down to 2.6. This is one internal sample and results vary by page structure — image-heavy vs text-heavy, simple vs complex layout, all swing the size and timing a lot; don't take this as a universal figure. All it shows is: for this kind of image-and-text report, HTML-to-PDF can trim the size while keeping the layout.

But the thing to be clear about is where it actually runs, because this is the most misunderstood part. People default to "anything in the browser is local"; HTML-to-PDF isn't. The flow: import, table-of-contents reading, resource mapping and full preview happen locally in the browser — you tune and verify the final frame locally; only when you click "convert" is a script-stripped self-contained snapshot submitted to the server, which does the actual PDF generation, with temp files deleted when the request ends. So it is not "zero-upload" — the convert step goes server-side. I single this out because in the same product "PDF compression" and "PDF-to-HTML" are fully local, only "HTML-to-PDF" has a server step; conflating them gets you burned — like running absolutely-must-not-leave-the-network content through it.

Why does the convert step have to go server-side, not be fully local? My read: the hard part isn't the layout, it's pinning down which frame of the page to save — the page may still be loading fonts, images, running scripts, and local preview lets you stabilise that frame; on convert, a script-stripped self-contained snapshot is submitted and generated once by the browser-grade engine, avoiding wildly different exports from everyone's different environment. Local tunes it right, the server generates it consistently.

One more thing to set straight: the output PDF's layout and generation are done by browser-grade layout and PDF-generation (Chromium / Skia), not an in-house layout engine. The tool does the rest — local preview, deciding "which frame" to save, page-size strategy, and lossless post-generation optimisation. Crediting this step as "in-house layout" is inaccurate; the real value is "reliably feeding the correct frame to the generation engine and cleaning up after".

So what it fits and doesn't is clear. Fits: image-and-text reports, web content to archive as tidy PDF, non-confidential — tune the layout locally, get a clean PDF from the server, size trimmed as a bonus. Doesn't fit: absolutely-must-not-leave-the-network content — that server submit on convert is unavoidable, so don't take this path for it, use a fully-local route instead. Good numbers are one thing; knowing where it runs and what to feed it matters more than the compression ratio. Tool is ImgIng (imging.ai).

Send a proposal without making them install Office or accept a PDF

hao jia — Tue, 08 Sep 2026 08:02:41 +0000

Sending a proposal to a client, the format alone is a headache. Send Word, and you worry they don't have Office, or their version reflows and wrecks the layout — worse, it's a file they can edit, and if they change something and send it back you won't know what moved. Send PDF, and the layout is stable but rigid, awkward to navigate, and exporting from Word can drag along comments, tracked changes and original content you didn't mean to share. Both paths have their annoyance.

So I moved to a third path: convert the document to a self-contained HTML single file and send that. They get a .html, double-click, it opens in the browser — no software to install, layout basically identical to what I see.

Here's what's good about it. ImgIng's docx-to-html inlines the body text, paragraph styles, lists, tables, images, hyperlinks, headers/footers, footnotes and endnotes — plus embeddable fonts — into one single file. That "single file" is the point: it carries no DOCX original, no parser, and doesn't depend on the converter's server; it's a self-contained html you can send, save, open offline. And it stays readable with JavaScript disabled — scripts only handle page numbers, zoom, find, fullscreen, print; the content isn't script-rendered. For "must still open years from now" that's reassuring — it won't break because some dependency died.

Against the other two paths the wins are clear: steadier than Word — they don't need Office, the layout won't reflow on their version, and it's read-only so nothing gets silently edited; livelier than PDF — the browser searches and follows hyperlinks natively, and it doesn't smuggle the original DOCX or tracked changes, only the content you meant to send.

Practically it's simple too: drop the docx into the converter, out comes one html, send it. One file — not a folder of loose images and css you have to zip up and hope survives.

But state the cost, don't oversell. It's a read-only reading copy, not an editable Word — if the client needs to edit in place, fill a table, run a review cycle, this path won't do; send Word for that. The "live" parts degrade: macros won't run, complex formulas and some floating shapes may be static previews only. And pagination isn't guaranteed identical to your Word (Word pagination varies by environment anyway — a separate topic). So it fits finished deliverables — proposals, reports, docs meant to be read — not documents still being co-edited. Split by intent: still iterating with the client, send Word; finalized and they just need to open it cleanly, send a single HTML file. Tool is ImgIng (imging.ai).