handhold-sdk 1.0.0

package/src/ui/UICoach.js

@@ -0,0 +1,1725 @@
+/**
+ * Hand Hold SDK - UI Coach
+ * Handles visual UI guidance with element highlighting, overlays, arrows, and dimming
+ */
+
+import eventBus from '../utils/eventBus.js';
+import { MarkdownRenderer } from '../utils/MarkdownRenderer.js';
+import '@phosphor-icons/web/regular';
+import { Button, ButtonVariant, ButtonSize } from './components/Button.js';
+
+class UICoach {
+  constructor(config) {
+    this.config = config;
+    this.overlay = null;
+    this.spotlight = null;
+    this.highlightBox = null;
+    this.arrow = null;
+    this.tooltip = null;
+    this.currentElement = null;
+    this.resizeObserver = null;
+    this.isHighlighting = false;
+    this.selectionButton = null;
+    this.selectionEnabled = false;
+    this.selectionText = '';
+    this._selectionHandler = null;
+    this._selectionHideHandler = null;
+    
+    // Inject styles
+    this._injectStyles();
+    
+    // Listen for scan requests
+    eventBus.on('ui:scan_request', (data) => this._onScanRequest(data));
+  }
+
+  /**
+   * Handle scan request animation
+   * @param {Object} data - { selector }
+   */
+  _onScanRequest(data) {
+    const selector = data.selector;
+    if (!selector) return;
+
+    const element = document.querySelector(selector);
+    if (!element) return;
+
+    // Scroll into view first
+    try {
+      element.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+    } catch (e) {
+      element.scrollIntoView(true);
+    }
+
+    // Create scanner if needed
+    if (!this.scanner) {
+      this._createScanner();
+    }
+
+    // Get element position
+    const rect = element.getBoundingClientRect();
+    
+    // Position scanner initially at center of screen
+    const startX = window.innerWidth / 2 - 30;
+    const startY = window.innerHeight / 2 - 30;
+    
+    this.scanner.style.left = `${startX}px`;
+    this.scanner.style.top = `${startY}px`;
+    this.scanner.classList.add('active');
+
+    // Animate to target after a tiny delay to ensure CSS transition works
+    requestAnimationFrame(() => {
+      setTimeout(() => {
+        // Recalculate rect in case scroll happened
+        const updatedRect = element.getBoundingClientRect();
+        const targetX = updatedRect.left + (updatedRect.width / 2) - 30; 
+        const targetY = updatedRect.top + (updatedRect.height / 2) - 30;
+        
+        this.scanner.style.left = `${targetX}px`;
+        this.scanner.style.top = `${targetY}px`;
+      }, 50);
+    });
+
+    // Hide after animation
+    setTimeout(() => {
+        this.scanner.classList.remove('active');
+    }, 1500);
+  }
+
+  /**
+   * Create scanner element (magnifying glass)
+   */
+  _createScanner() {
+    this.scanner = document.createElement('div');
+    this.scanner.className = 'handhold-scanner';
+    // Use a Phosphor-style magnifying glass icon for better visibility
+    this.scanner.innerHTML = `
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="11" cy="11" r="7"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    `;
+    document.body.appendChild(this.scanner);
+  }
+
+  /**
+   * Inject CSS styles for highlighting
+   */
+  _injectStyles() {
+    const existingStyles = document.getElementById('handhold-uicoach-styles');
+    if (existingStyles) {
+      existingStyles.remove();
+    }
+
+    const primaryColor = this.config.primaryColor || '#004AF5';
+    const primaryRgb = this._hexToRgb(primaryColor);
+    const zIndex = this.config.zIndex || 999990;
+    const isDark = this.config.theme === 'dark';
+
+    const styles = document.createElement('style');
+    styles.id = 'handhold-uicoach-styles';
+    styles.textContent = `
+      :root {
+        --hh-coach-bg: ${isDark ? 'rgba(30, 41, 59, 0.75)' : 'rgba(255, 255, 255, 0.9)'};
+        --hh-coach-backdrop: blur(24px);
+        --hh-coach-fg: ${isDark ? '#f8fafc' : '#334155'};
+        --hh-coach-border: ${isDark ? 'rgba(255, 255, 255, 0.08)' : 'rgba(255, 255, 255, 0.6)'};
+        --hh-coach-primary: ${primaryColor};
+        --hh-coach-primary-rgb: ${primaryRgb};
+        --hh-coach-primary-fg: #ffffff;
+        --hh-coach-primary-dark: ${this._adjustColor(primaryColor, -20)};
+        --hh-coach-secondary: ${isDark ? 'rgba(51, 65, 85, 0.6)' : '#f1f5f9'};
+        --hh-coach-secondary-fg: ${isDark ? '#f8fafc' : '#475569'};
+        --hh-coach-muted: ${isDark ? '#94a3b8' : '#64748b'};
+        --hh-coach-shadow: ${isDark ? '0 20px 40px -5px rgba(0, 0, 0, 0.4), 0 0 0 1px rgba(255, 255, 255, 0.05)' : '0 24px 48px -12px rgba(50, 50, 93, 0.15), 0 12px 24px -8px rgba(0, 0, 0, 0.1), 0 0 0 1px rgba(255, 255, 255, 0.5)'};
+        --hh-coach-radius: 24px;
+      }
+
+      /* Overlay background */
+      .handhold-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100vw;
+        height: 100vh;
+        background: transparent; 
+        z-index: ${zIndex + 1};
+        pointer-events: none;
+        opacity: 0;
+        transition: opacity 0.4s ease;
+      }
+      
+      .handhold-overlay.active {
+        opacity: 1;
+      }
+
+      /* Highlight box around element */
+      .handhold-highlight {
+        position: fixed;
+        border: 2px solid var(--hh-coach-primary);
+        border-radius: 12px;
+        z-index: ${zIndex + 3};
+        pointer-events: none;
+        box-shadow: 0 0 0 4px rgba(var(--hh-coach-primary-rgb), 0.2);
+        transition: all 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+        animation: handhold-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+      }
+
+      @keyframes handhold-pulse {
+        0%, 100% { opacity: 1; }
+        50% { opacity: .7; }
+      }
+
+      /* Scanning Animation (Magnifying Glass) */
+      .handhold-scanner {
+        position: fixed;
+        width: 60px;
+        height: 60px;
+        pointer-events: none;
+        z-index: ${zIndex + 10};
+        transition: top 0.4s ease-in-out, left 0.4s ease-in-out;
+        opacity: 0;
+      }
+
+      .handhold-scanner.active {
+        opacity: 1;
+        animation: handhold-scan-float 3s infinite ease-in-out;
+      }
+
+      .handhold-scanner svg {
+        width: 100%;
+        height: 100%;
+        filter: drop-shadow(0 4px 6px rgba(0,0,0,0.1));
+        color: var(--hh-coach-primary);
+      }
+
+      @keyframes handhold-scan-float {
+        0%, 100% { transform: translateY(0) rotate(0deg); }
+        25% { transform: translateY(-10px) rotate(-5deg); }
+        75% { transform: translateY(5px) rotate(5deg); }
+      }
+
+      /* Arrow pointing to element */
+      .handhold-arrow {
+        position: fixed;
+        z-index: ${zIndex + 4};
+        pointer-events: none;
+        animation: handhold-bounce 1s ease-in-out infinite;
+        filter: drop-shadow(0 4px 8px rgba(0,0,0,0.15));
+      }
+
+      .handhold-arrow svg {
+        width: 36px;
+        height: 36px;
+      }
+
+      .handhold-arrow svg path {
+        fill: var(--hh-coach-primary);
+      }
+
+      @keyframes handhold-bounce {
+        0%, 100% { transform: translateY(0); }
+        50% { transform: translateY(-8px); }
+      }
+      
+      /* Direction-specific arrow positions */
+      .handhold-arrow.top { transform-origin: center bottom; }
+      .handhold-arrow.bottom { transform-origin: center top; }
+      .handhold-arrow.left { transform-origin: right center; }
+      .handhold-arrow.right { transform-origin: left center; }
+
+      .handhold-arrow.bottom svg { transform: rotate(180deg); }
+      .handhold-arrow.left svg { transform: rotate(-90deg); }
+      .handhold-arrow.right svg { transform: rotate(90deg); }
+
+      /* Step tooltip */
+      .handhold-step-tooltip {
+        position: fixed;
+        background: var(--hh-coach-bg);
+        backdrop-filter: var(--hh-coach-backdrop);
+        -webkit-backdrop-filter: var(--hh-coach-backdrop);
+        border: 1px solid var(--hh-coach-border);
+        border-radius: 16px;
+        box-shadow: var(--hh-coach-shadow);
+        padding: 16px 20px;
+        max-width: 300px;
+        z-index: ${zIndex + 5};
+        pointer-events: auto;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+        font-size: 14px;
+        line-height: 1.5;
+        color: var(--hh-coach-fg);
+        animation: handhold-fadeIn 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+      }
+
+      @keyframes handhold-fadeIn {
+        from { opacity: 0; transform: translateY(12px) scale(0.96); }
+        to { opacity: 1; transform: translateY(0) scale(1); }
+      }
+      
+      .handhold-step-tooltip.dark {
+        /* handled by variables now */
+      }
+
+      .handhold-step-tooltip-text {
+        margin: 0 0 16px 0;
+        font-weight: 500;
+        color: var(--hh-coach-fg);
+      }
+
+      .handhold-step-tooltip-actions {
+        display: flex;
+        justify-content: flex-end;
+        gap: 8px;
+      }
+
+      .handhold-step-tooltip-btn {
+        padding: 8px 16px;
+        border-radius: 10px;
+        border: 1px solid transparent;
+        cursor: pointer;
+        font-size: 13px;
+        font-weight: 600;
+        transition: all 0.2s;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.05);
+      }
+
+      .handhold-step-tooltip-btn.primary {
+        background: var(--hh-coach-primary);
+        color: var(--hh-coach-primary-fg);
+        box-shadow: 0 8px 20px -4px rgba(0, 0, 0, 0.2);
+      }
+
+      .handhold-step-tooltip-btn.primary:hover {
+        transform: none;
+        background: var(--hh-coach-primary-dark);
+        box-shadow: 0 12px 24px -4px rgba(0, 0, 0, 0.25);
+      }
+
+      .handhold-step-tooltip-btn.secondary {
+        background: var(--hh-coach-secondary);
+        color: var(--hh-coach-secondary-fg);
+      }
+
+      .handhold-step-tooltip-btn.secondary:hover {
+        background: ${isDark ? 'rgba(51, 65, 85, 0.8)' : '#e2e8f0'};
+      }
+
+      /* Explanation Modal */
+      .handhold-explain-modal-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100vw;
+        height: 100vh;
+        background: rgba(0, 0, 0, 0.2);
+        backdrop-filter: blur(2px);
+        z-index: ${zIndex + 10};
+        opacity: 0;
+        transition: opacity 0.2s ease;
+        pointer-events: none;
+      }
+
+      .handhold-explain-modal-overlay.active {
+        opacity: 1;
+        pointer-events: auto;
+      }
+
+      .handhold-explain-modal {
+        position: fixed;
+        top: 20px;
+        right: 20px;
+        bottom: 20px;
+        height: auto;
+        background: #FFFFFF;
+        border: 1px solid #E2E8F0;
+        border-radius: 6px;
+        box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+        width: 380px;
+        max-width: calc(100vw - 40px);
+        z-index: ${zIndex + 11};
+        font-family: 'Manrope', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+        font-size: 14px;
+        line-height: 1.5;
+        color: #0F172A;
+        transform: translateX(calc(100% + 20px));
+        transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+        display: flex;
+        flex-direction: column;
+        gap: 0;
+      }
+      
+      .handhold-explain-modal.active {
+        transform: translateX(0);
+      }
+
+      .handhold-explain-header {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        padding: 12px 16px;
+        border-bottom: 2px solid #E2E8F0;
+        flex-shrink: 0;
+      }
+      
+      .handhold-explain-title {
+        font-weight: 700;
+        font-size: 16px;
+        margin: 0;
+        color: #0F172A; /* slate-900 */
+      }
+
+      .handhold-explain-close-icon {
+        background: none;
+        border: none;
+        cursor: pointer;
+        padding: 0;
+        width: 56px;
+        height: 56px;
+        color: #64748B; /* slate-500 */
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        border-radius: 4px;
+        transition: all 0.2s;
+        margin-right: -4px;
+        font-size: 24px; /* For Phosphor icon */
+      }
+
+      .handhold-explain-close-icon:hover {
+        background: #F1F5F9; /* slate-100 */
+        color: #0F172A;
+      }
+
+      .handhold-explain-content {
+        padding: 16px;
+        overflow-y: auto;
+        flex: 1;
+        display: flex;
+        flex-direction: column;
+        gap: 12px; /* Gap between group and close button */
+      }
+
+      .handhold-explain-body-group {
+        display: flex;
+        flex-direction: column;
+        gap: 8px; /* Closer gap between term and text */
+      }
+      
+      .handhold-explain-term {
+        font-weight: 700;
+        font-size: 18px;
+        color: #0F172A; /* slate-900 */
+        line-height: 1.3;
+      }
+      
+      .handhold-explain-text {
+        font-size: 14px;
+        line-height: 1.6;
+        color: #64748B; /* slate-500 */
+      }
+      
+      /* Markdown Styles */
+      .handhold-explain-text p {
+        margin-bottom: 0px;
+      }
+      
+      .handhold-explain-text strong {
+        font-weight: 700;
+        color: #334155; /* slate-700 */
+      }
+      
+      .handhold-explain-text em {
+        font-style: italic;
+      }
+      
+      .handhold-explain-text ul, .handhold-explain-text ol {
+        margin-left: 20px;
+        margin-bottom: 12px;
+        list-style-type: disc;
+      }
+      
+      .handhold-explain-text ol {
+        list-style-type: decimal;
+      }
+      
+      .handhold-explain-text li {
+        margin-bottom: 4px;
+      }
+      
+      .handhold-explain-text code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+        font-size: 0.9em;
+        background-color: #F1F5F9; /* slate-100 */
+        padding: 2px 4px;
+        border-radius: 4px;
+        color: #0F172A; /* slate-900 */
+      }
+      
+      .handhold-explain-text pre {
+        background-color: #F8FAFC; /* slate-50 */
+        border: 1px solid #E2E8F0; /* slate-200 */
+        border-radius: 6px;
+        padding: 12px;
+        overflow-x: auto;
+        margin-bottom: 12px;
+      }
+      
+      .handhold-explain-text pre code {
+        background-color: transparent;
+        padding: 0;
+        color: inherit;
+        font-size: 0.85em;
+      }
+      
+      .handhold-explain-text blockquote {
+        border-left: 4px solid #E2E8F0; /* slate-200 */
+        padding-left: 12px;
+        color: #64748B; /* slate-500 */
+        font-style: italic;
+        margin-bottom: 12px;
+      }
+      
+      .handhold-explain-text h1, .handhold-explain-text h2, .handhold-explain-text h3, .handhold-explain-text h4 {
+        font-weight: 600;
+        color: #1E293B; /* slate-800 */
+        margin-top: 16px;
+        margin-bottom: 8px;
+        line-height: 1.4;
+      }
+      
+      .handhold-explain-text h1 { font-size: 1.5em; }
+      .handhold-explain-text h2 { font-size: 1.3em; }
+      .handhold-explain-text h3 { font-size: 1.1em; }
+      
+      .handhold-explain-text a {
+        color: var(--hh-coach-primary);
+        text-decoration: none;
+      }
+      
+      .handhold-explain-text a:hover {
+        text-decoration: underline;
+      }
+      
+      .handhold-explain-text hr {
+        border: 0;
+        border-top: 1px solid #E2E8F0; /* slate-200 */
+        margin: 24px 0;
+      }
+      
+      .handhold-explain-text img {
+        max-width: 100%;
+        height: auto;
+        border-radius: 6px;
+        margin: 16px 0;
+        border: 1px solid #E2E8F0;
+      }
+      
+      .handhold-explain-text table {
+        width: 100%;
+        border-collapse: collapse;
+        margin-bottom: 16px;
+        font-size: 0.9em;
+      }
+      
+      .handhold-explain-text th, .handhold-explain-text td {
+        border: 1px solid #E2E8F0;
+        padding: 8px 12px;
+        text-align: left;
+      }
+      
+      .handhold-explain-text th {
+        background-color: #F8FAFC; /* slate-50 */
+        font-weight: 600;
+        color: #1E293B; /* slate-800 */
+      }
+      
+      .handhold-explain-text tr:nth-child(even) {
+        background-color: #F8FAFC; /* slate-50 */
+      }
+
+      .handhold-explain-footer-close {
+        width: 100%;
+        padding: 8px 16px;
+        background: #FFFFFF;
+        border: 2px solid #E2E8F0;
+        border-radius: 6px;
+        color: #0F172A;
+        font-weight: 500;
+        font-size: 14px;
+        cursor: pointer;
+        transition: all 0.2s;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin-top: auto;
+      }
+
+      .handhold-explain-footer-close:hover {
+        background: #F8FAFC; /* slate-50 */
+        border-color: #CBD5E1; /* slate-300 */
+      }
+
+      .handhold-explain-loading {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding: 40px;
+        color: #64748B;
+      }
+      
+      .handhold-explain-spinner {
+        width: 32px;
+        height: 32px;
+        border: 3px solid #E2E8F0;
+        border-top-color: #0F172A;
+        border-radius: 50%;
+        animation: handhold-spin 0.8s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+        margin-bottom: 16px;
+      }
+
+      @keyframes handhold-spin {
+        from { transform: rotate(0deg); }
+        to { transform: rotate(360deg); }
+      }
+
+      /* Selection Explain Button */
+      .handhold-selection-explain {
+        position: fixed;
+        z-index: ${zIndex + 6};
+        display: inline-flex;
+        height: 40px;
+        padding: 0 16px;
+        flex-direction: row;
+        justify-content: center;
+        align-items: center;
+        gap: 8px;
+        
+        border-radius: 9999px;
+        border: 1px solid #004AF5;
+        background: #004AF5;
+        
+        /* shadow/xs */
+        box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+        
+        color: #FFFFFF;
+        font-size: 14px;
+        font-weight: 600;
+        
+        cursor: pointer;
+        transform: translate(-50%, -100%) scale(0.9);
+        opacity: 0;
+        pointer-events: none;
+        transition: all 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+        font-family: 'Manrope', Circular Std, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      }
+      
+      .handhold-selection-explain i, .handhold-selection-explain svg {
+        font-size: 20px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+
+      .handhold-selection-explain:hover {
+        transform: translate(-50%, -100%) scale(1);
+        box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+        background: #003BC4; /* paidhr-blue-600 */
+        border-color: #003BC4;
+      }
+
+      .handhold-selection-explain.visible {
+        opacity: 1;
+        pointer-events: auto;
+        transform: translate(-50%, -120%) scale(1);
+      }
+
+      /* Error State */
+      .handhold-explain-error {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding: 40px 20px;
+        text-align: center;
+        height: 100%;
+        color: #64748B;
+      }
+      
+      .handhold-explain-error-icon {
+        width: 48px;
+        height: 48px;
+        background: #FEF2F2; /* red-50 */
+        color: #EF4444; /* red-500 */
+        border-radius: 50%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin-bottom: 16px;
+        font-size: 24px;
+        font-weight: 700;
+        font-family: ui-sans-serif, system-ui, sans-serif;
+      }
+      
+      .handhold-explain-error-title {
+        font-weight: 700;
+        font-size: 16px;
+        color: #1E293B;
+        margin-bottom: 8px;
+      }
+      
+      .handhold-explain-error-text {
+        font-size: 14px;
+        line-height: 1.5;
+        margin-bottom: 24px;
+      }
+      
+      .handhold-explain-retry-btn {
+        background: #FFFFFF;
+        border: 1px solid #E2E8F0;
+        border-radius: 6px;
+        padding: 8px 16px;
+        font-size: 14px;
+        font-weight: 600;
+        color: #0F172A;
+        cursor: pointer;
+        transition: all 0.2s;
+        box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+      }
+      
+      .handhold-explain-retry-btn:hover {
+        background: #F8FAFC;
+        border-color: #CBD5E1;
+      }
+
+      /* Skeleton Loader */
+      .handhold-skeleton {
+        animation: handhold-pulse-bg 1.5s infinite ease-in-out;
+        background-color: ${isDark ? '#334155' : '#E2E8F0'};
+        border-radius: 4px;
+      }
+      
+      @keyframes handhold-pulse-bg {
+        0% { opacity: 0.6; }
+        50% { opacity: 1; }
+        100% { opacity: 0.6; }
+      }
+
+      .handhold-explain-skeleton-container {
+        padding: 16px;
+        display: flex;
+        flex-direction: column;
+        gap: 24px;
+      }
+
+      .handhold-skeleton-group {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+      }
+
+      .handhold-skeleton-text {
+        height: 14px;
+        width: 100%;
+      }
+      
+      .handhold-skeleton-text.short {
+        width: 60%;
+      }
+      
+      .handhold-skeleton-text.medium {
+        width: 80%;
+      }
+
+      .handhold-skeleton-term {
+        height: 20px;
+        width: 40%;
+        margin-bottom: 4px;
+      }
+    `;
+
+    document.head.appendChild(styles);
+  }
+
+  /**
+   * Adjust color brightness
+   */
+  _adjustColor(color, amount) {
+    const hex = color.replace('#', '');
+    const num = parseInt(hex, 16);
+    let r = (num >> 16) + amount;
+    if (r > 255) r = 255; else if (r < 0) r = 0;
+    let b = ((num >> 8) & 0x00FF) + amount;
+    if (b > 255) b = 255; else if (b < 0) b = 0;
+    let g = (num & 0x0000FF) + amount;
+    if (g > 255) g = 255; else if (g < 0) g = 0;
+    return `#${(g | (b << 8) | (r << 16)).toString(16).padStart(6, '0')}`;
+  }
+
+  /**
+   * Convert hex to rgb
+   */
+  _hexToRgb(hex) {
+    const num = parseInt(hex.replace('#', ''), 16);
+    const r = (num >> 16) & 255;
+    const g = (num >> 8) & 255;
+    const b = num & 255;
+    return `${r}, ${g}, ${b}`;
+  }
+
+  /**
+   * Darken a hex color
+   */
+  _darkenColor(hex, percent) {
+    const num = parseInt(hex.replace('#', ''), 16);
+    const amt = Math.round(2.55 * percent);
+    const R = Math.max(0, (num >> 16) - amt);
+    const G = Math.max(0, ((num >> 8) & 0x00FF) - amt);
+    const B = Math.max(0, (num & 0x0000FF) - amt);
+    return `#${(1 << 24 | R << 16 | G << 8 | B).toString(16).slice(1)}`;
+  }
+
+  /**
+   * Highlight a UI element
+   * @param {string} selector - CSS selector for element
+   * @param {Object} options - { message, showArrow, showTooltip, arrowPosition }
+   * @returns {boolean} - Success status
+   */
+  highlightElement(selector, options = {}) {
+    const element = document.querySelector(selector);
+
+    if (!element) {
+      console.warn(`[HandHold UICoach] Element not found: ${selector}`);
+      eventBus.emit('highlight:not_found', { selector });
+      return Promise.resolve(false);
+    }
+
+    // Scroll element into view first to ensure visibility (guarded: scrollIntoView
+    // is absent in some environments, and the old catch re-threw by calling it again)
+    if (typeof element.scrollIntoView === 'function') {
+      try {
+        element.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+      } catch (e) {
+        try { element.scrollIntoView(true); } catch (_) { /* not supported */ }
+      }
+    }
+
+    // Phase 5.3: resolve with the ACTUAL outcome after the highlight is built,
+    // so a caller can fall back when the element detached (SPA re-render) between
+    // the query and the delayed build. Previously this returned true synchronously
+    // before the setTimeout ran, so the fallback could never trigger on that race.
+    return new Promise((resolve) => {
+      // Wait for scroll to potentially finish or at least start
+      setTimeout(() => {
+        // The element may have been removed while we waited — bail so the caller
+        // can re-match instead of silently doing nothing.
+        if (!element.isConnected) {
+          eventBus.emit('highlight:not_found', { selector });
+          resolve(false);
+          return;
+        }
+        // Clear previous highlight
+        this.clearHighlight();
+
+        this.currentElement = element;
+        this.isHighlighting = true;
+
+        // Add click listener to the element itself to auto-advance
+        if (options.onClick) {
+          this._elementClickListener = options.onClick;
+          element.addEventListener('click', this._elementClickListener, { once: true });
+          
+          // Also listen for input/focus events if it's an input element
+          if (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' || element.isContentEditable) {
+             this._elementInputListener = () => {
+                // Remove listeners immediately to prevent double firing
+                element.removeEventListener('input', this._elementInputListener);
+                if (this._elementClickListener) {
+                   element.removeEventListener('click', this._elementClickListener);
+                }
+                options.onClick();
+             };
+             element.addEventListener('input', this._elementInputListener, { once: true });
+             
+             // Also treat focus as interaction if requested? 
+             // User said "click into... and start typing", so 'input' is safest. 
+             // But for checkboxes/radios 'change' is better.
+             if (element.type === 'checkbox' || element.type === 'radio') {
+                element.addEventListener('change', this._elementInputListener, { once: true });
+             }
+          }
+        }
+
+        // Create overlay (for dimming)
+        this._createOverlay();
+
+        // Create highlight box
+        this._createHighlightBox(element);
+
+        // Create arrow
+        if (options.showArrow !== false) {
+          this._createArrow(element, options.arrowPosition);
+        }
+
+        // Create tooltip if message provided
+        if (options.message && options.showTooltip !== false) {
+          // Pass arrow position preference to tooltip for smarter placement relative to arrow
+          const tooltipOptions = { ...options, preferredPosition: options.arrowPosition };
+          this._createTooltip(element, options.message, tooltipOptions);
+        }
+
+        // Watch for element position changes
+        this._watchElementPosition(element);
+
+        eventBus.emit('highlight:shown', { selector, element });
+        resolve(true);
+      }, 100); // Short delay to allow layout to settle
+    });
+  }
+
+  /**
+   * Create overlay background
+   */
+  _createOverlay() {
+    this.overlay = document.createElement('div');
+    this.overlay.className = 'handhold-overlay';
+    this.overlay.id = 'handhold-overlay';
+    document.body.appendChild(this.overlay);
+
+    // Trigger animation
+    requestAnimationFrame(() => {
+      if (this.overlay) {
+        this.overlay.classList.add('active');
+      }
+    });
+  }
+
+  /**
+   * Create highlight box around element
+   */
+  _createHighlightBox(element) {
+    const rect = element.getBoundingClientRect();
+    const padding = 4;
+
+    this.highlightBox = document.createElement('div');
+    this.highlightBox.className = 'handhold-highlight';
+    this.highlightBox.id = 'handhold-highlight';
+    this.highlightBox.style.cssText = `
+      top: ${rect.top - padding}px;
+      left: ${rect.left - padding}px;
+      width: ${rect.width + padding * 2}px;
+      height: ${rect.height + padding * 2}px;
+    `;
+
+    document.body.appendChild(this.highlightBox);
+  }
+
+  /**
+   * Create arrow pointing to element
+   */
+  _createArrow(element, preferredPosition) {
+    const rect = element.getBoundingClientRect();
+    const arrowSize = 40;
+    const offset = 10;
+
+    // Determine best arrow position
+    const position = preferredPosition || this._calculateArrowPosition(rect);
+
+    this.arrow = document.createElement('div');
+    this.arrow.className = `handhold-arrow ${position}`;
+    this.arrow.id = 'handhold-arrow';
+
+    // Arrow SVG
+    this.arrow.innerHTML = `
+      <svg viewBox="0 0 40 40" xmlns="http://www.w3.org/2000/svg">
+        <path d="M20 5 L35 35 L20 28 L5 35 Z" />
+      </svg>
+    `;
+
+    // Position arrow based on direction
+    let top, left;
+    switch (position) {
+      case 'top':
+        top = rect.top - arrowSize - offset;
+        left = rect.left + (rect.width / 2) - (arrowSize / 2);
+        break;
+      case 'bottom':
+        top = rect.bottom + offset;
+        left = rect.left + (rect.width / 2) - (arrowSize / 2);
+        break;
+      case 'left':
+        top = rect.top + (rect.height / 2) - (arrowSize / 2);
+        left = rect.left - arrowSize - offset;
+        break;
+      case 'right':
+        top = rect.top + (rect.height / 2) - (arrowSize / 2);
+        left = rect.right + offset;
+        break;
+      default:
+        top = rect.top - arrowSize - offset;
+        left = rect.left + (rect.width / 2) - (arrowSize / 2);
+    }
+
+    this.arrow.style.cssText = `top: ${top}px; left: ${left}px;`;
+    document.body.appendChild(this.arrow);
+  }
+
+  /**
+   * Calculate best arrow position based on element position
+   */
+  _calculateArrowPosition(rect) {
+    const viewport = {
+      width: window.innerWidth,
+      height: window.innerHeight,
+    };
+
+    // Check available space in each direction
+    const spaceAbove = rect.top;
+    const spaceBelow = viewport.height - rect.bottom;
+    const spaceLeft = rect.left;
+    const spaceRight = viewport.width - rect.right;
+
+    const minSpace = 60;
+
+    // Prefer top, then bottom, then sides
+    if (spaceAbove >= minSpace) return 'top';
+    if (spaceBelow >= minSpace) return 'bottom';
+    if (spaceLeft >= minSpace) return 'left';
+    if (spaceRight >= minSpace) return 'right';
+    
+    return 'top';
+  }
+
+  /**
+   * Create tooltip near element
+   */
+  _createTooltip(element, message, options = {}) {
+    const rect = element.getBoundingClientRect();
+    
+    this.tooltip = document.createElement('div');
+    this.tooltip.className = `handhold-step-tooltip ${this.config.theme === 'dark' ? 'dark' : ''}`;
+    this.tooltip.id = 'handhold-step-tooltip';
+
+    const showDoneButton = options.showDoneButton !== false;
+    const showSkipButton = options.showSkipButton === true;
+
+    this.tooltip.innerHTML = `
+      <p class="handhold-step-tooltip-text">${message}</p>
+      <div class="handhold-step-tooltip-actions">
+        ${showSkipButton ? new Button({
+          text: 'Skip',
+          variant: ButtonVariant.SECONDARY,
+          size: ButtonSize.SMALL,
+          className: 'handhold-step-tooltip-btn',
+          attributes: { 'data-action': 'skip' }
+        }).render() : ''}
+        ${showDoneButton ? new Button({
+          text: 'Got it',
+          variant: ButtonVariant.PRIMARY,
+          size: ButtonSize.SMALL,
+          className: 'handhold-step-tooltip-btn',
+          attributes: { 'data-action': 'done' }
+        }).render() : ''}
+      </div>
+    `;
+
+    // Position tooltip logic
+    const tooltipWidth = 280;
+    // We can't know height yet as it's not in DOM, assume roughly 150px
+    const estimatedHeight = 150; 
+    const margin = 12;
+
+    const viewport = {
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+
+    // Default: try placing it on the side with most space
+    // Similar to arrow logic but with collision detection against the element itself
+    
+    // Check available space
+    const spaceTop = rect.top;
+    const spaceBottom = viewport.height - rect.bottom;
+    const spaceLeft = rect.left;
+    const spaceRight = viewport.width - rect.right;
+
+    let top, left;
+
+    // Prefer bottom if space allows
+    if (spaceBottom >= estimatedHeight + margin) {
+       top = rect.bottom + margin + 10; // +10 for arrow offset
+       left = rect.left + (rect.width / 2) - (tooltipWidth / 2);
+    } 
+    // Else try top
+    else if (spaceTop >= estimatedHeight + margin) {
+       top = rect.top - estimatedHeight - margin;
+       left = rect.left + (rect.width / 2) - (tooltipWidth / 2);
+    }
+    // Else try right
+    else if (spaceRight >= tooltipWidth + margin) {
+       top = rect.top;
+       left = rect.right + margin;
+    }
+    // Else try left
+    else if (spaceLeft >= tooltipWidth + margin) {
+       top = rect.top;
+       left = rect.left - tooltipWidth - margin;
+    }
+    // Fallback: Stick to bottom but force it on screen (might overlap if screen really small)
+    else {
+       top = rect.bottom + margin;
+       left = rect.left;
+    }
+
+    // Horizontal boundary check (keep within viewport)
+    left = Math.max(10, Math.min(left, viewport.width - tooltipWidth - 10));
+    
+    // Vertical boundary check
+    if (top + estimatedHeight > viewport.height) {
+        top = viewport.height - estimatedHeight - 10;
+    }
+    if (top < 10) {
+        top = 10;
+    }
+
+    // Final Collision Check: Ensure we don't overlap the target element
+    // If tooltip rect overlaps element rect, move it
+    const tooltipRect = {
+        top: top,
+        bottom: top + estimatedHeight,
+        left: left,
+        right: left + tooltipWidth
+    };
+
+    const elementRect = {
+        top: rect.top,
+        bottom: rect.bottom,
+        left: rect.left,
+        right: rect.right
+    };
+
+    const overlap = !(tooltipRect.right < elementRect.left || 
+                      tooltipRect.left > elementRect.right || 
+                      tooltipRect.bottom < elementRect.top || 
+                      tooltipRect.top > elementRect.bottom);
+
+    if (overlap) {
+        // If overlapping, try to move it away aggressively
+        // If mostly overlapping vertically, move sideways
+        if (spaceRight > spaceLeft) {
+            left = rect.right + margin;
+        } else {
+            left = rect.left - tooltipWidth - margin;
+        }
+        
+        // Clamp again
+        left = Math.max(10, Math.min(left, viewport.width - tooltipWidth - 10));
+    }
+
+    this.tooltip.style.cssText = `top: ${top}px; left: ${left}px;`;
+    
+    // Add event listeners
+    this.tooltip.addEventListener('click', (e) => {
+      const target = e.target;
+      const action = target.dataset.action;
+      
+      if (action) {
+        // Disable button to prevent double-clicks
+        if (target.tagName === 'BUTTON') {
+          target.disabled = true;
+          // target.textContent = '...'; // Removed to prevent conflicts with text-analysis extensions
+          target.style.opacity = '0.7';
+          target.style.cursor = 'wait';
+        }
+
+        try {
+          if (action === 'done') {
+            eventBus.emit('step:done');
+          } else if (action === 'skip') {
+            eventBus.emit('step:skip');
+          }
+        } catch (error) {
+          console.error('[HandHold] Error handling click action:', error);
+        }
+      }
+    });
+
+    document.body.appendChild(this.tooltip);
+  }
+
+  /**
+   * Watch for element position changes
+   */
+  _watchElementPosition(element) {
+    // Use ResizeObserver to detect size changes
+    if (window.ResizeObserver) {
+      this.resizeObserver = new ResizeObserver(() => {
+        this._updateHighlightPosition();
+      });
+      this.resizeObserver.observe(element);
+    }
+
+    // Also update on scroll and resize
+    this._boundUpdatePosition = () => this._updateHighlightPosition();
+    window.addEventListener('scroll', this._boundUpdatePosition, { passive: true });
+    window.addEventListener('resize', this._boundUpdatePosition, { passive: true });
+  }
+
+  /**
+   * Update highlight position (for scroll/resize)
+   */
+  _updateHighlightPosition() {
+    if (!this.currentElement || !this.isHighlighting) return;
+
+    const rect = this.currentElement.getBoundingClientRect();
+    const padding = 4;
+
+    if (this.highlightBox) {
+      this.highlightBox.style.top = `${rect.top - padding}px`;
+      this.highlightBox.style.left = `${rect.left - padding}px`;
+      this.highlightBox.style.width = `${rect.width + padding * 2}px`;
+      this.highlightBox.style.height = `${rect.height + padding * 2}px`;
+    }
+
+    // Update arrow position too
+    if (this.arrow) {
+      const position = this.arrow.className.split(' ').find(c => ['top', 'bottom', 'left', 'right'].includes(c));
+      const arrowSize = 40;
+      const offset = 10;
+      let top, left;
+
+      switch (position) {
+        case 'top':
+          top = rect.top - arrowSize - offset;
+          left = rect.left + (rect.width / 2) - (arrowSize / 2);
+          break;
+        case 'bottom':
+          top = rect.bottom + offset;
+          left = rect.left + (rect.width / 2) - (arrowSize / 2);
+          break;
+        case 'left':
+          top = rect.top + (rect.height / 2) - (arrowSize / 2);
+          left = rect.left - arrowSize - offset;
+          break;
+        case 'right':
+          top = rect.top + (rect.height / 2) - (arrowSize / 2);
+          left = rect.right + offset;
+          break;
+      }
+
+      this.arrow.style.top = `${top}px`;
+      this.arrow.style.left = `${left}px`;
+    }
+  }
+
+  /**
+   * Clear all highlights
+   */
+  clearHighlight() {
+    // Remove click listener if exists
+    if (this.currentElement && this._elementClickListener) {
+      this.currentElement.removeEventListener('click', this._elementClickListener);
+      this._elementClickListener = null;
+    }
+
+    this.isHighlighting = false;
+    this.currentElement = null;
+
+    // Remove elements
+    if (this.overlay) {
+      this.overlay.remove();
+      this.overlay = null;
+    }
+    if (this.spotlight) {
+      this.spotlight.remove();
+      this.spotlight = null;
+    }
+    if (this.highlightBox) {
+      this.highlightBox.remove();
+      this.highlightBox = null;
+    }
+    if (this.arrow) {
+      this.arrow.remove();
+      this.arrow = null;
+    }
+    if (this.tooltip) {
+      this.tooltip.remove();
+      this.tooltip = null;
+    }
+
+    // Clean up observers and listeners
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+      this.resizeObserver = null;
+    }
+    if (this._boundUpdatePosition) {
+      window.removeEventListener('scroll', this._boundUpdatePosition);
+      window.removeEventListener('resize', this._boundUpdatePosition);
+      this._boundUpdatePosition = null;
+    }
+
+    eventBus.emit('highlight:cleared');
+  }
+
+  /**
+   * Update tooltip message
+   */
+  updateTooltipMessage(message) {
+    if (this.tooltip) {
+      const textEl = this.tooltip.querySelector('.handhold-step-tooltip-text');
+      if (textEl) {
+        textEl.textContent = message;
+      }
+    }
+  }
+
+  enableSelectionExplain() {
+    if (this.selectionEnabled) return;
+    this.selectionEnabled = true;
+    this._createSelectionButton();
+    this._selectionHandler = () => this._handleSelection();
+    this._selectionHideHandler = (e) => {
+      // Check if event target is valid Node before checking contains
+      if (this.selectionButton && e.target instanceof Node && this.selectionButton.contains(e.target)) return;
+      this._hideSelectionButton();
+    };
+    document.addEventListener('mouseup', this._selectionHandler);
+    document.addEventListener('keyup', this._selectionHandler);
+    document.addEventListener('scroll', this._selectionHideHandler, true);
+    document.addEventListener('mousedown', this._selectionHideHandler);
+    // Hide on window blur (tab switch) or visibility change
+    window.addEventListener('blur', this._selectionHideHandler);
+    document.addEventListener('visibilitychange', this._selectionHideHandler);
+  }
+
+  disableSelectionExplain() {
+    if (!this.selectionEnabled) return;
+    this.selectionEnabled = false;
+    
+    // Clear debounce timer
+    if (this._selectionDebounce) {
+      clearTimeout(this._selectionDebounce);
+      this._selectionDebounce = null;
+    }
+
+    if (this._selectionHandler) {
+      document.removeEventListener('mouseup', this._selectionHandler);
+      document.removeEventListener('keyup', this._selectionHandler);
+      this._selectionHandler = null;
+    }
+    if (this._selectionHideHandler) {
+      document.removeEventListener('scroll', this._selectionHideHandler, true);
+      document.removeEventListener('mousedown', this._selectionHideHandler);
+      window.removeEventListener('blur', this._selectionHideHandler);
+      document.removeEventListener('visibilitychange', this._selectionHideHandler);
+      this._selectionHideHandler = null;
+    }
+    this._hideSelectionButton();
+  }
+
+  _createSelectionButton() {
+    if (this.selectionButton) return;
+    
+    this.selectionButton = new Button({
+      text: 'Explain this',
+      icon: '<i class="ph ph-question"></i>',
+      variant: ButtonVariant.PRIMARY,
+      className: 'handhold-selection-explain',
+      attributes: { type: 'button' },
+      onClick: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const text = this.selectionText;
+        this._hideSelectionButton();
+        if (text) {
+          // Capture page context (truncated to ~15k chars)
+          let context = document.body.innerText || '';
+          if (context.length > 15000) {
+            context = context.substring(0, 15000) + '...[truncated]';
+          }
+          
+          eventBus.emit('selection:explain', { text, context });
+        }
+      }
+    }).create();
+
+    // Use mousedown to prevent focus loss issues
+    this.selectionButton.addEventListener('mousedown', (e) => e.stopPropagation());
+    
+    document.body.appendChild(this.selectionButton);
+  }
+
+  /**
+   * Expand selection to nearest meaningful container
+   * @param {Selection} selection 
+   * @returns {Range|null}
+   */
+  _getExpansionRange(selection) {
+    if (!selection.rangeCount) return null;
+    
+    const range = selection.getRangeAt(0);
+    const container = range.commonAncestorContainer;
+    
+    // Ensure we have an element, not a text node
+    let element = container.nodeType === Node.TEXT_NODE ? container.parentElement : container;
+    
+    // Define "meaningful" containers
+    const meaningfulTags = ['P', 'DIV', 'SPAN', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'TD', 'TH', 'BUTTON', 'A', 'LABEL', 'SECTION', 'ARTICLE', 'ASIDE'];
+    
+    // Scenario B: Multi-Element Selection
+    // If common ancestor contains both start and end nodes but they are different
+    if (range.startContainer !== range.endContainer) {
+      // Safety check for very large containers
+      const isTooLarge = ['BODY', 'MAIN'].includes(element.tagName) || (element.textContent && element.textContent.length > 2000);
+      
+      if (isTooLarge) {
+        // Fallback: return original range to avoid selecting entire page
+        return range; 
+      }
+      
+      // Expand to full content of the common ancestor
+      const newRange = document.createRange();
+      newRange.selectNodeContents(element);
+      return newRange;
+    }
+
+    // Scenario A/C: Single Element/Partial Selection
+    // Walk up to find best container
+    let targetElement = element;
+    let attempts = 0;
+    while (targetElement && targetElement.parentElement && attempts < 5) {
+      // Stop if we hit a meaningful tag
+      if (meaningfulTags.includes(targetElement.tagName)) {
+        break;
+      }
+      // Stop if growing too large
+      if (targetElement.textContent && targetElement.textContent.length > 500) {
+        break;
+      }
+      // Stop if we hit root-ish things
+      if (['BODY', 'HTML', 'MAIN'].includes(targetElement.tagName)) {
+        break;
+      }
+      
+      targetElement = targetElement.parentElement;
+      attempts++;
+    }
+    
+    if (targetElement) {
+        const newRange = document.createRange();
+        newRange.selectNodeContents(targetElement);
+        return newRange;
+    }
+    
+    return range;
+  }
+
+  _handleSelection() {
+    // Clear existing debounce
+    if (this._selectionDebounce) {
+      clearTimeout(this._selectionDebounce);
+    }
+
+    // Debounce to prevent flickering on double clicks/drags
+    this._selectionDebounce = setTimeout(() => {
+      const selection = window.getSelection();
+      
+      // Basic validation
+      if (!selection || selection.isCollapsed || selection.rangeCount === 0) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      // Initial check on original selection to avoid expanding in ignored areas
+      let range = selection.getRangeAt(0);
+      let container = range.commonAncestorContainer;
+      let element = container.nodeType === Node.ELEMENT_NODE ? container : container.parentElement;
+
+      if (!element) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      // Ignore if inside our own UI
+      if (element.closest('#handhold-container') || 
+          element.closest('.handhold-selection-explain') ||
+          element.closest('.handhold-explain-modal')) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      // Ignore input fields
+      if (element.closest('input, textarea, [contenteditable="true"]')) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      // --- EXPANSION LOGIC ---
+      const expandedRange = this._getExpansionRange(selection);
+      if (expandedRange) {
+        // Apply expansion
+        selection.removeAllRanges();
+        selection.addRange(expandedRange);
+        
+        // Update range reference
+        range = expandedRange;
+      }
+      // -----------------------
+
+      const text = selection.toString().trim();
+      // Length check - ensure we have meaningful content
+      if (!text || text.length < 2) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      const rect = range.getBoundingClientRect();
+      
+      // Ignore zero-width rects (hidden elements or empty selections)
+      if (!rect || rect.width === 0 || rect.height === 0) {
+        this._hideSelectionButton();
+        return;
+      }
+
+      this.selectionText = text;
+      this._showSelectionButton(rect);
+    }, 200); // 200ms delay
+  }
+
+  _showSelectionButton(rect) {
+    if (!this.selectionButton) return;
+    const top = Math.max(8, rect.top - 8);
+    const left = rect.left + rect.width / 2;
+    this.selectionButton.style.top = `${top}px`;
+    this.selectionButton.style.left = `${left}px`;
+    this.selectionButton.classList.add('visible');
+  }
+
+  _hideSelectionButton() {
+    if (!this.selectionButton) return;
+    this.selectionText = '';
+    this.selectionButton.classList.remove('visible');
+  }
+
+  /**
+   * Check if currently highlighting
+   */
+  isActive() {
+    return this.isHighlighting;
+  }
+
+  /**
+   * Get current highlighted element
+   */
+  getCurrentElement() {
+    return this.currentElement;
+  }
+
+  /**
+   * Destroy the UI Coach (cleanup)
+   */
+  destroy() {
+    this.clearHighlight();
+    this.disableSelectionExplain();
+    if (this.selectionButton) {
+      this.selectionButton.remove();
+      this.selectionButton = null;
+    }
+    this._removeExplainModal();
+    
+    // Remove injected styles
+    const styles = document.getElementById('handhold-uicoach-styles');
+    if (styles) {
+      styles.remove();
+    }
+  }
+
+  /**
+   * Show explanation modal for a term
+   * @param {Object} data - { terms: [{term, definition}], summary }
+   */
+  showExplainModal(data) {
+    this._createExplainModal();
+    
+    // Build content HTML for multiple terms
+    const termsHtml = (data.terms || []).map(item => {
+      // If term is just the full selection (likely error fallback), skip it
+      // But if it's a real term, show it.
+      // We can use a heuristic: if term length > 100, it's probably the selection text, not a "term"
+      const isLongTerm = item.term && item.term.length > 100;
+      
+      const definitionHtml = MarkdownRenderer.parse(item.definition);
+      return `
+        <div class="handhold-explain-body-group">
+          ${!isLongTerm ? `<div class="handhold-explain-term">${this._escapeHtml(item.term)}</div>` : ''}
+          <div class="handhold-explain-text">${definitionHtml}</div>
+        </div>
+      `;
+    }).join('');
+    
+    const body = this.explainModal.querySelector('.handhold-explain-content');
+    body.innerHTML = `
+      ${termsHtml}
+      ${new Button({
+        text: 'Close',
+        variant: ButtonVariant.OUTLINE,
+        className: 'handhold-explain-footer-close'
+      }).render()}
+    `;
+    
+    // Add listeners
+    const closeBtn = body.querySelector('.handhold-explain-footer-close');
+    if (closeBtn) {
+        closeBtn.addEventListener('click', () => this._hideModal());
+    }
+    
+    // Show
+    this._showModal();
+  }
+
+  /**
+   * Show loading state in explain modal
+   * @param {string} term 
+   */
+  showExplainLoading(term) {
+    this._createExplainModal();
+    
+    const body = this.explainModal.querySelector('.handhold-explain-content');
+    body.innerHTML = `
+      <div class="handhold-explain-skeleton-container">
+        <div class="handhold-skeleton-group">
+          <div class="handhold-skeleton handhold-skeleton-term"></div>
+          <div class="handhold-skeleton handhold-skeleton-text"></div>
+          <div class="handhold-skeleton handhold-skeleton-text medium"></div>
+        </div>
+        <div class="handhold-skeleton-group">
+          <div class="handhold-skeleton handhold-skeleton-term"></div>
+          <div class="handhold-skeleton handhold-skeleton-text"></div>
+          <div class="handhold-skeleton handhold-skeleton-text"></div>
+          <div class="handhold-skeleton handhold-skeleton-text short"></div>
+        </div>
+        <div class="handhold-explain-loading-message" style="display: flex; align-items: center; gap: 10px; margin-top: 8px; color: #64748B; font-size: 13px; font-weight: 500;">
+          <div style="width: 16px; height: 16px; border: 2px solid #CBD5E1; border-top-color: #334155; border-radius: 50%; animation: handhold-spin 1s linear infinite;"></div>
+          <span>Consulting knowledgebase...</span>
+        </div>
+      </div>
+    `;
+    
+    this._showModal();
+  }
+
+  /**
+   * Show error state in explain modal
+   * @param {string} term 
+   * @param {Function} onRetry 
+   */
+  showExplainError(term, onRetry) {
+    this._createExplainModal();
+    
+    const body = this.explainModal.querySelector('.handhold-explain-content');
+    body.innerHTML = `
+      <div class="handhold-explain-error" style="display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 40px 20px; text-align: center; height: 100%;">
+        <div style="width: 112px; height: 112px; margin-bottom: 8px; flex-shrink: 0; display: flex; align-items: center; justify-content: center;">
+          <img src="/illustration-error.svg" alt="Error" style="width: 100%; height: 100%; object-fit: contain;" />
+        </div>
+        <div class="handhold-explain-error-title" style="font-size: 18px; font-weight: 700; color: #0F172A; margin-bottom: 4px; line-height: 1.5;">We're sorry, something went wrong</div>
+        <div class="handhold-explain-error-text" style="font-size: 14px; color: #64748B; margin-bottom: 16px; line-height: 1.5; padding: 0 8px;">We encountered an issue while trying to pull the definitions of the selected terms please try again.</div>
+        ${new Button({
+          text: 'Try again',
+          variant: ButtonVariant.PRIMARY,
+          className: 'handhold-explain-retry-btn',
+          attributes: { 'style': 'width: 100%; justify-content: center;' }
+        }).render()}
+      </div>
+    `;
+    
+    // Add listeners
+    const retryBtn = body.querySelector('.handhold-explain-retry-btn');
+    if (retryBtn && onRetry) {
+        retryBtn.addEventListener('click', () => {
+             onRetry();
+        });
+    }
+
+    const closeBtn = body.querySelector('.handhold-explain-footer-close');
+    if (closeBtn) {
+        closeBtn.addEventListener('click', () => this._hideModal());
+    }
+    
+    this._showModal();
+  }
+
+  _createExplainModal() {
+    if (this.explainModal) return;
+
+    // Create overlay
+    this.explainOverlay = document.createElement('div');
+    this.explainOverlay.className = 'handhold-explain-modal-overlay';
+    document.body.appendChild(this.explainOverlay);
+
+    // Create modal
+    this.explainModal = document.createElement('div');
+    this.explainModal.className = `handhold-explain-modal ${this.config.theme === 'dark' ? 'dark' : ''}`;
+    this.explainModal.innerHTML = `
+      <div class="handhold-explain-header">
+        <h3 class="handhold-explain-title">Glossary / FAQs</h3>
+        ${new Button({
+          icon: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"></line><line x1="6" y1="6" x2="18" y2="18"></line></svg>',
+          variant: ButtonVariant.GHOST,
+          size: ButtonSize.ICON_LG,
+          className: 'handhold-explain-close-icon',
+          attributes: { 'aria-label': 'Close' }
+        }).render()}
+      </div>
+      <div class="handhold-explain-content"></div>
+    `;
+    document.body.appendChild(this.explainModal);
+
+    // Events
+    this.explainOverlay.addEventListener('click', () => this._hideModal());
+    this.explainModal.querySelector('.handhold-explain-close-icon').addEventListener('click', () => this._hideModal());
+  }
+
+  _showModal() {
+    if (!this.explainModal) return;
+    
+    // Side panel animation
+    requestAnimationFrame(() => {
+      this.explainOverlay.classList.add('active');
+      this.explainModal.classList.add('active');
+    });
+  }
+
+  _hideModal() {
+    if (!this.explainModal) return;
+    this.explainOverlay.classList.remove('active');
+    this.explainModal.classList.remove('active');
+    
+    // Remove from DOM after transition to prevent overlay blocking
+    setTimeout(() => {
+      this._removeExplainModal();
+    }, 250);
+  }
+
+  _removeExplainModal() {
+    if (this.explainModal) {
+      this.explainModal.remove();
+      this.explainModal = null;
+    }
+    if (this.explainOverlay) {
+      this.explainOverlay.remove();
+      this.explainOverlay = null;
+    }
+  }
+
+  _escapeHtml(value) {
+    return String(value)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+}
+
+export default UICoach;