ENG-1249 Implement Discourse context overlay in Live Preview

[trangdoan982]

Second of three stacked PRs for ENG-1249. Stack: #1413 → this → #1415. Based on #1413 — review that first; this diff is against it.

https://www.loom.com/share/a7a58ec7bfd54d34b702c395acffe819

Reviewer brief

Result: In Live Preview, every link to a discourse node carries an inline badge with that node's relation count. Selecting it opens a popover listing those relations, with the option to add one. A node with no relations still badges, reading 0, and its popover says "No discourse relation found". Toggled by Show discourse context overlay in General settings, applied without a reload. Reading view is unchanged and follows in #1415.

Review focus: how a badge learns its count changed, and the two CodeMirror flags whose meaning is easy to invert. Both expanded below.

How a badge gets on screen

flowchart LR
  DOC["editor text<br>see [[Claim A|this]]"] --> RE["extractLinktext<br>→ 'Claim A'"]
  RE --> RES["resolveDiscourseLinkTarget"]
  RES --> IDX[("RelationsIndex")]
  RES --> OUT["file, nodeType, count 4"]
  OUT --> W["CM6 widget decoration"]
  W --> BADGE["shared badge element"]

Loading

The badge is plain DOM, not React. Neither render surface has a React root where a badge is inserted, and mounting one per link — dozens per note — would be far heavier than the badge deserves. #1415 reuses this same element, which is what keeps the two surfaces from drifting apart visually.

React appears exactly once, in the popover, which renders RelationshipSection — the same component the sidebar panel uses, so the two cannot disagree about a node's relations.

How a badge learns its count changed — the subtle part

Nothing about the document changes when a relation is added. The count lives entirely outside the text being rendered.

sequenceDiagram
  participant U as User
  participant F as relations.json
  participant I as RelationsIndex
  participant V as ViewPlugin
  U->>F: add a relation
  F->>I: vault "modify"
  I->>I: mark stale, reload<br>keep old snapshot
  I->>I: version 7 → 8
  I->>V: notify → empty transaction
  V->>V: update: version changed?
  V->>U: rebuild, badge now 5

Loading

The trap is in the last two steps. update() early-returns when nothing relevant changed, and an empty transaction changes neither the document nor the viewport — so the guard swallowed exactly the signal the refresh was sending:

// before — the redraw ran and did nothing
if (!update.docChanged && !update.viewportChanged) return;

The fix gives update() something it can observe: the index exposes a monotonic version, compared alongside the setting.

[!NOTE]
This is why the index carries a version counter in #1413. A ViewPlugin can only see transactions, so state living outside the document has to be made visible to it explicitly.

Two flags whose meaning inverts easily

ignoreEvent() returns true — the CM6 default, and the one we want. The subject of "ignore" is the editor, not the widget: true keeps CM6 out of the way so the badge's own click listener fires. Returning false reads like "let the widget receive clicks" and does the opposite — an earlier revision had a badge that rendered perfectly and was completely inert.

updateDOM() returns true — meaning the element was updated in place and must not be replaced. CM6 rebuilds a widget's DOM whenever eq() is false, which a count change always is; replacing the element would detach the anchor an open popover is positioned against.

Verification

• pnpm ci:validate: 8/8 check-types, 5/5 test:unit.
• Driven against a real vault over CDP on this branch alone: badges render with the correct count, the popover opens and lists the same relations, the setting adds and removes badges live, and Reading view correctly shows nothing yet.

Scope check

• Ran $scope-check against the ENG ticket and final diff.
• Scope beyond Done When: None. Covers the setting and the overlay for one surface; the second follows.

Local delegated full review

• Ran a comprehensive review of the entire final diff in a subagent with a fresh context.

Review findings addressed here: badges update in place so an open popover keeps a connected anchor; the outside-click guard no longer treats Obsidian's suggestion overlay as outside; the popover opens toward whichever side has more room; the empty-state message clears when the first relation is added; and a file that stops being a discourse node now triggers the refresh that removes its badges.

Warning

Known limitation: Live Preview skips a link straddling a viewport-range boundary. The badge also does not model buildGroupedRelations dropping relations whose endpoint no longer resolves to a file, so a relation pointing at a deleted note is still counted — that needs a file lookup per relation on a render path, so it is left as a follow-up.

🤖 Generated with Claude Code

[linear-code]

ENG-1249

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
discourse-graph	Ready	Preview	Sep 8, 2026 9:31pm UTC

[supabase]

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[devin-ai-integration]

Devin Review found 4 potential issues.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

[graphite-app]

PR size/scope check

This PR is over our review-size guideline.

• Recommended: ~200 lines changed
• Acceptable limit: up to 400 lines when well-scoped/self-contained
• Preferred file count: fewer than 5 files

Please split this into smaller PRs unless there is a clear reason the changes need to land together.

If keeping it as one PR, please add a brief justification covering:

• What single problem this PR solves
• Why the files/changes are coupled

[mdroidian]

Same as #1413: ENG-1249 Add a cached relations index and link resolution

There should be one PR per ticket. If the original ticket needs to be broken up into three, then create a parent ticket and 3 children tickets, please.

[trangdoan982]

ahh gotcha, this answers my question earlier. in case it left you a notification

[trangdoan982]

Superseded by #1434. Closed automatically when its head branch was renamed to eng-2249-implement-discourse-context-overlay-in-live-preview to match its new ticket, ENG-2249. Same commits, same body (Loom link carried over).