# PDF Engine

Cross-platform, high-performance, license-safe PDF rendering and editing SDK.
A single C++ core (PDFium + Skia + FreeType + HarfBuzz) drives native desktop,
server-side, and browser (WASM) rendering, with a FastAPI gateway and a
React + TypeScript viewer on top.

> **Status:** Phase 0 — Infrastructure. The stack must compile clean on
> Linux, macOS, and Windows before any feature work begins. See
> [`docs/phase0.md`](docs/phase0.md).

## Repository layout

| Path             | Purpose                                                              |
|------------------|----------------------------------------------------------------------|
| `engine/`        | C++23 PDF SDK core. The only code that links PDFium/Skia/FreeType.    |
| `engine/src/parser/` | **Only** place raw `FPDF_*` PDFium APIs may be used (Rule R2).    |
| `bindings/`      | Language bindings — C ABI (.NET/ctypes) and pybind11 (Python).        |
| `gateway/`       | FastAPI service: auth, metadata, storage, job queue. *(placeholder)* |
| `frontend/`      | React + TypeScript layered PDF viewer. *(placeholder)*               |
| `wasm/`          | Emscripten build of the engine for in-browser rendering. *(placeholder)* |
| `third_party/`   | Vendored dependencies built from source (PDFium via depot_tools/GN).  |
| `cmake/`         | Reusable CMake modules (`pdfium.cmake`, warnings, sanitizers).        |
| `corpus/`        | Test PDF corpus for rendering/regression gates.                      |
| `scripts/`       | Bootstrap, lint, and developer tooling.                              |
| `docs/`          | Engineering docs and phase plans.                                    |

## Prerequisites

- **CMake** >= 3.25 and **Ninja**
- A **C++23** compiler: MSVC 19.36+ (VS 2022 17.6+ **or** VS 2026 / Build
  Tools 2026 — IDE not required), GCC 13+, or Clang 16+
- **vcpkg** (set `VCPKG_ROOT`; `scripts/bootstrap` can install it). On
  Windows, `setx VCPKG_ROOT ...` does not affect already-open shells —
  set `$env:VCPKG_ROOT` in that shell or open a new terminal.
- **clang-format 22.1.5** (CI is pinned to this exact version) —
  `pip install clang-format==22.1.5` on Windows
- **Python 3.11+** and **Node 20+** (for gateway/frontend, later phases)
- For building PDFium from source: **depot_tools** (handled by
  `third_party/pdfium/build_pdfium.*` — do **not** add it to your
  persistent `PATH`; its `ninja.bat` shadows real Ninja and breaks the
  engine build, see [`docs/phase0.md`](docs/phase0.md))

## Quick start

```sh
# 1. One-time setup: checks tools, installs vcpkg, pins the dependency baseline.
#    Windows:  pwsh scripts/bootstrap.ps1
#    Unix:     ./scripts/bootstrap.sh

# 2. Build PDFium from source (slow, one-time — see third_party/pdfium/README.md).
#    Windows:  pwsh third_party/pdfium/build_pdfium.ps1
#    Unix:     ./third_party/pdfium/build_pdfium.sh

# 3. Configure + build + test via CMake presets.
cmake --preset windows-debug      # or linux-debug / macos-debug
cmake --build --preset windows-debug
ctest --preset windows-debug
```

> **Windows + PDFium:** the engine-linked-against-PDFium build is
> RelWithDebInfo + static CRT (not the Debug preset). Drop the
> `win-local-pdfium` preset into a local `CMakeUserPresets.json` and use
> that — see [`docs/phase0.md`](docs/phase0.md#windows--pdfium) for the
> exact JSON and the reason (CRT alignment).

> **OneDrive note:** this checkout lives in a OneDrive-synced folder whose
> path also contains a space. On **Windows** this is not optional — put
> your build directory outside OneDrive on a space-free path
> (e.g. `C:\Users\<you>\pdfeng-build\...`), or vcpkg/meson and depot_tools
> will fail. On Linux/macOS it is just a sync nuisance — exclude `out/`
> and `vcpkg/` from sync, or pause sync while building. See
> [`docs/phase0.md`](docs/phase0.md#onedrive-warning) for details.

## Engineering rules (non-negotiable)

- **R1** PDFium stays the parser core — no custom parser.
- **R2** Only `engine/src/parser/` may call raw `FPDF_*` APIs. CI enforces this.
- **R3** No custom graphics interpreter in Phase 1/2 — use PDFium's renderer.
- **R4** Saving is incremental (append-only xref) by default.
- **R5** WASM never blocks shipping — server-side render is the fallback.

Dependency versions are **pinned** (vcpkg baseline + a pinned PDFium ref).
Never track rolling `HEAD`.