handhold-sdk 1.0.0

package/src/ui/HelpWidget.js

@@ -0,0 +1,1189 @@
+/**
+ * Hand Hold SDK - Help Widget
+ * Main floating help widget with intent menu, search, and guidance display
+ */
+
+import eventBus from '../utils/eventBus.js';
+import { MarkdownRenderer } from '../utils/MarkdownRenderer.js';
+import '@phosphor-icons/web/regular';
+import './widget.css';
+import { Button, ButtonVariant, ButtonSize } from './components/Button.js';
+
+class HelpWidget {
+  constructor(config) {
+    this.config = config;
+    this.container = null;
+    this.widget = null;
+    this.helpButton = null;
+    this.isOpen = false;
+    this.currentView = 'menu'; // 'menu', 'loading', 'guidance', 'error', 'clarification'
+    this.currentIntents = [];
+    this.currentGuidance = null;
+    this.currentArticle = null;
+    this.currentQuery = '';
+    this.errorMessage = null;
+    this.clarificationQuestion = null;
+    this.clarificationOptions = [];
+    this.completionLabel = null;
+    // Phase 2.1b: the SDK's single UI-state store, attached by HandHold. View
+    // methods mirror their state into it so a host renderer (React) can read
+    // one store instead of monkey-patching this widget.
+    this.uiState = null;
+
+    // Inject theme variables
+    this._injectThemeVariables();
+
+    // Bind methods
+    this._handleHeaderClick = this._handleHeaderClick.bind(this);
+  }
+
+  /** Attach the SDK UiState store so view changes mirror into it (Phase 2.1b). */
+  attachState(uiState) {
+    this.uiState = uiState;
+    this._syncState();
+  }
+
+  /**
+   * Mirror the current view + its data into UiState. Called from _updateBody()
+   * (which every view method funnels through) and from show/hide and the couple
+   * of view methods that write the DOM directly.
+   */
+  _syncState(extra = {}) {
+    if (!this.uiState) return;
+    const view = this.currentView;
+    this.uiState.setState({
+      view,
+      isOpen: this.isOpen,
+      intents: this.currentIntents ?? [],
+      guidance: this.currentGuidance ?? null,
+      article: view === 'article'
+        ? { ...(this.currentArticle || {}), query: this.currentQuery }
+        : null,
+      error: view === 'error' ? (this.errorMessage ?? null) : null,
+      clarification: view === 'clarification'
+        ? { question: this.clarificationQuestion, options: this.clarificationOptions ?? [] }
+        : null,
+      completion: view === 'completion' ? (this.completionLabel ?? null) : null,
+      ...extra,
+    });
+  }
+
+  /**
+   * Inject CSS variables for theme customization
+   */
+  _injectThemeVariables() {
+    const existingStyles = document.getElementById('handhold-theme-styles');
+    if (existingStyles) {
+      existingStyles.remove();
+    }
+
+    const { primaryColor, zIndex } = this.config;
+    
+    // Helper to darken color
+    const 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')}`;
+    };
+
+    const primaryDark = adjustColor(primaryColor || '#004AF5', -20);
+    
+    const styles = document.createElement('style');
+    styles.id = 'handhold-theme-styles';
+    styles.textContent = `
+      #handhold-container {
+        --hh-primary: ${primaryColor || '#004AF5'};
+        --hh-primary-dark: ${primaryDark};
+        --hh-z-index: ${zIndex || 9999};
+      }
+    `;
+
+    document.head.appendChild(styles);
+  }
+
+  /**
+   * Render the widget
+   */
+  render() {
+    if (this.container) return;
+
+    // Create container
+    this.container = document.createElement('div');
+    this.container.id = 'handhold-container';
+    
+    // Apply theme class
+    if (this.config.theme === 'dark') {
+      this.container.classList.add('dark');
+    }
+
+    // Determine position class
+    const pos = this.config.position || 'bottom-right';
+    let posClass = 'position-bottom-right';
+    if (pos.includes('top')) {
+        if (pos.includes('left')) posClass = 'position-top-left';
+        else posClass = 'position-top-right';
+    } else {
+        if (pos.includes('left')) posClass = 'position-bottom-left';
+        // default is bottom-right
+    }
+
+    // Create help button
+    if (this.config.showHelpButton) {
+      this.helpButton = new Button({
+        text: this.config.helpButtonText || '?',
+        variant: ButtonVariant.FAB,
+        className: `handhold-help-button ${posClass}`,
+        attributes: {
+          'aria-label': this.config.helpButtonAriaLabel
+        },
+        onClick: () => this.toggle()
+      }).create();
+      this.container.appendChild(this.helpButton);
+    }
+
+    // Create widget panel
+    this.widget = document.createElement('div');
+    this.widget.className = `handhold-widget ${posClass}`;
+    this.widget.innerHTML = this._renderWidgetContent();
+    this.container.appendChild(this.widget);
+
+    // Add to document
+    document.body.appendChild(this.container);
+
+    // Setup event listeners
+    this._setupEventListeners();
+  }
+
+  /**
+   * Render widget content
+   */
+  _renderWidgetContent() {
+    return `
+      <div class="handhold-widget-header">
+        <h3 class="handhold-widget-title">Get help</h3>
+        <div class="handhold-header-actions">
+          ${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-widget-close handhold-widget-exit',
+            attributes: { 'aria-label': 'Close help' }
+          }).render()}
+        </div>
+      </div>
+      <div class="handhold-widget-body">
+        ${this._renderViewContent()}
+      </div>
+    `;
+  }
+
+  /**
+   * Render current view content
+   */
+  _renderViewContent() {
+    switch (this.currentView) {
+      case 'loading':
+        return this._renderLoading();
+      case 'guidance':
+        return this._renderGuidance();
+      case 'agent':
+        return this._renderAgentRun();
+      case 'error':
+        return this._renderError(this.errorMessage);
+      case 'clarification':
+        return this._renderClarification();
+      case 'article':
+        return this._renderArticle();
+      case 'menu':
+      default:
+        return this._renderIntentMenu();
+    }
+  }
+
+  _renderArticle() {
+    if (!this.currentArticle) return '';
+    const title = this._escapeHtml(this.currentArticle.title || 'Explanation');
+    const summary = this.currentArticle.summary ? this._escapeHtml(this.currentArticle.summary) : '';
+    
+    // Parse markdown instead of just escaping
+    const contentHtml = MarkdownRenderer.parse(this.currentArticle.content || '');
+    
+    const query = this.currentQuery ? this._escapeHtml(this.currentQuery) : '';
+    return `
+      <div class="handhold-article">
+        <div class="handhold-article-query">${query ? `Selected: "${query}"` : ''}</div>
+        <h4 class="handhold-article-title">${title}</h4>
+        ${summary ? `<div class="handhold-article-summary">${summary}</div>` : ''}
+        <div class="handhold-article-content">${contentHtml}</div>
+        <div class="handhold-article-actions">
+          ${new Button({
+            text: 'Back',
+            variant: ButtonVariant.SECONDARY,
+            attributes: { 'data-action': 'back' }
+          }).render()}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Render intent menu view
+   */
+  _renderIntentMenu() {
+    const intentsHtml = this.currentIntents.map((intent, index) => `
+      <button class="handhold-intent-item" data-intent-index="${index}" data-intent-key="${intent.key}">
+        <span class="handhold-intent-label">${intent.label}</span>
+        <span class="handhold-btn-text">Start</span>
+      </button>
+    `).join('');
+
+    return `
+      <div class="handhold-search-container">
+        <label class="handhold-search-label">Ask a question</label>
+        <div class="handhold-input-wrapper">
+          <input 
+            type="text" 
+            class="handhold-search-input" 
+            placeholder="${this.config.widgetPlaceholder}"
+            aria-label="Ask a question"
+          >
+          ${new Button({
+            icon: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M22 2L11 13"></path><path d="M22 2L15 22L11 13L2 9L22 2Z"></path></svg>',
+            variant: ButtonVariant.OUTLINE,
+            size: ButtonSize.ICON,
+            className: 'handhold-send-btn',
+            attributes: { 'aria-label': 'Send' }
+          }).render()}
+        </div>
+      </div>
+      <div class="handhold-intent-menu">
+        <h4 class="handhold-section-title">Page Actions</h4>
+        ${intentsHtml || '<p class="handhold-empty-state">No actions available for this page</p>'}
+        
+        <div class="handhold-divider"></div>
+        
+        ${new Button({
+          text: 'Contact Support',
+          icon: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z"></path></svg>',
+          variant: ButtonVariant.OUTLINE,
+          size: ButtonSize.MEDIUM,
+          className: 'handhold-intent-item handhold-contact-support'
+        }).render()}
+      </div>
+    `;
+  }
+
+  /**
+   * Render loading view
+   */
+  _renderLoading() {
+    return `
+      <div class="handhold-skeleton-container">
+        <div class="handhold-skeleton title"></div>
+        <div class="handhold-skeleton text"></div>
+        <div class="handhold-skeleton text"></div>
+        <div class="handhold-skeleton text short"></div>
+      </div>
+    `;
+  }
+
+  /**
+   * Render guidance view
+   */
+  _renderGuidance() {
+    if (!this.currentGuidance) return '';
+
+    const { steps, current_step, summary, total_steps } = this.currentGuidance;
+    const progress = Math.round(((current_step) / total_steps) * 100);
+
+    const stepsHtml = steps.map((step, index) => {
+      let statusClass = '';
+      if (index < current_step) statusClass = 'completed';
+      else if (index === current_step) statusClass = 'active';
+
+      return `
+        <div class="handhold-step ${statusClass}" data-step-index="${index}">
+          <div class="handhold-step-card">
+            <div class="handhold-step-content">
+              <div class="handhold-step-number">${index < current_step ? '' : index + 1}</div>
+              <div class="handhold-step-text">${step.text}</div>
+            </div>
+            <div class="handhold-step-action handhold-step-actions">
+               ${index === current_step ? `
+                 ${new Button({
+                   text: 'Done',
+                   variant: ButtonVariant.SUCCESS,
+                   size: ButtonSize.SMALL,
+                   attributes: { 'data-action': 'mark-done', 'data-step-index': index }
+                 }).render()}
+                 ${new Button({
+                   text: 'Show UI',
+                   variant: ButtonVariant.PRIMARY,
+                   size: ButtonSize.SMALL,
+                   attributes: { 'data-action': 'show-ui', 'data-show-ui': index, 'data-step-index': index }
+                 }).render()}
+               ` : ''}
+            </div>
+          </div>
+        </div>
+      `;
+    }).join('');
+
+    return `
+      <div class="handhold-guidance">
+        <div class="handhold-progress">
+          <div class="handhold-progress-bar">
+            <div class="handhold-progress-fill" style="width: ${progress}%"></div>
+          </div>
+          <span class="handhold-progress-text">${current_step}/${total_steps}</span>
+        </div>
+        ${summary ? `<div class="handhold-guidance-summary">${summary}</div>` : ''}
+        <div class="handhold-steps-list">
+          ${stepsHtml}
+        </div>
+        <div class="handhold-guidance-actions">
+           ${this.config.agentMode && this.currentGuidance.agent_plan ? new Button({
+             text: 'Do it for me',
+             variant: ButtonVariant.PRIMARY,
+             attributes: { 'data-action': 'do-it-for-me' }
+           }).render() : ''}
+           ${new Button({
+             text: 'Close',
+             variant: ButtonVariant.SECONDARY,
+             attributes: { 'data-action': 'close' }
+           }).render()}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Render the agent run view (H5): goal line, live activity feed, a slot for
+   * Allow/Deny confirm cards, and Stop/Close actions. Agent- and page-derived
+   * strings are ALWAYS inserted with textContent (never innerHTML) — model
+   * output and page text are untrusted.
+   */
+  _renderAgentRun() {
+    return `
+      <div class="handhold-agent">
+        <div class="handhold-agent-goal"></div>
+        <div class="handhold-agent-feed" aria-live="polite"></div>
+        <div class="handhold-agent-confirm-slot"></div>
+        <div class="handhold-guidance-actions">
+           ${new Button({
+             text: 'Stop',
+             variant: ButtonVariant.SECONDARY,
+             size: ButtonSize.SMALL,
+             attributes: { 'data-action': 'agent-stop' }
+           }).render()}
+           ${new Button({
+             text: 'Close',
+             variant: ButtonVariant.SECONDARY,
+             attributes: { 'data-action': 'close' }
+           }).render()}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Render error view
+   */
+  _renderError(message) {
+    return `
+      <div class="handhold-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>
+        <p class="handhold-error-message" style="font-size: 18px; font-weight: 700; color: #0F172A; margin-bottom: 4px; line-height: 1.5;">We're sorry, something went wrong</p>
+        <p style="font-size: 14px; color: #64748B; margin-bottom: 16px; line-height: 1.5; padding: 0 8px;">${message || 'We encountered an issue while trying to pull the definitions of the selected terms please try again.'}</p>
+        ${new Button({
+          text: 'Try again',
+          variant: ButtonVariant.PRIMARY,
+          className: 'handhold-btn-primary',
+          attributes: { 'data-action': 'retry', 'style': 'width: 100%; justify-content: center;' }
+        }).render()}
+      </div>
+    `;
+  }
+
+  /**
+   * Render clarification view
+   */
+  _renderClarification() {
+    const optionsHtml = (this.clarificationOptions || []).map(opt => `
+      <button class="handhold-intent-item" data-intent-key="${opt.key}">
+        ${opt.label}
+      </button>
+    `).join('');
+
+    return `
+      <div class="handhold-clarification">
+        <p class="handhold-clarification-question">${this.clarificationQuestion || 'Did you mean one of these?'}</p>
+        <div class="handhold-clarification-options">
+          ${optionsHtml}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Handle "Show UI" click for a step
+   * @private
+   */
+  _onShowUIClick(stepId, selector) {
+    if (!selector) return;
+    
+    // Check if element exists before starting animation
+    const element = document.querySelector(selector);
+    if (!element) {
+        // Fallback to highlight request which handles "not found" state
+        eventBus.emit('ui:highlight_request', { selector, stepId });
+        return;
+    }
+
+    // Add scanner animation
+    const btn = this.widget.querySelector(`[data-show-ui="${stepId}"]`);
+    if (btn) {
+      // Prevent multiple clicks
+      if (btn.classList.contains('loading')) return;
+      
+      btn.classList.add('loading');
+      const originalText = btn.textContent;
+      btn.textContent = 'Locating...';
+      
+      // Trigger scanning animation via UICoach
+      eventBus.emit('ui:scan_request', { selector });
+      
+      // Simulate scanning delay for effect
+      setTimeout(() => {
+        eventBus.emit('ui:highlight_request', { 
+          selector, 
+          stepId 
+        });
+        
+        // Reset button state
+        btn.classList.remove('loading');
+        btn.textContent = originalText;
+      }, 1000); // Slightly longer for better effect
+    } else {
+        // Fallback if button not found (rare)
+        eventBus.emit('ui:highlight_request', { selector, stepId });
+    }
+  }
+
+  /**
+   * Setup event listeners
+   */
+  _setupEventListeners() {
+    // Header actions
+    const header = this.widget.querySelector('.handhold-widget-header');
+    if (header) {
+       header.addEventListener('click', this._handleHeaderClick);
+    }
+
+    // Delegate event handling for dynamic content
+    this.widget.addEventListener('click', (e) => {
+      // Prevent click from bubbling to document (prevents immediate close)
+      e.stopPropagation();
+
+      // Send button click
+      const sendBtn = e.target.closest('.handhold-send-btn');
+      if (sendBtn) {
+        const input = this.widget.querySelector('.handhold-search-input');
+        if (input) {
+          const query = input.value.trim();
+          if (query) {
+            eventBus.emit('query:submitted', query);
+          }
+        }
+      }
+
+      // Intent item click
+      const intentItem = e.target.closest('.handhold-intent-item');
+      if (intentItem) {
+        const key = intentItem.dataset.intentKey;
+        const index = parseInt(intentItem.dataset.intentIndex, 10);
+        const intent = this.currentIntents[index] || { key };
+        eventBus.emit('intent:selected', intent);
+      }
+
+      // Resolve the action element — handles clicks on inner spans inside Button components
+      const actionEl = e.target.closest('[data-action]');
+      const action = actionEl?.dataset?.action;
+
+      // Retry button
+      if (action === 'retry') {
+        eventBus.emit('help:open');
+      }
+
+      if (action === 'back') {
+        this.showIntentMenu(this.currentIntents);
+      }
+
+      // Show UI button
+      if (action === 'show-ui') {
+        const stepIndex = parseInt(actionEl.dataset.stepIndex, 10);
+        // Find selector from current guidance steps
+        const step = this.currentGuidance?.steps?.[stepIndex];
+        const selector = step?.selector;
+
+        if (selector) {
+            // Call internal handler for animation
+            this._onShowUIClick(stepIndex, selector);
+        } else {
+            // Fallback just in case
+            eventBus.emit('step:show_ui', { stepIndex });
+        }
+      }
+
+      // Mark Done button
+      if (action === 'mark-done') {
+        eventBus.emit('step:done');
+      }
+
+      // "Do it for me" (H5): switch to the agent view, then ask AgentMode to run
+      if (action === 'do-it-for-me') {
+        const plan = this.currentGuidance?.agent_plan;
+        if (plan) {
+          this.showAgentRun(plan);
+          eventBus.emit('agent:start', plan);
+        }
+      }
+
+      // Stop a running agent (cooperative)
+      if (action === 'agent-stop') {
+        eventBus.emit('agent:stop');
+      }
+
+      // Close button (bottom)
+      if (action === 'close') {
+        this.hide();
+      }
+
+    });
+
+    // Search input
+    this.widget.addEventListener('keydown', (e) => {
+      if (e.target.classList.contains('handhold-search-input') && e.key === 'Enter') {
+        const query = e.target.value.trim();
+        if (query) {
+          eventBus.emit('query:submitted', query);
+        }
+      }
+    });
+
+    // Click outside to close
+    document.addEventListener('click', (e) => {
+      // Ignore if element was removed from DOM (e.g. by view change)
+      if (!e.target.isConnected) return;
+
+      // Check if click is inside any UICoach element (e.g. tooltip, highlight)
+      const isUICoachElement = e.target.closest('.handhold-step-tooltip') || 
+                               e.target.closest('.handhold-highlight') || 
+                               e.target.closest('.handhold-arrow');
+
+      // If in guidance mode, do NOT close on outside click (user needs to interact with app)
+      // Also don't close if interacting with UICoach elements
+      if (this.currentView === 'guidance' || isUICoachElement) return;
+
+      if (this.isOpen && !this.container.contains(e.target)) {
+        this.hide();
+      }
+    });
+
+    // Escape key to close
+    document.addEventListener('keydown', (e) => {
+      if (this.isOpen && e.key === 'Escape') {
+        this.hide();
+      }
+    });
+  }
+
+
+
+  /**
+   * Handle header clicks (Minimize/Exit)
+   */
+  _handleHeaderClick(e) {
+     e.stopPropagation();
+
+     // Exit button — actually ends the workflow (hide() only minimizes now).
+     if (e.target.closest('.handhold-widget-exit')) {
+        eventBus.emit('session:close');
+        return;
+     }
+
+     // Minimize button
+     if (e.target.closest('.handhold-widget-minimize')) {
+        this.collapse();
+        return;
+     }
+
+     // Click on header itself (toggle collapse)
+     // Only if collapsed, expand it. If expanded, do nothing (unless we want double-click to collapse?)
+     if (this.isCollapsed) {
+        this.expand();
+     }
+  }
+
+  /**
+   * Collapse the widget
+   */
+  collapse() {
+     this.isCollapsed = true;
+     this.widget.classList.add('collapsed');
+     // Change minimize icon to expand
+     const minBtn = this.widget.querySelector('.handhold-widget-minimize');
+     if (minBtn) minBtn.innerHTML = `
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <polyline points="18 15 12 9 6 15"></polyline>
+        </svg>
+     `;
+  }
+
+  /**
+   * Expand the widget
+   */
+  expand() {
+     this.isCollapsed = false;
+     this.widget.classList.remove('collapsed');
+     // Restore minimize icon
+     const minBtn = this.widget.querySelector('.handhold-widget-minimize');
+     if (minBtn) minBtn.innerHTML = `
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <line x1="5" y1="12" x2="19" y2="12"></line>
+        </svg>
+     `;
+  }
+
+  /**
+   * Update widget body content
+   */
+  _updateBody() {
+    const body = this.widget.querySelector('.handhold-widget-body');
+    if (body) {
+      body.innerHTML = this._renderViewContent();
+    }
+    this._syncState();
+  }
+
+  _escapeHtml(value) {
+    return String(value)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  // ============================================
+  // Public Methods
+  // ============================================
+
+  /**
+   * Toggle widget visibility
+   */
+  toggle() {
+    if (this.isOpen) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  /**
+   * Show the widget
+   */
+  show() {
+    if (this.isOpen) return;
+
+    this.isOpen = true;
+    this.widget.classList.add('open');
+
+    if (this.helpButton) {
+      this.helpButton.classList.add('hidden');
+    }
+
+    this._syncState();
+    eventBus.emit('help:open');
+  }
+
+  /**
+   * Hide the widget
+   */
+  hide() {
+    if (!this.isOpen) return;
+
+    this.isOpen = false;
+    this.widget.classList.remove('open');
+
+    if (this.helpButton) {
+      this.helpButton.classList.remove('hidden');
+    }
+
+    // hide() is now purely visual (a "minimize"): it does NOT end the workflow.
+    // Closing the panel keeps the session alive so reopening resumes it. The
+    // session is ended only by an explicit exit (the widget's exit button /
+    // HandHold.exitWorkflow()), so a stray outside-click/Escape no longer
+    // discards a workflow the user is midway through.
+    this._syncState();
+  }
+
+  /**
+   * Reset the panel back to a clean menu state and clear any workflow data so
+   * stale guidance can't be re-rendered or resumed after the session ends.
+   * Called by the SDK when a workflow is exited/closed for good.
+   */
+  resetView() {
+    this.currentView = 'menu';
+    this.currentGuidance = null;
+    this.errorMessage = null;
+    this.clarificationQuestion = null;
+    this.clarificationOptions = null;
+    this.completionLabel = null;
+    this._syncState();
+  }
+
+  /**
+   * Show intent menu with intents
+   * @param {Array} intents - Array of intent objects
+   */
+  showIntentMenu(intents) {
+    this.currentView = 'menu';
+    this.currentIntents = intents || [];
+    this._updateBody();
+  }
+
+  /**
+   * Show loading state
+   */
+  showLoading() {
+    this.currentView = 'loading';
+    this._updateBody();
+  }
+
+  /**
+   * Show guidance steps
+   * @param {Object} guidance - Guidance object with steps
+   */
+  showGuidanceTooltip(guidance) {
+    this.currentView = 'guidance';
+    this.currentGuidance = guidance;
+    this._updateBody();
+  }
+
+  // ============================================
+  // Agent mode UI (H5)
+  // ============================================
+  // Everything below renders agent-/page-derived strings via textContent —
+  // model output and page text must never become HTML.
+
+  /**
+   * Switch to the agent run view for a plan.
+   * @param {Object} plan - agent_plan ({goal, hints, target_page_path})
+   */
+  showAgentRun(plan) {
+    this.currentView = 'agent';
+    this.currentAgentPlan = plan || null;
+    this._updateBody();
+    const goalEl = this.widget.querySelector('.handhold-agent-goal');
+    if (goalEl) goalEl.textContent = plan?.goal || '';
+  }
+
+  /** The activity feed element, creating the agent view if needed. */
+  _agentFeed() {
+    let feed = this.widget.querySelector('.handhold-agent-feed');
+    if (!feed) {
+      this.showAgentRun(this.currentAgentPlan);
+      feed = this.widget.querySelector('.handhold-agent-feed');
+    }
+    return feed;
+  }
+
+  /** One human-readable line per engine activity event. */
+  _agentActivityText(ev) {
+    switch (ev?.type) {
+      case 'run_start':
+        return `Starting: ${ev.goal || ''}`;
+      case 'thinking':
+        return `Thinking… (step ${ev.step})`;
+      case 'executing':
+        return `▶ ${ev.nextGoal || ev.actionName || 'Working…'}`;
+      case 'executed':
+        return ev.resultMessage || '';
+      case 'done':
+        return ev.success === false ? '⚠ Task ended' : '✓ Task complete';
+      case 'resuming':
+        return `Resuming: ${ev.task || ''}`;
+      case 'checkpoint_discarded':
+        return `Agent checkpoint discarded: ${ev.reason || ''}`;
+      case 'info':
+        return ev.message || '';
+      default:
+        return ev?.message || ev?.resultMessage || '';
+    }
+  }
+
+  /**
+   * Append an engine activity line to the feed (textContent only).
+   * @param {Object} ev - activity event from AgentMode
+   */
+  addAgentActivity(ev) {
+    if (!this.widget) return;
+    const feed = this._agentFeed();
+    if (!feed) return;
+    const text = this._agentActivityText(ev);
+    if (!text) return;
+    const line = document.createElement('div');
+    line.className = `handhold-agent-line handhold-agent-${ev?.type || 'event'}`;
+    line.textContent = text;
+    feed.appendChild(line);
+    feed.scrollTop = feed.scrollHeight;
+  }
+
+  /**
+   * Render a fail-closed Allow/Deny card for a sensitive action. `respond` is
+   * AgentMode's resolver: only an explicit Allow click passes true; the card
+   * is one-shot (buttons removed after the first decision).
+   * @param {Object} pending - {name, input, reason} from PolicyGuard
+   * @param {(allowed:boolean)=>void} respond
+   */
+  showAgentConfirm(pending, respond) {
+    if (!this.widget) return;
+    this._agentFeed(); // ensure the agent view exists
+    const slot = this.widget.querySelector('.handhold-agent-confirm-slot');
+    if (!slot) return;
+
+    const card = document.createElement('div');
+    card.className = 'handhold-agent-confirm';
+
+    const title = document.createElement('div');
+    title.className = 'handhold-agent-confirm-title';
+    title.textContent = 'Approval needed';
+
+    const reason = document.createElement('div');
+    reason.className = 'handhold-agent-confirm-reason';
+    reason.textContent = pending?.reason || pending?.name || 'Sensitive action';
+
+    const buttons = document.createElement('div');
+    buttons.className = 'handhold-agent-confirm-buttons';
+
+    let decided = false;
+    const decide = (allowed) => {
+      if (decided) return;
+      decided = true;
+      buttons.remove(); // one-shot: no double decisions
+      const note = document.createElement('div');
+      note.className = 'handhold-agent-confirm-decision';
+      note.textContent = allowed ? 'Allowed' : 'Denied';
+      card.appendChild(note);
+      try {
+        respond(allowed === true);
+      } catch (e) {
+        /* respond must never throw into the UI */
+      }
+    };
+
+    const allowBtn = document.createElement('button');
+    allowBtn.type = 'button';
+    allowBtn.dataset.agentConfirm = 'allow';
+    allowBtn.className = 'handhold-btn handhold-btn-primary handhold-btn-small';
+    allowBtn.textContent = 'Allow';
+    allowBtn.addEventListener('click', () => decide(true));
+
+    const denyBtn = document.createElement('button');
+    denyBtn.type = 'button';
+    denyBtn.dataset.agentConfirm = 'deny';
+    denyBtn.className = 'handhold-btn handhold-btn-secondary handhold-btn-small';
+    denyBtn.textContent = 'Deny';
+    denyBtn.addEventListener('click', () => decide(false));
+
+    buttons.appendChild(allowBtn);
+    buttons.appendChild(denyBtn);
+    card.appendChild(title);
+    card.appendChild(reason);
+    card.appendChild(buttons);
+    slot.appendChild(card);
+  }
+
+  /**
+   * Render an inline question card for the engine's ask_user channel.
+   * @param {string} question
+   * @param {(answer:string)=>void} respond
+   */
+  showAgentAsk(question, respond) {
+    if (!this.widget) return;
+    this._agentFeed();
+    const slot = this.widget.querySelector('.handhold-agent-confirm-slot');
+    if (!slot) return;
+
+    const card = document.createElement('div');
+    card.className = 'handhold-agent-ask';
+
+    const label = document.createElement('div');
+    label.className = 'handhold-agent-ask-question';
+    label.textContent = question || 'The agent has a question.';
+
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.className = 'handhold-agent-ask-input';
+
+    let sent = false;
+    const send = () => {
+      if (sent) return;
+      sent = true;
+      const answer = input.value;
+      card.remove();
+      try {
+        respond(answer);
+      } catch (e) {
+        /* respond must never throw into the UI */
+      }
+    };
+
+    const sendBtn = document.createElement('button');
+    sendBtn.type = 'button';
+    sendBtn.className = 'handhold-btn handhold-btn-primary handhold-btn-small';
+    sendBtn.textContent = 'Send';
+    sendBtn.addEventListener('click', send);
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') send();
+    });
+
+    card.appendChild(label);
+    card.appendChild(input);
+    card.appendChild(sendBtn);
+    slot.appendChild(card);
+    input.focus();
+  }
+
+  /**
+   * Final run report line.
+   * @param {Object} result - {success, text, steps}
+   */
+  showAgentDone(result) {
+    if (!this.widget || !result) return;
+    const feed = this._agentFeed();
+    if (!feed) return;
+    const line = document.createElement('div');
+    line.className = `handhold-agent-line handhold-agent-report ${result.success ? 'success' : 'failure'}`;
+    line.textContent = `${result.success ? '✓' : '⚠'} ${result.text || ''}`;
+    feed.appendChild(line);
+    feed.scrollTop = feed.scrollHeight;
+  }
+
+  /**
+   * Update guidance (step progress)
+   * @param {Object} session - Updated session
+   */
+  updateTooltip(session) {
+    if (this.currentGuidance) {
+      this.currentGuidance.current_step = session.current_step;
+      this._updateBody();
+    }
+  }
+
+  /**
+   * Show error message
+   * @param {string} message - Error message
+   */
+  showError(message) {
+    this.currentView = 'error';
+    this.errorMessage = message;
+    this._updateBody();
+  }
+
+  /**
+   * Show clarification question
+   * @param {string} question - Clarification question
+   * @param {Array} options - Intent options
+   */
+  showClarification(question, options) {
+    this.currentView = 'clarification';
+    this.clarificationQuestion = question;
+    this.clarificationOptions = options;
+    this._updateBody();
+  }
+
+  showArticle(article, query) {
+    this.currentView = 'article';
+    this.currentArticle = article;
+    this.currentQuery = query || '';
+    this._updateBody();
+  }
+
+  /**
+   * Show text-only guidance (when element not found)
+   * @param {Object} session - Full session object or steps info
+   * @param {string} fallbackMessage - Additional message
+   */
+  showTextOnlyGuidance(session, fallbackMessage) {
+    // If session is just a string (legacy call), wrap it
+    if (typeof session === 'string') {
+      const text = session;
+      this.showGuidanceTooltip({
+        steps: [{ text, order: 1 }],
+        current_step: 0,
+        total_steps: 1,
+        summary: `<div class="handhold-alert handhold-alert-warning"><span class="handhold-alert-title">Element not found</span>${fallbackMessage}</div>`,
+      });
+      return;
+    }
+
+    this.showGuidanceTooltip({
+      steps: session.steps,
+      current_step: session.current_step,
+      total_steps: session.steps.length,
+      summary: `<div class="handhold-alert handhold-alert-warning"><span class="handhold-alert-title">Element not found</span>${fallbackMessage}</div>`,
+    });
+  }
+
+  /**
+   * Show completion screen when all guidance steps are done
+   * @param {string} intentLabel - The intent the user just completed
+   */
+  showCompletion(intentLabel) {
+    this.currentView = 'completion';
+    this.completionLabel = intentLabel;
+    this._syncState();
+    const body = this.widget.querySelector('.handhold-widget-body');
+    if (!body) return;
+
+    body.innerHTML = `
+      <div class="handhold-completion">
+        <div class="handhold-completion-icon">
+          <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"></path>
+            <polyline points="22 4 12 14.01 9 11.01"></polyline>
+          </svg>
+        </div>
+        <h3 class="handhold-completion-title">You're all done!</h3>
+        <p class="handhold-completion-message">
+          ${intentLabel ? `You've successfully completed <strong>${intentLabel}</strong>.` : "You've completed all the steps."}
+        </p>
+        ${new Button({
+          text: 'Got it',
+          variant: ButtonVariant.PRIMARY,
+          size: ButtonSize.MEDIUM,
+          attributes: { 'data-action': 'close' }
+        }).render()}
+      </div>
+    `;
+  }
+
+  /**
+   * Show success message
+   * @param {string} message - Success message
+   */
+  showSuccess(message) {
+    this.showCompletion(message);
+  }
+
+  /**
+   * Show navigation suggestion
+   * @param {Object} article - KB article
+   */
+  showNavigationSuggestion(article) {
+    const body = this.widget.querySelector('.handhold-widget-body');
+    if (body) {
+      body.innerHTML = `
+        <div class="handhold-clarification">
+          <p class="handhold-clarification-question">
+            Found a guide that might help:
+          </p>
+          <p class="handhold-suggestion-title">${article.title}</p>
+          <p class="handhold-suggestion-excerpt">${article.excerpt || ''}</p>
+          ${article.route_pattern ? `
+            ${new Button({
+              text: 'Go to that page',
+              variant: ButtonVariant.PRIMARY,
+              attributes: { 'onclick': `window.location.href='${article.route_pattern}'` }
+            }).render()}
+          ` : ''}
+        </div>
+      `;
+    }
+  }
+
+  /**
+   * Confirm if user wants to continue session
+   * @param {string} message - Confirmation message
+   * @returns {Promise<boolean>}
+   */
+  confirmContinueSession(message) {
+    // The confirm must open the panel (e.g. on boot restore) — mirror isOpen too.
+    this.isOpen = true;
+    this.currentView = 'confirm';
+    this._syncState({ confirm: { message } });
+    return new Promise((resolve) => {
+      // Resolve on EITHER this widget's own buttons (standalone) OR an
+      // hh:confirm:response event from a host UI (the React demo answers there).
+      let settled = false;
+      const onEvent = (answer) => finish(!!answer);
+      const finish = (answer) => {
+        if (settled) return;
+        settled = true;
+        eventBus.off('hh:confirm:response', onEvent);
+        resolve(answer);
+      };
+      eventBus.on('hh:confirm:response', onEvent);
+
+      const body = this.widget.querySelector('.handhold-widget-body');
+      if (body) {
+        body.innerHTML = `
+          <div class="handhold-clarification">
+            <p class="handhold-clarification-question">${message}</p>
+            <div class="handhold-confirm-actions">
+              ${new Button({
+                text: 'No, start over',
+                variant: ButtonVariant.SECONDARY,
+                attributes: { 'data-confirm': 'no' }
+              }).render()}
+              ${new Button({
+                text: 'Yes, continue',
+                variant: ButtonVariant.PRIMARY,
+                attributes: { 'data-confirm': 'yes' }
+              }).render()}
+            </div>
+          </div>
+        `;
+
+        const handleClick = (e) => {
+          if (e.target.dataset.confirm) {
+            body.removeEventListener('click', handleClick);
+            finish(e.target.dataset.confirm === 'yes');
+          }
+        };
+
+        body.addEventListener('click', handleClick);
+      }
+    });
+  }
+
+  /**
+   * Destroy the widget
+   */
+  destroy() {
+    if (this.container) {
+      this.container.remove();
+      this.container = null;
+      this.widget = null;
+      this.helpButton = null;
+    }
+
+    // Remove styles
+    const styles = document.getElementById('handhold-theme-styles');
+    if (styles) {
+      styles.remove();
+    }
+  }
+}
+
+export default HelpWidget;