AOC Simplifier

A browser extension that condenses Advent of Code puzzle descriptions using AI while preserving technical details and examples.

Features

• Automatically detects AOC puzzle pages
• Simplifies verbose narratives into clear problem statements
• Caches results locally
• Toggle between original and simplified versions

Tech Stack

Backend (Rust)

• Axum - Web framework
• Rig - LLM client (via OpenRouter)
• Utoipa - OpenAPI docs generation
• Uses Gemini Flash 3 for simplification

Extension (TypeScript/Svelte)

• WXT - Modern browser extension framework
• Svelte 5 - UI with latest runes API
• Bun - Fast package manager and runtime
• Marked - Markdown to HTML conversion
• Tailwind - Styling

Project Structure

aoc-simplifier/
├── backend/          # Rust API server
│   ├── src/
│   │   ├── handlers.rs    # API endpoints
│   │   ├── prompt.txt     # LLM system prompt
│   │   └── ...
│   └── Cargo.toml
│
└── extension/        # Browser extension
    ├── src/
    │   ├── entrypoints/
    │   │   ├── background.ts    # API calls & storage
    │   │   ├── content.ts       # Page interaction
    │   │   └── popup/           # Extension popup UI
    │   └── types/
    └── package.json

Setup

Backend

1. Install Rust (if you haven't already):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Set up environment variables in backend/.env:

   OPENROUTER_API_KEY=your_key_here
   BEARER_TOKEN=your_auth_token_for_extension

3. Run the server:

   cd backend
   cargo run

   The API will be available at http://localhost:3000

4. Generate OpenAPI types (optional):

   cargo run --bin export-openapi

Extension

1. Install Bun (if needed):

   curl -fsSL https://bun.sh/install | bash

2. Install dependencies:

   cd extension
   bun install

3. Set up environment variables in extension/.env:

   VITE_BACKEND_API_URL=http://localhost:3000
   VITE_BEARER_TOKEN=same_token_from_backend

4. Run in development mode:

   bun run dev          # Chrome/Edge
   bun run dev:firefox  # Firefox

5. Load the extension:

   • Chrome: Go to chrome://extensions, enable Developer Mode, click "Load unpacked", select .output/chrome-mv3
   • Firefox: Go to about:debugging#/runtime/this-firefox, click "Load Temporary Add-on", select any file in .output/firefox-mv3

Usage

1. Navigate to an Advent of Code puzzle
2. Click the extension icon
3. Click "Simplify Question"
4. Toggle between original and simplified versions as needed

Results are cached locally for instant access on subsequent visits.

Development

Extension Commands

bun run dev           # Start dev server (Chrome)
bun run dev:firefox   # Start dev server (Firefox)
bun run build         # Build for production
bun run check         # Type check with Svelte
bun run typegen       # Regenerate API types from OpenAPI spec

Backend Commands

cargo run                        # Run server
cargo run --bin export-openapi   # Generate OpenAPI spec
cargo build --release            # Production build

Type Safety

The extension uses auto-generated TypeScript types from the backend's OpenAPI spec. After changing API endpoints:

1. Export new spec: cd backend && cargo run --bin export-openapi
2. Regenerate types: cd extension && bun run typegen

How It Works

1. Content script extracts puzzle HTML from the page
2. Background script checks local cache
3. If not cached, sends content to backend API
4. Backend uses Gemini Flash 3 with a structured prompt to simplify
5. Response is cached locally and rendered from Markdown
6. Original HTML is preserved for toggling

Security Note

The bearer token is embedded in the extension for API authentication. This is fine for personal use, but don't publish this extension publicly without implementing proper auth (e.g., user-provided API keys or OAuth).

Note: This was written mostly without AI as a learning project. AI was used minimally to do things like write the README or write the chrome extension CSS.