DEV Community: BellSal

Free PDF tools paywall the one button that matters. Here's why — and how I avoided it

BellSal — Fri, 21 Aug 2026 18:25:37 +0000

Almost every "free" PDF tool lets you merge, split, rotate and reorder pages for free — and then puts a paywall on the one button you actually came for: Export. I got annoyed enough to build a PDF toolkit that doesn't, so here's the honest technical reason it happens and what it takes to avoid it.

Reading a PDF is cheap. Writing a valid one back is not.

Rendering a PDF to show it on screen is a solved, cheap problem — the browser and a dozen libraries do it. The expensive part is going the other way: taking your edits and serializing a spec-valid PDF back out. The PDF format is a cross-referenced object graph with an xref table, object streams, and byte-offset bookkeeping that has to stay internally consistent or the file won't open.

That asymmetry is why so many tools happily show you a preview and let you rearrange thumbnails, then charge at export: the preview is free, the write-out is the work.

The second reason: they uploaded your file to do it

The other common pattern is a server round-trip. Your document goes up to their backend, a headless tool (Ghostscript, a licensed SDK, LibreOffice) does the manipulation, and the result comes back. That costs them real money per file — CPU, bandwidth, storage — which is exactly why it eventually needs to cost you money, and why the free tier is capped at "3 files a day."

For a contract, an ID scan, or a payslip, silently shipping the document to someone's server is also a privacy problem people don't think about until later.

Doing it client-side with pdf-lib

The fix for both problems is the same: never upload, and do the write-out in the browser. pdf-lib is the key piece — it can create and modify existing PDFs entirely in JS, including the parts that are annoying to get right:

import { PDFDocument } from 'pdf-lib';

// merge: copy pages between documents, re-embedding fonts/resources
const out = await PDFDocument.create();
for (const bytes of files) {
  const src = await PDFDocument.load(bytes);
  const pages = await out.copyPages(src, src.getPageIndices());
  pages.forEach((p) => out.addPage(p));
}
const merged = await out.save(); // valid xref + object streams, in the browser

copyPages is the bit that matters: it deep-copies the page's resource dictionary (fonts, images, shared objects) into the target so the merged file is actually valid, not just concatenated bytes. The same document model handles split, extract/remove/reorder, rotate, N-up, page numbers and watermarks — all as object-graph edits, then one save().

A few things that bite:

Compression / grayscale aren't first-class in pdf-lib; you work at the content-stream and image-XObject level, which is fiddly but keeps it local.
OCR (making a scanned PDF searchable) needs a separate WASM engine (Tesseract) — heavy, so lazy-load it only when the user actually asks.
Editing existing body text is the one thing you genuinely can't fake: PDF has no reflowable text model, so "change the words" still means a real editor like LibreOffice Draw. Be honest about that limit instead of pretending.

Why bother

Client-side means the file never leaves the device, there's no per-file server cost, so the export can just be free — permanently — and static hosting keeps it that way. That's the whole reason pdfonlinefree.com exists: merge, split, compress, sign, OCR, unlock, page numbers, watermark, JPG↔PDF — export included, nothing uploaded.

If you're building something similar: put the expensive write-out in the browser, lazy-load the WASM parts, and don't paywall the button people came for.

I added gravity to a block puzzle to make players take risks — here's the design logic

BellSal — Thu, 20 Aug 2026 19:15:56 +0000

Block puzzles have a math problem: the optimal strategy is almost always the safe one. Place each piece to keep the board as open as possible, clear a line when it's free, never gamble. It's solvable on autopilot, and autopilot is boring. I wanted a mechanic that made the greedy, risky play the exciting one — without turning it into luck. Here's what I landed on and why.

The mechanic: streaks trigger gravity

The rule is one sentence: clear lines on consecutive turns, and at streak 3+ gravity switches on — every remaining block falls to the bottom, and whatever new lines that forms clear too, chaining into cascade combos.

That one rule flips the incentive. Normally you clear a line the moment you can, to stay safe. But now, breaking your streak to make a safe clear costs you the gravity payoff. So the interesting question becomes: do I take the small safe clear now, or hold the streak one more turn for a cascade that could clear half the board? That tension is the whole game.

Why cascades, specifically

Cascades solve two problems at once:

They reward planning without requiring perfect play. You don't have to calculate the exact cascade — you just have to keep the streak alive and stack toward the bottom. The gravity does the satisfying part. That keeps it accessible while still having depth.
They create "juice" for free. A cascade is a chain reaction: one clear causes a fall causes another clear. Chain reactions feel great with almost no extra design — the game does something bigger than the move you made. That dopamine hit is what makes people play "one more round."

The trap I avoided: making the cascade random. If gravity dropped blocks in unpredictable ways, it'd feel like a slot machine and players would stop trusting their decisions. Gravity here is fully deterministic — same board, same fall, every time. The skill is in setting it up.

Difficulty comes from the board, not from speed

A cheap way to add difficulty is to speed things up until the player's reflexes fail. I didn't want that — it punishes older or casual players and it's not interesting difficulty. Instead the pressure comes from obstacles that change how the board behaves:

Asteroids take two hits to clear, so they clog a line you were counting on.
Ice blocks freeze in place and can't move, forcing you to route around them.
Reward cubes drop a power-up when destroyed, so there's a reason to want to clear a spot you'd otherwise avoid.

Each of these makes you re-plan rather than react faster. Difficulty as a puzzle, not as a stopwatch.

Modes as difficulty curves, not content padding

Same core rules, four framings:

Zen — no timer, no fail state, no ads. This is the mode people actually relax with, and it's the one I'd defend hardest. A puzzle game needs a mode where the game isn't trying to extract anything from you.
Timed — the streak tension plus a clock, for people who want the pressure.
Endless — score-chasing, where cascades compound.
Daily — one fixed board for everyone, which turns a solo puzzle into a shared conversation ("did you get the triple cascade on today's?").

The lesson: modes aren't content, they're difficulty and mood curves over the same ruleset. One mechanic, four audiences.

The takeaway for anyone building a puzzle game

If your puzzle has one obvious optimal strategy, players will find it and leave. The fix isn't more content — it's a single mechanic that makes the risky line competitive with the safe one, and that pays off in a way the game animates for you. For me that was streak-triggered gravity. Make the greedy play tempting, keep the payoff deterministic so it stays skill, and let obstacles — not speed — carry the difficulty.

The game is Cosmo Blocks (iOS here) — disclosure, it's mine, and everything above is the actual design running in it. Free, and Zen mode has no ads if you just want to see the cascade thing without a timer breathing on you.

Shipping a Flutter arcade game to both app stores with AdMob and consent — 4 things that bit me

BellSal — Thu, 20 Aug 2026 18:10:14 +0000

I built a small arcade puzzle game in Flutter and shipped it to Google Play and the App Store from one codebase. The gameplay was the easy part. Monetizing it with ads without making the game feel like a slot machine, and getting the privacy consent right, is where the real work hid. Here are the four things that actually broke.

1. The interstitial that showed up at the worst possible moment

The naive way to add an interstitial is: game over, show ad. Ship that and players hate you, because the ad fires the instant they die — before they've even processed the loss — and again on every single retry.

Two rules fixed it:

Never on the first game over. A new player who eats a fullscreen ad ten seconds in just uninstalls. Gate it behind a play counter.
Rate-limit it in wall-clock time, not by count. Track the timestamp of the last interstitial and refuse to show another within N minutes, regardless of how many times the player died.

DateTime? _lastInterstitial;
int _gameOvers = 0;

bool _canShowInterstitial() {
  _gameOvers++;
  if (_gameOvers < 3) return false; // let them settle in first
  final last = _lastInterstitial;
  if (last != null && DateTime.now().difference(last) < const Duration(minutes: 2)) {
    return false;
  }
  return true;
}

The counter and timestamp both have to persist, or a player who force-quits between rounds sees an ad every launch.

2. Consent has to run before the first ad request, not alongside it

If you serve ads in the EU/UK you need a consent flow (Google's User Messaging Platform, UMP). The mistake I made first: kicking off consent and ad initialization in parallel at startup. That's a race. Sometimes the first banner requested before consent resolved, which is exactly the thing the consent form exists to prevent.

The correct order is strictly sequential: request the consent info, load and show the form if required, and only after that initialize the Mobile Ads SDK and request anything.

final params = ConsentRequestParameters();
ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
  if (await ConsentInformation.instance.isConsentFormAvailable()) {
    await _loadAndShowConsentFormIfRequired();
  }
  // ONLY now:
  await MobileAds.instance.initialize();
  _loadBanner();
}, (error) { /* fail open: init ads without personalization */ });

Test it by forcing an EEA geography in the UMP debug settings, not just on your own device in your own country — otherwise you'll never see the form and think it works.

3. The rewarded video that closed early left players stuck

I used a rewarded ad to grant an extra life. The bug: if the user dismisses the ad early, the "reward earned" callback never fires, but my code was waiting on it to resume the game. Result: a dead screen.

The fix is to treat earned and closed as two independent events, and always have a path forward on dismissal:

bool earned = false;
ad.fullScreenContentCallback = FullScreenContentCallback(
  onAdDismissedFullScreenContent: (ad) {
    ad.dispose();
    earned ? _grantExtraLife() : _returnToGameOver(); // never just hang
  },
);
ad.show(onUserEarnedReward: (_, __) => earned = true);

Race conditions around ad lifecycle callbacks are the single most common source of "the game froze" reports. Assume every callback might not fire.

4. Test ads in debug, real ads only in release — enforced by the build, not by memory

The classic disaster is shipping a build that still points at test ad unit IDs (zero revenue) — or worse, developing against your real units and getting flagged for invalid traffic by clicking your own ads.

Don't rely on remembering to swap IDs. Wire it to the build mode:

const bannerUnitId = kReleaseMode
  ? 'ca-app-pub-REAL/REAL'
  : 'ca-app-pub-3940256099942544/6300978111'; // Google's official test ID

Debug and profile builds physically cannot serve real ads; release builds physically cannot serve test ads. It's one line and it removes an entire category of mistake.

The takeaway

None of this is about ad revenue being high — for a free game it rarely is. It's that the difference between a game people keep and one they uninstall in a day is almost entirely in when and how the ads appear, and whether the lifecycle callbacks are handled defensively. Get the pacing and the consent order right and the ads become almost invisible; get them wrong and no amount of good gameplay survives it.

The game this came from is GridZap — an arcade puzzle where you trace grid lines to close squares while enemies chase you (iOS here). Disclosure: it's mine, and every code pattern above is what actually ships in it. Zen of the whole thing: a banner, one interstitial between levels, and an optional rewarded video — nothing more.

Your canvas "A4 export" is not A4: DPI, print size, and the number nobody checks

BellSal — Wed, 19 Aug 2026 22:12:08 +0000

When I added an "A4" preset to a browser-based collage tool, I thought the hard part was the layout maths. It wasn't. The hard part was that "A4" on a canvas is a shape, not a size — and if you don't say that out loud, your users find out at the print shop.

Here is what I got wrong, and the numbers that matter.

A canvas has no physical size

An HTML canvas is a pixel grid. It has width and height in pixels and nothing else. Paper has millimetres. The bridge between them is DPI, and the canvas has no opinion about it.

So when a preset says "A4", all it can honestly promise is the aspect ratio — 1:1.414, the ratio every ISO 216 paper size shares. What those pixels become on paper depends entirely on how many of them you exported.

My preset exports 1414 x 2000 px. That is exactly the A4 ratio. Now convert:

A4 = 210 x 297 mm = 8.27 x 11.69 inches

1414 px / 8.27 in = 171 DPI
2000 px / 11.69 in = 171 DPI

171 DPI. Not 300. For a home or office printer that is genuinely fine — you will not see individual pixels at normal viewing distance. For a photo lab, it is under half the data they expect.

To hit the 300 DPI that print shops assume, the same page needs:

8.27 in x 300 = 2480 px
11.69 in x 300 = 3508 px

2480 x 3508 is 3.1x more pixels than 1414 x 2000. That is the whole trade-off in one line.

Why not just export at 300 DPI then?

Because of memory, and because phones are where people actually use this.

A 2480 x 3508 canvas is 8.7 million pixels. The browser holds it as RGBA, 4 bytes per pixel, so the bitmap alone is about 35 MB before you have drawn anything into it. Now add the source photos: a 12-photo collage where each source is a 12-megapixel phone image is another 576 MB if you keep them all decoded at full size.

That is how you get the crash that only ever happens on someone else's Android phone.

The fix that made this survivable was downscaling every source image on import, before compositing:

const MAX_SOURCE_EDGE = 2400;

function fitSource(img) {
  const longest = Math.max(img.width, img.height);
  if (longest <= MAX_SOURCE_EDGE) return img;
  const scale = MAX_SOURCE_EDGE / longest;
  const c = document.createElement('canvas');
  c.width = Math.round(img.width * scale);
  c.height = Math.round(img.height * scale);
  c.getContext('2d').drawImage(img, 0, 0, c.width, c.height);
  return c;
}

A source image never needs more pixels than the region it will occupy in the output. If a photo lands in a quarter of a 1414 x 2000 page, anything beyond ~1000 px on its long edge is decoded, held in memory, and then thrown away by the scaler. Capping the long edge at 2400 px costs nothing visible and removes most of the memory pressure.

Worth knowing: iOS Safari also caps total canvas area (historically around 16.7 million pixels on older devices). Exceed it and you don't get an exception — you get a blank canvas. Silent failure is the theme of this whole area.

The part that is not technical

None of the above is what users complain about. They complain because they expected "A4" to mean "this will print correctly", and nobody told them otherwise.

So the fix that mattered most was a sentence in the UI, not a line of code: say the export size in pixels, say roughly what DPI that is at A4, and say plainly that it suits a home printer rather than a photo lab. People are completely fine with a limitation they were told about in advance. They are not fine with discovering it after paying for prints.

Two more things worth surfacing while you are at it:

Printer margins. Most consumer printers cannot print to the edge and will shrink or crop your page to fit their unprintable margin — usually a few millimetres. A layout that looks perfectly centred on screen comes back visibly off-centre. Either design in a safe margin or warn about "borderless" mode.
Orientation. 1414 x 2000 is portrait. Users who want landscape A4 need 2000 x 1414, and if you only ship one, half of them will rotate the image in a photo editor afterwards and lose quality doing it.

The takeaway

If you export anything meant for paper from a canvas, do this arithmetic once and put the result in your interface:

DPI = pixel width / physical width in inches

It takes ten seconds and it is the difference between a tool people trust and one they stop using after a bad print.

The tool this came from is freecollageimage.com — free, browser-only, nothing is uploaded. Full disclosure: it's mine, and the 171 DPI number above is its actual current export, not a hypothetical.

The HTML canvas quietly deletes your photo's metadata — and one day that bites you

BellSal — Tue, 18 Aug 2026 20:05:32 +0000

I build browser-based image tools, and the single most confusing class of bug reports I get all trace back to the same fact: the moment a photo passes through a <canvas>, its metadata is gone. No EXIF, no GPS, no color profile, no orientation flag. The canvas carries pixels and nothing else.

Most of the time that's a feature. Sometimes it's a silent disaster. Here's both sides.

What actually happens

When you draw an image to a canvas and read it back out:

const canvas = document.createElement("canvas");
canvas.width = img.naturalWidth;
canvas.height = img.naturalHeight;
canvas.getContext("2d").drawImage(img, 0, 0);
const out = canvas.toDataURL("image/jpeg", 0.85); // or toBlob

out is a brand-new JPEG encoded from raw pixels. Every ancillary chunk the original file carried — the EXIF block, the IPTC/XMP metadata, the ICC color profile — never existed in the canvas, so none of it makes it into the output. There's no flag to preserve it. The pixels are all the canvas ever had.

The good side: free metadata stripping

This is genuinely useful. If you run a photo through any canvas-based compressor, resizer or format converter, the output is automatically clean:

The GPS coordinates that say where you took the photo? Gone.
The camera serial number, the timestamp, the "edited by X"? Gone.
The little privacy leak that is a raw phone photo? Gone.

So a browser tool that re-encodes an image is also, for free, a metadata stripper — whether or not that's advertised as the point. I lean on this on purpose: "compress this image" and "scrub this image before I post it" become the same operation, done locally, with nothing uploaded.

One caveat worth stating loudly: this only protects you if the tool processes locally. If the page uploads your file to a server to do the work, you've handed the metadata to that server on the way to deleting it. "Runs in the browser" is the part that matters, not "strips EXIF."

The bad side: the orientation bug that eats an afternoon

Here's the one that generates the confused bug reports. iPhones (and many other cameras) don't rotate the pixels when you turn the phone. They store the image in the sensor's native orientation and set an EXIF Orientation flag — "display this rotated 90°." Your photo viewer reads that flag and rotates on display. The pixels themselves are sideways.

Now send that image through a canvas. The canvas draws the raw pixels — sideways — and the orientation flag, like all metadata, is dropped. Your output is a photo that is now permanently rotated the wrong way, with no flag left to correct it.

The infuriating part is that it looks fine in your <img> preview, because the browser applied the orientation flag when it displayed the original. It only breaks after the canvas round-trip. So the user sees a correct preview, downloads the result, and it's rotated. Classic "works on my screen."

The fix, since 2020-ish, is one line. Tell the browser to bake the orientation into the pixels when it decodes:

const bitmap = await createImageBitmap(file, { imageOrientation: "from-image" });
// now draw `bitmap` to the canvas — pixels are already upright

Or, if you draw an <img> element instead, CSS image-orientation: from-image (the default in modern browsers) fixes the display — but not what drawImage reads. drawImage still takes the raw pixels. So for canvas work, createImageBitmap with imageOrientation: "from-image" is the reliable route. Test it with a portrait photo taken on a phone held sideways; a landscape screenshot will never reveal the bug.

The rule I settled on

Two sentences I now keep in my head whenever a canvas touches user images:

Assume all metadata is lost the instant you drawImage. If you need to keep any of it (orientation, color profile, a copyright tag), handle it explicitly before the round-trip — don't hope it survives, it won't.
Treat the loss as a privacy win only if the processing is local. Uploading to strip is theatre.

If you want to see both sides in practice, both tools are mine and free: an EXIF viewer to see exactly what your photos are carrying, and the compressor that drops all of it while it shrinks the file — both running entirely in the browser, nothing uploaded.

One codebase, one website, two app stores: what Capacitor actually costs you

BellSal — Mon, 17 Aug 2026 14:44:05 +0000

My photo collage editor was a static site: vanilla JS, a canvas, no framework. Putting it on the Play Store and the App Store with Capacitor took a weekend of work and about three weeks of small surprises. The surprises are the interesting part, so here they are.

Don't ship the website inside the app

The instinct is to point Capacitor at your existing web root and be done. Don't. A website root contains a pile of things that make no sense inside an app and some that will actively hurt you: sitemap.xml, robots.txt, a service worker, a cookie consent script, landing pages, llms.txt.

I ended up with a build step that generates a separate app-only bundle. It copies the public folder while filtering out every .html file and an explicit deny list of site-only assets, then rebuilds a single index.html from a native shell template:

const siteOnlyFiles = new Set([
  "ads.txt", "consent-tracking.js", "home-seo.js", "llms.txt",
  "manifest.webmanifest", "pwa.js", "robots.txt",
  "service-worker.js", "sitemap.xml", "social-preview.png"
]);

fs.cpSync(publicDir, outputDir, {
  recursive: true,
  filter(source) {
    if (source === publicDir) return true;
    const name = path.basename(source);
    if (siteOnlyFiles.has(name)) return false;
    return path.extname(name).toLowerCase() !== ".html";
  }
});

Then it pulls the editor markup out of the website's homepage by slicing between two known markers and injects it into the native template:

const workspaceStart = siteHtml.indexOf('<section class="workspace editor-workspace"');
const workspaceEnd = siteHtml.indexOf('<section class="content-band">', workspaceStart);

if (workspaceStart < 0 || workspaceEnd < 0) {
  throw new Error("Could not extract the shared collage editor from index.html.");
}

Yes, this is string-slicing HTML, and yes, that is usually a terrible idea. The reason I kept it: the throw turns a refactor of the homepage into a failed build rather than an app that ships with an empty screen. A brittle step that fails loudly beats a clever one that fails silently. If you do this, make the failure mode explicit.

The word "free" can get your build flagged

This one I did not see coming. My translation file is shared between the site and the app, and the site copy says things like "free, no signup, no watermark" because that is what the landing page is selling.

Store metadata scanners read the strings inside your bundle. Price language in shipped assets is a good way to get a conversation you don't want with a review team. The build step now rewrites those specific strings for the packaged version: the app says "Create photo collages", the website keeps its copy.

If you share an i18n file between a marketing site and an app, audit it for price and promotional wording before you submit.

The download button that does nothing

The single biggest functional break. On the web, saving the collage was an <a download> pointing at a data URL. In an Android WebView that silently does nothing: no error, no console warning, no download. The button just doesn't work.

The fix was a small native plugin that writes to MediaStore, plus a shim that intercepts the anchor click so the shared editor code never has to know which environment it's in:

var originalClick = HTMLAnchorElement.prototype.click;
HTMLAnchorElement.prototype.click = function () {
  if (this.download && /^data:image\//.test(this.href || "")) {
    saveDataUrl(this.href, this.download);   // native plugin -> MediaStore
    return undefined;
  }
  return originalClick.apply(this, arguments);
};

Monkey-patching a DOM prototype is not something I'd normally advocate, but the alternative was branching every save path in shared code. I wrote about that bug in more detail in an earlier post.

Capacitor 8 wants JDK 21, and your machine probably has 17

My system JAVA_HOME pointed at JDK 17, which produced a Gradle error that does not obviously say "wrong Java version". The build script now finds a JDK 21 itself (Android Studio bundles one in jbr) and only falls back to JAVA_HOME after verifying it actually is 21:

function isJdk21(dir) {
  const out = execFileSync(path.join(dir, "bin", "java.exe"), ["-version"], {
    encoding: "utf8", stdio: ["ignore", "pipe", "pipe"]
  });
  return /version "21|openjdk 21|build 21/.test(out);
}

Checking the version instead of trusting the variable took ten minutes and has saved me the same debugging session at least three times.

Debug builds must force test ads

If you monetise with AdMob, tapping your own real ad while testing on your own phone is a policy violation. Rather than remembering not to tap things, the debug build rewrites the ad config in the generated bundle:

if (mode === "debug") {
  for (const name of ["admob.js", "premium.js"]) {
    const file = path.join(root, "android-web", name);
    fs.writeFileSync(file,
      fs.readFileSync(file, "utf8").replace("IS_TESTING: false", "IS_TESTING: true"));
  }
}

Make the safe thing automatic, because you will forget.

You don't need a Mac for the iOS build

I built and shipped the iOS version from a Windows machine. Codemagic runs the Mac, and the whole config is short enough to read in one screen:

workflows:
  ios-release:
    instance_type: mac_mini_m2
    environment:
      node: 22
      ios_signing:
        distribution_type: app_store
        bundle_identifier: com.example.app
    scripts:
      - script: npm ci
      - script: npm run build:android-web
      - script: npx cap sync ios
      - script: xcode-project use-profiles
      - script: |
          xcode-project build-ipa --project ios/App/App.xcodeproj --scheme App
    publishing:
      app_store_connect:
        auth: integration
        submit_to_testflight: true

One gotcha: running npx cap sync ios on Windows rewrites paths in Package.swift in a way that macOS won't accept. Let the CI machine do the iOS sync and don't commit the result from Windows.

Was it worth it?

For a canvas-based tool with no server, yes. The editor is genuinely the same code in all three places, and a bug fix ships everywhere. The cost was not the packaging, it was the seams: file saving, ad policy, store metadata, and a build pipeline that now has opinions about which files belong where.

What I would tell past me: budget your time for the platform boundaries, not for the port. The port is a weekend. The boundaries are the rest of the month.

The result, if you want to poke at it: freecollageimage.com, and the same editor as an Android app and an iOS app. All mine, all free.

Why HEIC breaks every browser-based image tool, and what it costs to fix

BellSal — Sun, 16 Aug 2026 14:00:40 +0000

Every image tool that runs in the browser hits the same wall eventually: someone drops in a photo straight off an iPhone and nothing happens. No error, no preview, no conversion. The file is HEIC, and the browser has no idea what to do with it.

This is worth writing up because the workarounds people reach for first are all wrong in interesting ways.

Why the browser can't help you

HEIC is a HEIF container holding HEVC-encoded image data. HEVC is patent-encumbered, and that has kept it out of browsers: Chrome, Firefox and Edge cannot decode it. Safari can, because Apple already licenses HEVC for the rest of the platform — which is exactly why this bug is invisible if you develop on a Mac and test in Safari.

So the usual pipeline just fails:

const img = new Image();
img.src = URL.createObjectURL(file);
await img.decode();   // rejects on HEIC in Chrome, works in Safari

img.decode() rejects with a decode error. canvas.drawImage() on a never-loaded image draws nothing. If you're not awaiting the decode, you get a silently blank canvas instead of an exception, which is worse.

The trap: renaming the extension

Users do this constantly, and so do developers when they're debugging in a hurry. Renaming IMG_4021.HEIC to IMG_4021.jpg changes nothing — the bytes are still HEIF, and anything that sniffs the actual content rejects the file. Reddit, most upload forms and every real decoder look at magic bytes, not at the name.

If you want to detect HEIC properly, read the header. The ftyp box sits at offset 4 and the brand tells you what you have:

async function isHeic(file) {
  const head = new Uint8Array(await file.slice(0, 12).arrayBuffer());
  const boxType = String.fromCharCode(...head.slice(4, 8));   // 'ftyp'
  const brand   = String.fromCharCode(...head.slice(8, 12));  // 'heic','heix','mif1','msf1'
  return boxType === 'ftyp' && /^(heic|heix|hevc|mif1|msf1)$/.test(brand);
}

Do not rely on file.type for this, which brings us to the second trap.

`file.type` is often an empty string

This one cost me a long time. Files arriving from iOS — through the share sheet, some pickers, occasionally AirDrop — frequently have file.type === ''. Not image/heic, not image/jpeg. Nothing.

Which means the validation almost everyone writes first silently rejects perfectly good photos:

// rejects real images from iPhones
if (!file.type.startsWith('image/')) return reject('Not an image');

The user sees a file they know is a photo being refused as "not an image", and there is nothing in the console to explain it. The fix is to treat an empty type as unknown rather than as invalid, and fall back to the extension or the header:

const looksLikeImage =
  file.type.startsWith('image/') ||
  (file.type === '' && /\.(jpe?g|png|webp|gif|heic|heif)$/i.test(file.name));

What decoding actually costs

If your tool's whole premise is that files stay on the device, you can't punt HEIC to a server. So you ship a decoder to the client — usually libheif compiled to WebAssembly, via libheif-js or heic2any.

It works. It is also the single heaviest thing in the bundle: a few hundred kilobytes of WASM that the vast majority of visitors will never need, because most people aren't uploading HEIC. Loading that eagerly to serve a minority is the wrong trade.

Lazy-load it behind the detection above, so the cost only lands on the users who actually have a HEIC file:

async function toJpegBlob(file) {
  if (!(await isHeic(file))) return file;              // no decoder needed
  const { default: heic2any } = await import('heic2any');  // fetched now, not at boot
  return heic2any({ blob: file, toType: 'image/jpeg', quality: 0.9 });
}

Two things worth knowing once it runs. Decoding is CPU-bound and blocks the main thread — a 12-megapixel photo can freeze the tab for a noticeable moment, so a Web Worker is worth the trouble if you handle batches. And Live Photos are HEIC files with multiple images inside; most decoders hand you the primary one, which is usually what people expect, but not always what they wanted.

Orientation, since you're already here

HEIC photos carry EXIF orientation, and once you've decoded to a canvas that metadata is gone. Portrait photos come out sideways. If you decode to a bitmap yourself, apply the rotation before export; createImageBitmap accepts { imageOrientation: 'from-image' } for exactly this.

The shape of the problem

Every failure here is silent. A rejected decode with no catch, an empty MIME type that reads as invalid, a renamed file that looks converted, an orientation tag dropped on the floor. Nothing throws, and the user just sees a tool that doesn't work with their photos.

That's the general lesson, and it's the same one I ran into with the mobile save button: the platform boundaries — file types, downloads, share sheets, permissions — are where things fail quietly, and where checking the outcome on a real device matters more than reading the code.

For context, this came out of building imageonlinefree.com, which converts HEIC locally. The failure modes are the transferable part.

What actually breaks when you process PDFs in the browser

BellSal — Sat, 15 Aug 2026 20:38:57 +0000

Doing PDF work entirely in the browser is a nicer story than it sounds. pdf-lib loads a document from an ArrayBuffer, gives you pages as objects, and hands back bytes — no server, no upload, no retention policy anyone has to trust. The happy path is about fifteen lines.

The unhappy paths are where the actual engineering is, and none of them announce themselves. Here are the four that cost me the most.

Encrypted PDFs can't be modified, and most tools lie about it

This is the one that generates support emails.

A PDF can carry two different passwords. A user password stops you opening the file at all — obvious, and users understand it. An owner password lets anyone open and read the document while restricting what can be done to it. Files that come out of banks, insurers and government portals very often have one, and nothing in the viewer tells you.

pdf-lib will refuse to load such a document:

import { PDFDocument } from 'pdf-lib';

try {
  const pdf = await PDFDocument.load(bytes);
} catch (err) {
  // "Input document to `PDFDocument.load` is encrypted."
}

There is an ignoreEncryption: true option, and it is a trap. It gets you past the exception, and the object you get back is structurally incomplete. Merge it with another document and you produce a file that opens to blank pages, or doesn't open at all. The operation "succeeded" and the output is garbage.

Plenty of online PDF tools take exactly that shortcut. You upload a protected file, the spinner runs, you get a download, and the result is broken — with no explanation, because from the tool's point of view nothing failed.

The honest handling is to detect the condition and say so:

let pdf;
try {
  pdf = await PDFDocument.load(bytes);
} catch (err) {
  if (String(err).includes('encrypted')) {
    throw new UserFacingError(
      'This PDF is password-protected and cannot be modified. ' +
      'Remove the protection in the application that produced it, then try again.'
    );
  }
  throw err;
}

It's a worse-looking outcome and a much better one. "I can't do this, here's why" beats a corrupted file every time.

The memory ceiling is real, and it kills the tab silently

Everything lives in the tab. The original ArrayBuffer, the parsed object graph, the serialised output — at peak you are holding several copies of the document at once. A 300-page scan at 300 dpi is a few hundred megabytes before you've done anything useful, and on mobile the tab just dies. No exception you can catch, no onerror, nothing to report. The page is simply gone.

So the size guard has to come before parsing, not after:

const MAX_BYTES = 100 * 1024 * 1024;

if (file.size > MAX_BYTES) {
  throw new UserFacingError(
    `This file is ${(file.size / 1048576).toFixed(0)} MB. ` +
    `Browser memory tops out well below that — PDFsam or Stirling PDF on your desktop ` +
    `will handle it comfortably.`
  );
}

Naming a tool that does the job better is not a defeat. Someone with a 400 MB scan is not going to be served by any browser, and pretending otherwise wastes their afternoon.

Two things that help below the ceiling: process sequentially rather than loading every input at once, and drop references as you go so the collector can actually reclaim them. Merging ten files one at a time uses a fraction of the peak of merging them in parallel.

"Compress this PDF" means two completely different jobs

Users ask for one thing and mean one of two, and the difference decides whether you can help at all.

If the PDF came from a scanner, there is no text inside it — there's a photograph per page. Ninety-five percent of the weight is images, and compression works spectacularly: re-encoding those images or dropping them from 600 dpi to 200 can take a file down by an order of magnitude, and it stays perfectly readable.

If the PDF was generated from a word processor, the text weighs almost nothing. The size is in embedded fonts and images, and there's very little to win. A tool promising 80% off that kind of file is rasterising it behind your back — turning every page into a picture. The file gets smaller, and the text stops being selectable, searchable and accessible. Most people don't notice until they try to search the document weeks later.

Telling the two apart is cheap. Extract the text; if there's essentially none across the pages, you're looking at a scan:

const looksLikeScan = (extractedChars, pageCount) =>
  extractedChars / pageCount < 50;

Say which one you're dealing with, and what the realistic outcome is. Managing that expectation up front is worth more than any codec.

`pdf-lib` doesn't render, and that surprises people

pdf-lib manipulates document structure — pages, metadata, annotations, form fields. It does not draw anything. If you want thumbnails so users can pick pages before splitting, you need pdf.js, which is a separate library with a separate footprint.

Shipping both is the normal answer, and it roughly doubles what the user downloads before anything happens. Worth loading the renderer lazily, only when a preview is actually requested.

Why do it client-side at all

The honest summary is that it wins on trust and loses on scale.

Every "we delete your files after an hour" promise is a statement about what a company does after receiving your document. It might be entirely true. It's still a promise, and for a signed contract or a medical record that's a decision worth making deliberately rather than by default.

When the work happens in the browser, there's nothing to promise. The request doesn't exist, and anyone can confirm it in ten seconds: open DevTools, Network tab, run the operation, watch nothing leave. That test works on any site, including mine — I run pdfonlinefree.com, which is where all of the above came from.

What you give up is everything that needs real memory or real CPU. Hundred-page scans, batch jobs, OCR. For those, a desktop application is simply the right tool and I'd say so to anyone who asked.

The failure modes are the transferable part. Every one of them is silent by default, and every one of them is a place where the easy implementation reports success while handing the user something broken.

The download button that silently did nothing on mobile

BellSal — Sat, 15 Aug 2026 17:38:15 +0000

For about a year, the save button in my collage editor did nothing on phones. Not "threw an error." Not "downloaded a corrupted file." Nothing at all. You tapped it, the button got its little active state, and then the app just sat there.

Nobody reported it. That's the part that still bothers me. A button that crashes gets a bug report; a button that does nothing gets interpreted as user error. People assumed they'd tapped wrong, tapped again, then left.

The code that looked fine

The editor is vanilla JS drawing to a <canvas>. Everything happens client-side — the images never leave the device, which is the whole point of the thing. So exporting was the textbook approach:

const dataUrl = canvas.toDataURL('image/png');
const a = document.createElement('a');
a.href = dataUrl;
a.download = 'collage.png';
a.click();

This works in every desktop browser. It works in Chrome DevTools' device emulation, which is how it survived so long. It works in a mobile browser often enough that you don't immediately suspect it.

It does not work in an Android WebView, and it does not work in iOS Safari.

The download attribute is a hint, and both of those environments are free to ignore it. An Android WebView has no download manager attached unless the host app wires one up, so the navigation to a data: URL is simply dropped. iOS Safari has historically refused download on data: and blob: URLs from a synthetic click. Neither throws. Neither logs. There is no rejected promise to catch, no event to listen for. The failure mode is a return value of undefined from a function that had one job.

That's what makes this class of bug expensive: you cannot detect it from the JS side. There's no if (downloadWorked). You find it by holding a phone.

Fixing Android: stop pretending it's a browser

The mobile apps are the same editor wrapped in Capacitor, so on Android I had a native layer available and used it. The web code hands the base64 payload to a plugin, and the plugin writes the bytes to shared storage with the platform's own file APIs.

const dataUrl = canvas.toDataURL('image/png');
const base64 = dataUrl.split(',')[1];

await Filesystem.writeFile({
  path: `collage-${Date.now()}.png`,
  data: base64,
  directory: Directory.Documents,
});

Unremarkable, and that's the point. On Android the honest fix was to admit I wasn't in a browser and use the host platform. The user gets a real file in a real folder, which is what they wanted when they tapped save.

Fixing iOS: the Web Share API, and the constraint it doesn't document

iOS has no equivalent escape hatch I was willing to take, so the export goes through the Web Share API instead:

const file = dataUrlToFile(dataUrl, 'collage.png');

if (navigator.canShare && navigator.canShare({ files: [file] })) {
  await navigator.share({ files: [file], title: 'Collage' });
}

Note canShare({ files }) rather than a bare check for navigator.share. Sharing text is widely supported; sharing files is a separate capability, and the feature-detect has to include the payload or it lies to you.

The part that cost me an evening is not in that snippet. navigator.share() requires transient user activation — it must be called during the gesture that triggered it. And that activation is consumed by await. If you write the natural-looking version:

// broken on iOS
button.addEventListener('click', async () => {
  const blob = await new Promise(res => canvas.toBlob(res));
  const file = new File([blob], 'collage.png', { type: 'image/png' });
  await navigator.share({ files: [file] });  // silently dismissed
});

...the share sheet either never appears or flashes and dies. Same signature as the original bug: no error, no console output. The await yielded to the event loop, the activation window closed, and iOS declined without comment.

So the base64-to-File conversion has to be synchronous. canvas.toDataURL() is synchronous, atob() is synchronous, and the File constructor is synchronous — the whole chain can run inside the handler with no yield point:

function dataUrlToFile(dataUrl, filename) {
  const [header, payload] = dataUrl.split(',');
  const mime = header.match(/:(.*?);/)[1];
  const binary = atob(payload);
  const bytes = new Uint8Array(binary.length);

  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }

  return new File([bytes], filename, { type: mime });
}

fetch(dataUrl).then(r => r.blob()) is the prettier version of this function and it is unusable here, because it's async. Same for canvas.toBlob(). The ugly charCodeAt loop exists specifically to stay inside the gesture. For a few megapixels it costs a handful of milliseconds, which is a fine trade for a feature that otherwise doesn't exist.

One caveat worth stating plainly: navigator.share() returning without rejecting does not mean a file was saved. It means the sheet was presented. You cannot tell whether the user picked "Save Image," sent it to a chat, or cancelled — the promise resolves the same way. Some visibility is simply not available to you.

The part I'm not happy about

On iOS the user taps a button labelled save and gets a share sheet, where "Save Image" is one option among Messages, Mail, AirDrop and a dozen apps. That is not a download and does not look like one. It's an extra decision at exactly the moment the user thought they were done.

I shipped it because a share sheet is enormously better than nothing, and because the alternative on iOS was a long-press-to-save instruction nobody reads. But I want to be clear that it's a compromise, not a solution. If you're evaluating this approach: the ceiling is "acceptable," not "good."

A second silent failure, same shape

While I was in there, I found a bug with an identical personality in the analytics setup. Google Consent Mode was initialised with defaults denied — correct and required — but the cookie banner that could flip those defaults only rendered for EU visitors, because that's who the compliance requirement targeted.

Read those two facts together: every visitor outside the EU started denied and was never shown any way to consent. They were permanently invisible in GA4. The site looked close to dead in the reports while it was in fact getting traffic.

gtag's consent defaults take a region parameter, and the fix is to scope the denial to the places where the banner actually exists:

gtag('consent', 'default', {
  ad_storage: 'denied',
  analytics_storage: 'denied',
  ad_user_data: 'denied',
  ad_personalization: 'denied',
  region: [
    'AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU',
    'IE','IT','LV','LT','LU','MT','NL','PL','PT','RO','SK','SI','ES',
    'SE','IS','LI','NO','GB','CH'
  ],
});

With a region array, the directive applies only to those countries; visitors elsewhere fall through to whatever your unscoped default is. You still need a real consent flow for the listed regions — this isn't a way to opt out of the banner, it's a way to stop applying a banner's defaults where the banner never runs.

What actually generalises

Both bugs were invisible to every tool I had pointed at the project. No exception, no failed request, no red line anywhere. They were only visible as an absence: a file that never appeared, a country that never showed up in a report.

So the lesson I took isn't about download attributes or consent strings specifically. It's that anything you hand off to the platform — a download, a share sheet, a permission prompt, a consent signal — can be declined in silence, and your code will happily report success. Those handoffs are where I now check the outcome on a real device rather than trusting the call site.

The editor in question is freecollageimage.com, if the context helps. The bugs are the transferable part.

DEV Community: BellSal

Free PDF tools paywall the one button that matters. Here's why — and how I avoided it

Reading a PDF is cheap. Writing a valid one back is not.

The second reason: they uploaded your file to do it

Doing it client-side with pdf-lib

Why bother

I added gravity to a block puzzle to make players take risks — here's the design logic

The mechanic: streaks trigger gravity

Why cascades, specifically

Difficulty comes from the board, not from speed

Modes as difficulty curves, not content padding

The takeaway for anyone building a puzzle game

Shipping a Flutter arcade game to both app stores with AdMob and consent — 4 things that bit me

1. The interstitial that showed up at the worst possible moment

2. Consent has to run before the first ad request, not alongside it

3. The rewarded video that closed early left players stuck

4. Test ads in debug, real ads only in release — enforced by the build, not by memory

The takeaway

Your canvas "A4 export" is not A4: DPI, print size, and the number nobody checks

A canvas has no physical size

Why not just export at 300 DPI then?

The part that is not technical

The takeaway

The HTML canvas quietly deletes your photo's metadata — and one day that bites you

What actually happens

The good side: free metadata stripping

The bad side: the orientation bug that eats an afternoon

The rule I settled on

One codebase, one website, two app stores: what Capacitor actually costs you

Don't ship the website inside the app

The word "free" can get your build flagged

The download button that does nothing

Capacitor 8 wants JDK 21, and your machine probably has 17

Debug builds must force test ads

You don't need a Mac for the iOS build

Was it worth it?

Why HEIC breaks every browser-based image tool, and what it costs to fix

Why the browser can't help you

The trap: renaming the extension

file.type is often an empty string

What decoding actually costs

Orientation, since you're already here

The shape of the problem

What actually breaks when you process PDFs in the browser

Encrypted PDFs can't be modified, and most tools lie about it

The memory ceiling is real, and it kills the tab silently

"Compress this PDF" means two completely different jobs

pdf-lib doesn't render, and that surprises people

Why do it client-side at all

The download button that silently did nothing on mobile

The code that looked fine

Fixing Android: stop pretending it's a browser

Fixing iOS: the Web Share API, and the constraint it doesn't document

The part I'm not happy about

A second silent failure, same shape

What actually generalises

`file.type` is often an empty string

`pdf-lib` doesn't render, and that surprises people