@timoconnellaus/ai-ui-annotate-core

Core runtime package for AI UI Annotate. This package provides the foundational client-side functionality for highlighting components, creating comments, and communicating with the WebSocket server.

Installation

bun add @timoconnellaus/ai-ui-annotate-core

Usage

import { init } from '@timoconnellaus/ai-ui-annotate-core';

// Initialize the runtime
const runtime = init({
  hotkey: 'Alt',           // Key to hold for annotation mode (default: 'Alt')
  websocketPort: 3001,     // WebSocket server port (default: 3001)
});

// Later, to clean up:
runtime.destroy();

How It Works

1. Hold the hotkey (Alt by default) to enter annotation mode
2. Hover over components with data-component attribute to highlight them
3. Click a highlighted component to open the comment box
4. Write your comment and press Save (or Cmd/Ctrl+Enter)
5. Comment is sent to the WebSocket server for processing

Required HTML Attributes

For components to be annotatable, they must have these attributes:

<div
  data-component="MyComponent"
  data-source-file="src/components/MyComponent.tsx"
  data-source-line="42"
>
  <!-- component content -->
</div>

Framework-specific plugins (e.g., for Next.js, Vite) can automatically add these attributes during development builds.

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | hotkey | 'Alt' \| 'Control' \| 'Meta' \| 'Shift' | 'Alt' | Key to hold for annotation mode | | websocketPort | number | 3001 | WebSocket server port | | websocketUrl | string | - | Full WebSocket URL (overrides port) |

API

init(config?: Config): AnnotateRuntime

Initialize the annotation runtime.

const runtime = init({
  hotkey: 'Alt',
  websocketPort: 3001,
});

destroy(): void

Destroy the active runtime and clean up all resources.

import { destroy } from '@timoconnellaus/ai-ui-annotate-core';

destroy();

Types

interface Comment {
  componentName: string;
  sourceFile: string;
  sourceLine: number;
  text: string;
  timestamp: number;
}

interface Config {
  hotkey?: 'Alt' | 'Control' | 'Meta' | 'Shift';
  websocketPort?: number;
  websocketUrl?: string;
}

WebSocket Message Format

Comments are sent to the server as JSON:

{
  "type": "comment",
  "payload": {
    "componentName": "MyComponent",
    "sourceFile": "src/components/MyComponent.tsx",
    "sourceLine": 42,
    "text": "This button should be bigger",
    "timestamp": 1699999999999
  }
}

Development

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Lint
bun run lint

License

MIT