# TypoGenie - AI Coding Agent Guide

## Project Overview

TypoGenie is a web application that transforms Markdown content into professionally formatted Microsoft Word documents. Users upload `.md` or `.txt` files, select from 40+ typography styles across multiple categories (Minimalist, Corporate, Editorial, Tech, Creative, etc.), and download a formatted `.docx` file.

The application uses a local Markdown parser (marked) rather than AI for document conversion, though it was originally designed with AI integration in mind.

## Technology Stack

- **Framework**: React 19.2.4 with TypeScript 5.8.2
- **Build Tool**: Vite 6.2.0
- **Styling**: Tailwind CSS (loaded via CDN in `index.html`)
- **Icons**: Lucide React
- **Document Generation**: docx library (client-side DOCX creation)
- **Markdown Parsing**: marked library (local conversion, no API calls)
- **Fonts**: Google Fonts loaded dynamically

## Project Structure

```
├── App.tsx                 # Main application component with state machine
├── index.tsx               # React root mount
├── index.html              # HTML entry, Tailwind CDN, import maps
├── types.ts                # TypeScript interfaces (StyleOption, DocxStyleConfig, etc.)
├── constants.ts            # System prompts and style exports
├── components/
│   ├── FileUpload.tsx      # Drag-and-drop file upload (.md, .txt)
│   ├── StyleSelector.tsx   # Style grid with preview iframe
│   ├── Preview.tsx         # Final preview and DOCX export
│   └── StylePreviewModal.tsx # (Unused) Modal style preview component

├── styles/                 # Typography style definitions
│   ├── index.ts            # Aggregates all style categories
│   ├── minimalist.ts       # 11 minimalist styles
│   ├── corporate.ts        # 13 corporate/professional styles
│   ├── editorial.ts        # Editorial/magazine styles
│   ├── tech.ts             # Tech/startup styles
│   ├── creative.ts         # Creative/artistic styles
│   ├── vintage.ts          # Retro/vintage styles
│   ├── lifestyle.ts        # Lifestyle/blog styles
│   ├── academic.ts         # Academic/research styles
│   └── industrial.ts       # Industrial/technical styles
```

## Application State Flow

The app uses a 4-state machine defined in `types.ts`:

1. **UPLOAD** - Initial screen with file upload dropzone
2. **CONFIG** - Style selection interface with live preview
3. **GENERATING** - Processing animation (800ms artificial delay for UX)
4. **PREVIEW** - Final preview with DOCX download option

State transitions:
- UPLOAD → CONFIG: After file loaded successfully
- CONFIG → GENERATING: When user clicks "Apply Style & Convert"
- GENERATING → PREVIEW: After HTML generation completes
- PREVIEW → CONFIG: Via "Back to Editor" button
- Any → UPLOAD: Via header logo click (reset)

## Style System Architecture

Each style is a `StyleOption` object containing:

```typescript
{
  id: string,                    // Unique identifier
  name: string,                  // Display name
  category: string,              // For filtering (Minimalist, Corporate, etc.)
  description: string,           // Short description
  vibe: string,                  // Mood/aesthetic descriptor
  googleFontsImport: string,     // Google Fonts URL
  wordConfig: {
    heading1: DocxStyleConfig,   // H1 formatting for Word
    heading2: DocxStyleConfig,   // H2 formatting for Word
    body: DocxStyleConfig,       // Body text formatting for Word
    accentColor: string          // Brand accent color
  },
  previewCss: string             // CSS string for web preview (must manually match wordConfig)
}
```

**Important**: `wordConfig` and `previewCss` must be kept in sync manually for visual fidelity between preview and exported document.

## Build Commands

```bash
# Install dependencies
npm install

# Development server (runs on port 3000)
npm run dev

# Production build (outputs to dist/)
npm run build

# Preview production build
npm run preview
```

## Environment Configuration

No environment variables required. The app uses local Markdown parsing only.

## Key Implementation Details

### DOCX Generation (components/Preview.tsx)

The DOCX export uses the `docx` library to create Word-compatible documents:

- Converts HTML to docx Paragraph elements
- Supports headings (h1-h6), paragraphs, blockquotes, lists
- Applies style-specific fonts, colors, spacing, borders, and shading
- Paper sizes: A4 (210mm × 297mm) and Letter (8.5in × 11in)
- Margins: 1in top/bottom, 1.2in left/right

### Preview System

Previews render in an iframe with dynamically injected:
- Google Fonts link from style config
- Style-specific CSS from `previewCss`
- Sample content for style selection view
- Actual converted content for final preview

### File Upload

Accepts: `.md`, `.txt`, `.markdown`
Uses FileReader API for client-side text extraction
Validates file extension before processing

## Code Style Guidelines

- **TypeScript**: Strict mode enabled; all components typed with React.FC
- **Imports**: Use `@/` path alias for project root imports
- **Styling**: Tailwind utility classes; custom CSS only in `previewCss` fields
- **Naming**: PascalCase for components, camelCase for functions/variables
- **Comments**: Explain business logic and non-obvious decisions

## Adding New Typography Styles

1. Choose appropriate category file in `/styles/` (or create new category)
2. Add StyleOption object to the array with:
   - Unique `id`
   - Google Fonts URL
   - Complete `wordConfig` for DOCX export
   - Matching `previewCss` for web preview
3. Export from `/styles/index.ts` if new category
4. Test both preview and DOCX export

## Security Considerations

- No server-side processing; all conversion happens client-side
- No API keys required; all processing is done locally
- File upload limited to text files by extension check
- iframe sandboxing for style previews (same-origin content only)

## Known Limitations

- `wordConfig` and `previewCss` require manual synchronization
- DOCX export has limited table support
- Complex Markdown (nested lists, code blocks) may not format perfectly
- Style categories are loosely organized and may overlap