docs: Update README.md with detailed project information

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# CONTRIBUTING.md
+
+We welcome contributions to the `@interactive-video-labs/react` project! By contributing, you help us improve and expand the capabilities of this React wrapper for interactive video experiences. Please take a moment to review this document to understand how to contribute effectively.
+
+## Table of Contents
+
+1.  [Code of Conduct](#1-code-of-conduct)
+2.  [How Can I Contribute?](#2-how-can-i-contribute)
+    *   [Reporting Bugs](#reporting-bugs)
+    *   [Suggesting Enhancements](#suggesting-enhancements)
+    *   [Your First Code Contribution](#your-first-code-contribution)
+    *   [Pull Request Guidelines](#pull-request-guidelines)
+3.  [Development Setup](#3-development-setup)
+4.  [Testing](#4-testing)
+5.  [Coding Style](#5-coding-style)
+6.  [Commit Messages](#6-commit-messages)
+7.  [License](#7-license)
+
+## 1. Code of Conduct
+
+This project adheres to the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [your contact email or issue tracker].
+
+## 2. How Can I Contribute?
+
+### Reporting Bugs
+
+If you find a bug, please open an issue on our [GitHub Issues](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues) page. When reporting a bug, please include:
+
+*   A clear and concise description of the bug.
+*   Steps to reproduce the behavior.
+*   Expected behavior.
+*   Actual behavior.
+*   Screenshots or video (if applicable).
+*   Your environment details (OS, browser, `@interactive-video-labs/react` version, React version).
+
+### Suggesting Enhancements
+
+We love new ideas! If you have a suggestion for an enhancement or a new feature, please open an issue on our [GitHub Issues](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues) page. Please include:
+
+*   A clear and concise description of the proposed enhancement.
+*   Why this enhancement would be useful.
+*   Any potential use cases or examples.
+
+### Your First Code Contribution
+
+If you're looking to make your first code contribution, look for issues labeled `good first issue` on our [issue tracker](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues).
+
+### Pull Request Guidelines
+
+1.  **Fork the repository** and create your branch from `main`.
+2.  **Ensure your code adheres to the existing style** (see [Coding Style](#5-coding-style)).
+3.  **Add or update tests** for any new features or bug fixes. Ensure all tests pass.
+4.  **Update documentation** as necessary (e.g., `README.md`, `DEVELOPER.md`).
+5.  **Write clear and concise commit messages** (see [Commit Messages](#6-commit-messages)).
+6.  **Open a pull request** to the `main` branch. Provide a clear description of your changes and reference any related issues.
+
+## 3. Development Setup
+
+For detailed instructions on setting up your development environment, installing dependencies, and running the project locally, please refer to the [DEVELOPER.md](DEVELOPER.md) file.
+
+## 4. Testing
+
+All new features and bug fixes should be accompanied by appropriate tests. To run the test suite, use:
+
+```bash
+pnpm test
+```
+
+Ensure all tests pass before submitting a pull request.
+
+## 5. Coding Style
+
+We use ESLint and Prettier to maintain a consistent coding style. Please ensure your code is formatted correctly before submitting a pull request. You can typically run linting and formatting checks via your IDE or by running project-specific scripts (if available, check `package.json`).
+
+## 6. Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for our commit messages. This helps with automated changelog generation and understanding the history of changes.
+
+Examples:
+
+*   `feat: Add new video playback controls`
+*   `fix: Resolve issue with cue point triggering`
+*   `docs: Update README with new usage example`
+*   `chore: Update dependencies`
+
+## 7. License
+
+By contributing to `@interactive-video-labs/react`, you agree that your contributions will be licensed under its MIT License. See the [LICENSE](LICENSE) file for details.

DEVELOPER.md

@@ -0,0 +1,106 @@
+# DEVELOPER.md
+
+This document provides a guide for developers who want to contribute to or work with the `@interactive-video-labs/react` project. It covers setting up the development environment, understanding the project structure, running tests, building the project, and working with examples.
+
+## Table of Contents
+
+1.  [Getting Started](#getting-started)
+2.  [Project Structure](#project-structure)
+3.  [Available Scripts](#available-scripts)
+4.  [Testing](#testing)
+5.  [Building the Project](#building-the-project)
+6.  [Working with Examples](#working-with-examples)
+7.  [Contributing](#contributing)
+8.  [Troubleshooting](#troubleshooting)
+
+## 1. Getting Started
+
+To get started with development, follow these steps:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/interactive-video-labs/interactive-video-react-wrapper.git
+    cd interactive-video-react-wrapper
+    ```
+
+2.  **Install dependencies:**
+    This project uses `pnpm` as its package manager. If you don't have `pnpm` installed, you can install it via npm:
+    ```bash
+    npm install -g pnpm
+    ```
+    Then, install the project dependencies:
+    ```bash
+    pnpm install
+    ```
+
+## 2. Project Structure
+
+Here's an overview of the key directories and files in this project:
+
+*   `src/`: Contains the main source code for the React wrapper (`index.tsx`).
+*   `test/`: Contains unit tests for the components (`InteractiveVideo.test.tsx`) and test setup (`setupTests.ts`).
+*   `examples/`: Contains a simple example React application demonstrating how to use the wrapper.
+    *   `index.html`: The HTML entry point for the example.
+    *   `index.tsx`: The React application code for the example.
+*   `dist/`: The output directory for the compiled library files.
+*   `tsup.config.ts`: Configuration for `tsup`, the bundler used to build the library.
+*   `vitest.config.ts`: Configuration for `Vitest`, the testing framework.
+*   `package.json`: Project metadata, dependencies, and scripts.
+
+## 3. Available Scripts
+
+This project includes several scripts defined in `package.json` to help with development:
+
+*   `pnpm build`: Compiles the TypeScript source code into JavaScript for distribution (`dist` folder).
+*   `pnpm dev`: Starts `tsup` in watch mode, recompiling the library whenever source files change.
+*   `pnpm test`: Runs all unit tests using Vitest.
+*   `pnpm clean`: Removes the `dist` directory.
+*   `pnpm prepare`: Runs `pnpm build`. This script is typically run before publishing the package.
+*   `pnpm serve-examples`: Builds the example application and serves it using `http-server`.
+*   `pnpm build-examples`: Compiles the example application using `esbuild`.
+
+## 4. Testing
+
+Tests are written using `Vitest` and `React Testing Library`. You can run all tests with:
+
+```bash
+pnpm test
+```
+
+When adding new features or fixing bugs, please ensure you add or update relevant tests to maintain code quality and prevent regressions.
+
+## 5. Building the Project
+
+The project is built using `tsup`. To compile the library for production, run:
+
+```bash
+pnpm build
+```
+
+This will generate the compiled JavaScript files and TypeScript declaration files in the `dist` directory.
+
+## 6. Working with Examples
+
+The `examples/` directory contains a basic usage example. To run it:
+
+```bash
+pnpm serve-examples
+```
+
+This will build the example and start a local web server, usually accessible at `http://localhost:8080` (or another port if 8080 is in use). You can modify the `examples/index.tsx` file to test your changes in a live environment.
+
+## 7. Contributing
+
+We welcome contributions to this project! Please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines on how to contribute, including information on:
+
+*   Reporting bugs
+*   Suggesting enhancements
+*   Submitting pull requests
+*   Coding style and conventions
+
+## 8. Troubleshooting
+
+*   **`pnpm` command not found**: Ensure `pnpm` is installed globally (`npm install -g pnpm`).
+*   **Build errors**: Check the output of `pnpm build` for specific error messages. Ensure all dependencies are installed (`pnpm install`).
+*   **Test failures**: Review the test output for details on failing tests. You can often debug tests by adding `console.log` statements or using your IDE's debugger.
+*   **Example server not starting**: Check if port 8080 (or the default `http-server` port) is already in use. You might need to stop other processes using that port or configure `http-server` to use a different port (though this is not directly supported by the `serve-examples` script).

README.md

@@ -17,4 +17,106 @@ Welcome to `@interactive-video-labs/react` — a lightweight React wrapper aroun
 
 This wrapper makes it easy to embed interactive video players in React apps using familiar props and event handlers, while keeping close to the core API.
 
----
+---
+
+## Introduction
+
+`@interactive-video-labs/react` is a thin React component that provides a convenient way to integrate interactive video experiences into your React applications. It leverages the powerful `@interactive-video-labs/core` engine, allowing you to easily manage video playback, cue points, and analytics within a familiar React paradigm.
+
+## Features
+
+*   **Easy Integration**: Seamlessly embed interactive videos into your React components.
+*   **Cue Point Management**: Load and manage cue points for dynamic video interactions.
+*   **Analytics Events**: Receive detailed analytics events from the video player to track user engagement.
+*   **Localization**: Support for player localization through translations.
+*   **Direct Core API Access**: Provides a React-friendly interface while maintaining close alignment with the core IVLabsPlayer API.
+
+## Installation
+
+You can install the package using npm or pnpm:
+
+```bash
+pnpm add @interactive-video-labs/react @interactive-video-labs/core react react-dom
+# or
+npm install @interactive-video-labs/react @interactive-video-labs/core react react-dom
+```
+
+## Usage
+
+To use the `InteractiveVideo` component, simply import it and pass the necessary props. The `videoUrl` prop is mandatory.
+
+```tsx
+import React from 'react';
+import { InteractiveVideo } from '@interactive-video-labs/react';
+
+const MyVideoPlayer = () => {
+  return (
+    <div style={{ width: '100%', maxWidth: '800px', margin: '0 auto' }}>
+      <InteractiveVideo
+        videoUrl="https://interactive-video-labs.github.io/interactive-video-demos/videos/big_buck_bunny.mp4"
+        autoplay={true}
+        loop={false}
+        controls={true}
+        onAnalyticsEvent={(event, payload) => {
+          console.log('Analytics Event:', event, payload);
+          // Handle analytics events, e.g., send to a tracking service
+        }}
+        cues={[
+          { time: 10, id: 'intro-cue', type: 'pause' },
+          { time: 25, id: 'question-cue', type: 'custom', data: { question: 'What is your favorite color?' } },
+        ]}
+        translations={{
+          en: {
+            play: 'Play Video',
+            pause: 'Pause Video',
+          },
+        }}
+      />
+    </div>
+  );
+};
+
+export default MyVideoPlayer;
+```
+
+## Props
+
+The `InteractiveVideo` component accepts the following props:
+
+*   `videoUrl` (string, **required**): The URL of the video to be played.
+*   `onAnalyticsEvent` (function, optional): A callback function that is triggered when an analytics event occurs. It receives the `event` name and an optional `payload`.
+    *   `event`: `PLAYER_LOADED`, `VIDEO_STARTED`, `VIDEO_PAUSED`, `VIDEO_ENDED`, `CUE_TRIGGERED`, `INTERACTION_COMPLETED`, `ERROR`.
+    *   `payload`: An object containing event-specific data.
+*   `cues` (CuePoint[], optional): An array of cue points to load into the player. Each `CuePoint` object should conform to the `@interactive-video-labs/core` `CuePoint` interface.
+*   `translations` (Translations, optional): An object containing translations for player localization. This should conform to the `@interactive-video-labs/core` `Translations` interface.
+*   `...restOptions` (PlayerConfig, optional): Any other valid `PlayerConfig` options from `@interactive-video-labs/core` (excluding `videoUrl`, `cues`, and `translations`). This allows for direct pass-through of core player configurations like `autoplay`, `loop`, `controls`, `locale`, etc.
+
+## Development
+
+To set up the development environment:
+
+1.  Clone the repository.
+2.  Install dependencies:
+    ```bash
+    pnpm install
+    ```
+3.  Build the project:
+    ```bash
+    pnpm build
+    ```
+4.  Run tests:
+    ```bash
+    pnpm test
+    ```
+5.  Run examples:
+    ```bash
+    pnpm serve-examples
+    ```
+
+## Contributing
+
+We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

tsup.config.ts

@@ -1,23 +1,16 @@
 import { defineConfig } from 'tsup';
 import pkg from './package.json';
 
-export default defineConfig((options) => ({
-export default defineConfig((options) => ({
+export default defineConfig({
     entry: ['src/index.tsx'],
     format: ['esm', 'cjs'],
-    outExtension: ext => ({
-        esm: '.mjs',
-        cjs: '.cjs',
-    }),
     dts: true,
-    watch: options.watch,
     clean: true,
-}));
     banner: {
         js: `/**
  * ${pkg.name} v${pkg.version}
  * Author: ${pkg.author}
  */
-    `,
+        `,
     },
-}));
+});