Read by OpenAI Development Assistant

This skill provides expert guidance for working with the "Read by AI" Chrome extension codebase - an AI-powered text-to-speech extension that uses OpenAI's TTS API.

Project Context

This Chrome extension allows users to select text on any webpage and have it read aloud using AI-powered voices. The project uses React 19, TypeScript, Vite, and the OpenAI SDK.

Key Architecture Components

When working with this codebase, understand these core components:

1. **Background Service Worker** (`src/background.ts`)

- Central hub managing audio playback via `AudioManager` singleton

- Handles context menu integration and offscreen document management

- Implements LRU audio caching (up to 100MB)

2. **Content Script** (`src/content.tsx`)

- React-based control bar injected into web pages

- Handles playback control interactions

3. **Offscreen Document** (`src/offscreen.ts`, `src/offscreen.html`)

- Dedicated context for HTML5 audio playback (required by Chrome extension restrictions)

4. **Popup Interface** (`src/popup.tsx`)

- Settings UI for OpenAI API configuration

- Persists to IndexedDB

5. **Message Flow**: TypeScript-typed message passing (`src/message.ts`) between all components

Development Workflow

Setup and Build Commands

When setting up or building the extension:

```bash

Install dependencies

yarn install

Development with hot-reload

yarn watch

Production build

yarn build

Type checking

yarn compile

Development server for popup

yarn dev

```

Testing the Extension

Follow these steps to test changes:

1. Run `yarn watch` to build with hot-reload

2. Navigate to `chrome://extensions/` in Chrome

3. Enable "Developer mode" toggle

4. Click "Load unpacked" and select the `dist` directory

5. Extension will appear in browser toolbar

When making changes, the `yarn watch` process will rebuild automatically, but you may need to click the refresh icon on the extension card in `chrome://extensions/` for some changes.

Important Implementation Patterns

Streaming Audio Playback

The extension uses an on-demand streaming system:

When modifying audio playback, maintain this streaming architecture for performance.

Singleton Pattern

`AudioManager` and `SimpleDBManager` use `getInstance()` pattern. When adding new managers:

Message Type Safety

All Chrome runtime messages are typed via discriminated unions in `src/message.ts`. When adding new messages:

React Component Mounting

The content script mounts React into web pages. When modifying mounting logic:

Storage and State Management

When modifying configuration:

1. Update Zod schema in config.ts

2. Update TypeScript types

3. Update popup UI accordingly

4. Test migration from old to new schema

Common Tasks

Adding a New Voice Option

1. Update configuration schema in `src/config.ts`

2. Add UI controls in `src/popup.tsx`

3. Update OpenAI API call in background script

4. Test with various text samples

Modifying Audio Playback Logic

1. Locate logic in `AudioManager` (src/background.ts)

2. Consider impact on streaming architecture

3. Test pause/resume, skip forward/back, and error cases

4. Verify cache behavior remains correct

Adding New Message Types

1. Define interface in `src/message.ts` with `type` field

2. Add to message union type

3. Implement handlers in background/content/offscreen as needed

4. Ensure type safety with TypeScript checks

Recent Known Issues

When encountering playback issues, check `AudioManager` state transitions and offscreen document message handling.

Best Practices

1. **Error Handling**: Use consistent try-catch with user notifications

2. **Async Operations**: Always handle promises properly in Chrome extension contexts

3. **Message Passing**: Validate message types and handle errors gracefully

4. **Audio Resources**: Clean up audio elements and blobs to prevent memory leaks

5. **Type Safety**: Leverage TypeScript for all Chrome API interactions

File Structure Reference

Notes