guideai-app 0.4.3 → 0.5.0

package/dist/utils/dataChannel.d.ts

@@ -0,0 +1,85 @@
+import { StoredMessage } from './messageStorage';
+import { ConversationManager } from './conversationManager';
+export type RecordingStatus = 'idle' | 'recording' | 'active' | 'processing' | 'playing';
+export declare const IGNORE_MESSAGE_TYPES: string[];
+export interface DataChannelCallbacks {
+    setIsDataChannelOpen: (open: boolean) => void;
+    setIsConnecting: (connecting: boolean) => void;
+    setStatus: (status: RecordingStatus) => void;
+    handleHighlightThenClick: (out: any) => Promise<boolean>;
+    handleHoverThenClick: (out: any) => Promise<boolean>;
+    handleHover: (out: any) => Promise<boolean>;
+    handleGoToAElmLink: (linkText: string, delay?: number) => Promise<boolean>;
+    onDataChannelClose: (pc: RTCPeerConnection) => void;
+    onDataChannelError: (event: Event) => void;
+    onDataChannelMessageError: (message: any) => void;
+    updateStreamingMessage: (delta: string) => void;
+    /** Reset streaming state when a new response starts (call on response.created) */
+    resetStreamingMessage?: () => void;
+    allMessages: StoredMessage[];
+    status: RecordingStatus;
+    organizationKey: string;
+    /** Ref to ConversationManager - use .current when logging (set in onSessionData before data channel opens) */
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+    updateSessionId?: (sessionId: string | null) => void;
+}
+export interface DataChannelConfig {
+    audioStream: MediaStream | null;
+    callbacks: DataChannelCallbacks;
+}
+export declare const BUFFERED_AMOUNT_THRESHOLD = 65536;
+export declare class DataChannelManager {
+    private dataChannel;
+    private peerConnection;
+    private callbacks;
+    private audioStream;
+    private sendQueue;
+    constructor(config: DataChannelConfig);
+    /**
+     * Create a new data channel on the peer connection
+     */
+    createDataChannel(pc: RTCPeerConnection): RTCDataChannel;
+    /**
+     * Setup all event handlers for the data channel
+     */
+    private setupEventHandlers;
+    /**
+     * Handle data channel open event
+     */
+    private handleChannelOpen;
+    /**
+     * Handle incoming messages from the data channel
+     */
+    private handleMessage;
+    /**
+     * Flush queued messages when buffer has drained
+     */
+    private flushSendQueue;
+    /**
+     * Send a message through the data channel.
+     * Queues the message if bufferedAmount exceeds threshold; it will be sent when buffer drains.
+     */
+    sendMessage(message: any): void;
+    /**
+     * Check if the data channel is open and ready
+     */
+    isOpen(): boolean;
+    /**
+     * Get the current buffered amount in bytes
+     */
+    getBufferedAmount(): number;
+    /**
+     * Check if the send buffer is full (above threshold)
+     */
+    isBufferFull(): boolean;
+    /**
+     * Get the current data channel
+     */
+    getDataChannel(): RTCDataChannel | null;
+    /**
+     * Close and cleanup the data channel
+     */
+    close(): void;
+}

package/dist/utils/elementInteractions.d.ts

@@ -1,7 +1,11 @@
 import { ElementInteractionType } from './constants';
+export interface ToolInput {
+    arguments: string;
+    name?: string;
+}
 export declare const HOVER_EFFECT_KEEP_ALIVE_TIME = 3000;
 export declare const createHoverEffect: (element: Element, initialRect: DOMRect, cursorElement?: HTMLElement | null, duration?: number) => Promise<void>;
-export declare const clickElement: (element: Element, rect: DOMRect, withEffects?: boolean) => Promise<void>;
+export declare const clickElement: (element: Element, rect: DOMRect, withEffects?: boolean, cursorElement?: HTMLElement | null) => Promise<void>;
 export declare const parseCustomSelector: (selector: string) => {
     type: "text" | "css" | "xpath";
     cssSelector?: string;
@@ -12,7 +16,8 @@ export declare const findElementBySelectorStrict: (selector: string) => Element
 export declare const findElementBySelector: (selector: string) => Element | null;
 export declare const interactWithElement: (element: Element, cursorElement: HTMLElement | null, state: ElementInteractionType, hoverTime?: number) => Promise<HTMLElement | null>;
 export declare const processSelectorsInteraction: (selectors: string | string[], isInteracting: boolean, setIsInteracting: (interacting: boolean) => void, onEachElement: (element: Element, cursor: HTMLElement | null, index: number) => Promise<HTMLElement | null>, onComplete?: (lastElement: Element | null, cursor: HTMLElement | null) => Promise<void>) => Promise<boolean>;
-export declare const Highlight_Tool: {
+export declare const parseArgs: (argsToUse: string) => Promise<any>;
+export declare const Highlight_Click_Tool: {
     type: string;
     name: string;
     description: string;
@@ -37,6 +42,37 @@ export declare const Highlight_Tool: {
         required: string[];
     };
 };
+export declare const Hover_Click_Tool: {
+    type: string;
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            selector: {
+                oneOf: ({
+                    type: string;
+                    description: string;
+                    items?: undefined;
+                } | {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                })[];
+                description: string;
+            };
+            hoverTime: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
 export declare const Hover_Tool: {
     type: string;
     name: string;

package/dist/utils/highlightThenClick.d.ts

@@ -1 +1,2 @@
-export declare const highlightThenClick: (selector: string | string[], isHighlighting: boolean, setIsHighlighting: (highlighting: boolean) => void) => Promise<boolean>;
+import { ToolInput } from "./elementInteractions";
+export declare const highlightThenClick: (out: ToolInput, isHighlighting: boolean, setIsHighlighting: (highlighting: boolean) => void) => Promise<boolean>;

package/dist/utils/hover.d.ts

@@ -0,0 +1,2 @@
+import { ToolInput } from './elementInteractions';
+export declare const hover: (out: ToolInput, isHovering: boolean, setIsHovering: (hovering: boolean) => void) => Promise<boolean>;

package/dist/utils/hoverThenClick.d.ts

@@ -1 +1,2 @@
-export declare const hoverThenClick: (selector: string | string[], isHovering: boolean, setIsHovering: (hovering: boolean) => void, hoverTime?: number) => Promise<boolean>;
+import { ToolInput } from './elementInteractions';
+export declare const hoverThenClick: (out: ToolInput, isHovering: boolean, setIsHovering: (hovering: boolean) => void) => Promise<boolean>;

package/dist/utils/isChromeExtension.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detects if the code is running inside a Chrome extension content script.
+ * Used for audio setup and other extension-specific behavior.
+ */
+export declare function isChromeExtension(): boolean;

package/dist/utils/localStorageHelper.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Centralized localStorage helper
+ * Tracks all localStorage keys used in the application
+ */
+declare const STORAGE_KEYS: {
+    readonly USER_UUID: "guideAI_userUUID";
+    readonly SESSION_ID: "guideAI_sessionId";
+    readonly CONVERSATION: "guideAI_conversation";
+    readonly HAS_INTERACTED: "guideAI_hasInteracted";
+    readonly IS_MUTED: "guideAI_isMuted";
+    readonly LOGGER_ENABLED: "guideAI_loggerEnabled";
+};
+/**
+ * Check if localStorage is available
+ */
+export declare const isLocalStorageAvailable: () => boolean;
+/**
+ * Get or create user UUID
+ * Creates a new UUID if one doesn't exist
+ */
+export declare const getUserUUID: () => string;
+/**
+ * Get session ID (active OpenAI session)
+ */
+export declare const getSessionId: () => string | null;
+/**
+ * Set session ID
+ */
+export declare const setSessionId: (sessionId: string | null) => void;
+/**
+ * Get has interacted flag
+ */
+export declare const getHasInteracted: () => boolean;
+/**
+ * Set has interacted flag
+ */
+export declare const setHasInteracted: (value: boolean) => void;
+/**
+ * Get is muted flag
+ */
+export declare const getIsMuted: () => boolean;
+/**
+ * Set is muted flag
+ */
+export declare const setIsMuted: (value: boolean) => void;
+/**
+ * Get logger enabled flag (used by Logger to persist enable state)
+ */
+export declare const getLoggerEnabled: () => boolean;
+/**
+ * Set logger enabled flag
+ */
+export declare const setLoggerEnabled: (value: boolean) => void;
+/**
+ * Export storage keys for reference (read-only)
+ */
+export { STORAGE_KEYS };

package/dist/utils/logger.d.ts

@@ -1,10 +1,55 @@
-/**
- * Standardized logging utility for GuideAI package
- * Provides consistent formatting and development gating across all components
- */
-type Component = 'GuideAI' | 'UserMetadata' | 'API' | 'TranscriptBox' | 'Onboarding';
+type Component = 'GuideAI' | 'API' | 'TranscriptBox' | 'Onboarding' | 'VisualContext' | 'MessageStorage' | 'DataChannel' | 'ConversationManager' | 'LocalStorageHelper' | 'WebRTCConnection';
 declare class Logger {
     private static formatMessage;
+    private static checkLoggingEnabled;
+    /**
+     * Initialize logger and attach to window for console access
+     * Call Logger.init() from browser console to enable logging.
+     * Restores persisted enabled state from localStorage if previously enabled.
+     */
+    static init(): void;
+    /**
+     * Enable logging from console, or for a specific component.
+     * Usage: GuideAILogger.enable() or GuideAILogger.enable('API')
+     */
+    static enable(component?: Component): void;
+    /**
+     * Disable logging from console, or for a specific component.
+     * Usage: GuideAILogger.disable() or GuideAILogger.disable('API')
+     */
+    static disable(component?: Component): void;
+    /**
+     * Enable or disable logging for a specific component
+     * Usage: GuideAILogger.setComponentEnabled('API', true)
+     */
+    static setComponentEnabled(component: Component, enabled: boolean): void;
+    /**
+     * Get current logging status
+     * Usage: GuideAILogger.getStatus()
+     */
+    static getStatus(): {
+        manualEnabled: boolean;
+        components: Record<Component, boolean>;
+    };
+    /**
+     * Disable logging for all components
+     * Usage: GuideAILogger.disableAllComponents()
+     */
+    static disableAllComponents(): void;
+    /**
+     * Enable logging for all components
+     * Usage: GuideAILogger.enableAllComponents()
+     */
+    static enableAllComponents(): void;
+    /**
+     * Display help information listing all available Logger functions
+     * Usage: GuideAILogger.help()
+     */
+    static help(): void;
+    /**
+     * Standard info logging - only in development
+     */
+    static info(component: Component, action: string, data?: any): void;
     /**
      * Standard info logging - only in development
      */
@@ -29,9 +74,5 @@ declare class Logger {
      * Conversation flow tracking
      */
     static conversation(action: string, data?: any): void;
-    /**
-     * Metadata tracking logging
-     */
-    static metadata(action: string, data?: any): void;
 }
 export default Logger;

package/dist/utils/messageStorage.d.ts

@@ -1,19 +1,27 @@
 export interface StoredMessage {
     content: string;
-    sender: 'GUIDEAI' | 'HUMAN';
+    sender: 'GUIDEAI' | 'HUMAN' | 'SYSTEM';
     timestamp: number;
 }
 export interface StoredConversation {
     conversationId: string;
+    conversationKey?: string;
     messages: StoredMessage[];
     timestamp: number;
     organizationKey: string;
+    keyExpiresAt?: number;
+    sessionExpiresAt?: number;
+    user?: string;
 }
-export declare const CONVERSATION_STORAGE_KEY = "guideai_conversation";
+export declare const CONVERSATION_STORAGE_KEY = "guideAI_conversation";
 export declare const CONVERSATION_EXPIRY_MINUTES = 30;
 export declare const MAX_STORED_MESSAGES = 100;
 export declare const isLocalStorageAvailable: () => boolean;
-export declare const isConversationExpired: (conversation: StoredConversation) => boolean;
+export declare const initializeConversationStorage: (organizationKey: string, conversationId: string) => void;
+export declare const isSessionExpired: (organizationKey: string) => boolean;
+export declare const isConversationExpired: (organizationKey: string) => boolean;
+export declare const updateSessionExpiresAt: (organizationKey: string, sessionExpiresAt: number) => void;
+export declare const getConversationId: (organizationKey: string) => string | null;
 export declare const saveConversationToStorage: (conversation: StoredConversation) => void;
 export declare const loadConversationFromStorage: () => StoredConversation | null;
 export declare const clearConversationStorage: () => void;
@@ -24,3 +32,8 @@ export declare const checkForStoredConversation: (currentOrganizationKey: string
     messages: StoredMessage[] | null;
 };
 export declare const formatConversationContext: (messages: StoredMessage[], maxMessages?: number) => string;
+/**
+ * Get messages from localStorage as the single source of truth
+ * This ensures all components read from the same storage location
+ */
+export declare const getMessagesFromStorage: (organizationKey: string) => StoredMessage[];

package/dist/utils/positionUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Position and layout utilities for GuideAI components.
+ * Handles mic position, popup position, transcript position, and z-index config.
+ */
+import type { GuideAIPosition, PopupPosition, TranscriptPosition } from '../types/GuideAI.types';
+export declare const DEFAULT_POSITION: {
+    readonly bottom: "20px";
+    readonly left: "50%";
+    readonly transform: "translateX(-50%)";
+};
+export interface ZIndexConfig {
+    main: number;
+    transcript: number;
+    microphone: number;
+    onboarding: number;
+}
+/**
+ * Get default mic position (bottom center).
+ */
+export declare function getDefaultPosition(): typeof DEFAULT_POSITION;
+/**
+ * Calculate popup position based on mic position prop.
+ * Used for onboarding and welcome bubble placement.
+ */
+export declare function calculatePositionFromProp(position?: GuideAIPosition | null): PopupPosition;
+/**
+ * Get transcript box position (left or right) based on mic position.
+ */
+export declare function getTranscriptPosition(transcriptOptions?: {
+    position?: TranscriptPosition;
+} | null, position?: GuideAIPosition | null): TranscriptPosition;
+/**
+ * Get z-index configuration from position prop.
+ */
+export declare function getZIndexConfig(position?: GuideAIPosition | null): ZIndexConfig;
+/**
+ * Get position styles for mic/base component (position only, no z-index).
+ */
+export declare function getPositionStyles(position?: GuideAIPosition | null): Record<string, string>;

package/dist/utils/webrtcConnection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * WebRTC connection manager for OpenAI Realtime API.
+ * Uses unified initialize endpoint (conversation + WebRTC SDP exchange).
+ * See: https://developers.openai.com/api/docs/guides/realtime-webrtc
+ */
+import { DataChannelManager, DataChannelConfig } from './dataChannel';
+/** Ref-like holder for mutable references (avoids React dependency in utils) */
+export interface RefLike<T> {
+    current: T | null;
+}
+export interface InitializeSessionData {
+    id: string;
+}
+export interface WebRTCConnectionConfig {
+    /** Microphone stream, or null for text-only mode */
+    audioStream: MediaStream | null;
+    /** Initialize endpoint URL (e.g. /api/initialize) - returns { id, answerSdp } */
+    initializeEndpoint: string;
+    /** Payload for initialize (organizationKey, user, conversationId */
+    initializePayload: {
+        organizationKey: string;
+        user?: string;
+        conversationId?: string | null;
+    };
+    /** Called when session data is received (id) */
+    onSessionData?: (data: InitializeSessionData) => void;
+    /** Whether running in Chrome extension content script (affects audio setup) */
+    isContentScript?: boolean;
+    /** Config for the data channel manager */
+    dataChannelConfig: DataChannelConfig;
+    /** Optional refs to populate with created objects */
+    refs?: {
+        peerConnection?: RefLike<RTCPeerConnection>;
+        dataChannelManager?: RefLike<DataChannelManager>;
+        audioElement?: RefLike<HTMLAudioElement>;
+    };
+    /** Optional existing audio element to reuse (avoids duplicate elements on reconnect) */
+    existingAudioElement?: HTMLAudioElement | null;
+}
+/**
+ * Manages WebRTC connection via unified initialize endpoint.
+ * Handles peer connection setup, SDP exchange (via initialize), and data channel creation.
+ */
+export declare class WebRTCConnection {
+    private config;
+    private peerConnection;
+    private dataChannelManager;
+    private audioElement;
+    constructor(config: WebRTCConnectionConfig);
+    /**
+     * Establish WebRTC connection via initialize endpoint.
+     */
+    connect(): Promise<boolean>;
+    private createAudioElement;
+    close(): void;
+}

package/dist/visualContext/VisualContextScheduler.d.ts

@@ -4,40 +4,37 @@ export declare class VisualContextScheduler {
     private screenshotProvider;
     private isRunning;
     private isCaptureInFlight;
-    private hasPendingCapture;
-    private pendingReason;
-    private lastHash;
     private lastCaptureAt;
-    private lastScrollAt;
-    private lastDomBurstAt;
-    private domChangeCounter;
-    private domBurstWindowMs;
-    private domBurstThreshold;
     private minIntervalMs;
-    private scrollDebounceMs;
-    private scrollTimer;
     private mode;
     private buttonObserver;
-    private domObserver;
+    private intervalId;
     private targetWidth;
     private rootElement;
     private quality;
     private minQuality;
     private maxBytes;
     private onFrame;
+    private isBufferFull;
+    private hasSignificantDomChange;
+    private markDomChangeConsumed;
+    private onError;
+    private pendingRequestResolve;
     constructor(getContainer: () => HTMLElement | null, screenshotProvider: ScreenshotProvider, onFrame: (frame: ScreenshotFrame) => void, options?: {
         targetWidth?: number;
         quality?: number;
         minQuality?: number;
         maxBytes?: number;
+        isBufferFull?: () => boolean;
+        hasSignificantDomChange?: () => boolean;
+        markDomChangeConsumed?: () => void;
+        onError?: (message: string, data?: any) => void;
     });
     setRootElement(root: HTMLElement | ShadowRoot | Document): void;
     start(): void;
     stop(): void;
     private observeButtonState;
-    private observeDomChanges;
-    private observeScroll;
     scheduleCapture(reason: 'preview' | 'final' | 'change'): void;
+    requestCapture(): Promise<ScreenshotFrame | null>;
     private performCapture;
-    private maybeRunPending;
 }

package/dist/visualContext/domChangeTracker.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DOM change tracker that detects significant host-page changes.
+ * Excludes only the GuideAI widget container (transcript, mic, etc.) - not by class name.
+ * Detects SPA navigation (route changes, visibility changes) and structural DOM changes.
+ */
+export interface DomChangeTrackerOptions {
+    /** Returns the GuideAI widget root element - mutations inside it are excluded */
+    getGuideaiRoot: () => HTMLElement | null;
+}
+export interface DomChangeTracker {
+    hasSignificantChange: () => boolean;
+    markCaptured: () => void;
+    start: () => void;
+    stop: () => void;
+}
+export declare function createDomChangeTracker(options: DomChangeTrackerOptions): DomChangeTracker;

package/dist/visualContext/index.d.ts

@@ -1,5 +1,12 @@
+/**
+ * Visual Context module for GuideAI
+ * Provides screenshot capture, storage, image sending, debug overlay,
+ * and the useVisualContext hook for integration.
+ */
 export { VisualContextStore } from './VisualContextStore';
 export { VisualContextScheduler } from './VisualContextScheduler';
 export { DebugOverlay } from './debug-overlay';
+export { useVisualContext } from './useVisualContext';
 export { createDefaultScreenshotProvider, getDefaultScreenshotProvider } from './defaultProvider';
-export type { ScreenshotResponse, ScreenshotFrame, ScreenshotOptions, ScreenshotProvider, VisualContextConfig } from './types';
+export type { ScreenshotResponse, ScreenshotFrame, ScreenshotDetail, ScreenshotOptions, ScreenshotProvider, VisualContextConfig } from './types';
+export { MAX_IMAGE_MESSAGE_BYTES } from './types';

package/dist/visualContext/types.d.ts

@@ -24,6 +24,10 @@ export type ScreenshotFrame = {
     sentToLLM?: boolean;
     llmReceivedAt?: number;
 };
+/** Alias for ScreenshotFrame, used for event payload compatibility */
+export type ScreenshotDetail = ScreenshotFrame;
+/** Max size for WebRTC image message payload (bytes) */
+export declare const MAX_IMAGE_MESSAGE_BYTES = 200000;
 export type ScreenshotOptions = {
     targetElement?: HTMLElement;
     targetWidth?: number;

package/dist/visualContext/useVisualContext.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useVisualContext - React hook that encapsulates screenshot capture, storage,
+ * image sending, and debug overlay for the GuideAI visual context feature.
+ */
+import { ScreenshotFrame, VisualContextConfig } from './types';
+export type RecordingStatus = 'idle' | 'recording' | 'active' | 'processing' | 'playing';
+export interface UseVisualContextParams {
+    options: VisualContextConfig;
+    sendMessage: (msg: any) => void;
+    isDataChannelOpen: () => boolean;
+    status: RecordingStatus;
+    isConversationActive: boolean;
+    getContainer: () => HTMLElement | null;
+    onLogVisualContext: (content: string, data?: any) => void;
+    onVisualContextError?: (message: string, data?: any) => void;
+    isBufferFull?: () => boolean;
+}
+export interface UseVisualContextReturn {
+    frames: ScreenshotFrame[];
+    debugEnabled: boolean;
+    setDebugEnabled: (value: boolean | ((prev: boolean) => boolean)) => void;
+    showGallery: boolean;
+    setShowGallery: (value: boolean | ((prev: boolean) => boolean)) => void;
+    latencyMs: number | null;
+    windowAPI: Record<string, any>;
+    captureForMessage: () => Promise<{
+        type: 'input_image';
+        image_url: string;
+    } | null>;
+    cleanupOnConversationEnd: () => void;
+}
+export declare function useVisualContext(React: typeof import('react'), params: UseVisualContextParams): UseVisualContextReturn;

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "guideai-app",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "AI-powered guide component for React applications",
   "main": "dist/GuideAI.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/GuideAI/guideai.git",
@@ -13,7 +16,11 @@
     "registry": "https://npm.pkg.github.com"
   },
   "scripts": {
-    "build": "webpack && tsc --emitDeclarationOnly && javascript-obfuscator dist/GuideAI.js --config obfuscator.json --output dist/GuideAI.js",
+    "build": "webpack --mode=production && tsc --emitDeclarationOnly && javascript-obfuscator dist/GuideAI.js --config obfuscator.json --output dist/GuideAI.js",
+    "build:dev": "webpack --mode=development && tsc --emitDeclarationOnly",
+    "watch": "webpack --mode=development --watch & tsc --emitDeclarationOnly --watch",
+    "dev": "npm run watch",
+    "serve:local": "npm run build:dev && npx serve -l 8080 dist",
     "prepare": "npm run build",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -29,13 +36,12 @@
   "license": "ISC",
   "dependencies": {
     "@google/generative-ai": "^0.2.1",
-    "guideai-app": "^0.3.4",
     "html2canvas": "^1.4.1",
     "openai": "^4.28.0"
   },
   "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
-    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -56,4 +62,4 @@
     "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1"
   }
-}
+}

package/.workflow-test

@@ -1 +0,0 @@
-# Workflow Test