While developing a client-side thumbnail generator, exporting styled DOM nodes into high-resolution PNG images emerged as the core engineering bottleneck.
Under Chromium desktop browsers, standard libraries like html-to-image perform reliably. However, WebKit engines (desktop and iOS Safari) and mobile in-app webviews (KakaoTalk, Instagram, Line) introduce race conditions, asset stripping, and broken download behaviors.
Here is how we debugged and resolved these cross-browser export issues.
Problem 1: WebKit Resource Dropping in Safari
When using html-to-image, Safari frequently renders blank spaces where custom fonts or CSS background images should appear.
[DOM Element] ──(SVG ForeignObject)──> [Canvas rasterization]
▲
Safari prematurely terminates resource fetches
Safari isolates SVG foreignObject contexts aggressively. If external web fonts or base64 images take even a few milliseconds to resolve, WebKit aborts resource loading and rasterizes the canvas with missing text and blank backgrounds.
The Fix: Migrating to modern-screenshot
We switched to modern-screenshot, a maintained fork of html-to-image that includes pre-flight asset caching, font embedding workarounds, and better foreignObject lifecycle management.
import { domToPng } from 'modern-screenshot';
async function exportNodeToPng(element) {
return await domToPng(element, {
scale: 2, // Retina scale
fetch: {
busting: true,
},
});
}
The Safari Warm-Up Pass
On certain mobile Safari versions, WebKit's font rendering cache fails on the initial snapshot even when fonts are technically preloaded via document.fonts.ready.
Triggering a silent preliminary pass primes the internal WebKit glyph cache:
const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
let dataUrl = "";
// Safari requires a warm-up cycle on cold DOM structures
const attempts = isSafari ? 2 : 1;
for (let i = 0; i < attempts; i++) {
dataUrl = await domToPng(node, { scale: 2 });
}
Problem 2: Mobile Downloads (<a> download vs. Photo Library)
On desktop browsers, triggering an automatic download is straightforward:
const link = document.createElement('a');
link.download = 'thumbnail.png';
link.href = dataUrl;
link.click();
However, on iOS Safari and mobile in-app webviews:
- Synthetic clicks on
<a download>open the blob as a generic document or prompt a save dialog into the iOS "Files" app rather than the Camera Roll / Photos app. - Inside in-app browsers (like KakaoTalk or Instagram),
downloadattributes are often completely suppressed by the native container webview.
The Solution: Long-Press Modal Fallback
Detect mobile WebKit and webview user agents. Instead of triggering an anchor download, present the rendered PNG inside an overlay modal with instructions to long-press and tap "Save to Photos":
async function handleDownload(node) {
const dataUrl = await exportNodeToPng(node);
const isIos = /iPad|iPhone|iPod/.test(navigator.userAgent);
const isInAppWebview = /KAKAOTALK|Instagram|Line|FB/i.test(navigator.userAgent);
if (isIos || isInAppWebview) {
// Render the image into an overlay modal
openPhotoSaveModal(dataUrl);
} else {
// Desktop / Android browser direct file download
const link = document.createElement('a');
link.download = 'thumbnail.png';
link.href = dataUrl;
link.click();
link.remove();
}
}
Takeaways
- Treat client-side canvas rasterization as asynchronous and race-condition prone under WebKit.
- Prefer
modern-screenshotover unmaintainedhtml-to-imageforks. - Always provide fallback modal UIs for mobile browsers where native
<a download>behavior is restricted.