Render suggestive mode overlay button

[sid597]

refer eng-732-left-side-panel-for-suggestive-mode for main pr

[linear]

ENG-912 Render suggestive mode overlay

[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 ↗︎.

[sid597]

• Render suggestive mode overlay button #465 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[mdroidian]

@CodeRabbit full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new Suggestive Mode overlay feature: implements a React overlay component with a render entry point, wires a new page-ref observer/handler to render it, and exposes a user setting to enable/disable the observer. Integration touches settings UI, observer initialization, and page-ref handler logic.

Changes

Cohort / File(s)	Summary
Suggestive overlay component apps/roam/src/components/SuggestiveModeOverlay.tsx	New React overlay component and render entry renderSuggestive. Includes lazy render wrapper, highlight toggling, panel open/close handling, and mounting via ExtensionApiContextProvider. Exports default SuggestiveModeOverlay and named renderSuggestive.
Observers and handlers apps/roam/src/utils/pageRefObserverHandlers.ts, apps/roam/src/utils/initializeObserversAndListeners.ts	Adds suggestive overlay observer path: new getSuggestiveOverlayHandler and suggestiveOverlayPageRefHandler, marking nodes with data-discourse-suggestive-overlay and invoking renderSuggestive. Initializes the observer conditionally based on the setting in initializeObserversAndListeners.ts.
Settings UI apps/roam/src/components/settings/HomePersonalSettings.tsx	Adds “Suggestive Mode Overlay” Checkbox tied to extensionAPI.settings["suggestive-mode-overlay"]. On change, updates setting and triggers onPageRefObserverChange(getSuggestiveOverlayHandler(onloadArgs)).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Settings as Settings UI
  participant Init as Observer Init
  participant Observer as PageRef Observer
  participant Handler as suggestiveOverlayPageRefHandler
  participant Renderer as renderSuggestive
  participant React as SuggestiveModeOverlay (React)

  User->>Settings: Toggle "Suggestive Mode Overlay"
  Settings-->>Init: onPageRefObserverChange(handler)
  Init->>Observer: addPageRefObserver(getSuggestiveOverlayHandler)

  Note over Observer,Handler: On matching page-ref span appears
  Observer->>Handler: handle(span, onloadArgs)
  Handler->>Handler: Gate checks (parent, tag, data attr)
  Handler->>Renderer: renderSuggestive({ tag, parent, onloadArgs })
  Renderer->>React: Mount component into parent
  React-->>Observer: Overlay mounted

  User->>React: Click toggle button
  React->>React: Open/close panel, toggle highlights

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• move pageRefObs from discourseGraphMode #36 — Introduces a suggestive overlay handler and rendering path, paralleling the new handler and render integration added here.
• Initial steps to re-enable Roam Discourse Context Overlay #95 — Updates the same observer/render workflow (handlers, initialization, settings), closely matching the added suggestive overlay wiring in this PR.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title “Render suggestive mode overlay button” clearly and concisely conveys the primary change introduced by this pull request, namely the rendering of a UI button for the suggestive mode overlay, aligning with the core additions in the component and settings files without extraneous detail.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8464cf1 and 3db29ed.

📒 Files selected for processing (4)

• apps/roam/src/components/SuggestiveModeOverlay.tsx (1 hunks)
• apps/roam/src/components/settings/HomePersonalSettings.tsx (2 hunks)
• apps/roam/src/utils/initializeObserversAndListeners.ts (2 hunks)
• apps/roam/src/utils/pageRefObserverHandlers.ts (3 hunks)

🔇 Additional comments (3)

apps/roam/src/utils/initializeObserversAndListeners.ts (1)

146-148: Nice alignment with existing observer gating

Conditionally adding the suggestive observer before the shared enable step mirrors the other overlay flows and keeps the initialization order intact. Looks good.

apps/roam/src/components/settings/HomePersonalSettings.tsx (1)

80-104: Setting toggle wiring looks solid

The new checkbox mirrors the discourse overlay toggle, persists the setting, and hooks into onPageRefObserverChange with the cached handler. No concerns here.

apps/roam/src/utils/pageRefObserverHandlers.ts (1)

21-83: Parallel handler implementation looks good

The suggestive overlay handler mirrors the discourse overlay flow, including tag resolution, data-attribute gating, and parent insertion. This keeps the observer semantics consistent. Nicely done.

[mdroidian]