From 867d00ad3ce4d64e860fefebb1481f9bf27ca01b Mon Sep 17 00:00:00 2001
From: Furqan-14 <furqan076@gmail.com>
Date: Tue, 26 May 2026 16:49:02 +0530
Subject: [PATCH] fix: updated build scripts

---
 command.MD               | 120 ++++++++++++++++++++++++++-------------
 scripts/build_wasm.ps1   |  80 ++++++++++++++++++++++++++
 scripts/test_cpp.ps1     |   2 +-
 scripts/test_gateway.ps1 |   2 +-
 4 files changed, 161 insertions(+), 43 deletions(-)
 create mode 100644 scripts/build_wasm.ps1

diff --git a/command.MD b/command.MD
index 2202774..c879b12 100644
--- a/command.MD
+++ b/command.MD
@@ -1,39 +1,39 @@
-# Developer Command Reference
+# 🛠️ PDF Engine — Developer Command Cheat Sheet
 
-This guide lists the exact commands each developer needs for their day-to-day workflow. All compiler environments, presets, and path configs are handled automatically under the hood by the scripts.
+This document serves as the single source of truth for commands across our developer roles.
 
 ---
 
-## 🛠️ Dev 1 — C++ Core Engine Developer
-Use these when writing C++ code (`engine/`), modifying PDFium layers, or changing binding structures.
+## 🗺️ Developer Matrix & Focus Areas
 
-### 1. Build C++ Engine & Python Bindings
-Run this after changing C++ source code to update the local binaries and the Python extension:
-```powershell
-powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
-```
-*(On first execution, this will automatically generate your local `CMakeUserPresets.json` file).*
-
-### 2. Run C++ Unit Tests
-Runs all C++ document, rendering, and lifecycle unit tests:
-```powershell
-powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
-```
-
-### 3. Check PDFium API Boundary
-Verifies no raw `FPDF_*` calls exist outside the `engine/src/parser/` abstraction layer (Rule R2):
-```powershell
-powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1
-```
+| 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 |
 
 ---
 
-## 🐍 Dev 3 — Backend API Developer (Python / FastAPI)
-Use these when writing FastAPI routes, managing Python services, or testing endpoint integrations.
+## ⚡ Quick Reference Command Matrix
 
-### 1. Environment Setup (One-Time)
-Run this once to create the virtual environment and install dependencies:
+| 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
@@ -41,47 +41,85 @@ pip install -e ".[dev]"
 cd ..
 ```
 
-### 2. Start Dev Server
-Launches the FastAPI gateway locally on port `8000` (reloads automatically on file save):
+#### B. Build & Local Verification
 ```powershell
-powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
+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
 ```
 
-### 3. Run Gateway Integration Tests
-Runs all pytest integration tests checking route responses and document modifications:
+#### C. Gateway Integration & Dev Loop
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
+powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
 ```
 
 ---
 
-## ⚛️ Dev 2 — Frontend Developer (React / WASM)
-Use these when building the React UI, annotation toolbar, and client-side WASM engine components.
+### ⚛️ Dev 2 — Graphics & Render Workflow
 
-### 1. Project Setup (One-Time)
-Run once to install Node dependencies:
+#### A. Setup Frontend UI
 ```powershell
+powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
 cd frontend
 npm install
 cd ..
 ```
 
-### 2. Build WebAssembly Module
-Compiles the C++ engine to WebAssembly, runs smoke tests, and deploys `.wasm` and `.mjs` assets directly to `frontend/public/` for local loading:
+#### B. WASM Engine Compilation
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1
 ```
 
-### 3. Start Frontend Dev Server
-Launches the local Vite web server:
+#### C. Frontend Execution & Production Build
+To launch the Vite web server for visual UI prototyping:
 ```powershell
 cd frontend
 npm run dev
 ```
 
-### 4. Build for Production
-Validates TypeScript and generates static build files for deployment:
+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).*
+
diff --git a/scripts/build_wasm.ps1 b/scripts/build_wasm.ps1
new file mode 100644
index 0000000..fa174ff
--- /dev/null
+++ b/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
diff --git a/scripts/test_cpp.ps1 b/scripts/test_cpp.ps1
index 7187912..f9dd3c4 100644
--- a/scripts/test_cpp.ps1
+++ b/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
diff --git a/scripts/test_gateway.ps1 b/scripts/test_gateway.ps1
index 2bd5926..1598f1f 100644
--- a/scripts/test_gateway.ps1
+++ b/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
 }