Pre-push review: T-1979 — open footnote popovers keep stale render state

diff --git a/prism/Views/FootnotePopoverView.swift b/prism/Views/FootnotePopoverView.swiftindex 1fdb637..73cf1ff 100644--- a/prism/Views/FootnotePopoverView.swift+++ b/prism/Views/FootnotePopoverView.swift@@ -10,7 +10,8 @@ //  header stays a native (localised) label; the WebView shows the rendered content. // //  Isolation (Req 8.4): the shared page loads fresh content per presentation and retains-//  nothing between footnotes — `present` on appear, `reset` on disappear.+//  nothing between footnotes — `present` whenever the render key moves (including on+//  appear), `reset` on disappear. //  import SwiftUI@@ -44,8 +45,8 @@ struct FootnotePopoverView: View {      /// The popover page's complete render input, as one equatable value.     ///-    /// Static and pure so it can be asserted without mounting the view — and so a later-    /// change can key a re-present on it (T-1979) rather than re-deriving the inputs.+    /// Static and pure so it can be asserted without mounting the view — and so the+    /// re-present key (T-1979) observes exactly these inputs rather than re-deriving them.     ///     /// `contrast` and `dynamicTypeSize` carry no default, matching `typographyVariables`     /// and `pushInitialState`: a silently `.standard`/`.large` default is invisible at the@@ -79,14 +80,30 @@ struct FootnotePopoverView: View {         )     } +    /// The popover page's complete render input, including which footnote and which+    /// definition — the value an open popover must stay in step with (T-1979).+    ///+    /// Evaluated in `body`, which is what makes this work at all: reading+    /// `settings.showHTMLComments` and `settings.theme(for:)` here registers them with+    /// Observation, so an `AppSettings` change invalidates the body and re-runs the+    /// comparison below. Reading them only inside the old `onAppear` closure registered+    /// nothing, so nothing ever re-presented.+    private var renderKey: FootnotePopoverWebPage.RenderKey {+        FootnotePopoverWebPage.RenderKey(+            footnoteId: footnoteId, data: data, settings: renderSettings+        )+    }+     var body: some View {         content-            .onAppear {+            // One trigger for every input, fired on appear too (`initial: true`). The page+            // ignores an unchanged key, so this cannot thrash the WebPage on an unrelated+            // body pass. Splitting it back into an appear hook plus an identifier-only+            // trigger is the bug: theme, contrast, typography, comment visibility, and a+            // same-id definition replacement all move the key, none move the identifier.+            .onChange(of: renderKey, initial: true) {                 popoverPage.present(footnoteId: footnoteId, data: data, settings: renderSettings)             }-            .onChange(of: footnoteId) { _, newID in-                popoverPage.present(footnoteId: newID, data: data, settings: renderSettings)-            }             .onDisappear {                 // Retain nothing once dismissed (Req 8.4).                 popoverPage.reset()

diff --git a/prism/ViewModels/FootnotePopoverWebPage.swift b/prism/ViewModels/FootnotePopoverWebPage.swiftindex 699473c..921161c 100644--- a/prism/ViewModels/FootnotePopoverWebPage.swift+++ b/prism/ViewModels/FootnotePopoverWebPage.swift@@ -12,6 +12,11 @@ //  between footnotes or documents. `present` replaces the served HTML and reloads; //  `reset` clears it back to empty so a dismissed popover holds no prior content. //+//  Freshness (T-1979): the page is bridge-less, so everything it renders — content,+//  palette, contrast, typography, comment visibility — is baked in at emit time and can+//  only change by re-presenting. `present` is therefore keyed on the whole `RenderKey`:+//  it reloads when any of those move and no-ops when none did.+// //  Reuse: footnote content is parsed with the same `MarkdownBlockParser.parseFragment` //  used by the legacy popover and rendered through `BlockHTMLEmitter` — the same emitter //  the document surface uses — so popover rendering matches document rendering. Only the@@ -38,10 +43,49 @@ final class FootnotePopoverWebPage {     /// The identifier of the footnote currently rendered, for the view's header.     private(set) var footnoteId: String? +    /// The render input the currently-served HTML was emitted from, or nil when the page+    /// holds the empty reset content. Compared on every `present` so an unchanged+    /// re-evaluation is a no-op rather than a reload (T-1979).+    private(set) var renderKey: RenderKey?++    /// Bumped by every actual load. Doubles as the presentation generation: a load task+    /// started for an earlier state observes a newer value and stops, so an older refresh+    /// can never report after a newer one began (T-1979). Also drives the document URL's+    /// `rev`, so each present is a distinct navigation rather than a same-URL reload.+    private(set) var renderGeneration: Int = 0+     private static let logger = Logger.prism(category: "FootnotePopover") -    /// A stable per-page document URL (the content varies; the URL does not).-    private static let documentURL = URL(string: "prism-doc://document/footnote?rev=1")!+    /// The document URL for a given generation. The route ignores the query (any session+    /// id / rev resolves to `.document`); varying it keeps consecutive presents from+    /// collapsing into one navigation.+    private static func documentURL(generation: Int) -> URL {+        URL(string: "prism-doc://document/footnote?rev=\(generation)")!+    }++    /// The complete set of inputs the served HTML is a function of.+    ///+    /// The page is bridge-less by design (Decision 10): palette, contrast, typography,+    /// comment visibility and content are all baked into the HTML at emit time, so a live+    /// page does not change when any of them change — only a re-present updates it. That+    /// is why presentation is keyed on this whole value and not on `footnoteId` alone,+    /// which is the T-1979 bug: every input except the identifier could change under an+    /// open popover and leave it showing the state it was born with.+    ///+    /// It holds the resolved `FootnoteDefinition` rather than the whole `FootnoteData`, so+    /// a document reload that leaves this footnote untouched does not reload the popover,+    /// while one that replaces its content under the same identifier does.+    struct RenderKey: Equatable, Sendable {+        let footnoteId: String+        let definition: FootnoteDefinition?+        let settings: RenderSettings++        init(footnoteId: String, data: FootnoteData, settings: RenderSettings) {+            self.footnoteId = footnoteId+            self.definition = data.definition(for: footnoteId)+            self.settings = settings+        }+    }      init() {         let htmlBox = HTMLBox()@@ -66,7 +110,14 @@ final class FootnotePopoverWebPage {      /// Renders `footnoteId`'s content fresh and loads it (Req 7.1). Replaces any prior     /// content first so a re-present never shows the previous footnote.+    ///+    /// Idempotent in its inputs (T-1979): callers re-present whenever any render input+    /// may have moved, and an unchanged call must not reload — that would re-emit the+    /// same bytes and blank the live page mid-read for nothing.     func present(footnoteId: String, data: FootnoteData, settings: RenderSettings) {+        let key = RenderKey(footnoteId: footnoteId, data: data, settings: settings)+        guard key != renderKey else { return }+        renderKey = key         self.footnoteId = footnoteId         htmlBox.set(Self.emitHTML(footnoteId: footnoteId, data: data, settings: settings))         load()@@ -78,6 +129,9 @@ final class FootnotePopoverWebPage {     /// present(). (Pre-existing gap surfaced by WebFootnotePopoverTests.liveResetEmpties.)     func reset() {         footnoteId = nil+        // Unconditional, unlike `present`: clearing is the isolation guarantee, so it is+        // never skipped on the strength of a key comparison.+        renderKey = nil         htmlBox.set(Self.emitHTML(footnoteId: nil, data: .empty, settings: RenderSettings()))         load()     }@@ -105,11 +159,27 @@ final class FootnotePopoverWebPage {     // MARK: - Private      private func load() {-        let url = Self.documentURL-        Task { [page] in+        renderGeneration += 1+        let generation = renderGeneration+        let url = Self.documentURL(generation: generation)+        // The guard is robustness, not ordering. Nothing here orders the navigations+        // themselves — two rapid presents enqueue two tasks — and nothing needs to:+        // content correctness comes from `htmlBox`, which `present` writes synchronously+        // before calling this, so every navigation (superseded or not) is served the+        // newest bytes and there are no older bytes left to serve. What the guard buys is+        // that a task overtaken by a newer load does not act on its events, and does not+        // log a failure that only means "you were superseded" (T-1979).+        //+        // Guarded rather than cancelled: the superseded navigation ends on its own once+        // the newer load starts, and calling `cancel` on the old consumer risks tearing+        // down the new navigation instead if it lands after the swap.+        Task { [weak self, page] in             do {-                for try await _ in page.load(URLRequest(url: url)) {}+                for try await _ in page.load(URLRequest(url: url)) {+                    guard self?.renderGeneration == generation else { return }+                }             } catch {+                guard self?.renderGeneration == generation else { return }                 Self.logger.error("Footnote popover load failed: \(error.localizedDescription)")             }         }

diff --git a/prismTests/WebRendering/WebFootnotePopoverTests.swift b/prismTests/WebRendering/WebFootnotePopoverTests.swiftindex abfbb4d..245078c 100644--- a/prismTests/WebRendering/WebFootnotePopoverTests.swift+++ b/prismTests/WebRendering/WebFootnotePopoverTests.swift@@ -131,6 +131,242 @@ struct WebFootnotePopoverTests {         #expect(try await waitForBodyText(page.page, absent: "First footnote body."))     } +    // MARK: - Live render-state refresh (T-1979)++    /// The view is the only thing that can refresh a bridge-less page, so this pins the+    /// wiring: presenting must be keyed on the WHOLE render input, not on `footnoteId`.+    ///+    /// Keying on `footnoteId` alone is the bug — a theme flip, an Increase Contrast+    /// change, a comment-visibility toggle, a Dynamic Type change, or a document reload+    /// that replaces the definition under the same identifier all leave the identifier+    /// untouched, so the open popover kept the HTML it was born with.+    @Test("The popover presents on its whole render key, not on the footnote id alone")+    func viewPresentsOnRenderKey() throws {+        let source = try String(+            contentsOf: URL(fileURLWithPath: #filePath)+                .deletingLastPathComponent()   // WebRendering+                .deletingLastPathComponent()   // prismTests+                .deletingLastPathComponent()   // repo root+                .appendingPathComponent("prism/Views/FootnotePopoverView.swift"),+            encoding: .utf8+        )+        // Assert on the CODE, not on the comments — which discuss the old `onAppear`+        // trigger by name and would otherwise satisfy (or defeat) every check below.+        let code = source+            .split(separator: "\n", omittingEmptySubsequences: false)+            .filter { !$0.trimmingCharacters(in: .whitespaces).hasPrefix("//") }+            .joined(separator: "\n")++        // `initial: true` is load-bearing and is the most likely accidental edit: without+        // it the FIRST present never fires, so a sheet opened after a prior `reset()` shows+        // the empty document. Pin the whole trigger, not just its key.+        #expect(+            code.contains("onChange(of: renderKey, initial: true)"),+            """+            FootnotePopoverView must drive `popoverPage.present` from the composite \+            render key, fired on appear too (`initial: true`). Presenting only \+            `onAppear`/`onChange(of: footnoteId)` leaves an open popover showing stale \+            theme, contrast, typography, comment visibility, and definition content; \+            dropping `initial: true` leaves a freshly-opened popover on the empty \+            document until some input happens to move (T-1979).+            """+        )+        #expect(+            !code.contains("onChange(of: footnoteId)"),+            "The footnote id is one component of the render key, not a separate trigger."+        )+        // …and the trigger must actually present. A key-only `onChange` that did+        // something else would satisfy the checks above.+        let trigger = code.range(of: "onChange(of: renderKey, initial: true)").map {+            String(code[$0.upperBound...].prefix(300))+        }+        #expect(+            trigger?.contains("popoverPage.present(") == true,+            "The render-key trigger must call popoverPage.present."+        )+        // The key trigger is the ONLY present trigger: an `onAppear`-driven present would+        // hide a regression that drops `initial: true` above.+        #expect(+            !code.contains(".onAppear"),+            "The render key is the only present trigger; an onAppear hook is the old bug."+        )+    }++    /// The render key must move for every input the emitted HTML depends on — it is the+    /// only thing standing between a changed input and a stale open popover.+    @Test("The render key moves with every input the emitted HTML depends on")+    func renderKeyIsInputSensitive() {+        let data = footnoteData()+        func key(+            id: String = "1",+            data keyData: FootnoteData? = nil,+            settings: RenderSettings = RenderSettings()+        ) -> FootnotePopoverWebPage.RenderKey {+            FootnotePopoverWebPage.RenderKey(+                footnoteId: id, data: keyData ?? data, settings: settings+            )+        }+        let baseline = key()+        #expect(baseline == key())++        // Identifier.+        #expect(baseline != key(id: "2"))+        // Palette: theme key and Increase Contrast (T-1829, one pair).+        #expect(baseline != key(settings: RenderSettings(+            palette: WebPaletteFeed(themeKey: "prism-dark", contrast: .standard)+        )))+        #expect(+            key(settings: RenderSettings(+                palette: WebPaletteFeed(themeKey: "prism-dark", contrast: .standard)+            ))+            != key(settings: RenderSettings(+                palette: WebPaletteFeed(themeKey: "prism-dark", contrast: .increased)+            ))+        )+        // Comment visibility.+        #expect(baseline != key(settings: RenderSettings(showHTMLComments: true)))+        // Typography (T-1978).+        #expect(baseline != key(settings: RenderSettings(typography: ["--prism-scale": "1.500"])))++        // A definition replaced under the SAME identifier — the document-reload case.+        var replaced = data.definitions+        replaced["1"] = FootnoteDefinition(identifier: "1", displayNumber: 1, content: "Rewritten body.")+        let reloaded = FootnoteData(definitions: replaced, referenceOrder: data.referenceOrder)+        #expect(baseline != key(data: reloaded))++        // …but a reload that leaves THIS footnote alone must not move the key, or every+        // document change would reload the open popover for nothing.+        var untouched = data.definitions+        untouched["2"] = FootnoteDefinition(identifier: "2", displayNumber: 2, content: "Different.")+        #expect(baseline == key(data: FootnoteData(+            definitions: untouched, referenceOrder: data.referenceOrder+        )))+    }++    @Test("An unchanged re-present does not reload; a changed input does")+    func rePresentIsDedupedByRenderKey() {+        let page = FootnotePopoverWebPage()+        let data = footnoteData()++        page.present(footnoteId: "1", data: data, settings: RenderSettings())+        let first = page.renderGeneration+        #expect(first > 0)++        // Same inputs: no reload (the live page would otherwise blank and re-render).+        page.present(footnoteId: "1", data: data, settings: RenderSettings())+        #expect(page.renderGeneration == first)++        // Changed palette: reload.+        page.present(footnoteId: "1", data: data, settings: RenderSettings(+            palette: WebPaletteFeed(themeKey: "prism-dark", contrast: .standard)+        ))+        #expect(page.renderGeneration == first + 1)++        // Reset always reloads, then the same footnote presents again from scratch.+        page.reset()+        #expect(page.renderKey == nil)+        #expect(page.renderGeneration == first + 2)+        page.present(footnoteId: "1", data: data, settings: RenderSettings())+        #expect(page.renderGeneration == first + 3)+    }++    // MARK: - Live: an open popover follows its render inputs (T-1979)++    @Test("A live theme change re-renders the open popover in the new palette")+    func liveThemeChangeRefreshesOpenPopover() async throws {+        let page = FootnotePopoverWebPage()+        let data = footnoteData()+        func settings(_ themeKey: String) -> RenderSettings {+            RenderSettings(palette: WebPaletteFeed(themeKey: themeKey, contrast: .standard))+        }++        // DARK FIRST, deliberately: `prism-light` is document.css's `:root` default+        // (`:root, :root[data-prism-theme="prism-light"]`), so opening on light and+        // asserting light passes identically with no palette baked at all. Starting on a+        // non-default palette makes the first assertion prove the bake reached the+        // renderer, and every later assertion differs from the state before it, so a bake+        // that stops applying part-way cannot slip through either.+        page.present(footnoteId: "1", data: data, settings: settings("prism-dark"))+        #expect(try await waitForBodyText(page.page, contains: "First footnote body."))+        // getComputedStyle, not the markup: the assertion is that the page actually+        // RESOLVES the baked palette, so a bake that never reached the renderer fails.+        #expect(try await waitForBackgroundColor(page.page, equals: Self.prismDarkBackground))++        // The same footnote, a new palette — the identifier has not moved, which is+        // exactly why this used to leave the popover on the old theme (T-1979). The page+        // is dark right now, so "renders light" here means it actually MOVED.+        page.present(footnoteId: "1", data: data, settings: settings("prism-light"))+        #expect(try await waitForBackgroundColor(page.page, equals: Self.prismLightBackground))+        // And once more, to a palette that is neither the default nor the previous value:+        // a re-present that only ever works the first time fails here.+        page.present(footnoteId: "1", data: data, settings: settings("refraction"))+        #expect(try await waitForBackgroundColor(page.page, equals: Self.refractionBackground))+        // The content survives the re-renders (this is a refresh, not a reset).+        #expect(try await bodyText(page.page).contains("First footnote body."))+    }++    @Test("A same-identifier definition replacement re-renders the open popover")+    func liveDefinitionReplacementRefreshesOpenPopover() async throws {+        let page = FootnotePopoverWebPage()+        page.present(footnoteId: "1", data: footnoteData(), settings: RenderSettings())+        #expect(try await waitForBodyText(page.page, contains: "First footnote body."))++        // A document reload supplies new content under the same identifier.+        let reloaded = FootnoteData(+            definitions: [+                "1": FootnoteDefinition(+                    identifier: "1", displayNumber: 1, content: "Rewritten after reload."+                ),+            ],+            referenceOrder: ["1"]+        )+        page.present(footnoteId: "1", data: reloaded, settings: RenderSettings())+        #expect(try await waitForBodyText(page.page, contains: "Rewritten after reload."))+        #expect(!(try await bodyText(page.page)).contains("First footnote body."))+    }++    /// What keeps overlapping presents correct is the HTML box, not the generation guard+    /// in `load()`: `present` writes the newly emitted HTML into the box SYNCHRONOUSLY,+    /// so whichever navigation the scheme handler ends up serving — the newest, or one+    /// that was superseded while still in flight — it is handed the newest bytes. There+    /// are no older bytes left to serve.+    ///+    /// So that is what this asserts. The generation guard orders nothing (see the comment+    /// on `FootnotePopoverWebPage.load()`); it only stops a superseded task from acting or+    /// logging, which is robustness, not this property. A regression that stopped writing+    /// the newest HTML up front — capturing it per load and committing it when that load+    /// runs — would let a superseded navigation paint older content, and fails here.+    @Test("A superseded, in-flight load still leaves the page on the newest render state")+    func overlappingPresentsSettleOnNewest() async throws {+        let page = FootnotePopoverWebPage()+        let data = footnoteData()++        page.present(footnoteId: "1", data: data, settings: RenderSettings())+        #expect(try await waitForBodyText(page.page, contains: "First footnote body."))++        // Start a second navigation and let it genuinely BEGIN — `load()`'s task is+        // MainActor-bound, so it cannot run until this suspension — then supersede it+        // mid-flight with a third.+        page.present(footnoteId: "2", data: data, settings: RenderSettings())+        try await Task.sleep(for: .milliseconds(5))+        page.present(+            footnoteId: "3", data: data,+            settings: RenderSettings(palette: WebPaletteFeed(themeKey: "prism-dark", contrast: .standard))+        )+        #expect(page.footnoteId == "3")++        #expect(try await waitForBodyText(page.page, contains: "item two"))+        #expect(try await waitForBackgroundColor(page.page, equals: Self.prismDarkBackground))++        // …and it stays settled: the superseded navigation cannot commit older content,+        // whichever order the two finish in.+        try await Task.sleep(for: .milliseconds(300))+        let text = try await bodyText(page.page)+        #expect(text.contains("item two"))+        #expect(!text.contains("First footnote body."))+        #expect(!text.contains("emphasis"))+    }+     // MARK: - Badge tap routing (Req 7.1)      @Test("A footnote deep link resolves to the identifier the coordinator presents")@@ -175,6 +411,33 @@ struct WebFootnotePopoverTests {         return !(try await bodyText(page)).contains(needle)     } +    /// `document.css`'s `--prism-background` for the two themes these tests flip between,+    /// as the renderer resolves it on `body { background-color: … }`.+    private static let prismLightBackground = "rgb(238, 240, 250)"   // #EEF0FA+    private static let prismDarkBackground = "rgb(11, 16, 32)"       // #0B1020+    private static let refractionBackground = "rgb(237, 235, 246)"   // #EDEBF6++    /// Polls the live page's RESOLVED body background colour until it matches.+    ///+    /// Asserting on computed style rather than on the emitted attribute is the point: it+    /// proves the baked palette reached the renderer, which is the whole failure mode of a+    /// bridge-less page that never re-presented.+    private func waitForBackgroundColor(_ page: WebPage, equals expected: String) async throws -> Bool {+        for _ in 0..<60 {+            if (try? await backgroundColor(page)) == expected { return true }+            try await Task.sleep(for: .milliseconds(50))+        }+        return (try await backgroundColor(page)) == expected+    }++    private func backgroundColor(_ page: WebPage) async throws -> String {+        let result = try await page.callJavaScript(+            "return document.body ? getComputedStyle(document.body).backgroundColor : '';",+            contentWorld: .page+        )+        return (result as? String) ?? ""+    }+     private func bodyText(_ page: WebPage) async throws -> String {         let result = try await page.callJavaScript(             "return document.body ? document.body.innerText : '';",

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8b3f10d..45fa2fc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,7 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0  ### Fixed -- Footnote popovers now use the same text settings as the document (T-1978). A footnote's content ignored the **Body Font** you chose, the in-app **Text Size** slider, and the system text size (iOS Larger Text / macOS Text Size), always rendering in the system font at the default reading size — so footnote text could be noticeably smaller than the document it belongs to, and at accessibility text sizes it stayed small while everything around it grew. Footnote content now follows the same font, scale, and system text size as document text. A font that is no longer installed still falls back to the system font, and a font name is applied as text only, so it cannot alter the popover's styling. The system **Increase Contrast** setting had been missed in the same way and now reaches popovers too, though the only footnote content that looks different for it today is an HTML comment shown inline, which kept the standard low-contrast grey. A popover already open when you change these settings still shows the previous values until it is reopened; that is tracked separately (T-1979).+- Footnote popovers now use the same text settings as the document (T-1978). A footnote's content ignored the **Body Font** you chose, the in-app **Text Size** slider, and the system text size (iOS Larger Text / macOS Text Size), always rendering in the system font at the default reading size — so footnote text could be noticeably smaller than the document it belongs to, and at accessibility text sizes it stayed small while everything around it grew. Footnote content now follows the same font, scale, and system text size as document text. A font that is no longer installed still falls back to the system font, and a font name is applied as text only, so it cannot alter the popover's styling. The system **Increase Contrast** setting had been missed in the same way and now reaches popovers too, though the only footnote content that looks different for it today is an HTML comment shown inline, which kept the standard low-contrast grey. A popover already open when you change these settings updates in place, as of the fix below (T-1979).+- An open footnote popover now keeps up with the document instead of freezing at the moment it opened (T-1979). Switching to dark mode, turning **Increase Contrast** on, changing the **Body Font**, moving the **Text Size** slider, changing the system text size, or toggling **Show HTML comments** all left a popover that was already on screen showing the settings it opened with — and if the file changed on disk (or a URL document was refreshed) while the popover was open, the "Footnote N" heading could update to the new document while the footnote text below it still showed the old definition. The popover now re-renders whenever anything it displays changes, including replaced footnote content under the same reference, and leaves itself alone when nothing did, so reading is not interrupted by needless redraws. Changes arriving in quick succession settle on the newest one rather than whichever finished last. - Search and reading-position restore no longer lose their place to content the document hides (T-1944). Three faults shared one cause: hidden content — the body of a collapsed section, or the carrier holding a document's YAML frontmatter — measures as a zero-size box sitting exactly at the top of the window, and several parts of the app read that as "visible". Stepping to a search match inside a collapsed section silently did nothing: the section expanded, but the app had already treated the invisible match as on screen and skipped the scroll; the match is now brought to its usual resting place a third of the way down the window as soon as the section opens. Reopening a document after collapsing the section you were reading left the page at the top instead of anywhere near your place; the restore now lands on the collapsed heading that hides the saved block — and a stale saved position pointing at the hidden frontmatter carrier now falls back to the top of the document instead of doing nothing. Hidden matches also no longer count as on-screen when deciding which highlights to draw, and expanding a section lights its highlights up immediately instead of waiting for the next scroll. The zero-size test now lives in one shared check used by every reader of section layout, so a future feature cannot quietly reintroduce the assumption. Matches inside nested collapsed disclosure blocks (`<details>`) are tracked separately (T-1930). - Stepping to a search match now scrolls there in one motion and leaves the match itself in view (T-1918). Two parts of the app both moved the page on the same step — one lining the top of the match's block up with the top of the window, the other placing the match about a third of the way down — so the page could visibly jump twice, and which position stuck depended on timing. When the block was taller than the window, the block-top alignment could even settle with the match below the fold. One owner scrolls now, resting the match about a third of the way down the window every time. Two more gaps closed with it: stepping to a match far outside the part of the document being highlighted found no highlight to scroll to and relied on the other, block-based jump to get anywhere near it; and with a single match found, pressing next or previous after scrolling away to read something else did nothing — it now brings the match back into view. A match inside a collapsed section initially still did not scroll; the hidden-content fix above (T-1944) closed that gap. - Searching for text that lives in a footnote's definition now highlights and scrolls to the right reference badge when the same footnote is referenced more than once (T-1853). Badges were looked up document-wide by footnote number, so stepping to the match belonging to a later reference always marked and scrolled to the document's first badge — the one actually selected never even showed as matched. Each reference's badge is now resolved within its own block, and repeated references inside a single block are told apart by position, so stepping through matches visits each badge in turn. Text that merely looks like a reference — `` `[^1]` `` written in inline code — still occupies its place in the match order but renders no badge, so stepping onto it marks the nearest following badge in the block, or the last one when none follows.

diff --git a/CLAUDE.md b/CLAUDE.mdindex d41122d..a054e97 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -65,7 +65,7 @@ Implementation history and gotchas (the `<script>` data-island CSP trap, the nat 4. Badge substitution happens inside `InlineHTMLRenderer.render`, NOT by splitting the source in the emitter (T-1716/T-1945). `FootnoteReferenceScanner.scan` walks the block's inline SOURCE once and marks every occurrence that is spelled verbatim (no backslash escape anywhere in the token) and resolvable, rewriting only its identifier characters into a reserved Private Use Area window. The marker is length-preserving (runs come out in block coordinates — no rebasing, `rebased` is gone) and parse-shape-preserving (`[`, `^`, `]` untouched, so cmark builds the same tree). The whole marked source is then parsed ONCE 5. `InlineHTMLRenderer.Walker` turns a marker into a badge only where a badge is legal: TEXT position **and** not nested inside an element that cannot contain an anchor. Text position alone is not sufficient — the badge is itself an `<a>`, so a `Link` ancestor disqualifies it (`<a>` inside `<a>` is invalid HTML), tracked by the walker's `linkDepth` counter. Every other landing place — a code span, a link destination, an image `src`/`alt`, raw inline HTML, or text inside a link — is restored to the literal `[^id]` the author wrote. Classification is never inferred from parsed text, which is the failure class the redesign removes. `BlockHTMLEmitter.footnoteBadge` builds the styled pill-badge anchor (`prism://footnote/{id}`, display number from `FootnoteData`) carrying `data-prism-chrome`: inert, unselectable, covered by no source-map run 6. Badge taps produce `prism://footnote/{id}` links → `linkActivated` over the bridge → `WebDocumentMessageRouter` → `DocumentLayoutCoordinator` popover state (`PrismLinkRoute.footnotePrefix`)-7. `FootnotePopoverView` displays rendered footnote content (paragraphs, lists, blockquotes only) over a shared, non-persistent `FootnotePopoverWebPage` (emitter-rendered fragment). Since the WebKit cutover it is presented as a sheet on every platform via the shared `FootnotePresenter` modifier (`View.footnotePresentation(coordinator:session:)`), which **both** `CompactDocumentLayout` and `RegularDocumentLayout` must apply — the regular layout lacking it is T-1893. The web-rendered badge has no SwiftUI anchor view, so the anchored popover the original footnotes spec called for (Req 3.1/3.6/3.7) no longer applies; `FootnotePopoverView` self-sizes per platform. The popover page is bridge-less, so everything the document surface receives over the bridge must instead be BAKED into the emitted HTML via `RenderSettings`. Baked today: the palette — theme key **and** Increase Contrast state, carried as one `WebPaletteFeed` so they can never be applied out of step (T-1542/T-1829), emitted as `data-prism-theme`/`data-prism-contrast` by `BlockHTMLEmitter.paletteAttributes`; and the typography custom properties (T-1978, emitted as a validated `<html style>` by `BlockHTMLEmitter.rootStyleAttribute`). Not baked: the mermaid theme config and the note/search/section state, none of which a footnote fragment can contain. `FootnotePopoverView.renderSettings(settings:colorScheme:contrast:dynamicTypeSize:)` is the single pure builder of that render input — it reuses `WebDocumentControllerFactory.typographyVariables` rather than resolving fonts again (font-settings Decision 18), and its equatable result is what a future re-present key (T-1979) observes+7. `FootnotePopoverView` displays rendered footnote content (paragraphs, lists, blockquotes only) over a shared, non-persistent `FootnotePopoverWebPage` (emitter-rendered fragment). Since the WebKit cutover it is presented as a sheet on every platform via the shared `FootnotePresenter` modifier (`View.footnotePresentation(coordinator:session:)`), which **both** `CompactDocumentLayout` and `RegularDocumentLayout` must apply — the regular layout lacking it is T-1893. The web-rendered badge has no SwiftUI anchor view, so the anchored popover the original footnotes spec called for (Req 3.1/3.6/3.7) no longer applies; `FootnotePopoverView` self-sizes per platform. The popover page is bridge-less, so everything the document surface receives over the bridge must instead be BAKED into the emitted HTML via `RenderSettings`. Baked today: the palette — theme key **and** Increase Contrast state, carried as one `WebPaletteFeed` so they can never be applied out of step (T-1542/T-1829), emitted as `data-prism-theme`/`data-prism-contrast` by `BlockHTMLEmitter.paletteAttributes`; and the typography custom properties (T-1978, emitted as a validated `<html style>` by `BlockHTMLEmitter.rootStyleAttribute`). Not baked: the mermaid theme config and the note/search/section state, none of which a footnote fragment can contain. `FootnotePopoverView.renderSettings(settings:colorScheme:contrast:dynamicTypeSize:)` is the single pure builder of that render input — it reuses `WebDocumentControllerFactory.typographyVariables` rather than resolving fonts again (font-settings Decision 18), and its equatable result is one half of the re-present key. Because a bake can only be applied by re-emitting, an OPEN popover stays current only by re-presenting: `FootnotePopoverWebPage.RenderKey` (footnote id + the resolved `FootnoteDefinition` + that `RenderSettings`) is the equatable trigger, and `FootnotePopoverView` drives it with one `.onChange(of: renderKey, initial: true)` — evaluated in `body`, which is what registers the `AppSettings` reads with Observation (reading them only inside `onAppear` registered nothing). `present` no-ops on an unchanged key (an identical re-emit would blank the live page mid-read) and `renderGeneration` guards overlapping loads so a superseded one cannot win; it also varies the document URL's `rev`. Keying on `footnoteId` alone was T-1979: the identifier is the one input that does not move when the theme, contrast, typography, comment visibility, or a same-id definition does 8. `FootnoteStripping` removes `[^id]` references from heading text used in ToC entries, anchor IDs, and window titles 9. Search integration: `searchableText(with:)` appends footnote content to host blocks; badge highlighting indicates matches 

diff --git a/specs/a11y-increase-contrast/decision_log.md b/specs/a11y-increase-contrast/decision_log.mdindex 6e27ceb..69d04e9 100644--- a/specs/a11y-increase-contrast/decision_log.md+++ b/specs/a11y-increase-contrast/decision_log.md@@ -193,7 +193,7 @@ The footnote popover bakes the contrast state alongside the theme key. `RenderSe - Q4's "revisit if the popover ever renders badges, comments or search highlights" is answered ahead of the trigger.  **Negative:**-- The popover still does not update live: a sheet already open when contrast (or typography) changes keeps its baked values until reopened. Tracked as T-1979.+- ~~The popover still does not update live: a sheet already open when contrast (or typography) changes keeps its baked values until reopened. Tracked as T-1979.~~ **Closed by T-1979.** An open popover now re-presents whenever its render key moves — footnote id + resolved `FootnoteDefinition` + this `RenderSettings` value — so palette, contrast, typography, and comment visibility all reach a sheet that is already on screen. Baking is still the only delivery mechanism; what changed is that it is re-applied on change instead of only on first present. - `RenderSettings.theme` was renamed, so spec text and agent notes referring to it needed a sweep.  ---