### Start Vite Development Server with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Starts the Vite development server.

```bash
npm start
```

--------------------------------

### Start Storybook with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Starts the Storybook development server using bun.

```bash
bun run storybook
```

--------------------------------

### Install Dependencies

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Install project dependencies using npm or bun.

```bash
npm install
```

```bash
bun install
```

--------------------------------

### Start Vite Development Server with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Starts the Vite development server using bun.

```bash
bun run dev
```

--------------------------------

### Install React Image Annotate with npm

Source: https://github.com/karlorz/react-image-annotate/wiki/Getting-Started

Use npm to install the @karlorz/react-image-annotate package. This is the recommended installation method.

```bash
npm install @karlorz/react-image-annotate
```

--------------------------------

### Install Dependencies with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Installs project dependencies using bun, an alternative for faster installs.

```bash
bun install
```

--------------------------------

### Install @karlorz/react-image-annotate

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Install the package using npm or bun. Optional: load the Inter font for improved typography.

```bash
npm install @karlorz/react-image-annotate
```

```bash
# or
bun add @karlorz/react-image-annotate
```

```css
/* Optional: load Inter font for best typography */
@import url("https://rsms.me/inter/inter.css");
```

--------------------------------

### Start Development Server

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Launch the Storybook development server to interactively view and test components.

```bash
npm run storybook
```

--------------------------------

### Basic React Image Annotate Usage

Source: https://github.com/karlorz/react-image-annotate/wiki/Home

Demonstrates the basic setup for React Image Annotate with predefined region classes and tags, and a single image. Ensure you have the library installed.

```javascript
import ReactImageAnnotate from "@karlorz/react-image-annotate";

const App = () => (
  <ReactImageAnnotate
    labelImages
    regionClsList={["Alpha", "Beta", "Charlie", "Delta"]}
    regionTagList={["tag1", "tag2", "tag3"]}
    images={[{ 
      src: "https://placekitten.com/408/287",
      name: "Image 1",
      regions: []
    }]}
  />
);
```

--------------------------------

### Start Vite Development Server with npm (dev)

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Starts the Vite development server using the 'dev' script.

```bash
npm run dev
```

--------------------------------

### Example Image Object Array

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Provides an example of how to structure the `images` prop, which is an array of `ImageObject`.

```javascript
images={[
  {
    src: "https://example.com/image.jpg",
    name: "Image 1",
    regions: []
  }
]}
```

--------------------------------

### Install @karlorz/react-image-annotate using yarn

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

Use this command to install the package if you are using yarn as your package manager.

```bash
yarn add @karlorz/react-image-annotate
```

--------------------------------

### Search Migration Guides with context7

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Use context7 to find specific migration guides for React versions, styling systems, and build tools.

```bash
# For React version migration guides:
1. Use context7 to search "React 18 migration guide"
2. Use context7 to search "React 19 breaking changes"
3. Use context7 to search "React concurrent features migration"

# For Material-UI to Tailwind migration:
1. Use context7 to search "Material-UI v5 with Tailwind CSS integration"
2. Use context7 to search "MUI sx prop to Tailwind utilities"

# For webpack to Vite migration:
1. Use context7 to search "webpack to Vite migration guide"
2. Use context7 to search "Vite configuration for React library"
```

--------------------------------

### Install react-image-annotate for Headless Use

Source: https://github.com/karlorz/react-image-annotate/blob/master/examples/headless/README.md

Install the package and necessary React dependencies for headless operation. MUI dependencies are not required for headless usage.

```bash
npm install @karlorz/react-image-annotate

# For headless use, you don't need MUI dependencies
# Just install React
npm install react react-dom
```

--------------------------------

### Run Storybook for Development

Source: https://github.com/karlorz/react-image-annotate/blob/master/README.md

Execute this command to start the Storybook development server. A browser tab will open automatically to display components.

```bash
npm run storybook
```

```bash
bun run storybook
```

--------------------------------

### Install Material-UI and Tailwind CSS

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Install both Material-UI v6 and Tailwind CSS side-by-side to maintain compatibility during migration.

```bash
# Keep Material-UI v6
npm install @mui/material @emotion/react @emotion/styled

# Add Tailwind CSS
npm install -D tailwindcss postcss autoprefixer

# Or with bun
bun add @mui/material @emotion/react @emotion/styled
bun add -D tailwindcss postcss autoprefixer
```

--------------------------------

### Install React Image Annotate with bun

Source: https://github.com/karlorz/react-image-annotate/wiki/Getting-Started

Use bun to add the @karlorz/react-image-annotate package to your project. Ensure you have bun installed.

```bash
bun add @karlorz/react-image-annotate
```

--------------------------------

### Verify Package Installation with npm

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

After installation, run this command to check if the package is listed in your project's dependencies.

```bash
npm list @karlorz/react-image-annotate
```

--------------------------------

### Example Environment Variables

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Define environment variables in a .env file for development configuration.

```env
# Example environment variables
VITE_API_URL=http://localhost:3000
VITE_ENABLE_DEBUG=true
```

--------------------------------

### Troubleshoot npm Installation: Clear Cache

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

If npm installation fails, try clearing the npm cache with this command.

```bash
npm cache clean --force
```

--------------------------------

### Install a Specific Version of @karlorz/react-image-annotate

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

Use this command to install a particular version of the package, replacing '3.0.0' with your desired version.

```bash
npm install @karlorz/react-image-annotate@3.0.0
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Installs project dependencies using npm. Use `--legacy-peer-deps` if needed for React 19 compatibility.

```bash
npm install
--legacy-peer-deps
```

--------------------------------

### Example Test Case

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

A basic example of a unit test using Vitest and React Testing Library to verify component rendering.

```typescript
import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import ReactImageAnnotate from '../src';

describe('ReactImageAnnotate', () => {
  it('renders without crashing', () => {
    render(
      <ReactImageAnnotate
        images={[
          { src: 'test.jpg', name: 'Test', regions: [] }
        ]}
        regionClsList={['Object']}
      />
    );

    expect(screen.getByRole('main')).toBeInTheDocument();
  });
});
```

--------------------------------

### Storybook Component Testing Workflow

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

This example demonstrates a typical agent workflow for testing a Storybook component. It includes navigation, taking screenshots, interacting with elements, and checking for errors.

```text
Agent Prompt:
"Navigate to http://localhost:9090/?path=/story/annotator--basic-usage,
take a screenshot, click the 'Add Box' button,
check console for errors, and list any failed network requests."

Expected Actions:
1. navigate_page(url="http://localhost:9090/?path=...")
2. take_screenshot() → Displays initial component state
3. take_snapshot() → Gets accessibility tree (finds button UID)
4. click(uid="button-add-box")
5. list_console_messages(types=["error"]) → Returns empty or CORS issues
6. list_network_requests(resourceTypes=["fetch", "xhr"]) → Checks API failures
```

--------------------------------

### Bounding Box Output Format

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Example of the output format for a bounding box annotation.

```javascript
{
  type: "box",
  x: 0.1,      // Normalized x position (0-1)
  y: 0.2,      // Normalized y position (0-1)
  w: 0.3,      // Normalized width (0-1)
  h: 0.4,      // Normalized height (0-1)
  cls: "Car"   // Classification
}
```

--------------------------------

### Point Annotation Output Format

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Example of the output format for a point annotation.

```javascript
{
  type: "point",
  x: 0.5,      // Normalized x position
  y: 0.5,      // Normalized y position
  cls: "Center"
}
```

--------------------------------

### Basic React Image Annotation Tool

Source: https://github.com/karlorz/react-image-annotate/wiki/Getting-Started

A minimal React component demonstrating the basic setup for image annotation. It includes sample labels and an image source.

```javascript
import React from 'react';
import ReactImageAnnotate from "@karlorz/react-image-annotate";

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <ReactImageAnnotate
        labelImages
        regionClsList={["Cat", "Dog", "Bird"]}
        images={[
          {
            src: "https://placekitten.com/408/287",
            name: "Sample Image",
            regions: []
          }
        ]}
        onExit={(output) => {
          console.log("Annotations:", output);
        }}
      />
    </div>
  );
}

export default App;
```

--------------------------------

### Programmatically Select Annotation Tool

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Demonstrates how to use the `actions.selectTool` function to change the active annotation tool at runtime, for example, in response to keyboard events.

```jsx
const { actions, state } = useAnnotator({ images, enabledTools: ["select", "create-box"] })

// Programmatically switch tools (e.g. from a keyboard shortcut handler)
document.addEventListener("keydown", (e) => {
  if (e.key === "b") actions.selectTool("create-box")
  if (e.key === "s") actions.selectTool("select")
})

console.log(state.selectedTool) // "create-box"
```

--------------------------------

### Implementing Theme Support in React Image Annotate

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

This example shows how to implement theme support for the React Image Annotate component using string-based themes or custom MUI themes.

```javascript
// String mode (recommended)
<ReactImageAnnotate theme="dark" {...props} />
<ReactImageAnnotate theme="light" {...props} />

// Custom MUI theme
import { createTheme } from '@mui/material/styles'
const customTheme = createTheme({
  palette: {
    mode: 'dark',
    primary: { main: '#3f51b5' },
  },
})
<ReactImageAnnotate theme={customTheme} {...props} />
```

--------------------------------

### Polygon Annotation Output Format

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Example of the output format for a polygon annotation, including an array of points.

```javascript
{
  type: "polygon",
  points: [
    [0.1, 0.2],  // [x, y] pairs (normalized)
    [0.3, 0.2],
    [0.3, 0.4],
    [0.1, 0.4]
  ],
  cls: "Object"
}
```

--------------------------------

### Basic React Image Annotate Usage

Source: https://github.com/karlorz/react-image-annotate/blob/master/src/LandingPage/content.md

A simple example demonstrating how to integrate the React Image Annotate component into a React application. It sets up an image for annotation with a task description and specifies the available tools.

```javascript
import ReactImageAnnotate from "@karlorz/react-image-annotate"

const App = () => (
  <ReactImageAnnotate
    selectedImage="https://example.com/image1.png"
    taskDescription="# Draw region around each animal."
    images={[{ src: "https://example.com/image1.png", name: "Image 1" }]} 
    regionClsList={["Dog", "Cat"]}
    enabledTools={["create-box"]}
  />
)
```

--------------------------------

### Peer Dependencies for React Projects

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

The library requires React and ReactDOM. Ensure these are installed in your project; if not, use the provided command.

```json
{
  "react": "^18.0.0",
  "react-dom": "^18.0.0"
}
```

```bash
npm install react react-dom
```

--------------------------------

### Troubleshoot npm Installation: Reinstall Dependencies

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

After clearing the cache or if facing issues, remove node_modules and package-lock.json, then reinstall.

```bash
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Resolve Version Conflicts with Legacy Peer Deps

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

Use this flag during installation if you encounter version conflicts with peer dependencies.

```bash
npm install @karlorz/react-image-annotate --legacy-peer-deps
```

--------------------------------

### getOutput

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Call `getOutput()` to get a serializable `AnnotationOutput` snapshot at any point before saving.

```APIDOC
## `getOutput` — retrieve annotation data

Call `getOutput()` to get a serializable `AnnotationOutput` snapshot at any point before saving.

```jsx
function AutoSaveAnnotator({ images }) {
  const { getOutput, actions, regions } = useAnnotator({ images })

  // Auto-save every 30 seconds
  React.useEffect(() => {
    const timer = setInterval(() => {
      const output = getOutput()
      localStorage.setItem("autosave", JSON.stringify(output))
      console.log("Auto-saved", output.images.length, "images")
    }, 30_000)
    return () => clearInterval(timer)
  }, [getOutput])

  // output shape returned by getOutput():
  // {
  //   images: [
  //     {
  //       src: string, name: string,
  //       regions: Array<BoxRegion | PolygonRegion | PointRegion>,
  //       cls?: string, tags?: string[]
  //     }
  //   ]
  // }

  return <div>{/* custom UI */}</div>
}
```
```

--------------------------------

### useAnnotator Hook

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Import from `@karlorz/react-image-annotate/headless` to get full annotation state and actions with zero default UI. Build any design system integration on top.

```APIDOC
## useAnnotator hook — headless API

Import from `@karlorz/react-image-annotate/headless` to get full annotation state and actions with zero default UI. Build any design system integration on top.

```jsx
import { useAnnotator } from "@karlorz/react-image-annotate/headless"

function MinimalAnnotator({ images, onSave }) {
  const {
    state,           // full internal state object
    actions,         // { selectTool, deleteRegion, … }
    regions,         // Region[] for the current image
    currentImage,    // ImageObject | null
    getOutput,       // () => AnnotationOutput  (call before saving)
  } = useAnnotator({
    images,
    enabledTools: ["select", "create-box", "create-polygon", "create-point"],
    selectedTool: "create-box",
    regionClsList: ["Person", "Car"],
    onExit: onSave,
  })

  return (
    <div style={{ display: "flex", height: "100vh", fontFamily: "sans-serif" }}>
      {/* Toolbar */}
      <aside style={{ width: 160, padding: 12, borderRight: "1px solid #ddd" }}>
        <p style={{ fontWeight: 600 }}>Tool</p>
        {["select", "create-box", "create-polygon", "create-point"].map((tool) => (
          <button
            key={tool}
            onClick={() => actions.selectTool(tool)}
            style={{
              display: "block", width: "100%", marginBottom: 6, padding: "6px 10px",
              background: state.selectedTool === tool ? "#3b82f6" : "#f3f4f6",
              color: state.selectedTool === tool ? "#fff" : "#111",
              border: "none", borderRadius: 4, cursor: "pointer",
            }}
          >
            {tool}
          </button>
        ))}

        <p style={{ fontWeight: 600, marginTop: 16 }}>
          Regions ({regions.length})
        </p>
        {regions.map((region) => (
          <div
            key={region.id}
            style={{ display: "flex", justifyContent: "space-between", marginBottom: 4 }}
          >
            <span>{region.cls || region.type}</span>
            <button
              onClick={() => actions.deleteRegion(region)}
              style={{ color: "red", background: "none", border: "none", cursor: "pointer" }}
            >
              ✕
            </button>
          </div>
        ))}
      </aside>

      {/* Main area */}
      <main style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <header
          style={{
            display: "flex", justifyContent: "space-between", alignItems: "center",
            padding: "10px 16px", borderBottom: "1px solid #ddd",
          }}
        >
          <strong>{currentImage?.name ?? "No image"}</strong>
          <button
            onClick={() => onSave(getOutput())}
            style={{
              padding: "6px 16px", background: "#22c55e", color: "#fff",
              border: "none", borderRadius: 4, cursor: "pointer",
            }}
          >
            Save
          </button>
        </header>
        <div style={{ flex: 1, background: "#f9fafb", display: "flex", alignItems: "center", justifyContent: "center" }}>
          {/* Render your custom canvas here */}
          <p style={{ color: "#9ca3af" }}>Canvas area</p>
        </div>
      </main>
    </div>
  )
}
```
```

--------------------------------

### Build and Deploy to GitHub Pages with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds the demo site and deploys it to GitHub Pages.

```bash
npm run gh-pages
```

--------------------------------

### Build Demo Site for GitHub Pages with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds the demo site for GitHub Pages using bun.

```bash
bun run build:gh-pages
```

--------------------------------

### Build Demo Site for GitHub Pages with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds the demo site for deployment on GitHub Pages.

```bash
npm run build:gh-pages
```

--------------------------------

### Build and Publish to npm with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds the library and publishes it to npm.

```bash
npm run dist
```

--------------------------------

### Build Library for Distribution with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds the library for distribution using bun.

```bash
bun run build
```

--------------------------------

### Build and Publish to npm with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds and publishes to npm using bun.

```bash
bun run dist
```

--------------------------------

### Format All Files with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Formats all files using bun.

```bash
bun run format
```

--------------------------------

### Build, Test, and Publish npm Package

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Follow the release process to build the production version, test the package, and publish it to npm. Publishing is restricted to maintainers.

```bash
# Build
npm run build:prod

# Test build
npm pack

# Publish to npm
npm publish --access public
```

--------------------------------

### Build and Deploy to GitHub Pages with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Builds and deploys to GitHub Pages using bun.

```bash
bun run gh-pages
```

--------------------------------

### Run All Tests

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Execute all unit and integration tests in the project.

```bash
npm run test
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Start developing a new feature by creating a dedicated Git branch.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Format All Files with npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Formats all files, including JSON and Markdown.

```bash
npm run format
```

--------------------------------

### Production Build

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Generate an optimized production build of the project.

```bash
npm run build:prod
```

--------------------------------

### Development Build

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Generate a development build of the project.

```bash
npm run build
```

--------------------------------

### Configure I18nProvider with Custom French Translations

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Provide fully custom translations by passing a 'translations' object to I18nProvider. This example shows how to add French translations.

```jsx
// Custom / additional language (e.g. French)
const frTranslations = {
  fr: {
    "header.save": "Enregistrer",
    "header.prev": "Précédent",
    "header.next": "Suivant",
    "header.clone": "Dupliquer",
    "header.settings": "Paramètres",
    "header.fullscreen": "Plein écran",
    "tools.createBox": "Ajouter un cadre",
    "tools.createPolygon": "Ajouter un polygone",
    "tools.createPoint": "Ajouter un point",
    "sidebar.regions": "Régions",
    "sidebar.history": "Historique",
  },
}

function FrenchAnnotator() {
  return (
    <I18nProvider language="fr" translations={frTranslations}>
      <ReactImageAnnotate images={images} regionClsList={["Objet"]} />
    </I18nProvider>
  )
}
```

--------------------------------

### Quick Test Commands for Browser Automation

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

A collection of quick commands for basic browser automation tasks, including navigation, screenshotting, console debugging, form submission, and performance analysis.

```bash
# Basic browser control test
"Navigate to https://demo.realworld.io and take a screenshot"
```

```bash
# Console debugging
"Load https://demo.realworld.io, check console for CORS errors"
```

```bash
# Form automation
"On https://demo.realworld.io, click Sign In, fill test@example.com / testpass123, submit"
```

```bash
# Performance analysis
"Navigate to https://developers.chrome.com, trace performance, analyze insights"
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Execute tests and generate a code coverage report.

```bash
npm run test:coverage
```

--------------------------------

### Run Tests with Vitest using npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Runs project tests using Vitest.

```bash
npm test
```

--------------------------------

### Run Tests with Vitest using bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Runs project tests using Vitest with bun.

```bash
bun test
```

--------------------------------

### Update @karlorz/react-image-annotate to Latest

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

Run this command to update the package to the most recent stable version.

```bash
npm update @karlorz/react-image-annotate
```

--------------------------------

### Basic Headless Annotator Usage in React

Source: https://github.com/karlorz/react-image-annotate/blob/master/examples/headless/README.md

Demonstrates the fundamental integration of the `useAnnotator` hook in a React component. It shows how to initialize the hook with images and an `onExit` callback, and how to render custom UI elements for tools, canvas interaction, and region display.

```jsx
import { useAnnotator } from '@karlorz/react-image-annotate/headless'

function MyAnnotator() {
  const { state, actions, regions, currentImage } = useAnnotator({
    images: [
      { src: '/image1.jpg', name: 'Image 1' },
      { src: '/image2.jpg', name: 'Image 2' },
    ],
    onExit: (output) => {
      console.log('Annotation complete:', output)
    }
  })

  return (
    <div>
      <h1>{currentImage?.name}</h1>

      {/* Your custom toolbar */}
      <div>
        <button onClick={() => actions.selectTool('create-box')}>
          Box Tool
        </button>
        <button onClick={() => actions.selectTool('create-polygon')}> 
          Polygon Tool
        </button>
      </div>

      {/* Your custom canvas (simplified) */}
      <canvas width={800} height={600} />

      {/* Or use getCanvasProps() for automatic event handling */}
      <canvas
        width={800}
        height={600}
        {...actions.getCanvasProps()}
      />

      {/* Your custom region list */}
      <ul>
        {regions.map(region => (
          <li key={region.id}>
            {region.cls || 'Unlabeled'}
            <button onClick={() => actions.deleteRegion(region)}>
              Delete
            </button>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

--------------------------------

### Format Source Files with Prettier using npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Formats source files using Prettier.

```bash
npm run prettier
```

--------------------------------

### Enable Video Annotation

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Enable frame-by-frame video annotation by passing 'videoSrc' instead of or alongside 'images'. Configure framerate and initial time.

```jsx
<ReactImageAnnotate
  videoSrc="/videos/dashcam.mp4"
  videoName="Dashcam Clip 1"
  videoTime={0}
  framerate={30}
  regionClsList={["Vehicle", "Pedestrian", "Cyclist"]}
  onExit={(output) => saveVideoAnnotations(output)}
  onFrameAnnotated={(frameNumber, regions) => {
    console.log(`Frame ${frameNumber}:`, regions.length, "regions")
  }}
/>
```

--------------------------------

### Importing react-image-annotate Component

Source: https://github.com/karlorz/react-image-annotate/wiki/Installation

Demonstrates how to import the main component or the headless hook into your React application.

```javascript
// Default import
import ReactImageAnnotate from "@karlorz/react-image-annotate";
```

```javascript
// Or named import (if using headless mode)
import { useAnnotator } from "@karlorz/react-image-annotate";
```

--------------------------------

### Format Source Files with Prettier using bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Formats source files using Prettier with bun.

```bash
bun run prettier
```

--------------------------------

### actions.selectTool

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Switch the active annotation tool at runtime.

```APIDOC
## `actions.selectTool`

Switch the active annotation tool at runtime.

```jsx
const { actions, state } = useAnnotator({ images, enabledTools: ["select", "create-box"] })

// Programmatically switch tools (e.g. from a keyboard shortcut handler)
document.addEventListener("keydown", (e) => {
  if (e.key === "b") actions.selectTool("create-box")
  if (e.key === "s") actions.selectTool("select")
})

console.log(state.selectedTool) // "create-box"
```
```

--------------------------------

### Set Task Description

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Displays custom instructions or task descriptions to the user using the `taskDescription` prop.

```javascript
taskDescription="Draw bounding boxes around all vehicles"
```

--------------------------------

### Configure Tool-Specific Settings

Source: https://github.com/karlorz/react-image-annotate/wiki/Advanced-Features

Apply specific settings to individual annotation tools. This allows fine-tuning parameters like minimum size for boxes or point limits for polygons.

```javascript
<ReactImageAnnotate
  images={images}
  regionClsList={["Object"]}
  toolSettings={{
    "create-box": {
      minSize: 10,  // Minimum box size in pixels
      snapToGrid: true,
      gridSize: 10
    },
    "create-polygon": {
      minPoints: 3,
      maxPoints: 20,
      autoClose: true
    }
  }}
/>
```

--------------------------------

### Set Task Instructions for Annotators

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Use the `taskDescription` prop to provide clear instructions to annotators. This helps ensure consistency and accuracy in the annotation process.

```javascript
<ReactImageAnnotate
  taskDescription="Draw bounding boxes around all people in the image. Include partially visible people."
  regionClsList={"["Person"]"}
  images={images}
/>
```

--------------------------------

### Configure Tool-Specific Settings

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Provides a way to apply specific configurations to individual annotation tools, such as minimum size constraints for bounding boxes.

```javascript
toolSettings={{
  "create-box": {
    minSize: 10,
    snapToGrid: true
  }
}}
```

--------------------------------

### Retrieve Annotation Output with getOutput

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Illustrates how to use the `getOutput` function to obtain a serializable snapshot of the current annotation data. This is useful for saving or auto-saving annotations.

```jsx
function AutoSaveAnnotator({ images }) {
  const { getOutput, actions, regions } = useAnnotator({ images })

  // Auto-save every 30 seconds
  React.useEffect(() => {
    const timer = setInterval(() => {
      const output = getOutput()
      localStorage.setItem("autosave", JSON.stringify(output))
      console.log("Auto-saved", output.images.length, "images")
    }, 30_000)
    return () => clearInterval(timer)
  }, [getOutput])

  // output shape returned by getOutput():
  // {
  //   images: [
  //     {
  //       src: string, name: string,
  //       regions: Array<BoxRegion | PolygonRegion | PointRegion>,
  //       cls?: string, tags?: string[]
  //     }
  //   ]
  // }

  return <div>{/* custom UI */}</div>
}

```

--------------------------------

### Enable Image Labeling

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Set the `labelImages` prop to `true` to enable labeling of entire images.

```javascript
labelImages={true}
```

--------------------------------

### Handling Multiple Images for Annotation

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Configure the component to handle multiple images in a single annotation session by providing an array of image objects.

```javascript
const images = [
  { src: "/image1.jpg", name: "Image 1", regions: [] },
  { src: "/image2.jpg", name: "Image 2", regions: [] },
  { src: "/image3.jpg", name: "Image 3", regions: [] }
];

<ReactImageAnnotate
  images={images}
  regionClsList={["Object"]}
  onExit={(output) => {
    output.images.forEach((img, idx) => {
      console.log(`Image ${idx + 1}:`, img.regions.length, "regions");
    });
  }}
/>
```

--------------------------------

### Lint Code with ESLint using npm

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Checks code quality using ESLint.

```bash
npm run lint
```

--------------------------------

### Bump Project Version using npm

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Increment the project version according to Semantic Versioning using npm commands. Use `patch` for bug fixes, `minor` for backward-compatible features, and `major` for breaking changes.

```bash
# Patch release (1.0.0 -> 1.0.1)
npm version patch

# Minor release (1.0.0 -> 1.1.0)
npm version minor

# Major release (1.0.0 -> 2.0.0)
npm version major
```

--------------------------------

### Format and Lint Code with npm Scripts

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Utilize npm scripts for code formatting and linting to maintain code style consistency. Auto-fix linting issues with `npm run lint:fix`.

```bash
# Format code
npm run format

# Lint code
npm run lint

# Auto-fix linting issues
npm run lint:fix
```

--------------------------------

### Internationalization with I18nProvider

Source: https://github.com/karlorz/react-image-annotate/blob/master/README.md

Enable multi-language support by wrapping your app with `I18nProvider`. Specify the language or provide custom translations.

```javascript
import { I18nProvider } from "@karlorz/react-image-annotate";

<I18nProvider language="zh"> {/* en, zh, or vi */}
  <ReactImageAnnotate {...props} />
</I18nProvider>
```

```javascript
<I18nProvider
  language="fr"
  translations={{
    fr: { 'header.save': 'Enregistrer', ... }
  }}
>
  <ReactImageAnnotate {...props} />
</I18nProvider>
```

--------------------------------

### Lint Code with ESLint using bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Checks code quality using ESLint with bun.

```bash
bun run lint
```

--------------------------------

### Clone Repository

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Clone the repository locally and add the upstream remote for future updates.

```bash
git clone https://github.com/YOUR_USERNAME/react-image-annotate.git
cd react-image-annotate
```

```bash
git remote add upstream https://github.com/karlorz/react-image-annotate.git
```

--------------------------------

### Navigate to Previous Image using useAnnotator Hook

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Use the `prevImage` method provided by the `useAnnotator` hook to navigate to the previous image in the sequence.

```javascript
prevImage();
```

--------------------------------

### Use useAnnotator Hook for Headless Architecture

Source: https://github.com/karlorz/react-image-annotate/wiki/Advanced-Features

Leverage the `useAnnotator` hook to build custom UIs with the core annotation logic. Requires images and region class list configuration.

```javascript
import { useAnnotator } from "@karlorz/react-image-annotate";

function CustomAnnotationTool() {
  const {
    currentImage,
    regions,
    selectedRegion,
    addRegion,
    updateRegion,
    deleteRegion,
    selectRegion,
    nextImage,
    prevImage
  } = useAnnotator({
    images: [
      {
        src: "/image.jpg",
        name: "Image 1",
        regions: []
      }
    ],
    regionClsList: ["Person", "Car"]
  });

  return (
    <div className="custom-ui">
      <div className="toolbar">
        <button onClick={prevImage}>Previous</button>
        <button onClick={nextImage}>Next</button>
      </div>

      <canvas
        ref={canvasRef}
        onClick={(e) => {
          const rect = e.currentTarget.getBoundingClientRect();
          const x = (e.clientX - rect.left) / rect.width;
          const y = (e.clientY - rect.top) / rect.height;

          addRegion({
            type: "point",
            x,
            y,
            cls: "Person"
          });
        }}
      />

      <div className="regions-list">
        {regions.map((region, idx) => (
          <div
            key={idx}
            onClick={() => selectRegion(idx)}
            className={selectedRegion === idx ? "selected" : ""}
          >
            {region.cls} - {region.type}
            <button onClick={() => deleteRegion(idx)}>Delete</button>
          </div>
        ))}
      </div>
    </div>
  );
}
```

--------------------------------

### Check Translation Completeness with bun

Source: https://github.com/karlorz/react-image-annotate/blob/master/AGENTS.md

Checks translation completeness using bun.

```bash
bun run lint:i18n
```

--------------------------------

### Enable Video Annotation Mode

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Activates specific features for annotating video content when `videoMode` is set to `true`. Defaults to `false`.

```javascript
videoMode={true}
```

--------------------------------

### Bounding Box Annotation Configuration

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Configure the component for bounding box annotation by setting a task description and classification labels.

```javascript
<ReactImageAnnotate
  taskDescription="Draw boxes around all vehicles"
  regionClsList={["Car", "Truck", "Bus"]}
  images={images}
/>
```

--------------------------------

### Initialize useAnnotator Hook

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Import and call the `useAnnotator` hook with options to manage annotation state and methods for custom UI implementations. It returns various state variables and control functions.

```javascript
import { useAnnotator } from "@karlorz/react-image-annotate";

const { 
  currentImage,
  currentImageIndex,
  regions,
  selectedRegion,
  addRegion,
  updateRegion,
  deleteRegion,
  selectRegion,
  nextImage,
  prevImage,
  goToImage,
  save,
  exit
} = useAnnotator(options);
```

--------------------------------

### Specify Video Source URL

Source: https://github.com/karlorz/react-image-annotate/wiki/API-Reference

Provides the URL for the video file when `videoMode` is enabled. This prop is required if `videoMode` is `true`.

```javascript
videoSrc="/path/to/video.mp4"
```

--------------------------------

### Basic ReactImageAnnotate Configuration

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Configure the main ReactImageAnnotate component with essential props for image annotation.

```javascript
import ReactImageAnnotate from "@karlorz/react-image-annotate";

<ReactImageAnnotate
  labelImages={true}
  regionClsList={["Class1", "Class2", "Class3"]}
  regionTagList={["tag1", "tag2", "tag3"]}
  images={imageArray}
  onExit={handleExit}
/>
```

--------------------------------

### Import Inter UI or Roboto Font

Source: https://github.com/karlorz/react-image-annotate/blob/master/README.md

Ensure proper font rendering by importing Inter UI or Roboto. Add this line to your CSS file.

```css
@import url("https://rsms.me/inter/inter.css");
```

--------------------------------

### Headless Architecture with useAnnotator Hook

Source: https://github.com/karlorz/react-image-annotate/blob/master/README.md

Utilize the `useAnnotator` hook for custom UI implementations. This allows for building your own annotation interface.

```javascript
import { useAnnotator } from "@karlorz/react-image-annotate/headless";

function MyCustomAnnotator() {
  const { state, actions, regions, currentImage } = useAnnotator({
    images: [{ src: '/image.jpg', name: 'Test' }],
    onExit: (output) => console.log(output)
  });

  return (
    <div>
      <button onClick={() => actions.selectTool('create-box')}>
        Box Tool
      </button>
      <canvas {...actions.getCanvasProps()} />
      {regions.map(r => (
        <div key={r.id}>
          {r.cls}
          <button onClick={() => actions.deleteRegion(r)}>Delete</button>
        </div>
      ))}
    </div>
  );
}
```

--------------------------------

### Enable Debug Mode in Browser

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Activate debug logging for the `react-image-annotate` library by setting the `DEBUG` item in `localStorage`.

```javascript
localStorage.setItem('DEBUG', 'react-image-annotate:*');
```

--------------------------------

### Point Annotation Configuration

Source: https://github.com/karlorz/react-image-annotate/wiki/Basic-Usage

Configure the component for point annotation by specifying enabled tools and classification labels.

```javascript
<ReactImageAnnotate
  taskDescription="Mark the center of each object"
  enabledTools={["create-point"]}
  regionClsList={["Center", "Corner"]}
  images={images}
/>
```

--------------------------------

### Minimal Annotator Component with useAnnotator

Source: https://context7.com/karlorz/react-image-annotate/llms.txt

Demonstrates a basic integration of the useAnnotator hook to build a custom annotation interface. It manages tool selection, displays regions, and provides a save function.

```jsx
import { useAnnotator } from "@karlorz/react-image-annotate/headless"

function MinimalAnnotator({ images, onSave }) {
  const {
    state,           // full internal state object
    actions,         // { selectTool, deleteRegion, … }
    regions,         // Region[] for the current image
    currentImage,    // ImageObject | null
    getOutput,       // () => AnnotationOutput  (call before saving)
  } = useAnnotator({
    images,
    enabledTools: ["select", "create-box", "create-polygon", "create-point"],
    selectedTool: "create-box",
    regionClsList: ["Person", "Car"],
    onExit: onSave,
  })

  return (
    <div style={{ display: "flex", height: "100vh", fontFamily: "sans-serif" }}>
      {/* Toolbar */}
      <aside style={{ width: 160, padding: 12, borderRight: "1px solid #ddd" }}>
        <p style={{ fontWeight: 600 }}>Tool</p>
        {["select", "create-box", "create-polygon", "create-point"].map((tool) => (
          <button
            key={tool}
            onClick={() => actions.selectTool(tool)}
            style={{ 
              display: "block", width: "100%", marginBottom: 6, padding: "6px 10px",
              background: state.selectedTool === tool ? "#3b82f6" : "#f3f4f6",
              color: state.selectedTool === tool ? "#fff" : "#111",
              border: "none", borderRadius: 4, cursor: "pointer",
            }}
          >
            {tool}
          </button>
        ))}

        <p style={{ fontWeight: 600, marginTop: 16 }}>
          Regions ({regions.length})
        </p>
        {regions.map((region) => (
          <div
            key={region.id}
            style={{ display: "flex", justifyContent: "space-between", marginBottom: 4 }}
          >
            <span>{region.cls || region.type}</span>
            <button
              onClick={() => actions.deleteRegion(region)}
              style={{ color: "red", background: "none", border: "none", cursor: "pointer" }}
            >
              ✕
            </button>
          </div>
        ))}
      </aside>

      {/* Main area */}
      <main style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <header
          style={{
            display: "flex", justifyContent: "space-between", alignItems: "center",
            padding: "10px 16px", borderBottom: "1px solid #ddd",
          }}
        >
          <strong>{currentImage?.name ?? "No image"}</strong>
          <button
            onClick={() => onSave(getOutput())}
            style={{ 
              padding: "6px 16px", background: "#22c55e", color: "#fff",
              border: "none", borderRadius: 4, cursor: "pointer",
            }}
          >
            Save
          </button>
        </header>
        <div style={{ flex: 1, background: "#f9fafb", display: "flex", alignItems: "center", justifyContent: "center" }}>
          {/* Render your custom canvas here */}
          <p style={{ color: "#9ca3af" }}>Canvas area</p>
        </div>
      </main>
    </div>
  )
}

```

--------------------------------

### Create Storybook Stories for Component Development

Source: https://github.com/karlorz/react-image-annotate/wiki/Development-Guide

Write Storybook stories to develop and document components in isolation. Import components and define their metadata and states.

```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { ToolButton } from '../components/ToolButton';

const meta: Meta<typeof ToolButton> = {
  title: 'Components/ToolButton',
  component: ToolButton,
};

export default meta;
type Story = StoryObj<typeof ToolButton>;

export const Default: Story = {
  args: {
    icon: '📦',
    label: 'Box Tool',
    active: false,
  },
};

export const Active: Story = {
  args: {
    icon: '📦',
    label: 'Box Tool',
    active: true,
  },
}
```