handhold-sdk 1.0.0

package/src/HandHold.js

@@ -0,0 +1,1599 @@
+/**
+ * Hand Hold SDK - Main Orchestrator Class
+ * 
+ * Provides context-aware, in-app help by combining:
+ * - Intent menu inferred from current page UI
+ * - Conversational fallback for free-text questions
+ * - Visual UI guidance with element highlighting
+ * - Multi-page workflow tracking
+ * 
+ * @version 1.0.0
+ */
+
+import Config from './core/Config.js';
+import { Logger } from './utils/Logger.js';
+import EventBus from './utils/eventBus.js';
+import APIClient from './api/APIClient.js';
+import PageObserver from './observers/PageObserver.js';
+import IntentExtractor from './intent/IntentExtractor.js';
+import SessionManager from './session/SessionManager.js';
+import HelpWidget from './ui/HelpWidget.js';
+import UICoach from './ui/UICoach.js';
+import AgentMode from './agent-mode/AgentMode.js';
+import UiState from './core/UiState.js';
+import EVENTS from './events.js';
+import html2canvas from 'html2canvas';
+
+class HandHold {
+  constructor() {
+    // Core components (initialized on init())
+    this.config = null;
+    this.logger = null;
+    this.apiClient = null;
+    this.pageObserver = null;
+    this.sessionManager = null;
+    this.helpWidget = null;
+    this.uiCoach = null;
+    this.agentMode = null;
+    // Single source of truth for the widget UI (Phase 2.1). Host renderers
+    // subscribe via HandHold.subscribe()/getState(); the legacy widget mirrors
+    // its view changes into it (HelpWidget._syncState).
+    this.uiState = new UiState();
+    // Bound so a host can pass them straight to useSyncExternalStore.
+    this.subscribe = this.subscribe.bind(this);
+    this.getState = this.getState.bind(this);
+
+    // State
+    this.initialized = false;
+    this.currentIntents = [];
+    this.isUpdating = false;
+    this.isMatchingStep = false;
+    this.lastStepAdvanceTime = 0;
+
+    // Host-agnostic step-completion detection. We attach a one-shot interaction
+    // listener to the CURRENT step's real target element so a step advances when
+    // the user actually performs the action — in ANY host, including one that
+    // renders its own UI (and therefore suppresses the SDK's own overlay). This
+    // is the single source of auto-advance; the visual highlight no longer
+    // carries its own onClick (which only fired when the SDK drew the overlay
+    // and skipped the first step entirely).
+    this._watchedEl = null;
+    this._watchHandlers = null;
+    // Timestamp of the last navigation-type step completion. Lets
+    // _onNavigationChanged tell an EXPECTED step navigation (clicked the
+    // highlighted "Click X" element) from the user wandering off (which prompts
+    // to keep/exit the workflow).
+    this._stepNavAt = 0;
+  }
+
+  /**
+   * Initialize the SDK
+   * @param {Object} options - Configuration options
+   * @param {string} options.apiKey - API key for authentication (required)
+   * @param {string} options.baseUrl - Backend API base URL (required)
+   * @param {string} [options.theme='light'] - UI theme ('light' or 'dark')
+   * @param {string} [options.position='bottom-right'] - Widget position
+   * @param {string} [options.primaryColor='#2196F3'] - Primary color
+   * @param {number} [options.minHighlightConfidence=0.85] - Min confidence for highlighting
+   * @param {number} [options.sessionInactivityTimeout=600000] - Session timeout (ms)
+   * @param {boolean} [options.enableMultiPageTracking=true] - Enable multi-page flows
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   * @returns {Promise<void>}
+   */
+  async init(options) {
+    if (this.initialized) {
+      console.warn('[HandHold] Already initialized. Call destroy() first to reinitialize.');
+      return;
+    }
+
+    try {
+      // Initialize configuration
+      this.config = new Config(options);
+      
+      // Initialize logger
+      this.logger = new Logger({
+        prefix: 'HandHold',
+        level: this.config.get('logLevel'),
+        enabled: this.config.get('debug')
+      });
+      
+      this.logger.info('Initializing Hand Hold SDK...');
+      
+      // Initialize API client
+      this.apiClient = new APIClient(this.config);
+      
+      // Initialize page observer
+      this.pageObserver = new PageObserver(this.config);
+      
+      // Initialize session manager
+      this.sessionManager = new SessionManager(this.config);
+      
+      // Initialize UI coach
+      this.uiCoach = new UICoach(this.config);
+      
+      // Initialize help widget and wire it to the single UI-state store.
+      this.helpWidget = new HelpWidget(this.config);
+      this.helpWidget.attachState(this.uiState);
+      // Re-broadcast state changes as a single event for any event-based consumer.
+      this.uiState.subscribe((snapshot) => EventBus.emit(EVENTS.STATE_CHANGED, snapshot));
+
+      // Initialize agent mode (H5) — feature-flagged, off by default.
+      // "Show me"/"Explain" behavior is untouched when disabled.
+      if (this.config.get('agentMode')) {
+        this.agentMode = new AgentMode({
+          config: this.config,
+          eventBus: EventBus,
+          sessionManager: this.sessionManager
+        });
+      }
+
+      // Setup event listeners
+      this._setupEventListeners();
+      
+      // Start page observation
+      this.pageObserver.observe();
+      
+      // Render help widget first (needed for session restoration)
+      this.helpWidget.render();
+      this.uiCoach.enableSelectionExplain();
+      
+      // Restore agent/guidance state. A host that renders the widget itself
+      // (React demo) sets `deferRestore` and calls restoreSession() AFTER it has
+      // patched its renderer — otherwise the session-restore "continue?" confirm
+      // is drawn by the unpatched (and about-to-be-hidden) legacy widget and
+      // init blocks on it (Phase 1.4).
+      if (!this.config.get('deferRestore')) {
+        await this.restoreSession();
+      }
+
+      this.initialized = true;
+      this.logger.info('Hand Hold SDK initialized successfully');
+
+      // Emit ready event
+      EventBus.emit('handhold:ready');
+
+    } catch (error) {
+      console.error('[HandHold] Initialization failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Restore agent/guidance state after boot. Separated from init() so a host
+   * that owns the widget rendering can patch its renderer first (deferRestore),
+   * then call this so the confirm is drawn by the host UI, not the legacy widget.
+   *
+   * Cross-page agent resume (H7) runs BEFORE the "Show me" session restore and
+   * takes precedence: if a "Do it for me" run was mid-flight when the page
+   * full-reloaded, resume it and SKIP the guidance-session prompt (declining it
+   * would end the session and delete the agent checkpoint). The resumed run
+   * continues in the background; boot does not block on it.
+   * @returns {Promise<void>}
+   */
+  async restoreSession() {
+    let agentResumed = false;
+    if (this.agentMode) {
+      try {
+        const r = await this.agentMode.resumeIfCheckpointed();
+        agentResumed = !!(r && r.resumed);
+      } catch (error) {
+        this.logger.error('Agent resume failed:', error);
+      }
+    }
+    if (!agentResumed) {
+      await this._restoreSession();
+    }
+  }
+
+  /**
+   * Setup internal event listeners
+   * @private
+   */
+  _setupEventListeners() {
+    // Help button clicked
+    EventBus.on('help:open', () => this._onHelpOpen());
+    
+    // Intent selected from menu
+    EventBus.on('intent:selected', (intent) => this._onIntentSelected(intent));
+    
+    // Free text query submitted
+    EventBus.on('query:submitted', (query) => this._onQuerySubmitted(query));
+    
+    // Navigation changed
+    EventBus.on('navigation:changed', (data) => this._onNavigationChanged(data));
+    
+    // Step marked as done
+    EventBus.on('step:done', () => this._onStepDone());
+    
+    // Step skipped
+    EventBus.on('step:skip', () => this._onStepSkip());
+    
+    // Session close requested (end the workflow)
+    EventBus.on('session:close', () => this._onSessionClose());
+
+    // Minimize requested (hide panel, KEEP the workflow so reopening resumes it)
+    EventBus.on(EVENTS.HELP_MINIMIZE, () => this._onMinimize());
+
+    // Re-show the current step's on-page hint (re-resolve + re-highlight + re-arm)
+    EventBus.on(EVENTS.HELP_SHOW_HINT, () => this._showCurrentStep());
+    
+    // DOM changes (debounced by PageObserver)
+    EventBus.on('page:dom_changed', () => this._onDomChanged());
+
+    // Show UI for specific step
+    EventBus.on('step:show_ui', (data) => this._onShowUI(data));
+
+    EventBus.on('selection:explain', (data) => this._onSelectionExplain(data));
+
+    // Handle highlight request (emitted by HelpWidget when selector is already known)
+    EventBus.on('ui:highlight_request', async (data) => {
+      const { selector, stepId } = data;
+      const session = this.sessionManager.getActiveSession();
+      const step = session?.steps?.[stepId];
+
+      // await the real outcome (Phase 5.3) — resolves false if the element is
+      // missing OR detaches before the highlight builds, so the fallback fires.
+      // No onClick here: completion detection is owned by the host-agnostic
+      // watcher (_watchStepElement) so it works even when a host suppresses the
+      // SDK overlay, and clicking never advances twice.
+      const found = await this.uiCoach.highlightElement(selector, {
+        message: step?.text,
+        showArrow: true,
+        showTooltip: true,
+        showDoneButton: true,
+      });
+
+      if (found) {
+        this._watchStepElement(document.querySelector(selector), step);
+      } else {
+        // If selector is stale and element wasn't found, fall back to API-based matching
+        EventBus.emit('step:show_ui', { stepIndex: stepId });
+      }
+    });
+
+    // ---- Agent mode (H5): engine events -> widget UI + best-effort spotlight ----
+    // AgentMode itself listens for 'agent:start' (emitted by the widget's
+    // "Do it for me" button) and 'agent:stop'. These listeners only render.
+    EventBus.on('agent:activity', (ev) => {
+      if (!this.agentMode) return;
+      this.helpWidget.addAgentActivity(ev);
+      // Reserve space so the fixed built-in panel doesn't occlude page content
+      // from the agent (any site). run_start (fresh) or resuming (after reload).
+      if (ev?.type === 'run_start' || ev?.type === 'resuming') {
+        this._setAgentReflow(true);
+      }
+      if (ev?.type === 'executing' && ev.targetSelector) {
+        // Spotlight what the agent is about to act on (best-effort: a stale
+        // selector just logs a warning inside UICoach).
+        this.uiCoach.highlightElement(ev.targetSelector, {
+          message: ev.nextGoal || 'Working…',
+          showArrow: true,
+          showTooltip: Boolean(ev.nextGoal),
+          showDoneButton: false
+        });
+      }
+    });
+
+    EventBus.on('agent:confirm', ({ pending, respond }) => {
+      if (!this.agentMode) return;
+      this.helpWidget.showAgentConfirm(pending, respond);
+    });
+
+    EventBus.on('agent:ask', ({ question, respond }) => {
+      if (!this.agentMode) return;
+      this.helpWidget.showAgentAsk(question, respond);
+    });
+
+    EventBus.on('agent:done', (result) => {
+      if (!this.agentMode) return;
+      this.uiCoach.clearHighlight();
+      this.helpWidget.showAgentDone(result);
+      this._setAgentReflow(false);
+    });
+  }
+
+  /**
+   * Agent-mode reflow (works on ANY site). The built-in widget is a fixed
+   * right-side panel; during an agent run it visually OCCLUDES page content, and
+   * the agent's DOM engine treats covered elements as not-visible
+   * (elementFromPoint), so it can't see/click them. Reserve space on the right
+   * (a margin on <html>) so the page reflows left and every element stays
+   * visible — released when the run ends.
+   *
+   * Skipped when the built-in widget isn't visible: a custom host that hides it
+   * (e.g. the React demo) owns its own layout and docks its own panel.
+   * @param {boolean} active
+   * @private
+   */
+  _setAgentReflow(active) {
+    if (typeof document === 'undefined') return;
+    const html = document.documentElement;
+
+    if (!active) {
+      html.style.transition = 'margin-right 0.3s ease';
+      html.style.removeProperty('margin-right');
+      return;
+    }
+
+    const container = this.helpWidget?.container;
+    if (!container) return;
+    // A host that hides the built-in widget handles its own layout.
+    const computed = (typeof window !== 'undefined' && window.getComputedStyle)
+      ? window.getComputedStyle(container)
+      : null;
+    if (container.style.display === 'none' || (computed && computed.display === 'none')) {
+      return;
+    }
+
+    // Reserve the panel width (.handhold-widget is 380px) + a gap. Measure when
+    // possible; fall back to the known CSS width (jsdom returns 0 for layout).
+    const panel = container.querySelector('.handhold-widget');
+    const measured = panel && panel.getBoundingClientRect ? panel.getBoundingClientRect().width : 0;
+    const reserve = Math.ceil(measured || 380) + 40;
+    html.style.transition = 'margin-right 0.3s ease';
+    html.style.marginRight = `${reserve}px`;
+  }
+
+  /**
+   * Handle show UI request for a step
+   * @private
+   * @param {Object} data - { stepIndex }
+   */
+  async _onShowUI(data) {
+    const { stepIndex } = data;
+    this.logger.debug('Show UI requested for step:', stepIndex);
+    
+    const session = this.sessionManager.getActiveSession();
+    if (!session) return;
+    
+    const step = session.steps[stepIndex];
+    if (!step) return;
+    
+    try {
+      this.helpWidget.showLoading();
+      
+      // Scan page
+      const pageContext = this.pageObserver.scanPage();
+      
+      // Request matching for this specific step
+      const matchResult = await this.apiClient.matchElement({
+        step_description: step.text,
+        original_selector: step.selector,
+        route: pageContext.route,
+        ui_elements: pageContext.ui_elements,
+        session_id: session.session_id,
+        intent: session.intent,
+        steps: session.steps,
+        current_step_index: stepIndex
+      });
+      
+      this.helpWidget.showGuidanceTooltip(session); // Restore view
+      
+      if (matchResult.found && matchResult.confidence >= this.config.get('minHighlightConfidence')) {
+         // Update step with new selector
+         this.sessionManager.updateStep(stepIndex, {
+            selector: matchResult.selector,
+            confidence: matchResult.confidence,
+            match_type: matchResult.match_type
+         });
+         
+         // Highlight (visual only). Detection is owned by the watcher below.
+         this.uiCoach.highlightElement(matchResult.selector, {
+            message: step.text,
+            showArrow: true,
+            showTooltip: true,
+            showDoneButton: true,
+         });
+         this._watchStepElement(document.querySelector(matchResult.selector), step);
+
+      } else {
+         this.uiCoach.clearHighlight();
+         this._unwatchStepElement();
+         this.helpWidget.showError(`Could not find element for: "${step.text}" on this page.`);
+      }
+      
+    } catch (error) {
+      this.logger.error('Error showing UI:', error);
+      this.helpWidget.showGuidanceTooltip(session);
+      this.helpWidget.showError('Failed to locate element.');
+    }
+  }
+
+  /**
+   * Handle help button click
+   * @private
+   */
+  async _onHelpOpen() {
+    this.logger.debug('Help opened');
+
+    // Restore ONLY an active session. A completed/ended session lingering in
+    // storage must not reappear as a live workflow (Phase 1.3) — end it and
+    // fall through to a fresh intent menu.
+    const session = this.sessionManager.getActiveSession();
+    if (session && session.status === 'active') {
+       // Resume the workflow where it was left off (e.g. after Close = minimize)
+       // and re-arm on-page detection + the highlight for the current step.
+       this.helpWidget.showGuidanceTooltip(session);
+       this._showCurrentStep();
+       return;
+    }
+    if (session) {
+      this.sessionManager.endSession('completed');
+    }
+
+    try {
+      // Scan current page
+      const pageContext = this.pageObserver.scanPage();
+      this.logger.debug('Page scanned:', pageContext);
+
+      // Extract intents (client-side, instant)
+      this.currentIntents = IntentExtractor.extract(
+        pageContext.ui_elements,
+        pageContext.route,
+        { maxIntents: this.config.get('maxIntents') }
+      );
+
+      this.logger.debug('Intents extracted:', this.currentIntents);
+
+      // Show intent menu
+      this.helpWidget.showIntentMenu(this.currentIntents);
+
+    } catch (error) {
+      this.logger.error('Error opening help:', error);
+      this.helpWidget.showError('Failed to load help. Please try again.');
+    }
+  }
+
+  /**
+   * Handle intent selection
+   * @private
+   * @param {Object} intent - Selected intent
+   */
+  async _onIntentSelected(intent) {
+    this.logger.debug('Intent selected:', intent);
+    
+    try {
+      this.helpWidget.showLoading();
+      
+      // Get page context and UI elements
+      const pageContext = this.pageObserver.scanPage();
+      
+      // Capture screenshot for visual context
+      const screenshot = await this._captureScreenshot();
+      
+      // Generate or get session ID
+      const sessionId = this.sessionManager.getSessionId();
+      
+      // Request guidance from backend
+      const guidance = await this.apiClient.getGuidance({
+        intent: intent.key,
+        route: pageContext.route,
+        page_context: {
+          route: pageContext.route,
+          title: pageContext.title,
+          headings: pageContext.headings || []
+        },
+        ui_elements: pageContext.ui_elements,
+        session_id: sessionId,
+        screenshot: screenshot
+      });
+      
+      this.logger.debug('Guidance received:', guidance);
+      
+      // Start session
+      this.sessionManager.startSession({
+        session_id: guidance.session_id, // Use backend-provided session ID
+        intent: intent.key,
+        intent_label: intent.label,
+        steps: guidance.steps,
+        original_route: pageContext.route,
+        summary: guidance.summary
+      });
+      
+      // Show guidance tooltip
+      this.helpWidget.showGuidanceTooltip(guidance);
+
+      // Resolve + highlight + ARM completion detection for the first step. This
+      // was previously skipped ("just show the list"), which is why doing the
+      // first action never advanced it — nothing was listening on the target
+      // element. Now every step, including the first, is watched.
+      this._showCurrentStep();
+
+    } catch (error) {
+      this.logger.error('Error getting guidance:', error);
+      
+      if (error.status === 404) {
+        this.helpWidget.showError(
+          'No help article found for this action. Please contact support.'
+        );
+      } else {
+        this.helpWidget.showError(
+          'Failed to load guidance. Please try again or contact support.'
+        );
+      }
+    }
+  }
+
+  /**
+   * Handle free text query submission
+   * @private
+   * @param {string} query - User query
+   */
+  async _onQuerySubmitted(query) {
+    this.logger.debug('Query submitted:', query);
+    
+    try {
+      this.helpWidget.showLoading();
+      
+      const pageContext = this.pageObserver.scanPage();
+      
+      // Get available intents for this page
+      const availableIntents = this.currentIntents.length > 0
+        ? this.currentIntents.map(i => i.key)
+        : IntentExtractor.extract(pageContext.ui_elements, pageContext.route)
+            .map(i => i.key);
+      
+      // Try to match query to existing intents first (client-side)
+      const localMatch = IntentExtractor.matchQueryToIntent(query, this.currentIntents);
+      
+      if (localMatch && localMatch.confidence >= 0.8) {
+        // Good local match, use it directly
+        this.logger.debug('Local intent match:', localMatch);
+        this._onIntentSelected(localMatch);
+        return;
+      }
+      
+      // Capture screenshot for visual context
+      const screenshot = await this._captureScreenshot();
+
+      // Use LLM to extract intent
+      const result = await this.apiClient.extractIntent({
+        user_query: query,
+        route: pageContext.route,
+        available_intents: availableIntents,
+        ui_elements: pageContext.ui_elements, // Pass UI elements for better context matching
+        screenshot: screenshot
+      });
+      
+      this.logger.debug('Intent extraction result:', result);
+      
+      if (result.intent) {
+        // Intent found, get guidance
+        const matchedIntent = this.currentIntents.find(i => i.key === result.intent)
+          || { key: result.intent, label: this._formatIntentLabel(result.intent) };
+        
+        this._onIntentSelected(matchedIntent);
+        
+      } else if (result.clarifying_question) {
+        // Need clarification
+        const suggestedIntents = (result.suggested_intents || [])
+          .map(key => this.currentIntents.find(i => i.key === key) || {
+            key,
+            label: this._formatIntentLabel(key)
+          });
+        
+        this.helpWidget.showClarification(
+          result.clarifying_question,
+          suggestedIntents
+        );
+        
+      } else {
+        // No intent matched, search KB directly
+        await this._handleKBSearch(query);
+      }
+      
+    } catch (error) {
+      this.logger.error('Error processing query:', error);
+      this.helpWidget.showError('Failed to process your question. Please try again.');
+    }
+  }
+
+  async _onSelectionExplain(data) {
+    const text = (data?.text || '').trim();
+    if (!text) return;
+    
+    try {
+      // Use UI Coach Modal instead of Help Widget
+      this.uiCoach.showExplainLoading(text);
+      
+      const pageContext = this.pageObserver.scanPage();
+      
+      // Use dedicated explain endpoint
+      const result = await this.apiClient.explainTerm({
+        text: text,
+        route: pageContext.route,
+        page_title: pageContext.title,
+        context: "" // Can add surrounding text if available later
+      });
+      
+      this.uiCoach.showExplainModal({
+        terms: result.terms,
+        summary: result.source === 'kb' ? 'From Knowledge Base' : 'AI Explanation'
+      });
+      
+    } catch (error) {
+      this.logger.error('Selection explain failed:', error);
+      // Fallback to error modal with retry
+      this.uiCoach.showExplainError(text, () => {
+        this._onSelectionExplain({ text });
+      });
+    }
+  }
+
+  /**
+   * Handle KB search for unmatched queries
+   * @private
+   * @param {string} query - Search query
+   */
+  async _handleKBSearch(query) {
+    try {
+      const results = await this.apiClient.searchKB(query, { limit: 3 });
+      
+      if (results.results && results.results.length > 0) {
+        const topResult = results.results[0];
+        
+        // Check if article is for a different route
+        if (topResult.route_pattern) {
+          this.helpWidget.showNavigationSuggestion({
+            title: topResult.title,
+            route: topResult.route_pattern,
+            excerpt: topResult.excerpt
+          });
+        } else {
+          // Show generic KB result
+          this.helpWidget.showError(
+            `Found help article: "${topResult.title}". Navigate to the relevant page to get step-by-step guidance.`
+          );
+        }
+      } else {
+        this.helpWidget.showError(
+          'Could not find help for that question. Please contact support.'
+        );
+      }
+    } catch (error) {
+      this.logger.error('KB search failed:', error);
+      this.helpWidget.showError(
+        'Could not search help articles. Please contact support.'
+      );
+    }
+  }
+
+  /**
+   * Handle navigation changes (multi-page flow tracking)
+   * @private
+   * @param {Object} data - Navigation data
+   */
+  async _onNavigationChanged(data) {
+    const { route, previousRoute } = data;
+    this.logger.debug('Navigation changed:', { route, previousRoute });
+
+    // Clear any active selection explain button
+    this.uiCoach.disableSelectionExplain();
+    // Re-enable it after a short delay (to clear state but keep feature active)
+    setTimeout(() => this.uiCoach.enableSelectionExplain(), 100);
+
+    // Invalidate the page-scoped intent cache — it belongs to the previous
+    // page. Stale intents corrupt both the local match AND the available_intents
+    // sent to the LLM in _onQuerySubmitted (Phase 3.1). Next use re-scans the
+    // current page.
+    this.currentIntents = [];
+
+    const session = this.sessionManager.getActiveSession();
+    
+    if (!session) {
+      // No active session, nothing to track
+      return;
+    }
+    
+    // Record navigation
+    this.sessionManager.recordNavigation(route);
+
+    // NOTE (Phase 1.5): we intentionally do NOT auto-advance the step on
+    // navigation. Real step completion is driven by interaction on the
+    // highlighted element (see _watchStepElement).
+
+    // Decide whether this navigation is PART OF the workflow or the user
+    // wandering off. The reliable signal is: did a navigation-type step just
+    // complete? When the user clicks the highlighted element for a "Click X"
+    // step, the watcher fires step:done (stamping _stepNavAt) and THEN the app
+    // navigates — so that route change is expected and must not prompt. Any
+    // other navigation (a manual click on an unrelated nav item) is the user
+    // leaving, so we ask whether to keep the workflow.
+    //
+    // The old check used SessionManager.isInSameFlow(route), which keyed off
+    // session.original_route — so navigating BACK to the page the assistant was
+    // opened on (typically /dashboard) looked "in-flow" and never prompted,
+    // even for an unrelated workflow. That was the missed-prompt bug.
+    const stepDriven = this._stepNavAt && (Date.now() - this._stepNavAt) < 2000;
+    this._stepNavAt = 0; // consume: only the immediately-following nav is exempt
+
+    if (!stepDriven) {
+      const shouldContinue = await this.helpWidget.confirmContinueSession(
+        'You’ve left this workflow. Keep the guided workflow running?'
+      );
+
+      if (!shouldContinue) {
+        this._onSessionClose();
+        return;
+      }
+
+      // Kept the workflow after a manual navigation — re-anchor the current
+      // step on this page (its target may live here). Best-effort. Step-driven
+      // navigations already re-anchor via _onStepDone's post-advance timeout.
+      this._showCurrentStep();
+    }
+  }
+
+  /**
+   * Resolve, highlight, and ARM completion detection for the current step.
+   *
+   * This is the single entry point that makes a step "live": it re-resolves the
+   * step's target element against the CURRENT page when the stored selector was
+   * matched on a different route or no longer resolves (fixes the "Next points
+   * at the sidebar instead of Add Employee" bug), draws the visual highlight for
+   * hosts using the built-in widget, and attaches a host-agnostic interaction
+   * watcher so the step advances when the user actually performs the action —
+   * regardless of whether the host renders the SDK's own UI.
+   * @private
+   */
+  async _showCurrentStep() {
+    try {
+      await this._showCurrentStepInner();
+    } catch (error) {
+      // A step-resolution/highlight failure must never break the caller
+      // (intent-select, resume-on-open, advance). Degrade quietly.
+      this.logger?.error?.('Failed to show current step:', error);
+    }
+  }
+
+  /** @private */
+  async _showCurrentStepInner() {
+    const session = this.sessionManager.getActiveSession();
+    if (!session || session.status !== 'active') return;
+
+    const step = this.sessionManager.getCurrentStep();
+    if (!step) return;
+
+    const route = this.pageObserver.getRoute();
+    const minConfidence = this.config.get('minHighlightConfidence');
+
+    // A stored selector is trustworthy only if it was matched on THIS page and
+    // still resolves. Selectors from the backend are matched on the page where
+    // guidance was generated (session.original_route); reused verbatim on a
+    // later page they point at the wrong element.
+    const matchedRoute = step.selector_route || session.original_route;
+    const selectorUsable = !!step.selector
+      && (step.confidence === undefined || step.confidence >= minConfidence)
+      && matchedRoute === route
+      && this.pageObserver.elementExists(step.selector);
+
+    let selector = selectorUsable ? step.selector : await this._resolveStepSelector(step, route);
+
+    const element = selector ? document.querySelector(selector) : null;
+
+    if (!element) {
+      // Couldn't locate the element on this page — show the instruction as text
+      // so the user isn't stranded, and stop watching a stale element.
+      this._unwatchStepElement();
+      this.uiCoach.clearHighlight();
+      this.helpWidget.show();
+      this.helpWidget.showTextOnlyGuidance(
+        session,
+        'Look for: ' + step.text
+      );
+      return;
+    }
+
+    // Visual highlight for built-in-widget hosts. A host that renders its own
+    // on-page indicator (showStepHighlight:false) suppresses it to avoid a
+    // duplicate — detection below is independent of the visual. No onClick:
+    // completion detection is the watcher's job, so it never double-advances.
+    if (this.config.get('showStepHighlight')) {
+      this.uiCoach.highlightElement(selector, {
+        message: step.text,
+        showArrow: true,
+        showTooltip: true,
+        showDoneButton: true,
+        showSkipButton: false,
+      });
+    } else {
+      this.uiCoach.clearHighlight();
+    }
+
+    // Arm host-agnostic completion detection on the real element.
+    this._watchStepElement(element, step);
+
+    // Keep the step list in sync (progress/highlight state).
+    this.helpWidget.updateTooltip(session);
+  }
+
+  /**
+   * Ask the backend to match the current step's described action to an element
+   * on the CURRENT page. Updates the step's selector and stamps the route it was
+   * matched against (selector_route) so we know when it later goes stale.
+   * @private
+   * @returns {Promise<string|null>} the matched selector, or null
+   */
+  async _resolveStepSelector(step, route) {
+    if (this.isMatchingStep) return null;
+    const session = this.sessionManager.getActiveSession();
+    if (!session) return null;
+
+    this.isMatchingStep = true;
+    try {
+      const pageContext = this.pageObserver.scanPage();
+      const matchResult = await this.apiClient.matchElement({
+        step_description: step.text,
+        original_selector: step.selector,
+        route,
+        ui_elements: pageContext.ui_elements,
+        session_id: session.session_id,
+        intent: session.intent,
+        steps: session.steps,
+        current_step_index: session.current_step,
+      });
+
+      this.logger.debug('Element match result:', matchResult);
+
+      if (matchResult.found && matchResult.confidence >= this.config.get('minHighlightConfidence')) {
+        this.sessionManager.updateStep(session.current_step, {
+          selector: matchResult.selector,
+          confidence: matchResult.confidence,
+          match_type: matchResult.match_type,
+          selector_route: route, // remember the page this selector is valid for
+        });
+        return matchResult.selector;
+      }
+      return null;
+    } catch (error) {
+      this.logger.error('Error re-matching element:', error);
+      return null;
+    } finally {
+      this.isMatchingStep = false;
+    }
+  }
+
+  /**
+   * Attach a one-shot completion watcher to the current step's real target
+   * element. Clicking a button/link, or typing into / toggling a field, emits
+   * step:done. This works in ANY host because it listens on the actual page
+   * element, not on the SDK's overlay.
+   * @private
+   */
+  _watchStepElement(element, step) {
+    this._unwatchStepElement();
+    if (!element) return;
+
+    this._watchedEl = element;
+    this._watchHandlers = [];
+
+    const fire = (ev) => {
+      // Remove the sibling listeners so the same interaction can't double-fire.
+      this._unwatchStepElement();
+      // A CLICK on the highlighted element may navigate (a nav link, or a button
+      // that routes). Mark it so _onNavigationChanged treats the imminent route
+      // change as EXPECTED step progress and doesn't prompt "leave the
+      // workflow?". Only real clicks on the highlighted element count — NOT the
+      // panel's "Next" button and NOT typing — so a manual navigation to an
+      // unrelated page still prompts.
+      if (ev && ev.type === 'click') {
+        this._stepNavAt = Date.now();
+      }
+      EventBus.emit(EVENTS.STEP_DONE);
+    };
+
+    const add = (type) => {
+      element.addEventListener(type, fire, { once: true });
+      this._watchHandlers.push([type, fire]);
+    };
+
+    const tag = element.tagName;
+    const isField = tag === 'INPUT' || tag === 'TEXTAREA' || element.isContentEditable;
+    if (isField) {
+      if (element.type === 'checkbox' || element.type === 'radio') {
+        add('change');
+      } else {
+        add('input');
+      }
+    } else {
+      add('click');
+    }
+  }
+
+  /** Detach the current step-completion watcher, if any. @private */
+  _unwatchStepElement() {
+    if (this._watchedEl && this._watchHandlers) {
+      for (const [type, fn] of this._watchHandlers) {
+        this._watchedEl.removeEventListener(type, fn);
+      }
+    }
+    this._watchedEl = null;
+    this._watchHandlers = null;
+  }
+
+  /**
+   * Back-compat shim: older call sites re-matched the current step on a new
+   * page. That responsibility now lives in _showCurrentStep (which also arms
+   * detection), so delegate.
+   * @private
+   */
+  async _rematchCurrentStep() {
+    return this._showCurrentStep();
+  }
+
+  /**
+   * Handle step marked as done
+   * @private
+   */
+  _onStepDone() {
+    if (this.isUpdating) return;
+    
+    this.logger.debug('Step marked as done');
+    this.lastStepAdvanceTime = Date.now();
+    
+    // Check if the current step action likely triggers navigation
+    const currentStep = this.sessionManager.getCurrentStep();
+    const isNavigationAction = currentStep && (
+      currentStep.text.toLowerCase().includes('click') ||
+      currentStep.text.toLowerCase().includes('navigate') ||
+      currentStep.text.toLowerCase().includes('select') ||
+      currentStep.selector
+    );
+
+    // NOTE: _stepNavAt (the "expected step navigation" marker) is set in the
+    // interaction watcher on a real CLICK of the highlighted element — NOT here.
+    // Advancing via the panel's "Next" button must not exempt a subsequent
+    // manual navigation from the "leave the workflow?" prompt.
+
+    const advanced = this.sessionManager.advanceStep();
+    
+    if (!advanced) {
+      // All steps completed
+      this._onSessionComplete();
+      return;
+    }
+    
+    // Update widget
+    const session = this.sessionManager.getActiveSession();
+    this.helpWidget.updateTooltip(session);
+    
+    // Ensure widget is visible if not minimized
+    // We don't force show here if it was explicitly closed, but we should ensure content is updated
+    
+    // If this was likely a navigation action, delay highlighting
+    // to give the page time to transition
+    if (isNavigationAction) {
+      this.logger.debug('Navigation action detected, delaying highlight...');
+
+      // Set a flag or just use a timeout to retry highlighting
+      // Ideally we would wait for page:dom_changed, but a simple timeout is safer fallback
+      setTimeout(() => {
+        // Re-resolve the next step against whatever page we're now on and arm it.
+        this._showCurrentStep();
+      }, 1000);
+    } else {
+      // Immediate highlight for non-navigation steps (e.g. typing)
+      this._showCurrentStep();
+    }
+  }
+
+  /**
+   * Handle step skipped
+   * @private
+   */
+  _onStepSkip() {
+    this.logger.debug('Step skipped');
+    
+    // Same as done, just move to next step
+    this._onStepDone();
+  }
+
+  /**
+   * Handle session completion
+   * @private
+   */
+  async _onSessionComplete() {
+    if (this.isUpdating) return;
+    this.isUpdating = true;
+
+    this.logger.info('Session completed');
+    
+    const session = this.sessionManager.getActiveSession();
+    
+    if (session) {
+      try {
+        // Update backend
+        await this.apiClient.updateSession({
+          session_id: session.session_id,
+          status: 'completed',
+          current_step: session.current_step,
+          total_steps: session.total_steps
+        });
+        
+        // Update local session to stop polling but keep active
+        this.sessionManager.updateSession({ status: 'completed' });
+        
+      } catch (error) {
+        this.logger.error('Failed to update session status:', error);
+      }
+    }
+    
+    // Clear highlight + stop watching the completed step's element.
+    this.uiCoach.clearHighlight();
+    this._unwatchStepElement();
+
+    // Show the widget (in case it was closed/minimized) so user sees the completion screen
+    this.helpWidget.show();
+
+    // Show completion screen
+    this.helpWidget.showCompletion(session?.intent_label || session?.intent);
+
+    // Emit completion event
+    EventBus.emit('handhold:completed', { intent: session?.intent });
+    
+    this.isUpdating = false;
+  }
+
+  /**
+   * Handle session close
+   * @private
+   */
+  async _onSessionClose() {
+    this.logger.debug('Session close requested');
+
+    const session = this.sessionManager.getActiveSession();
+
+    // Tear down SYNCHRONOUSLY, before any await. A caller often exits then
+    // immediately reopens (handleConfirmExit: exitWorkflow(); openHelp()). If we
+    // awaited the backend update first, endSession() would run later and the
+    // reopen would still observe the session as active and RESUME the workflow
+    // we just exited — the "stale workflow bleeds into the next question" bug.
+    this.uiCoach.clearHighlight();
+    this._unwatchStepElement();
+    this.helpWidget.hide();
+    // Full reset so stale guidance can't bleed into the next question/menu.
+    this.helpWidget.resetView();
+    this.sessionManager.endSession();
+
+    // Emit close event
+    EventBus.emit('handhold:closed', { intent: session?.intent });
+
+    // Best-effort backend update — must not gate the local teardown above.
+    if (session) {
+      try {
+        await this.apiClient.updateSession({
+          session_id: session.session_id,
+          status: 'abandoned',
+          current_step: session.current_step,
+          total_steps: session.total_steps
+        });
+      } catch (error) {
+        this.logger.error('Failed to update session status:', error);
+      }
+    }
+  }
+
+  /**
+   * Minimize the widget: hide the panel but KEEP the active workflow so
+   * reopening (the trigger button / open()) resumes it where it left off.
+   * This is what Close/✕ should do on an active workflow — ending the session
+   * is reserved for an explicit "Exit workflow". Clears the on-page highlight
+   * and detection while minimized so nothing lingers on the page.
+   * @private
+   */
+  _onMinimize() {
+    const session = this.sessionManager.getActiveSession();
+    // Nothing to minimize to — behave like a plain close.
+    if (!session || session.status !== 'active') {
+      this._onSessionClose();
+      return;
+    }
+    this.uiCoach.clearHighlight();
+    this._unwatchStepElement();
+    // Pure-visual hide; keeps currentView/currentGuidance so resume works.
+    this.helpWidget.hide();
+  }
+
+  /**
+   * Handle DOM changes
+   * @private
+   */
+  _onDomChanged() {
+    // 1. If active highlight, verify element still exists
+    if (this.uiCoach.isActive()) {
+      const session = this.sessionManager.getActiveSession();
+      if (session) {
+        const currentStep = this.sessionManager.getCurrentStep();
+        if (currentStep && currentStep.selector) {
+          const exists = this.pageObserver.elementExists(currentStep.selector);
+          if (!exists) {
+            this.logger.debug('Highlighted element no longer exists');
+            this.uiCoach.clearHighlight();
+            this._rematchCurrentStep(this.pageObserver.getRoute());
+          }
+        }
+      }
+    }
+
+    // 2. If session active, check if we need to re-scan page (for navigation/content loading)
+    /* 
+    // Disabled per user request to prevent infinite loops and 429s. 
+    // User prefers explicit "Show UI" or interaction.
+    const session = this.sessionManager.getActiveSession();
+    if (session && session.status === 'active') {
+      // Use debounced check to avoid spamming API
+      if (this._checkPageTimer) clearTimeout(this._checkPageTimer);
+      
+      this._checkPageTimer = setTimeout(() => {
+        this._checkPageStatus();
+      }, 500); // 500ms debounce
+    }
+    */
+  }
+
+  /**
+   * Check page status and update guidance
+   * @private
+   */
+  async _checkPageStatus() {
+    const session = this.sessionManager.getActiveSession();
+    if (!session) return;
+
+    try {
+      const pageContext = this.pageObserver.scanPage(true); // Force rescan
+      
+      const result = await this.apiClient.checkPageStatus({
+        session_id: session.session_id,
+        route: pageContext.route,
+        ui_elements: pageContext.ui_elements
+      });
+
+      this.logger.debug('Page status check:', result);
+
+      if (result.status === 'active' && result.action === 'highlight') {
+        // Update step info with new selector
+        if (result.step_info) {
+          this.sessionManager.updateStep(session.current_step, {
+            selector: result.selector,
+            confidence: result.step_info.confidence,
+            match_type: result.step_info.match_type
+          });
+        }
+        
+        // Highlight element
+        this._highlightCurrentStep();
+      } else if (result.status === 'active' && result.action === 'stay') {
+         // Show fallback message if provided
+         if (result.fallback_message) {
+            this.helpWidget.showTextOnlyGuidance(session, result.fallback_message);
+         }
+      }
+
+    } catch (error) {
+      this.logger.error('Failed to check page status:', error);
+    }
+  }
+
+  /**
+   * Highlight current step element. Kept for back-compat; the resolve +
+   * highlight + arm-detection logic now lives in _showCurrentStep.
+   * @private
+   */
+  async _highlightCurrentStep() {
+    return this._showCurrentStep();
+  }
+
+  /**
+   * Restore session after page load
+   * @private
+   */
+  async _restoreSession() {
+    if (!this.sessionManager.hasActiveSession()) {
+      return;
+    }
+    
+    const session = this.sessionManager.getActiveSession();
+    this.logger.debug('Found existing session:', session);
+    
+    // Ask user if they want to continue
+    const shouldContinue = await this.helpWidget.confirmContinueSession(
+      'You have an active guidance session. Continue where you left off?'
+    );
+    
+    if (!shouldContinue) {
+      this._onSessionClose();
+      return;
+    }
+    
+    // Restore session UI
+    try {
+      // Show guidance tooltip
+      this.helpWidget.showGuidanceTooltip({
+        intent: session.intent,
+        summary: session.summary || '',
+        steps: session.steps,
+        current_step: session.current_step,
+        total_steps: session.total_steps
+      });
+      
+      // Try to highlight current step
+      await this._rematchCurrentStep(this.pageObserver.getRoute());
+      
+    } catch (error) {
+      this.logger.error('Error restoring session:', error);
+      this._onSessionClose();
+    }
+  }
+
+  /**
+   * Capture screenshot of the current page
+   * @private
+   * @returns {Promise<string|null>} Base64 encoded screenshot (no prefix)
+   */
+  async _captureScreenshot() {
+    // Opt-out (default on). On modern-CSS sites (oklch/oklab — Tailwind v4)
+    // html2canvas cannot parse the colors and stalls for seconds before
+    // failing, hanging the widget on every question. Skip it entirely when
+    // disabled; intent extraction works fine from the DOM without it.
+    if (!this.config.get('enableScreenshots')) {
+      return null;
+    }
+    try {
+        // Ensure widget is hidden/minimized during capture if needed,
+        // but ignoreElements handles it better visually.
+
+        const canvas = await html2canvas(document.body, {
+            logging: false,
+            useCORS: true,
+            onclone: (clonedDoc) => {
+                // Fix for html2canvas not supporting modern CSS colors like oklch
+                try {
+                    const allElements = clonedDoc.querySelectorAll('*');
+                    const canvas = document.createElement('canvas');
+                    canvas.width = 1;
+                    canvas.height = 1;
+                    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+                    const colorCache = new Map();
+
+                    const resolveColor = (color) => {
+                        if (!color || typeof color !== 'string') return color;
+                        // Check for unsupported modern color functions
+                        if (!color.includes('oklch') && !color.includes('oklab') && !color.includes('lab(') && !color.includes('lch(')) return color;
+                        
+                        if (colorCache.has(color)) return colorCache.get(color);
+
+                        // Use canvas to convert color to RGBA
+                        ctx.clearRect(0, 0, 1, 1);
+                        ctx.fillStyle = color;
+                        ctx.fillRect(0, 0, 1, 1);
+                        const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+                        const rgba = `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+                        colorCache.set(color, rgba);
+                        return rgba;
+                    };
+
+                    allElements.forEach(el => {
+                        // Use defaultView from the cloned document (it should be mounted in an iframe)
+                        const view = el.ownerDocument.defaultView;
+                        if (!view) return;
+                        
+                        const style = view.getComputedStyle(el);
+                        
+                        // 1. Iterate through all computed style properties
+                        for (let i = 0; i < style.length; i++) {
+                            const prop = style[i];
+                            const val = style.getPropertyValue(prop);
+                            
+                            // Check for any unsupported color function (oklch, oklab, lab, lch)
+                            if (val && (val.includes('oklch') || val.includes('oklab') || val.includes('lab(') || val.includes('lch('))) {
+                                el.style.setProperty(prop, resolveColor(val), 'important');
+                            }
+                        }
+                        
+                        // 2. Also check inline styles specifically
+                        if (el.style) {
+                             for (let i = 0; i < el.style.length; i++) {
+                                const prop = el.style[i];
+                                const val = el.style.getPropertyValue(prop);
+                                if (val && (val.includes('oklch') || val.includes('oklab') || val.includes('lab(') || val.includes('lch('))) {
+                                    el.style.setProperty(prop, resolveColor(val), 'important');
+                                }
+                             }
+                        }
+                    });
+                } catch (e) {
+                    console.warn('[HandHold] Failed to process colors in screenshot clone:', e);
+                }
+            },
+            ignoreElements: (element) => {
+                // Ignore the help widget and coaching elements
+                return element.id === 'handhold-container' || 
+                       element.classList.contains('handhold-widget') ||
+                       element.classList.contains('handhold-overlay') ||
+                       element.classList.contains('handhold-highlight') ||
+                       element.classList.contains('handhold-arrow') ||
+                       element.classList.contains('handhold-spotlight') ||
+                       element.classList.contains('handhold-step-tooltip');
+            }
+        });
+        
+        const dataUrl = canvas.toDataURL('image/png');
+        // Return just the base64 part
+        return dataUrl.split(',')[1];
+    } catch (error) {
+        this.logger.error('Screenshot capture failed:', error);
+        return null;
+    }
+  }
+
+  /**
+   * Format intent key to human-readable label
+   * @private
+   * @param {string} key - Intent key
+   * @returns {string} Formatted label
+   */
+  _formatIntentLabel(key) {
+    return key
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  // ==================== Public API ====================
+
+  /**
+   * Open the help widget
+   */
+  open() {
+    if (!this.initialized) {
+      console.warn('[HandHold] SDK not initialized. Call init() first.');
+      return;
+    }
+    
+    this.helpWidget.show();
+    this._onHelpOpen();
+  }
+
+  /**
+   * Close the help widget
+   */
+  close() {
+    if (!this.initialized) return;
+    
+    this._onSessionClose();
+  }
+
+  /**
+   * Toggle the help widget
+   */
+  toggle() {
+    if (!this.initialized) return;
+    
+    this.helpWidget.toggle();
+  }
+
+  /**
+   * Start guidance for a specific intent
+   * @param {string} intentKey - Intent key (e.g., 'approve_payroll')
+   */
+  async startGuidance(intentKey) {
+    if (!this.initialized) {
+      console.warn('[HandHold] SDK not initialized. Call init() first.');
+      return;
+    }
+    
+    // Find intent in current page intents
+    let intent = this.currentIntents.find(i => i.key === intentKey);
+    
+    if (!intent) {
+      // Create intent object
+      intent = {
+        key: intentKey,
+        label: this._formatIntentLabel(intentKey),
+        confidence: 1.0
+      };
+    }
+    
+    this.helpWidget.show();
+    await this._onIntentSelected(intent);
+  }
+
+  /**
+   * Get current intents for the page
+   * @returns {Array} Array of intent objects
+   */
+  getIntents() {
+    if (!this.initialized) return [];
+    
+    const pageContext = this.pageObserver.scanPage();
+    return IntentExtractor.extract(pageContext.ui_elements, pageContext.route);
+  }
+
+  /**
+   * Check if there's an active guidance session
+   * @returns {boolean}
+   */
+  hasActiveSession() {
+    if (!this.initialized) return false;
+    
+    return this.sessionManager.hasActiveSession();
+  }
+
+  /**
+   * Get the active session
+   * @returns {Object|null} Session object or null
+   */
+  getActiveSession() {
+    if (!this.initialized) return null;
+    
+    return this.sessionManager.getActiveSession();
+  }
+
+  /**
+   * Get session progress
+   * @returns {number} Progress percentage (0-100)
+   */
+  getProgress() {
+    if (!this.initialized) return 0;
+    
+    return this.sessionManager.getProgress();
+  }
+
+  /**
+   * Subscribe to SDK events
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, callback) {
+    return EventBus.on(event, callback);
+  }
+
+  /**
+   * Unsubscribe from SDK events
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   */
+  off(event, callback) {
+    EventBus.off(event, callback);
+  }
+
+  /**
+   * Destroy the SDK instance
+   */
+  destroy() {
+    if (!this.initialized) return;
+    
+    this.logger.info('Destroying Hand Hold SDK...');
+    
+    // Clear any active session without notifying backend
+    if (this.uiCoach) {
+      this.uiCoach.destroy();
+    }
+    
+    if (this.helpWidget) {
+      this.helpWidget.destroy();
+    }
+    
+    if (this.pageObserver) {
+      this.pageObserver.disconnect();
+    }
+    
+    if (this.sessionManager) {
+      this.sessionManager.endSession();
+    }
+    
+    // Clear event listeners
+    EventBus.clear();
+    
+    // Reset state
+    this.config = null;
+    this.logger = null;
+    this.apiClient = null;
+    this.pageObserver = null;
+    this.sessionManager = null;
+    this.helpWidget = null;
+    this.uiCoach = null;
+    this.currentIntents = [];
+    this.initialized = false;
+    
+    console.log('[HandHold] SDK destroyed');
+  }
+
+  /**
+   * Get SDK version
+   * @returns {string} Version string
+   */
+  getVersion() {
+    return '1.0.0';
+  }
+
+  /**
+   * Check if SDK is initialized
+   * @returns {boolean}
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+
+  // ============================================
+  // UI state (Phase 2) — single source of truth
+  // ============================================
+
+  /**
+   * Subscribe to UI-state changes. Shaped for React's useSyncExternalStore:
+   * pass HandHold.subscribe and HandHold.getState directly. The listener runs
+   * on every state change.
+   * @param {(snapshot: Object) => void} listener
+   * @returns {() => void} unsubscribe
+   */
+  subscribe(listener) {
+    return this.uiState.subscribe(listener);
+  }
+
+  /** Current UI-state snapshot (stable reference until it changes). */
+  getState() {
+    return this.uiState.getSnapshot();
+  }
+
+  // ============================================
+  // Commands (Phase 2.2) — the public API a host calls
+  // ============================================
+  // App code should call these instead of emitting raw EventBus events, so the
+  // SDK owns the contract. Internally they drive the same event-based handlers.
+
+  /**
+   * Open the help widget (marks it open, scans the page, shows the menu).
+   * Sets the WIDGET's isOpen — the source _syncState() reflects into UiState —
+   * so the follow-up scan doesn't overwrite isOpen back to false.
+   */
+  openHelp() {
+    if (this.helpWidget) this.helpWidget.isOpen = true;
+    this.uiState.setState({ isOpen: true });
+    EventBus.emit(EVENTS.HELP_OPEN);
+  }
+
+  /** Submit a free-text question. */
+  submitQuery(query) { EventBus.emit(EVENTS.QUERY_SUBMITTED, query); }
+
+  /** Start a workflow for an intent. @param {{key:string,label?:string}} intent */
+  startIntent(intent) { EventBus.emit(EVENTS.INTENT_SELECTED, intent); }
+
+  /** Mark the current guidance step done (advance). */
+  markStepDone() { EventBus.emit(EVENTS.STEP_DONE); }
+
+  /** Go back a step. */
+  goBackStep(stepIndex) { EventBus.emit(EVENTS.STEP_BACK, stepIndex); }
+
+  /** Answer the session-restore "continue?" confirm. @param {boolean} answer */
+  respondToConfirm(answer) { EventBus.emit(EVENTS.CONFIRM_RESPONSE, answer); }
+
+  /** End / exit the active workflow session. */
+  exitWorkflow() { EventBus.emit(EVENTS.SESSION_CLOSE); }
+
+  /**
+   * Minimize the widget without ending the workflow. Reopening resumes it.
+   * Use this for a Close/✕ affordance; use exitWorkflow() to actually end it.
+   */
+  minimize() { EventBus.emit(EVENTS.HELP_MINIMIZE); }
+
+  /**
+   * Re-show the current step's on-page hint. Re-resolves the step's target
+   * against the current page and re-anchors the highlight + completion watcher.
+   * Use it for a "Show hint" affordance when the on-page pointer has been
+   * dismissed or has scrolled/re-rendered away.
+   */
+  showHint() { EventBus.emit(EVENTS.HELP_SHOW_HINT); }
+
+  /** Start a "Do it for me" agent run. @param {Object} plan agent_plan */
+  startAgent(plan) { EventBus.emit(EVENTS.AGENT_START, plan); }
+
+  /** Cooperatively stop the running agent. */
+  stopAgent() { EventBus.emit(EVENTS.AGENT_STOP); }
+}
+
+// Create singleton instance
+const handHoldInstance = new HandHold();
+
+export default handHoldInstance;
+export { HandHold };