Refactoring the L1 Voronoi Library, Part 2

---

# 🧭 Refactoring the L1 Voronoi Library

## Part 2: From "Patterns Applied" to Patterns *Actually* Applied

@luk036 👨‍💻 · 2026 📅

---

### 📋 Agenda

**Part 1: The Gap** 🔍
- What the first refactor shipped ✅
- Where the seams still leaked 🕳️
- Issue #2: the plan 📝

**Part 2: The Work** 🛠️
- Phase 1: Strategy + Context 🧵
- Phase 2: Factory, Null Object, DRY 🏭
- Phase 3: DTO + Adapter 🎭

]
.pull-right[

**Part 3: Parity** 🐍
- Phase 4: the Python module split
- Phase 5: the oracle leaves the API
- The behavior-preservation net 🧪

**Part 4: Proof** ✅
- Golden 42/42, differential 7, pytest 49
- The output, unchanged (real SVG) 🖼️
- Commits & takeaways 📜

]

---

## 🔁 Recap: The First Refactor

---

### 🗺️ Where This Session Started

The first refactor split an **820-line monolith** into **9 modules** behind a facade.

<pre>
graph LR
    subgraph PIPE["Pipeline"]
        GEN["generator.js"]
        PRE["preprocess.js"]
        DC["divideConquer.js"]
        MW["mergeLine.js"]
        POLY["polygonizer.js"]
    end
    subgraph SUP["Support"]
        GEO["geometry.js"]
        BIS["bisector.js"]
        L1M["l1Metric.js"]
    end
    VOR["voronoi.js facade"]
    GEN --> PRE
    PRE --> DC
    DC --> MW
    MW --> POLY
    POLY --> VOR
    GEO -.-> BIS
    L1M -.-> BIS
    BIS -.-> DC
    BIS -.-> MW
    style VOR fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style GEN fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    style L1M fill:#fff9c4,stroke:#f57f17,stroke-width:3px
</pre>

]

---

### 🕳️ The Gap: Two Patterns Were Only Half-Applied

| Pattern | The claim | What the code actually did |
|:--------|:----------|:---------------------------|
| 🚪 Facade | ✅ done | thin re-export layer |
| 🪜 Pipeline | ✅ done | clean stage order |
| 🏭 Factory | ⚠️ half | three construction paths for one shape |
| 🧵 Strategy | ⚠️ half | `isNewBisectorUpward` imported directly |
| 🔌 Adapter | ⚠️ half | SVG `d` baked onto the core nodes |

]

> The deck said "applied". The code said "aspirational". 🎯

---

## 📝 Issue #2: The Plan

---

### 🔬 The Evidence (Straight From the Code)

**Leaky Strategy** 🧵
- `mergeLine.js` imported `isNewBisectorUpward` from `l1Metric.js`
- `geometry.distance` (L1) reached into **6** modules
- The "metric-agnostic core" wasn't one

**Fused Adapter** 🎭
- `polygonizeSite` bolted `.d` (SVG) onto the core `Site`
- the demo read `bisector.mergeLine` directly

]
.pull-right[

**Inconsistent Factory** 🏭
- `findL1Bisector` returned raw literals in two branches, a factory object in one

**Mixed sentinels** 🚦
- `checkForOrphans` returned `undefined`
- `determineFirstBorderCross` returned `null`

**Hand-mirrored Python** 🐍
- `py_ai/voronoi.py`: **869 lines**, one flat file

]

---

### 🗓️ Six Phases, One Safety Net

<pre>
graph LR
    P0["Phase 0\ncontract test"] --> P1["Phase 1\nStrategy + Context"]
    P1 --> P2["Phase 2\nFactory / Null / DRY"]
    P2 --> P3["Phase 3\nDTO + Adapter"]
    P3 --> P4["Phase 4\nPython parity"]
    P4 --> P5["Phase 5\noracle out of API"]
    style P0 fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    style P1 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style P2 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style P3 fill:#fff9c4,stroke:#f57f17,stroke-width:3px
    style P4 fill:#f8bbd0,stroke:#c2185b,stroke-width:3px
    style P5 fill:#d1c4e9,stroke:#6a1b9a,stroke-width:3px
</pre>

]

---

## 🧵 Phase 1: Strategy + Context

---

### 📏 The Metric We're Injecting

$$ d_1(P, Q) \;=\; |x_P - x_Q| \,+\, |y_P - y_Q| $$

The L1 **bisector** of two sites is the set of points equidistant under $d_1$:

$$ |x - x_1| + |y - y_1| \;=\; |x - x_2| + |y - y_2| $$

When ${\color{green}|\Delta x|} \ne {\color{red}|\Delta y|}$ this is a monotone stair-step chain. When they are **equal**, rotate by 45°:

> All of this is exactly what the new strategy object hides. 🧵

---

### 🕳️ The Leak

```js
// mergeLine.js — BEFORE
import {isNewBisectorUpward} from './l1Metric.js';   // L1 baked in
...
goUp === isNewBisectorUpward(hopTo, sideSite, otherSite, goUp)
```

Only `findBisector` was injected. The **upward test** and the **distance** stayed hard-wired to L1.

> A strategy seam that still imports the strategy is not a seam. 🧵

---

### 🧰 One Object Carries the Whole Metric

```js
// l1Metric.js — AFTER
export function createL1Metric(width, height){
    return {
        width: width,
        height: height,
        distance: distance,                        // L1
        bisector: (a, b) => findL1Bisector(a, b, width, height),
        isUpward: isNewBisectorUpward
    };
}
```

A different metric (L∞, L2) is now **one new file**, not a cross-cutting edit.

---

### 🪆 Context: Kill the 8-Argument Drilling

> One `metric` object replaces a function **and** two loose dimensions. 🎯

**Before** 😵

```js
walkMergeLine(
  currentR, currentL,
  currentBisector,
  currentCropPoint,
  goUp, crossedBorder,
  mergeArray, findBisector
)
```

]
.pull-right[

**After** 😌

```js
walkMergeLine(
  currentR, currentL,
  currentBisector,
  currentCropPoint,
  goUp, metric
)
```

]

---

### 🧵 The Seam, Visualized

<pre>
graph LR
    L1["l1Metric.js\ncreateL1Metric"]
    MW["mergeLine.js"]
    DC["divideConquer.js"]
    POLY["polygonizer.js"]
    BIS["bisector.js"]
    L1 -->|"metric.bisector"| MW
    L1 -->|"metric.isUpward"| MW
    L1 -->|"metric.distance"| BIS
    L1 -->|"metric.width/height"| POLY
    L1 -->|"metric.distance"| DC
    style L1 fill:#fff9c4,stroke:#f57f17,stroke-width:3px
    style MW fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    style BIS fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
</pre>

]

---

## 🏭 Phase 2: Factory, Null Object, DRY

---

### 🧹 Three Small Fixes, One Theme

**🏭 Factory consistency**

```js
// all three branches now:
let bisector = createBisector([P1, P2], up);
bisector.points = vertexes;
```

No more raw literals drifting away from the factory shape.

**🔗 DRY**

Deleted the duplicate `hopOver`; every "other site" now calls `findHopTo`.

]
.pull-right[

**🚦 Null Object**

```js
// checkForOrphans
return orphan ? orphan : null;
```

`undefined` unified to `null`, matching the rest of the pipeline.

> Small, boring, and exactly the kind of thing that rots if you skip it. 🧹

]

---

## 🎭 Phase 3: DTO + Adapter

---

### 🚧 A Real Presentation Boundary

<pre>
graph LR
    subgraph CORE["Computational core (mutable graph)"]
        SITE["Site"]
        BIS["Bisector"]
        POLY["polygonizeSite\npolygonPoints + neighbors"]
    end
    subgraph EDGE["Presentation boundary"]
        CELL["cell.js\ntoCell + toSVGPath"]
    end
    OUT["public cell\nsite, bisectors,\npolygonPoints, d, neighbors"]
    POLY --> CELL
    CELL --> OUT
    style CELL fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style OUT fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    style POLY fill:#fff9c4,stroke:#f57f17,stroke-width:3px
</pre>

]

---

### 🎭 The Mapper

```js
// cell.js — the entire presentation boundary
export function toSVGPath(points){
    return "M " + points.map(p => p.join(" ")).join(" L") + " Z";
}

export function toCell(site){
    return {
        site: site.site.slice(),
        polygonPoints: site.polygonPoints.map(p => p.slice()),
        d: toSVGPath(site.polygonPoints),
        neighbors: site.neighbors.map(n => n.slice()),
        bisectors: site.bisectors.map(toBisectorDTO)
    };
}
```

`polygonizer.js` no longer knows that SVG exists. 🎨

---

### 🐛 The Golden Test Earned Its Keep

The first cut looked harmless:

```js
graph.map(site => toCell(polygonizeSite(site, metric)))   // 42/42 FAIL
```

`chainBisectorPoints` **reverses shared `bisector.points` in place**, so snapshotting a cell *during* the map captured pre-reversal order for earlier sites.

The fix — polygonize **all** sites first, then map:

```js
const cells = graph.map(site => polygonizeSite(site, metric));
return cells.map(toCell);                                  // 42/42 pass
```

> Temporal coupling, made visible. The characterization test caught it instantly. ⚡

---

## 🐍 Phase 4: Python Parity

---

### 📦 From Monolith to Facade

<pre>
graph LR
    subgraph BEFORE["py_ai/voronoi.py"]
        MONO["869 lines\neverything"]
    end
    subgraph AFTER["py_ai/ package"]
        FAC["voronoi.py facade\n20 lines"]
        M1["geometry / bisector"]
        M2["l1_metric / merge_line"]
        M3["divide_conquer / polygonizer"]
        M4["cell / preprocess / generator"]
    end
    MONO --> FAC
    FAC -.-> M1
    FAC -.-> M2
    FAC -.-> M3
    FAC -.-> M4
    style MONO fill:#f8bbd0,stroke:#c2185b,stroke-width:3px
    style FAC fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
</pre>

]

---

### 🐍 Same Map, Same Patterns

- Modules **mirror `src/`**: `geometry`, `bisector`, `l1_metric`, `merge_line`, `divide_conquer`, `polygonizer`, `cell`, `preprocess`, `generator`
- Adopted **`create_l1_metric`** and the **DTO + SVG adapter**
- Flat absolute imports (the port is imported as a top-level module)
- Public names preserved: `generate_l1_voronoi`, `clean_data`, `distance`, …

**Behavior preserved exactly**, including Python's own quirks:

```python
bisector_intersection(...) -> False   # not None
_orphan_sort_key(...)                 # simplified
walk_merge_line(...)                  # still recursive
```

---

## 🧪 Phase 5: The Oracle Leaves the API

---

### 🚪 A Nondeterministic Export, Evicted

> If it is a test oracle, it belongs in tests. 🧪

**Before** 😬
- `generateVoronoiPoints` shipped in the public API
- Colors came from `Math.random()` → nondeterministic
- It was only ever a brute-force cross-check

]
.pull-right[

**After** ✅
- Moved to `tests/naiveOracle.js` (JS) and `py_ai/naive_oracle.py`
- Facade shrinks to `generateL1Voronoi` + `cleanData`
- README, demo and test script updated

]

---

## ✅ Proof: The Safety Net

---

### 🧪 Three Independent Nets

<pre>
graph TD
    C["42-case corpus\nseeded LCG"]
    C --> G["Golden master\nnpm test"]
    C --> D["JS vs Python diff\nnpm run test:diff"]
    PY["py_ai pytest"] --> D
    G --> R{"all green?"}
    D --> R
    P["pyflakes"] --> R
    R -->|yes| OK["behavior preserved"]
    style C fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    style OK fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style R fill:#fff9c4,stroke:#f57f17,stroke-width:3px
</pre>

]

---

### 🟢 Verification Results

| Check | Result |
|:------|:-------|
| `npm test` | **9/9** — golden 42/42 + 6 smoke + oracle |
| `npm run test:diff` | **7 diverging (baseline 7), healed 0** ✅ |
| `py_ai` pytest | **49/49** |
| `pyflakes` | **clean** |
| `npx gulp` | library + demo build ✅ |
| golden re-record | **none needed** 🎉 |

]

> Byte-identical behavior across a 25-file refactor. That is the whole point. 🎯

---

### 🖼️ The Output, Unchanged (Real SVG)

</p>

> Six L1 cells with staircase boundaries, emitted by the refactored library. 🏙️

---

### 🔍 Scaling Up: Sixteen Sites

</p>

> Sixteen cells — the paths are the library's own `d` output, rounded only for readability. 🏙️

---

### 📜 Commit History

| Commit | Message |
|:-------|:--------|
| `9315396` | Document the refactored module layout |
| `0a2f953` | Split the Python port into modules mirroring src/ |
| `a12492f` | Complete the metric strategy and DTO seams in the JS pipeline |
| `57e8364` | Bump GitHub Actions to Node 24 runtimes |

]

> Three atomic commits, each independently revertable, working tree clean. 🌿

---

### 🧠 Key Takeaways

**Architecture** 🧩
- A pattern is "applied" only when the seam is real
- Inject the *whole* strategy, not a convenience slice
- Bundle drifting parameters into a context object
- Put the presentation adapter at the boundary

**Bugs** 🐛
- Refactoring surfaced a real ordering hazard
- Shared mutable state hides temporal coupling

]
.pull-right[

**Discipline** 🧪
- Characterization tests make refactors boring (good!)
- The golden test caught the ordering bug instantly
- Cross-language parity = one conformance corpus
- Byte-identical output is the strongest evidence

**Result** ✅
- npm 9/9, differential clean, pytest 49/49
- Same public API, same diagrams, honest internals

]

---

# 🙋 Q&A

**Refactoring the L1 Voronoi Library — Part 2**

### Questions? Discussion? 💬

---

# 👏 Thank You

## Happy Voronoi Tiling! 🗺️ 🚀

Slides built with Remark.js 🎉 | KaTeX 📐 | Mermaid 🧩 | Nord Theme 🌙