# Phase 8 — CGAL Package Design

> **Status: planned.** This document describes the target architecture for Phase 8.
> No code has been written yet. The design is informed by the CGAL package submission
> guidelines at https://www.cgal.org/developers.html

---

## Goal

Integrate conformallab++ into the CGAL library as a proper CGAL package:
`Discrete_conformal_map`. The package must satisfy all CGAL submission requirements:
traits-class design, Doxygen documentation, CGAL-format test suite, and coverage of
the CGAL coding conventions.

---

## 8a — Traits class & concepts

The current code is tightly coupled to `CGAL::Surface_mesh<Point3>`. Phase 8a introduces
a traits class that separates the mesh type from the algorithm:

```cpp
// TODO(Phase 8a): implement this header
// include/CGAL/Conformal_map_traits.h

template<
    typename MeshType,      // any CGAL halfedge mesh
    typename KernelType,    // CGAL kernel
    typename ScalarType = double
>
struct Conformal_map_traits {
    using Mesh   = MeshType;
    using Kernel = KernelType;
    using FT     = ScalarType;
    // ... vertex/edge/face descriptor types
    // ... property map access
};
```

Concept checks will ensure any user-provided mesh satisfies the halfedge mesh concept.

---

## 8b — Public header hierarchy

A clean public API separate from the internal implementation:

```
include/CGAL/
  Discrete_conformal_map.h        ← single user-facing include
  Conformal_map_traits.h
  Conformal_newton_solver.h
  Conformal_layout.h
  Conformal_cut_graph.h
  conformal_map_package.h         ← PackageDescription
```

All existing `include/*.hpp` headers remain as internal implementation details,
not part of the public CGAL API.

---

## 8c — CGAL-style documentation

```
doc/Conformal_map/
  PackageDescription.txt
  User_manual.md
  Reference_manual.md
  fig/                            ← pipeline diagrams, mathematical figures
```

All public functions and concepts require Doxygen comments following the CGAL style.

---

## 8d — CGAL test format

```
test/Conformal_map/
  CMakeLists.txt                  ← CGAL-format, uses find_package(CGAL)
  test_euclidean_functional.cpp
  test_newton_solver.cpp
  ...
```

The existing GTest suite remains. CGAL-format tests are added alongside as a separate
target, following the CGAL test infrastructure conventions.

---

## 8e — Declarative YAML pipeline

A lightweight YAML format for reproducible experiments. The CLI accepts
`--pipeline experiment.yml`; the validator checks `require`/`provide` tokens
before execution.

**Full concept & design specification:** [doc/concepts/declarative-pipeline.md](../concepts/declarative-pipeline.md)
— token vocabulary, validation algorithm, 5 complete examples, implementation plan.

Abbreviated example:

```yaml
pipeline:
  name: flat_torus_period
  geometry: euclidean

  input:
    source: data/torus.off

  steps:
    - id: setup
      unit: setup_euclidean_maps
      provide: [maps_initialised]

    - id: gauss_bonnet
      unit: enforce_gauss_bonnet
      require: [maps_initialised]
      provide: [gauss_bonnet_satisfied]

    - id: solve
      unit: newton_euclidean
      require: [gauss_bonnet_satisfied]
      params:
        tol: 1.0e-10
        max_iter: 200
      provide: [x_converged]

    - id: cut
      unit: compute_cut_graph
      require: [mesh_closed]
      provide: [cut_graph]

    - id: layout
      unit: euclidean_layout
      require: [x_converged, cut_graph]
      params:
        normalise: true
      provide: [layout_uv, holonomy]

    - id: period
      unit: compute_period_matrix
      require: [holonomy]
      provide: [tau]

  output:
    layout: out/torus_layout.off
    json:   out/torus_result.json
    tau:    out/torus_tau.txt
```

The contract table in [contracts.md](contracts.md) defines the valid `require`/`provide`
token vocabulary.

---

## TODO

- [ ] Design `Conformal_map_traits.h` interface (8a)
- [ ] Define concept requirements for `MeshType` (8a)
- [ ] Create `include/CGAL/` header skeleton (8b)
- [ ] Write `PackageDescription.txt` (8c)
- [ ] Port GTest tests to CGAL format (8d)
- [ ] Implement YAML validator (8e)
- [ ] CLI: `--pipeline` flag (8e)