pdfcraft/docs/form-performance.md

# AcroForm JavaScript performance

Status: implemented; proposed as an independent performance PR. Last reviewed and updated:
2026-10-19. Measurements below are historical synthetic evidence collected before this split,
not fresh measurements on upstream main. No private document is needed for the benchmark.

## Architecture

- `crates/ui-egui/src/forms_ui.rs` queues `Edit::SetFieldValue` for a text commit or checkbox
  toggle. `crates/automation/src/forms.rs::form_fill` uses the same edit API.
- `crates/engine/src/lib.rs::Session::apply` runs edits on a copy, preserving rollback and undo.
  `run_edit` calls `pdfcraft_forms::set_value_with` with an engine `JsRunner`.
- `crates/forms/src/lib.rs` validates and writes the edited value, then runs one calculation
  pass. `/CO` precedes calculated fields omitted from `/CO`. Each script sees prior writes.
  There is no dependency graph or dependency-based filtering: dynamic references and script
  side effects are evaluated on every pass.
- `crates/engine/src/js.rs::JsRunner::run` snapshots the fields, invokes `pdfcraft_js::run_shared`,
  then converts changed JavaScript field states into form updates.
- `crates/js/src/lib.rs::run_shared` starts a scoped worker per script. `run_here` builds a fresh Boa
  context, installs the API, evaluates document scripts and evaluates the action. No script or
  bytecode cache is present in this AcroForm path. XFA uses a separate session implementation.
- `crates/forms/src/scripting.rs::apply_changes` applies script side effects before the next
  calculation. It rereads the field snapshot when side effects occur. Calculation results
  equal to the existing value already skip value writes and appearance generation.
- Checkboxes write the field `/V` and widget `/AS`; they enter the same calculation pass as
  text edits. JavaScript exposes the export value or `Off`, and `isBoxChecked`.
- `Session::refresh_scoped` writes an incremental working revision, rereads fields and rebuilds
  the render pool. `crates/ui-egui/src/editing.rs::apply_edit` compares old/new fields and
  invalidates affected pages (including dependent fields on other pages). It does not blindly
  invalidate every page for an ordinary AcroForm fill. Rendering uses page/tile requests;
  widget appearance streams are separate from cached page rasters.

## Findings and changes

The dominant measured cost was the bridge, not executing calculation logic:

1. `JsRunner` expanded a sparse `Outcome::changed` into a complete second snapshot. `changes`
   then searched the first snapshot linearly for **each** field, even when JavaScript had not
   changed any field directly. That repeated quadratic comparison ran after every calculation.
   It now compares the sparse outcome only, with an indexed original snapshot when needed.
   Empty outcomes return immediately; unchanged writes still produce no form updates. The
   console/button path uses the same conversion.
2. Once that was removed, field-state construction dominated. Reading every widget's display
   flags on every script traversed the same immutable pre-edit COS snapshot. This workload
   exceeds COS's 1,024-object editing-cache cap, repeatedly reparsing widget dictionaries.
   The runner now memoizes only those scalar display readings by widget reference. Each edit
   creates a new runner; current values, read-only/required flags and options still come from
   the current field snapshot. No global cache or object-cache limit changes were needed.

All calculation actions still execute in the same order. No dependency filtering, script
removal, context reuse, bytecode caching or recursive scheduling changes were introduced.
Equal calculated values already skipped appearance regeneration; this behavior remains.
The Release investigation also found a full field-state copy inside the JavaScript host on
**every** script invocation. `pdfcraft_js::run_shared` now accepts an immutable shared snapshot;
`Arc::make_mut` detaches it on the first field write. The engine retains the initial snapshot
for comparing effects. Read-only calculations no longer copy every field again. Each script
still gets a fresh context and thread; exceptions, globals and uncommitted writes remain
isolated. Scripts that write fields retain the previous copy isolation. The existing borrowed
`run` API remains available. No new dependencies were added.

## Measurements

Historically measured under Rust 1.99.1 on Linux x86_64 with the default optimized development
profile, two-job builds. Serial benchmark runs had no concurrent compilation. These are
**synthetic engine measurements, not measurements of the original Pathfinder PDF or GUI input
latency**. Five edits: ranks 1, checkbox on, ranks 2, checkbox off, ranks 0. Every edit runs all
190 custom calculations among 3,129 fields on a six-page document. Widgets are colocated
on the first page; the fixture is an engine calculation stress test, not a layout replica.

| Synchronous edit | Before (ms) | After (ms) |
|---|---:|---:|
| ranks 1 | 4,425.274 | 424.465 |
| checkbox on | 4,378.642 | 458.716 |
| ranks 2 | 4,291.131 | 521.721 |
| checkbox off | 4,391.942 | 492.851 |
| ranks 0 | 4,322.570 | 453.392 |
| Median | **4,378.642** | **458.716** |

Median speedup: **9.55×**, approximately **89.5% less synchronous editing time**. The synthetic
scripts are deliberately small; this does not predict the exact result for other documents.
Raw logs and the baseline test executable are retained locally in `target/form-performance/`.

Historical serial runs collected with optional instrumentation (mean per edit; inclusive
nested spans). That instrumentation is not included in this PR:

| Phase | Before (ms) | After (ms) |
|---|---:|---:|
| JavaScript, including thread/context setup | 225.934 | 201.584 |
| Changed-field comparison | 2,814.805 | 0.024 |
| Entire script dispatch, all 190 scripts | 4,320.643 | 352.733 |
| Calculation pass, including changed appearances | 4,399.084 | 390.958 |
| Direct field write | 0.201 | 0.196 |
| Appearance generation, including Format | 61.225 | 22.981 |
| Form event, including direct write and calculations | 4,411.767 | 402.981 |
| Engine refresh/serialization | 23.499 | 21.826 |
| Whole engine edit | 4,442.144 | 431.539 |

An intermediate run after sparse comparison alone measured 1,193.419 ms/edit in field-state
construction. After display memoization it measured 101.821 ms/edit. The intermediate run's
whole engine edit averaged 1,592.101 ms. Appearance time also benefits from the changed cache
working set; there was no change to which calculated appearances are generated.

Rendering and compositor time are not included in these edit numbers. The original sheet and
GUI acceptance run remain required to quantify them.

## Release comparison and remaining cost

Historical comparison used the repository's Release profile (thin LTO, one code-generation
unit) and an optional standalone profiler, which is not included in this PR.
A fresh in-memory fixture was exported with create-new semantics to
`target/form-performance/synthetic-large.pdf` (SHA-256
`300431eeae117458d96e52877e12a9e63ea8dcbb8ad4500da717ba00ebb2f1e1`). It remained unchanged.
The example alternated `ranks` between 1 and 2 for six samples per process, always executing
all 190 scripts. Page rendering was timed separately.

Initial matched comparison, before the additional shared-snapshot change:

| Build | Samples | Median engine edit (ms) |
|---|---:|---:|
| Development | 6 | 460.697 |
| Release | 6 | 408.358 |

Release alone reduced the median by about 11%. A detailed Release run measured 106.947 ms/edit
constructing field states, 174.696 ms in JavaScript setup/execution, and 19.808 ms refreshing
engine view data. Calculation-order setup was only 0.319 ms. That supported investigating the
host's extra copy, rather than changing calculation scheduling or disabling calculations.

The pre-change Release profiler was retained, then compared with the shared-snapshot Release
profiler in alternating runs (old, new, old, new). No compilation ran during measurement.

| Release version | Samples | Median edit (ms) | Range (ms) |
|---|---:|---:|---:|
| Before shared snapshots | 12 | 381.380 | 353.468–447.833 |
| With shared snapshots | 12 | 267.063 | 258.545–313.777 |

The additional optimization reduced median engine time by **30.0%** (1.43× speedup).
This is a separate comparison from the earlier five-edit benchmark; do not combine their
speedup factors. The page-render/setup cost in the initial matched comparison was about
6–9 ms for this deliberately overlapping synthetic layout, not for the original sheet.

After shared snapshots, a historical Release run with optional instrumentation averaged:

| Phase | Mean per edit (ms) |
|---|---:|
| Field-state construction | 75.754 |
| JavaScript setup/execution | 83.198 |
| Complete script dispatch | 200.480 |
| Calculation pass | 237.780 |
| Calculated-value writes, including appearances | 25.089 |
| Appearances | 23.712 |
| All complete field enumerations (three per edit) | 27.387 |
| Calculation-order setup | 0.305 |
| Engine refresh | 19.128 |
| Whole engine edit | 272.807 |

These inclusive timings show that scheduling is now negligible on the fixture. The main
remaining costs are constructing/disposing field snapshots and creating/executing isolated
JavaScript contexts. Further snapshot caching or context reuse would need additional semantic
work and real-document evidence; no dependency-based skipping or global/context reuse was
introduced. The current shared-snapshot change was retained because its paired measurement
showed a substantial improvement and isolation regressions passed.

**Remaining limit:** these numbers do not quantify real-document or compositor latency.
A representative document and delayed field are still needed for a reproducible engine/render/UI
comparison. Prior manual acceptance on the integrated release reported responsive field editing;
that is not a timing measurement or independent validation of this split.

## Reproduce

Use the same compiler, build profile and machine for before/after runs. The default development
profile optimizes workspace crates at level 1 and dependencies at level 2. Build with two jobs
and a separate target directory, then run the benchmark without concurrent compilation:

```sh
CARGO_TARGET_DIR=target/acroform-benchmark cargo test -p pdfcraft-engine -j 2 --lib acroform_interaction_benchmark --no-run
CARGO_TARGET_DIR=target/acroform-benchmark cargo test -p pdfcraft-engine -j 2 --lib acroform_interaction_benchmark -- --ignored --nocapture
```

The benchmark creates a six-page, 3,129-field/190-calculation workload from contributor-original
PDF objects in memory and times five synchronous edits with `Instant`. It also checks the final
calculated chain and an independent field. Widgets overlap on page one; this is an engine stress
test, not a realistic page layout. There is no machine-dependent timing threshold in CI.

To export a synthetic fixture for a standalone comparison, set `PDFCRAFT_BENCH_EXPORT` to a new
filename when running the ignored benchmark. Its parent must exist; export refuses to overwrite
any existing file. The ordinary benchmark writes no PDF.

## Validation

Regression coverage includes shared-snapshot write/error/global isolation, duplicate field names,
scripted display changes with a warm cache and a fresh edit, ordered checkbox/rank calculations,
dynamic field lookup, property/value side effects, undo/save/reopen, and unchanged appearances.
The existing JavaScript and engine suites cover the unchanged public scripting behavior.

Before the split, the ignored benchmark passed both before and after optimization. Earlier
scoped native/WASM checks, Clippy, layering, asset and parity checks, UI form/JavaScript tests,
and automation `javascript_through_tools` checks also passed on the mixed review history.
Those historical checks do not certify these independent branches or hosted CI.

## Independent branch validation

Validated on upstream `a12fe8f4116984ebbc870eb514346ea922233316` using a fresh, isolated
Cargo target directory, offline locked dependencies and two build jobs:

- All five focused regressions passed separately: duplicate names, warm/new-edit display
  caches, ordered checkbox/rank dependents, dynamic lookup/side effects and shared-snapshot
  write/error/global isolation.
- `cargo test -p pdfcraft-js -p pdfcraft-engine -p pdfcraft-forms -j 2`: engine 285 unit
  and 9 integration tests, JavaScript 47 tests, and forms 80 tests passed. Two unit timing
  probes and two private-file acceptance tests were ignored in the regular suite.
- The ignored 3,129-field/190-calculation benchmark was then run explicitly and passed;
  its final calculated chain and independent field remained correct. This is a diagnostic
  timing run, not a new before/after comparison on this upstream base.
- Scoped `cargo clippy --all-targets -- -D warnings` and WASM checks of those three
  crates passed, as did formatting, whitespace, layering, asset and parity checks.
- `javascript_through_tools` passed. A CLI built in the isolated target directory then
  reproduced bonuses 1 → 4 → 5 → 2 → 0; save/reopen and `page_render` passed, and the
  synthetic page image was inspected.

These are local checks, not hosted CI. No GUI executable was rebuilt and no private PDF
was used for this independent validation.

## Rebase validation

Revalidated on upstream `932bf9c6bfdd63e2a21bb831696a3447b9def9cf` (2026-10-18).
The performance implementation and all five focused regressions are unchanged from the
previously reviewed fix. Upstream's newer tests and CSV documentation are retained.

- Engine: 286 unit and 9 integration tests passed; JavaScript: 48 passed; forms: 82 passed.
  Two unit timing probes and two private-file acceptance tests remain ignored in the
  regular suite.
- All five focused regressions and the explicit 3,129-field/190-calculation benchmark passed.
- Scoped all-targets Clippy with `-D warnings`, WASM, formatting, whitespace, layering,
  asset and parity checks passed.
- `javascript_through_tools` and a freshly built CLI's fill/save/reopen/render smoke check
  passed. The bonus chain remained 1 → 4 → 5 → 2 → 0, and the synthetic render was inspected.

Validation used a separate Cargo target directory. No GUI build or private PDF was needed;
these are local checks, not hosted CI or a new before/after performance comparison.

## PR #3318 refresh

Rebased onto freshly fetched upstream main
`e397efa85451be00f8d56df7649807fe31e019c7` on 2026-10-19. Both roadmap conflicts
retain upstream's menu, button-label and content-editing notes alongside the performance
notes. Every performance source, regression-test and parity hunk is exactly the original
performance patch applied to current upstream; upstream's additional tests are retained.
Main advanced after initial validation on `43550c44`; the non-overlapping redaction update
was incorporated and all checks below were repeated on the final base.

- All five focused regressions passed.
- Engine: 287 unit and 15 integration tests passed. JavaScript: 49 tests passed. Forms:
  84 tests passed. Doc tests passed. The regular suite still ignored two timing probes
  and two private-file tests; the synthetic benchmark was then run explicitly and passed.
- The 3,129-field/190-calculation benchmark preserved the expected calculated values. Its
  five diagnostic edits took 317.347–328.488 ms; this is not a new before/after comparison.
- Scoped all-targets Clippy with warnings denied, WASM, formatting, whitespace, layering,
  assets and parity passed.
- Automation JavaScript and CLI checks passed: bonuses 1 → 4 → 5 → 2 → 0, save/reopen,
  and page rendering. The synthetic render was inspected.

Builds used an isolated Cargo target outside the worktrees. No GUI executable was built,
no private PDF was used, and the compatibility branch was not changed. These are local
checks, not hosted CI or a new performance speedup claim.

## Revision history

- 2026-10-19: refresh PR #3318 onto upstream `e397efa8`, retain upstream roadmap additions
  and all performance changes, and repeat focused, scoped, benchmark and headless validation.

- 2026-10-18: rebase onto upstream `932bf9c6`; retain all performance source edits and regression
  tests; preserve upstream CSV documentation and repeat scoped native/WASM and headless checks.
- 2026-10-18: separate performance changes for review on current upstream main; add duplicate-name
  and scripted-display coverage; keep historical optional instrumentation results as evidence only.
- 2026-10-18: retain shared snapshots after a paired 30% synthetic Release improvement and
  verify snapshot isolation.
- 2026-10-17: remove quadratic outcome conversion and repeated display reads; record the
  synthetic before/after benchmark.