Skip to content

API Reference

Jump to bottom
Wei Xuan edited this page Feb 7, 2026 · 1 revision

API Reference

Complete API reference for the Web Guide Chrome Extension.

Table of Contents

Content Script API

The content script exposes two main objects: PageExtractor and VisualGuide.

PageExtractor

Handles all DOM reading and data extraction.

extractPageData()

Extracts comprehensive page data for AI processing.

Returns: Object

{
  url: String,           // Current page URL
  title: String,         // Page title
  text: String,          // Visible text content (truncated)
  elements: Array,       // Interactive elements
  headings: Array,       // Page headings (h1-h6)
  navigation: Array      // Navigation links
}

Example:

const pageData = PageExtractor.extractPageData();
console.log(pageData.elements.length); // Number of interactive elements

getInteractiveElements()

Finds all interactive elements on the page.

Returns: Array<Object>

[
  {
    tag: String,        // Element tag name (lowercase)
    text: String,       // Visible text or placeholder
    selector: String,   // Generated CSS selector
    visible: Boolean,   // Whether element is visible
    type: String        // Input type (for inputs)
  }
]

Example:

const buttons = PageExtractor.getInteractiveElements()
  .filter(el => el.tag === 'button');

getPageText()

Extracts visible text content from the page.

Returns: String (max 5000 characters)

Example:

const text = PageExtractor.getPageText();

getHeadings()

Extracts all heading elements (h1-h6).

Returns: Array<Object>

[
  {
    level: Number,      // 1-6
    text: String,       // Heading text
    selector: String    // CSS selector
  }
]

generateSelector(element)

Generates a stable CSS selector for any DOM element.

Parameters:

  • element (HTMLElement) - The DOM element

Returns: String - CSS selector

Strategy:

  1. ID if available (#id)
  2. First class name if available (.classname)
  3. Tag name as fallback

Example:

const button = document.querySelector('button');
const selector = PageExtractor.generateSelector(button);
// Returns: "#submit-btn" or ".btn-primary" or "button"

isVisible(element)

Checks if an element is visible in the viewport.

Parameters:

  • element (HTMLElement) - Element to check

Returns: Boolean

Checks:

  • Display is not 'none'
  • Visibility is not 'hidden'
  • Opacity is not 0
  • Has dimensions (width/height > 0)

VisualGuide

Handles all visual feedback rendering.

highlightElement(selector, description)

Highlights an element with arrow, tooltip, and overlay.

Parameters:

  • selector (String) - CSS selector for target element
  • description (String) - Human-readable description

Returns: void

Actions:

  1. Scrolls element into view (smooth)
  2. Creates animated arrow above element
  3. Shows tooltip with description
  4. Adds pulsing highlight overlay
  5. Auto-removes after 5 seconds or on click

Example:

VisualGuide.highlightElement(
  '#search-input',
  'This is the search input field'
);

createArrow(element)

Creates an animated arrow pointing to an element.

Parameters:

  • element (HTMLElement) - Target element

Returns: HTMLElement - The arrow element

Styling:

  • Position: Fixed, above element
  • Animation: Bounce
  • Color: Red (#ea4335)
  • Z-index: 1000000

createTooltip(element, text)

Creates a tooltip next to an element.

Parameters:

  • element (HTMLElement) - Target element
  • text (String) - Tooltip content

Returns: HTMLElement - The tooltip element

Positioning:

  • Attempts to position above element
  • Falls back to below if insufficient space
  • Adjusts horizontally to stay in viewport

createHighlight(element)

Creates a pulsing highlight overlay on an element.

Parameters:

  • element (HTMLElement) - Target element

Returns: HTMLElement - The highlight element

Features:

  • Pulsing animation
  • Semi-transparent background
  • Colored border
  • Click-to-dismiss

clearHighlights()

Removes all visual guide elements from the page.

Returns: void

Removes:

  • All arrows (.webguide-arrow)
  • All tooltips (.webguide-tooltip)
  • All highlights (.webguide-highlight)

showAnimatedPath(steps) ⚠️ Placeholder

Future feature for multi-step guidance.

Parameters:

  • steps (Array) - Array of step objects

Planned Structure:

[
  {
    selector: String,
    action: String,
    description: String
  }
]

Message Passing API

Communication between popup and content scripts using Chrome's message passing.

From Popup to Content Script

Get Page Data

Message:

chrome.tabs.sendMessage(tabId, 
  { action: 'getPageData' },
  (response) => {
    console.log(response.data);
  }
);

Response:

{
  data: {
    url: String,
    title: String,
    text: String,
    elements: Array,
    headings: Array
  }
}

Highlight Element

Message:

chrome.tabs.sendMessage(tabId, {
  action: 'highlightElement',
  selector: '#submit-button',
  description: 'This is the submit button'
});

Response: None (fire-and-forget)

Clear Highlights

Message:

chrome.tabs.sendMessage(tabId, {
  action: 'clearHighlights'
});

Message Listener Setup

In content.js:

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'getPageData') {
    const data = PageExtractor.extractPageData();
    sendResponse({ data });
    return true; // Async response
  }
  
  if (request.action === 'highlightElement') {
    VisualGuide.highlightElement(request.selector, request.description);
  }
  
  if (request.action === 'clearHighlights') {
    VisualGuide.clearHighlights();
  }
});

External APIs

Groq API

Endpoint

POST https://api.groq.com/openai/v1/chat/completions

Headers

{
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

Request Body

{
  "model": "llama-3.3-70b-versatile",
  "messages": [
    {
      "role": "user",
      "content": "Your prompt with page context"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "top_p": 1,
  "stream": false
}

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "llama-3.3-70b-versatile",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Response text with optional [HIGHLIGHT_ELEMENT]{...}[/HIGHLIGHT_ELEMENT]"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

Special Response Format

For element highlighting, responses include:

Regular response text here.

[HIGHLIGHT_ELEMENT]
{
  "selector": "#search-input",
  "description": "This is the search box"
}
[/HIGHLIGHT_ELEMENT]

Parsing:

const match = response.match(/\[HIGHLIGHT_ELEMENT\](.*?)\[\/HIGHLIGHT_ELEMENT\]/s);
if (match) {
  const elementData = JSON.parse(match[1]);
  // Use elementData.selector and elementData.description
}

ElevenLabs API (Optional)

Currently not actively used. The extension uses browser's native speechSynthesis.

Endpoint (if implementing)

POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}

Headers

{
  'xi-api-key': 'YOUR_ELEVENLABS_API_KEY',
  'Content-Type': 'application/json'
}

Web Speech API

Speech Recognition

const recognition = new webkitSpeechRecognition();
recognition.continuous = false;
recognition.interimResults = false;
recognition.lang = 'en-US';

recognition.onresult = (event) => {
  const transcript = event.results[0][0].transcript;
  console.log('User said:', transcript);
};

recognition.start();

Speech Synthesis

const utterance = new SpeechSynthesisUtterance('Hello, I am Web Guide');
utterance.lang = 'en-US';
utterance.rate = 1.0;
utterance.pitch = 1.0;
utterance.volume = 1.0;

window.speechSynthesis.speak(utterance);

Configuration

config.js

Central configuration file for API keys and settings.

// API Keys
const GROQ_API_KEY = 'gsk_...';
const ELEVENLABS_API_KEY = 'your_key_here'; // Optional

// Feature Flags
const VOICE_INPUT = true;
const VOICE_OUTPUT = true;

// API Configuration
const GROQ_API_URL = 'https://api.groq.com/openai/v1/chat/completions';
const GROQ_MODEL = 'llama-3.3-70b-versatile';

// UI Configuration
const HIGHLIGHT_COLOR = '#4285f4';
const ARROW_COLOR = '#ea4335';
const TOOLTIP_BG = 'rgba(0, 0, 0, 0.8)';

// Timing
const HIGHLIGHT_DURATION = 5000; // milliseconds
const SCROLL_DELAY = 300; // milliseconds

// Text Limits
const MAX_PAGE_TEXT = 5000; // characters
const MAX_ELEMENTS = 100; // interactive elements to analyze

Chrome Storage API

Saving Settings

chrome.storage.sync.set({
  voiceInput: true,
  voiceOutput: true,
  highlightColor: '#4285f4'
}, () => {
  console.log('Settings saved');
});

Loading Settings

chrome.storage.sync.get(['voiceInput', 'voiceOutput'], (result) => {
  console.log('Voice input:', result.voiceInput);
  console.log('Voice output:', result.voiceOutput);
});

Storage Limits

  • sync: 100KB total, 8KB per item
  • local: 5MB total (use for larger data)

Error Handling

API Errors

try {
  const response = await callGroqAPI(prompt);
  if (!response.choices || !response.choices[0]) {
    throw new Error('Invalid API response');
  }
} catch (error) {
  console.error('API Error:', error);
  displayError('Failed to get response from AI');
}

Element Not Found

const element = document.querySelector(selector);
if (!element) {
  console.warn('Element not found:', selector);
  return null;
}

Permission Errors

recognition.onerror = (event) => {
  if (event.error === 'not-allowed') {
    displayError('Microphone permission denied');
  }
};

Code Examples

Complete Command Flow

// In popup.js
async function processVoiceCommand(command) {
  try {
    // 1. Get page data
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    
    const pageData = await new Promise((resolve) => {
      chrome.tabs.sendMessage(tab.id, { action: 'getPageData' }, resolve);
    });
    
    // 2. Build prompt
    const prompt = buildPrompt(command, pageData.data);
    
    // 3. Call API
    const response = await fetch(GROQ_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${GROQ_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: GROQ_MODEL,
        messages: [{ role: 'user', content: prompt }]
      })
    });
    
    const data = await response.json();
    const responseText = data.choices[0].message.content;
    
    // 4. Display response
    displayResponse(responseText);
    
    // 5. Check for element highlight
    const match = responseText.match(/\[HIGHLIGHT_ELEMENT\](.*?)\[\/HIGHLIGHT_ELEMENT\]/s);
    if (match) {
      const elementData = JSON.parse(match[1]);
      chrome.tabs.sendMessage(tab.id, {
        action: 'highlightElement',
        selector: elementData.selector,
        description: elementData.description
      });
    }
    
  } catch (error) {
    console.error('Error:', error);
    displayError('Failed to process command');
  }
}

← Back to Technical Documentation | Next: Contributing →

Clone this wiki locally