handhold-sdk 1.0.0

package/src/core/Config.js

@@ -0,0 +1,207 @@
+/**
+ * Hand Hold SDK - Configuration Management
+ * Handles SDK configuration with defaults and validation
+ */
+
+import { DEFAULT_BASE_URL } from './defaults.js';
+
+const DEFAULT_CONFIG = {
+  // Required
+  apiKey: null,
+  baseUrl: null,
+
+  // UI Customization
+  theme: 'light',                        // 'light' | 'dark'
+  position: 'bottom-right',              // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+  primaryColor: '#004AF5',               // Primary accent color (PaidHR Blue 500)
+  zIndex: 999990,                        // Base z-index for SDK elements
+
+  // Behavior
+  minHighlightConfidence: 0.70,          // Minimum confidence to highlight element
+  sessionInactivityTimeout: 600000,      // Session timeout (10 minutes)
+  autoOpenOnLoad: false,                 // Auto-open help widget on page load
+  deferRestore: false,                   // If true, init() skips session restore; the host calls
+                                         // HandHold.restoreSession() after patching its own renderer
+                                         // (Phase 1.4 — avoids the legacy widget drawing the confirm)
+  enableMultiPageTracking: true,         // Track guidance across pages
+  showHelpButton: true,                  // Show floating help button
+  showStepHighlight: true,               // Draw the SDK's own overlay/arrow/tooltip on the
+                                         // current step's element. Turn OFF when the host
+                                         // renders its own on-page indicator (avoids a
+                                         // duplicate highlight); completion is still detected
+                                         // — the SDK watches the real element either way.
+  agentMode: false,                      // "Do it for me" agent (H5) — off unless the tenant enables it
+  enableScreenshots: true,               // Capture a page screenshot (html2canvas) for vision intent
+                                         // extraction. Turn OFF on sites using modern CSS colors
+                                         // (oklch/oklab, e.g. Tailwind v4): html2canvas can't parse
+                                         // them and stalls for seconds before failing. The agent
+                                         // never needs screenshots (it uses the DOM engine).
+
+  // API
+  apiTimeout: 30000,                     // API request timeout (30 seconds)
+  retryAttempts: 3,                      // Number of retry attempts
+  retryDelay: 1000,                      // Delay between retries
+
+  // Debug
+  debug: false,                          // Enable debug mode
+  logLevel: 'warn',                      // 'error' | 'warn' | 'info' | 'debug'
+
+  // Help Button
+  helpButtonText: '?',                   // Text/icon for help button
+  helpButtonAriaLabel: 'Open help',      // Accessibility label
+
+  // Widget
+  widgetTitle: 'How can I help?',        // Widget title
+  widgetPlaceholder: 'Type your question...', // Search input placeholder
+  maxIntents: 6,                         // Maximum intents to show
+};
+
+class Config {
+  constructor(userConfig = {}) {
+    // Validate required fields
+    if (!userConfig.apiKey) {
+      throw new Error('[HandHold Config] apiKey is required');
+    }
+    // baseUrl may come from the call, or the build-time baked default
+    // (HANDHOLD_DEFAULT_BASE_URL). Only an unresolvable baseUrl is an error.
+    const resolvedBaseUrl = userConfig.baseUrl || DEFAULT_BASE_URL;
+    if (!resolvedBaseUrl) {
+      throw new Error(
+        '[HandHold Config] baseUrl is required — pass baseUrl, set data-handhold-base-url, ' +
+        'or build the SDK with HANDHOLD_DEFAULT_BASE_URL'
+      );
+    }
+
+    // Merge with defaults
+    this._config = { ...DEFAULT_CONFIG, ...userConfig, baseUrl: resolvedBaseUrl };
+
+    // Normalize baseUrl (remove trailing slash)
+    this._config.baseUrl = this._config.baseUrl.replace(/\/$/, '');
+
+    // Validate values
+    this._validate();
+
+    // Freeze config to prevent modification
+    Object.freeze(this._config);
+  }
+
+  /**
+   * Validate configuration values
+   */
+  _validate() {
+    const { theme, position, logLevel, minHighlightConfidence } = this._config;
+
+    // Validate theme
+    if (!['light', 'dark'].includes(theme)) {
+      console.warn(`[HandHold Config] Invalid theme "${theme}", using "light"`);
+      this._config.theme = 'light';
+    }
+
+    // Validate position
+    const validPositions = ['bottom-right', 'bottom-left', 'top-right', 'top-left'];
+    if (!validPositions.includes(position)) {
+      console.warn(`[HandHold Config] Invalid position "${position}", using "bottom-right"`);
+      this._config.position = 'bottom-right';
+    }
+
+    // Validate log level
+    const validLogLevels = ['error', 'warn', 'info', 'debug'];
+    if (!validLogLevels.includes(logLevel)) {
+      console.warn(`[HandHold Config] Invalid logLevel "${logLevel}", using "warn"`);
+      this._config.logLevel = 'warn';
+    }
+
+    // Validate confidence threshold
+    if (minHighlightConfidence < 0 || minHighlightConfidence > 1) {
+      console.warn(`[HandHold Config] minHighlightConfidence must be between 0 and 1, using 0.85`);
+      this._config.minHighlightConfidence = 0.85;
+    }
+  }
+
+  /**
+   * Get configuration value
+   * @param {string} key - Config key
+   * @returns {*} - Config value
+   */
+  get(key) {
+    return this._config[key];
+  }
+
+  /**
+   * Get all configuration as object
+   * @returns {Object}
+   */
+  getAll() {
+    return { ...this._config };
+  }
+
+  /**
+   * Check if debug mode is enabled
+   * @returns {boolean}
+   */
+  get isDebug() {
+    return this._config.debug;
+  }
+
+  // Convenience getters
+  get apiKey() { return this._config.apiKey; }
+  get baseUrl() { return this._config.baseUrl; }
+  get theme() { return this._config.theme; }
+  get position() { return this._config.position; }
+  get primaryColor() { return this._config.primaryColor; }
+  get zIndex() { return this._config.zIndex; }
+  get agentMode() { return this._config.agentMode; }
+  get minHighlightConfidence() { return this._config.minHighlightConfidence; }
+  get sessionInactivityTimeout() { return this._config.sessionInactivityTimeout; }
+  get enableMultiPageTracking() { return this._config.enableMultiPageTracking; }
+  get logLevel() { return this._config.logLevel; }
+  get maxIntents() { return this._config.maxIntents; }
+  get showHelpButton() { return this._config.showHelpButton; }
+  get apiTimeout() { return this._config.apiTimeout; }
+  get retryAttempts() { return this._config.retryAttempts; }
+  get retryDelay() { return this._config.retryDelay; }
+  get widgetTitle() { return this._config.widgetTitle; }
+  get widgetPlaceholder() { return this._config.widgetPlaceholder; }
+  get helpButtonText() { return this._config.helpButtonText; }
+  get helpButtonAriaLabel() { return this._config.helpButtonAriaLabel; }
+  get autoOpenOnLoad() { return this._config.autoOpenOnLoad; }
+
+  /**
+   * Get CSS variables for theming
+   * @returns {Object}
+   */
+  getCSSVariables() {
+    const isDark = this._config.theme === 'dark';
+    
+    return {
+      '--hh-primary': this._config.primaryColor,
+      '--hh-primary-light': this._adjustColor(this._config.primaryColor, 40),
+      '--hh-primary-dark': this._adjustColor(this._config.primaryColor, -40),
+      '--hh-bg': isDark ? '#1e1e1e' : '#ffffff',
+      '--hh-bg-secondary': isDark ? '#2d2d2d' : '#f5f5f5',
+      '--hh-text': isDark ? '#ffffff' : '#333333',
+      '--hh-text-secondary': isDark ? '#b0b0b0' : '#666666',
+      '--hh-border': isDark ? '#404040' : '#e0e0e0',
+      '--hh-shadow': isDark ? 'rgba(0, 0, 0, 0.5)' : 'rgba(0, 0, 0, 0.15)',
+      '--hh-overlay': 'rgba(0, 0, 0, 0.5)',
+      '--hh-z-index': this._config.zIndex,
+    };
+  }
+
+  /**
+   * Adjust color brightness
+   * @param {string} color - Hex color
+   * @param {number} amount - Amount to adjust (-255 to 255)
+   * @returns {string}
+   */
+  _adjustColor(color, amount) {
+    const hex = color.replace('#', '');
+    const r = Math.max(0, Math.min(255, parseInt(hex.substr(0, 2), 16) + amount));
+    const g = Math.max(0, Math.min(255, parseInt(hex.substr(2, 2), 16) + amount));
+    const b = Math.max(0, Math.min(255, parseInt(hex.substr(4, 2), 16) + amount));
+    return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+  }
+}
+
+export default Config;
+export { DEFAULT_CONFIG };

package/src/core/UiState.js

@@ -0,0 +1,83 @@
+/**
+ * Hand Hold SDK - UiState (Phase 2.1)
+ *
+ * The single source of truth for the widget UI. A tiny observable store shaped
+ * for React's useSyncExternalStore: getSnapshot() returns a STABLE object
+ * reference until setState() replaces it, and subscribe(fn) is notified on every
+ * change. The legacy DOM widget and any host renderer (the React demo) both read
+ * from this one store, so the two can no longer drift.
+ *
+ * State shape (all serializable):
+ *   view           'menu' | 'loading' | 'guidance' | 'article' | 'error'
+ *                  | 'clarification' | 'completion'
+ *   isOpen         whether the widget panel is open
+ *   intents        scanned intent list for the menu
+ *   guidance       active guidance object (steps, current_step, agent_plan, …)
+ *   article        KB article being shown
+ *   error          error message string
+ *   clarification  { question, options } for an ambiguous query
+ *   completion     completion label
+ *   loadingLabel   label for the loading view
+ *   confirm        { message } for the session-restore confirm
+ */
+
+const DEFAULT_STATE = {
+  view: 'menu',
+  isOpen: false,
+  intents: [],
+  guidance: null,
+  article: null,
+  error: null,
+  clarification: null,
+  completion: null,
+  loadingLabel: null,
+  confirm: null,
+};
+
+export default class UiState {
+  constructor(initial = {}) {
+    this._state = { ...DEFAULT_STATE, ...initial };
+    this._listeners = new Set();
+    // Bound so it can be passed directly as useSyncExternalStore(subscribe, …).
+    this.subscribe = this.subscribe.bind(this);
+    this.getSnapshot = this.getSnapshot.bind(this);
+  }
+
+  /** Current immutable snapshot (stable reference until setState). */
+  getSnapshot() {
+    return this._state;
+  }
+
+  /**
+   * Subscribe to state changes. The listener is called with the new snapshot.
+   * @returns {() => void} unsubscribe
+   */
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  /** Merge a partial update, producing a new snapshot, and notify listeners. */
+  setState(partial) {
+    this._state = { ...this._state, ...partial };
+    this._notify();
+  }
+
+  /** Reset to defaults (e.g. on close/destroy). */
+  reset() {
+    this._state = { ...DEFAULT_STATE };
+    this._notify();
+  }
+
+  _notify() {
+    for (const listener of this._listeners) {
+      // One bad subscriber must not break the others (or the state update).
+      try {
+        listener(this._state);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[HandHold UiState] subscriber threw:', e);
+      }
+    }
+  }
+}

package/src/core/defaults.js

@@ -0,0 +1,20 @@
+/**
+ * Hand Hold SDK - Build-time defaults
+ *
+ * The default backend URL is settable by whoever builds the bundle. A Model B
+ * self-hoster runs:
+ *
+ *     HANDHOLD_DEFAULT_BASE_URL=https://help.acme.com npm run build
+ *
+ * and the served `handhold.js` already points at THEIR backend — so their pages
+ * only need `data-handhold-api-key`, not `data-handhold-base-url` on every embed.
+ *
+ * `__HANDHOLD_DEFAULT_BASE_URL__` is replaced at build time by webpack's
+ * DefinePlugin. The `typeof` guard keeps this safe under jest/node (where the
+ * global is not defined) — there it resolves to '' and callers fall back to an
+ * explicit value or same-origin.
+ */
+export const DEFAULT_BASE_URL =
+  (typeof __HANDHOLD_DEFAULT_BASE_URL__ !== 'undefined' && __HANDHOLD_DEFAULT_BASE_URL__) || '';
+
+export default DEFAULT_BASE_URL;

package/src/events.js

@@ -0,0 +1,59 @@
+/**
+ * Hand Hold SDK - Event registry (Phase 6.3)
+ *
+ * One place that names every EventBus event. Stringly-typed event names caused
+ * real bugs (an unhandled 'ui:highlight_request', a missing 'session:close'
+ * wiring): a typo in an emit or on had no compile-time signal. Reference these
+ * constants instead of raw strings so emit and on always agree.
+ *
+ * Values are IDENTICAL to the historical string literals, so this can be
+ * adopted incrementally — code still using a raw string interops with code
+ * using the constant.
+ */
+export const EVENTS = Object.freeze({
+  // Lifecycle
+  READY: 'handhold:ready',
+  CLOSED: 'handhold:closed',
+  STATE_CHANGED: 'state:changed',
+
+  // User/host commands (host -> SDK)
+  HELP_OPEN: 'help:open',
+  QUERY_SUBMITTED: 'query:submitted',
+  INTENT_SELECTED: 'intent:selected',
+  STEP_DONE: 'step:done',
+  STEP_SKIP: 'step:skip',
+  STEP_BACK: 'step:back',
+  SESSION_CLOSE: 'session:close',
+  HELP_MINIMIZE: 'help:minimize',
+  HELP_SHOW_HINT: 'help:show_hint',
+  CONFIRM_RESPONSE: 'hh:confirm:response',
+
+  // Page / navigation
+  NAVIGATION_CHANGED: 'navigation:changed',
+  PAGE_DOM_CHANGED: 'page:dom_changed',
+  STEP_SHOW_UI: 'step:show_ui',
+  SELECTION_EXPLAIN: 'selection:explain',
+  UI_HIGHLIGHT_REQUEST: 'ui:highlight_request',
+
+  // Highlighting (UICoach)
+  HIGHLIGHT_SHOWN: 'highlight:shown',
+  HIGHLIGHT_NOT_FOUND: 'highlight:not_found',
+
+  // Session lifecycle (SessionManager)
+  SESSION_STARTED: 'session:started',
+  SESSION_UPDATED: 'session:updated',
+  SESSION_NAVIGATION: 'session:navigation',
+  SESSION_COMPLETED: 'session:completed',
+  SESSION_STEP_ADVANCED: 'session:step_advanced',
+  SESSION_ENDED: 'session:ended',
+
+  // Agent mode
+  AGENT_START: 'agent:start',
+  AGENT_STOP: 'agent:stop',
+  AGENT_ACTIVITY: 'agent:activity',
+  AGENT_CONFIRM: 'agent:confirm',
+  AGENT_ASK: 'agent:ask',
+  AGENT_DONE: 'agent:done',
+});
+
+export default EVENTS;

package/src/index.js

@@ -0,0 +1,77 @@
+/**
+ * Hand Hold SDK - Entry Point
+ * 
+ * Context-aware, in-app help system that provides:
+ * - Intent-based help menus
+ * - Visual UI guidance with element highlighting
+ * - Multi-page workflow tracking
+ * - Conversational fallback for free-text queries
+ * 
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import HandHold, { HandHold as HandHoldClass } from './HandHold.js';
+import { DEFAULT_BASE_URL } from './core/defaults.js';
+
+// Export core modules for advanced usage
+export { default as Config } from './core/Config.js';
+export { default as Logger } from './utils/Logger.js';
+export { default as EventBus } from './utils/eventBus.js';
+export { default as APIClient } from './api/APIClient.js';
+export { default as PageObserver } from './observers/PageObserver.js';
+export { default as NavigationObserver } from './observers/NavigationObserver.js';
+export { default as ElementScanner } from './observers/ElementScanner.js';
+export { default as IntentExtractor } from './intent/IntentExtractor.js';
+export { default as ActionVerbMap } from './intent/ActionVerbMap.js';
+export { default as SessionManager } from './session/SessionManager.js';
+export { default as SessionStorage } from './session/SessionStorage.js';
+export { default as HelpWidget } from './ui/HelpWidget.js';
+export { default as UICoach } from './ui/UICoach.js';
+
+// Export utilities
+export * as domUtils from './utils/domUtils.js';
+export * as stringUtils from './utils/stringUtils.js';
+
+// Event registry + UI-state store (Phase 2 / 6.3)
+export { default as EVENTS } from './events.js';
+export { default as UiState } from './core/UiState.js';
+
+// Export HandHold class for custom instantiation
+export { HandHoldClass };
+
+// Default export is the singleton instance
+export default HandHold;
+
+// Attach to window for non-module usage
+if (typeof window !== 'undefined') {
+  window.HandHold = HandHold;
+  
+  // Auto-initialize if data attributes are present
+  window.addEventListener('DOMContentLoaded', () => {
+    const script = document.querySelector('script[data-handhold-api-key]');
+    
+    if (script) {
+      const apiKey = script.getAttribute('data-handhold-api-key');
+      // Backend URL precedence: explicit attribute > build-time baked default
+      // (HANDHOLD_DEFAULT_BASE_URL) > same-origin (works when the API is reverse
+      // -proxied under the app's domain). No dead external default.
+      const baseUrl = script.getAttribute('data-handhold-base-url')
+        || DEFAULT_BASE_URL
+        || (typeof window !== 'undefined' ? window.location.origin : '');
+      const theme = script.getAttribute('data-handhold-theme') || 'light';
+      const position = script.getAttribute('data-handhold-position') || 'bottom-right';
+      const debug = script.getAttribute('data-handhold-debug') === 'true';
+      
+      HandHold.init({
+        apiKey,
+        baseUrl,
+        theme,
+        position,
+        debug
+      }).catch(error => {
+        console.error('[HandHold] Auto-initialization failed:', error);
+      });
+    }
+  });
+}