Fix race condition when applying EPUB decorations

[mickael-menu]

Fixed

Navigator

• Fixed a race condition in EPUBNavigatorViewController where rapidly calling apply(decorations:in:) for the same group could cause multiple highlights to appear simultaneously.

[Copilot]

Pull request overview

This PR addresses a decoration rendering race in the EPUB navigator when apply(decorations:in:) is called rapidly for the same decoration group, aiming to prevent simultaneous/duplicate highlights.

Changes:

• Introduces per-decoration-group task cancellation to supersede in-flight decoration applications.
• Refactors decoration group identifiers to use a shared DecorationGroup typealias across the Navigator and SpreadView delegate APIs.
• Updates the changelog to document the race condition fix.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
Sources/Navigator/EPUB/EPUBSpreadView.swift	Updates decoration-activation delegate signature to use DecorationGroup.
Sources/Navigator/EPUB/EPUBNavigatorViewController.swift	Adds per-group task tracking/cancellation and migrates decoration storage/callbacks to DecorationGroup.
Sources/Navigator/Decorator/DecorableNavigator.swift	Updates DecorableNavigator API to use DecorationGroup and defines the typealias.
CHANGELOG.md	Documents the race-condition fix.

Comments suppressed due to low confidence (1)

Sources/Navigator/EPUB/EPUBNavigatorViewController.swift:848

• self.decorations[group] is updated to target before any JavaScript updates are applied. If this task is cancelled after the assignment (e.g. by a subsequent apply for the same group), the in-memory source of truth will advance while the web views may not have been updated, and the next diff will be computed from the wrong source, potentially skipping needed updates/clears. Consider only committing self.decorations[group] = target after the task group completes successfully (and wasn’t cancelled), or reverting to source when cancellation happens.

                let source = self.decorations[group] ?? []
                let target = decorations.map {
                    var d = $0
                    d.locator = publication.normalizeLocator(d.locator)
                    return DiffableDecoration(decoration: d)
                }
                self.decorations[group] = target

---

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

Sources/Navigator/EPUB/EPUBNavigatorViewController.swift:855

• apply(decorations:in:) updates self.decorations[group] = target before any JavaScript is actually executed. If this task gets cancelled after that assignment (e.g. a newer apply call cancels it), the in-memory decorations state can diverge from what’s rendered in the web views. The next apply will compute a diff from the updated in-memory state (which may never have been applied) and can end up issuing .update(...) operations for decorations that don’t exist in the DOM, leaving decorations missing or stale. Consider only committing self.decorations[group] = target once the task group finished applying scripts and the task wasn’t cancelled, or track “last applied” vs “latest requested” decorations separately so diffs are computed from the actually-rendered state.

                let source = self.decorations[group] ?? []
                let target = decorations.map {
                    var d = $0
                    d.locator = self.publication.normalizeLocator(d.locator)
                    return DiffableDecoration(decoration: d)
                }
                self.decorations[group] = target

---

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