Eventop SDK V2

Eventop is an AI visual guidance layer for React applications. It registers application capabilities, receives validated action plans, resolves DOM or non-DOM targets through adapters, and renders accessible guidance overlays.

Install

pnpm add @eventop/sdk @eventop/react @eventop/ai

Minimal setup

import { EventopProvider, EventopTarget, useEventopAI } from '@eventop/react';
import { createHostedProvider } from '@eventop/ai';

const provider = createHostedProvider({ endpoint: '/api/eventop/plan' });

function AskButton() {
  const { runUserMessage } = useEventopAI();
  return <button onClick={() => runUserMessage('How do I export this report?')}>Ask Eventop</button>;
}

export function AppRoot({ children }) {
  return (
    <EventopProvider appName="Reports" provider={provider}>
      <EventopTarget id="report.export" name="Export report" description="Download the report as PDF or CSV" route="/reports">
        <button>Export</button>
      </EventopTarget>
      <AskButton />
      {children}
    </EventopProvider>
  );
}

EventopAIProvider remains available as a compatibility alias for existing integrations. V1 { message, steps } providers can temporarily use createLegacyProviderAdapter from @eventop/ai.

Native V2 plans

Providers return plans that reference registered capability IDs—not selectors or executable code:

{
  "version": "2.0",
  "goal": "Export the report",
  "actions": [
    { "id": "focus-export", "type": "focus", "targetId": "report.export" },
    { "id": "ask-export", "type": "ask-user", "targetId": "report.export", "expectedEvent": "click" },
    { "id": "done", "type": "complete" }
  ]
}

Plans are validated before execution. Unsupported actions, unknown targets, malformed contracts, and unsafe executable actions are rejected. Destructive actions require explicit capability permission and confirmation.

Non-DOM targets

<EventopTarget
  id="chart.revenue-drop"
  name="Revenue drop"
  target={{ type: 'rect', getRect: () => chart.getRegionBounds('2026-Q2') }}
/>

Optional adapters are available for canvas objects, chart regions, map features, same-origin iframes, and tldraw shapes. They are dependency-free contracts; library-specific integrations remain application-owned.

Shadcn integration

npx @eventop/cli init --shadcn

@eventop/shadcn provides source-owned assistant, tooltip, confirmation, pause/resume, control-panel, and annotation components. It does not replace the application’s design system.

Documentation

• V2 foundation
• Migration guide
• Current architecture
• V2 design specification

Development

pnpm install
pnpm test
pnpm test:react
pnpm test:e2e
pnpm typecheck
pnpm build

The core SDK does not require Shepherd, tldraw, Canvas UI, WebGL, or a specific AI vendor.