Pre-push review: T-1968/bugfix-escaped-footnote-references

diff --git a/prism/Models/FootnoteData.swift b/prism/Models/FootnoteData.swiftindex e084203e..110c12c3 100644--- a/prism/Models/FootnoteData.swift+++ b/prism/Models/FootnoteData.swift@@ -37,6 +37,45 @@ struct FootnoteData: Equatable, Sendable {     /// Centralised here to avoid pattern divergence across the codebase.     nonisolated(unsafe) static let referencePattern = /\[\^([a-zA-Z0-9_-]+)\]/ +    /// Whether the character at `index` in `text` is backslash-escaped, i.e. renders as+    /// literal text rather than as the markdown construct it spells.+    ///+    /// A backslash escapes exactly the character following it, so a run of backslashes+    /// immediately before `index` pairs off left to right: an odd-length run leaves its+    /// last backslash to escape the character (literal), an even-length run (including+    /// zero) is entirely escaped-backslash pairs (live) — `\[^1]` is escaped, `\\[^1]`+    /// is not. This is the same left-to-right consumption `FootnoteReferenceScanner.scan`+    /// performs directly on its UTF-16 buffer (T-1716); counting the preceding run's+    /// parity is equivalent for a `Regex` match, which only hands back where the token+    /// starts, not what already consumed the text before it.+    ///+    /// Shared by `FootnotePreprocessor.scanLineForReferences`, `MarkdownBlock+    /// .combinedSearchableText`, and `SearchStateFeeder`'s two scans, so those four sites+    /// cannot each invent their own answer to "is this occurrence escaped?" — four copies+    /// of the rule is what let the preprocessor disagree with the renderer (T-1968).+    /// Deliberately generic rather than reference-shaped: the preprocessor asks the same+    /// question of a code-span-opening backtick, which CommonMark escapes by exactly this+    /// rule, and a second copy of the parity walk there would reintroduce the same class.+    ///+    /// Scope, precisely: this settles ESCAPING only. Those sites still approximate the+    /// renderer in other ways, and known residuals are listed in+    /// `specs/bugfixes/escaped-footnote-references/report.md` — the preprocessor's+    /// line-at-a-time scan cannot see indented code blocks or a code span that spans+    /// lines, and its closing-run match does not require the run lengths to be equal;+    /// `FootnoteStripping.strip` and `DocumentReaderView.routeDocumentLink` do not consult+    /// this predicate at all. Do not read "shared predicate" as "the scanners agree".+    nonisolated static func isEscaped(in text: String, before index: String.Index) -> Bool {+        var count = 0+        var cursor = index+        while cursor > text.startIndex {+            let previous = text.index(before: cursor)+            guard text[previous] == "\\" else { break }+            count += 1+            cursor = previous+        }+        return count % 2 == 1+    }+     nonisolated var isEmpty: Bool { definitions.isEmpty }      nonisolated func definition(for identifier: String) -> FootnoteDefinition? {

diff --git a/prism/Models/MarkdownBlock.swift b/prism/Models/MarkdownBlock.swiftindex b48f8128..65e4a78d 100644--- a/prism/Models/MarkdownBlock.swift+++ b/prism/Models/MarkdownBlock.swift@@ -1019,9 +1019,37 @@ nonisolated enum MarkdownBlock: Identifiable, Equatable, Sendable {         // are visible, additionally scan the surfaced comment bodies so         // references inside rendered comment ranges contribute consistently         // with the render — but references inside rejected (never-rendered)-        // comment shapes still contribute nothing.+        // comment shapes still contribute nothing. A backslash-escaped+        // occurrence (`\[^1]`) renders as literal text, never a live+        // reference, so it must not pull in a footnote's content just+        // because some OTHER, live occurrence of the same id resolves it+        // (T-1968) — `SearchStateFeeder.referencedFootnoteIdentifiers`+        // applies the same predicate over the same `scanSource`, so the two+        // agree on ESCAPING; they still differ on comment gating, because+        // `SearchStateFeeder.badgeEligibility` scans the raw source instead+        // (pre-existing, noted at that call site).+        //+        // Known residual (T-1968 review): `HTMLCommentStripping.removing`+        // excises a comment span leaving NO separator behind, so+        // `A\<!-- x -->[^1]` collapses to `A\[^1]` here and the reference is+        // read as escaped, while the renderer badges it — cmark sees `\<`+        // as an escaped `<`, so no comment ever opened. The mis-detection is+        // upstream in the comment scan, not in the escape rule; recorded in+        // `specs/bugfixes/escaped-footnote-references/report.md` rather than+        // papered over here, since inserting a separator would change the+        // searchable text of every commented block.         if !context.footnoteData.isEmpty {-            for match in components.scanSource.matches(of: footnoteReferenceRegex) {+            // Hoisted: `scanSource` is COMPUTED (it joins the base with the surfaced+            // comment bodies on every read), so reading it once for `matches(of:)` and+            // again inside the loop would hand a `String.Index` derived from one String+            // instance to a different one — a programmer error in Swift that happens to+            // work only while the two instances compare equal. `SearchStateFeeder` hoists+            // it at its sibling site for the same reason.+            let scanSource = components.scanSource+            for match in scanSource.matches(of: footnoteReferenceRegex) {+                guard !FootnoteData.isEscaped(in: scanSource, before: match.range.lowerBound) else {+                    continue+                }                 let identifier = String(match.1)                 if let definition = context.footnoteData.definition(for: identifier) {                     result += " " + stripMarkdownFormatting(definition.content)

diff --git a/prism/Services/FootnotePreprocessor.swift b/prism/Services/FootnotePreprocessor.swiftindex 3dc984ca..10ff0c56 100644--- a/prism/Services/FootnotePreprocessor.swift+++ b/prism/Services/FootnotePreprocessor.swift@@ -350,6 +350,25 @@ enum FootnotePreprocessor: Sendable {          while index < line.endIndex {             if line[index] == "`" {+                // A backslash-escaped backtick is literal text and cannot OPEN a code+                // span (CommonMark "Backslash escapes": `\`not code`` renders the+                // backticks verbatim). Without this the escaped backtick was taken as an+                // opener, so in `` \`[^1]` `` the unmatched trailing backtick closed a+                // code span that never opened and swallowed the reference — while the+                // renderer, parsing the same line through cmark, badges it live. Same+                // odd-backslash-run parity the reference check below uses, from the same+                // predicate, because a divergent second copy is the whole failure class+                // T-1968 is closing.+                //+                // Only the OPENER is escape-aware. Backslash escapes do not apply inside+                // a code span, so the closing run below is matched raw: CommonMark's+                // `` `foo\`bar` `` is `<code>foo\</code>` followed by literal ``bar` ``,+                // not a span running to the final backtick.+                if FootnoteData.isEscaped(in: line, before: index) {+                    index = line.index(after: index)+                    continue+                }+                 var backtickCount = 0                 var btIndex = index                 while btIndex < line.endIndex && line[btIndex] == "`" {@@ -369,10 +388,22 @@ enum FootnotePreprocessor: Sendable {             if line[index] == "[" {                 let remaining = line[index...]                 if let match = remaining.prefixMatch(of: referencePattern) {-                    let identifier = String(match.1)-                    if !seen.contains(identifier) {-                        order.append(identifier)-                        seen.insert(identifier)+                    // A backslash-escaped reference (`\[^1]`) renders as literal text, not+                    // a live reference — it must not consume a display number or keep an+                    // otherwise-orphaned definition alive. Escape-aware the same way+                    // `FootnoteReferenceScanner.scan` decides live vs. literal, so this+                    // scan and the renderer's badge substitution agree on ESCAPING+                    // (T-1968). They can still disagree on other grounds — this scan is+                    // line-at-a-time and regex-based, so an indented code block or a code+                    // span crossing a line boundary is invisible to it, and its+                    // closing-run match does not require equal run lengths. Residuals are+                    // listed in `specs/bugfixes/escaped-footnote-references/report.md`.+                    if !FootnoteData.isEscaped(in: line, before: match.range.lowerBound) {+                        let identifier = String(match.1)+                        if !seen.contains(identifier) {+                            order.append(identifier)+                            seen.insert(identifier)+                        }                     }                     index = match.range.upperBound                     continue

diff --git a/prism/Services/SearchStateFeeder.swift b/prism/Services/SearchStateFeeder.swiftindex 351620fb..441dcf0d 100644--- a/prism/Services/SearchStateFeeder.swift+++ b/prism/Services/SearchStateFeeder.swift@@ -42,12 +42,14 @@ enum SearchStateFeeder {         /// plus the badge occurrence (never a text ordinal — appended footnote         /// text has no rendered equivalent). `occurrence` is the 0-based index among         /// the block's BADGE-RENDERING references to that SAME identifier in source-        /// order — i.e. the badge's DOM index within the section. References that-        /// resolve to a footnote but never render a badge (code spans, escaped-        /// tokens, link-nested text — `FootnoteReferenceScanner`/-        /// `InlineHTMLRenderer.Walker` own that classification) still occupy-        /// match-ordinal space, but are excluded from the occurrence count because-        /// they have no DOM badge to address (T-1853).+        /// order — i.e. the badge's DOM index within the section. A reference that+        /// resolves to a footnote but never renders a badge (a code span or+        /// link-nested text — `FootnoteReferenceScanner`/`InlineHTMLRenderer.Walker`+        /// own that classification) still occupies match-ordinal space, but is+        /// excluded from the occurrence count because it has no DOM badge to address+        /// (T-1853). A backslash-escaped occurrence occupies no ordinal space at all —+        /// it is excluded upstream, same as `FootnotePreprocessor`'s reference scan,+        /// because it is never a reference in the first place (T-1968).         case badge(id: String, occurrence: Int)     } @@ -250,6 +252,14 @@ enum SearchStateFeeder {                 .footnoteScanComponents(forInlineText: source, context: context)                 .scanSource             for match in scanSource.matches(of: FootnoteData.referencePattern) {+                // 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`.+                guard !FootnoteData.isEscaped(in: scanSource, before: match.range.lowerBound) else {+                    continue+                }                 identifiers.append(String(match.1))             }         }@@ -294,17 +304,29 @@ enum SearchStateFeeder {         return sources     } -    /// Badge-eligibility flags aligned one-to-one with `footnoteMatchCounts`'s-    /// entries (same inline-source iteration, same reference regex, same-    /// resolvable-identifier filter). A flag is true when that reference occurrence-    /// actually renders as a badge in the DOM.+    /// 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.+    ///+    /// 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`.     ///     /// 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, escape, link nesting) gets `false`.+    /// (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@@ -330,6 +352,13 @@ enum SearchStateFeeder {             let badgeStarts = Set(starts)             for match in source.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 {+                    continue+                }                 let offset = source.utf16.distance(from: source.startIndex, to: match.range.lowerBound)                 flags.append(badgeStarts.contains(offset))             }@@ -354,12 +383,14 @@ enum SearchStateFeeder {         // matches in order and find which reference occurrence owns this overflow         // position. The occurrence is the winner's DOM badge index: the count of         // PRIOR same-id entries that actually render as badges. Entries that resolve-        // but never badge (code span, escape, link nesting) occupy ordinal space —-        // their definition content is appended to the searchable text — but have no-        // DOM badge, so counting them would skew the index off the section's real-        // badge list (T-1853 review). Eligibility is resolved lazily and only for-        // the one block that owns the current match — normally a lookup of the-        // emit-captured starts, with a renderer fallback only on a cache miss.+        // but never badge (code span, link nesting) occupy ordinal space — their+        // definition content is appended to the searchable text — but have no DOM+        // badge, so counting them would skew the index off the section's real badge+        // list (T-1853 review). A backslash-escaped occurrence is never one of these+        // entries at all — `footnoteMatches` excludes it upstream (T-1968). Eligibility+        // is resolved lazily and only for the one block that owns the current match —+        // normally a lookup of the emit-captured starts, with a renderer fallback only+        // on a cache miss.         var remaining = index - textMatchCount         for (matchIndex, footnote) in footnoteMatches.enumerated() where footnote.count > 0 {             if remaining < footnote.count {

diff --git a/prismTests/FootnotePreprocessorTests.swift b/prismTests/FootnotePreprocessorTests.swiftindex 7e9995d9..62644a98 100644--- a/prismTests/FootnotePreprocessorTests.swift+++ b/prismTests/FootnotePreprocessorTests.swift@@ -941,6 +941,125 @@ struct FootnotePreprocessorTests {         #expect(!result.cleanedSource.contains("Should be orphaned"))     } +    @Test("Backslash-escaped reference is not counted as a reference")+    func testEscapedReferenceIsNotCounted() {+        let source = """+        Text with an escaped \\[^1] that renders as literal text.++        [^1]: Should be orphaned.+        """+        let result = FootnotePreprocessor.process(source)++        // The escaped occurrence is literal text, not a reference, so the+        // definition it would otherwise keep alive is orphaned (T-1968).+        #expect(result.footnoteData.definition(for: "1") == nil)+        #expect(!result.cleanedSource.contains("Should be orphaned"))+    }++    @Test("Escaped reference preceding a live one does not skew display numbers")+    func testEscapedReferenceDoesNotSkewDisplayNumbers() {+        let source = """+        First an escaped \\[^1] then a real[^1] reference.++        [^1]: The only definition.+        """+        let result = FootnotePreprocessor.process(source)++        // The escaped occurrence must not consume a display number before the+        // live one is reached (T-1968): the live reference is still number 1.+        #expect(result.footnoteData.definition(for: "1")?.displayNumber == 1)+        #expect(result.footnoteData.referenceOrder == ["1"])+    }++    @Test("Escaped reference before a different live footnote leaves numbering untouched")+    func testEscapedReferenceDoesNotConsumeANumberForOtherFootnotes() {+        let source = """+        An escaped \\[^skipped] comes first, then a real[^live] reference.++        [^skipped]: Orphaned — never referenced live.+        [^live]: The live one.+        """+        let result = FootnotePreprocessor.process(source)++        #expect(result.footnoteData.definition(for: "skipped") == nil)+        #expect(result.footnoteData.definition(for: "live")?.displayNumber == 1)+        #expect(result.footnoteData.referenceOrder == ["live"])+    }++    @Test("Escaped backslash before a reference does not escape it")+    func testEscapedBackslashLeavesReferenceLive() {+        let source = """+        A literal backslash then a reference: \\\\[^1].++        [^1]: Still live.+        """+        let result = FootnotePreprocessor.process(source)++        // `\\` is an escaped backslash, not an escape of `[` — the reference stays+        // live, matching `FootnoteReferenceScanner`'s left-to-right rule (T-1716,+        // T-1968).+        #expect(result.footnoteData.definition(for: "1")?.displayNumber == 1)+    }++    @Test("An escaped backtick does not open a code span that swallows a reference")+    func testEscapedBacktickDoesNotOpenCodeSpan() {+        // The line is literally: Escaped \`[^1]` still counts.+        // The leading backtick is backslash-escaped, so per CommonMark it is literal+        // text and opens nothing; the trailing backtick is an unmatched literal. The+        // reference between them is live. Before T-1968's review the scan took the+        // escaped backtick as an opener and matched it against the trailing one,+        // swallowing `[^1]` as code — while the renderer, parsing the same line through+        // cmark, badged it. See `testEscapedBacktickAgreesWithTheRenderer` for the+        // parity assertion that pins the two together.+        let source = """+        Escaped \\`[^1]` still counts.++        [^1]: The definition.+        """+        let result = FootnotePreprocessor.process(source)++        #expect(result.footnoteData.referenceOrder == ["1"])+        #expect(result.footnoteData.definition(for: "1")?.displayNumber == 1)+        #expect(result.footnoteData.definition(for: "1")?.content == "The definition.")+        // The reference itself survives into the cleaned source for the renderer to+        // badge — only the DEFINITION line is extracted out of it.+        #expect(result.cleanedSource.contains("[^1]"))+    }++    @Test("Preprocessor and renderer agree on a reference after an escaped backtick")+    func testEscapedBacktickAgreesWithTheRenderer() {+        // The same line, asked of both components that classify `[^1]` independently:+        // the preprocessor's reference scan (which assigns display numbers) and the+        // renderer's badge substitution. Disagreement here is exactly the failure class+        // T-1968 closes — the preprocessor would orphan a footnote the reader can see.+        let line = "Escaped \\`[^1]` still counts."+        let result = FootnotePreprocessor.process("\(line)\n\n[^1]: The definition.")+        let html = FootnoteRenderProbe.emit(line)++        #expect(FootnoteRenderProbe.badgeCount(html) == 1)+        #expect(result.footnoteData.referenceOrder == ["1"])+    }++    @Test("An escaped backslash before a backtick still opens a real code span")+    func testEscapedBackslashBeforeBacktickStillOpensCodeSpan() {+        // The line is literally: Literal backslash \\`[^1]` end.+        // `\\` is an escaped backslash, so the backtick that follows is NOT escaped and+        // opens a genuine code span — the reference inside it renders as literal text+        // and must stay orphaned. The parity check guards the other direction of the+        // fix: making the opener escape-aware must not make every backtick literal.+        let source = """+        Literal backslash \\\\`[^1]` end.++        [^1]: Should be orphaned.+        """+        let result = FootnotePreprocessor.process(source)+        let html = FootnoteRenderProbe.emit("Literal backslash \\\\`[^1]` end.")++        #expect(result.footnoteData.definition(for: "1") == nil)+        #expect(!result.cleanedSource.contains("Should be orphaned"))+        #expect(FootnoteRenderProbe.badgeCount(html) == 0)+    }+     @Test("Empty source produces empty result")     func testEmptySource() {         let result = FootnotePreprocessor.process("")

diff --git a/prismTests/MarkdownBlockSearchContextTests.swift b/prismTests/MarkdownBlockSearchContextTests.swiftindex 04c0f088..771d68e2 100644--- a/prismTests/MarkdownBlockSearchContextTests.swift+++ b/prismTests/MarkdownBlockSearchContextTests.swift@@ -205,6 +205,34 @@ struct MarkdownBlockSearchContextTests {         )     } +    // MARK: - Backslash-escaped footnote references (T-1968)++    /// A backslash-escaped reference (`\[^1]`) renders as literal text, never a+    /// badge, so it must not pull a footnote's content into a block's searchable+    /// text just because some OTHER, live occurrence of the same id resolves it.+    @Test("escaped footnote reference alongside a live one still only contributes once")+    func escapedFootnoteReferenceDoesNotDoubleContribute() {+        let footnote = FootnoteDefinition(+            identifier: "1",+            displayNumber: 1,+            content: "footnote body"+        )+        let data = FootnoteData(+            definitions: ["1": footnote],+            referenceOrder: ["1"]+        )+        let block = MarkdownBlock.paragraph(+            markdown: "An escaped \\[^1] and a live[^1] reference."+        )+        let context = SearchContext(showHTMLComments: false, footnoteData: data)+        let text = block.searchableText(in: context)+        let occurrences = text.components(separatedBy: "footnote body").count - 1+        #expect(+            occurrences == 1,+            "the escaped occurrence must not append the definition a second time; got: \(text)"+        )+    }+     // MARK: - Rejected comment shapes (search/DOM parity, T-1638)      /// The render path routes every inline `<!--…-->` span through

diff --git a/prismTests/WebRendering/WebSearchBridgeTests.swift b/prismTests/WebRendering/WebSearchBridgeTests.swiftindex 470392b4..71abc446 100644--- a/prismTests/WebRendering/WebSearchBridgeTests.swift+++ b/prismTests/WebRendering/WebSearchBridgeTests.swift@@ -617,6 +617,93 @@ struct WebSearchBridgeTests {         #expect(states.first?.current == .badge(id: "1", occurrence: 0))     } +    // MARK: - T-1968: an escaped occurrence occupies no ordinal space at all++    /// The source used by the escape-alignment tests below. Literally:+    /// `Escaped \[^1] alpha then live[^1] and again[^1] end.`+    ///+    /// One escaped `[^1]` followed by two live ones, and the word "alpha" — which is+    /// also footnote 1's content — once in the visible text. So the block's ordinal+    /// space is [1 text match][2 footnote-content matches], one per LIVE reference.+    private static let escapedThenLiveSource =+        "Escaped \\[^1] alpha then live[^1] and again[^1] end."++    @Test("An escaped reference is excluded from both feeder arrays, keeping them aligned")+    func escapedReferenceKeepsFeederArraysAligned() {+        // `referencedFootnoteIdentifiers` and `badgeEligibility` are private, and their+        // documented contract is that they stay aligned entry-for-entry — so the escape+        // filter has to be observed through the payload. Each assertion below fails+        // against a different half of it:+        //+        //  - `matchedFootnoteIds == ["1", "1"]` and `textMatchCount == 1` fail if+        //    `referencedFootnoteIdentifiers` drops its filter: the escaped occurrence+        //    would add a third footnote match, over-claiming the block's 3-match total+        //    and clamping the visible-text portion to 0.+        //  - `current == .badge(id: "1", occurrence: 1)` fails if `badgeEligibility`+        //    drops its filter: the escaped occurrence renders no badge, so its `false`+        //    flag would land at index 0 and push the current badge back to occurrence 0,+        //    marking the FIRST badge instead of the second.+        let blocks: [MarkdownBlock] = [.paragraph(markdown: Self.escapedThenLiveSource)]+        let context = footnoteContext()+        let counts = blocks.map { SearchService.countMatches(query: "alpha", in: $0, context: context) }+        // 1 visible + 1 per live reference. A fourth would mean the escaped occurrence+        // pulled footnote 1's content into the searchable text (the same blind spot on+        // the `combinedSearchableText` side).+        #expect(counts[0] == 3)++        let states = SearchStateFeeder.buildStates(+            query: "alpha",+            blocks: blocks,+            matchCountsPerBlock: counts,+            currentGlobalMatchIndex: 2,+            context: context+        )+        #expect(states.count == 1)+        #expect(states.first?.textMatchCount == 1)+        #expect(states.first?.matchedFootnoteIds == ["1", "1"])+        #expect(states.first?.current == .badge(id: "1", occurrence: 1))+    }++    @Test("Match ordinals across an escaped reference address the right text and badges")+    func escapedReferenceOrdinalsWalkTheLiveOccurrences() {+        // The whole ordinal walk over the same source, one index at a time: 0 is the+        // visible "alpha", then one footnote-content match per live reference — the+        // section's first and second badges. Nothing addresses the escaped occurrence,+        // because it never entered the ordinal space.+        let blocks: [MarkdownBlock] = [.paragraph(markdown: Self.escapedThenLiveSource)]+        let context = footnoteContext()+        let counts = blocks.map { SearchService.countMatches(query: "alpha", in: $0, context: context) }++        let expected: [SearchStateFeeder.CurrentMatch] = [+            .text(ordinal: 0),+            .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("The escaped occurrence renders no badge, so the DOM list is the two live ones")+    func escapedReferenceRendersNoBadge() {+        // The premise the two tests above rest on: the render pipeline itself reports+        // badge starts only for the live occurrences, so a feeder that counted the+        // escaped one would be indexing against a DOM list that does not contain it.+        let starts = InlineHTMLRenderer.badgeSourceStarts(+            source: Self.escapedThenLiveSource, footnotes: footnoteData()+        )+        #expect(starts.count == 2)+        // Offsets of the two live `[^1]` tokens in the source, in DOM order.+        #expect(starts == [29, 43])+    }+     @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/escaped-footnote-references/report.md b/specs/bugfixes/escaped-footnote-references/report.mdnew file mode 100644index 00000000..b4c45816--- /dev/null+++ b/specs/bugfixes/escaped-footnote-references/report.md@@ -0,0 +1,323 @@+# Bugfix Report: Escaped Footnote References Skew Display Numbers++**Date:** 2026-09-06+**Status:** Fixed++## Description of the Issue++`FootnotePreprocessor.scanLineForReferences` counted a backslash-escaped footnote+reference such as `\[^1]` as a real reference. `\[^1]` renders as literal text — the+reader never sees a badge — but the scan still recorded its identifier in+`referenceOrder`, so it consumed a display number nothing displayed and pushed every+subsequent live footnote's number one higher. The same escaped occurrence could also+keep a definition alive that should have been orphan-filtered, since the scan treated+it as a genuine reference to that definition.++The scan already special-cased backtick-delimited inline code (a `[^1]` inside+`` ` `` `` ` `` is correctly excluded), so the missing backslash handling was an+inconsistency rather than an oversight — and it disagreed with+`FootnoteReferenceScanner.scan` (the renderer's badge-substitution pass, T-1716),+which has been escape-aware since it was introduced.++**Reproduction steps:**+1. Write a document containing `First an escaped \[^1] then a real[^1] reference.`+   followed by a single `[^1]: The only definition.`+2. Parse it with `FootnotePreprocessor.process(_:)`.+3. Observe: prior to the fix the escaped occurrence was counted first, so numbering+   drifted once a second, independently-referenced footnote existed ahead of it in+   scan order (a single-footnote document happens to still show `1`, which is why+   this was easy to miss).++**Impact:** Any document mixing an escaped `\[^id]` occurrence with genuine footnote+references got footnote numbering one higher than it should be from that point+onward, and a footnote referenced only via an escaped occurrence was kept alive+(rendered) instead of being dropped as orphaned.++## Investigation Summary++- **Symptoms examined:** `scanLineForReferences`'s character-by-character walk over+  each line: it special-cases backtick spans (skipping code-span content entirely)+  and then matches `FootnoteData.referencePattern` (`/\[\^([a-zA-Z0-9_-]+)\]/`)+  directly against remaining text with no backslash awareness at all.+- **Code inspected:** `FootnotePreprocessor.swift` (reference scan and its state+  machine, reworked two days prior by T-1963 for HTML-block extent — unrelated to+  this scan, which sits in Phase 4 and was untouched by that change),+  `FootnoteReferenceScanner.swift` (the renderer's escape-aware candidacy pass,+  T-1716), `MarkdownBlock.swift` (`combinedSearchableText`) and+  `SearchStateFeeder.swift` (`referencedFootnoteIdentifiers`, `badgeEligibility`) —+  the two search-side consumers the ticket asked to check for the same blind spot.+- **Hypotheses tested:** Whether the T-1963 rework (CommonMark HTML-block handling)+  touched the reference scan — it did not; Phase 4 (`scanReferences`/+  `scanLineForReferences`) is a separate pass from Phase 1's block-extent state+  machine. Whether the search feeders already filtered escaped occurrences via some+  other path (e.g. relying on `FootnoteData.definition(for:)` returning `nil`) —+  confirmed they do not: both scan raw source with the same unescaped regex,+  independently of the preprocessor.++## Discovered Root Cause++Several components each independently decided what counts as a `[^id]` reference.+`FootnoteReferenceScanner.scan` (badge substitution) has been escape-aware since+T-1716; nothing else was. The full inventory of unescaped scanners at the time of the+fix — the review's correction to this report's original "three components" framing:++| # | Site | Purpose | Fixed here? |+|---|------|---------|-------------|+| 1 | `FootnotePreprocessor.scanLineForReferences` | Numbering + orphan filtering | Yes |+| 2 | `MarkdownBlock.combinedSearchableText` | Search text expansion | Yes |+| 3 | `SearchStateFeeder.referencedFootnoteIdentifiers` | Matched-footnote ids | Yes |+| 4 | `SearchStateFeeder.badgeEligibility` | Current-badge occurrence | Yes |+| 5 | `FootnoteStripping.strip` | ToC/anchor/title text | No — pre-existing |+| 6 | `DocumentReaderView.routeDocumentLink` | Badge deep-link block lookup | No — pre-existing |++Sites 5 and 6 are out of scope and are not regressions: `strip` removing a `\[^1]`+from a heading is cosmetic and arguably desirable, and `routeDocumentLink`'s+`textContent.contains("[^id]")` can only pick the wrong block for a badge the user+tapped, which requires a document where the escaped occurrence precedes the live one+in a different block. Both are recorded here so the next person does not have to+rediscover that "the scanners agree now" is false.++**Defect type:** Logic error — a missing predicate (backslash-escape awareness) in a+regex-based scan, present in four of six components that need to agree.++**Why it occurred:** The escape-aware rule was added to `FootnoteReferenceScanner.scan`+in T-1716 when badge substitution was redesigned, but nothing propagated that rule+back to `FootnotePreprocessor` (a much older component) or to the search feeders,+which were each written against the same regex without reference to the others.++**Contributing factors:** The reference-counting rule lives in several separate files+with no shared predicate before this fix — `FootnoteData.referencePattern` was+already centralised, but "is this match escaped" was not.++## Resolution for the Issue++**Changes made:**+- `prism/Models/FootnoteData.swift` — added `FootnoteData.isEscaped(in:before:)`, a+  shared predicate: the character at an index is escaped when it is preceded by an+  odd-length run of backslashes (each backslash escapes exactly the character after+  it, so pairs of backslashes escape each other and leave the following character+  live — equivalent to `FootnoteReferenceScanner.scan`'s left-to-right consumption+  for a single following token). Named for the character rather than for `[^id]`+  because the preprocessor asks the same question of a code-span-opening backtick+  (see the review round below); a reference-shaped name would have invited a second+  copy of the parity walk there.+- `prism/Services/FootnotePreprocessor.swift` — `scanLineForReferences` now skips+  recording an identifier when its match is escaped per the shared predicate, while+  still advancing past the matched span so scanning continues correctly. Its+  code-span skip also treats a backslash-escaped BACKTICK as literal text rather than+  as a code-span opener (see the review round below).+- `prism/Models/MarkdownBlock.swift` — `combinedSearchableText`'s footnote-content+  append loop now skips an escaped occurrence, so it cannot pull a footnote's content+  into a block's searchable text merely because a different, live occurrence of the+  same id resolves it.+- `prism/Services/SearchStateFeeder.swift` — `referencedFootnoteIdentifiers` and+  `badgeEligibility` (which must stay aligned entry-for-entry per their existing+  "same inline-source iteration, same reference regex, same resolvable-identifier+  filter" contract) both gained the same escape filter, plus doc-comment corrections+  removing "escape" from the list of categories that "resolve but never badge yet+  still occupy match-ordinal space" — an escaped occurrence now occupies no ordinal+  space at all, since it is not a reference.+- `prismTests/FootnotePreprocessorTests.swift` — seven new regression tests (four for+  the escape predicate, three for the escaped-backtick opener).+- `prismTests/MarkdownBlockSearchContextTests.swift` — one new regression test for the+  search-side blind spot.+- `prismTests/WebRendering/WebSearchBridgeTests.swift` — three new tests driving+  `SearchStateFeeder.buildStates` over an escaped-plus-live reference pair.+- `CHANGELOG.md` — `[Unreleased] / Fixed` entry.++**Approach rationale:** Rather than adding a third independent escape rule, the fix+centralises the predicate `FootnoteReferenceScanner.scan` already uses (backslash-run+parity) in `FootnoteData`, the file that already centralises the shared reference+regex, and applies it at each of the three sites that scan for `[^id]` outside the+renderer. This directly addresses the ticket's stated concern — three components+independently deciding what counts as a reference — without touching the renderer,+which was already correct.++**Alternatives considered:**+- **Give `FootnotePreprocessor` its own index-based backslash-skip loop** (mirroring+  `FootnoteReferenceScanner`'s UTF-16 buffer walk) — rejected: it would duplicate the+  escape rule a third time in a different shape (index-skipping vs. parity-checking),+  reintroducing exactly the drift risk the ticket flags, for no behavioural gain over+  a shared predicate.+- **Leave the search feeders as a "finding" without a code fix** — considered, since+  the ordinal-space bookkeeping between `combinedSearchableText`,+  `referencedFootnoteIdentifiers`, and `badgeEligibility` is order-sensitive.+  Rejected once inspection showed the three loops already share "same inline-source+  iteration, same reference regex, same resolvable-identifier filter" as a documented+  invariant — adding "same escape filter" to all three keeps that invariant intact+  rather than fighting it, so the fix is contained.++## Regression Test++**Test file:** `prismTests/FootnotePreprocessorTests.swift`+**Test names:**+- `testEscapedReferenceIsNotCounted`+- `testEscapedReferenceDoesNotSkewDisplayNumbers`+- `testEscapedReferenceDoesNotConsumeANumberForOtherFootnotes`+- `testEscapedBackslashLeavesReferenceLive`++**What it verifies:** An escaped `\[^1]` orphans its definition instead of keeping it+alive; an escaped reference preceding a live reference to the SAME id leaves the live+one at display number 1; an escaped reference to a DIFFERENT, otherwise-unreferenced+id does not consume a number that should belong to a later live footnote; an escaped+*backslash* (`\\[^1]`) does not escape the reference that follows it, matching+`FootnoteReferenceScanner`'s rule.++**Test file:** `prismTests/MarkdownBlockSearchContextTests.swift`+**Test name:** `escapedFootnoteReferenceDoesNotDoubleContribute`++**What it verifies:** With an escaped `\[^1]` and a live `[^1]` in the same block, the+footnote's definition content is appended to the block's searchable text exactly once,+not twice.++**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 \+  -only-testing:prismTests/FootnotePreprocessorTests \+  -only-testing:prismTests/FootnotePreprocessorHTMLBlockExtentTests \+  -only-testing:prismTests/FootnotePreprocessorBlockExtentParityTests \+  -only-testing:prismTests/MarkdownBlockSearchContextTests+```++## Affected Files++| File | Change |+|------|--------|+| `prism/Models/FootnoteData.swift` | Added shared `isEscaped(in:before:)` predicate |+| `prism/Services/FootnotePreprocessor.swift` | `scanLineForReferences` now skips escaped matches |+| `prism/Models/MarkdownBlock.swift` | `combinedSearchableText` now skips escaped matches |+| `prism/Services/SearchStateFeeder.swift` | `referencedFootnoteIdentifiers`/`badgeEligibility` now skip escaped matches; doc comments corrected |+| `prismTests/FootnotePreprocessorTests.swift` | 7 new regression tests |+| `prismTests/MarkdownBlockSearchContextTests.swift` | 1 new regression test |+| `prismTests/WebRendering/WebSearchBridgeTests.swift` | 3 new regression tests |+| `specs/footnotes/decision_log.md` | Quick decision Q1 (escape rule) |+| `CHANGELOG.md` | `[Unreleased] / Fixed` entries |++## Review Round (PR #416)++The local review confirmed the escape predicate itself and raised two items; both were+actioned, along with three follow-ups from the pre-push review.++**1. `SearchStateFeeder` had no direct test.** Added three to+`prismTests/WebRendering/WebSearchBridgeTests.swift`, driving `buildStates` over+`Escaped \[^1] alpha then live[^1] and again[^1] end.` — an escaped occurrence, two+live ones, and a visible "alpha" that is also footnote 1's content. Each assertion+fails against a different half of the filter, verified by mutation: dropping the+filter from `referencedFootnoteIdentifiers` breaks `textMatchCount == 1` and+`matchedFootnoteIds == ["1", "1"]` (the escaped entry over-claims the block's total),+and dropping it from `badgeEligibility` breaks+`current == .badge(id: "1", occurrence: 1)` (the escaped entry's `false` flag lands at+index 0 and pushes the current badge back one).++**2. The code-span backtick skip was not escape-aware.** Fixed rather than deferred,+because it reuses the same predicate. Per CommonMark, a backslash-escaped backtick is+literal text and cannot OPEN a code span, so `` \`[^1]` `` is a live reference followed+by an unmatched literal backtick — but the skip took the escaped backtick as an opener,+matched it against the trailing one, and swallowed the reference, orphaning a footnote+the reader can see. Only the OPENER is escape-aware: backslash escapes do not apply+inside a code span, so the closing run is still matched raw (CommonMark's+`` `foo\`bar` `` is `<code>foo\</code>` followed by literal ``bar` ``). Three tests,+one of them asserting preprocessor/renderer parity directly through+`FootnoteRenderProbe`.++**3. `String.Index` across two instances of a computed property (blocking).**+`MarkdownBlock.combinedSearchableText` read `components.scanSource` — which JOINS its+inputs on every read — once for `matches(of:)` and again per iteration as the escape+predicate's `text`, so an index from one String instance subscripted a different one.+That is a programmer error in Swift and worked only because the instances compare+equal. Hoisted to a `let`; the sibling site in `SearchStateFeeder` already did this.++**4. Overclaiming comments.** Three comment blocks said the scanners "can never+disagree" / "stay in lockstep". Reworded to what is true: the shared predicate settles+ESCAPING at four sites, and the residuals below remain.++### Known residuals++Recorded rather than fixed, and none of them regressions:++- **Comment excision can fabricate an escape (new, narrow).**+  `HTMLCommentStripping.removing` excises a span leaving no separator, so+  `A\<!-- x -->[^1]` collapses to `A\[^1]` in `scanSource` and reads as escaped, while+  the renderer badges it — cmark treats `\<` as an escaped `<`, so no comment ever+  opened. The mis-detection is upstream in the comment scan; inserting a separator+  would change the searchable text of every commented block, which is a wider change+  than this ticket.+- **`badgeEligibility` scans the raw source, `referencedFootnoteIdentifiers` the+  comment-gated `scanSource`** (pre-existing). For a block containing an HTML comment+  the two iterate different text, so the arrays can still shift relative to each+  other. `currentMatch` degrades safely — a missing flag is read as eligible.+- **The preprocessor's scan is line-at-a-time**, so it cannot see an indented code+  block or a code span that spans lines, and its closing-run match does not require+  equal run lengths (pre-existing).+- **The reserved Private Use Area window** the renderer marks references with is not+  something the preprocessor models at all (pre-existing, by design).+- **`FootnoteStripping.strip` and `DocumentReaderView.routeDocumentLink`** do not+  consult the predicate (sites 5 and 6 above).++## Verification++**Automated:**+- [x] Regression tests pass (`FootnotePreprocessorTests`, `MarkdownBlockSearchContextTests`,+      `WebSearchBridgeTests`)+- [x] Mutation-checked (PR #416 round): with the escape filter removed from BOTH+      `SearchStateFeeder` sites, `escapedReferenceKeepsFeederArraysAligned` and+      `escapedReferenceOrdinalsWalkTheLiveOccurrences` fail and+      `escapedReferenceRendersNoBadge` still passes — the last asserts the renderer's+      own behaviour, which the mutation does not touch, so it is the premise rather+      than a detector. Result bundle read by `Tools/check-test-results.sh`:+      `total=3 passed=1 failed=2`.+- [!] Machine-state caveat for the final verification pass: after the first run of the+      review round, every subsequent `xcodebuild test` on this machine wedged during+      TEARDOWN — tests completed (the log records each one), then the process slept+      indefinitely without finalising its result bundle, so+      `Tools/check-test-results.sh` could not read it. This is the wedge recorded in+      the project's testmanagerd note, not a property of the change; killing+      `testmanagerd` did not clear it, and by the last attempt the run hung before any+      test executed at all. Evidence actually collected: one checker-verified bundle+      (`total=108 passed=107 failed=1` — the single failure being an incorrect+      `cleanedSource` expectation in a new test, since corrected), the+      checker-verified mutation bundle above, and four further log-only runs recording+      422 / 190 / 189 / 189 executions with zero failures, the 422-execution run+      covering ten footnote suites. The corrected assertion is confirmed by those+      log-only runs rather than by a bundle.+- [x] Adjacent suites pass (`FootnotePreprocessorHTMLBlockExtentTests`,+      `FootnotePreprocessorBlockExtentParityTests` — unaffected by this change, run to+      confirm no disturbance from the T-1963 rework's neighbourhood;+      `FootnoteBadgeSubstitutionTests`, `FootnoteBadgeOrderingTests`,+      `FootnoteBadgeNestedContextTests`, `FootnoteNonTextOccurrenceTests` — the+      renderer-side escape suite, confirming component #2 needed no change)+- [x] `make lint` passes+- [x] `make build-macos` passes+- [ ] Full `make test-quick` / `make test-locales` — intentionally NOT run per task+      instructions (concurrent sibling builds); targeted suites above were run instead++**Manual verification:** Traced the call sites by hand against+`FootnoteReferenceScanner.scan`'s documented escape rule to confirm the shared+predicate's parity check produces the same live/escaped classification for `\[^1]`+(escaped) and `\\[^1]` (not escaped, since the pair of backslashes escapes itself).++## Prevention++**Recommendations to avoid similar bugs:**+- When a new predicate is added to one of several components that must agree on+  parsing a shared syntax (here, `[^id]`), centralise it next to the shared pattern+  (`FootnoteData.referencePattern`) rather than leaving it local to the component+  that first needed it — this is the same shape T-1963 named for HTML-block extent+  (preprocessor vs. real parser) and now for reference escaping (preprocessor vs.+  renderer vs. search).+- The ticket also asked to verify two documentation claims: a code comment in+  `InlineHTMLRenderer` and CLAUDE.md's Footnote System section were checked and no+  longer contain any statement that badge substitution "agrees with+  scanLineForReferences" — both were already cleaned up by the T-1963/T-1716+  rewrites before this ticket, so no correction was needed there.++## Related++- T-1716 (introduced `FootnoteReferenceScanner.scan`'s escape-aware badge substitution)+- T-1963 (footnote preprocessor HTML-block extent parity, most recent prior rework of+  this file)+- T-1853 (footnote search current-match occurrence addressing, whose "occupies+  ordinal space" comments this fix corrects for the escape case)

diff --git a/specs/footnotes/decision_log.md b/specs/footnotes/decision_log.mdindex 731b7c8d..b4a85831 100644--- a/specs/footnotes/decision_log.md+++ b/specs/footnotes/decision_log.md@@ -1,5 +1,12 @@ # Decision Log: Footnotes +## Quick Decisions++| ID | Date | Decision | Rationale |+|----|------|----------|-----------|+| Q1 | 2026-09-06 | A `[^id]` occurrence is escaped when an odd-length run of backslashes immediately precedes it, decided by one shared `FootnoteData.isEscaped(in:before:)` used by every scanner outside the renderer | Restates `FootnoteReferenceScanner.scan`'s existing left-to-right rule (T-1716) rather than inventing a second one; parity is equivalent because a `Regex` match reports only where a token starts. No genuine alternative — a per-site copy is the bug (T-1968) |+| Q2 | 2026-09-06 | The predicate is named for the character, not for `[^id]`, and the preprocessor's code-span skip applies it to a backtick — the opener only, never the closing run | CommonMark escapes a code-span-opening backtick by the same rule, but backslash escapes do not apply inside a code span (`` `foo\`bar` `` is `<code>foo\</code>` plus literal text). A reference-shaped name would have invited a second copy of the parity walk (T-1968 review) |+ ## Decision 1: Feature Name  **Date**: 2026-03-31

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f75bfbce..31a564f4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - On the Mac, opening a document while another one is already open now closes the image and diagram windows belonging to the document you left, instead of stranding them (T-1757). Those windows were only ever cleared away by closing a document explicitly; opening a replacement — from the file picker, Recent Files, a paste, the bundled guides, or a URL — left them on screen belonging to a document that was no longer open, with no way left to clear them short of closing each one by hand. Reopening the document you are already reading is not a replacement and leaves its windows exactly where they are, so picking the current document again from Recent Files still costs you nothing; refreshing a URL document and reloading a file changed on disk keep those windows too, as they always have. Two pasted documents are never treated as the same document, so pasting fresh content still clears the previous paste's windows. - HTML comments embedded in paragraph text (and in headings, list items, and table cells) render again as dimmed inline annotations when "Show HTML comments" is on — they were silently dropped by the new rendering engine (T-1638). Stand-alone comments nested inside blockquotes or list items now get the same toggleable annotation treatment instead of leaking as always-visible plain text, and comment annotations regained their info indicator glyph. Search now stays aligned with what is actually rendered: comment shapes that are never displayed (conditional comments, note-infrastructure tags) no longer count as matches when the toggle is on, and hidden comment text nested inside blockquotes or list items no longer produces phantom highlights. - A note written while a document's notes are still loading is no longer thrown away when the load finishes (T-2089). Notes can be added the moment a document appears, but loading them from iCloud takes a moment longer — and a note added in that gap vanished from the screen as soon as the load landed, because the load put back the set of notes it had read before your note existed. Where that load also had to re-attach notes to moved text, it saved that older set back to iCloud too, so the note was gone for good rather than just off-screen until the next reopen. The load now recognises when the notes have moved on beneath it and keeps what is on screen — your note and everything already stored — instead of replacing it. A reload with nothing added still picks up whatever iCloud holds, as before.+- A backslash-escaped footnote reference (`\[^1]`) no longer consumes a display number or keeps an otherwise-orphaned definition alive (T-1968). The footnote preprocessor's reference scan counted `\[^1]` as a real reference even though it renders as literal text — a footnote it kept alive that way pushed every genuinely-referenced footnote's display number one higher, and the renderer already deliberately declined to badge it, so the two disagreed on what counted as a reference. The scan is now escape-aware the same way the renderer is: a reference preceded by an odd-length run of backslashes is literal, an even-length run (including zero) is live. Search shared the same blind spot — a block's searchable text and its footnote-badge indication both scanned raw source for `[^id]` with no escape awareness, so an escaped occurrence sitting alongside a live reference to the same footnote could pull that footnote's content into search a second time — and now shares the same escape check.+- An escaped backtick no longer hides the footnote reference that follows it (T-1968). The preprocessor's code-span skip treated every backtick as a code-span delimiter, so in a line like `` \`[^1]` `` — an escaped backtick, a live reference, then a stray literal backtick — it paired the two backticks up and read the reference as code, dropping the footnote from the document's numbering and orphaning its definition. The renderer, which parses the line properly, showed the badge, so the footnote appeared with no number behind it. A backslash-escaped backtick is now literal text and opens nothing, matching CommonMark and matching what the renderer already did. Only the opening backtick is treated this way: backslashes have no escaping power inside a code span, so a backtick that closes one still closes it.  ### Security