nigig-org/REVIEWS/PLAN_PATH_1TO1_PORT.md

# Plan: 1:1 Port of dart-pdf `path.dart` → `nigig-pdf` (Phase 7.5 — Path Object Parity)

**Date:** 2026-09-06
**Reference:** `dart-pdf/packages/pdf_graphics/lib/src/path.dart:1` (343 LOC), `dart-pdf/packages/pdf_graphics/test/path_test.dart:1` (73 LOC)
**Nigig baseline:** `crates/apps/pdf/pdf-graphics/src/recording.rs:11` (`RenderCommand` path ops), `crates/apps/pdf/pdf-graphics/src/lib.rs:1`
**Master plan:** `NIGIG_PDF_FEATURE_PARITY_PLAN.md:746` (`path_test | DONE` — overstated, see §1)

---

## 1. Objective

Bring `nigig-pdf` path object model to 1:1 parity with dart-pdf's `path.dart` without changing interpreter correctness. `RenderCommand` stays as the paint-level wire; `PdfPath` becomes the packed, allocation-conscious path payload that dense CAD streams need and that `PdfPathCursor` traverses without allocating.

Non-goal: path booleans, stroking, simplification (no dart equivalent).

## 2. Gap Audit (why `DONE` is partial)

| Aspect | dart-pdf `path.dart` | nigig `recording.rs` | Gap |
|---|---|---|---|
| **Path type** | `sealed PdfPathSegment` + `PdfPath` dual storage: `List<PdfPathSegment>` *or* packed `Uint8List verbs` + `Float32List coordinates` (wire f32 preserved) + `segmentCount` + `Expando` materialized cache `path.dart:38` | `RenderCommand::MoveTo/LineTo/CurveTo/ClosePath/Rectangle` — path implicit as command sequence | No `PdfPath` struct, no packed wire, no materialized cache |
| **Builder** | `PdfPathBuilder(verbCapacity=16, coordinateCapacity=48)` pools buffers, `_ensure` grows `>>1`, `takePath()` copies exact-size `Uint8List`/`Float64List` and reuses scratch (tens of k one-segment CAD paths) `path.dart:196` | `RecordingDevice::move_to` pushes `RenderCommand` directly `recording.rs:554` | No pooling, no exact-size copy, no reuse |
| **Cursor** | `PdfPathCursor` non-allocating `moveNext()` over packed or object storage `path.dart:106` | `for cmd in &commands` over `Vec<RenderCommand>` | No cursor, allocates per segment if `segments` needed |
| **Fill rule** | `enum PdfFillRule { nonzero, evenOdd }` `path.dart:302` | Two commands `FillWinding`/`FillEvenOdd` `recording.rs:21` — no enum | Missing enum (trivial) |
| **Stroke** | `class PdfStroke { width cap join miterLimit dashArray dashPhase }` page-space `path.dart:305` | Five commands `SetStrokeWidth/Cap/Join/MiterLimit/Dash` `recording.rs:27` | Not bundled |

Correctness is already 1:1 (ops round-trip). Performance + wire exactness is ~60%.

## 3. Scope

### 3.1 New file `crates/apps/pdf/pdf-graphics/src/path.rs` (~350 LOC)

```rust
pub enum PdfPathSegment { MoveTo{x:f64,y:f64}, LineTo{x,y}, CubicTo{x1,y1,x2,y2,x3,y3}, Close }
pub struct PdfPath { // dual storage, like dart
  segments: Option<Vec<PdfPathSegment>>,
  verbs: Option<Vec<u8>>,
  coords: Option<Vec<f32>>, // f32 on wire, f64 in builder — mirrors dart Float32List vs Float64List
  len: usize,
  materialized: OnceCell<Vec<PdfPathSegment>>,
}
impl PdfPath {
  pub fn from_segments(Vec<PdfPathSegment>) -> Self;
  pub fn packed_float32(Vec<u8>, Vec<f32>, usize) -> Self; // wire exactness
  pub fn segments(&self) -> &[PdfPathSegment]; // lazy materialize + cache
  pub fn cursor(&self) -> PdfPathCursor;
  pub fn segment_count(&self) -> usize;
  pub fn is_empty(&self) -> bool;
}
pub enum PdfPathVerb { MoveTo, LineTo, CubicTo, Close }
pub struct PdfPathCursor { verb: PdfPathVerb, x1,y1,x2,y2,x3,y3, move_next() -> bool }
pub struct PdfPathBuilder { verbs: Vec<u8>, coords: Vec<f64>, verb_count, coord_count }
impl PdfPathBuilder {
  pub fn new(verb_capacity: usize, coord_capacity: usize) -> Self; // defaults 16/48
  pub fn move_to(&mut self, x:f64, y:f64);
  pub fn line_to(&mut self, x:f64, y:f64);
  pub fn cubic_to(&mut self, x1:f64,y1:f64,x2:f64,y2:f64,x3:f64,y3:f64);
  pub fn close(&mut self);
  pub fn add_segment(&mut self, PdfPathSegment);
  pub fn take_path(&mut self) -> PdfPath; // exact-size copy + reuse scratch
  pub fn clear(&mut self);
}
pub enum PdfFillRule { NonZero, EvenOdd }
pub struct PdfStroke { pub width:f64, pub cap:u32, pub join:u32, pub miter_limit:f64, pub dash_array:Vec<f64>, pub dash_phase:f64 }
```

Constants: `_moveTag=0, _lineTag=1, _cubicTag=2, _closeTag=3` `path.dart:184`, builder defaults `16/48` `path.dart:198`.

### 3.2 Modified files

* `crates/apps/pdf/pdf-graphics/src/recording.rs:11` — add `RenderCommand::Path(Rc<PdfPath>, PdfFillRule, Option<PdfStroke>)` alternative *or* keep `MoveTo` etc. for back-compat and add `PdfPath` as optional payload; update `format_command` + `wire.rs` codec to preserve f32 bit-exact (dart guarantee).
* `crates/apps/pdf/pdf-graphics/src/device.rs:6` `MakepadPdfDevice` — when a path is open, delegate `move_to` etc. to `PdfPathBuilder`, on `fill`/`stroke` consume via `take_path()`.
* `crates/apps/pdf/pdf-graphics/src/lib.rs:1` — `pub mod path; pub use path::{PdfPath, PdfPathBuilder, PdfPathCursor, PdfFillRule, PdfStroke, PdfPathVerb};`
* `NIGIG_PDF_FEATURE_PARITY_PLAN.md:746` — flip `path_test | DONE` → `path_test | Phase 7.5 | packed + cursor + builder pool + stroke/fill_rule, wire f32 exact` until landed, then back to `DONE`.

## 4. Test Port (dart → Rust)

| # | dart `pdf_graphics/test/path_test.dart` | Rust `crates/apps/pdf/pdf-graphics/src/path.rs` or `tests/path.rs` | Notes |
|---|---|---|---|
| T1 | `packed path cursor and compatibility segments agree` — `PdfPathBuilder(1,2) moveTo→lineTo→cubicTo→close`, `cursor.moveNext()` verbs/coords, `segments` lazy + `identical` cache `path_test.dart:5` | `packed_path_cursor_and_compatibility_segments_agree` | Verbatim port, checks `segment_count==4`, cursor `(verb,x1,y1…)`, `segments[0].is::<PdfMoveTo>()`, `ptr_eq(segments, segments)` via `Rc::ptr_eq` |
| T2 | `takePath copies immutable storage and reuses the builder` — `takePath` empties builder, second `takePath` independent `path_test.dart:47` | `take_path_copies_immutable_storage_and_reuses_builder` | Verbatim, checks `(segment_count, x1, y1)` for both paths |
| T3 | `ordinary const paths retain their supplied segment list` — `const PdfPath(segments)` returns `identical` list `path_test.dart:64` | `ordinary_const_paths_retain_supplied_segment_list` | `PdfPath::from_segments(Rc::new(vec![]))` → `ptr_eq` |
| T4 | *(new, perf)* dense CAD does not reallocate per path | `dense_cad_does_not_reallocate_per_path` | 10k `moveTo→lineTo→close` via one builder, assert `verbs.capacity()` amortized, `take_path` exact-size (`verbs.len()==verb_count`) |
| T5 | *(new, wire)* wire round-trip preserves f32 bit-exact | `wire_round_trip_preserves_float32_bit_exact` | `PdfPath` via `wire::encode`/`decode` → `coords` bitwise equal (dart wire guarantee) |
| Tool | `pdf_graphics/tool/dump_paths.dart`, `dump_bar_paths.dart` | `cargo run --bin dump_paths` (optional) | Perf dump for dense files, not required for green |

All 3 dart tests must pass as Rust equivalents before `746` flips to `DONE`.

## 5. Exit Criteria

* All 5 tests green: `cargo test -p nigig-pdf-graphics --lib path` + `cargo test -p nigig-pdf-graphics --test path` (if separate) + golden.
* `cargo test -p nigig-pdf-graphics` full suite still green (no interpreter regression).
* `NIGIG_PDF_FEATURE_PARITY_PLAN.md:746` updated to `DONE` with note `— packed + cursor + builder pool + stroke/fill_rule, wire f32 exact`.
* ADR `REVIEWS/adr/00xx-pdf-path-object-parity.md` records why `RenderCommand::Rectangle` stays as sugar (PDF `re` is rect) and why builder coords are `f64` but wire is `f32` (mirrors dart `Float64List` vs `Float32List`).
* No change to `pdf-makepad` rendering path except via `PdfPath` payload; existing goldens unchanged (wire is additive).

## 6. Risks & Mitigations

* **Wire breaking change** — mitigation: keep `MoveTo/LineTo` variants, add `Path` as new variant; old goldens unchanged; deprecate after one release.
* **Allocation win not measurable** — mitigation: T4 asserts amortized growth; bench with `cargo bench -p nigig-pdf-graphics path_dense`.
* **Const `identical` semantics** — Rust `const` not same as Dart `const`; use `Rc` + `ptr_eq` to emulate.

## 7. Estimate

* ~1 session, no fork needed, pure `pdf-graphics` crate.
* LOC: ~350 new + ~50 modified.
* Dependencies: none new.