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."

Features

- Self-contained chat overlay with full AI chat
- Agent SDK integration with OpenAI Agents SDK, Swarm, or custom backends
- Full context (prompt, history, DOM) sent to your agent
- Smart UI highlighting - auto-discover elements by ID or keywords
- Guided walkthroughs for interactive product tours
- Full TypeScript support with complete type definitions
- Beautiful dark theme out of the box
- All styles bundled - no CSS overrides needed
- Zero config - works with mock responses when no backend is connected
- Easy setup - just npm install and one CSS import

Installation

``bash
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:

`tsx
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.

No additional CSS files or overrides needed. The library handles all styling internally with:
- Scoped CSS selectors (prefixed with .tm-overlay-root in production)
- CSS custom properties for theming
- Zero runtime CSS injection
- Complete isolation from host app styles

📚 Library vs Demo Code

Important: This repository contains both:

1. Library code (/src/*) - Exported after npm install ✅
- createTaskMaprClient - Client factory
- HttpAgentOrchestrator - HTTP-based orchestrator with SSE streaming
- HighlightProvider, useHighlight - Context and hooks
- All utility hooks and functions
- TypeScript types

2. Demo code (/src/demo/*) - Example usage, NOT exported ⚠️
- Shows HOW to configure the library for your app
- useTaskMapr hook is demo-specific configuration
- You'll create your own version adapted to your needs

Quick Start

`tsx
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 (



My App

...

{/ One line - fully self-contained! /}


);
}
`

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

React Admin Integration Example

The react-admin example in this repo (examples/simple) demonstrates a production-style setup. The integration boils down to:

1. Import the CSS bundle once (usually in App.tsx).
2. Wrap your app with HighlightProvider so highlighting and walkthroughs work.
3. Create a tiny integration component that configures the client and returns the bundled overlay.

`tsx
// src/taskmaprIntegration.tsx
import {
useTaskMaprClientInstance,
useTaskMaprActionHandlers,
} from '@taskmapr/ui-overlay';

export const TaskMaprOverlay = () => {
const actionHandlers = useTaskMaprActionHandlers();
const agentEndpoint =
import.meta.env.VITE_TASKMAPR_ENDPOINT ??
'http://localhost:8000/api/taskmapr/orchestrate';

const { Overlay } = useTaskMaprClientInstance({
agentEndpoint,
actionHandlers,
});

return ;
};
`

That's it—the overlay bundle takes care of portal mounting, DOM isolation, and the default orchestrator configuration. Provide an endpoint and handlers, and you're done.

useTaskMaprClientInstance memoizes the underlying client for you; pass any additional triggers with the optional extraDependencies array if needed.

$3

- agentEndpoint – URL for your orchestrator/agent endpoint. Leave blank to fall back to the package mock mode.
- actionHandlers – Object returned by useTaskMaprActionHandlers() (or your own implementation) so the overlay can trigger navigation/highlighting.
- options – Any additional TaskMaprClientOptions you want to override (model, overlay theme, etc.). You generally don't need to pass actionHandlers here; the top-level prop takes precedence if both are supplied.
- extraDependencies – Optional array of values that should force the client to refresh (for example, when swapping API keys at runtime).

Use it inside your admin shell:

`tsx
// src/App.tsx
import '@taskmapr/ui-overlay/taskmapr-overlay.css';
import { HighlightProvider } from '@taskmapr/ui-overlay';
import { Admin, Resource } from 'react-admin';
import { TaskMaprOverlay } from './taskmaprIntegration';

export const App = () => (



{/ ... /}



);
`

useTaskMaprActionHandlers wires navigation, highlighting, scrolling, and clicking back into the overlay automatically by reusing the library's highlight context. You can override any handler if your app needs custom behaviour.

👉 See examples/simple for the full working project.

AI Agent Integration

$3

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

`tsx
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

$3

Use this when you want full control over agent orchestration with tools that have knowledge of your repo and workflows.

`tsx
import { createTaskMaprClient, AgentOrchestrator } from '@taskmapr/ui-overlay';

class MyAgentOrchestrator implements AgentOrchestrator {
async orchestrate(context) {
// context includes: prompt, history, domElements, pageContext
const response = await myAgentSDK.run({
prompt: context.prompt,
history: context.history,
domElements: context.domElements,
tools: [repoKnowledgeTool, workflowTool],
});
return { message: response };
}
}

const taskmapr = createTaskMaprClient('', {
orchestrator: {
orchestrator: new MyAgentOrchestrator(),
includeDomSnapshots: true,
},
});
`

What your agent receives:
- Current user prompt
- Full conversation history
- All visible DOM elements (IDs, text, classes, positions, interactivity)
- Page context (URL, title)
- Active walkthrough state




Highlighting

Any element with an id is auto-discoverable:

`tsx


Title

...

`

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

Walkthroughs

`tsx
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 Start Tour;
}
`

Hooks

TaskMapr provides several hooks for advanced use cases:

$3

- 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