🔬 Research

This document contains the uncompromising, hard-truths of the v1 AgentBubble architecture and the research driving the v2 upgrade.

1. 🐛 SPA Navigation

The Flaw: Quartz uses client-side routing. agent-bubble.inline.ts bails out if the DOM elements exist. Thus, the iframe’s chatUrl gets locked to the very first page the user landed on. The Fix: We CANNOT fix this by re-rendering the iframe (destroys UX). We MUST inject a MutationObserver or listen to document.addEventListener("nav") and push state via postMessage.

2. 🧱 Iframe Jail

The Flaw: Iframes are cross-origin sandboxes. The agent cannot “see” the page the user is on, nor can it highlight text or guide the user visually. The Fix: A structured window.addEventListener("message") bridge inside the host script. This turns the host script into the “hands and eyes” of the agent.

3. 💬 Comment Integration

How do we merge the AI Agent with the community comment system?

• ❌ Bad (DOM Scraping): Fragile, breaks on Remark42 theme updates.
• 🟡 Okay (API Fetching): Agent queries Remark42’s read API based on the current URL.
• 🟢 Genius (Native Bot): AgentBubble isn’t a floating FAB at all. The OMP Agent registers as a Remark42 user. It replies natively in comment threads when @agent is mentioned. For floating chat, use the RPC Bridge to stream active comment context.