mv-ignited: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents working with code in this repository.

Project Context

MV-Ignited is a browser extension that enhances the mediavida.com forum. It injects React components into the forum's existing DOM to add new features and improve the user experience.

Quick Start

yarn install             # Install dependencies
yarn watch              # Start development mode (outputs to dist/)
yarn build:chrome       # Production build for Chrome → dist-chrome/
yarn build:chrome:zip   # Build Chrome + create store-ready zip
yarn build:firefox      # Production build for Firefox → dist-firefox/
yarn build:firefox:zip  # Build Firefox + create store-ready zip
# Load dist/ (dev) or dist-chrome/ (prod) as unpacked extension in Chrome

Code Quality Validation

CRITICAL: After completing EVERY task, you MUST run these three commands:

yarn tsc --noEmit                  # Type checking
yarn eslint src --ext .ts,.tsx     # Linting
yarn style                         # Formatting

Never skip this validation step. All three commands must pass before committing any changes.

Architecture Overview

Four Entry Points:

1. Theme Loader (src/theme-loader.ts) - Runs at document_start to inject custom theme CSS before any rendering
2. Background Service Worker (src/background.ts) - Handles extension lifecycle, icon updates, and script injection
3. Popup UI (src/popup.tsx) - Quick access settings interface
4. Content Scripts (src/injected/) - Main functionality injected into forum pages

Key Directories:

• src/domains/ - Data parsing from forum DOM (pure functions)
• src/injected/ - Injection orchestration and page detection
• src/react/ - React components for UI enhancements
• src/utils/ - Zustand stores with localStorage persistence

State Management

Uses Zustand with subscribeWithSelector middleware and localStorage persistence:

// Main store: useStore
- threadsIgnored: string[]
- features: Feature[]
- users: MVUser[]
- customFont?: string

// Theme store: useCustomTheme
- customWidth, headerColour, pageBackground, primaryColour