Pre-push review: T-2025 footnote badge occurrence drift

diff --git a/prism/Services/SearchStateFeeder.swift b/prism/Services/SearchStateFeeder.swiftindex 441dcf0d..2d1be2f7 100644--- a/prism/Services/SearchStateFeeder.swift+++ b/prism/Services/SearchStateFeeder.swift@@ -255,8 +255,8 @@ enum SearchStateFeeder {                 // Escaped occurrences (`\[^1]`) render as literal text, never a live                 // reference — excluded here, and by the identical predicate in                 // `badgeEligibility` below, so escaping alone cannot pull the two-                // arrays out of alignment (T-1968). Comment gating still can: see the-                // note on `badgeEligibility`.+                // arrays out of alignment (T-1968). `badgeEligibility` scans this+                // same `scanSource` too (T-2025), so comment gating can't either.                 guard !FootnoteData.isEscaped(in: scanSource, before: match.range.lowerBound) else {                     continue                 }@@ -304,29 +304,46 @@ enum SearchStateFeeder {         return sources     } -    /// Badge-eligibility flags intended to line up one-to-one with-    /// `footnoteMatchCounts`'s entries: same inline-source iteration, same reference-    /// regex, same resolvable-identifier filter, and — since T-1968 — the same escape-    /// predicate, so an escaped occurrence is dropped on both sides rather than-    /// contributing a flag with no matching entry. A flag is true when that reference-    /// occurrence actually renders as a badge in the DOM.+    /// Badge-eligibility flags aligned one-to-one with `footnoteMatchCounts`'s+    /// entries: same inline-source iteration, same comment-gated `scanSource`+    /// (`MarkdownBlock.footnoteScanComponents`) `referencedFootnoteIdentifiers`+    /// scans, same resolvable-identifier filter, and the same escape predicate. A+    /// flag is true when that reference occurrence actually renders as a badge in+    /// the DOM.     ///-    /// The alignment is not unconditional, and the gap is pre-existing: this scans the-    /// RAW inline source, while `referencedFootnoteIdentifiers` scans the-    /// comment-gated `scanSource` (`MarkdownBlock.footnoteScanComponents`). For a block-    /// containing an HTML comment the two iterate different text, so a reference inside-    /// a hidden comment — or one whose escape status the comment excision changes — can-    /// still shift the arrays relative to each other. `currentMatch` degrades safely-    /// (a missing flag is read as eligible), and the residual is recorded in-    /// `specs/bugfixes/escaped-footnote-references/report.md`.+    /// Before T-2025 this scanned the RAW inline source instead of `scanSource`,+    /// so a reference hidden inside a comment (or excluded because its enclosing+    /// comment's shape is rejected) still contributed a flag here with nothing to+    /// pair it with in `footnoteMatchCounts` — the array picked up an extra+    /// leading/interior entry and every flag after it landed one position off.+    /// `currentMatch` has no way to detect that shift; it just reads the wrong+    /// flag and reports the wrong occurrence. Scanning the same `scanSource` both+    /// functions already share, rather than translating indices between two+    /// independently-filtered arrays, makes that class of drift structurally+    /// impossible: whatever `referencedFootnoteIdentifiers` counts is exactly what+    /// this counts too.     ///-    /// Eligibility comes from the render pipeline itself-    /// (`FootnoteReferenceScanner` candidacy plus the walker's position rules),-    /// matched back to each regex occurrence by its UTF-16 source offset — never-    /// re-approximated here, which is the failure class the badge redesign removed-    /// (T-1853 review). A `[^id]`-shaped occurrence that resolves but never badges-    /// (code span, link nesting) gets `false`; an escaped occurrence never reaches-    /// this array at all (excluded upstream, same as `referencedFootnoteIdentifiers`).+    /// `scanSource` is comment-gated text, not what the emitter actually rendered+    /// from, so an occurrence's offset there cannot be looked up directly against+    /// `badgeStarts` (`EmittedDocument.badgeSourceStarts`, keyed in RAW source+    /// coordinates — see the note on `BlockHTMLEmitter.badgeSourceStarts`). Two+    /// cases:+    ///  - An occurrence in the BASE portion (`components.baseWithoutMarkers`, i.e.+    ///    outside every comment span) is rebased to its raw offset via+    ///    `rawOffset(forBaseOffset:matches:)` and looked up normally.+    ///  - An occurrence in a SURFACED comment body (toggle on, accepted shape) is+    ///    always `false`, not looked up at all: `InlineHTMLRenderer.visitInlineHTML`+    ///    escapes comment text verbatim rather than re-parsing it for markdown, so+    ///    a `[^id]` inside a comment never becomes a badge regardless of whether+    ///    the comment itself is CSS-visible.+    ///+    /// Eligibility for a base-portion occurrence comes from the render pipeline+    /// itself (`FootnoteReferenceScanner` candidacy plus the walker's position+    /// rules), matched back by its UTF-16 source offset — never re-approximated+    /// here, which is the failure class the badge redesign removed (T-1853+    /// review). A `[^id]`-shaped occurrence that resolves but never badges (code+    /// span, link nesting) gets `false`; an escaped occurrence never reaches this+    /// array at all (excluded upstream, same as `referencedFootnoteIdentifiers`).     ///     /// `cachedStarts` supplies the starts the document emit already captured     /// (`EmittedDocument.badgeSourceStarts`, cached per `parseRevision`), so the@@ -350,22 +367,64 @@ enum SearchStateFeeder {             let starts = cachedStarts(source)                 ?? InlineHTMLRenderer.badgeSourceStarts(source: source, footnotes: context.footnoteData)             let badgeStarts = Set(starts)-            for match in source.matches(of: FootnoteData.referencePattern)++            let commentMatches = HTMLCommentStripping.matches(in: source)+            let components = MarkdownBlock.footnoteScanComponents(forInlineText: source, context: context)+            let scanSource = components.scanSource+            let baseLength = components.baseWithoutMarkers.utf16.count++            for match in scanSource.matches(of: FootnoteData.referencePattern)             where context.footnoteData.definition(for: String(match.1)) != nil {                 // Kept in lockstep with `referencedFootnoteIdentifiers`'s escape check                 // above: an escaped occurrence never enters that array, so it must not                 // contribute a flag here either, or the two would misalign entry-for-                 // entry (T-1968).-                guard !FootnoteData.isEscaped(in: source, before: match.range.lowerBound) else {+                guard !FootnoteData.isEscaped(in: scanSource, before: match.range.lowerBound) else {                     continue                 }-                let offset = source.utf16.distance(from: source.startIndex, to: match.range.lowerBound)-                flags.append(badgeStarts.contains(offset))+                let scanOffset = scanSource.utf16.distance(from: scanSource.startIndex, to: match.range.lowerBound)+                if scanOffset < baseLength {+                    let offset = rawOffset(forBaseOffset: scanOffset, matches: commentMatches)+                    flags.append(badgeStarts.contains(offset))+                } else {+                    // A surfaced comment body: never a badge, see the doc comment above.+                    flags.append(false)+                }             }         }         return flags     } +    /// Maps a UTF-16 offset within `baseWithoutMarkers` — the text+    /// `MarkdownBlock.footnoteScanComponents` returns after removing every+    /// `<!--…-->` span in `matches` from the original inline source — back to+    /// that span's offset in the ORIGINAL source. `matches` must be+    /// `HTMLCommentStripping.matches(in:)` computed from that same source.+    ///+    /// `matches` are non-overlapping and in increasing order (the same contract+    /// `HTMLCommentStripping.removing` relies on): walk them once, and for each+    /// one either `baseOffset` falls in the untouched span just before it — in+    /// which case the raw offset is that span's raw start plus the same+    /// within-span delta — or it doesn't, in which case skip past the removed+    /// span and keep looking. A `baseOffset` past every match falls in the+    /// trailing untouched span after the last one.+    private static func rawOffset(+        forBaseOffset baseOffset: Int,+        matches: [HTMLCommentStripping.CommentMatch]+    ) -> Int {+        var rawCursor = 0+        var baseCursor = 0+        for match in matches {+            let segmentLength = match.range.location - rawCursor+            if baseOffset < baseCursor + segmentLength {+                return rawCursor + (baseOffset - baseCursor)+            }+            baseCursor += segmentLength+            rawCursor = match.range.location + match.range.length+        }+        return rawCursor + (baseOffset - baseCursor)+    }+     /// Resolves the current within-block match index into a text ordinal or a     /// footnote badge id. The within-block ordinal space is [text matches…][footnote     /// matches in source order], matching `combinedSearchableText`'s concatenation.

diff --git a/prismTests/WebRendering/WebSearchBridgeTests.swift b/prismTests/WebRendering/WebSearchBridgeTests.swiftindex 71abc446..3f8a474f 100644--- a/prismTests/WebRendering/WebSearchBridgeTests.swift+++ b/prismTests/WebRendering/WebSearchBridgeTests.swift@@ -704,6 +704,123 @@ struct WebSearchBridgeTests {         #expect(starts == [29, 43])     } +    // MARK: - T-2025: a hidden comment must not skew the badge occurrence++    /// The source used by the hidden-comment-alignment tests below. Literally:+    /// `See <!-- [^1] --> First[^1] Second[^1]`+    ///+    /// A minimal non-comment prefix keeps this a `.paragraph` with an INLINE HTML+    /// comment (a line starting with `<!--` parses as a block-level HTML comment+    /// instead, per CommonMark — a different block variant this bug does not+    /// reach). One `[^1]` hidden inside that leading comment, followed by two live+    /// references to the same footnote. With comments hidden (the default),+    /// `referencedFootnoteIdentifiers` counts only the two live occurrences — so+    /// the block's footnote ordinal space is exactly two entries — but+    /// `badgeEligibility` used to scan the RAW source independently, producing a+    /// THIRD flag (for the hidden occurrence) at index 0. `currentMatch` then read+    /// that flag when resolving the second live occurrence, computing badge+    /// occurrence 0 instead of 1 (T-2025).+    private static let hiddenCommentThenLiveSource =+        "See <!-- [^1] --> First[^1] Second[^1]"++    @Test("A footnote reference hidden in a comment is excluded from both feeder arrays, keeping them aligned")+    func hiddenCommentReferenceKeepsFeederArraysAligned() {+        // `referencedFootnoteIdentifiers` and `badgeEligibility` are private, so — as+        // with the T-1968 escape tests above — the alignment is observed through the+        // payload. `matchedFootnoteIds == ["1", "1"]` pins that the hidden occurrence+        // contributes no third entry; `current == .badge(id: "1", occurrence: 1)` pins+        // that `badgeEligibility`'s flags line up one-to-one with those two entries+        // rather than carrying a leading flag for the hidden occurrence.+        let blocks: [MarkdownBlock] = [.paragraph(markdown: Self.hiddenCommentThenLiveSource)]+        let context = footnoteContext()+        let counts = blocks.map { SearchService.countMatches(query: "alpha", in: $0, context: context) }+        // 2 footnote-content matches, one per LIVE reference; the hidden one+        // contributes nothing (comments hidden by default).+        #expect(counts[0] == 2)++        let states = SearchStateFeeder.buildStates(+            query: "alpha",+            blocks: blocks,+            matchCountsPerBlock: counts,+            currentGlobalMatchIndex: 1,+            context: context+        )+        #expect(states.count == 1)+        #expect(states.first?.textMatchCount == 0)+        #expect(states.first?.matchedFootnoteIds == ["1", "1"])+        #expect(states.first?.current == .badge(id: "1", occurrence: 1))+    }++    @Test("Match ordinals across a hidden comment reference address the two live badges")+    func hiddenCommentOrdinalsWalkTheLiveOccurrences() {+        // The whole ordinal walk over the same source: index 0 is the first live+        // reference's badge, index 1 the second. Nothing addresses the hidden+        // occurrence, because it never entered the ordinal space.+        let blocks: [MarkdownBlock] = [.paragraph(markdown: Self.hiddenCommentThenLiveSource)]+        let context = footnoteContext()+        let counts = blocks.map { SearchService.countMatches(query: "alpha", in: $0, context: context) }++        let expected: [SearchStateFeeder.CurrentMatch] = [+            .badge(id: "1", occurrence: 0),+            .badge(id: "1", occurrence: 1),+        ]+        for (index, want) in expected.enumerated() {+            let states = SearchStateFeeder.buildStates(+                query: "alpha",+                blocks: blocks,+                matchCountsPerBlock: counts,+                currentGlobalMatchIndex: index,+                context: context+            )+            #expect(states.first?.current == want, "global match index \(index)")+        }+    }++    @Test("A footnote reference hidden in a comment renders no badge, regardless of the toggle")+    func hiddenCommentReferenceRendersNoBadge() {+        // The premise the two tests above rest on: an inline HTML comment is always+        // escaped as literal text (InlineHTMLRenderer.visitInlineHTML) rather than+        // re-parsed for markdown, so a `[^1]` inside one never becomes a badge —+        // whether or not the comment itself is CSS-visible.+        let starts = InlineHTMLRenderer.badgeSourceStarts(+            source: Self.hiddenCommentThenLiveSource, footnotes: footnoteData()+        )+        #expect(starts.count == 2)+    }++    @Test("Live: current badge on the second visible reference after a hidden comment")+    func liveCurrentBadgeAfterHiddenCommentReference() async throws {+        let blocks: [MarkdownBlock] = [.paragraph(markdown: Self.hiddenCommentThenLiveSource)]+        let footnotes = footnoteData()+        let context = footnoteContext()+        let harness = try await WebDocumentLiveHarness.make(+            blocks: blocks,+            footnotes: footnotes,+            featureScripts: ["prism-search"]+        )+        let counts = blocks.map { SearchService.countMatches(query: "alpha", in: $0, context: context) }+        // Global index 1 → the SECOND live reference — the section's second (and+        // last) real badge, since the hidden comment's occurrence never badges.+        let json = SearchStateFeeder.searchStateJSON(+            query: "alpha",+            blocks: blocks,+            matchCountsPerBlock: counts,+            currentGlobalMatchIndex: 1,+            context: context+        )+        try await harness.send(.setSearchState(json: json, reveal: false))+        try await Task.sleep(for: .milliseconds(150))++        let attributes = try await harness.evalString(+            "var badges = document.querySelectorAll('[data-prism-footnote=\\\"1\\\"]');"+                + " if (badges.length !== 2) { return 'count:' + badges.length; }"+                + " function d(b) { return (b.getAttribute('data-prism-search-match') || '-')"+                + " + '/' + (b.getAttribute('data-prism-search-current') || '-'); }"+                + " return d(badges[0]) + '|' + d(badges[1]);"+        )+        #expect(attributes == "true/-|true/true")+    }+     @Test("Live: current badge lands on the right badge across a code-span look-alike")     func liveCurrentBadgeSkipsCodeSpanLookAlike() async throws {         let blocks: [MarkdownBlock] = [.paragraph(markdown: "See[^1] here `[^1]` and also[^1] end.")]

diff --git a/specs/bugfixes/footnote-badge-occurrence-drift/report.md b/specs/bugfixes/footnote-badge-occurrence-drift/report.mdnew file mode 100644index 00000000..e64d18ca--- /dev/null+++ b/specs/bugfixes/footnote-badge-occurrence-drift/report.md@@ -0,0 +1,218 @@+# Bugfix Report: Hidden Comments Skew Repeated-Footnote Search Badge Occurrence++**Date:** 2026-09-07+**Status:** Fixed++## Description of the Issue++When a block contains a footnote reference (`[^id]`) hidden inside an HTML+comment, followed by two or more LIVE references to the same footnote,+navigating search to the second (or later) live occurrence highlighted the+wrong badge — the first live badge was marked again instead of the second.++**Reproduction steps:**+1. Open a document containing a paragraph such as+   `See <!-- [^1] --> First[^1] Second[^1]`, with `[^1]: alpha` defined and+   HTML comments hidden (the default).+2. Search for `alpha` (matches footnote 1's content).+3. Navigate to the second counted footnote match.++**Expected:** the section's second badge (`Second[^1]`) is marked current.+**Actual:** the section's first badge (`First[^1]`) is marked current again.++**Impact:** Search navigation misidentifies which footnote badge is current+whenever a hidden (or otherwise comment-gated) `[^id]` occurrence precedes+live occurrences of the same footnote in a block. Cosmetic/navigation-only —+no data loss — but confusing when using search to jump between repeated+footnote references.++## Investigation Summary++T-1968 (PR #416) had already documented the shape of this exact drift while+fixing a neighbouring one (escaped occurrences): `SearchStateFeeder+.referencedFootnoteIdentifiers` (and therefore `footnoteMatchCounts`) scans+`MarkdownBlock.footnoteScanComponents(...).scanSource` — the inline source+with HTML comments excised (or, on the toggle, joined with surfaced comment+bodies) — while `badgeEligibility` scanned the RAW, unmodified inline source.+For a block with no comments the two scans see identical text and stay+aligned; for a block with a hidden comment, `referencedFootnoteIdentifiers`+produces one array entry per LIVE occurrence while `badgeEligibility`+produced one flag per RAW occurrence (comment included) — a longer array,+misaligned from the first entry after the hidden occurrence onward.++`currentMatch` (`SearchStateFeeder.swift`) walks `footnoteMatches` (built from+`referencedFootnoteIdentifiers`) to find which reference occurrence owns an+overflow search-match position, and for each candidate counts prior+badge-eligible entries by indexing straight into the `badgeEligibility` flags+array with the SAME index. With the two arrays different lengths/shapes, that+index landed on the wrong flag.++Reproduced with a Swift Testing regression+(`WebSearchBridgeTests.hiddenCommentReferenceKeepsFeederArraysAligned` and+`hiddenCommentOrdinalsWalkTheLiveOccurrences`) before the fix: navigating to+the second live occurrence resolved to `.badge(id: "1", occurrence: 0)`+instead of the expected `.badge(id: "1", occurrence: 1)`.++- **Symptoms examined:** `SearchStateFeeder.currentMatch`'s occurrence math,+  `badgeEligibility`'s and `referencedFootnoteIdentifiers`'s scan sources.+- **Code inspected:** `prism/Services/SearchStateFeeder.swift`,+  `prism/Models/MarkdownBlock.swift` (`footnoteScanComponents`,+  `combinedSearchableText`), `prism/Services/WebRendering/InlineHTMLRenderer.swift`+  (`visitInlineHTML`, to confirm a `[^id]` inside any HTML comment — hidden or+  CSS-visible — never renders as a badge, since the comment's inner text is+  always escaped verbatim rather than re-parsed).+- **Hypotheses tested:** whether the fix should stay "translate indices at the+  point of use" (rejected — the same class of bug already survived one such+  fix, T-1968, because a second, independent divergence source existed);+  whether `badgeEligibility` should scan raw source and rebase+  `referencedFootnoteIdentifiers`'s output instead (rejected — reordering risk+  for the toggle-on "surfaced comment body" case, see Alternatives below).++## Discovered Root Cause++`SearchStateFeeder.badgeEligibility` scanned the raw, comment-including inline+source, independently from `SearchStateFeeder.referencedFootnoteIdentifiers`,+which scans the comment-gated `scanSource`. The two arrays this produces+(`footnoteMatches`, `badgeEligibility`'s flags) are consumed as if+index-aligned by `currentMatch`, but nothing enforced that alignment — a block+containing a comment-hidden footnote reference broke it silently.++**Defect type:** Coordinate-space mismatch between two independently-derived+arrays consumed as if index-aligned.++**Why it occurred:** T-1968 fixed the ESCAPING half of this same class of bug+(both functions now apply the identical `FootnoteData.isEscaped` predicate)+but explicitly left the COMMENT-GATING half as a documented, un-fixed residual+in `badgeEligibility`'s doc comment — this ticket is that residual.++**Contributing factors:** `badgeEligibility` needs RAW source offsets to query+`EmittedDocument.badgeSourceStarts` (deliberately keyed in raw-source+coordinates, since that's what the renderer actually parsed), which is+presumably why it scanned raw source directly instead of the transformed+`scanSource` — but scanning a different TEXT than `referencedFootnoteIdentifiers`+means iterating a different SET of occurrences whenever a comment is present.++## Resolution for the Issue++**Changes made:**+- `prism/Services/SearchStateFeeder.swift` — `badgeEligibility` now iterates+  the same `scanSource` (`MarkdownBlock.footnoteScanComponents`) that+  `referencedFootnoteIdentifiers` scans, so both arrays are built from+  identical text with identical filters (comment gating, escape, resolvability)+  applied in the same order — misalignment is no longer possible by+  construction. For a match found in the BASE (non-comment) portion of+  `scanSource`, a new helper `rawOffset(forBaseOffset:matches:)` maps its+  offset back to the ORIGINAL raw source (needed because `badgeStarts` is+  keyed in raw coordinates). For a match found in a SURFACED comment body+  (toggle on, accepted comment shape), the flag is unconditionally `false` —+  `InlineHTMLRenderer.visitInlineHTML` always escapes an inline HTML comment's+  text verbatim rather than re-parsing it, so a footnote reference inside any+  comment (hidden or visible) never renders a badge, and no offset lookup is+  needed to know that.++**Approach rationale:** The task brief for this fix asked for ONE coordinate+space rather than translating indices at the point of use. `scanSource` — the+comment-gated text `referencedFootnoteIdentifiers` already treats as+authoritative for "which occurrences count" — is that single coordinate space:+`badgeEligibility` now derives its per-occurrence set from the exact same scan,+so the two arrays can never drift in LENGTH or SHAPE again, only rebasing a+matched occurrence's OFFSET when it actually needs to query raw-coordinate+badge starts.++**Alternatives considered:**+- Make BOTH functions scan the raw source, with `referencedFootnoteIdentifiers`+  skipping raw occurrences whose containing comment is hidden/rejected —+  rejected because it would change the RELATIVE ORDER of occurrences for the+  toggle-on case where a comment sits mid-paragraph (today `scanSource` orders+  base text first, then surfaced comment bodies), risking a regression in+  `currentMatch`'s overflow walk for blocks mixing base-text and+  surfaced-comment-body footnote references — a real but narrow scenario with+  no existing test coverage either way.+- Translate `badgeEligibility`'s existing raw-source-produced index into+  `referencedFootnoteIdentifiers`'s coordinate space at the `currentMatch` call+  site — rejected per the task brief: this is exactly the "point of use+  translation" pattern that already failed once (T-1968 fixed escaping this+  way, but comment-gating was left as a residual because a second translation+  point is a second place to get it wrong).++## Regression Test++**Test file:** `prismTests/WebRendering/WebSearchBridgeTests.swift`+**Test names:**+- `hiddenCommentReferenceKeepsFeederArraysAligned`+- `hiddenCommentOrdinalsWalkTheLiveOccurrences`+- `hiddenCommentReferenceRendersNoBadge` (pins the premise: a comment's+  `[^id]` never becomes a DOM badge)+- `liveCurrentBadgeAfterHiddenCommentReference` (live-DOM regression over a+  real rendered page, per the ticket's request for a live-DOM test alongside+  the feeder-level one)++**What it verifies:** With a leading hidden-comment `[^1]` occurrence followed+by two live `[^1]` occurrences, `matchedFootnoteIds` has exactly two entries+(the hidden one contributes nothing) and navigating to the second live+occurrence resolves to `.badge(id: "1", occurrence: 1)`, not `occurrence: 0`.+The live test additionally confirms the rendered DOM's second badge, not the+first, is marked `data-prism-search-current`.++**Run command:**+```+xcodebuild test -project prism.xcodeproj -scheme prism \+  -destination 'platform=macOS' -configuration Debug \+  -derivedDataPath ./DerivedData -resultBundlePath ./DerivedData/t.xcresult \+  -testPlan prism -only-test-configuration "en (base)" \+  -parallel-testing-worker-count 1 -enableCodeCoverage NO \+  -only-testing:prismTests/WebSearchBridgeTests+```++## Affected Files++| File | Change |+|------|--------|+| `prism/Services/SearchStateFeeder.swift` | `badgeEligibility` rewritten to scan the same `scanSource` as `referencedFootnoteIdentifiers`; new `rawOffset(forBaseOffset:matches:)` helper rebases a base-portion match to raw-source coordinates for the `badgeStarts` lookup; doc comments updated to record the fix and the T-2025 reference. |+| `prismTests/WebRendering/WebSearchBridgeTests.swift` | Added the T-2025 regression tests (feeder-level + live-DOM). |+| `CHANGELOG.md` | Added `[Unreleased] / Fixed` entry. |++## Verification++**Automated:**+- [x] Regression test passes (`WebSearchBridgeTests`, 33/33)+- [x] Related suites pass: `MarkdownBlockSearchContextTests`,+      `FootnoteBadgeSubstitutionTests`, `FootnoteBadgeGrowthTests`,+      `WebSearchParityTests`, `InlineSourceMapScanGrowthTests` (50/50)+- [ ] Full test suite — NOT run; out of scope per validation constraints for+      this session (see note below)+- [x] Linters/validators pass (`make lint`: 0 violations, 580 files)+- [x] `make build-macos` and `make build-ios` both succeed+- [x] `make verify-test-isolation` passes (static + unit guard suite)++**Manual verification:** Traced the exact reproduction source+(`See <!-- [^1] --> First[^1] Second[^1]`) through `rawOffset` and+`badgeEligibility` by hand to confirm occurrence 1 is produced for the second+live reference (see PR description / commit for the worked trace).++**Note on scope:** the full `make test`/`make test-quick` suite was not run in+this session; only the targeted suites above (SearchStateFeeder/footnote/+search-related, ~83 tests total) were exercised, plus both platform builds and+lint. This was a deliberate scope decision for this session, not a machine+failure — the targeted runs above completed cleanly, including the+`.liveWebKit`-gated tests.++## Prevention++**Recommendations to avoid similar bugs:**+- When two arrays are consumed as index-aligned, derive them from ONE shared+  scan/filter rather than two independently-filtered scans over different+  (or even textually-identical-looking) inputs — this is the second time this+  exact class of bug has appeared between these two functions (T-1968, then+  T-2025).+- When a function's doc comment already says "the alignment is not+  unconditional, and the gap is pre-existing" (as `badgeEligibility`'s did),+  treat that as an open bug report, not a permanent caveat.++## Related++- T-1968 (PR #416): fixed the escaping half of this same class of drift, and+  is the origin of the doc comment that flagged this exact residual.+- T-1853: introduced badge-occurrence addressing in `currentMatch`.+- T-1713: introduced the comment-gated `scanSource` /+  `referencedFootnoteIdentifiers`.

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8b947fb7..f9339d4a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0  ### Fixed +- A footnote reference hidden inside an HTML comment no longer skews which badge search marks as current when the same footnote is referenced again visibly afterward (T-2025). Two feeder arrays are consumed as index-aligned — one counting which occurrences of a footnote actually appear in the block's comment-gated searchable text, one flagging which of those occurrences render as a DOM badge — but the second was built by independently scanning the raw, comment-including source, so a hidden occurrence added an extra flag the first array had no matching entry for; every flag after it then answered for the wrong occurrence. Navigating to the second live reference to a footnote that also had a hidden occurrence earlier in the same block marked the first badge again instead of the second. Both arrays now derive from the same comment-gated scan, so they cannot drift out of length or order relative to each other; a comment-included occurrence still needs its offset rebased to the raw source to look up whether the renderer actually placed a badge there, but a reference hidden inside a comment — or one rendered as a comment's own visible-but-escaped text — is now known to carry no badge without a lookup at all, since an HTML comment's contents are always rendered as literal escaped text rather than re-parsed for footnote syntax. - Tapping a note in the compact Notes panel or the regular Notes sidebar now scrolls to the block that note is actually anchored to, instead of always the first occurrence of identical content elsewhere in the document (T-1929). Both note UIs navigated by passing the note's bare content-hash block id, which `BlockDOMID` resolves to its first (or first-visible) occurrence by design — the note's own stored heading path, already recorded for note storage/display disambiguation (T-209), was never consulted. Navigation now resolves the note's specific occurrence against that heading path and builds the same verified composite target TOC/search/scroll-restore already use, falling back to the previous first-occurrence behaviour only when a note carries no heading path (legacy notes) or its heading path no longer matches any occurrence (the block was relocated). A table-row or list-item note anchor resolves to its parent block's correct occurrence, since rows and items are not independently scrollable. - An open document now follows its file when you rename or move it in Finder, the Files app, or another file provider (T-1881). The app watches the open file through a file presenter, and that presenter never implemented the half of its contract that deals with the file moving: it kept pointing at where the file used to be, and so did the document. Reload then failed on a file that is perfectly readable, the title kept the old name, images beside the document were looked for in the old folder, and the notes were left filed under a path nothing would ever look up again. The presenter now retargets itself the moment it is told the file moved, and the document follows it — which is what carries the title, the Save destination, Reload, the remembered reading position and the page's image resolution across the move, since all of them are derived from the one property. The notes move with the document, and the record left at the old path is retired rather than stranded there. Moving them is its own operation rather than a reuse of the one Save As runs, because three things a Save As can take for granted are not true of a rename, and each of them lost notes: a renamed file's notes may not be loaded yet (a rename arriving before you have opened the notes pane, or before the document has finished loading, used to be reported as migrated while nothing moved); an old and a new name can be the same file, so renaming `readme.md` to `README.md` used to write the notes and then delete the file it had just written, taking every note with it; and the document is already at its new name by the time the app is told, so a note written in the instant the rename lands used to clear every note already on the document. Trashing an open document is no longer mistaken for a rename either — it arrives as one, measurably, so the notes would have been rewritten under a path inside the Trash and the ones at the real path deleted; the document now stays where it was, which is where Put Back returns it and where its notes are waiting. Two things deliberately do not move: the Recent Files entry still names the path you opened from (that is T-1842 / T-2172 / T-2173), and the security-scoped access the session holds is left alone — it was granted for the file itself and survives the rename, whereas releasing it is the one way to actually lose access to the file. Two files moved in quick succession — a rename followed by a drag into another folder, or an iCloud reorganisation — are followed all the way, with the notes taken from where they actually are rather than from the intermediate location the document only passed through; before this they were left behind at the original path while everything reported success. And if the notes cannot be written to their new location, you are now told so, with the same alert Save As raises, instead of the notes quietly ceasing to be the document's. - `HTMLImageSourceRewriter` no longer re-emits a mediated `src`/`srcset` value with an embedded quote character left unescaped (T-1942). The rewriter always re-emits these attributes double-quoted, but a value could still contain a raw `"`: the `rewrite` closure's `data:` passthrough hands unencoded `data:` URIs back unchanged, and `rewriteSrcset` re-joins a candidate's descriptor half — never passed through `rewrite` — verbatim. Either one could terminate the re-emitted attribute early, splicing the remainder into attribute position (e.g. `srcset='a.png 1x" onerror=… z='`). The value is now escaped for its double-quoted context before being written, so any quote characters it carries round-trip intact instead of breaking out. The escape leaves a character reference the value already carries alone (the `data:` passthrough re-emits the attribute's text as written, references undecoded, and the browser decodes it once), so an SVG `data:` URI whose author correctly wrote `&` for a literal ampersand still renders that ampersand rather than the reference. This is defence in depth rather than a live exploit: the subsequent `HTMLSanitizer` (SwiftSoup) pass is the actual security boundary and already reduced the broken-out remainder to non-allowlisted junk.