78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
<!--
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
SPDX-FileCopyrightText: 2025 ai-ad4 and the FreePDFEditor contributors
|
|
-->
|
|
# Spike D — Skia vs PDFium renderer: M0 status (DEFERRED)
|
|
|
|
* **Spike**: D — our own Skia display-list renderer vs PDFium on the corpus
|
|
(engineering plan §14 step 7)
|
|
* **Date**: 2026-07-25
|
|
* **Status**: **Deferred.** Not buildable in the M0 development environment;
|
|
recorded here so the deferral is explicit, not silent.
|
|
* **Gate**: pixel divergence ≤ 0.3% between our Skia display-list renderer and
|
|
PDFium on 500 corpus pages — decides whether the §2.5 predictive tier is
|
|
viable.
|
|
|
|
## Why deferred
|
|
|
|
Spike D requires **our own Skia display-list renderer** (which does not exist
|
|
yet — it is M2 work) and **PDFium** as the reference renderer. Neither is
|
|
available as a system package on Debian 13:
|
|
|
|
- **PDFium** has no system package and must be built from Chromium's
|
|
`pdfium` git mirror. Its build is Chromium-scale: the source is ~2 GB, the
|
|
build wants tens of GB of disk and produces a large static library, and a
|
|
full build takes hours even on capable hardware. The M0 development
|
|
environment here (29 GB free disk, 7.8 GB RAM) is below PDFium's practical
|
|
build floor.
|
|
- **Skia** likewise has no system package and builds from Google's repo; it
|
|
is smaller than PDFium but still a from-source build with its own toolchain
|
|
(`gn` + `ninja`, depot_tools).
|
|
|
|
The spike is specifically testing the divergence between **two specific
|
|
renderers** we will use in production (§2.4: Skia for the predictive tier and
|
|
overlays, PDFium for the authoritative raster). It cannot be substituted with
|
|
Poppler or another renderer — that would test a different question.
|
|
|
|
## What this does NOT mean
|
|
|
|
- **It is not a go/no-go block on M0 for the other spikes.** Spikes A, B, C, E
|
|
are complete and give go signals: surgical splice validated (A),
|
|
reconstruction works (B), font growth works (C), sandbox works (E). The M0
|
|
exit criteria in §14 are met for the four spikes that could be built here.
|
|
- **It is not an architectural risk we are ignoring.** The §2.5 predictive
|
|
tier is the *optimisation* that keeps keystroke latency bounded; the
|
|
authoritative tier (re-emit + render through PDFium) is the guarantee and
|
|
does not depend on the Skia renderer's existence. If Spike D later shows
|
|
the Skia renderer diverges too much from PDFium, the fallback is the
|
|
authoritative tier alone (slower keystrokes on dense pages, still correct).
|
|
ADR-0001 records this as the design's escape valve.
|
|
|
|
## What this DOES mean / next steps
|
|
|
|
- **Spike D must run on a machine with the bandwidth to build PDFium and
|
|
Skia** — a CI runner, a developer workstation, or a build server. It is the
|
|
one M0 spike that needs a heavier environment than a laptop sandbox.
|
|
- **Before Spike D can run, the Skia display-list renderer must exist** (M2
|
|
work). Spike D tests *that renderer* against PDFium; without it, there is
|
|
nothing to compare. So D is naturally a late-M0 / early-M2 activity, not a
|
|
pure M0 spike — it depends on M2's L3 renderer.
|
|
- **The pixel-diff harness scaffolding is already in place**
|
|
(`ci/pixel-diff/run_pixel_diff.py`) with the CLI/JSON contract and `--noop`
|
|
mode. When the Skia renderer and PDFium are available, the harness fills in
|
|
the real `render_page` and `compare_png` stubs. That work is M2, not blocked
|
|
by this deferral.
|
|
|
|
## Reproducing (when the environment allows)
|
|
|
|
```bash
|
|
# Build PDFium ( Chromium's pdfium repo — hours, ~tens of GB):
|
|
# git clone https://pdfium.googlesource.com/pdfium.git
|
|
# cd pdfium && ./build/install-build-deps.sh && gn gen out/Default && ninja -C out/Default pdfium
|
|
# Build Skia:
|
|
# git clone https://skia.googlesource.com/skia.git && cd skia && python tools/git-sync-deps
|
|
# gn gen out/Default && ninja -C out/Default
|
|
# Then wire them into spike/D_renderer/ and run the pixel-diff harness.
|
|
```
|
|
|
|
This is left as the next step for an environment with the build bandwidth. |