Merge branch 'dev' of https://gitea.maskantech.in/gitea_admin/pdf into azeem

command.MD

@@ -1,239 +1,125 @@
-# PDF Engine — Developer Command Reference
+# 🛠️ PDF Engine — Developer Command Cheat Sheet
+
+This document serves as the single source of truth for commands across our developer roles.
 
 ---
 
-## ⚠️ Windows — Activate MSVC Before Anything Else
+## 🗺️ Developer Matrix & Focus Areas
 
-Run this once per terminal session before any `cmake` command:
+| Role | Focus Area | Code Paths | Primary Responsibilities |
-
+| :--- | :--- | :--- | :--- |
-**Option A — Open a new PowerShell with MSVC loaded**
+| **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 |
-```powershell
+| **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 |
-cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && powershell'
-```
-
-**Option B — Load MSVC into your current PowerShell window**
-
-```powershell
-cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && set' |
-  Where-Object { $_ -match '=' } |
-  ForEach-Object {
-    $name, $value = $_ -split '=', 2
-    [System.Environment]::SetEnvironmentVariable($name, $value, 'Process')
-  }
-$env:VCPKG_ROOT = "C:\Users\furqa\vcpkg"
-```
-
-If you skip this step, cmake will fail with:
-`CMake Error: No CMAKE_CXX_COMPILER could be found.`
 
 ---
 
-## One-Time Setup (new machine only)
+## ⚡ Quick Reference Command Matrix
 
-```powershell
+| Task / Goal | Dev 1: Parser & SDK | Dev 2: Graphics & Render | Dev 3: Fonts & Text |
-pwsh scripts/bootstrap.ps1
+| :--- | :--- | :--- | :--- |
-```
+| **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` |
-```sh
+| **3. Run Unit Tests** | `powershell scripts/test_cpp.ps1` | `node wasm/pdfengine.test.mjs` | `powershell scripts/test_cpp.ps1 -R "Font\|Text"` |
-./scripts/bootstrap.sh
+| **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` |
 
 ---
 
-## Component 1 — C++ Engine
+## 🛠️ Setup & Execution Workflows
 
-### Configure
+### 💻 Dev 1 — Parser & SDK Workflow
-
-Run on first setup, after adding `.cpp` files, or after changing `CMakeLists.txt`.
-
-```powershell
-cmake --preset windows-debug
-```
-
-### Build
-
-Run after changing any C++ source file.
-
-```powershell
-cmake --build --preset windows-debug
-```
-
-### Test
-
-```powershell
-ctest --preset windows-debug
-```
-
-Expected output: `100% tests passed`
-
-### Fresh / Clean Rebuild
-
-Use when you see cache errors or strange Ninja errors.
-
-```powershell
-cmake --preset windows-debug --fresh
-cmake --build --preset windows-debug
-```
-
-### Rule R2 Boundary Check
-
-Verifies no raw `FPDF_*` calls exist outside `engine/src/parser/`.
-
-```powershell
-pwsh scripts/check_pdfium_boundary.ps1
-```
-
----
-
-## Component 2 — Gateway (FastAPI / Python)
 
+#### A. Setup Python Gateway
 ```powershell
+powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
 cd gateway
-python -m pip install -e ".[dev]"
+python -m venv .venv
-python -m ruff check .
+.venv\Scripts\Activate.ps1
-python -m ruff format --check .
+pip install -e ".[dev]"
-python -m pytest
+cd ..
 ```
 
----
+#### B. Build & Local Verification
-
-## Component 3 — Frontend (React / TypeScript)
-
-```powershell
-cd frontend
-npm install
-npm run dev
-npm run build
-npm run lint
-```
-
----
-
-## Component 4 — WASM (Emscripten)
-
-Activate Emscripten first (one-time install):
-
-```powershell
-Get-Content wasm/emsdk.pinned
-./emsdk install <version>
-./emsdk activate <version>
-./emsdk_env.ps1
-```
-
-Build and test:
-
-```powershell
-cmake --preset wasm
-cmake --build --preset wasm
-node wasm/hello.test.mjs
-```
-
-Expected output:
-```
-[wasm-smoke] OK — add(2,3)=5, hello_version()=1, cwrap add(40,2)=42
-```
-
-Browser test (optional):
-
-```powershell
-npx serve .
-```
-
-Open `http://localhost:3000/test.html` and check the browser console (F12).
-
----
-
-## C++ Code Style (clang-format)
-
-Install once (CI is pinned to 22.1.5):
-
-```powershell
-pip install clang-format==22.1.5
-```
-
-Check formatting:
-
-```powershell
-Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
-  ForEach-Object { clang-format --dry-run --Werror $_.FullName }
-```
-
-Auto-format in place:
-
-```powershell
-Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
-  ForEach-Object { clang-format -i $_.FullName }
-```
-
----
-
-## Run Everything at Once
-
-Runs all components and prints one pass/fail per component.
-
-```powershell
-pwsh scripts/test_phase0.ps1 -Preset windows-debug
-pwsh scripts/test_phase0.ps1 -Preset windows-debug -SkipWasm
-```
-
-```sh
-./scripts/test_phase0.sh
-SKIP_WASM=1 ./scripts/test_phase0.sh
-```
-
----
-
-## Automated Convenience Scripts
-
-We have created several PowerShell scripts in the `scripts/` directory to automate setting up the MSVC compiler environments, building, running tests, and starting the FastAPI gateway server. You can run these from the project root:
-
-*   **Build C++ Engine & Python Bindings**:
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
-    ```
-*   **Run C++ Core Unit Tests**:
-    ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
+powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1
 ```
-*   **Run Gateway pytest Integration Tests**:
+
+#### C. Gateway Integration & Dev Loop
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
-    ```
-*   **Start the Local FastAPI Dev Server**:
-    ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
 ```
 
 ---
 
-## Quick Reference
+### ⚛️ Dev 2 — Graphics & Render Workflow
-
-
-```powershell
-cmake --preset windows-debug
-cmake --build --preset windows-debug
-ctest --preset windows-debug
-```
-
-```powershell
-cd gateway
-python -m pip install -e ".[dev]"
-python -m pytest
-```
 
+#### 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
-cmake --preset wasm
+cd frontend
-cmake --build --preset wasm
+npm run build
-node wasm/hello.test.mjs
 ```
 
+---
+
+### 🔤 Dev 3 — Fonts & Text Workflow
+
+#### A. Setup Environment
 ```powershell
-pwsh scripts/check_pdfium_boundary.ps1
+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).*
+

scripts/build_wasm.ps1

@@ -0,0 +1,80 @@
+#requires -Version 5.1
+# Build C++ Engine to WebAssembly (WASM) and deploy to Frontend public folder.
+
+$ErrorActionPreference = 'Stop'
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = (Resolve-Path (Join-Path $ScriptDir "..")).Path
+
+# --- Resolve EMSDK ---
+$emsdk = $env:EMSDK
+if (-not $emsdk) {
+    $candidates = @(
+        "C:\Users\$env:USERNAME\emsdk",
+        "C:\emsdk",
+        "C:\src\emsdk",
+        "C:\Users\furqa\emsdk"
+    )
+    foreach ($cand in $candidates) {
+        if (Test-Path $cand) {
+            $emsdk = $cand
+            break
+        }
+    }
+    
+    if (-not $emsdk) {
+        Write-Error "EMSDK environment variable was not set and could not be found at standard locations. Please set the EMSDK environment variable."
+        exit 1
+    }
+    $env:EMSDK = $emsdk
+    Write-Host "EMSDK defaulted to: $emsdk" -ForegroundColor Yellow
+}
+
+# Load EMSDK environment variables in PowerShell context
+$envScript = Join-Path $emsdk "emsdk_env.ps1"
+if (-not (Test-Path $envScript)) {
+    Write-Error "Could not find emsdk_env.ps1 at $emsdk"
+    exit 1
+}
+
+Write-Host "Loading Emscripten environment variables..." -ForegroundColor Cyan
+. $envScript
+
+# Configure WASM preset
+Write-Host "Configuring CMake WASM preset..." -ForegroundColor Cyan
+cmake --preset wasm
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "CMake configuration failed."
+    exit $LASTEXITCODE
+}
+
+# Build WASM preset
+Write-Host "Building WASM targets..." -ForegroundColor Cyan
+cmake --build --preset wasm
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "WASM build failed."
+    exit $LASTEXITCODE
+}
+
+# Run WASM smoke tests
+Write-Host "Running WASM smoke tests..." -ForegroundColor Cyan
+node wasm/pdfengine.test.mjs
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "WASM smoke tests failed."
+    exit $LASTEXITCODE
+}
+
+# Copy built targets to frontend public folder
+$WasmBinDir = Join-Path $ProjectRoot "out\build\wasm\bin"
+$FrontendPublic = Join-Path $ProjectRoot "frontend\public"
+
+if (-not (Test-Path $FrontendPublic)) {
+    Write-Warning "Frontend public folder not found at $FrontendPublic. Skipping copy."
+} else {
+    Write-Host "Copying WASM build artifacts to frontend public folder..." -ForegroundColor Cyan
+    Copy-Item -Path (Join-Path $WasmBinDir "pdfengine.mjs") -Destination (Join-Path $FrontendPublic "pdfengine.mjs") -Force
+    Copy-Item -Path (Join-Path $WasmBinDir "pdfengine.wasm") -Destination (Join-Path $FrontendPublic "pdfengine.wasm") -Force
+    Write-Host "Successfully copied WASM files to $FrontendPublic" -ForegroundColor Green
+}
+
+Write-Host "Success! WASM built and deployed." -ForegroundColor Green

scripts/test_cpp.ps1

@@ -11,5 +11,5 @@ if (Test-Path $vcvars) {
 }
 
 Write-Host "Running C++ core unit tests..." -ForegroundColor Cyan
-ctest --preset win-local-pdfium
+ctest --preset win-local-pdfium $args
 exit $LASTEXITCODE

scripts/test_gateway.ps1

@@ -4,7 +4,7 @@ $gatewayDir = Join-Path (Split-Path -Parent $scriptDir) "gateway"
 Write-Host "Running FastAPI Gateway integration tests..." -ForegroundColor Cyan
 Push-Location $gatewayDir
 try {
-    & .venv\Scripts\pytest
+    & .venv\Scripts\pytest $args
 } finally {
     Pop-Location
 }