handhold-sdk 1.0.0

package/src/observers/PageObserver.js

@@ -0,0 +1,293 @@
+/**
+ * Hand Hold SDK - Page Observer
+ * Main observer that combines navigation detection and element scanning
+ * Uses MutationObserver to detect DOM changes
+ */
+
+import NavigationObserver from './NavigationObserver.js';
+import ElementScanner from './ElementScanner.js';
+import eventBus from '../utils/eventBus.js';
+
+class PageObserver {
+  constructor(config) {
+    this.config = config;
+    this.navigationObserver = new NavigationObserver(config);
+    this.elementScanner = new ElementScanner(config);
+    this.mutationObserver = null;
+    this.isObserving = false;
+    this.debounceTimer = null;
+    this.debounceDelay = 250; // ms
+    this.lastScanResult = null;
+  }
+
+  /**
+   * Start observing page changes
+   */
+  observe() {
+    if (this.isObserving) return;
+
+    // Start navigation observer
+    this.navigationObserver.observe();
+
+    // Start mutation observer for DOM changes
+    this._startMutationObserver();
+
+    // Listen for navigation changes
+    eventBus.on('navigation:changed', (data) => this._onNavigationChanged(data));
+
+    this.isObserving = true;
+  }
+
+  /**
+   * Stop all observation
+   */
+  disconnect() {
+    if (!this.isObserving) return;
+
+    this.navigationObserver.disconnect();
+    
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    this.isObserving = false;
+  }
+
+  /**
+   * Start MutationObserver for DOM changes
+   */
+  _startMutationObserver() {
+    this.mutationObserver = new MutationObserver((mutations) => {
+      this._onDOMChange(mutations);
+    });
+
+    this.mutationObserver.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['class', 'style', 'hidden', 'disabled', 'aria-hidden'],
+    });
+  }
+
+  /**
+   * Handle DOM changes (debounced)
+   * @param {MutationRecord[]} mutations
+   */
+  _onDOMChange(mutations) {
+    // Skip Hand Hold's own changes
+    const isHandHoldChange = mutations.some(m => {
+      const target = m.target;
+      if (target.id?.startsWith('handhold-')) return true;
+      if (target.closest?.('#handhold-container')) return true;
+      return false;
+    });
+
+    if (isHandHoldChange) return;
+
+    // Debounce to avoid excessive processing
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this._emitDOMChanged();
+    }, this.debounceDelay);
+  }
+
+  /**
+   * Emit DOM changed event
+   */
+  _emitDOMChanged() {
+    eventBus.emit('page:dom_changed', {
+      route: this.navigationObserver.getRoute(),
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Handle navigation change
+   * @param {Object} data - Navigation data
+   */
+  _onNavigationChanged(data) {
+    // Clear cached scan result
+    this.lastScanResult = null;
+
+    // Emit page changed event after a short delay for content to load
+    setTimeout(() => {
+      eventBus.emit('page:changed', {
+        route: data.route,
+        previousRoute: data.previousRoute,
+        pathname: data.pathname,
+        timestamp: Date.now(),
+      });
+    }, 100);
+  }
+
+  /**
+   * Scan the current page
+   * @param {boolean} [forceRescan=false] - Force rescan even if cached
+   * @returns {Object} - { route, title, headings, ui_elements, forms }
+   */
+  scanPage(forceRescan = false) {
+    const currentRoute = this.navigationObserver.getRoute();
+
+    // Return cached result if available and route hasn't changed
+    if (!forceRescan && this.lastScanResult && this.lastScanResult.route === currentRoute) {
+      return this.lastScanResult;
+    }
+
+    // Get page context
+    const context = this.elementScanner.getPageContext();
+
+    // Scan UI elements
+    const uiElements = this.elementScanner.scan();
+
+    this.lastScanResult = {
+      route: context.route,
+      full_route: currentRoute,
+      title: context.title,
+      headings: context.headings,
+      forms: context.forms,
+      ui_elements: uiElements,
+      scanned_at: Date.now(),
+    };
+
+    return this.lastScanResult;
+  }
+
+  /**
+   * Get current route
+   * @returns {string}
+   */
+  getRoute() {
+    return this.navigationObserver.getRoute();
+  }
+
+  /**
+   * Get current pathname
+   * @returns {string}
+   */
+  getPathname() {
+    return this.navigationObserver.getPathname();
+  }
+
+  /**
+   * Check if element exists
+   * @param {string} selector
+   * @returns {boolean}
+   */
+  elementExists(selector) {
+    return this.elementScanner.elementExists(selector);
+  }
+
+  /**
+   * Find element by selector
+   * @param {string} selector
+   * @returns {Element|null}
+   */
+  findElement(selector) {
+    return this.elementScanner.findElement(selector);
+  }
+
+  /**
+   * Get buttons on current page
+   * @returns {Array}
+   */
+  getButtons() {
+    const result = this.scanPage();
+    return result.ui_elements.filter(el => el.role === 'button');
+  }
+
+  /**
+   * Get links on current page
+   * @returns {Array}
+   */
+  getLinks() {
+    const result = this.scanPage();
+    return result.ui_elements.filter(el => el.role === 'link');
+  }
+
+  /**
+   * Get primary actions (prominent buttons)
+   * @returns {Array}
+   */
+  getPrimaryActions() {
+    const result = this.scanPage();
+    
+    // Filter for likely primary actions
+    return result.ui_elements.filter(el => {
+      if (el.role !== 'button') return false;
+      if (el.disabled) return false;
+      
+      // Check for primary styling indicators
+      const selector = el.selector.toLowerCase();
+      const text = (el.text + ' ' + el.aria_label).toLowerCase();
+      
+      const isPrimary = 
+        selector.includes('primary') ||
+        selector.includes('submit') ||
+        selector.includes('main') ||
+        text.includes('save') ||
+        text.includes('submit') ||
+        text.includes('create') ||
+        text.includes('approve') ||
+        text.includes('confirm');
+      
+      return isPrimary || el.position.y < 500; // Above fold
+    }).slice(0, 6);
+  }
+
+  /**
+   * Wait for an element to appear
+   * @param {string} selector
+   * @param {number} timeout
+   * @returns {Promise<Element>}
+   */
+  waitForElement(selector, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+      // Check if already exists
+      const existing = this.findElement(selector);
+      if (existing) {
+        resolve(existing);
+        return;
+      }
+
+      const startTime = Date.now();
+      
+      const observer = new MutationObserver(() => {
+        const element = this.findElement(selector);
+        if (element) {
+          observer.disconnect();
+          resolve(element);
+        } else if (Date.now() - startTime > timeout) {
+          observer.disconnect();
+          reject(new Error(`Element ${selector} not found within ${timeout}ms`));
+        }
+      });
+
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+      });
+
+      // Fallback timeout
+      setTimeout(() => {
+        observer.disconnect();
+        const element = this.findElement(selector);
+        if (element) {
+          resolve(element);
+        } else {
+          reject(new Error(`Element ${selector} not found within ${timeout}ms`));
+        }
+      }, timeout);
+    });
+  }
+}
+
+export default PageObserver;

package/src/session/SessionManager.js

@@ -0,0 +1,402 @@
+/**
+ * Hand Hold SDK - Session Manager
+ * Manages guidance sessions with multi-page tracking support
+ */
+
+import SessionStorage from './SessionStorage.js';
+import eventBus from '../utils/eventBus.js';
+
+const SESSION_KEY = 'session';
+const SESSION_HISTORY_KEY = 'session_history';
+
+// Bump when the persisted session shape changes. On load, a session written by
+// an older build (different or absent version) is discarded so a stale shape
+// can't break new code (Phase 2.3). v2 added agent_checkpoint (H7).
+const SESSION_SCHEMA_VERSION = 2;
+
+class SessionManager {
+  constructor(config) {
+    this.config = config;
+    this.storage = new SessionStorage();
+    this.currentSession = null;
+  }
+
+  /**
+   * Generate unique session ID
+   * @returns {string}
+   */
+  _generateSessionId() {
+    const random = Math.random().toString(36).substring(2, 11);
+    const timestamp = Date.now().toString(36);
+    return `ses_${random}${timestamp}`;
+  }
+
+  /**
+   * Get or create session ID
+   * @returns {string}
+   */
+  getSessionId() {
+    const session = this.getActiveSession();
+    if (session) {
+      return session.session_id;
+    }
+    return this._generateSessionId();
+  }
+
+  /**
+   * Start a new guidance session
+   * @param {Object} data - { intent, steps, original_route }
+   * @returns {Object} - Session object
+   */
+  startSession(data) {
+    // End any existing session
+    if (this.currentSession) {
+      this.endSession('abandoned');
+    }
+
+    const session = {
+      schema_version: SESSION_SCHEMA_VERSION,
+      session_id: data.session_id || this._generateSessionId(),
+      intent: data.intent,
+      intent_label: data.intent_label || data.intent,
+      steps: data.steps || [],
+      current_step: 0,
+      steps_completed: 0,
+      total_steps: data.steps?.length || 0,
+      original_route: data.original_route,
+      current_route: data.original_route,
+      started_at: Date.now(),
+      last_activity: Date.now(),
+      status: 'active',
+      navigation_history: [data.original_route],
+    };
+
+    this.currentSession = session;
+    this._saveSession(session);
+    
+    eventBus.emit('session:started', session);
+    
+    return session;
+  }
+
+  /**
+   * Get the active session
+   * @returns {Object|null}
+   */
+  getActiveSession() {
+    // Check memory first
+    if (this.currentSession) {
+      return this.currentSession;
+    }
+
+    // Check storage
+    const session = this.storage.get(SESSION_KEY);
+
+    if (!session) {
+      return null;
+    }
+
+    // Discard sessions written by an older build (Phase 2.3): a stale shape must
+    // not flow into new code.
+    if (session.schema_version !== SESSION_SCHEMA_VERSION) {
+      this.storage.remove(SESSION_KEY);
+      return null;
+    }
+
+    // Check if session has expired
+    // Use internal property access instead of getActiveSession to prevent recursion
+    if (this._isSessionExpired(session)) {
+      this.endSession('expired');
+      return null;
+    }
+
+    this.currentSession = session;
+    return session;
+  }
+
+  /**
+   * Check if there's an active session
+   * @returns {boolean}
+   */
+  hasActiveSession() {
+    return this.getActiveSession() !== null;
+  }
+
+  /**
+   * Check if session has expired due to inactivity
+   * @param {Object} session
+   * @returns {boolean}
+   */
+  _isSessionExpired(session) {
+    const now = Date.now();
+    const lastActivity = session.last_activity || session.started_at;
+    const inactiveTime = now - lastActivity;
+    return inactiveTime > this.config.sessionInactivityTimeout;
+  }
+
+  /**
+   * Update the current session
+   * @param {Object} updates - Fields to update
+   */
+  updateSession(updates) {
+    const session = this.getActiveSession();
+    if (!session) return null;
+
+    Object.assign(session, updates, {
+      last_activity: Date.now(),
+    });
+
+    this.currentSession = session;
+    this._saveSession(session);
+    
+    eventBus.emit('session:updated', session);
+    
+    return session;
+  }
+
+  /**
+   * Record a navigation event
+   * @param {string} newRoute - New route
+   */
+  recordNavigation(newRoute) {
+    const session = this.getActiveSession();
+    if (!session) return;
+
+    session.current_route = newRoute;
+    session.last_activity = Date.now();
+    
+    if (!session.navigation_history.includes(newRoute)) {
+      session.navigation_history.push(newRoute);
+    }
+
+    this._saveSession(session);
+    eventBus.emit('session:navigation', { session, route: newRoute });
+  }
+
+  /**
+   * Advance to the next step
+   * @returns {Object|null} - Next step or null if completed
+   */
+  advanceStep() {
+    const session = this.getActiveSession();
+    if (!session) return null;
+
+    session.steps_completed++;
+    session.current_step++;
+    session.last_activity = Date.now();
+
+    // Check if all steps completed
+    if (session.current_step >= session.total_steps) {
+      session.status = 'completed';
+      this._saveSession(session);
+      eventBus.emit('session:completed', session);
+      return null;
+    }
+
+    this._saveSession(session);
+    eventBus.emit('session:step_advanced', {
+      session,
+      step: session.steps[session.current_step],
+      stepIndex: session.current_step,
+    });
+
+    return session.steps[session.current_step];
+  }
+
+  /**
+   * Get current step
+   * @returns {Object|null}
+   */
+  getCurrentStep() {
+    const session = this.getActiveSession();
+    if (!session || session.current_step >= session.total_steps) {
+      return null;
+    }
+    return session.steps[session.current_step];
+  }
+
+  /**
+   * Get step by index
+   * @param {number} index - Step index
+   * @returns {Object|null}
+   */
+  getStep(index) {
+    const session = this.getActiveSession();
+    if (!session || index < 0 || index >= session.total_steps) {
+      return null;
+    }
+    return session.steps[index];
+  }
+
+  /**
+   * Update step selector (after re-matching on new page)
+   * @param {number} stepIndex - Step index
+   * @param {Object} updates - { selector, confidence, match_type }
+   */
+  updateStep(stepIndex, updates) {
+    const session = this.getActiveSession();
+    if (!session || stepIndex < 0 || stepIndex >= session.total_steps) {
+      return;
+    }
+
+    Object.assign(session.steps[stepIndex], updates);
+    session.last_activity = Date.now();
+    
+    this._saveSession(session);
+  }
+
+  // ============================================
+  // Agent checkpoint (H7)
+  // ============================================
+  // The "Do it for me" agent persists a run checkpoint on the session object
+  // so a task survives full page loads. The checkpoint rides the session in
+  // per-tab sessionStorage (same trust boundary as the rest of the session);
+  // schema/TTL/size validation happens in AgentMode on restore.
+
+  /**
+   * Attach an agent checkpoint to the active session.
+   * @param {Object} checkpoint - {v, task, stepsUsed, history, audit, savedAt}
+   * @returns {boolean} - false when there is no active session to carry it
+   */
+  saveAgentCheckpoint(checkpoint) {
+    const session = this.getActiveSession();
+    if (!session) return false;
+
+    session.agent_checkpoint = checkpoint;
+    session.last_activity = Date.now();
+    this._saveSession(session);
+    return true;
+  }
+
+  /**
+   * The active session's agent checkpoint, if any.
+   * @returns {Object|null}
+   */
+  getAgentCheckpoint() {
+    const session = this.getActiveSession();
+    return session?.agent_checkpoint ?? null;
+  }
+
+  /** Remove the agent checkpoint from the active session. */
+  clearAgentCheckpoint() {
+    const session = this.getActiveSession();
+    if (!session || session.agent_checkpoint === undefined) return;
+
+    delete session.agent_checkpoint;
+    this._saveSession(session);
+  }
+
+  /**
+   * End the current session
+   * @param {string} [reason='closed'] - Reason for ending
+   */
+  endSession(reason = 'closed') {
+    // Get session directly from property or storage to avoid recursion loop
+    const session = this.currentSession || this.storage.get(SESSION_KEY);
+    
+    if (!session) return;
+
+    session.status = reason === 'completed' ? 'completed' : 'ended';
+    session.ended_at = Date.now();
+    session.end_reason = reason;
+
+    // Save to history
+    this._saveToHistory(session);
+    
+    // Clear current session
+    this.currentSession = null;
+    this.storage.remove(SESSION_KEY);
+    
+    eventBus.emit('session:ended', { session, reason });
+  }
+
+  /**
+   * Save session to storage
+   * @param {Object} session
+   */
+  _saveSession(session) {
+    this.storage.set(SESSION_KEY, session);
+  }
+
+  /**
+   * Save completed session to history
+   * @param {Object} session
+   */
+  _saveToHistory(session) {
+    const history = this.storage.get(SESSION_HISTORY_KEY) || [];
+    
+    // Keep only last 10 sessions
+    history.unshift({
+      session_id: session.session_id,
+      intent: session.intent,
+      status: session.status,
+      started_at: session.started_at,
+      ended_at: session.ended_at,
+      steps_completed: session.steps_completed,
+      total_steps: session.total_steps,
+    });
+    
+    if (history.length > 10) {
+      history.pop();
+    }
+    
+    this.storage.set(SESSION_HISTORY_KEY, history);
+  }
+
+  /**
+   * Get session history
+   * @returns {Array}
+   */
+  getSessionHistory() {
+    return this.storage.get(SESSION_HISTORY_KEY) || [];
+  }
+
+  /**
+   * Check if navigation is within the same flow
+   * @param {string} newRoute - New route
+   * @returns {boolean}
+   */
+  isInSameFlow(newRoute) {
+    const session = this.getActiveSession();
+    if (!session) return false;
+
+    const originalRoute = session.original_route;
+    
+    // Extract route base (first 2 segments)
+    const getRouteBase = (route) => route.split('/').filter(Boolean).slice(0, 2).join('/');
+    
+    const originalBase = getRouteBase(originalRoute);
+    const newBase = getRouteBase(newRoute);
+
+    // Same base = same flow
+    if (originalBase === newBase) return true;
+
+    // Check if intent keywords match new route
+    const intentKeywords = session.intent.split('_');
+    const inNewRoute = intentKeywords.some(keyword => 
+      newRoute.toLowerCase().includes(keyword.toLowerCase())
+    );
+
+    return inNewRoute;
+  }
+
+  /**
+   * Get progress percentage
+   * @returns {number} - 0-100
+   */
+  getProgress() {
+    const session = this.getActiveSession();
+    if (!session || session.total_steps === 0) return 0;
+    return Math.round((session.steps_completed / session.total_steps) * 100);
+  }
+
+  /**
+   * Clear all session data
+   */
+  clearAll() {
+    this.currentSession = null;
+    this.storage.clear();
+  }
+}
+
+export default SessionManager;