TaskMapr UI Overlay

Bring Cursor-style AI assistance to your React applications

A beautiful, fully-featured overlay component that adds AI chat, UI highlighting, and interactive walkthroughs to any React app. Think "Cursor for websites."

Installation

npm install @taskmapr/ui-overlay

Setup

The library includes all necessary styles bundled. You must import the CSS file for the overlay to display correctly:

import '@taskmapr/ui-overlay/taskmapr-overlay.css';

Important: The CSS import is required. The library uses scoped CSS with the .tm-overlay-root prefix to ensure complete isolation from your host application's styles. All styles are bundled into a single CSS file that is automatically included when you import the library.

Quick Start

import { createTaskMaprClient, HighlightProvider } from '@taskmapr/ui-overlay';
// Import the bundled CSS (all styles included, no overrides needed!)
import '@taskmapr/ui-overlay/taskmapr-overlay.css';

// Initialize client once with your configuration
const taskmapr = createTaskMaprClient(
  import.meta.env.VITE_AGENT_ENDPOINT,
  {
    apiKey: import.meta.env.VITE_OPENAI_API_KEY,
    framework: 'openai-agents',
    model: 'gpt-4o',
    overlay: {
      title: 'TaskMapr Assistant',
      showTimestamps: true,
      defaultTheme: 'light', // or 'dark' - defaults to 'light' if not specified
    },
    initialMessages: [{
      id: '1',
      role: 'assistant',
      content: 'Hello! How can I help you today?',
      timestamp: new Date(),
    }],
  }
);

function App() {
  return (
    <HighlightProvider>
      <h1 id="hero" data-highlight-keywords="title, header">My App</h1>
      <section id="features">...</section>
      
      {/* One line - fully self-contained! */}
      <taskmapr.Overlay />
    </HighlightProvider>
  );
}

Minimal Setup: Just two imports and you're ready to go. No CSS overrides, no configuration files - the library handles everything internally.

AI Agent Integration

HTTP Agent Orchestrator (Recommended)

For most use cases, use the built-in HttpAgentOrchestrator to connect to a TaskMapr backend server with SSE streaming support:

import { createTaskMaprClient, HttpAgentOrchestrator } from '@taskmapr/ui-overlay';

const agentEndpoint = 'http://localhost:8000/api/taskmapr/orchestrate';

const taskmapr = createTaskMaprClient(agentEndpoint, {
  orchestrator: {
    orchestrator: new HttpAgentOrchestrator(agentEndpoint, {
      getAccessToken: () => yourSupabaseToken, // Optional: for auth
      timeout: 60000, // Optional: request timeout
    }),
    includeDomSnapshots: true,
  },
  overlay: {
    title: 'TaskMapr Assistant',
    placeholder: 'Ask me anything...',
  },
});

Features:

• ✅ SSE (Server-Sent Events) streaming support
• ✅ Real-time text streaming with text_delta events
• ✅ Reasoning and tool call notifications
• ✅ Automatic error handling and retries
• ✅ Works with TaskMapr orchestrator backend

Highlighting

Any element with an id is auto-discoverable:

<h1 id="hero">Title</h1>
<section id="features" data-highlight-keywords="capabilities, list">...</section>

Users can type "show me features" or "hero" in chat to highlight elements.

Walkthroughs

import { useHighlight } from '@taskmapr/ui-overlay';

function App() {
  const { startWalkthrough } = useHighlight();
  
  const tour = () => {
    startWalkthrough([
      { query: 'hero', message: 'This is the title', waitForClick: true },
      { query: 'features', message: 'Check out features', waitForClick: true },
    ], {
      onComplete: () => console.log('Done!')
    });
  };
  
  return <button onClick={tour}>Start Tour</button>;
}

Hooks

TaskMapr provides several hooks for advanced use cases:

Hooks

• useVisibleHtmlIds - Track visible DOM elements with rich metadata
• useVisibleComponents - Track TaskMapr's highlightable components
• useHighlight - Access highlighting context and walkthrough functions

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 API Reference

Full API documentation coming soon. For now, check the TypeScript types in the package for complete API details.

🐛 Issues

Found a bug? Have a feature request? Open an issue on GitHub.

📄 License

MIT License - see LICENSE for details.

🔗 Links

• npm Package: https://www.npmjs.com/package/@taskmapr/ui-overlay
• GitHub Repository: https://github.com/taskmapr/ui-overlay
• Issues: https://github.com/taskmapr/ui-overlay/issues

---

Built with ❤️ by TaskMapr • Add AI superpowers to your React apps