fix: apply ios workarounds and rendering issues and improve image generation performance

[FoHoOV]

This project did not work out of the box for our use case, particularly because most of our users are on iOS.

I initially cloned the repository without preserving its Git history and reworked the implementation to make it compatible with our codebase. These changes have now been tested successfully in production with our user-base, so I am opening this pull request to contribute the relevant improvements upstream.

I also maintain a separate fork with its own build and release process because the original project appears to be unmaintained.

This PR reworks DOM cloning, rendering, resource caching, and iOS-specific compatibility.

I know the pr title is not good, because it cannot capture all of this in one PR title, but as I said, this is all the changes we did in our application in one go :D

Breaking changes

• filter is now called for the root element and every descendant. It must return keep, unwrap, or remove. Boolean return values are no longer supported.
• Removed the standalone backgroundColor option. Use style.backgroundColor instead.
• Output dimensions are now measured from the styled and filtered clone. Consumer-provided width, height, and layout-affecting style values are applied before capture, and filtering may change the resulting bounds.
• Removed module-level resource and stylesheet caches. Cross-render cache reuse is now opt-in through a caller-owned Cache.
• includeQueryParams now defaults to true.

Features

• Export a reusable, caller-owned Cache for images, fonts, stylesheets, and external SVG resources. This avoids retaining fetched resource data globally for the lifetime of the application.

• Add tri-state filtering with support for:

  • keep: preserve the element and its children.
  • unwrap: remove the element while preserving its children.
  • remove: remove the element and its descendants.

• Inline definitions referenced by external SVG <use> elements, including their transitive dependencies.

• Capture browser-computed styles from a live, off-screen clone before serialization.

Bug fixes

• On iOS, wait for WebKit rendering to settle, then clear and redraw canvas-based output on a later animation frame. This prevents images and other elements from being omitted during the initial draw.
• Use traversal logic compatible with older iOS versions when collecting SVG definitions and dependencies.
• Apply consumer-provided dimensions and layout-affecting styles before measuring the clone, including triggering reflow when only one dimension is provided.
• Preserve logical dimensions and the complete rendered image at high pixel ratios and after automatic canvas scaling.
• Preserve computed width, height, object-fit, and related styles when replacing video frames or posters with images.
• Wait for images to become ready before capture.
• Apply caller-provided fetch options consistently.
• Keep cache busting independent from cache reuse.
• Avoid separately inlining descendant styles within SVG elements.
• Preserve namespaced SVG references.
• Remove clone-time font-size adjustments so selected options render using their actual computed styles (use font-kerning instead of 0.1 pixel hack).

Performance

• Collect computed styles before applying them in a batched write phase, reducing layout thrashing.

should fix most ios related issues #569, #556, #579 (but with correct external references) and other similar iOS related issues.

[biiibooo]

👋 @FoHoOV

💖 Thanks for opening this pull request! 💖

Please follow the contributing guidelines. And we use semantic commit messages to streamline the release process.

Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add graph.scale() method
• docs: graph.getShortestPath is now available

Things that will help get your PR across the finish line:

• Follow the TypeScript coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[biiibooo]

@FoHoOV Please provide us with more info about this pull request title.

[codecov]

Codecov Report

❌ Patch coverage is 83.14607% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.50%. Comparing base (d9b2fcf) to head (9ede381).
⚠️ Report is 26 commits behind head on master.

Files with missing lines	Patch %	Lines
src/embed-webfonts.ts	50.00%	7 Missing ⚠️
src/embed-images.ts	80.00%	1 Missing and 2 partials ⚠️
src/dataurl.ts	85.71%	1 Missing and 1 partial ⚠️
src/index.ts	94.44%	0 Missing and 2 partials ⚠️
src/embed-resources.ts	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #585   +/-   ##
=======================================
  Coverage   66.50%   66.50%           
=======================================
  Files          10       10           
  Lines         612      612           
  Branches      150      150           
=======================================
  Hits          407      407           
  Misses        144      144           
  Partials       61       61           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.