prep-jee: Instructions file for Codex

AGENTS.md

This file is the single source of project wisdom. Make sure to keep this up to date with the project.

---

What this is

Client-side web app: upload a JEE Test PDF + Solution PDF → extracts questions & answer key → interactive quiz → grading with solution pages.

Target user: JEE (Joint Entrance Exam) aspirants practicing with weekly test PDFs from coaching institutes (e.g., PW Arjuna, Allen, Aakash). The app runs entirely in the browser — no server, no uploads to external services.

Constraints: Fully client-side. pdf.js from npm (pdfjs-dist) bundled via Vite. PDF text extraction via getTextContent() — no OCR. Deployed to Cloudflare Pages.

---

Core workflow

1. Upload — Two separate drop zones (Test PDF / Solution PDF). User explicitly picks which is which. No auto-detection.
2. Parse — pdf.js getTextContent() → reconstructLines() (content-stream order, no y-sort) → text → parsers.
3. Quiz — One question at a time. Controls adapt to type (radio/checkbox/text input). Navigator popup (🔍 Jump button or / key) for jumping between questions. State managed by SolidJS createStore in store.ts.
4. Results — Score with per-question breakdown. Linked solution pages from the solution PDF. Resume banner on reload via localStorage.

Entry point: src/index.tsx renders <App /> into <div id="root">. All screens routed via <Show when={state.screen === '...'}> within App.tsx — no router library.

---

Features (all ✅ done)

• Quiz countdown timer — Duration parsed from the test PDF's first page (looks for DURATION : 180 Minutes pattern). Uses absolute timestamp (startedAt) stored in localStorage, so the timer survives page refreshes. Auto-submits when time runs out. Warning color at <5 min, critical at <1 min. Displayed on both quiz and results screens.
• Two upload sections — Two explicit drop zones, each with its own file input. Validation compares questions.length vs Object.keys(answers).length, throws error with exact counts on mismatch.
• 2D page cropping — Each question shows only its portion of the PDF page, cropped on both x and y. reconstructLines() tracks { minY, maxY, minX, maxX } per line. Falls back: no bbox → full page, no x-bounds → y-only crop.
• Multi-column span notice — Amber notice when a question's x-range covers >55% of the page content width (text in one column, options in another).
• Question navigator — Pop-up grid via "🔍 Jump" button or / key. Green border = answered, purple+glow = current. 1-9 jumps, Escape closes.
• Resume from localStorage — userAnswers + currentQ saved per PDF filename pair. Validates saved qnums match current question set on reload.
• Debug panel — Raw extracted text for first 3 pages. Console debug dump with full question/answer/userAnswer/solutionPageMap data.