Add experimental EPUB decoration positioning

[ddfreiling]

Optionally set decorations at z-index: -1, in order to support opaque highlights behind text, but in front of background-color. This ensures that highlights do not blur/modify text color via alpha overlay.

From discussion with @mickael-menu I named this experimentalDecorationPositioning and turned it off by default. However I do think it's a superior solution and experience for the visually impaired user. I plan to add this feature to kotlin-toolkit as well.

Without experimental positioning:

With experimental positioning:

[mickael-menu]

Thank you @ddfreiling, this is promising!

I changed the Configuration constructor and kept only the experimentalPositioning in the HTMLDecoration.defaultTemplates() API. If we don't encounter any issue in production, this will become the new default. 👍

[Copilot]

Pull Request Overview

This PR introduces experimental positioning for EPUB decorations, allowing highlights to be placed behind text to improve legibility when using opaque decorations (alpha: 1.0).

Key changes:

• Added experimentalPositioning parameter to HTMLDecorationTemplate.defaultTemplates() and related factory methods
• When enabled, decorations are positioned with z-index: -1 to place them behind text
• Updated the TestApp to demonstrate the feature with opaque highlights

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
Sources/Navigator/EPUB/HTMLDecorationTemplate.swift	Added experimentalPositioning parameter to template factory methods and CSS z-index styling
TestApp/Sources/Reader/EPUB/EPUBViewController.swift	Updated to use opaque highlights with experimental positioning enabled
CHANGELOG.md	Documented the new experimental positioning feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mickael-menu]

@ddfreiling By the way I noticed an issue already, if we set a light foreground color in the preferences:

We may need a way to provide a map of colors according to the provided theme. But maybe it's enough to let the app refresh the decorations directly.

[ddfreiling]

@ddfreiling By the way I noticed an issue already, if we set a light foreground color in the preferences:

We may need a way to provide a map of colors according to the provided theme. But maybe it's enough to let the app refresh the decorations directly.

Isn't this just because the alpha is also set to 1.0 in the example app now to highlight the difference? Without the position fix using alpha 1.0 would just completely obscure the text

[mickael-menu]

Yes, if you reset the alpha to 0.3 it remains as readable as before. But that's a shame if we can't use a 1.0 alpha in light mode at the same time.