Auto-cleanup orphaned tooltips on DOM detachment (#134)

Author: karngyan

.gitignore

@@ -3,4 +3,5 @@ node_modules
 dist
 web
 .docs
-.husky/_
+.husky/_
+scripts/

src/managers/message-component-manager.test.ts

@@ -296,7 +296,12 @@ describe('message-component-manager', () => {
       await showTooltipComponent(message);
 
       const tooltipElement = document.querySelector('.gist-tooltip-outer');
-      expect(positionTooltip).toHaveBeenCalledWith(tooltipElement, '#target-el', 'top');
+      expect(positionTooltip).toHaveBeenCalledWith(
+        tooltipElement,
+        '#target-el',
+        'top',
+        expect.objectContaining({ onDetach: expect.any(Function) })
+      );
     });
 
     it('defaults tooltip position to bottom when not specified', async () => {
@@ -328,7 +333,12 @@ describe('message-component-manager', () => {
 
       await showTooltipComponent(message);
 
-      expect(positionTooltip).toHaveBeenCalledWith(expect.any(HTMLElement), '#target-el', 'bottom');
+      expect(positionTooltip).toHaveBeenCalledWith(
+        expect.any(HTMLElement),
+        '#target-el',
+        'bottom',
+        expect.objectContaining({ onDetach: expect.any(Function) })
+      );
     });
 
     it('returns false when positionTooltip returns null (target not found)', async () => {
@@ -426,6 +436,34 @@ describe('message-component-manager', () => {
       expect(container?.classList.contains('gist-visible')).toBe(false);
     });
 
+    it('removes wrapper and clears handle when onDetach is invoked by position manager', async () => {
+      let capturedOnDetach: (() => void) | undefined;
+      const mockCleanup = vi.fn();
+      vi.mocked(positionTooltip).mockImplementation((_el, _sel, _pos, options) => {
+        capturedOnDetach = options?.onDetach;
+        return { cleanup: mockCleanup, reposition: vi.fn() };
+      });
+
+      setupTooltipWrapper('inst-1');
+      const message: GistMessage = {
+        messageId: 'msg-1',
+        instanceId: 'inst-1',
+        properties: { gist: { elementId: '#target-el' } },
+      };
+
+      const result = await showTooltipComponent(message);
+      expect(result).toBe(true);
+      expect(document.getElementById('gist-tooltip-inst-1')).not.toBeNull();
+
+      capturedOnDetach!();
+
+      expect(document.getElementById('gist-tooltip-inst-1')).toBeNull();
+
+      // Subsequent hide should not call cleanup again since the map entry was cleared
+      hideTooltipComponent(message);
+      expect(mockCleanup).not.toHaveBeenCalled();
+    });
+
     it('returns false without calling positionTooltip when ensureTargetInView returns false', async () => {
       vi.mocked(ensureTargetInView).mockResolvedValue(false);
       setupTooltipWrapper('inst-1');

src/managers/message-component-manager.ts

@@ -292,7 +292,16 @@ export async function showTooltipComponent(message: GistMessage): Promise<boolea
     return false;
   }
 
-  const handle = positionTooltip(tooltipElement, selector, position);
+  const handle = positionTooltip(tooltipElement, selector, position, {
+    onDetach: () => {
+      tooltipHandleMap.delete(instanceId);
+      const w = findElement(wrapperId);
+      if (w) {
+        w.parentNode?.removeChild(w);
+      }
+    },
+  });
+
   if (handle) {
     const isVisible = tooltipElement.style.display !== 'none';
     if (isVisible) {

src/managers/tooltip-position-manager.test.ts

@@ -377,48 +377,199 @@ describe('tooltip-position-manager', () => {
         expect(result).toBeNull();
       });
 
-      it('stops repositioning when target is removed from DOM after initial positioning', () => {
+      it('calls onDetach and cleans up when target is removed from DOM after initial positioning', () => {
         let rafCallback: FrameRequestCallback | null = null;
         vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
           rafCallback = cb;
           return 1;
         });
 
+        const onDetach = vi.fn();
         const target = createTarget({});
         const tooltip = createTooltip({ width: 120, height: 50 });
-        handle = positionTooltip(tooltip, '#target', 'bottom');
+        handle = positionTooltip(tooltip, '#target', 'bottom', { onDetach });
 
         target.remove();
 
         window.dispatchEvent(new Event('scroll'));
         rafCallback!(0);
 
+        expect(onDetach).toHaveBeenCalledTimes(1);
         expect(log).toHaveBeenCalledWith(
           'Tooltip or target element removed from DOM, cleaning up listeners'
         );
       });
 
-      it('stops repositioning when tooltip is removed from DOM', () => {
+      it('calls onDetach and cleans up when tooltip is removed from DOM', () => {
         let rafCallback: FrameRequestCallback | null = null;
         vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
           rafCallback = cb;
           return 1;
         });
 
+        const onDetach = vi.fn();
         createTarget({});
         const tooltip = createTooltip({ width: 120, height: 50 });
-        handle = positionTooltip(tooltip, '#target', 'bottom');
+        handle = positionTooltip(tooltip, '#target', 'bottom', { onDetach });
 
         tooltip.remove();
 
         window.dispatchEvent(new Event('scroll'));
         rafCallback!(0);
 
+        expect(onDetach).toHaveBeenCalledTimes(1);
+        expect(log).toHaveBeenCalledWith(
+          'Tooltip or target element removed from DOM, cleaning up listeners'
+        );
+      });
+
+      it('calls onDetach via MutationObserver when target is removed without scroll', async () => {
+        const onDetach = vi.fn();
+        const target = createTarget({});
+        const tooltip = createTooltip({ width: 120, height: 50 });
+        handle = positionTooltip(tooltip, '#target', 'bottom', { onDetach });
+        expect(handle).not.toBeNull();
+
+        target.remove();
+
+        // MutationObserver callbacks are microtasks — flush them
+        await new Promise((r) => setTimeout(r, 0));
+
+        expect(onDetach).toHaveBeenCalledTimes(1);
+        expect(log).toHaveBeenCalledWith(
+          'Tooltip or target element removed from DOM, cleaning up listeners'
+        );
+      });
+
+      it('calls onDetach when target parent is replaced (SPA navigation)', async () => {
+        const onDetach = vi.fn();
+        const container = document.createElement('div');
+        container.id = 'app-root';
+        document.body.appendChild(container);
+
+        const target = document.createElement('div');
+        target.id = 'spa-target';
+        container.appendChild(target);
+        target.getBoundingClientRect = vi.fn(
+          () =>
+            ({
+              top: 100,
+              bottom: 140,
+              left: 200,
+              right: 280,
+              width: 80,
+              height: 40,
+              x: 200,
+              y: 100,
+              toJSON: () => ({}),
+            }) as DOMRect
+        );
+
+        const tooltip = createTooltip({ width: 120, height: 50 });
+        handle = positionTooltip(tooltip, '#spa-target', 'bottom', { onDetach });
+        expect(handle).not.toBeNull();
+
+        container.innerHTML = '<div>new page content</div>';
+
+        await new Promise((r) => setTimeout(r, 0));
+
+        expect(onDetach).toHaveBeenCalledTimes(1);
+        expect(log).toHaveBeenCalledWith(
+          'Tooltip or target element removed from DOM, cleaning up listeners'
+        );
+      });
+
+      it('cleans up without error when onDetach is not provided', () => {
+        let rafCallback: FrameRequestCallback | null = null;
+        vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+          rafCallback = cb;
+          return 1;
+        });
+
+        const target = createTarget({});
+        const tooltip = createTooltip({ width: 120, height: 50 });
+        handle = positionTooltip(tooltip, '#target', 'bottom');
+
+        target.remove();
+
+        window.dispatchEvent(new Event('scroll'));
+        expect(() => rafCallback!(0)).not.toThrow();
+
         expect(log).toHaveBeenCalledWith(
           'Tooltip or target element removed from DOM, cleaning up listeners'
         );
       });
 
+      it('does not swallow scroll repositioning when an unrelated DOM mutation fires', () => {
+        const rafCallbacks: FrameRequestCallback[] = [];
+        let nextRafId = 1;
+        vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+          rafCallbacks.push(cb);
+          return nextRafId++;
+        });
+
+        const target = createTarget({});
+        const tooltip = createTooltip({ width: 120, height: 50 });
+        handle = positionTooltip(tooltip, '#target', 'bottom');
+
+        const callCountBefore = (target.getBoundingClientRect as ReturnType<typeof vi.fn>).mock
+          .calls.length;
+
+        // Trigger an unrelated DOM mutation (target is still attached)
+        const unrelated = document.createElement('span');
+        document.body.appendChild(unrelated);
+
+        // Flush the MutationObserver microtask so its RAF is queued
+        // MutationObserver uses a real microtask in jsdom, but we need to
+        // manually invoke the RAF callback it scheduled.
+        // Simulate: mutation observer queued a RAF
+        const mutationRaf = rafCallbacks.pop();
+
+        // Now a scroll fires while the mutation RAF is pending
+        window.dispatchEvent(new Event('scroll'));
+
+        // The scroll should have queued its own RAF (not been blocked)
+        const scrollRaf = rafCallbacks.pop();
+        expect(scrollRaf).toBeDefined();
+
+        // Fire the mutation RAF — target is still attached, so it's a no-op
+        if (mutationRaf) mutationRaf(0);
+
+        // Fire the scroll RAF — this must call update() and reposition
+        scrollRaf!(0);
+
+        const callCountAfter = (target.getBoundingClientRect as ReturnType<typeof vi.fn>).mock.calls
+          .length;
+        expect(callCountAfter).toBeGreaterThan(callCountBefore);
+
+        unrelated.remove();
+      });
+
+      it('disconnects the MutationObserver on cleanup', async () => {
+        const disconnectSpy = vi.fn();
+        const OriginalObserver = globalThis.MutationObserver;
+        vi.stubGlobal(
+          'MutationObserver',
+          class extends OriginalObserver {
+            disconnect() {
+              disconnectSpy();
+              super.disconnect();
+            }
+          }
+        );
+
+        createTarget({});
+        const tooltip = createTooltip({ width: 120, height: 50 });
+        handle = positionTooltip(tooltip, '#target', 'bottom');
+
+        expect(disconnectSpy).not.toHaveBeenCalled();
+
+        handle!.cleanup();
+
+        expect(disconnectSpy).toHaveBeenCalledTimes(1);
+        handle = null;
+      });
+
       it('cleanup is idempotent and can be called multiple times safely', () => {
         createTarget({});
         const tooltip = createTooltip({ width: 120, height: 50 });

src/managers/tooltip-position-manager.ts

@@ -240,6 +240,15 @@ export interface TooltipHandle {
   reposition: () => void;
 }
 
+export interface PositionTooltipOptions {
+  /**
+   * Called when the position manager detects that the target or tooltip element
+   * was removed from the DOM unexpectedly (e.g. SPA navigation, dynamic DOM
+   * mutation). Not called when the consumer invokes `handle.cleanup()` directly.
+   */
+  onDetach?: () => void;
+}
+
 /**
  * Predicts whether the tooltip can be positioned after the target is scrolled
  * into view. Returns true only when the target exists in the DOM and at least
@@ -355,16 +364,19 @@ export async function ensureTargetInView(
 export function positionTooltip(
   tooltipElement: HTMLElement,
   targetSelector: string,
-  position: TooltipPosition
+  position: TooltipPosition,
+  options?: PositionTooltipOptions
 ): TooltipHandle | null {
   const targetElement = findTargetElement(targetSelector);
   if (!targetElement) {
     return null;
   }
 
   let rafId: number | null = null;
+  let mutationRafId: number | null = null;
   let cleaned = false;
   let scrollAncestors: Element[] = [];
+  let observer: MutationObserver | null = null;
 
   try {
     scrollAncestors = getScrollableAncestors(targetElement);
@@ -380,6 +392,7 @@ export function positionTooltip(
     if (!targetElement || !document.contains(targetElement) || !document.contains(tooltipElement)) {
       log(`Tooltip or target element removed from DOM, cleaning up listeners`);
       cleanup();
+      options?.onDetach?.();
       return;
     }
 
@@ -419,6 +432,10 @@ export function positionTooltip(
       return;
     }
     cleaned = true;
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
     window.removeEventListener('scroll', onScrollOrResize);
     window.removeEventListener('resize', onScrollOrResize);
     for (const ancestor of scrollAncestors) {
@@ -428,6 +445,10 @@ export function positionTooltip(
       cancelAnimationFrame(rafId);
       rafId = null;
     }
+    if (mutationRafId !== null) {
+      cancelAnimationFrame(mutationRafId);
+      mutationRafId = null;
+    }
   }
 
   update();
@@ -442,5 +463,20 @@ export function positionTooltip(
     ancestor.addEventListener('scroll', onScrollOrResize, { passive: true });
   }
 
+  try {
+    observer = new MutationObserver(() => {
+      if (mutationRafId !== null) return;
+      mutationRafId = requestAnimationFrame(() => {
+        mutationRafId = null;
+        if (!document.contains(targetElement)) {
+          update();
+        }
+      });
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  } catch {
+    // MutationObserver may not be available in some test environments
+  }
+
   return { cleanup, reposition: update };
 }