# 🛠️ PDF Engine — Developer Command Cheat Sheet

This document serves as the single source of truth for commands across our developer roles.

---

## 🗺️ Developer Matrix & Focus Areas

| Role | Focus Area | Code Paths | Primary Responsibilities |
| :--- | :--- | :--- | :--- |
| **Dev 1 — Parser & SDK** | Core PDF parser, C++ wrappers, and FastAPI integration | `engine/src/parser/`<br>`gateway/` | PDFium abstraction layers, Rule R2 compliance, Python bindings, FastAPI gateway |
| **Dev 2 — Graphics & Render** | Frontend React viewer and browser WebAssembly layers | `frontend/`<br>`wasm/` | Rendering facade, Emscripten build pipeline, annotation tools, React UI components |
| **Dev 3 — Fonts & Text** | Text shaping, font embedding, and subsetting | `engine/src/fonts/`<br>`engine/src/text/` | FreeType & HarfBuzz wrappers, font subsetting, text extraction layers |

---

## ⚡ Quick Reference Command Matrix

| Task / Goal | Dev 1: Parser & SDK | Dev 2: Graphics & Render | Dev 3: Fonts & Text |
| :--- | :--- | :--- | :--- |
| **1. One-Time Setup** | `powershell scripts/bootstrap.ps1`<br>*(Setup Python env in `gateway/`)* | `powershell scripts/bootstrap.ps1`<br>*(Setup Node in `frontend/`)* | `powershell scripts/bootstrap.ps1`<br>*(Setup Python env in `gateway/`)* |
| **2. Build C++ Engine** | `powershell scripts/build_cpp.ps1` | `powershell scripts/build_wasm.ps1` *(WASM)* | `powershell scripts/build_cpp.ps1` |
| **3. Run Unit Tests** | `powershell scripts/test_cpp.ps1` | `node wasm/pdfengine.test.mjs` | `powershell scripts/test_cpp.ps1 -R "Font\|Text"` |
| **4. Run Gateway/UI Tests**| `powershell scripts/test_gateway.ps1` | — | `powershell scripts/test_gateway.ps1` |
| **5. Start Local Server** | `powershell scripts/start_gateway.ps1` | `cd frontend; npm run dev` | — |
| **6. Aggregator/CI Check** | `powershell scripts/test_phase0.ps1` | `powershell scripts/test_phase0.ps1` | `powershell scripts/test_phase0.ps1` |

---

## 🛠️ Setup & Execution Workflows

### 💻 Dev 1 — Parser & SDK Workflow

#### A. Setup Python Gateway
```powershell
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
cd gateway
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
cd ..
```

#### B. Build & Local Verification
```powershell
powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1
```

#### C. Gateway Integration & Dev Loop
```powershell
powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
```

---

### ⚛️ Dev 2 — Graphics & Render Workflow

#### A. Setup Frontend UI
```powershell
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
cd frontend
npm install
cd ..
```

#### B. WASM Engine Compilation
```powershell
powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1
```

#### C. Frontend Execution & Production Build
To launch the Vite web server for visual UI prototyping:
```powershell
cd frontend
npm run dev
```

To compile production bundles:
```powershell
cd frontend
npm run build
```

---

### 🔤 Dev 3 — Fonts & Text Workflow

#### A. Setup Environment
```powershell
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
cd gateway
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
cd ..
```

#### B. Development & Test Loop
```powershell
powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1 -R "Font|Text"
powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
```

---

## 🏁 Environment Verification (Aggregator Check)
Before pushing any branches, all developers should run the full suite verification:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/test_phase0.ps1 -Preset win-local-pdfium
```

---

## 🔧 Developer Utilities
Below is a list of other helper scripts in the repository:
*   **Populate Test Corpus**:
    ```powershell
    powershell -ExecutionPolicy Bypass -File scripts/copy_test_corpus.ps1
    ```
    *(Copies standard testing PDFs from local PDFium source/checkout directories to the workspace `corpus/` folder).*