From 87033d19ab8d17fec21ece7e7580bbc7bd39ce7e Mon Sep 17 00:00:00 2001
From: David Grochowski <dgrochowski@squareup.com>
Date: Fri, 6 Nov 2026 16:41:21 -0500
Subject: [PATCH 1/4] Reach discussions inside collapsed details sections

A closed <details> in a plan hid the discussions anchored inside it:
the highlight existed, so the thread was left out of the Comments list,
but the reader could not see it, ?thread= links and j/k scrolled to an
invisible mark, and Chrome still reported rects, so the margin marker
sat beside the wrong text.

- Every jump to a thread (?thread=, j/k, the review tray, anchor quotes,
  any popover open) opens the enclosing sections first.
- Closed sections show a compact blue count badge on their summary
  instead of margin markers; it opens the section at the first
  discussion. Resolved threads count only while they are shown.
- Opening or closing a section refreshes the margin markers.
- Demo library: collapsed-discussions, with a nested section.
---
 AGENTS.md                                     |   1 +
 docs/DEMO_LIBRARY.md                          |   1 +
 .../assets/stylesheets/coplan/comments.css    |  32 +++++
 .../coplan/comment_margin_controller.js       |  64 +++++++--
 .../coplan/comment_nav_controller.js          |   2 +
 .../coplan/text_selection_controller.js       |  25 +++-
 .../javascript/coplan/collapsed_sections.js   |  33 +++++
 .../guides/markdown.text.erb                  |   1 +
 engine/app/views/coplan/plans/show.html.erb   |   2 +-
 engine/config/importmap.rb                    |   1 +
 .../db/demo/content/collapsed-discussions.md  |  48 +++++++
 engine/lib/coplan/development_seed.rb         |  21 +++
 spec/lib/development_seed_spec.rb             |  29 ++++
 .../system/collapsed_section_comments_spec.rb | 126 ++++++++++++++++++
 14 files changed, 374 insertions(+), 12 deletions(-)
 create mode 100644 engine/app/javascript/coplan/collapsed_sections.js
 create mode 100644 engine/db/demo/content/collapsed-discussions.md
 create mode 100644 spec/system/collapsed_section_comments_spec.rb

diff --git a/AGENTS.md b/AGENTS.md
index 51a8aadc..e887ebfb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -231,6 +231,7 @@ reader to an apparently empty page.
 ### Inline review UI
 - **Highlights**: anchored text is wrapped in `<mark>` elements — subtle blue for `open`, unstyled for `resolved`; orange is reserved for viewer-specific attention, never thread status
 - **Margin dots**: colored indicators in the left margin aligned to each highlight's vertical position
+- **Collapsed sections**: a closed `<details>` hides its highlights, so it shows a compact blue count badge on its summary instead of margin dots (open threads only, unless resolved threads are shown). Every jump to a thread — `?thread=`, j/k, a badge — opens the enclosing sections first (`coplan/collapsed_sections.js`)
 - **Thread popovers**: native HTML Popover API (`popover="auto"`) showing the comment thread, reply form, and action buttons; positioned relative to the anchor and tracked on scroll
 - **Comment toolbar**: fixed bottom bar showing open thread count, j/k navigation, and a "Show resolved" toggle
 
diff --git a/docs/DEMO_LIBRARY.md b/docs/DEMO_LIBRARY.md
index 4b0a7c82..e2be11d2 100644
--- a/docs/DEMO_LIBRARY.md
+++ b/docs/DEMO_LIBRARY.md
@@ -59,6 +59,7 @@ shipped types, including Scratchpad, PRD, Test Plan, and Handoff.
 | api-comment-anchors | Markdown text and table-row highlights; source-only discussion in Comments |
 | table-gallery | Precise cell discussion, repeated labels, empty values, links, wide expandable data |
 | comment-reactions | Discussions with emoji reactions; your own are pressed in blue, hover a chip for who reacted, add or remove one in place. Re-seeding keeps reactions you removed removed |
+| collapsed-discussions | Discussions inside closed `<details>`, one nested; each summary counts the open discussions it hides. Select a count, press j, follow a `?thread=` link, or open a section to reach them |
 | formatting-gallery | Headings, editable template notes hidden while reading, emphasis, quotes, nested lists, tasks, two code languages, image, mention, footnote |
 | discussion-margins | Crowded prose discussions, multiple participants, resolved visibility, and slide navigation/scrolling; avatars identify starters, not unread activity |
 | reading-specimen | A realistic design doc for judging reading in both modes: prose, headings, lists, tasks, quote, table, footnote, image, SQL/Ruby/diff/YAML code, a long scrolling line, flowchart and sequence diagrams, plus open, agent-answered, resolved, diagram-node, table-cell, and general discussions |
diff --git a/engine/app/assets/stylesheets/coplan/comments.css b/engine/app/assets/stylesheets/coplan/comments.css
index 766233a8..54ebd1a5 100644
--- a/engine/app/assets/stylesheets/coplan/comments.css
+++ b/engine/app/assets/stylesheets/coplan/comments.css
@@ -207,6 +207,38 @@
   background: var(--color-highlight-open-hover-bg);
 }
 
+/* Discussions hidden in a closed <details>: a compact blue count on its
+   summary. The count is generated here so the summary's text, which
+   comment anchors match against, stays the author's. */
+.details-comment-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  margin-left: var(--space-sm);
+  padding: 1px 7px;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: var(--color-primary-light);
+  color: var(--color-primary);
+  font: 700 0.7rem/1.4 var(--font-sans);
+  vertical-align: middle;
+  cursor: pointer;
+}
+
+.details-comment-badge::after { content: attr(data-count); }
+
+.details-comment-badge svg {
+  width: 12px;
+  height: 12px;
+}
+
+.details-comment-badge:hover { border-color: var(--color-highlight-open-border); }
+
+.details-comment-badge:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+
 #plan-threads {
   position: absolute;
   width: 0;
diff --git a/engine/app/javascript/controllers/coplan/comment_margin_controller.js b/engine/app/javascript/controllers/coplan/comment_margin_controller.js
index 49eb73c5..432ed1eb 100644
--- a/engine/app/javascript/controllers/coplan/comment_margin_controller.js
+++ b/engine/app/javascript/controllers/coplan/comment_margin_controller.js
@@ -1,4 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
+import { hidingSection } from "coplan/collapsed_sections"
 
 // Collapsed discussion markers in the page margin, one per highlighted
 // thread, aligned with the text they discuss. A marker shows the first
@@ -7,7 +8,8 @@ import { Controller } from "@hotwired/stimulus"
 //
 // Cards are derived from the highlights coplan--text-selection builds and
 // from the thread popovers in #plan-threads, so broadcasts that add
-// threads or comments update them without a server round-trip.
+// threads or comments update them without a server round-trip. A closed
+// <details> shows a count badge on its summary instead of markers.
 const STACK_GAP = 4
 // Room beside the document card: gap from the card, gap from the window
 // edge, and the marker width.
@@ -50,12 +52,25 @@ export default class extends Controller {
   refresh() {
     const showResolved = !this.layout.classList.contains("plan-layout--hide-resolved")
     const marks = new Map()
-    for (const mark of this.content.querySelectorAll("mark.anchor-highlight[data-thread-id]")) {
+    const hidden = new Map()
+    const seen = new Set()
+    // Table-cell and diagram discussions have their own badges, so they
+    // only count toward a closed section.
+    for (const mark of this.content.querySelectorAll("mark.anchor-highlight[data-thread-id], [data-source-badge][data-thread-id]")) {
       const id = mark.dataset.threadId
-      if (marks.has(id) || !mark.getClientRects().length) continue
+      if (seen.has(id)) continue
       if (!showResolved && !mark.classList.contains("anchor-highlight--open")) continue
-      marks.set(id, mark)
+      const section = hidingSection(mark)
+      if (!section && (mark.hasAttribute("data-source-badge") || !mark.getClientRects().length)) continue
+      seen.add(id)
+      if (section) {
+        if (!hidden.has(section)) hidden.set(section, [])
+        hidden.get(section).push(id)
+      } else {
+        marks.set(id, mark)
+      }
     }
+    this.renderSectionBadges(hidden)
 
     for (const [id, card] of this.cards) {
       if (marks.has(id)) continue
@@ -74,6 +89,32 @@ export default class extends Controller {
     this.position()
   }
 
+  // Each closed section counts the discussions it hides, in document order;
+  // its badge opens the section at the first one.
+  renderSectionBadges(sections) {
+    for (const badge of this.content.querySelectorAll(".details-comment-badge")) {
+      if (!sections.has(badge.closest("details"))) badge.remove()
+    }
+    for (const [details, ids] of sections) {
+      const summary = details.querySelector(":scope > summary")
+      if (!summary) continue
+      let badge = summary.querySelector(":scope > .details-comment-badge")
+      if (!badge) {
+        badge = document.createElement("button")
+        badge.type = "button"
+        badge.className = "details-comment-badge"
+        badge.dataset.action = "click->coplan--text-selection#openSectionThread"
+        // The count is CSS-generated: a text node here would enter the
+        // document text that comment anchors are matched against.
+        badge.innerHTML = COMMENT_ICON
+        summary.append(badge)
+      }
+      badge.dataset.threadId = ids[0]
+      badge.dataset.count = ids.length
+      badge.setAttribute("aria-label", `${ids.length} ${ids.length === 1 ? "discussion" : "discussions"} in this section`)
+    }
+  }
+
   // Reuse card elements: an open discussion window tracks its trigger
   // element while the page scrolls.
   buildCard(id) {
@@ -169,11 +210,16 @@ export default class extends Controller {
   }
 
   // Keep the card for the open discussion visibly selected, however it was
-  // opened (card, highlight, j/k, or a deep link).
-  popoverToggled(event) {
-    const popover = event.target
-    if (!popover.classList?.contains("thread-popover")) return
-    const card = this.cards.get(popover.id.replace(/_popover$/, ""))
+  // opened (card, highlight, j/k, or a deep link). Opening or closing a
+  // section in the document shows or hides the markers inside it.
+  toggled(event) {
+    const target = event.target
+    if (target.tagName === "DETAILS" && this.content.contains(target)) {
+      this.scheduleRefresh()
+      return
+    }
+    if (!target.classList?.contains("thread-popover")) return
+    const card = this.cards.get(target.id.replace(/_popover$/, ""))
     card?.classList.toggle("is-active", event.newState === "open")
   }
 }
diff --git a/engine/app/javascript/controllers/coplan/comment_nav_controller.js b/engine/app/javascript/controllers/coplan/comment_nav_controller.js
index 1760240c..5227bae7 100644
--- a/engine/app/javascript/controllers/coplan/comment_nav_controller.js
+++ b/engine/app/javascript/controllers/coplan/comment_nav_controller.js
@@ -1,6 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
 import { registerShortcuts, commandFor } from "coplan/shortcuts"
 import { commentWindowTop } from "coplan/comment_window"
+import { revealSections } from "coplan/collapsed_sections"
 
 export default class extends Controller {
 
@@ -125,6 +126,7 @@ export default class extends Controller {
     if (slide) slide.dispatchEvent(new CustomEvent("coplan:deck-reveal", {
       bubbles: true, detail: { slide: slide.dataset.slide }
     }))
+    revealSections(mark)
     if (mark.hasAttribute("data-source-badge")) {
       const thread = document.getElementById(mark.dataset.threadId)
       if (thread) mark.dispatchEvent(new CustomEvent("coplan:source-thread", {
diff --git a/engine/app/javascript/controllers/coplan/text_selection_controller.js b/engine/app/javascript/controllers/coplan/text_selection_controller.js
index 1d866cbf..e893de26 100644
--- a/engine/app/javascript/controllers/coplan/text_selection_controller.js
+++ b/engine/app/javascript/controllers/coplan/text_selection_controller.js
@@ -1,5 +1,6 @@
 import { Controller } from "@hotwired/stimulus"
 import { commentWindowTop } from "coplan/comment_window"
+import { revealSections } from "coplan/collapsed_sections"
 
 // Elements whose text is never rendered but still appears in textContent —
 // e.g. the <style> sheet Mermaid embeds inside its SVG. Their text must stay
@@ -354,6 +355,7 @@ export default class extends Controller {
     const highlighted = this.findAndHighlight(anchor, occurrence, "anchor-highlight--active")
     if (highlighted) {
       this._revealDeckSlide(highlighted)
+      revealSections(highlighted)
       highlighted.scrollIntoView({ behavior: "smooth", block: "center" })
     }
   }
@@ -363,6 +365,25 @@ export default class extends Controller {
     this._showThreadPopoverFor(event.currentTarget)
   }
 
+  // A collapsed section's discussion badge opens the section at its first
+  // discussion.
+  openSectionThread(event) {
+    event.preventDefault()
+    event.stopPropagation()
+    const id = event.currentTarget.dataset.threadId
+    const mark = this.contentTarget.querySelector(`mark.anchor-highlight[data-thread-id="${id}"], [data-source-badge][data-thread-id="${id}"]`)
+    if (!mark) return
+    revealSections(mark)
+    mark.scrollIntoView({ behavior: "instant", block: "center" })
+    if (mark.hasAttribute("data-source-badge")) {
+      mark.dispatchEvent(new CustomEvent("coplan:source-thread", {
+        bubbles: true, cancelable: true, detail: { threadId: document.getElementById(id)?.dataset.threadId, focusReply: false }
+      }))
+    } else {
+      this._showThreadPopoverFor(mark)
+    }
+  }
+
   openEditorThread(event) {
     event.preventDefault()
     event.stopPropagation()
@@ -478,6 +499,7 @@ export default class extends Controller {
   _showThreadPopoverFor(trigger) {
     if (!trigger) return false
     this._revealDeckSlide(trigger)
+    revealSections(trigger)
     const threadId = trigger.dataset.threadId
     if (!threadId) return false
 
@@ -888,8 +910,7 @@ export default class extends Controller {
           const trigger = generalVoiceComment ? document.querySelector(".voice-btn") || currentMark : currentMark
           if (generalVoiceComment) trigger.dataset.threadId = domId
           else {
-            const disclosure = currentMark.closest("details.document-support__disclosure")
-            if (disclosure) disclosure.open = true
+            revealSections(currentMark)
             this._revealDeckSlide(currentMark)
             currentMark.scrollIntoView({ behavior: "instant", block: "center" })
           }
diff --git a/engine/app/javascript/coplan/collapsed_sections.js b/engine/app/javascript/coplan/collapsed_sections.js
new file mode 100644
index 00000000..98c1d31a
--- /dev/null
+++ b/engine/app/javascript/coplan/collapsed_sections.js
@@ -0,0 +1,33 @@
+// A closed <details> keeps its content in the DOM. Highlights inside it
+// exist, and Chrome even reports client rects for them, but the reader
+// cannot see them. Its <summary> stays visible, so content there is not
+// hidden by its own section.
+
+function hiddenBy(details, element) {
+  return !details.open && !details.querySelector(":scope > summary")?.contains(element)
+}
+
+function* sections(element) {
+  for (let details = element.closest("details"); details; details = details.parentElement?.closest("details")) {
+    yield details
+  }
+}
+
+// The outermost closed section hiding the element: the one whose summary
+// the reader can currently see.
+export function hidingSection(element) {
+  let hiding = null
+  for (const details of sections(element)) if (hiddenBy(details, element)) hiding = details
+  return hiding
+}
+
+// Open every section that hides the element. Returns whether any opened.
+export function revealSections(element) {
+  let revealed = false
+  for (const details of sections(element)) {
+    if (!hiddenBy(details, element)) continue
+    details.open = true
+    revealed = true
+  }
+  return revealed
+}
diff --git a/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb b/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
index d15930bb..5827eafb 100644
--- a/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
+++ b/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
@@ -113,6 +113,7 @@ Markdown here still renders. Keep the blank line after the summary.
 ```
 
 Add `open` to the `<details>` tag to show the section expanded by default.
+Comments on text inside a collapsed section stay reachable: its summary shows how many open discussions it hides.
 
 ## Hover definitions
 
diff --git a/engine/app/views/coplan/plans/show.html.erb b/engine/app/views/coplan/plans/show.html.erb
index 9daf4ec3..002b52f1 100644
--- a/engine/app/views/coplan/plans/show.html.erb
+++ b/engine/app/views/coplan/plans/show.html.erb
@@ -158,7 +158,7 @@
           about. Positioned outside the card, so the text keeps its width. %>
       <aside class="comment-margin" aria-label="Discussions" hidden
              data-controller="coplan--comment-margin"
-             data-action="coplan:deck-slide-changed@document->coplan--comment-margin#refresh scroll@document->coplan--comment-margin#position:capture coplan:anchors-updated@document->coplan--comment-margin#refresh coplan:resolved-visibility@document->coplan--comment-margin#refresh resize@window->coplan--comment-margin#position toggle@document->coplan--comment-margin#popoverToggled:capture mouseover@document->coplan--comment-margin#hoverChanged"></aside>
+             data-action="coplan:deck-slide-changed@document->coplan--comment-margin#refresh scroll@document->coplan--comment-margin#position:capture coplan:anchors-updated@document->coplan--comment-margin#refresh coplan:resolved-visibility@document->coplan--comment-margin#refresh resize@window->coplan--comment-margin#position toggle@document->coplan--comment-margin#toggled:capture mouseover@document->coplan--comment-margin#hoverChanged"></aside>
     </div>
 </div>
 
diff --git a/engine/config/importmap.rb b/engine/config/importmap.rb
index 29db9553..fe73189c 100644
--- a/engine/config/importmap.rb
+++ b/engine/config/importmap.rb
@@ -4,6 +4,7 @@
 pin "coplan/shortcuts", to: "coplan/shortcuts.js", preload: true
 pin "coplan/reaction_focus", to: "coplan/reaction_focus.js", preload: true
 pin "coplan/comment_window", to: "coplan/comment_window.js", preload: true
+pin "coplan/collapsed_sections", to: "coplan/collapsed_sections.js", preload: true
 # Statically imported by the mermaid and data-grid controllers, which are
 # themselves preloaded — preload these too or every page pays a round trip
 # to discover them.
diff --git a/engine/db/demo/content/collapsed-discussions.md b/engine/db/demo/content/collapsed-discussions.md
new file mode 100644
index 00000000..eb8e36d4
--- /dev/null
+++ b/engine/db/demo/content/collapsed-discussions.md
@@ -0,0 +1,48 @@
+Checkout got slower after the March pricing release. The p95 for `POST /checkout` went from 420 ms to 610 ms. Almost all of the extra time is spent loading discount rules for each line item. Caching the rules per cart brings the p95 back to 430 ms in staging. We plan to ship the cache behind a flag next week.
+
+The evidence and the options we rejected are in the collapsed sections below. Each closed section shows how many open discussions it hides. Select the count to open the section at its first discussion, or press j to step through every discussion, hidden or not.
+
+## Findings
+
+Slow carts are large carts. Carts with more than 20 line items account for most of the regression, and small carts are unchanged.
+
+<details>
+<summary>Raw measurements</summary>
+
+We sampled 50,000 checkout requests from the week before and the week after the release.
+
+| Cart size | p95 before | p95 after |
+| --- | --- | --- |
+| 1–5 items | 380 ms | 390 ms |
+| 6–20 items | 450 ms | 520 ms |
+| 21+ items | 690 ms | 1,240 ms |
+
+Each line item runs one discount rule query, so a 40-item cart makes 40 round trips to the pricing database.
+
+<details>
+<summary>Query plan</summary>
+
+The rule lookup uses the merchant index but filters item categories in memory, so every query reads all of a merchant's active rules.
+
+</details>
+
+Weekend traffic was excluded because a marketing campaign doubled cart sizes on those days.
+
+</details>
+
+## Options
+
+We compared three ways to remove the repeated lookups.
+
+<details>
+<summary>Alternatives considered</summary>
+
+Batching the queries into one request per cart halves the time but still grows with merchant rule count.
+
+Precomputing prices nightly removes the lookups, but price changes would take up to a day to appear.
+
+</details>
+
+## Plan
+
+Cache each merchant's active rules for the life of one cart request. Invalidate the cache when a merchant edits a rule. Roll out to 10% of merchants first and compare p95 by cart size.
diff --git a/engine/lib/coplan/development_seed.rb b/engine/lib/coplan/development_seed.rb
index 364f25b8..c9bde4bf 100644
--- a/engine/lib/coplan/development_seed.rb
+++ b/engine/lib/coplan/development_seed.rb
@@ -89,6 +89,9 @@ module DevelopmentSeed
       { key: "comment-reactions", author: "hampton", type: "Design Doc", title: "Discussions: react to comments",
         tags: %w[demo comments], visibility: "published", folder: "Demo content/Discussions", group: "Discussions",
         showcase: "Threads with reactions; yours are pressed in blue, hover a chip to see who reacted, add one with the smiley button" },
+      { key: "collapsed-discussions", author: "hampton", type: "Research Note", title: "Collapsed sections: discussions in the appendix",
+        tags: %w[demo comments], visibility: "published", folder: "Demo content/Discussions", group: "Discussions",
+        showcase: "Collapsed sections count the open discussions they hide, one of them nested; select a count, press j, follow a link, or open a section to reach them" },
       { key: "single-slide", author: "hampton", type: "Presentation", title: "One slide: the workspace launch decision",
         tags: %w[demo slides], visibility: "published", folder: "Demo content/Presentations", group: "Presentations",
         showcase: "One-slide presentation with speaker notes" },
@@ -321,6 +324,7 @@ def call(base_url: ENV.fetch("COPLAN_DEMO_BASE_URL", "http://localhost:3000"))
         seed_content_discussions(users, plans)
         seed_discussion_margins(users, plans)
         seed_reading_specimen(users, plans)
+        seed_collapsed_discussions(users, plans)
         seed_comment_reactions(users, plans)
         seed_reference_gallery(plans, base_url: base_url)
         catalog = seed_catalog(users, plans, plan_types, base_url: base_url)
@@ -1025,6 +1029,23 @@ def seed_reading_specimen(users, plans)
       )
     end
 
+    # Most discussions sit inside closed <details>, one of them nested, so
+    # the summary badges, j/k, and deep links all have to open a section.
+    def seed_collapsed_discussions(users, plans)
+      plan = plans.fetch("collapsed-discussions")
+      [
+        [ "alex", "Caching the rules per cart", "Is the cache shared across checkout workers, or one per process?" ],
+        [ "sam", "one discount rule query", "Can we confirm this with a trace from a 40-item cart?" ],
+        [ "aiko", "filters item categories in memory", "Would an index on merchant and category make the cache unnecessary?" ],
+        [ "noura", "Weekend traffic was excluded", "Were weekday campaign days excluded too?" ],
+        [ "mateo", "Precomputing prices nightly", "Could we precompute only for merchants whose rules rarely change?" ]
+      ].each do |user, anchor, body|
+        seed_thread(plan: plan, user: users.fetch(user), anchor: anchor, body: body)
+      end
+      seed_thread(plan: plan, user: users.fetch("alex"), anchor: "halves the time",
+        body: "What does batching do to the p99?", resolved_by: users.fetch("hampton"))
+    end
+
     # Replies and reactions are added only when a thread is first created,
     # so re-seeding never restores a reaction someone removed.
     REACTION_DISCUSSIONS = [
diff --git a/spec/lib/development_seed_spec.rb b/spec/lib/development_seed_spec.rb
index 814df826..5fb547cb 100644
--- a/spec/lib/development_seed_spec.rb
+++ b/spec/lib/development_seed_spec.rb
@@ -503,6 +503,35 @@ def seeded_plan(key)
       expect(plan.reload.current_revision).to eq(1)
     end
 
+    it "seeds discussions hidden in collapsed sections, including a nested one" do
+      described_class.call
+      plan = seeded_plan("collapsed-discussions")
+      content = plan.current_content
+      expect(content.scan("<details>").size).to eq(3)
+      expect(content).not_to include("<details open")
+      expect(seeded_plan("demo-library").current_content).to include("## Discussions", "(/#{plan.url_path})", "`collapsed-discussions`")
+
+      threads = plan.comment_threads
+      expect(threads.pluck(:status).tally).to eq("open" => 5, "resolved" => 1)
+      anchors = threads.pluck(:anchor_text)
+      anchors.each { |anchor| expect(content).to include(anchor) }
+      measurements = content[%r{<summary>Raw measurements</summary>(.*?)\n## Options}m, 1]
+      query_plan = content[%r{<summary>Query plan</summary>(.*?)</details>}m, 1]
+      alternatives = content[%r{<summary>Alternatives considered</summary>(.*?)</details>}m, 1]
+      expect(anchors.count { |anchor| measurements.include?(anchor) }).to eq(3)
+      expect(query_plan).to include("filters item categories in memory")
+      expect(anchors.count { |anchor| alternatives.include?(anchor) }).to eq(2)
+
+      count = CoPlan::CommentThread.count
+      thread = threads.find_by!(anchor_text: "one discount rule query")
+      thread.comments.first.update!(body_markdown: "My revised question")
+      thread.resolve!(plan.created_by_user)
+      described_class.call
+      expect(CoPlan::CommentThread.count).to eq(count)
+      expect(thread.reload.status).to eq("resolved")
+      expect(plan.reload.current_revision).to eq(1)
+    end
+
     it "preserves edited and resolved seeded discussions on re-seeding" do
       described_class.call
       %w[collab-showcase diagram-comments table-gallery reading-specimen].each do |key|
diff --git a/spec/system/collapsed_section_comments_spec.rb b/spec/system/collapsed_section_comments_spec.rb
new file mode 100644
index 00000000..80c0c46c
--- /dev/null
+++ b/spec/system/collapsed_section_comments_spec.rb
@@ -0,0 +1,126 @@
+require "rails_helper"
+
+RSpec.describe "Discussions inside collapsed sections", type: :system do
+  let(:author) { create(:coplan_user, email: "author@example.com") }
+  let(:reviewer) { create(:coplan_user, email: "reviewer@example.com") }
+
+  let(:plan) do
+    plan = CoPlan::Plan.create!(title: "Queue incident review", created_by_user: author)
+    version = CoPlan::PlanVersion.create!(plan: plan, revision: 1, actor_type: "human", actor_id: author.id,
+      content_markdown: <<~MARKDOWN)
+        Summary: the retry budget ran out during the deploy.
+
+        <details>
+        <summary>Raw timeline</summary>
+
+        The queue backed up right after the rollout started.
+
+        Workers recovered once the cache warmed.
+
+        A manual drain was considered and rejected.
+
+        </details>
+
+        ## Follow-ups
+
+        Alert on queue age before the next rollout.
+      MARKDOWN
+    plan.update!(current_plan_version: version, current_revision: 1)
+    plan
+  end
+
+  let!(:outside) { discuss("retry budget", "Is the budget per partner?") }
+  let!(:backlog) { discuss("queue backed up", "How deep did the queue get?") }
+  let!(:recovery) { discuss("cache warmed", "Can we warm the cache before rollout?") }
+  let!(:drain) { discuss("manual drain", "Why was the drain rejected?").tap { |thread| thread.resolve!(author) } }
+
+  def discuss(anchor, body)
+    thread = plan.comment_threads.create!(plan_version: plan.current_plan_version, anchor_text: anchor,
+      anchor_occurrence: 1, created_by_user: reviewer, status: "open")
+    thread.comments.create!(author_type: "human", author_id: reviewer.id, body_markdown: body)
+    thread
+  end
+
+  def section = find("#plan-content-body details")
+  def badge = section.find("summary .details-comment-badge")
+  def collapsed = "#plan-content-body details:not([open])"
+  def expanded = "#plan-content-body details[open]"
+
+  before do
+    visit sign_in_path
+    fill_in "Email address", with: author.email
+    click_button "Sign In"
+    expect(page).to have_current_path(library_page_path(author))
+    page.current_window.resize_to(1600, 900)
+  end
+
+  after { page.current_window.resize_to(1400, 900) }
+
+  it "counts open discussions on the collapsed summary and opens the first one" do
+    visit plan_page_path(plan)
+    expect(page).to have_css(collapsed)
+    expect(badge["data-count"]).to eq("2")
+    expect(badge[:"aria-label"]).to eq("2 discussions in this section")
+
+    # Resolved discussions count only while they are shown.
+    find("body").send_keys("s")
+    expect(section).to have_css(".details-comment-badge[data-count='3']")
+    find("body").send_keys("s")
+    expect(section).to have_css(".details-comment-badge[data-count='2']")
+
+    badge.click
+    expect(page).to have_css(expanded)
+    expect(page).to have_css("#comment_thread_#{backlog.id}_popover:popover-open", text: "How deep did the queue get?")
+    expect(section).to have_no_css(".details-comment-badge", visible: :all)
+    mark = find("mark[data-thread-id='comment_thread_#{backlog.id}']")
+    expect(mark.evaluate_script("this.getClientRects().length")).to be > 0
+  end
+
+  it "opens the section for a linked discussion" do
+    visit plan_page_path(plan, thread: recovery.id)
+    expect(page).to have_css("#comment_thread_#{recovery.id}_popover:popover-open", text: "Can we warm the cache before rollout?")
+    expect(page).to have_css(expanded)
+    expect(find("mark[data-thread-id='comment_thread_#{recovery.id}']")).to be_visible
+  end
+
+  it "reaches discussions in a collapsed section with j and k" do
+    visit plan_page_path(plan)
+    expect(badge["data-count"]).to eq("2")
+
+    find("body").send_keys("j")
+    expect(page).to have_css("#comment_thread_#{outside.id}_popover:popover-open")
+    expect(page).to have_css(collapsed)
+
+    find("body").send_keys("j")
+    expect(page).to have_css("#comment_thread_#{backlog.id}_popover:popover-open", text: "How deep did the queue get?")
+    expect(page).to have_css(expanded)
+    expect(find("mark[data-thread-id='comment_thread_#{backlog.id}']")).to be_visible
+
+    # k from the first discussion wraps to the last one, inside the section.
+    section.find("summary", text: "Raw timeline").click
+    expect(page).to have_css(collapsed)
+    find("body").send_keys(:escape)
+    find("body").send_keys("k")
+    find("body").send_keys("k")
+    expect(page).to have_css("#comment_thread_#{recovery.id}_popover:popover-open")
+    expect(page).to have_css(expanded)
+  end
+
+  it "adds and removes margin markers as the section opens and closes" do
+    visit plan_page_path(plan)
+    expect(page).to have_css(".comment-margin__card[data-thread-id='comment_thread_#{outside.id}']")
+    expect(page).to have_no_css(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
+
+    section.find("summary", text: "Raw timeline").click
+    expect(page).to have_css(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
+    expect(page).to have_css(".comment-margin__card[data-thread-id='comment_thread_#{recovery.id}']")
+    card = find(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
+    middle = ->(element) { element.evaluate_script("(r => r.top + r.height / 2)(this.getClientRects()[0])") }
+    expect(middle.(card)).to be_within(4).of(middle.(find("mark[data-thread-id='comment_thread_#{backlog.id}']")))
+    expect(section).to have_no_css(".details-comment-badge", visible: :all)
+
+    section.find("summary", text: "Raw timeline").click
+    expect(page).to have_no_css(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
+    expect(section).to have_css(".details-comment-badge[data-count='2']")
+  end
+end

From de63df5b192c528c1df187b97de8900b99ffa484 Mon Sep 17 00:00:00 2001
From: David Grochowski <dgrochowski@squareup.com>
Date: Fri, 6 Nov 2026 22:49:00 -0500
Subject: [PATCH 2/4] Cover two discussions on the same line of a collapsed
 section

---
 .../system/collapsed_section_comments_spec.rb | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/spec/system/collapsed_section_comments_spec.rb b/spec/system/collapsed_section_comments_spec.rb
index 80c0c46c..d59b75fb 100644
--- a/spec/system/collapsed_section_comments_spec.rb
+++ b/spec/system/collapsed_section_comments_spec.rb
@@ -123,4 +123,24 @@ def expanded = "#plan-content-body details[open]"
     expect(page).to have_no_css(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
     expect(section).to have_css(".details-comment-badge[data-count='2']")
   end
+
+  it "counts and stacks two discussions on the same line of a collapsed section" do
+    same_line = discuss("rollout started", "Which rollout step was this?")
+    visit plan_page_path(plan)
+    expect(badge["data-count"]).to eq("3")
+
+    section.find("summary", text: "Raw timeline").click
+    first = find(".comment-margin__card[data-thread-id='comment_thread_#{backlog.id}']")
+    second = find(".comment-margin__card[data-thread-id='comment_thread_#{same_line.id}']")
+    rect = ->(element) { element.evaluate_script("(r => ({top: r.top, bottom: r.bottom}))(this.getBoundingClientRect())") }
+    upper, lower = [ rect.(first), rect.(second) ].sort_by { |r| r["top"] }
+    expect(lower["top"]).to be >= upper["bottom"]
+
+    find("body").send_keys(:escape)
+    find("body").send_keys("j")
+    find("body").send_keys("j")
+    expect(page).to have_css("#comment_thread_#{backlog.id}_popover:popover-open")
+    find("body").send_keys("j")
+    expect(page).to have_css("#comment_thread_#{same_line.id}_popover:popover-open")
+  end
 end

From b937899263b83e3caa46fffc38c15162816dcc66 Mon Sep 17 00:00:00 2001
From: Hampton Lintorn-Catlin <hampton@squareup.com>
Date: Fri, 6 Nov 2026 22:10:29 -0600
Subject: [PATCH 3/4] Reveal collapsed source discussion anchors

Signed-off-by: Hampton Lintorn-Catlin <hampton@squareup.com>
---
 .../coplan/source_comments_controller.js      |  2 ++
 .../guides/markdown.text.erb                  |  3 +-
 .../system/collapsed_section_comments_spec.rb | 33 ++++++++++++++++---
 3 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/engine/app/javascript/controllers/coplan/source_comments_controller.js b/engine/app/javascript/controllers/coplan/source_comments_controller.js
index 4fd7f35d..d77e3a50 100644
--- a/engine/app/javascript/controllers/coplan/source_comments_controller.js
+++ b/engine/app/javascript/controllers/coplan/source_comments_controller.js
@@ -1,6 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
 import { captureReactionFocus } from "coplan/reaction_focus"
 import { commentWindowTop } from "coplan/comment_window"
+import { revealSections } from "coplan/collapsed_sections"
 
 // The panel stays inside this Stimulus scope, even in the modal expander.
 // Only signed source ranges cross the wire; SVG ids are render-time lookup
@@ -266,6 +267,7 @@ export default class extends Controller {
       if (slide) slide.dispatchEvent(new CustomEvent("coplan:deck-reveal", {
         bubbles: true, detail: { slide: slide.dataset.slide }
       }))
+      revealSections(element)
       element.scrollIntoView({ block: "center", behavior: "instant" })
       this.show(element, data.dataset.threadStatus === "resolved", event.detail.focusReply === true)
     }
diff --git a/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb b/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
index 5827eafb..52019a6d 100644
--- a/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
+++ b/engine/app/views/coplan/agent_instructions/guides/markdown.text.erb
@@ -113,7 +113,8 @@ Markdown here still renders. Keep the blank line after the summary.
 ```
 
 Add `open` to the `<details>` tag to show the section expanded by default.
-Comments on text inside a collapsed section stay reachable: its summary shows how many open discussions it hides.
+Comments inside a collapsed section stay reachable: its summary shows how many open discussions it hides.
+Following a discussion link opens its enclosing sections, including for table and diagram comments.
 
 ## Hover definitions
 
diff --git a/spec/system/collapsed_section_comments_spec.rb b/spec/system/collapsed_section_comments_spec.rb
index d59b75fb..fa8e76cf 100644
--- a/spec/system/collapsed_section_comments_spec.rb
+++ b/spec/system/collapsed_section_comments_spec.rb
@@ -10,7 +10,7 @@
       content_markdown: <<~MARKDOWN)
         Summary: the retry budget ran out during the deploy.
 
-        <details>
+        <details id="raw-timeline">
         <summary>Raw timeline</summary>
 
         The queue backed up right after the rollout started.
@@ -19,6 +19,15 @@
 
         A manual drain was considered and rejected.
 
+        <details>
+        <summary>Queue samples</summary>
+
+        | Status | Count |
+        | --- | --- |
+        | Waiting | 42 |
+
+        </details>
+
         </details>
 
         ## Follow-ups
@@ -41,10 +50,10 @@ def discuss(anchor, body)
     thread
   end
 
-  def section = find("#plan-content-body details")
+  def section = find("#raw-timeline")
   def badge = section.find("summary .details-comment-badge")
-  def collapsed = "#plan-content-body details:not([open])"
-  def expanded = "#plan-content-body details[open]"
+  def collapsed = "#raw-timeline:not([open])"
+  def expanded = "#raw-timeline[open]"
 
   before do
     visit sign_in_path
@@ -56,6 +65,22 @@ def expanded = "#plan-content-body details[open]"
 
   after { page.current_window.resize_to(1400, 900) }
 
+  it "reveals every enclosing section for a linked table discussion" do
+    _, start, finish = CoPlan::Plans::SourceTargets.new(plan.current_content).ranges.find { |kind, *| kind == "table_cell" }
+    token = CoPlan::Plans::SourceTargets.verifier.generate(
+      { "digest" => Digest::SHA256.hexdigest(plan.current_content), "kind" => "table_cell",
+        "start" => start, "end" => finish, "label" => "Status" }, purpose: "comment")
+    thread = plan.comment_threads.create!(plan_version: plan.current_plan_version, source_token: token,
+      created_by_user: reviewer, status: "open")
+    thread.comments.create!(author_type: "human", author_id: reviewer.id, body_markdown: "How old are these samples?")
+
+    visit plan_page_path(plan, thread: thread.id)
+    expect(page).to have_css(".source-comments:popover-open", text: "How old are these samples?")
+    expect(page).to have_css("#plan-content-body details[open]", count: 2)
+    expect(page).to have_css(".data-grid .source-thread-badge", visible: true)
+    expect(page).to have_no_css(".source-comments textarea:focus")
+  end
+
   it "counts open discussions on the collapsed summary and opens the first one" do
     visit plan_page_path(plan)
     expect(page).to have_css(collapsed)

From 00778d2510bde19df77536c90cf14dc11d27bf91 Mon Sep 17 00:00:00 2001
From: Hampton Lintorn-Catlin <hampton@squareup.com>
Date: Sat, 7 Nov 2026 12:06:21 -0600
Subject: [PATCH 4/4] Preserve collapsed discussion keyboard focus

Signed-off-by: Hampton Lintorn-Catlin <hampton@squareup.com>
---
 .../assets/stylesheets/coplan/comments.css    |  3 +
 .../coplan/comment_margin_controller.js       |  4 +-
 .../coplan/text_selection_controller.js       |  8 ++-
 .../system/collapsed_section_comments_spec.rb | 69 ++++++++++++++++++-
 4 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/engine/app/assets/stylesheets/coplan/comments.css b/engine/app/assets/stylesheets/coplan/comments.css
index 54ebd1a5..5e08c4dc 100644
--- a/engine/app/assets/stylesheets/coplan/comments.css
+++ b/engine/app/assets/stylesheets/coplan/comments.css
@@ -215,6 +215,9 @@
   align-items: center;
   gap: 3px;
   margin-left: var(--space-sm);
+  min-width: 24px;
+  min-height: 24px;
+  justify-content: center;
   padding: 1px 7px;
   border: 1px solid transparent;
   border-radius: 999px;
diff --git a/engine/app/javascript/controllers/coplan/comment_margin_controller.js b/engine/app/javascript/controllers/coplan/comment_margin_controller.js
index 432ed1eb..d26e3a63 100644
--- a/engine/app/javascript/controllers/coplan/comment_margin_controller.js
+++ b/engine/app/javascript/controllers/coplan/comment_margin_controller.js
@@ -82,6 +82,8 @@ export default class extends Controller {
       if (!popover) continue
       const card = this.cards.get(id) || this.buildCard(id)
       this.fillCard(card, popover, mark)
+      // A section can reveal this card after the popover's toggle event.
+      card.classList.toggle("is-active", popover.matches(":popover-open"))
     }
 
     this.marks = marks
@@ -111,7 +113,7 @@ export default class extends Controller {
       }
       badge.dataset.threadId = ids[0]
       badge.dataset.count = ids.length
-      badge.setAttribute("aria-label", `${ids.length} ${ids.length === 1 ? "discussion" : "discussions"} in this section`)
+      badge.setAttribute("aria-label", `${ids.length} ${ids.length === 1 ? "discussion" : "discussions"} in this section, open the first`)
     }
   }
 
diff --git a/engine/app/javascript/controllers/coplan/text_selection_controller.js b/engine/app/javascript/controllers/coplan/text_selection_controller.js
index e893de26..1aab2ac9 100644
--- a/engine/app/javascript/controllers/coplan/text_selection_controller.js
+++ b/engine/app/javascript/controllers/coplan/text_selection_controller.js
@@ -372,12 +372,16 @@ export default class extends Controller {
     event.stopPropagation()
     const id = event.currentTarget.dataset.threadId
     const mark = this.contentTarget.querySelector(`mark.anchor-highlight[data-thread-id="${id}"], [data-source-badge][data-thread-id="${id}"]`)
-    if (!mark) return
+    const thread = document.getElementById(id)
+    if (!mark || !thread?.dataset.threadId) return
+    // Opening the section removes its badge. Keep a live focus-return target
+    // for both prose popovers and source-comment panels.
+    event.currentTarget.closest("summary")?.focus({ preventScroll: true })
     revealSections(mark)
     mark.scrollIntoView({ behavior: "instant", block: "center" })
     if (mark.hasAttribute("data-source-badge")) {
       mark.dispatchEvent(new CustomEvent("coplan:source-thread", {
-        bubbles: true, cancelable: true, detail: { threadId: document.getElementById(id)?.dataset.threadId, focusReply: false }
+        bubbles: true, cancelable: true, detail: { threadId: thread.dataset.threadId, focusReply: false }
       }))
     } else {
       this._showThreadPopoverFor(mark)
diff --git a/spec/system/collapsed_section_comments_spec.rb b/spec/system/collapsed_section_comments_spec.rb
index fa8e76cf..770d41f0 100644
--- a/spec/system/collapsed_section_comments_spec.rb
+++ b/spec/system/collapsed_section_comments_spec.rb
@@ -65,7 +65,7 @@ def expanded = "#raw-timeline[open]"
 
   after { page.current_window.resize_to(1400, 900) }
 
-  it "reveals every enclosing section for a linked table discussion" do
+  def table_discussion
     _, start, finish = CoPlan::Plans::SourceTargets.new(plan.current_content).ranges.find { |kind, *| kind == "table_cell" }
     token = CoPlan::Plans::SourceTargets.verifier.generate(
       { "digest" => Digest::SHA256.hexdigest(plan.current_content), "kind" => "table_cell",
@@ -74,6 +74,11 @@ def expanded = "#raw-timeline[open]"
       created_by_user: reviewer, status: "open")
     thread.comments.create!(author_type: "human", author_id: reviewer.id, body_markdown: "How old are these samples?")
 
+    thread
+  end
+
+  it "reveals every enclosing section for a linked table discussion" do
+    thread = table_discussion
     visit plan_page_path(plan, thread: thread.id)
     expect(page).to have_css(".source-comments:popover-open", text: "How old are these samples?")
     expect(page).to have_css("#plan-content-body details[open]", count: 2)
@@ -81,11 +86,71 @@ def expanded = "#raw-timeline[open]"
     expect(page).to have_no_css(".source-comments textarea:focus")
   end
 
+  it "returns focus to the table cell after its discussion closes" do
+    table_discussion
+    visit plan_page_path(plan)
+    section.find("summary", text: "Raw timeline").click
+    nested = section.find("details")
+    nested.find(".details-comment-badge").send_keys(:enter)
+    expect(page).to have_css(".source-comments:popover-open", text: "How old are these samples?")
+    expect(nested).to have_no_css(".details-comment-badge", visible: :all)
+    expect(page).to have_css(".source-comments [aria-label='Close element comments']:focus")
+    page.driver.browser.action.send_keys(:escape).perform
+    expect(page).to have_css("[data-source-target]:focus", text: "Status")
+  end
+
+  it "ignores a source badge whose thread disappeared before activation" do
+    thread = table_discussion
+    visit plan_page_path(plan)
+    section.find("summary", text: "Raw timeline").click
+    source_badge = section.find("details").find(".details-comment-badge")
+    # Model a Turbo replacement in the interval before the margin refresh.
+    dispatched_ids = source_badge.evaluate_script(<<~JS, "comment_thread_#{thread.id}")
+      ((button, id) => {
+        const dispatched = [];
+        const observe = event => { dispatched.push(event.detail.threadId ?? null); };
+        document.addEventListener("coplan:source-thread", observe);
+        button.click(); // Prove the action is bound and the event is observable.
+        document.getElementById(id).remove();
+        button.click();
+        document.removeEventListener("coplan:source-thread", observe);
+        return dispatched;
+      })(this, arguments[0])
+    JS
+    expect(dispatched_ids).to eq([ thread.id ])
+  end
+
+  it "keeps keyboard focus on the summary after activating its discussion badge" do
+    visit plan_page_path(plan)
+    badge.send_keys(:enter)
+    expect(page).to have_css("#comment_thread_#{backlog.id}_popover:popover-open")
+    expect(section).to have_no_css(".details-comment-badge", visible: :all)
+    expect(page).to have_css("#raw-timeline > summary:focus")
+    page.driver.browser.action.send_keys(:escape).perform
+    expect(page).to have_no_css(".thread-popover:popover-open")
+    expect(page).to have_css("#raw-timeline > summary:focus")
+  end
+
+  it "marks a newly revealed margin card active and clears it when dismissed" do
+    visit plan_page_path(plan)
+    badge.click
+    expect(page).to have_css("#comment_thread_#{backlog.id}_popover:popover-open")
+    expect(page).to have_css(".comment-margin__card.is-active[data-thread-id='comment_thread_#{backlog.id}']")
+    page.driver.browser.action.send_keys(:escape).perform
+    expect(page).to have_no_css(".comment-margin__card.is-active")
+  end
+
+  it "offers a discussion button target at least 24 pixels in each dimension" do
+    visit plan_page_path(plan)
+    expect(badge.rect.width).to be >= 24
+    expect(badge.rect.height).to be >= 24
+  end
+
   it "counts open discussions on the collapsed summary and opens the first one" do
     visit plan_page_path(plan)
     expect(page).to have_css(collapsed)
     expect(badge["data-count"]).to eq("2")
-    expect(badge[:"aria-label"]).to eq("2 discussions in this section")
+    expect(badge[:"aria-label"]).to eq("2 discussions in this section, open the first")
 
     # Resolved discussions count only while they are shown.
     find("body").send_keys("s")